InsertJoco

InsertJoco 是基于 MuJoCo 的插接/装配任务仿真仓库。当前仓库来自 DexJoCo 的裁剪和改造版本，但目标已经不是完整复刻原 DexJoCo benchmark，而是围绕 peg-in-hole / assembly 场景保留和整理可运行的仿真环境、任务配置、XML 资产、数据回放和数据转换工具。

当前仓库状态

这个仓库目前是一个整理中的 InsertJoco 快照，代码中仍有一些历史命名没有完全改完：

• Python 包名仍然是 dexjoco，导入路径也仍是 dexjoco.*。
• 当前实际注册的任务入口在 dexjoco/dexjoco/tasks/mappings.py 中，包含：
  • bimanual_assembly：双臂插接/装配环境
  • bimanual_assembly_single：单臂插接/装配环境
• configs/ 下仍保留了一批原 DexJoCo 任务配置文件，但目前核心环境映射只保留上面两个 assembly 任务。
• environment-dexjoco.yaml、dexjoco/pyproject.toml 等文件里仍有部分 DexJoCo/OpenPI 历史配置，后续需要继续清理。
• 这个公开快照不包含 OpenPI 训练/服务代码，也不包含本地渲染预览图片目录。

明确未纳入当前公开仓库的路径包括：

openpi/
render_insertjoco_env/
dexjoco/dexjoco_openpi_client/
scripts/evaluate_pi05.bash
scripts/serve_pi05.bash

因此，README 不再引用原 DexJoCo 的 OpenPI π0.5 训练、服务、评测流程。

目录结构

.
├── configs/
│   ├── multi_task/
│   ├── rand_full/
│   ├── rand_obj/
│   └── ipad_reasoning/
├── dexjoco/
│   ├── dexjoco/
│   │   ├── data/
│   │   ├── sim/
│   │   │   ├── controllers/
│   │   │   ├── envs/
│   │   │   │   └── xmls/
│   │   │   ├── mujoco_gym_env.py
│   │   │   └── rendering.py
│   │   └── tasks/
│   ├── README.md
│   └── pyproject.toml
├── dexjoco-data-converter/
├── docs/
├── scripts/
├── environment-dexjoco.yaml
├── LICENSE
└── README.md

dexjoco/dexjoco/sim/

仿真核心代码，包含 MuJoCo Gym 环境基类、渲染封装、控制器和具体环境实现。

重要文件：

• dexjoco/dexjoco/sim/envs/panda_bimanual_assembly_env.py：InsertJoco 当前主要环境实现。
• dexjoco/dexjoco/sim/envs/xmls/arena_insertjoco_bimanual.xml：双臂插接场景。
• dexjoco/dexjoco/sim/envs/xmls/arena_insertjoco_single.xml：单臂插接场景。
• dexjoco/dexjoco/sim/envs/xmls/insertjoco_panda_hand*.xml：Panda 机械臂与手爪组合模型。
• dexjoco/dexjoco/sim/envs/xmls/industreal_*：圆柱 peg 和 tray/socket 相关资产。

dexjoco/dexjoco/tasks/

任务层封装，负责把底层 MuJoCo 环境包装成 policy-facing 接口。

重要文件：

• mappings.py：当前任务名到配置类的映射。
• bimanual_assembly/config.py：双臂和单臂 assembly 任务配置。
• obs_adapters.py：把原始观测整理为策略接口使用的 state 和图像键。
• policy_wrappers.py：把 policy action 转换为环境 action。
• state_restorers.py：回放 demo 时恢复初始状态。

configs/

保留了原项目的配置目录。当前与 InsertJoco 直接相关的是 assembly 相关配置；其他旧任务配置还未系统清理。

目录含义：

• multi_task/：多任务配置集合。
• rand_obj/：对象随机化相关配置。
• rand_full/：更完整的随机化配置。
• ipad_reasoning/：原 DexJoCo reasoning 配置，当前不是 InsertJoco 的核心入口。

scripts/

当前公开快照保留的脚本：

• scripts/test_envs.py：用零动作快速跑当前注册环境。
• scripts/test_headless_envs.py：无头渲染测试，并输出测试视频。
• scripts/test_insertjoco_contract.py：检查 InsertJoco 当前两个任务的 action/state/image contract。
• scripts/replay_demos_zarr.py：回放已有 Zarr demo，并重新保存 Zarr 和 MP4 视频。

dexjoco-data-converter/

数据转换工具，保留了 Zarr / LeRobot 相关转换逻辑和数据一致性检查脚本。

主要内容：

• src/dexjoco_data_converter/to_zarr/：转换为 Zarr 数据。
• src/dexjoco_data_converter/to_lerobot/：转换为 LeRobot 数据格式。
• scripts/check_dataset_consistency.py：检查数据集一致性。
• configs/：数据转换相关配置。
• src/3rd/diffusion_policy：以 git submodule 形式保留的第三方引用。

docs/

文档和参考代码目录。当前仍包含部分 DexJoCo 历史材料：

• docs/custom_policy_integration.md：自定义策略集成说明，仍有参考价值，但部分内容带有历史上下文。
• docs/reference_code/：旧策略评测/客户端参考代码。
• docs/pics/：原 DexJoCo 图片资源。

快速检查

如果已经准备好 MuJoCo、EGL/GLFW 和 Python 依赖，可以在仓库根目录运行：

python scripts/test_insertjoco_contract.py

也可以跑一个更直接的环境 smoke test：

python scripts/test_envs.py

无头渲染测试：

MUJOCO_GL=egl python scripts/test_headless_envs.py

这些脚本会读取 dexjoco.tasks.mappings.CONFIG_MAPPING，因此当前只覆盖 bimanual_assembly 和 bimanual_assembly_single。

后续整理事项

当前仓库已经从原 DexJoCo 中裁剪出 InsertJoco 的核心部分，但还不是完全清理后的发布状态。后续建议继续处理：

• 将包名、项目描述和脚本入口从 dexjoco 逐步改成 insertjoco。
• 清理 environment-dexjoco.yaml 和 dexjoco/pyproject.toml 中对 OpenPI / 旧 client 的引用。
• 移除或归档 configs/、docs/ 中不再服务于 InsertJoco 的旧任务内容。
• 补充正式安装说明和最小可复现实验流程。

License

当前仓库保留原项目的 LICENSE 文件。第三方模型、资产或子模块的许可请分别参考对应目录中的 license / README。