gs_playground/docs/real2sim-debug-optimization-report.md

12 KiB
Raw Permalink Blame History

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

最终 MotrixSim 预览效果

最终验证指标:

项目 结果
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 的慢预览。

稀疏和低 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 面并补法线后,瓶身清晰度明显改善,但瓶盖/提手有缺失。

高 LOD 后的瓶盖缺失

排查方向:

  1. 原始 SAM-3D mesh 是否就缺瓶盖。
  2. PyMeshLab 降面是否删了小组件。
  3. 顶部 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
低 FPS 稀疏且慢的中间版本
模糊低清 低 LOD 模糊
材质过暗 深色贴图未曝光
瓶盖缺失 高 LOD 后发现瓶盖被误删
最终效果 240k LOD + 法线 + 瓶盖保护

仍然存在的限制

  • 透明瓶身、反光和水体细节仍受 SAM-3D 单物体重建质量限制。
  • 当前视觉质量已经明显优于 proxy 和低 LOD,但还不是多视角真实扫描级别。
  • 若继续提升,可以优先使用更多真实多视角照片,而不是只依赖合成视角。
  • 进一步可尝试 250k+ visual mesh 或局部瓶盖高保真 LOD,但 Motrix 交互帧率会下降。

经验总结

这次调试的核心经验是:Real2Sim 质量问题不能只看最终截图,要逐层查资产链路。

最有效的排查顺序是:

  1. 先确认 Motrix 实际加载的 mesh 是 proxy 还是真实 OBJ。
  2. 再确认 OBJ 是否有 MTL、texture、UV、vertex normals。
  3. 再看 cleaning/decimation 是否改变了原始组件数量。
  4. 最后才调面数和灯光。

最终问题不是单点修复,而是一个完整链路优化:材质、光照、LOD、法线、清理规则和 Motrix 加载验证必须一起闭环。