real2sim-platform/docs/IMPLEMENTATION_DETAIL.md

4.6 KiB
Raw Blame History

Real2Sim Platform 实现细案

目标闭环

  1. 场景:上传或导入视频、图片、RGBD 数据,创建 scene_reconstruction 任务,产出 3DGS/点云/mesh/collider、scene.json、MuJoCo/MotrixSim 可用文件和预览。
  2. 数据:创建 hf_import 任务,从 Hugging Face dataset 下载小批量验收数据,生成 dataset_manifest.json。
  3. 准备:创建 media_prepare 任务,把 HF parquet/video URL、本地 video、图片目录统一抽帧成 prepared_media 数据集,输出 prepared_manifest.json 和每个视频的帧贡献。
  4. 预检:创建 reconstruction_preflight 任务,检查帧数、分辨率、帧间变化和 AnySplat/COLMAP/ffmpeg runtime,输出 capture_preflight_report.json。
  5. 校验:创建 simulator_validation 任务,按 smoke / runtime_if_available / runtime_required 生成 MuJoCo/MotrixSim validation_report.json。
  6. 采集:选择场景、机器人配置、任务配置和 episode/step 参数,创建 expert_collection 任务,产出专家数据集。
  7. 训练:选择采集数据集,创建 training 任务,产出 policy_head.json、model_card.json。
  8. 推理:选择场景和模型,创建 inference 任务,产出 prediction_rollout.json 和 viewer.html。

渲染器选择

  • 默认:Spark。理由是它直接集成 Three.js,适合把 3DGS、Mesh、MuJoCo/MotrixSim proxy、轨迹和 UI overlay 放进同一个前端视图。平台随包部署 @sparkjsdev/spark 静态 ESM bundle。
  • 回退:Three.js fallback。用于 Spark bundle 不存在、Spark runtime 加载失败或只是普通点云预览时,界面会明确显示 Three.js fallback,不再冒充 Spark;Three.js ESM、controls 和 loaders 随静态文件部署。
  • 大资产策略:scene manifest 会在读取时补齐 size_bytes、autoload 和 viewer_hint。超过默认阈值的大 PLY/点云只显示手动加载入口,避免页面长时间停在 loading。
  • 备选:Aholo Viewer。理由是它强调高性能 3DGS 和 chunked streaming LOD,更适合大场景或移动端流式加载,但需要把资产转成 Aholo 最适合的 packed/LOD 格式。
  • 平台 API 保留 renderer 参数:spark | aholo | auto。首版 auto 在没有 Aholo LOD package 时等价于 spark,当 scene package 内存在 Aholo LOD 资产时切到 aholo。

仿真器支持

  • mujoco:保留 scene_mujoco.xml、V-HACD/convex collision、MJCF smoke/validation artifact。
  • motrixsim:保留 motrix_scene.json、motrix_import.json、预览 mesh/pointcloud/3DGS manifest。
  • UI 中每个场景记录 simulators: ["mujoco", "motrixsim"],任务不声称两者物理完全一致,分别展示各自产物和验证结果。

API

  • POST /api/datasets/import-path:导入服务器已有路径。
  • POST /api/datasets/upload:上传 zip/video/RGBD。
  • POST /api/scenes/import:导入已有 scene.json、motrix_import.json 或 project_manifest.json。
  • POST /api/tasks:统一创建任务,type 为 hf_import、media_prepare、reconstruction_preflight、scene_reconstruction、simulator_validation、expert_collection、training、inference、renderer_benchmark。
  • GET /api/tasks/{id}/logs、GET /api/tasks/{id}/artifacts、GET /api/artifacts/{id}/content:统一验收与下载。
  • GET /api/tasks/{id}/reports:读取结构化报告索引和可读失败原因。
  • reconstruction_preflight report 包含 readiness_score 和 next_action,任务详情页会直接展示失败门槛、关键指标和重采建议。
  • GET /api/datasets/{id}/manifest、GET /api/scenes/{id}/manifest、GET /api/models/{id}/card:数据、场景、模型治理信息。
  • GET /api/version:返回平台版本、构建时间、部署路径、功能开关和当前 renderer backend。

无影策略

  • 无影作为重建、训练和部署主环境:39.106.101.95,root 登录,GPU、COLMAP、Real2Sim 和 gsplat Python 已验证。
  • 服务默认绑定 127.0.0.1:18126,通过 SSH 隧道访问,避免公网暴露上传和模型产物。
  • 缺失 Node 不影响后端运行;Spark bundle 在本地通过 scripts/vendor_spark.sh 生成,Three.js bundle 通过 scripts/vendor_three.sh 生成,二者都随静态文件部署。
  • 无影 .venv 显式安装 huggingface_hub、pyarrow、pillow、imageio、opencv-python-headless、mujoco,/api/doctor 检查 ffmpeg、Spark bundle、Three.js bundle、媒体依赖、MuJoCo Python、AnySplat root/python、CUDA 和核心路径。
  • deploy_wuying.sh --restart 写入 systemd unit 并重启服务;acceptance_wuying.sh 通过远端 API 跑 preflight、非 dry-run 重建和仿真校验。