VoxelOptimizer 与优化 API
从 voxel-kit 2.17.0 起，设备可独立执行本地形状与颜色整理，不需要 Python 服务，也不依赖编译器 SO。开始使用请阅读 连续放置与一键优化，其中列出全部 19 类操作、参数、默认值和适用边界。
编辑会话 API
以下方法位于 VoxelEditorController：
| 方法 | 返回值 | 行为 |
|---|---|---|
| previewOptimization(options: VoxelOptimizationOptions) | Promise<VoxelOptimizationResult> | 从当前文档和选区快照创建后台任务；不改变模型。忙碌、未进入编辑、参数错误会拒绝。 |
| applyOptimization(result: VoxelOptimizationResult) | number | 仅接受同一控制器最近生成且源文档仍匹配的候选，返回实际修改数；一次撤销事务包含完整调色板。 |
| optimize(options: VoxelOptimizationOptions) | Promise<VoxelOptimizationResult> | 顺序调用计算与应用，适合宿主已确认参数的流程。 |
| cancelOptimization() | void | 作废候选和迟到结果；不强制终止已执行 Worker，不撤销已应用结果。 |
计算期通过既有 onStateChanged 返回 updating=true 和阶段文字；没有逐百分比进度。elapsedMs 是算法 Worker 内计时，不包含 TaskPool 排队、宿主应用或 GPU 更新。同步应用后 Chunk 队列继续工作，Promise 完成不能当成 GPU fence。
独立 API
const input = new VoxelOptimizationInput();
input.size = 2;
input.symbols = ['A'];
input.colors = ['#FFFFFF'];
input.rows = ['AA', 'AA', 'AA', 'AA'];
input.options.kind = VoxelOptimizationKind.ADJUST_COLORS;
input.options.brightness = 0.9;
const result = await VoxelOptimizer.optimize(input);
rows[z * size + y][x] 是单个体素符号，. 为空。size 为 1..128，palette 1..255 个唯一非空单字符；colors 与 symbols 一一对齐。selectionOnly=true 时必须提供 size³ 长度且非空的 selection 位图，X 最快。使用 new VoxelOptimizationOptions() 保留全部默认字段，再逐项赋值；不要用不完整对象强转代替。
结果对象
| 字段 | 类型 | 意义 |
|---|---|---|
| size | number | 与输入相同的网格边长 |
| cells | Uint32Array | X 最快的完整候选；0 为空，非零为 RGB 整数加 1 |
| added | number | 原空单元新增数量 |
| removed | number | 原实体删除数量 |
| recolored | number | 原实体仍存在、RGB 改变数量 |
| elapsedMs | number | Worker 算法耗时 |
| warnings | string[] | 几何预算、微漏推断、选区保护及规则限制说明 |
独立 API 不持有可编辑 Scene、不写入文件、不改变输入 rows；编辑器候选请视为只读。最终大于 255 色、已有模型被清空、无效参数会抛出 Error。优化不是 VFP 格式变更，保存时仍按既有 VFP 保存布局编译。
ADD Brush API
VoxelEditMode.ADD_BRUSH 显式选择连续放置，或在普通 ADD 下启用 VoxelEditorOptions.addBrushEnabled=true / editor.setAddBrushEnabled(true)。默认 false 保持单点放置与拖动旋转兼容。
isAddBrushEnabled(): boolean返回当前模式是否使用连续放置。VoxelEditorOptions.onAddBrushHit(x, y, z)对每个实际新增体素反馈一次。beginAddBrush()、handleAddBrushRay(ox, oy, oz, dx, dy, dz)、endAddBrush()是高级输入桥；射线必须是源体素网格空间，方向不能为零。通常只需设置模式，交给 VoxelViewer 转换屏幕坐标。- 同一笔基于开始时的源表面拾取，新增单元去重并合并撤销；双指接管时结束该笔，不回滚已放置方块。下一笔才能叠放上一笔的表面。
setGroundGridVisible(false) 修复与这些接口同版：关闭会移除地面 Geometry 的挂载，开关不会影响体素自身 AO 描边。