Cbrush

Cbrush 是一个简单、独立、可运行的 Three.js Web 雕刻实现与技术原型。它用于验证浏览器内的网格拾取、笔刷变形、体素重建和低延迟交互路线；核心运行不依赖 Houdini、Blender、Cyl1nder 或其他 DCC。

Cbrush 不是 ZBrush 替代品，也不承诺完整的专业雕刻工作流。当前重点是把关键算法做成可读、可测、可继续演进的 Web 基线。

工程细节、性能记录和设计决策见 devlog/；本 README 是用户启动与体验入口。

当前功能

• Clay / Clay Buildup：左键拖拽，在命中表面连续雕刻。
• Shift 临时 Smooth：雕刻时按住 Shift 临时切换平滑，不改变工具栏中永久选中的笔刷。
• 面 + 线框：按 W 切换实体面与独立线框叠加显示。
• 按钮式 DynaMesh：按工具栏按钮对整个对象执行一次全局体素重建；当前实现采用三轴 crossedEdges 标记、外部 flood fill、带符号距离与 Surface Nets 等值面提取。
• 重置回初始球：重置必须恢复应用启动时的初始球，包括初始拓扑，并把 DynaMesh resolution 恢复为 32；不会把上一次 DynaMesh 结果当成新的重置基准。
• Houdini 风格 Alt 导航：Alt + 左键 旋转、Alt + 中键 平移、Alt + 右键 缩放；滚轮也可缩放。
• 浏览器内独立运行：TypeScript + Three.js + Vite，使用 three-mesh-bvh 加速表面射线拾取。

启动

环境要求：已安装 Node.js 与 npm。仓库已存在依赖时，可直接启动；若是全新检出，请先在 app 目录执行 npm.cmd install。

推荐：根目录启动脚本

在 Windows 资源管理器双击 start-dev-npm.cmd，或在项目根目录运行：

start-dev-npm.cmd

脚本会进入 app 并以 127.0.0.1 启动 Vite。终端会打印实际访问地址。

直接使用 npm

cd app
npm.cmd run dev

如需显式限制监听地址：

cd app
npm.cmd run dev -- --host 127.0.0.1

快速验证

1. 启动后打开终端输出的本地地址，确认画面出现灰色初始球与顶部工具栏。
2. 在球体上按住左键拖拽，确认 Clay 产生凸起。
3. 保持左键雕刻并按住 Shift，确认表面被临时平滑，工具栏永久笔刷选择不改变。
4. 按 W，确认实体面上显示线框；再次按 W 关闭。
5. 修改 DynaMesh 精度并点击 DynaMesh，确认按钮式全局重建完成且仍可继续雕刻。
6. 点击 重置，确认模型恢复启动初始球的形状与拓扑，DynaMesh 精度回到 32。
7. 分别尝试 Alt + 左/中/右键，确认旋转、平移、缩放不会触发雕刻。

基础静态检查与生产构建：

cd app
npm.cmd test
npm.cmd run build

仓库中的浏览器回归脚本位于 app/tests/；详细验证数字由各版本专题 devlog 记录。

技术架构与目录

Cbrush/
├─ start-dev-npm.cmd       # Windows 快速启动入口
├─ app/                    # 可运行的 Three.js/Vite 应用
│  ├─ src/main.ts          # 场景、网格/BVH、雕刻循环、DynaMesh 与 Reset 接线
│  ├─ src/viewport.ts      # WebGL 视口与尺寸管理
│  ├─ src/navigation.ts    # Houdini 风格 Alt 导航
│  ├─ src/ui.ts            # 笔刷、DynaMesh、Reset、W 线框工具栏
│  ├─ src/brush/            # Clay、Smooth、alpha 与笔刷契约
│  ├─ src/dynamesh/         # crossedEdges、符号场与 Surface Nets 重建
│  └─ tests/                # 浏览器端交互/雕刻回归脚本
├─ bench/                  # 拾取、简化、压缩等基准测试
├─ research/               # 论文、开源实现与算法调研材料
└─ devlog/                 # 工程设计、版本记录、计划与实测结果

当前主链路为：指针事件 → BVH 射线命中 → 笔刷修改顶点 → 更新法线/包围体 → BVH refit → Three.js 渲染。DynaMesh 会替换拓扑，因此需重建几何相关缓存与 BVH，而不能只做 refit。

DynaMesh 与 Sculptris Pro 的区别

项目	当前 Cbrush DynaMesh	Sculptris Pro 类动态拓扑
触发方式	用户点击按钮	随笔划持续发生
处理范围	整个对象全局重建	笔刷附近局部区域
密度策略	全局统一体素分辨率	根据笔刷/细节局部增删拓扑
当前目标	消除拉伸、重建封闭表面、恢复较均匀网格	在连续雕刻中动态维持局部细节密度

因此，当前 DynaMesh 不等于 Sculptris Pro。不能通过每个 stamp 重跑全局稠密体素网格来伪装实时局部动态拓扑；两者的更新范围、性能模型和交互语义不同。

这里的“三轴 crossedEdges”只是检测 X/Y/Z 体素网格边是否穿过三角形，不是 triplanar（三平面）投影。球面横向环带和中心波纹更可能来自笛卡尔体素格的方向性、Surface Nets 每 cell 单顶点平均及缺少后投影/切向平滑。实测与分析见 research/dynamesh-projection-artifacts.md。

已知边界

• DynaMesh 目前在主线程同步执行；分辨率增大时可能阻塞交互。
• 当前是全局、均匀、稠密体素网格，时间与内存成本会随三维分辨率快速增长。
• crossedEdges + flood fill 主要面向封闭、可定向网格；开放边界、自相交、薄片和退化三角形仍可能产生不稳定结果。
• 仅有基础 Clay 与 Smooth；尚无完整压力曲线、遮罩、对称、分层、撤销历史、文件导入导出或生产级资产管理。
• W 显示的是三角网格边，不是四边形拓扑、PolyGroup 边界或 ZBrush 风格线框。
• 重置是回到固定启动基线，不是撤销系统，也不会恢复一段编辑历史。
• 当前项目是桌面鼠标交互原型；触控笔、触摸、多视口与浏览器快捷键冲突尚未形成完整兼容矩阵。

下一步路线

1. Worker：先把全局 DynaMesh 移出 UI 主线程，建立可取消任务、进度与几何数据传输边界。
2. WASM：将体素化、距离计算、flood fill 和等值面提取迁移到更可控的高性能实现，并用实测决定 SIMD/线程策略。
3. 稀疏体素与局部 remesh：从固定分辨率 sparse bricks 过渡到局部 dirty region / patch 重建，避免整模重复计算。
4. 实时动态拓扑：在局部 remesh 稳定后，再评估接近 Sculptris Pro 的逐笔划密度控制、边操作与缝合策略。

进行中计划见 devlog/in-progress/dynamesh-realtime-plan.md。

延伸阅读

以下仅作为算法和实现入口，不代表 Cbrush 已完整实现其中全部方法：

• Sarah F. F. Gibson, Constrained Elastic Surface Nets: Generating Smooth Surfaces from Binary Segmented Data（MERL，1999）：https://www.merl.com/publications/TR99-24
• Tao Ju 等，Dual Contouring of Hermite Data（SIGGRAPH 2002）：https://doi.org/10.1145/566570.566586
• SculptGL（浏览器雕刻与体素重建实现参考）：https://github.com/stephomi/sculptgl
• OpenVDB MeshToVolume：https://www.openvdb.org/documentation/doxygen/MeshToVolume_8h.html
• OpenVDB VolumeToMesh：https://www.openvdb.org/documentation/doxygen/VolumeToMesh_8h.html
• Mario Botsch、Leif Kobbelt，A Remeshing Approach to Multiresolution Modeling（SGP 2004）：https://www.graphics.rwth-aachen.de/publication/03101/

文档入口

• 用户启动与功能概览：本 README.md
• v0.1.00009 雕刻基线与 Reset 语义：devlog/sculpt-baseline.md
• DynaMesh 算法评估：devlog/dynamesh-assessment.md
• 雕刻交互：devlog/sculpt-interaction.md