# step-evaluator

**Repository Path**: david9988/step-evaluator

## Basic Information

- **Project Name**: step-evaluator
- **Description**: step-evaluator
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# STEP Evaluator

一个基于 Web 的 STEP (STP) 文件评估工具，提供 AI 驱动的 3D 模型质量评估。使用 Next.js、React、Three.js 和 Python 构建。

## 描述

STEP Evaluator 是一个全栈应用，允许用户上传 STEP 文件（.stp, .step）并获得全面的质量评估。系统使用 pythonocc-core 解析 STEP 文件，提取几何特征，并利用 Moonshot AI (Kimi) 在四个关键维度上提供专业评估：

- **几何质量** - 模型完整性、表面连续性、缺陷检测
- **设计规范** - 行业标准合规性、图层管理、命名约定
- **特征质量** - 特征创建质量、几何精度、表面质量
- **任务合规性** - 基于自定义任务规格的需求满足度

## 功能特性

- **文件上传**: 支持拖放或点击上传 STEP 文件
- **3D 可视化**: 基于 Three.js 的查看器，显示从 STEP 文件提取的网格数据
- **AI 评估**: Moonshot AI 驱动的质量评估与详细分析
- **特征检测**: 自动检测几何特征（圆柱面、圆锥面、球面、环面、平面等）
- **可配置评分**: 通过 JSON 配置自定义评估维度和权重
- **多语言支持**: 可配置输出语言（默认：中文）
- **回退评分**: 当 AI API 不可用时使用模拟评分系统

## 技术栈

### 前端
- **Next.js 16** - 带有 App Router 的 React 框架
- **React 19** - UI 库
- **TypeScript** - 类型安全
- **Tailwind CSS 4** - 样式
- **Three.js** - 3D 渲染和可视化

### 后端
- **Next.js API 路由** - 服务器端端点
- **Python 3** - STEP 文件解析
- **pythonocc-core** - OpenCASCADE 封装，用于 STEP 处理
- **Moonshot AI API** - AI 评估服务

### 开发工具
- **pnpm** - 包管理
- **PostCSS & Autoprefixer** - CSS 处理

## 快速开始

### 前置要求

- Node.js 18+ 和 pnpm
- Python 3.8+
- Miniconda（推荐，用于安装 pythonocc-core）
- pythonocc-core（可选，用于完整 STEP 解析功能）

### 安装

1. **克隆仓库**:
   ```bash
   git clone <repository-url>
   cd step-evaluator
   ```

2. **安装 Node.js 依赖**:
   ```bash
   pnpm install
   ```

3. **安装 Miniconda**（如果尚未安装）:
   ```bash
   # 下载 Miniconda 安装器
   wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O /tmp/miniconda.sh

   # 运行安装脚本
   bash /tmp/miniconda.sh

   # 安装完成后，重启终端或运行以下命令使 conda 生效
   source ~/miniconda3/bin/activate
   ```

4. **安装 pythonocc-core**（推荐，用于完整 STEP 解析）:
   ```bash
   # 创建 conda 环境
   conda create --name pyoccenv python=3.12 -y
   conda activate pyoccenv

   # 安装 pythonocc-core
   conda install -c conda-forge pythonocc-core=7.9.3 -y
   ```

   或者使用 pip 安装基础版本（功能有限）:
   ```bash
   pip install pythonocc-core
   ```

5. **配置环境**:
   - 将 `.env.local.example` 复制为 `.env.local`:
     ```bash
     cp .env.local.example .env.local
     ```
   - 编辑 `.env.local` 并添加你的 Moonshot AI API 密钥:
     ```
     NEXT_PUBLIC_MOONSHOT_API_KEY=your-api-key-here
     ```

### 运行应用

1. **开发模式**:
   ```bash
   # 如果使用 conda 环境
   conda activate pyoccenv
   pnpm dev
   ```
   应用将启动在 `http://localhost:3000`

2. **生产环境构建**:
   ```bash
   pnpm build
   pnpm start
   ```

3. **生成测试 STEP 文件**:
   ```bash
   pnpm test:step
   ```

## API 文档

### POST `/api/evaluate`

上传 STEP 文件进行解析和评估。

**请求**: `multipart/form-data`

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `file` | 文件 | 是 | STEP 文件（.stp 或 .step，最大 50MB） |
| `taskRequirements` | 字符串 | 否 | 自定义任务需求用于评估 |

**响应**: `application/json`

```typescript
{
  success: boolean;
  fileName: string;
  fileSize: number;
  parsing: {
    success: boolean;
    meshes: Array<{
      vertices: number[];
      type: string;
      faceIndex?: number;
    }>;
    modelInfo: {
      entityCount: number;
      facesCount?: number;
      edgesCount?: number;
      verticesCount?: number;
      boundingBox?: {
        min: { x: number; y: number; z: number };
        max: { x: number; y: number; z: number };
        dimensions?: { width: number; height: number; depth: number };
      };
      features?: Array<{
        id: number;
        type: string;
        surfaceType?: string;
      }>;
    };
  };
  evaluation?: {
    overallScore: number;
    breakdown: {
      geometricQuality: number;
      designStandard: number;
      featureQuality: number;
      taskCompliance: number;
    };
    analysis: {
      geometricQualityAnalysis: string;
      designStandardAnalysis: string;
      featureQualityAnalysis: string;
      taskComplianceAnalysis: string;
      features: string[];
      issues: string[];
      recommendations: string[];
    };
  };
}
```

### GET/POST `/api/config`

获取或更新评估配置。

**GET 响应**:
```typescript
{
  dimensions: {
    geometricQuality: { name: string; weight: number; description: string };
    designStandard: { name: string; weight: number; description: string };
    featureQuality: { name: string; weight: number; description: string };
    taskCompliance: { name: string; weight: number; description: string };
  };
  scoring: {
    minScore: number;
    maxScore: number;
    passScore: number;
  };
  output: {
    language: string;
    includeSuggestions: boolean;
    includeFeatures: boolean;
  };
}
```

## 项目结构

```
step-evaluator/
├── config/
│   └── evaluation-config.json    # 评估维度权重和设置
├── scripts/
│   └── parse-stp.py              # 使用 pythonocc-core 的 Python STEP 解析器
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── config/
│   │   │   │   └── route.ts      # 配置 API 端点
│   │   │   └── evaluate/
│   │   │       └── route.ts      # 评估 API 端点
│   │   ├── globals.css           # 全局样式
│   │   ├── layout.tsx            # 根布局组件
│   │   └── page.tsx              # 主页面组件
│   ├── components/
│   │   ├── EvaluationResult.tsx  # 结果展示组件
│   │   ├── FileUploader.tsx      # 文件上传组件
│   │   └── STPViewer.tsx         # 3D 查看器组件
│   └── lib/
│       └── evaluation.ts         # AI 评估服务
├── tests/
│   ├── assembly.stp              # 测试 STEP 文件
│   ├── cube.stp                  # 测试 STEP 文件
│   ├── cylinder.stp              # 测试 STEP 文件
│   └── generate-test-step.py     # 测试文件生成器
├── .env.local.example            # 环境模板
├── next.config.js                # Next.js 配置
├── package.json                  # Node.js 依赖
├── postcss.config.js             # PostCSS 配置
├── tailwind.config.js            # Tailwind CSS 配置
├── tsconfig.json                 # TypeScript 配置
└── README.md                     # 本文件
```

## 配置

### 评估配置 (`config/evaluation-config.json`)

评估系统使用四个可配置权重的维度：

| 维度 | 默认权重 | 描述 |
|------|---------|------|
| 几何质量 | 0.35 | 模型完整性、表面连续性、缺陷检测 |
| 设计规范 | 0.25 | 行业标准、图层管理、命名 |
| 特征质量 | 0.25 | 特征创建质量、几何精度 |
| 任务合规性 | 0.15 | 需求满足度 |

### 环境变量

| 变量 | 必填 | 描述 |
|------|------|------|
| `NEXT_PUBLIC_MOONSHOT_API_KEY` | 否 | Moonshot AI API 密钥（未设置时使用模拟评分） |
| `EVALUATION_CONFIG_PATH` | 否 | 评估配置文件的自定义路径 |

## 许可证

MIT