ColorYourModel 技术架构说明书

一、总体数据流

用户选择 STL
   │
   ▼  invoke("load_model")
[Rust] loader.rs 解析 → 顶点去重 → 面邻接图(petgraph) → KD-Tree(kiddo)
        → face_colors 全量填 #8a8a8a → segment_labels = vec![0; face_count]
   │
   ▼  MeshDataDto (serde camelCase)
[TS] useMesh.buildGeometry → toNonIndexed() → BufferGeometry → zustand
   │
   ├─► 自动分区：invoke("auto_segment_smart" | "auto_segment")
   │      [Rust] sdf.rs / dihedral.rs → SegmentResult
   │      → updateSegmentLabels 双写 segments + meshData.segments
   │
   ├─► 手动分区：invoke("manual_region_add_point") × N
   │      → invoke("finalize_manual_region")
   │      [Rust] manual.rs Dijkstra 加密 + 障碍 BFS + 形态学平滑
   │
   ├─► 上色：usePaintTool.paintFace 分派
   │      → invoke("fill_paint" | "brush_paint" | "spray_paint" | ...)
   │      [Rust] KD-Tree 命中 + mix_color → PaintResult{updatedFaces, updatedColors}
   │      → useMesh.updateFaceColors 增量写 GPU（不重建几何）
   │
   ├─► 撤销：invoke("restore_face_colors")
   │
   ▼  invoke("export_3mf_command")
[Rust] threemf.rs → quick-xml 生成 + zip 打包 → 3MF 文件
   │
   ▼
OrcaSlicer / BambuStudio 切片打印

二、模块清单

2.1 Rust 后端（src-tauri/src）

上表为 18 个实现文件。后端 .rs 文件实际共 24 个，另 6 个为纯声明文件，无实现逻辑：main.rs(6)、commands/mod.rs(4)、export/mod.rs(1)、mesh/mod.rs(8)、paint/mod.rs(4)、segment/mod.rs(4)。

README 勘误：README 中列出的 paint/eraser.rs 实际不存在（橡皮在 commands/paint.rs 内实现）；README 未列出 segment/sdf.rs、segment/manual.rs、mesh/kdtree.rs、paint/smart_snap.rs、paint/spray.rs。

2.2 React 前端（src）

Viewport.tsx 已达 2141 行，是明确的重构候选（相机控制、拾取、套索覆盖层、高亮覆盖层、HUD 探针混杂于单文件）。

三、前后端通信契约（18 个 Tauri 命令）

多数 DTO 采用 #[serde(rename_all = "camelCase")]（Segment — model.rs:14、MeshDataDto — model.rs:99），前端 key 为小驼峰。例外：BoundingBox（model.rs:7）未加该属性，因其字段名 min/max 为单词，恰好无对齐问题。二进制数组直接映射 Uint8Array / Uint32Array，无额外转码层。

下表入参列已省略 Tauri 自动注入的 state: State<AppState> 与 app: AppHandle，只列前端必须传递的参数（名称为 Rust 侧蛇形名，前端发送时用小驼峰）。

smart_brush_paint 的法线阈值不是入参。它是编译期常量 SMART_NORMAL_MIN_DOT = 0.5（smart_snap.rs:9），前端无法调节。按"可传阈值"实现会导致 Tauri 参数反序列化失败。

export_3mf_command 返回 Result<String, String>，成功时为 format!("Exported to {}", ...)。易与内层 export::threemf::export_3mf（threemf.rs:12，返回 Result<(), String>）混淆。当前前端忽略该返回值，问题被掩盖但契约本身如此。

lib.rs:22-41 的 invoke_handler! 注册 18 项，与 18 个 #[tauri::command] 宏一一对应，无未注册命令、无幽灵注册。

关键返回结构

PaintResult   { updated_faces: Vec<u32>, updated_colors: Vec<[u8; 4]> }
SegmentResult { segments, segment_labels, face_colors: Vec<u8> }

前端据 PaintResult 做增量 GPU 写入，不重建几何体。SegmentResult.face_colors 常被忽略，但它是"重新分区不丢失已有涂色"的关键字段（segment.rs:24-28 / types/mesh.ts:43）。

commands/segment.rs 另定义三个返回结构：PaintSegmentFaceResult(:76)、FinalizeSegmentResult(:135)、ManualPointResult(:176)。

四、核心数据结构

Rust（mesh/model.rs）

struct MeshModel {                          // model.rs:77
    vertices, faces, normals,
    face_colors,            // Vec<[u8;4]>，默认全 DEFAULT_FACE_COLOR
    segment_labels,         // Vec<u32>，长度必须 == faces.len()
    segments,               // HashMap<u32, Segment>，键 = segment label
    manual_region_history,  // Vec<ManualRegionSnapshot>，支撑 LIFO 撤销
    face_kdtree, vertex_kdtree, face_adjacency,
    bbox, unit,             // unit 恒为 "millimeter"，全库无读取点（死字段）
}

struct MeshDataDto {                        // model.rs:99，跨 IPC 的 DTO
    segments,               // Vec<Segment>  ← 注意与 MeshModel 不同
    ...
}

struct Segment { id, name, color, face_count }  // serde → camelCase

segments 在两层的类型不同，这是刻意设计而非笔误。 内存模型 MeshModel.segments 是 HashMap<u32, Segment>（按 label 键索引），跨 IPC 的 MeshDataDto.segments 是 Vec<Segment>（序列化为 JSON 数组）。转换点统一写作 mesh.segments.values().cloned().collect()（segment.rs:158 / 233 / 256 / 308）。把内存层当 Vec 使用会直接编译失败。

全局常量（定义位置分散，不集中于 model.rs）

吸附参数是前后端各自独立的字面量，无编译期约束——这是一处真实风险：

后端两处未提升为具名常量，无法通过 grep 保证与前端同步。

阈值角度的正确读法：实际取 60°，不是 54.74°。 arccos(1/√3) ≈ 54.7356° 是立方体角点处顶点法线与面法线的夹角，构成理论下界；代码取 60° 是为该下界留约 5° 余量（论证原文见 manual.rs:87-90）。低于 54.74° 会与相邻面法向混淆。

TypeScript（types/mesh.ts）

MeshData 镜像 MeshDataDto；PaintTool 枚举含 View / Fill / Brush / Spray / SmartBrush / Eyedropper / Eraser / Segment / Lasso；PaintSnapshot { faceColors: Uint8Array, segmentLabels: Uint32Array }；AMS_PALETTE 为标准料盘色板。

五、状态管理（zustand + persist）

完整 state：meshData, isLoaded, activeTool, brushRadius, brushStrength, brushFalloff, shadingMode, theme, currentColor, segments, selectedSegment, hoveredSegment, snapEnabled, segmentView, toast, undoStack, redoStack, language, statusMessage, isLoading, importProgress, importStage, lastPaintDebug, hoverProbe

持久化白名单（partialize，共 8 键） theme · language · shadingMode · brushRadius · brushStrength · brushFalloff · currentColor · snapEnabled

存储键 PREFS_KEY = "cym-prefs"，兼容旧键 LEGACY_THEME_KEY = "cym-theme"。

mergePrefs 校验规则

pickStorage 探测 localStorage 可用性，失败回退 memoryStorage。

关键模式：applyFaceColors 原地 mutate，不调 set() 更换 meshData 引用会触发 paintColorArray 从陈旧色重算并全量覆盖 GPU，还会重置相机。此模式已成为项目通用约定。

关键约定：updateSegmentLabels 必须双写 同时写顶层 segments 与 meshData.segments。仅写顶层会使 Fill 路由与分区悬停高亮双双静默失效。

六、关键算法

七、渲染与交互层（Viewport.tsx）

相机

• 正交投影，经 Canvas orthographic prop 声明（R3F 在 resize 时自动按 size 重算 frustum；drei <OrthographicCamera> 需自行管理 frustum 易漏）。
• [50,50,50] 只是 <Canvas camera={{position, zoom:1}}> 的初始 prop（Viewport.tsx:2102），CameraFit 并不使用它。
• CameraFit 按包围盒动态求解：方向固定 (0.4,0.4,1).normalize()，距离 viewDist = maxDim × 10，位置 center + dir × viewDist（Viewport.tsx:180-182）；zoom = min(fit × 0.88, 500)（:193）。相机不是固定在 iso 角落。
• ControlsBridge：minZoom=0.1、maxZoom=500、enableDamping=false（惯性积分会在右键平移期间继续施加旋转）。

鼠标映射（applyCameraButtons）

overModelRef 为模块级共享 ref，驱动上述上下文切换。约定：任何新工具必须在自身 pointermove 的命中/未命中两个分支都刷新它，否则读到冻结旧值。

拾取

• 射线法 + three-mesh-bvh，raycaster.firstHitOnly = true。
• BVH 构建必须 computeBoundsTree({ indirect: true }) —— 默认模式会物理重排 geometry.index，破坏 faceIndex 与后端面索引的对应关系。
• 构建移入 setTimeout(0) effect，未建树期自动回退暴力射线。
• 几何体经 toNonIndexed()，保证 faceIdx*3+v 的逐顶点写色寻址成立。

高亮覆盖层

SegmentOutline（lineSegments 描边）、SegmentHighlight（meshBasicMaterial, opacity 0.35）、LassoOverlay；OVERLAY_COLORS 提供 dark/light 双套（满足 WCAG 对比度）。

已知副作用：所有 overlay 均 depthTest = false，恒绘制于最前，不被模型遮挡；面数 >50k 时跳过 wireframe（20 万面同步构造线框会阻塞 1.5–4 秒）。

诊断

Tauri release 无 devtools，故诊断探针全部打到 UI：DebugHud 输出 face= / seg= / hover= / color= / gpu= / shade= / N filled / M highlighted ⚠️ MISMATCH，以及 [HOVER] [CLICK] [FILL-RX] 三级探针。

八、构建与验证

npx tsc --noEmit                    # 前端类型检查，须 exit 0
cd src-tauri && cargo test --lib    # 后端 13 项单测
npx tauri build --bundles nsis      # 打包（须先 unset NODE_OPTIONS）

产物：ColorYourModel_x64-setup.exe（~3.1 MB）、color-your-model.exe（~14 MB）

已知死代码：MeshModel.unit 字段（model.rs:94 声明，:128 赋值 "millimeter"，全库无读取点）。

早期版本此处记为"2 处 dead_code 警告，含 apply_falloff"，该断言已被证伪：apply_falloff 在代码库中不存在（0 处命中）；真实存在的是 falloff_strength（brush.rs:29），且被 commands/paint.rs:8,55 与 paint/smart_snap.rs:4,57 三处调用，属热路径函数。具体警告条数须以 cargo build 输出为准，本文不再断言计数。

打包环境注意

• 必须 unset NODE_OPTIONS（沙箱 safe-delete shim 会破坏 vite 清 dist）
• 必须 --bundles nsis 显式限定，bundle.targets="all" 会尝试需联网的 WiX
• choco 安装 NSIS 后 makensis 不入 PATH，需手动软链