# python-feature-recognition

**Repository Path**: david9988/python-feature-recognition

## Basic Information

- **Project Name**: python-feature-recognition
- **Description**: python-feature-recognition
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PythonOCC 特征识别系统

基于 pythonocc-core 的 STEP 文件特征识别系统，提供 Web 界面进行 3D 模型查看和特征分析。

## 功能特性

- 📁 STEP 文件上传 (.step, .stp)
- 🔍 几何特征识别 (平面、圆柱、圆锥等)
- ⚙️ 加工特征识别 (孔、圆角、倒角)
- 🎯 交互式 3D 查看器 (Three.js)
- 📊 特征树和详情面板

## 系统要求

- Python 3.12
- pythonocc-core 7.9.3
- [uv](https://github.com/astral-sh/uv) - Python 包管理器

## 安装

### 1. 安装 uv

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | more"
```

### 2. 创建 Conda 环境（仅用于 pythonocc-core）

```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
```

### 3. 安装项目依赖

```bash
cd ~/work/python-feature-recognition
uv sync
```

## 运行

### 启动服务

```bash
# 方式 1: 使用 uv 运行（推荐）
conda activate pyoccenv
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 方式 2: 使用启动脚本
./run.sh

# 方式 3: 直接激活虚拟环境后运行
conda activate pyoccenv
source .venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 访问应用

- 前端界面：http://localhost:8000/static/index.html
- API 文档：http://localhost:8000/docs
- 健康检查：http://localhost:8000/health

## API 端点

| 方法 | 端点 | 描述 |
|------|------|------|
| POST | /api/upload | 上传 STEP 文件 |
| GET | /api/features/{file_id} | 获取特征识别结果 |
| GET | /api/uploads | 列出已上传文件 |
| DELETE | /api/uploads/{file_id} | 删除上传的文件 |
| GET | /health | 健康检查 |

### 上传文件示例

```bash
curl -X POST -F "file=@part.step" http://localhost:8000/api/upload
```

### 获取特征示例

```bash
curl http://localhost:8000/api/features/<file_id>
```

## 特征识别范围

### 基础信息
- 文件名、文件大小
- 实体数量
- 体积 (mm³)
- 表面积 (mm²)
- 质心坐标
- 边界框

### 几何类型
- 平面 (Plane)
- 圆柱面 (Cylinder)
- 圆锥面 (Cone)
- 球面 (Sphere)
- 环面 (Torus)
- NURBS 曲面

### 加工特征
- 孔 (通孔、盲孔)
- 圆角 (恒定半径)
- 倒角

## 技术栈

- **后端**: FastAPI + pythonocc-core 7.9.3
- **前端**: Three.js + 原生 JavaScript
- **ASGI 服务器**: uvicorn
- **几何处理**: trimesh (用于 glTF 导出)
- **包管理**: [uv](https://github.com/astral-sh/uv) - 快速、可靠的 Python 包管理器

## 项目结构

```
python-feature-recognition/
├── app/
│   ├── main.py              # FastAPI 入口
│   ├── api/                 # API 端点
│   │   ├── upload.py        # 文件上传
│   │   └── features.py      # 特征查询
│   ├── core/                # 核心引擎
│   │   ├── step_parser.py   # STEP 解析
│   │   ├── gltf_exporter.py # glTF 转换
│   │   └── feature_engine.py# 特征识别引擎
│   ├── models/              # 数据模型
│   │   └── feature.py       # 特征数据类
│   └── api/                 # API 路由
├── static/                  # 前端静态文件
│   ├── index.html
│   ├── css/style.css
│   └── js/
│       ├── app.js
│       ├── viewer.js
│       └── feature-tree.js
├── uploads/                 # 临时上传目录
├── exports/                 # glTF 导出目录
├── tests/                   # 测试文件
├── pyproject.toml           # 项目配置 (uv)
├── uv.lock                  # 依赖锁定文件
└── run.sh                   # 启动脚本
```

## 运行测试

```bash
# 使用 uv 运行测试
conda activate pyoccenv
uv run pytest tests/ -v

# 或激活虚拟环境后运行
conda activate pyoccenv
source .venv/bin/activate
pytest tests/ -v
```

## 使用流程

1. 打开浏览器访问 http://localhost:8000/static/index.html
2. 点击"上传 STEP 文件"按钮
3. 选择 .step 或 .stp 文件
4. 等待系统处理完成
5. 在 3D 查看器中查看模型
6. 在特征树中查看识别结果
7. 点击特征查看详情

## 注意事项

- 最大文件大小：100MB
- 支持的格式：STEP AP214, AP203
- 首次加载可能需要更长时间进行网格划分

## 许可证

MIT License