Getting Started

This guide will help you install and run DexRobot MuJoCo, and walk you through basic usage patterns.

Prerequisites

Required Software

• Python >= 3.8

• MuJoCo >= 3.0.0

• ROS or ROS2 (any distribution)

Python Dependencies

• mujoco >= 3.0.0

• numpy

• pyyaml

• loguru

• scipy

• flask (for VR visualization)

• opencv-python

• pandas

• ros_compat

Installation

1. Set up your ROS environment (ROS1 or ROS2)

2. Install Python dependencies:

   pip install mujoco numpy pyyaml loguru scipy flask opencv-python pandas
   pip install git+https://gitee.com/dexrobot/ros_compat.git
   

3. Install DexRobot MuJoCo:

   pip install git+https://gitee.com/dexrobot/dexrobot_mujoco.git
   

   Or for development:

   git clone https://gitee.com/dexrobot/dexrobot_mujoco.git
   cd dexrobot_mujoco
   pip install -e .[dev]
   

Quick Start

Basic Hand Control

1. Launch the simulation with a simplified hand model:

   python nodes/dexrobot_mujoco_ros.py dexrobot_mujoco/models/dexhand021_right_simplified.xml
   

2. In another terminal, send joint commands:

   # Using ROS2
   ros2 topic pub /joint_commands sensor_msgs/msg/JointState \
       "{name: ['r_f_joint1_1'], position: [0.5]}"
   
   # Using ROS1
   rostopic pub /joint_commands sensor_msgs/JointState \
       "{name: ['r_f_joint1_1'], position: [0.5]}"
   

Simulating a Scene

1. Launch a scene with configuration:

   python nodes/dexrobot_mujoco_ros.py dexrobot_mujoco/scenes/box.xml \
       --config config/scene_default.yaml
   

2. Save the simulation:

   python nodes/dexrobot_mujoco_ros.py dexrobot_mujoco/scenes/box.xml \
       --config config/scene_default.yaml \
       --output-formats ros csv mp4 \
       --output-csv-path data.csv \
       --output-mp4-path video.mp4
   

Key Command-line Options

The ROS node supports various command-line options:

Required Arguments:
  model_path             Path to the Mujoco model XML file

Optional Arguments:
  --config-yaml         Path to the YAML configuration file
  --replay-csv          Path to CSV file for replay
  --hand-pose-topic     Topic name for hand pose control
  --position-magnifiers Position magnifiers for hand pose control [default: 2.5,2.0,0.8]
  --output-formats      Output formats (ros/csv/mp4) [default: ros]
  --output-csv-path     Path for CSV output
  --output-mp4-path     Path for MP4 output
  --output-bag-path     Path for ROS bag output
  --enable-vr           Enable VR visualization
  --renderer-dimension  Renderer dimensions as width,height (e.g., 640,480)
  --seed               Random seed [default: 0]

Basic Configuration

Scene configuration example (config/scene_default.yaml):

# Camera settings
camera:
  azimuth: 0
  distance: 1.2
  elevation: -20
  lookat: [0.0, 0.0, 1.2]

# Track these joints
tracked_joints:
- [ARTx, ARTy, ARTz]
- [r_f_joint1_1, r_f_joint1_2, r_f_joint1_3, r_f_joint1_4]
# ... more joints ...

# Track these bodies
tracked_bodies:
- [right_hand_base]
- [r_f_link1_1, r_f_link1_2, r_f_link1_3, r_f_link1_4]
# ... more bodies ...

Next Steps

After getting familiar with basic usage, you might want to:

• Learn about hand model configuration

• Create custom simulation scenes

• Explore advanced ROS integration

• Check the API reference for programmatic control

Common Issues

ModuleNotFoundError: No module named ‘mujoco’

Make sure MuJoCo is properly installed:

pip uninstall mujoco
pip install mujoco>=3.0.0

ROS messages not being received/sent

Check if your ROS environment is properly sourced and ROS_DOMAIN_ID is set correctly.

Low simulation performance

Consider using the simplified collision model:

python nodes/dexrobot_mujoco_ros.py \
    dexrobot_mujoco/models/dexhand021_right_simplified.xml