Metadata-Version: 2.4
Name: hex_driver_mujoco
Version: 0.0.1a20
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: 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.18309954">
        <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>
</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 E3 Desktop (dual‑arm) and Archer Y6 (6‑DOF arm) robot models. The library runs each simulation in a separate process, streams robot states and camera images via shared‑memory ring buffers, and provides simple `get_*_motor`/`get_*_color_img`/`get_*_depth_img` APIs.

## 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 process; the main thread only reads the latest state when needed.
- **Low‑latency sharing**: States and images are passed through shared‑memory ring buffers, avoiding serialization overhead.
- **Real‑time control**: Supports joint position, Cartesian pose, and MIT commands; command dict field names (`pos_tar`, `vel_tar`, `quat_tar`, …) match [`hex_driver_robot`](https://github.com/hexfellow/hex_driver_robot) Archer/Firefly Y6 drivers.

## 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.

# 📦 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
  - `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_zmq_servers,
  author    = {Dong, Zhaorui and Chen, Zejun},
  title     = {Hex ZMQ Servers: A ZeroMQ-Based Embodied AI Communication Framework},
  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>
