# mujoco-simulation-generator **Repository Path**: zhouByFrank/mujoco-simulation-generator ## Basic Information - **Project Name**: mujoco-simulation-generator - **Description**: 仿真环境生成器 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-04-06 - **Last Updated**: 2026-04-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Unitree G1 29DOF 仿真环境生成器 基于 MuJoCo 的 Unitree G1 人形机器人仿真环境，支持 29 自由度本体，可选 Dex3 灵巧手配置，可生成多种室内场景进行抓取、操作任务仿真。 > 📚 **文档导航** > - **[快速入门指南](QUICKSTART.md)** - 5分钟快速上手 > - **[完整说明文档](README_MUJOCO_SIM.md)** - API文档和使用说明 > - **[系统架构详解](ARCHITECTURE.md)** - 代码结构和扩展指南 > - **[文档索引](DOC_INDEX.md)** - 所有文档的导航 ## 功能特性 ### 机器人模型 - **29 自由度本体**: 双腿(12) + 腰部(3) + 双臂(14) - 默认配置 - **可选 Dex3 灵巧手**: 双手各 7 自由度（拇指3 + 食指2 + 中指2） - **灵活配置**: 通过启动参数 `--use-dex3` 选择是否使用灵巧手（默认禁用） ### 仿真模式 - **标准重力模式**: 正常重力环境（默认） - **零重力模式**: 通过 `--zero-gravity` 启用，适合太空或特殊测试场景 - **DDS通信**: 支持通过CycloneDDS与unitree_sdk2通信进行外部控制 ### 支持场景（8种） 1. **办公室** (`office`) - 办公桌、电脑、电话、文件、书架等 2. **会议室** (`meeting_room`) - 会议桌、投影仪、白板、笔记本电脑等 3. **教室** (`classroom`) - 讲台、课桌、黑板、实验器材等 4. **实验室** (`lab`) - 实验台、显微镜、烧杯、试剂瓶等 5. **家居** (`home`) - 沙发、茶几、电视、水果、书架等 6. **仓库** (`warehouse`) - 货架、纸箱、工具箱、叉车等 7. **厨房** (`kitchen`) - 餐桌、餐具、灶台、冰箱、食物等 8. **医院** (`hospital`) - 病床、医疗柜、药品、监测仪等 ### 物理交互 - **可抓取物体**: 支持手指闭合/张开进行抓取（需启用Dex3） - **可拖动物体**: Ctrl+鼠标右键拖拽任意物体 - **物理属性**: 每个物体都有质量、摩擦、弹性等物理属性 - **碰撞检测**: 精确的碰撞检测和接触力计算 ## 快速开始 ### 安装依赖 ```bash # 安装 Python 依赖 pip install -r requirements.txt # 确保已安装 MuJoCo # MuJoCo 会自动安装，无需额外配置 ``` ### 运行仿真 ```bash # 运行办公室场景（默认，无Dex3） python run_simulation.py # 运行带Dex3灵巧手的场景 python run_simulation.py --scene office --use-dex3 # 运行零重力模式 python run_simulation.py --scene office --zero-gravity # 运行特定场景 python run_simulation.py --scene lab # 键盘控制模式 python run_simulation.py --scene kitchen --mode keyboard # 列出所有场景 python run_simulation.py --list # 批量生成所有场景 python run_simulation.py --batch-generate # 批量生成带Dex3的所有场景 python run_simulation.py --batch-generate --use-dex3 ``` ### 控制说明 #### 交互模式（默认） - **鼠标左键**: 旋转视角 - **鼠标右键**: 平移视角 - **滚轮**: 缩放 - **双击**: 选中物体 - **Ctrl + 右键拖拽**: 拖动物体 #### 键盘控制模式 - **1**: 左手指闭合/张开（仅Dex3配置有效） - **2**: 右手指闭合/张开（仅Dex3配置有效） - **Q/W/E/R**: 左臂前伸/收回/左移/右移 - **A/S/D/F**: 右臂前伸/收回/左移/右移 - **Z/X**: 腰部左右转动 - **空格**: 暂停/继续 - **R**: 重置仿真 - **ESC**: 退出 ## DDS通信接口 (CycloneDDS) 仿真器支持通过CycloneDDS与unitree_sdk2通信，可以使用外部控制器控制仿真机器人。 ### 启用DDS通信 ```bash # 启用DDS（默认使用 config/config.yaml 中的配置） python run_simulation.py --scene office --enable-dds # 禁用DDS python run_simulation.py --scene office --disable-dds ``` ### DDS配置 编辑 `config/config.yaml`: ```yaml dds: domain_id: 1 # DDS域ID interface: "lo" # 网络接口 (lo=本地回环) ``` ### 通信协议 - **发布**: `rt/lowstate` - 机器人状态 (500Hz) - **订阅**: `rt/lowcmd` - 控制命令 详细文档: [DDS_INTERFACE.md](DDS_INTERFACE.md) ## 项目结构 ``` . ├── run_simulation.py # 主启动脚本 ├── requirements.txt # Python依赖 ├── config/ │ ├── config.yaml # 配置文件 │ └── __init__.py ├── src/ │ ├── scene_generator/ # 场景生成器包 │ │ ├── __init__.py │ │ ├── core.py # 场景生成器核心 │ │ ├── materials.py # 材质定义 │ │ ├── primitives.py # 基础物体创建 │ │ ├── utils.py # 工具函数 │ │ └── scenes/ # 场景定义 │ │ ├── __init__.py │ │ ├── base.py # 场景基类 │ │ ├── office.py # 办公室场景 │ │ ├── meeting_room.py # 会议室场景 │ │ ├── classroom.py # 教室场景 │ │ ├── lab.py # 实验室场景 │ │ ├── home.py # 家居场景 │ │ ├── warehouse.py # 仓库场景 │ │ ├── kitchen.py # 厨房场景 │ │ └── hospital.py # 医院场景 │ ├── simulator.py # 仿真器核心 │ ├── interaction.py # 交互控制 │ ├── robot_config.py # 机器人配置 │ ├── unitree_mujoco_interface_v3.py # DDS通信接口 │ ├── exceptions.py # 异常定义 │ └── logger.py # 日志工具 ├── assets/ │ ├── g1_29dof_no_dex3.xml # 机器人模型（无Dex3） │ └── g1_29dof_with_dex3.xml # 机器人模型（带Dex3） ├── scenes/ # 生成的场景文件 │ ├── office_scene_no_dex3.xml │ ├── office_scene_with_dex3.xml │ ├── lab_scene_no_dex3.xml │ └── ... └── examples/ # 示例脚本 ├── example_grasp.py # 抓取示例 ├── example_ik.py # 逆运动学示例 └── example_scene_switch.py # 场景切换示例 ``` ## 示例代码 ### 基本使用 ```python from src.simulator import G1Dex3Simulator # 创建仿真器 simulator = G1Dex3Simulator(scene_type="office") # 运行仿真 simulator.run_interactive() ``` ### 控制手指抓取 ```python from src.robot_config import G1Dex3Controller # 创建控制器 controller = G1Dex3Controller(model, data) # 闭合右手 controller.close_hand("right") # 张开右手 controller.open_hand("right") # 设置捏取姿态 controller.set_hand_pinch("left") ``` ### 自定义场景 场景生成器已模块化，场景定义位于 `src/scene_generator/scenes/` 目录： ```python from src.scene_generator.scenes import BaseScene from src.scene_generator.primitives import create_table, create_cup class MyCustomScene(BaseScene): """自定义场景""" def generate(self, worldbody): # 创建桌子 create_table(worldbody, pos=[2, 0, 0], size=[0.8, 0.4, 0.75]) # 创建杯子 create_cup(worldbody, pos=[2, 0, 0.76], material="ceramic_white") def get_collision_exclusions(self): return [] def get_object_info(self): return {"objects": ["table", "cup"]} # 使用场景生成器 from src.scene_generator import SceneGenerator generator = SceneGenerator("my_scene", "./scenes") scene_file = generator.generate_scene() ``` ## 配置文件 编辑 `config/config.yaml` 可自定义： - **初始姿态**: 修改 `robot.sitting_pose` - **PD 增益**: 修改 `control.pd_gains` - **仿真参数**: 修改 `simulation.timestep` 等 ## 物体物理属性 每种物体都有详细的物理属性： | 属性 | 说明 | 典型值 | |------|------|--------| | 质量 | 物体质量 | 0.01 ~ 5.0 kg | | 摩擦 | 摩擦系数 | 0.5 ~ 0.9 | | 弹性 | 恢复系数 | 0.1 ~ 0.5 | | 可抓取 | 是否可抓取 | true/false | ## 高级功能 ### 逆运动学 (IK) ```python from examples.example_ik import numerical_ik # 求解 IK target_pos = [0.6, -0.2, 0.85] # 目标位置 numerical_ik(controller, "right", target_pos) ``` ### 抓取检测 ```python from src.interaction import GraspDetector detector = GraspDetector(model, data) # 检测接触 contacts = detector.detect_contacts("right") # 检查稳定抓取 is_stable = detector.check_stable_grasp("right") # 获取抓取质量 quality = detector.get_grasp_quality("right") ``` ## 常见问题 ### Q: Wayland 下运行报错 `GLFWError: (65548) b'Wayland: The platform does not provide the window position'`？ A: 这是 Wayland 显示服务器的兼容性问题。已自动处理，无需手动操作。如仍有问题，可使用启动脚本： ```bash ./launch_sim.sh office ``` ### Q: 场景生成失败？ A: 确保有写入 `scenes/` 目录的权限，或尝试使用 `--force` 重新生成。 ### Q: 仿真运行卡顿？ A: 尝试降低仿真时间步长或关闭部分视觉效果。 ### Q: 如何添加自定义物体？ A: 在 `src/scene_generator/primitives.py` 中创建新的物体函数，然后在场景类中使用。 ## 依赖要求 - Python >= 3.8 - MuJoCo >= 3.0.0 - NumPy >= 1.20.0 - PyYAML >= 5.4.1 - OpenCV (可选，用于视觉传感器) ## 许可证 MIT License ## 参考 - [Unitree MuJoCo](https://github.com/unitreerobotics/unitree_mujoco) - [MuJoCo Documentation](https://mujoco.readthedocs.io/) - [Unitree G1](https://www.unitree.com/products/g1)