12 KiB
Real2Sim 到 MotrixSim 调试与优化复盘
日期:2026-06-12
分支:real2sim
目标:把单张 RGB / 合成多视角输入生成的 SAM-3D + Gaussian 资产,稳定导入 MotrixSim,并让水瓶与葫芦对象在桌面仿真预览中尽量接近原图。
最终效果
最终包路径:
/opt/gs_playground_real2sim_48q/outputs/office_bottle_gourd_synth_multiview_cap_preserved_20260612_142348/mjcf/scene.xml
手动预览命令:
cd /opt/gs_playground_real2sim_48q
scripts/real2sim_wuying_viewer.sh \
--package /opt/gs_playground_real2sim_48q/outputs/office_bottle_gourd_synth_multiview_cap_preserved_20260612_142348 \
--native
最终验证指标:
| 项目 | 结果 |
|---|---|
| Motrix 可视水瓶 OBJ | 239999 faces, 165529 vertex normals, proxy=False |
| Motrix 可视葫芦 OBJ | 239999 faces, 159363 vertex normals, proxy=False |
| 水瓶 highres OBJ | 280843 faces,瓶盖/提手组件已保留 |
| 顶部红色组件 | 最终 LOD 中检出 27 个顶部高饱和红色组件 |
| Motrix 材质加载 | total 2 materials loaded |
| 本地测试 | python3 -m pytest tests -> 93 passed |
| 远端测试 | .venv/bin/python -m unittest tests.test_real2sim_packaging -> 93 passed |
输入与目标
参考图中主要有两个目标对象:透明红盖水瓶和黑色葫芦瓶。水瓶的瓶盖、提手、透明瓶身、标签和底部细节都需要在 MotrixSim 里尽量保留。
调试路线概览
输入图 / 合成多视角
-> GroundingDINO + SAM2 分割
-> SAM-3D object reconstruction
-> mesh / texture / 3DGS assets
-> Real2Sim packaging
-> MJCF + MotrixSim preview
-> 发现问题
-> 定位到 packaging / mesh LOD / material / cleanup 规则
-> 修复并重新 package
这次优化的重点不在单一模型推理,而是在“真实重建资产进入仿真器”这条链路上逐层排查:mesh 是否被替换、材质是否被引用、法线是否存在、清理规则是否误删、MotrixSim 是否加载了正确包。
阶段 1:初始导入过于简陋,没有材质感
最早的 MotrixSim 预览像灰白模型,瓶身、标签、透明材质和葫芦的黑色反光都没有正确表达。
根因:
- OBJ 贴图 sidecar 和 MTL 引用不稳定。
- MotrixSim 更依赖显式
material/texture声明,不能只依赖部分 viewer 能识别的 vertex color。 - 透明/深色物体的烘焙贴图在 Motrix 默认光照下非常暗。
修复:
- 在
real2sim/packaging.py中为 OBJ 材质和贴图做 namespacing,避免多个物体的material_0.png冲突。 - 在 MJCF 中显式写入 texture/material 引用。
- 增加 headlight、key light、fill light、top light。
- 增加 baked texture 自动曝光,仅对极暗贴图生效。
关键提交:
dfce2ee 🎨 feat(real2sim): add part material atlas for Motrix proxies
76640e0 💡 fix(real2sim): brighten Motrix preview materials
979a6a5 🧭 fix(real2sim): brighten baked mesh textures
阶段 2:顶部白色漂浮片
第一次修复材质后,水瓶顶部出现了大块白色漂浮片。这类组件来自 SAM-3D 对透明瓶身和瓶口高光区域的误重建。
根因:
- SAM-3D 输出中存在很多 disconnected components。
- 顶部有宽、薄、低饱和的片状组件。
- 这些组件被打进 MJCF 后,会在 Motrix 里显示成不属于瓶子的漂浮面。
修复:
- 增加
clean_obj_floating_top_artifacts()。 - 通过组件数、顶部位置、Y 方向厚度、横向宽度、贴图亮度/饱和度过滤明显漂浮片。
- 保留主体和正常瓶身组件。
当时效果改善明显,但这个清理规则后来也引入了瓶盖缺失问题,见阶段 7。
阶段 3:代理网格导致形状从不同角度看不一致
为了让 Motrix 不卡,早期使用了旋转代理网格。它把物体近似成沿主轴的 radial profile,因此从不同角度看起来会不一致。
证据:
旧 Motrix OBJ: object_000_det_000_motrix_proxy
faces: 14016
verts: 7083
真实 highres OBJ:
faces: 268360
verts: 178835
结论:
- 这不是相机透视问题,而是 Motrix 实际加载的可视网格不是 SAM-3D 原始几何。
- 旋转代理适合性能验证,不适合作为最终视觉资产。
修复:
- 切换到
REAL2SIM_MOTRIX_PREVIEW_MODE=lod。 - 用 PyMeshLab 从 highres OBJ 做 texture-preserving decimation。
- 保持碰撞仍然使用轻量 collision box,可视 mesh 使用真实降面 OBJ。
阶段 4:降面后仍然稀疏、卡顿和模糊
60k 面版本已经比 proxy 好,但截图中仍然有颗粒感,且早期还出现 4 FPS 的慢预览。
进一步排查后发现:
- 60k 面对瓶盖、提手和标签细节仍偏少。
- OBJ 没有
vn顶点法线,Motrix 光照会让表面显得碎。 - 纹理虽存在,但法线缺失导致材质显示不够平滑。
修复:
- 给所有 LOD 输出补写 smooth vertex normals。
- face token 从
v/vt升级为v/vt/vn。 - 将水瓶和葫芦 LOD 从 60k 提升到 180k,最终提升到 240k。
- 保留性能边界:高面只用于 visual mesh,collision 仍使用 box。
关键提交:
6543c0d ✨ feat(real2sim): add smooth normals to preview meshes
阶段 5:深色材质过暗
真实贴图回到 LOD mesh 后,葫芦瓶变得过暗,几乎看不到形体。
证据:
修复前 object_001_det_001_material_0.png mean ~= 18.6 / 255
修复后 object_001_det_001_material_0.png mean ~= 108.4 / 255
修复:
- 增加
_auto_expose_texture_file()。 - 只对低 luminance percentile 的贴图做增益、gamma、lift。
- 正常亮度贴图不改,避免水瓶标签过曝。
结果:
- 葫芦瓶能看见轮廓和反光。
- 水瓶贴图均值保持
84.44,没有被过度提亮。
阶段 6:面数和法线优化后,瓶盖仍有缺失
提高到 180k 面并补法线后,瓶身清晰度明显改善,但瓶盖/提手有缺失。
排查方向:
- 原始 SAM-3D mesh 是否就缺瓶盖。
- PyMeshLab 降面是否删了小组件。
- 顶部 artifact 清理是否误删瓶盖。
证据:
原始水瓶 mesh: 285912 faces
清理后 highres: 268360 faces
被清理删除: 17552 faces, 22 components
进一步统计被删除组件的颜色:
最大被删组件 mean RGB: [213.7, 27.7, 48.6]
另一个被删组件 mean RGB: [224.3, 33.8, 56.6]
这些都是高饱和红色顶部组件,说明瓶盖/提手不是源模型缺失,而是清理规则误删。
阶段 7:保护高饱和瓶盖/提手
修复策略:
- 仍然删除低饱和、灰白、薄片状顶部漂浮物。
- 对高饱和顶部组件设置保护阈值。
- 默认
preserve_saturated_top_saturation=95.0。 - 增加回归测试:红色顶部瓶盖组件不能被清理掉。
修复后复测:
原始水瓶 mesh: 285912 faces
清理后 highres: 280843 faces
删除量从 17552 faces 降到 5069 faces
最终 LOD 顶部红色组件: 27 个
最终效果中,红色瓶盖和提手重新出现:
关键提交:
15a709f 🧢 fix(real2sim): preserve saturated bottle caps
问题与修复对照表
| 问题现象 | 根因 | 修复 |
|---|---|---|
| 灰白无材质 | OBJ/MTL/texture 未稳定接入 Motrix | sidecar namespacing + MJCF texture/material |
| 顶部白色漂浮片 | SAM-3D 透明物体误重建 disconnected sheets | 组件级顶部漂浮片清理 |
| 形状随角度变化 | Motrix 加载的是旋转 proxy,不是真实几何 | 改用 highres texture-preserving LOD |
| 模糊、颗粒 | LOD 面数偏低且无顶点法线 | 240k LOD + smooth vertex normals |
| 葫芦过暗 | baked texture luminance 太低 | 暗贴图自动曝光 + 场景灯光 |
| 瓶盖/提手缺失 | 清理器误删高饱和顶部组件 | 保护 saturated top parts |
最终包结构要点
outputs/office_bottle_gourd_synth_multiview_cap_preserved_20260612_142348/
mjcf/scene.xml
meshes/object_000_det_000.obj
meshes/object_000_det_000_highres.obj
meshes/object_000_det_000_material.mtl
meshes/object_000_det_000_material_0.png
meshes/object_001_det_001.obj
meshes/object_001_det_001_highres.obj
meshes/object_001_det_001_material.mtl
meshes/object_001_det_001_material_0.png
3dgs/object_000_det_000.ply
3dgs/object_001_det_001.ply
configs/go2_real2sim.json
package_manifest.json
关键 MJCF 片段:
<mesh name="object_000_det_000_mesh" file="object_000_det_000.obj" scale="1.187716 1.187716 1.187716" />
<texture name="object_000_det_000_texture" type="2d" file="object_000_det_000_material_0.png" />
<material name="object_000_det_000_material" rgba="1 1 1 1" specular="0.15" shininess="0.25" texture="object_000_det_000_texture" />
验证命令
本地:
python3 -m pytest tests
远端:
cd /opt/gs_playground_real2sim_48q
.venv/bin/python -m unittest tests.test_real2sim_packaging
无影云桌面预览:
cd /opt/gs_playground_real2sim_48q
scripts/real2sim_wuying_viewer.sh \
--package /opt/gs_playground_real2sim_48q/outputs/office_bottle_gourd_synth_multiview_cap_preserved_20260612_142348 \
--native
截图索引
| 图 | 说明 |
|---|---|
![]() |
原始参考图 |
![]() |
初始材质缺失 |
![]() |
SAM-3D 顶部 artifact |
![]() |
稀疏且慢的中间版本 |
![]() |
低 LOD 模糊 |
![]() |
深色贴图未曝光 |
![]() |
高 LOD 后发现瓶盖被误删 |
![]() |
240k LOD + 法线 + 瓶盖保护 |
仍然存在的限制
- 透明瓶身、反光和水体细节仍受 SAM-3D 单物体重建质量限制。
- 当前视觉质量已经明显优于 proxy 和低 LOD,但还不是多视角真实扫描级别。
- 若继续提升,可以优先使用更多真实多视角照片,而不是只依赖合成视角。
- 进一步可尝试 250k+ visual mesh 或局部瓶盖高保真 LOD,但 Motrix 交互帧率会下降。
经验总结
这次调试的核心经验是:Real2Sim 质量问题不能只看最终截图,要逐层查资产链路。
最有效的排查顺序是:
- 先确认 Motrix 实际加载的 mesh 是 proxy 还是真实 OBJ。
- 再确认 OBJ 是否有 MTL、texture、UV、vertex normals。
- 再看 cleaning/decimation 是否改变了原始组件数量。
- 最后才调面数和灯光。
最终问题不是单点修复,而是一个完整链路优化:材质、光照、LOD、法线、清理规则和 Motrix 加载验证必须一起闭环。







