内容
# 蛇形3D
**一款开源的NURBS曲面建模器，适用于Linux，支持通过MCP原生AI集成。**
蛇形3D（`serp3d`）是一款自由曲面建模器，其设计理念源自Rhinoceros 3D —— 基于OpenCASCADE内核的BREP/NURBS几何体，而不是网格。它专为布景师、建筑师和工业设计师设计，他们希望在Linux上拥有真正的Rhino风格工作流：命令行提示输入、图层、对象捕捉到构造平面、STEP/OBJ交换，以及深色、聚焦的界面。
以津巴布韦绍纳雕塑中的蛇形石和NURBS几何体核心的S曲线命名。
## 为什么
- **没有真正的开源NURBS建模器适用于Linux。** FreeCAD是参数化CAD；Blender是基于网格的。蛇形3D填补了自由曲面建模的空白。
- **首款具有原生AI集成的CAD工具。** 捆绑的MCP服务器允许Claude（或任何MCP客户端）查看您的视口、创建几何体、运行任何命令和管理场景。
## 安装
需要在Linux上安装Python 3.10+，并支持OpenGL 3.3。
```bash
git clone <此仓库> && cd 蛇形3D
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/serp3d # 启动
```
OpenCASCADE内核以pip轮包形式提供（`cadquery-ocp`）—— 无需conda或系统软件包。
**Windows（实验性）：** 相同的pip安装在Windows上有效 —— 每个依赖项都有预编译的轮包，全套测试在Windows 10（Python 3.12）上通过。图形用户界面需要具有OpenGL 3.3驱动的GPU；无GPU的虚拟机和远程桌面会话仅暴露Windows内置的OpenGL 1.1，并会收到清晰的错误消息。无头使用（`serp3d-batch`，MCP服务器，文件转换）在任何地方都有效。macOS未经测试 —— 欢迎报告。
## 命令行
所有操作都遵循Rhino风格：输入命令，回答其提示。提示接受输入的坐标（`10,5,0`，相对`@5,0,0`）或构造平面的视口点击。`Tab`完成命令名称，`上`/`下`回忆历史，空行上的`Enter`重复上一个命令，`Escape`取消。
| | 命令 |
|---|---|
| **曲线** | `line` `polyline` `curve`（插值NURBS） `circle` `arc` `ellipse` `rectangle` `helix` `textobject` `blendcrv` `project` `pull` `intersect` |
| **曲面** | `extrude` `revolve` `loft` `sweep1` `sweep2` `planarsrf` `patch`/`networksrf` `offsetsrf` `unrollsrf` |
| **实体** | `box` `sphere` `cylinder` `cone` `torus` `filletedge` `chamferedge`（两者直接选择边；圆角链并取`start,end`可变半径） `shell` `cap` `contour` `booleansplit` `pushpull` |
| **变形** | `twist` `taper` `bend` `flow`（曲线到曲线） `extend` `matchcrv` |
| **布尔运算** | `booleanunion` `booleandifference` `booleanintersection` |
| **变换** | `move` `copy` `rotate` `scale` `scalenu` `mirror` `array` |
| **编辑** | `join` `explode` `trim` `split` `offset` `fillet` `rebuild` `pointson`/`pointsoff`（控制点，曲线*和*曲面） `delete` `hide` `show` `rename` `undo` `redo` |
| **选择** | `selall` `selnone` `selcrv` `selsrf` `selsolid` `sellayer` `selname` `sellast` `invert` `isolate` `unisolate` |
| **组织** | `group`/`ungroup` `lock`/`unlockall` `block` `insert` `blocklist` `count` |
| **相机** | `camera`（镜头mm，电影传感器，放置，2.39/1.85帧导向） `units` `cplane` |
| **阵列** | `array`（网格） `arraypolar` `arraypath`（沿曲线） |
| **分析** | `distance` `length` `area` `volume` `curvature` `zebra` `curvaturegraph`（梳状） `draftanalysis` |
| **视图** | `top` `front` `right` `perspective` `4view`/`1view` `zoomextents` `wireframe` `shaded` `ghosted` `rendered` `technical` `grid` `snap` |
| **渲染** | `material`（Matte/Plastic/Metal/Glass/自定义PBR —— 流入GLB/USD导出） `rendered` |
| **图层** | `layer`（新建/当前/显示/隐藏/重命名/权重）—— 或使用图层面板 |
| **网格** | 沉重的OBJ/3DM道具保持原生网格（即时显示）；`meshtobrep` / `breptomesh`转换 |
| **文件** | `new` `open` `save` `import` `export`（`.serp`是一个带有缩略图+元数据的zip容器） |
| **实时** | `recordhistory` —— loft/extrude/revolve输出在输入曲线编辑时重建 |
大多数命令都有Rhino兼容的别名（`l`，`pl`，`c`，`m`，`co`，`mi`，...）。命令选项以**可点击的芯片**形式出现在提示下方（`Cap=Yes`，`BothSides=No`，`Style=Normal`），可以在任何时候以Rhino风格输入（`cap=n`）。数字提示显示结果的**金色幽灵预览**，在输入时。`help`（或F1）打开可搜索的命令参考。箭头键微调选择沿CPlane移动（Shift ×10，Ctrl ×0.1）。
### 导航和快捷键
- **中键鼠标** 轨道 · **Shift+中键鼠标** 平移 · **滚动** 缩放
- **F1–F4** 上/前/右/透视 · **Ctrl+E** 缩放范围 · **F7** 网格
- **Ctrl+Z / Ctrl+Y** 撤销/重做 · **Ctrl+A** 全选 · **Delete** 删除选择
- **Ctrl+S / Ctrl+O / Ctrl+N** 保存/打开/新建
- 点击选择（Shift-click添加，Ctrl-click删除），点击空白处取消选择
- **框选**：从左到右拖动选择 *窗口*（完全封闭，金色框），从右到左拖动选择 *交叉*（任何触及的，白色框）；Shift添加，Ctrl删除
- **控制点**：`pointson`（F10）显示曲线的CV —— 拖动CV实时编辑曲线；`pointsoff`（F11）隐藏它们
- **对象捕捉** —— 端点，中点，中心，象限，交点，垂直，和最近点，每个都有不同的光标标记。在**对象捕捉栏**或设置中切换类型。`gridsnap`将拾取的点捕捉到网格
- 使用文件启动：`serp3d 模型.serp`（或任何可导入的格式）
## 制图和文档
蛇形3D具有完整的双空间制图工作流 —— 在3D中建模，在2D中记录，无需离开应用程序：
- **布局**（`layout`）：纸张空间表格（A4-A0，Letter，Tabloid或自定义），在视口底部有选项卡：`[模型] [图纸 1] …`
- **细节视图**（`detail`）：模型中实时窗口到图纸上 —— 选择两个角，一个视图方向（上/前/右/…/透视）和一个比例（`1:10`，`1:50`，...）。双击细节进入，拖动（导航按钮拖动）和缩放（轮改变比例）；点击外部退出。`detailscale`，`detailmode`，`detaillock`，`detailborder`，`detaildelete`管理活动细节。
- **隐藏线渲染**：每个细节可以是 *技术性*（隐藏线移除），*隐藏*（虚线隐藏线），*线框*或*阴影* —— 由OCCT的HLR引擎驱动，在工作进程中隔离，以便退化几何体永远不会崩溃应用程序。相同的引擎驱动模型空间的`技术`显示模式。
- **`make2d`**：将当前视图（或选择）投影到`Make2D可见` / `Make2D隐藏`图层上的真实，可编辑的2D曲线。
- **注释**：多行`text`，`leader`，`dim` / `dimradius` / `dimdiameter` / `dimangle`，`hatch`（拾取角落或**模式=区域**以在内部点击），`scalebar`，`titleblock`，`sheetindex`和每张图纸的`revision`表格。图纸上的所有内容都是可选的 —— 拖动以移动，缩放以调整细节框架，删除则删除，`annotedit`编辑 —— 并且在细节内拾取的尺寸是**关联的**：它们在细节平移或缩放时重新投影。`dimstyle`管理命名文本/箭头样式。
- **`exportpdf`**（Ctrl+P）：真正的矢量PDF —— 线条在任何缩放级别下保持清晰；阴影细节作为渲染图像嵌入。布局与`.serp`文件一起保存/加载。
### 橡皮球
选择任何对象，都会出现一个**橡皮球**：拖动箭头沿轴移动，拖动垫在平面上移动，拖动圆圈旋转（Shift捕捉到15°），拖动方形旋钮沿轴缩放（Shift = 统一缩放）。Alt-drag移动副本。Esc取消拖动。`gumball`切换它。
### 单位
`units`设置文档单位（毫米/厘米/米/英寸/**英尺和英寸**），并可选地重新缩放模型。然后每个提示接受单位输入 —— `3'6"`，`2' 4 1/2"`，`30cm`，`1.5in` —— 并且坐标支持极坐标输入（`10<45`）和Shift-正交约束，同时拾取。
### 脚本和自动化
- **Python控制台**（工具菜单，Ctrl+`）：实时场景，几何体构建器和完整API的交互式会话。
- **`serpentine3d.scripting.Document`**：相同的功能在无头模式下 —— `doc.add(geo.make_box(...))`，`doc.run("filletedge", [...])`，`doc.export("part.step")`。
- **`serp3d-batch script.py`**：从命令行/CI运行脚本，预定义`doc`，`geo`和`args`。无需显示。
- **自动保存和崩溃恢复**：每5分钟（可配置）；在崩溃后启动，蛇形3D提供恢复自动保存的功能。
- 将`~/.config/serpentine3d/template.serp`放到启动时每个新文档的模板（单位，图层，标题块）。
### 设置
**工具 → 设置**（Ctrl+,）—— 五个扁平页面，变更立即生效：
- **鼠标** —— 用中间或右键鼠标轨道，滚动方向，轨道/缩放速度
- **键盘** —— 绑定任意键到任意命令；从文本文件（每行`F5 zoomextents`）或JSON导入
- **别名** —— 自定义命令别名；**导入Rhino别名导出**（选项 → 别名 → 导出）并自动映射已知命令
- **对象捕捉**和**显示**（网格大小）
设置存储在`~/.config/serpentine3d/settings.json`中。
## 文件格式
| 格式 | 导入 | 导出 | 备注 |
|---|---|---|---|
| `.serp` | ✓ | ✓ | 原生：JSON场景 + 嵌入式二进制BREP |
| `.step` / `.stp` | ✓ | ✓ | 通过OCCT的精确BREP交换 |
| `.3dm` | ✓ | ✓ | Rhino：精确NURBS曲线双向；breps/曲面导入为未修剪的NURBS面，导出为网格；图层保留 |
| `.obj` | ✓ | ✓ | 网格与`.mtl`颜色 |
| `.dxf` | ✓ | ✓ | 曲线/网格与图层；布局图纸按纸张比例导出 |
| `.svg` | ✓ | ✓ | 路径导入为曲线（贝塞尔曲线精确）；布局导出为矢量SVG |
| `.glb` | | ✓ | 带有材质的二进制glTF（Unreal/Blender/web） |
| `.usda` | | ✓ | 用于虚拟生产管道的USD |
## 助手（AI建模）
蛇形3D内置了一个AI助手：从视图菜单中打开它（或输入`ai`，或Ctrl+Shift+A），描述您想要的，它在您的实时场景中构建真正的BREP几何体 —
> *一个螺旋楼梯，3米高，14级，900毫米半径*
> *将盒子的每个边缘圆角2毫米*
> *船体的体积是多少？*
它适用于完整的命令集（您输入的命令），可以测量和检查场景，并且可以**查看视口** —— 它会截取屏幕截图，检查自己的工作，并在回答之前修复错误。它的所有操作都会实时流式传输到面板中，并且所有操作都可以撤销。
携带您自己的Anthropic API密钥（设置 → 助手，或`ANTHROPIC_API_KEY`环境变量 —— 在[console.anthropic.com](https://console.anthropic.com)获取）。使用情况记入您的Anthropic账户；助手绝不会与其他地方的电话联系，密钥在调用API之前绝不会离开您的机器。
## MCP服务器（AI集成）
更喜欢从外部代理（Claude Code，Claude Desktop）驱动蛇形3D吗？建模曲面通过MCP工具公开。启动应用程序，然后使用MCP客户端注册服务器：
```bash
claude mcp add serpentine3d -- /path/to/.venv/bin/serp3d-mcp
```
工具：`serp_scene_info`，`serp_screenshot`（返回视口图像），`serp_create_curve`，`serp_create_surface`，`serp_boolean`，`serp_transform`，`serp_select`，`serp_command`（运行任何命令及其交互式输入），`serp_layers`，`serp_import`，`serp_export`，`serp_measure`，`serp_undo`，`serp_viewport`。
`serp_screenshot`和`serp_command`的组合意味着AI助手可以与您一起建模：它看到您看到的内容，并且可以操作每个工具，命令行提供。桥梁是一个仅限本地主机的JSON-RPC套接字（`~/.serpentine3d/rpc.port`）；设置`SERP3D_NO_RPC=1`以禁用它。
## 架构
```
serpentine3d/
├── core/ # 内核层：几何体构建器，网格细分，场景图，图层，选择，撤销历史
├── commands/ # 基于生成器的交互式命令（Rhino风格提示协议，GUI + MCP共享）
├── ui/ # Qt：GL视口，命令行，面板，深色主题
├── fileio/ # .serp / STEP / OBJ
├── mcp_server/ # stdio MCP服务器 -> RPC桥
├── api.py # 运行会话的编程API
└── rpc.py # 本地主机JSON-RPC桥
```
几何体是OpenCASCADE 7.9（通过`OCP`pybind11绑定）的精确BREP；视口根据需要细分并带有修剪感知等曲面显示。命令是Python生成器，产生类型化输入请求 —— 相同的命令代码提供类型化输入，视口点击和MCP调用。
## 插件
将`.py`文件放入`~/.serpentine3d/plugins/`，定义`serpentine3d_plugin(ctx)`，或提供具有`serpentine3d.plugins`入口点的包 —— 插件注册一流命令（带有提示，对象捕捉，撤销和MCP支持）和菜单项。参见`docs/scripting.md`。
## 开发
```bash
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest # 单元测试（几何体，场景，命令，文件I/O）
```
## 许可证
MIT
