碰撞网格生成
本指南使用 splat-transform 生成体素（.voxel.json + .voxel.bin）和适合运行时物理的网格（.collision.glb）。
Web 界面生成或上传见 Studio 碰撞。
概览
同一次体素化产生两种输出：
典型管线四阶段，后两项按场景可选：
输入泼溅 ──► 连通簇过滤 ──► 体素化 ──► 填充 ──► 雕刻 ──► [碰撞网格]
第 1 步：隔离连通场景
漂浮点和远处断连几何体可由 --filter-cluster 在 GPU 粗体素化后，仅保留 seed-pos 所在连通区域。
splat-transform input.ply --filter-cluster --seed-pos 0,1,0 output.voxel.json
| 输入 | 簇过滤结果 |
|---|---|
 |  |
独立使用
这是通用过滤器，可直接输出 PLY/SOG，无需体素输出：
splat-transform input.ply --filter-cluster --seed-pos 0,1,0 cluster.ply
簇选项
-C, --filter-cluster [res,op,min]
| 参数 | 默认 | 说明 |
|---|---|---|
res | 1.0 | 粗网格世界体素大小，越大越快，更容忍间隙。 |
op | 0.999 | 超过则为实心的透明度阈值。 |
min | 0.1 | 保留单元所需在体素中心的最小贡献。 |
第 2 步：体素化
输出以 .voxel.json 结尾时自动启用，生成稀疏体素网格。这是原始结果，后续步骤在其上处理。
splat-transform input.ply output.voxel.json
体素选项
--voxel-size <n>
--voxel-opacity <n>
| 标志 | 默认 | 说明 |
|---|---|---|
--voxel-size | 0.05 | 世界边长，越小越精细、文件越大、填充越慢。 |
--voxel-opacity | 0.1 | 标实心所需最小不透明度。 |
第 3 步：封闭外壳
体素化常产生有孔薄壳，填充封孔，为下一步提供水密区域。室内和室外各有选项，通常不混用。
房间：外部填充
--voxel-external-fill 为房间保留可雕刻的封闭内部。其内部实际洪水填充外部空域：
- 按 size 世界距离膨胀实心网格，内部转为体素半范围，连接墙面小孔。
- 从包围盒边界填空，所有外部可达体素标为外部。
- 外部标实心，只留封闭内部供雕刻。
若种子可从外部到达，说明其处未封闭，则跳过并返回原网格。
splat-transform input.ply output.voxel.json --voxel-external-fill --seed-pos 0,1,0
--voxel-external-fill [size]
| 参数 | 默认 | 说明 |
|---|---|---|
size | 1.6 | 封墙缝的世界膨胀距离，漏孔时增加。 |
室外：地面填充
用于室外、地形或地面对象，从包围盒底部沿每个 XZ 柱向上，直到首个实心，以下全部填实，即使只采到表面也生成地实体。
splat-transform input.ply output.voxel.json --voxel-floor-fill
--voxel-floor-fill [size]
| 参数 | 默认 | 说明 |
|---|---|---|
size | 1.6 | 仅修补 2*size 范围内被地面包围的柱，保留大空外域，避免误填天空。 |
选择方式
| 场景 | 填充 |
|---|---|
| 房间 | --voxel-external-fill |
| 室外 | --voxel-floor-fill |
| 空间单对象 | 都跳过 |
第 4 步：雕刻可导航空间
--voxel-carve 从种子以胶囊体洪水搜索，将可到达体素标为可导航。封壳后形成运行时可行走区域，去无用细节，使碰撞更平滑、文件更小。
splat-transform input.ply output.voxel.json --voxel-carve --seed-pos 0,1,0
| 原始 | 雕刻后 |
|---|---|
|  |
种子位置必须容纳胶囊。无输出通常是种子在实体内或胶囊太大。
雕刻选项
--voxel-carve [h,r]
| 参数 | 默认 | 说明 |
|---|---|---|
h | 1.6 | 胶囊高度，世界单位，近似角色高，0 禁用。 |
r | 0.2 | 半径，近似角色半径。 |
第 5 步：生成碰撞网格
--collision-mesh [smooth|faces]
| 参数 | 默认 | 说明 |
|---|---|---|
| shape | smooth | smooth 为行进立方体加共面合并，三角少、轮廓自然；faces 为水密轴对齐体素面，三角多但精确匹配。 |
| 体素 | 平滑网格 | 面网格 |
|---|---|---|
 |  |  |
smooth（默认）
拟合表面平滑网格，三角少、自然，适合角色碰撞。
faces
用暴露体素面构水密网格，全部轴对齐。三角多但精确，适合碰撞与体素射线结果必须一致时。
seed-pos 参考
多个阶段共享：
- filter-cluster 选所在连通簇。
- external-fill 检查外部可达，若可达跳过。
- carve 胶囊搜索原点。
| 标志 | 参数 | 默认 | 说明 |
|---|---|---|---|
--seed-pos | x,y,z | 0,0,0 | 三阶段共用世界种子点。 |
完整示例
室内扫描
splat-transform room.ply \
--filter-cluster --seed-pos 0,1,0 \
room.voxel.json --voxel-external-fill --voxel-carve --collision-mesh
室外地形
splat-transform terrain.ply \
--filter-cluster --seed-pos 0,0,0 \
terrain.voxel.json --voxel-floor-fill --collision-mesh
高保真体素面
splat-transform input.ply \
output.voxel.json --voxel-size 0.025 --collision-mesh faces
故障排查
- 雕刻无结果：种子在实体或胶囊放不下，移动种子或缩小。
- 外部填充穿墙：增 size，或降低 voxel-opacity，让薄墙实心。
- 雕刻漏入邻室：墙薄或有缝，减 voxel-size 提精度，或增填充 size。
- 网格过密：smooth 或增 voxel-size。
- 连通簇错误：移动种子到目标，或增 res 跨越合理间隙。