root 7bd0624829 fix: 修复层级保留功能的导入错误并重新实现

- 移除有问题的OCC.Core导入，避免模块依赖问题
- 重新实现基于trimesh的层级保留功能，使用连通组件分离
- 添加智能回退机制，如果分离失败自动使用标准转换
- 扩展CLI和API接口支持层级保留参数
- 更新文档说明新的实现方式

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-08-02 16:55:22 +08:00

3.9 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个Python服务，用于将STP格式的3D模型文件转换为GLB格式。项目提供CLI和Web API两种使用方式，实现了STP → STL → GLB的转换流程。

核心架构

模块化设计

main.py: CLI入口，保持向后兼容
app.py: FastAPI服务入口
core/: 核心转换引擎
- converter.py: 转换器类（封装原有逻辑）
- models.py: 数据模型定义
api/: HTTP接口层
- routes.py: API路由定义
- schemas.py: API数据模式
services/: 业务服务层
- task_manager.py: 异步任务管理
utils/: 工具函数库

依赖要求

pythonocc-core: 用于STP/STEP文件读取和STL写入
trimesh: 用于STL到GLB格式转换
fastapi: Web框架
uvicorn: ASGI服务器
pydantic: 数据验证

常用命令

CLI模式转换

# 标准转换（默认）
python main.py input.stp output.glb

# 层级保留转换（实验性功能）
python main.py input.stp output.glb --hierarchy

# 显示帮助信息
python main.py --help

启动Web服务

# 开发模式
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使用示例

# 健康检查
curl http://localhost:8000/health

# 提交标准转换任务
curl -X POST http://localhost:8000/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"input_path": "/path/to/input.stp", "output_path": "/path/to/output.glb"}'

# 提交层级保留转换任务
curl -X POST http://localhost:8000/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"input_path": "/path/to/input.stp", "output_path": "/path/to/output.glb", "options": {"preserve_hierarchy": true}}'

# 查询任务状态
curl http://localhost:8000/api/v1/status/{task_id}

测试转换

python main.py test.stp test.glb

关键技术细节

转换流程

STP → STL: 使用pythonocc-core读取STP文件，生成临时STL文件
STL → GLB: 使用trimesh库将STL转换为GLB格式
自动清理: 转换完成后自动删除临时STL文件

服务化特性

异步处理: 使用asyncio实现并发转换任务
进度追踪: 实时更新转换进度(0-100%)
任务管理: 内存存储任务状态，支持查询和管理
RESTful API: 标准HTTP接口，支持跨语言调用
层级保留: 支持保留STP装配体的层级结构（实验性功能）

转换配置

STL设置: 二进制模式，线性偏差0.01，角度偏差0.1
自动优化:
- 智能缩放：超过1000单位的模型自动缩放到50单位以内
- 自动居中：模型质心移动到原点，便于Blender查看

层级保留功能（实验性）

连通组件分离: 基于trimesh自动分离STL文件中的独立网格组件
独立网格: 为每个分离组件创建独立的网格对象
场景构建: 使用trimesh.Scene保持组件分离关系
智能回退: 如果未发现分离组件，自动回退到标准转换模式
组件命名: 自动为分离组件分配有序名称(Part_001, Part_002等)
API兼容: 避免复杂的OCC.Core依赖，使用稳定的trimesh API

错误处理

完整的文件验证和网格检查
异常捕获和错误信息反馈
临时文件自动清理机制

重要注意事项

STP文件读取时可能出现OVER_RIDING_STYLED_ITEM样式警告，不影响几何转换
需要安装trimesh库：pip install trimesh
临时STL文件会自动清理，无需手动删除
生成的GLB文件已优化，可直接在Blender中正常显示
支持大尺寸模型的自动缩放和居中处理

3.9 KiB Raw Blame History Unescape Escape