Compressor/3d

压缩机 3D 部件查看与配色

Python（FastAPI）服务端 + Ant Design Vue（Vue3 + Vite + TypeScript）客户端。 加载 models/*.glb，按部件单独选中与着色，配色状态持久化到 data/color_state.json。

目录结构

3d/
├─ backend/            # FastAPI 服务端（扁平结构，无 app/ 层）
│  ├─ main.py          # 应用入口：/api、/models、前端托管与 SPA 回退
│  ├─ config.py        # 路径配置
│  ├─ routers/         # files.py（模型）、state.py（配色状态）
│  ├─ services/        # model_service、state_service
│  ├─ run.py           # 启动脚本
│  └─ requirements.txt
├─ frontend/           # Ant Design Vue 客户端
│  └─ src/
│     ├─ api/          # 接口封装（axios）
│     ├─ stores/       # pinia：model / parts / viewer
│     ├─ three/        # 纯 three.js 逻辑（Viewer.ts 等）
│     ├─ composables/  # useThreeViewer（Vue 与 three 的桥接）
│     ├─ components/   # TopBar / ViewerCanvas / DataPanel / 卡片 / 查询弹窗
│     ├─ types/        # 类型定义
│     └─ styles/
├─ tools/              # CAD/GLB 处理脚本（split_glb / remove_nodes / scale_part）
├─ models/             # *.glb 模型
├─ data/               # color_state.json
└─ docs/               # 建模与GLB转换指南.md

依赖

python3 -m pip install -r 3d/backend/requirements.txt
cd 3d/frontend && npm install

开发模式（前后端分离，热更新）

# 终端 1：服务端
python3 3d/backend/run.py --reload         # http://127.0.0.1:5182
# 若 python3 被解析成系统解释器（zsh 命令缓存），改用：
bash 3d/backend/run.sh --reload

# 终端 2：客户端
cd 3d/frontend
npm run dev                                # http://127.0.0.1:5183

排查：which python3 若显示 /usr/bin/python3 之类的系统解释器，执行 hash -r（zsh）或重开终端； run.sh 会优先使用当前 conda/venv 环境（$CONDA_PREFIX/bin/python），不受 PATH 缓存影响。

Vite 已把 /api、/models 代理到 http://127.0.0.1:5182（见 vite.config.ts）。

生产模式（单端口）

cd 3d/frontend && npm run build            # 产物：3d/frontend/dist
python3 3d/backend/run.py --host 0.0.0.0 --port 5182

FastAPI 托管 frontend/dist，非 /api、/models 的路径回退 index.html。

接口

方法	路径	说明
GET	/api/models	可用模型名列表
GET	/api/state?model=x	读取某模型的配色状态
POST	/api/state?model=x	保存配色状态（body 为 {部件id: {color, status}}）
GET	/models/<file>	GLB / glTF 模型文件

CAD 工具

# 按名字删除节点（世界变换烘焙，支持嵌套）
python3 3d/tools/remove_nodes.py --input a.glb --output b.glb --name 三维立体
# 按查看器标签缩放零件
python3 3d/tools/scale_part.py --input a.glb --label 区域_143 --width 3 --inplace
# 按平面拆分模块
python3 3d/tools/split_glb.py --input a.glb --outdir 3d/models --prefix a --axis y --planes 16 32