Metadata-Version: 2.4
Name: mujopy
Version: 0.0.1
Summary: Pythonic wrappers for MuJoCo models and Graph representations.
Author-email: Lukas Müller <lukasbmueller@gmail.com>
License-Expression: MIT
Keywords: mujoco,robotics,graph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mujoco>=3.3.6
Requires-Dist: numpy>=2.3.3
Requires-Dist: networkx>=3.5
Requires-Dist: pyyaml>=6.0.3
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# MuJoPy

## Table of Contents
- [Project Motivation](#project-motivation)
- [Installation](#installation)
- [File Descriptions](#file-descriptions)
- [Usage](#usage)
- [Licensing](#licensing)

## Project Motivation
MuJoPy provides pythonic access to MuJoCo models by wrapping the low-level structs of the model in dataclasses and by this deriving a navigable graph of bodies, joints and geoms. By this, downstream usage of robot models, e.g. feature extraction is faster without the need of custom parsing logic for the MuJoCo models.

With `RobotGraph()` the package also exposes an example of using the MuJoPy wrapper by providing a graph representation alongside of a feature matrix of the model.
## Installation
Install the package together with its MuJoCo dependency:

```bash
pip install mujopy
```

For development work inside this repository, install in editable mode with the testing extras:

```bash
pip install -e ".[test]"
```

## File Descriptions
- `mujopy/src/mujopy_model/`: Core wrappers (`Body`, `Joint`, `Geom`, `MuJoPyModel`) that expose MuJoCo fields as Python properties.
- `mujopy/src/robot_graph/`: Graph utilities built on top of NetworkX, including the `RobotGraph` and feature extraction pipeline.
- `tests/`: PyTest-based unit tests and fixtures covering the main APIs.
- `pyproject.toml`: Packaging metadata, dependencies, and tool configuration.

## Usage
```python
from pathlib import Path
from mujopy import MuJoPyModel, RobotGraph

# Load a MuJoCo XML and register the default property packs
model = MuJoPyModel(
    xml_path=str(Path("path/to/model.xml")),
    include_world_body=True,
    include_free_joints=False,
)
model.register_default_properties()

# Inspect bodies, joints, and geoms
trunk = model.body(0)
print(trunk.name, trunk.children_ids, trunk.primitive_geoms)

# Build a graph with feature vectors
graph = RobotGraph(
    xml_path=Path("path/to/model.xml"),
    feature_config_path=Path("path/to/feature_config.yml"),
)
print(graph.number_of_nodes(), graph.feature_matrix.shape)
```

Each wrapper exposes the underlying MuJoCo struct through the `mujoco_view` attribute—use it when you need direct access to raw MuJoCo fields:

```python
body_view = trunk.mujoco_view  # mujoco.MjDataView for the body
print(body_view.pos)
```

### Registering Custom Properties
Extend the core wrappers with your own read-only properties by registering callables on `MuJoPyModel`:

```python
from mujopy import MuJoPyModel

def _body_is_not_root(body: Body) -> bool:
        return int(np.asarray(body.mujoco_view.parentid).item()) != body.id

model = MuJoPyModel(xml_path="path/to/model.xml")
MuJoPyModel.register_body_property("_body_is_not_root", is_not_root)
model.register_default_properties()

print(model.body(0).is_not_root)
```

## Licensing
This project is distributed under the MIT License—see the license text in `pyproject.toml` for details.
