Metadata-Version: 2.3
Name: mujoco-scene-editor
Version: 0.1.2
Summary: Lightweight scene editor for mujoco
Keywords: robotics,research,simulation
Author: Markus Grotz
Author-email: Markus Grotz <scene-editor@robits.ai>
License: MIT License
         
         Copyright (c) 2025 Markus Grotz
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 4 - Beta
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 :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.13,<2.0.0
Requires-Dist: rich-click>=1
Requires-Dist: click-prompt>=0.6.0
Requires-Dist: robits[sim]>=0.8.1
Requires-Dist: mujoco>=3.3,<4.0
Requires-Dist: robot-descriptions>=1.14.0,<2.0
Requires-Dist: dm-control>=1.0.30,<2.0
Requires-Dist: cachier>=4.1.0
Requires-Dist: objaverse>=0.1.7
Requires-Dist: viser>=1.0.17
Requires-Dist: mink>=0.0.13
Requires-Dist: qpsolvers[quadprog]>=0.1.13
Requires-Dist: openai>=2.15.0
Requires-Dist: trimesh>=4.11.1
Requires-Dist: sphinx ; extra == 'dev'
Requires-Dist: toml ; extra == 'dev'
Requires-Dist: myst-parser ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Python: >=3.10, <3.13
Project-URL: homepage, https://github.com/markusgrotz/mujoco-scene-editor
Project-URL: repository, https://github.com/markusgrotz/mujoco-scene-editor
Project-URL: documentation, https://github.com/markusgrotz/mujoco-scene-editor
Project-URL: tracker, https://github.com/markusgrotz/mujoco-scene-editor/issues
Provides-Extra: dev
Description-Content-Type: text/markdown

[![Supported Python Versions](https://img.shields.io/pypi/pyversions/mujoco-scene-editor)](https://pypi.org/project/mujoco-scene-editor/)
[![PyPI version](https://img.shields.io/pypi/v/mujoco-scene-editor)](https://pypi.org/project/mujoco-scene-editor/)
[![License](https://img.shields.io/pypi/l/mujoco-scene-editor)](https://github.com/markusgrotz/mujoco-scene-editor/blob/main/LICENSE.md)
[![Code style](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)



# Scene Editor for MuJoCo

<p align="center">
   <img src="https://raw.githubusercontent.com/markusgrotz/mujoco-scene-editor/main/assets/logo.png" width="420" />
</p>

Lightweight, interactive scene editor for [MuJoCo 3.x.](https://mujoco.org/) Create or edit scenes in
your browser to place shapes, import meshes, add robots, and edit elements interactively.


## Quickstart

```bash
pip install mujoco-scene-editor

# Start a fresh, empty scene
mjcreate

# Load from MJCF XML or a blueprint JSON
mjedit path/to/scene.xml
```


## Installation

Install the package on [PyPi](https://pypi.org/project/mujoco-scene-editor/) with

```bash
pip install mujoco-scene-editor
```
This installs necessary dependencies and exposes console scripts.
The following entry points are available and they are also accessible as `scene-editor` subcommands:
 - `mjcreate`: Create an empty scene (opens the web browser)
 - `mjedit`: Edit an existing scene (opens the web browser)
 - `mjprompt`: Generate a scene from a prompt and save it as a MuJoCo XML

From a local checkout:

```bash
pip install -e .
# or with dev tools
pip install -e '.[dev]'
```

To run with uv, use

```bash
# Run the installed console script via uv
uv run scene-editor --help
uv run scene-editor new
```

When the server starts, it prints the URL and opens your browser. Quit with Ctrl+C or the "Quit server" button.

## Examples

Use the provided chemistry lab MJCF as a starting point:

```bash
# With pip-installed package
mjedit examples/prompt/scene_chemistry_lab.xml

# With uv (no install)
uv run mjedit examples/prompt/scene_chemistry_lab.xml
```

Then:
- Use "Add Box/Sphere/Cylinder" to place primitive geoms.
- Use "Add Asset" to insert a local mesh from your file system.
- Drag the gizmo to change pose; use “Export” to write MJCF/JSON.

Robot models are detected using a heuristic. See the section below on how to configure the editor to use different robot models.


## Prompting / Scene Generation Examples

You can conveniently generate a MuJoCo scene from a natural-language prompt (requires an OpenAI API key):

```bash
# Set this to your API key
export OPENAI_API_KEY=...
# Generate a scene from a prompt string
mjprompt

# Edit the generated scene. 
mjedit examples/prompt/scene_coffee_shop.xml
```
Loading a generated scene might not work out of the box in all cases. Generated scenes can have inconsistencies in geometry, but can be easily edited.

### Examples

Below are some generated example scenes. More examples are available in the `examples/prompt` folder.
 
 <table>
   <tr>
     <td align="center">
      <a href="https://raw.githubusercontent.com/markusgrotz/mujoco-scene-editor/main/assets/prompt/scene_living_room_large.png">
        <img src="https://raw.githubusercontent.com/markusgrotz/mujoco-scene-editor/main/assets/prompt/scene_living_room_small.png" alt="Living Room" width="420" />
      </a><br/><sub>Living Room</sub>
     </td>
     <td align="center">
      <a href="https://raw.githubusercontent.com/markusgrotz/mujoco-scene-editor/main/assets/prompt/scene_chess_large.png">
        <img src="https://raw.githubusercontent.com/markusgrotz/mujoco-scene-editor/main/assets/prompt/scene_chess_small.png" alt="Chess Table" width="420" />
      </a><br/><sub>Chess Table</sub>
     </td>
   </tr>
   <tr>
     <td align="center">
      <a href="https://raw.githubusercontent.com/markusgrotz/mujoco-scene-editor/main/assets/prompt/scene_playground_large.png">
        <img src="https://raw.githubusercontent.com/markusgrotz/mujoco-scene-editor/main/assets/prompt/scene_playground_small.png" alt="Playground" width="420" />
      </a><br/><sub>Playground</sub>
     </td>
     <td align="center">
      <a href="https://raw.githubusercontent.com/markusgrotz/mujoco-scene-editor/main/assets/prompt/scene_chemistry_lab_large.png">
        <img src="https://raw.githubusercontent.com/markusgrotz/mujoco-scene-editor/main/assets/prompt/scene_chemistry_lab_small.png" alt="Chemistry Lab" width="420" />
      </a><br/><sub>Chemistry Lab</sub>
     </td>
   </tr>
 </table>


## Working with different robots or cameras

Robot models must be specified with a JSON configuration.
To work with additional robot models, set the `ROBITS_CONFIG_DIR` environment variable to another config folder. See the [RoBits documentation](https://robits.ai/en/latest/configuration.html) for more details.

```bash
  export ROBITS_CONFIG_DIR=$HOME/code/robits/robits_config/additional_config_sim
  mjedit examples/prompt/scene_coffee_shop.xml
```


## Limitations

- Importing MuJoCo XML files may alter the internal structure, and some tags are discarded.
  - Joints/actuators are discarded if they are not part of a robot description.
  - Additional geom tags, including friction, conaffinity, or contype are not yet supported and discarded.
  - Light/option/compiler elements are not implemented yet.

If you are looking for a robot editor for MuJoCo that supports all the assets please checkout Robola web
  
- Not all MuJoCo robot descriptions have an equivalent URDF representation.

## Links

- Repository: https://github.com/markusgrotz/mujoco-scene-editor
- Issues: https://github.com/markusgrotz/mujoco-scene-editor/issues
