TellmeStpToGlb/README.md

# STP to GLB Converter Service

一个强大的STP到GLB转换服务，提供CLI和Web API两种使用方式，特别优化了在Blender中的显示效果。

## 功能特性

- **双模式支持**: CLI命令行工具 + Web API服务
- **异步处理**: 支持并发转换请求，实时进度追踪
- **格式转换**: STP → STL → GLB 完整转换流程
- **智能缩放**: 自动将过大模型缩放到适合3D软件的尺寸
- **自动居中**: 将模型质心移动到原点，便于查看
- **RESTful API**: 标准HTTP接口，支持跨语言调用
- **任务管理**: 完整的任务生命周期管理和状态追踪
- **样式兼容**: 正确处理STP文件中的样式信息，不影响几何转换
- **Blender优化**: 生成的GLB文件可直接在Blender中正常显示

## 系统要求

- Python 3.7+
- Windows/Linux/macOS

## 安装步骤

### 使用requirements.txt（推荐）

```bash
# 克隆或下载项目
git clone <项目地址>
cd TellmeStpToGlb

# 安装依赖
pip install -r requirements.txt
```

### 手动安装依赖

```bash
# 安装所有依赖
pip install pythonocc-core trimesh fastapi uvicorn pydantic
```

### 方法三：使用conda（可选）

```bash
# 创建虚拟环境
conda create -n stp2glb python=3.9
conda activate stp2glb

# 安装pythonocc-core
conda install -c conda-forge pythonocc-core

# 安装trimesh
pip install trimesh
```

## 使用方法

### CLI模式（命令行）

```bash
python main.py input.stp output.glb
```

#### CLI示例

```bash
# 转换单个文件
python main.py model.stp model.glb

# 转换测试文件
python main.py test.stp result.glb
```

### API模式（Web服务）

#### 启动服务

```bash
# 开发模式
python app.py

# 或使用uvicorn
uvicorn app:app --host 0.0.0.0 --port 8000 --reload

# 生产模式
uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
```

#### API接口

**健康检查**
```bash
GET http://localhost:8000/health
```

**提交转换任务**
```bash
POST http://localhost:8000/api/v1/convert
Content-Type: application/json

{
  "input_path": "/path/to/input.stp",
  "output_path": "/path/to/output.glb",
  "options": {
    "auto_scale": true,
    "auto_center": true
  }
}
```

**查询任务状态**
```bash
GET http://localhost:8000/api/v1/status/{task_id}
```

**获取任务列表**
```bash
GET http://localhost:8000/api/v1/tasks
```

#### API文档

服务启动后可访问：
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`

## 在Blender中使用

1. 打开Blender
2. 删除默认立方体（可选）
3. 文件 → 导入 → glTF 2.0 (.glb/.gltf)
4. 选择转换生成的GLB文件
5. 模型应该在视口中心正常显示

## 技术细节

### 转换流程
1. **STP读取**: 使用pythonocc-core读取STP文件
2. **STL生成**: 转换为高质量STL网格（线性偏差0.01）
3. **智能处理**: 自动缩放和居中处理
4. **GLB导出**: 使用trimesh生成最终GLB文件
5. **清理**: 自动删除临时STL文件

### 服务化特性
- **异步处理**: 使用asyncio实现并发转换任务
- **进度追踪**: 实时更新转换进度(0-100%)
- **任务管理**: 内存存储任务状态，支持查询和管理
- **RESTful API**: 标准HTTP接口，支持跨语言调用
- **错误处理**: 完整的异常捕获和错误信息反馈

### 智能优化
- **尺寸检测**: 自动检测模型最大尺寸
- **智能缩放**: 超过1000单位的模型自动缩放到50单位以内
- **质心居中**: 模型自动移动到坐标原点

## 故障排除

### 常见问题

**1. 导入错误**
```
ImportError: cannot import name 'xxx' from 'OCC.Core'
```
- 解决方案: 确保安装了正确版本的pythonocc-core
- 使用conda安装: `conda install -c conda-forge pythonocc-core`

**2. 样式警告**
```
OVER_RIDING_STYLED_ITEM warnings
```
- 这是正常现象，不影响几何转换
- 警告信息可以忽略

**3. Blender中看不见模型**
- 本工具已自动处理此问题
- 如仍有问题，在Blender中按数字键盘 `.` 键聚焦到对象

**4. 模型太大或太小**
- 工具已内置智能缩放功能
- 大模型会自动缩放到合适尺寸

### 依赖问题

如果遇到依赖安装问题：

```bash
# 升级pip
pip install --upgrade pip

# 清理缓存重新安装
pip cache purge
pip install -r requirements.txt --no-cache-dir
```

## 支持的格式

- **输入**: STP/STEP文件
- **输出**: GLB文件（glTF 2.0二进制格式）

## 性能说明

- 转换速度取决于模型复杂度
- 大模型（几万面片）通常需要几秒到几十秒
- 内存使用量与模型大小成正比

## 许可证

本项目使用MIT许可证，详见LICENSE文件。

## 贡献

欢迎提交Issue和Pull Request来改进这个工具。

## 更新日志

### v2.0.0
- 🚀 服务化改造，支持Web API
- ⚡ 异步处理和并发转换
- 📊 实时进度追踪
- 🔧 任务管理系统
- 📖 自动生成API文档
- 🔄 保持CLI模式向后兼容

### v1.0.0
- 初始版本发布
- 支持STP到GLB转换
- 智能缩放和居中功能
- Blender显示优化