Metadata-Version: 2.4
Name: hex_driver_mujoco
Version: 0.1.1a5
Summary: HEXFELLOW Mujoco Driver
Author-email: Dong Zhaorui <dzr159@gmail.com>
Maintainer-email: jecjune <zejun.chen@hexfellow.com>, Dong Zhaorui <dzr159@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/hexfellow/hex_driver_mujoco
Project-URL: Repository, https://github.com/hexfellow/hex_driver_mujoco.git
Project-URL: Bug Tracker, https://github.com/hexfellow/hex_driver_mujoco/issues
Project-URL: Documentation, https://github.com/hexfellow/hex_driver_mujoco/wiki
Keywords: hex,driver,mujoco
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hex_util_runtime<0.1.0,>=0.0.0
Requires-Dist: hex_util_robot<0.1.0,>=0.0.0
Requires-Dist: hex_util_urdf<0.1.0,>=0.0.0
Requires-Dist: hex_util_msg<0.1.0,>=0.0.0
Requires-Dist: opencv-python>=4.10.0
Requires-Dist: mujoco>=3.3.0
Dynamic: license-file

<h1 align="center">HEXFELLOW MUJOCO DRIVER</h1>

<p align="center">
    <a href="https://github.com/hexfellow/hex_driver_mujoco/stargazers">
        <img src="https://img.shields.io/github/stars/hexfellow/hex_driver_mujoco?style=flat-square&logo=github" />
    </a>
    <a href="https://github.com/hexfellow/hex_driver_mujoco/forks">
        <img src="https://img.shields.io/github/forks/hexfellow/hex_driver_mujoco?style=flat-square&logo=github" />
    </a>
    <a href="https://doi.org/10.5281/zenodo.18309960">
        <img src="https://zenodo.org/badge/1088506315.svg" alt="DOI">
    </a>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="https://github.com/hexfellow/hex_driver_mujoco/issues">
        <img src="https://img.shields.io/github/issues/hexfellow/hex_driver_mujoco?style=flat-square&logo=github" />
    </a>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    <img src="https://img.shields.io/badge/python-≥3.10-blue?style=flat-square&logo=python" />
</p>

---

# 📖 Overview

## What is `hex_driver_mujoco`

`hex_driver_mujoco` is a Python library for MuJoCo robot simulation with a unified interface. It supports the following robot models:

| Model | Arm DOF | Cameras | Special Features |
|-------|---------|---------|-----------------|
| **E3 Desktop** | 6 per arm (dual‑arm) | 3 (head, left, right) | Dual‑arm manipulation, per‑camera type config |
| **Archer Y6** | 6 | 1 (head) | MIT / joint position / Cartesian pose commands |

The library runs each simulation in a background daemon thread, streams robot states and camera images via deque ring buffers, and exposes simple `get_*_state` / `get_*_color_img` / `get_*_depth_img` APIs. A callback variant is also available for each robot model.

## What problem it solves

- **Unified simulation interface**: Use the same API for different robot models (E3 Desktop, Archer Y6).
- **Background simulation**: Each simulation runs in its own daemon thread; the main thread only reads the latest state when needed.
- **Low‑latency sharing**: States and images are passed through deque buffers within the same process, avoiding serialization overhead.
- **Real‑time control**: Supports joint position, Cartesian pose, and MIT commands; command dict field names (`jnt_pos`, `jnt_vel`, `pose_pos`, `pose_quat`, `mit_kp`, `mit_kd`, …) are consistent across robot models.
- **Callback support**: Every robot model provides a `*Callback` class that accepts user‑defined callables for state and image streams.

## Target users

- Robotics researchers prototyping manipulation pipelines with MuJoCo simulations.
- Developers who need a simple, consistent way to interface with simulated robots.
- Anyone who wants to switch between different robot models without changing client code.

## Project structure

```
hex_driver_mujoco/
├── hex_driver_mujoco/
│   ├── __init__.py                 # Package exports (all public classes)
│   ├── base.py                     # HexMujocoBase (abstract) & HexMujocoBaseParams
│   ├── mujoco_archer_y6/
│   │   ├── __init__.py
│   │   └── mujoco.py              # Archer Y6 simulation + callback + params
│   │   └── model/                 # MuJoCo model files (scene.xml, robot.xml, STL assets)
│   └── mujoco_e3_desktop/
│       ├── __init__.py
│       └── mujoco.py              # E3 Desktop simulation + callback + params
│       └── model/                 # MuJoCo model files (scene.xml, robot.xml, STL assets)
├── example/
│   ├── archer_y6_example.py
│   ├── archer_y6_callback_example.py
│   ├── e3_desktop_example.py
│   └── e3_desktop_callback_example.py
└── docs/
    ├── api.md                     # Full API reference
    └── example.md                 # Usage walkthroughs
```

# 📦 Installation

## Requirements

- **Python** ≥ 3.10
- **OS**: `Linux` (macOS/Windows may work but are less tested)
- **Core dependencies**:
  - `hex_util_runtime` ≥ 0.0.0, < 0.1.0
  - `hex_util_robot` ≥ 0.0.0, < 0.1.0
  - `hex_util_urdf` ≥ 0.0.0, < 0.1.0
  - `hex_util_msg` ≥ 0.0.0, < 0.1.0
  - `opencv-python` ≥ 4.10.0
  - `mujoco` ≥ 3.3.0

## Install from PyPI

```bash
pip install hex_driver_mujoco
```

## Install from Source

For those who need examples, you can install the package from source code with examples.

**Note**: We use [**uv**](https://github.com/astral-sh/uv) to manage the Python environment. Please install it first.

1. Clone and install in editable mode. The `venv.sh` script expects [uv](https://github.com/astral-sh/uv).

    ```bash
    git clone https://github.com/hexfellow/hex_driver_mujoco.git
    cd hex_driver_mujoco
    ./venv.sh
    ```

   - `./venv.sh` — creates `.venv`, installs `hex_driver_mujoco` in editable mode.

2. Activate before running examples:

    ```bash
    source .venv/bin/activate
    ```

# 📑 API

See [**API**](docs/api.md) for details of all MuJoCo driver classes and parameters.

# 💡 Example

See [**Example**](docs/example.md) for usage examples of each robot model.

# 📚 Citation

If you want to cite this project in your work, you can use the following BibTeX entry:

```bibtex
@software{hex_driver_mujoco,
  author    = {Dong, Zhaorui and Chen, Zejun},
  title     = {Hex Driver MuJoCo: A MuJoCo-Based Robot Simulation Driver},
  year      = {2025},
  publisher = {Zenodo},
  version   = {v1.0.0},
  doi       = {10.5281/zenodo.18309960},
  url       = {https://doi.org/10.5281/zenodo.18309960}
}
```

# 📄 License

Apache License 2.0. See [LICENSE](LICENSE).

# 🌟 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=hexfellow/hex_driver_mujoco&type=Date)](https://star-history.com/#hexfellow/hex_driver_mujoco&Date)

# 👥 Contributors

<a href="https://github.com/hexfellow/hex_driver_mujoco/graphs/contributors">
    <img src="https://contrib.rocks/image?repo=hexfellow/hex_driver_mujoco" />
</a>
