jwang771/3d-world-simulator

项目介绍

这是一个研究型代码仓库，用粒子与体素混合表示来模拟三维可形变物体的动力学。整个流程分两段：粒子-体素自编码器先把场景压缩成隐变量，三维隐动力学模型再根据最近若干帧隐变量和动作预测下一帧隐变量。README 给出 cloth、box、pusht、plug、marker、rope 六个任务，每个任务的体素网格、工作空间边界和是否使用触觉感知等参数放在 tasks.py 中。项目面向需要训练或扩展该模型、并已有操作类数据集的 researchers。

环境与数据准备

先根据仓库的环境文件创建 Conda 环境：

conda env create -f environment.yml
conda activate 3dws

数据集统一放在一个根目录下，例如 data/bimanual_plug_insertion_v3/{train,val}，具体文件布局见 docs/data_format.md。各任务的数据路径和参数在 tasks.py 中配置。

训练流程

训练分三步。第一步，针对某个任务训练自编码器：

python scripts/train_vae.py --task plug --data-root data --out-dir runs/plug/vae

第二步，用训练好的 checkpoint 为训练集和验证集导出隐变量：

python scripts/export_latents.py --vae-ckpt runs/plug/vae/checkpoints/latest.pth \
  --packed-dir data/bimanual_plug_insertion_v3/train --out-dir runs/plug/latents/train
python scripts/export_latents.py --vae-ckpt runs/plug/vae/checkpoints/latest.pth \
  --packed-dir data/bimanual_plug_insertion_v3/val --out-dir runs/plug/latents/val

第三步，在预计算的隐变量上训练动力学模型：

L=runs/plug/latents
python scripts/train_dynamics.py --latent-dir $L/train --val-latent-dir $L/val --out-dir runs/plug/dynamics \
  --n-history 8 --ar-schedule 1 2 3 4 5 6 7 8 9 10 --ar-schedule-epochs 50 100 150 200 250 300 350 400 450 500

--n-history 决定预测下一帧时使用多少帧历史隐变量；自回归调度则在指定 epoch 引入不同长度的历史。

使用约束

• 预训练 checkpoint、数据集和推理代码尚未发布，README 只说明后续会上传。目前仓库描述的是训练脚本和环境配置。
• 仓库未声明许可证，复用和再分发条件不明确。
• 流程假定数据已按文档格式打包好，且任务配置已存在于 tasks.py；新增任务需要补充配置并转换数据布局。
• 方法细节和结果可参考 项目主页 与 论文。

HotRepo 点评

2026 年 11 月 3 日，该项目出现在 HotRepo 新项目榜的 Python 榜单中，在前一天开始的统计窗口内新增 102 Star，同期新增 7 Fork；没有记录到 GitHub 全语言日榜名次。这些数字反映的是论文相关研究仓库的早期关注，而不是可运行发布的成熟度：由于 checkpoint、数据和推理代码都未提供，现有材料只支持复现训练流程，且该流程未在本次解读中实际执行。