# hello-robot/stretch_mujoco architecture

> Architecture diagram of the GitHub repository hello-robot/stretch_mujoco, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hello-robot/stretch_mujoco
- Repository: https://github.com/hello-robot/stretch_mujoco

## Overview

##### Project Type and Purpose
- This is a Python-based simulation library (“Stretch Mujoco”) for the Hello Robot Stretch robot, built on top of the MuJoCo physics engine.
- It provides an API (StretchMujocoSimulator) plus helper scripts (launch_sim, robocasa_gen) to start multi-process simulations, control robot joints/base, stream sensors (RGB, depth, lidar), and integrate with Robocasa environments and ROS2.

##### File Structure Analysis
- Top-level:
- config files (.flake8, pyproject.toml, mkdocs.yml, etc.) and docs/examples/tests.
- `stretch_mujoco/` package containing:
– config.py, utils.py
– datamodels/ & enums/ (data abstractions for joint and sensor status)
– models/ (XML world definitions + 3D asset files)
– mujoco_server*.py (different server processes: active, passive, sensor, camera manager, managed server)
– launch_sim.py (entrypoint that parses args, configures and spawns processes)
– stretch_mujoco_simulator.py (core API class wrapping mjModel/mjData, starting the sim, RPC to servers)
– robocasa_gen.py (kitchen scene model generator)
- Submodules:
- third_party/robocasa and third_party/robosuite (environment generators and macros).

##### README Insights
- Describes features: multi-process viewer vs headless mode, joint position/velocity control, camera + lidar streaming, Robocasa kitchen spawning, ROS2 bridge.
- Example usage: `uv run launch_sim`, Python API snippets, integration steps.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Examples["Example Scripts"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        API["StretchMujocoSimulator"]:::api
        Gen["Robocasa Scene Generator"]:::api
    end

    %% Utilities
    subgraph "Utilities"
        Config["Configuration Module"]:::utils
        Utils["Utility Functions"]:::utils
    end

    %% Data Abstractions
    subgraph "Data Abstractions"
        Datamodels["Datamodels"]:::data
        Enums["Enums"]:::data
    end

    %% Launch/Process Manager
    subgraph "Launch/Process Manager"
        Launch["launch_sim.py"]:::manager
        Manager["Multiprocessing Orchestrator"]:::manager
    end

    %% Simulation Backend
    subgraph "Simulation Backend"
        Active["Active Simulation Server"]:::server
        Passive["Passive (Read-Only) Server"]:::server
        Sensor["Sensor Manager Process"]:::server
        Camera["Camera Manager Process"]:::server
    end

    %% Asset Store
    subgraph "Asset Store"
        Assets["XML & 3D Models"]:::assets
    end

    %% Third-Party
    ThirdParty["Robocasa & Robosuite"]:::third

    %% Core
    Core["MuJoCo Core\n(mjModel/mjData)"]:::core

    %% External Integrations
    ROS2["ROS2 Bridge"]:::ext
    UV["uv Package Manager"]:::ext

    %% Relationships
    Examples -->|"imports / calls"| API
    API -->|"uses"| Config
    API -->|"uses"| Utils
    API -->|"loads datamodels / enums"| Datamodels
    API -->|"loads datamodels / enums"| Enums
    API -->|"calls scene gen"| Gen
    Gen -->|"writes XML"| Assets
    API -->|"spawns"| Launch
    Launch -->|"forks"| Manager
    Manager -->|"- - - IPC"| Active
    Manager -->|"- - - IPC"| Passive
    Manager -->|"- - - IPC"| Sensor
    Manager -->|"- - - IPC"| Camera
    Active -->|"calls into"| Core
    Passive -->|"calls into"| Core
    Sensor -->|"calls into"| Core
    Camera -->|"calls into"| Core
    Assets -->|"loaded by"| Active
    Assets -->|"loaded by"| Passive
    Assets -->|"loaded by"| Sensor
    Assets -->|"loaded by"| Camera
    Active -->|"- - - returns"| API
    Sensor -->|"- - - streams"| API
    Camera -->|"- - - streams"| API
    API -->|"returns data"| Examples
    ThirdParty -->|"provides macros to"| Gen
    API -->|"integration"| ROS2
    Launch -->|"run command via"| UV

    %% Click Events
    click Examples "https://github.com/hello-robot/stretch_mujoco/blob/main/examples/keyboard_teleop.py"
    click API "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/stretch_mujoco_simulator.py"
    click Gen "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/robocasa_gen.py"
    click Config "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/config.py"
    click Utils "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/utils.py"
    click Datamodels "https://github.com/hello-robot/stretch_mujoco/tree/main/stretch_mujoco/datamodels/"
    click Enums "https://github.com/hello-robot/stretch_mujoco/tree/main/stretch_mujoco/enums/"
    click Launch "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/launch_sim.py"
    click Manager "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/mujoco_server_managed.py"
    click Active "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/mujoco_server.py"
    click Passive "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/mujoco_server_passive.py"
    click Sensor "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/mujoco_server_sensor_manager.py"
    click Camera "https://github.com/hello-robot/stretch_mujoco/blob/main/stretch_mujoco/mujoco_server_camera_manager.py"
    click Assets "https://github.com/hello-robot/stretch_mujoco/tree/main/stretch_mujoco/models/"
    click ThirdParty "https://github.com/hello-robot/stretch_mujoco/tree/main/third_party/robocasa/"
    
    %% Styles
    classDef client fill:#ccffcc,stroke:#2f6627,color:#2f6627;
    classDef api fill:#cce5ff,stroke:#1f4e79,color:#1f4e79;
    classDef manager fill:#ffe5cc,stroke:#b36200,color:#b36200;
    classDef server fill:#fff2b2,stroke:#a18700,color:#a18700,stroke-dasharray: 5 5;
    classDef core fill:#ffcccc,stroke:#a10000,color:#a10000;
    classDef assets fill:#e6e6e6,stroke:#595959,color:#595959;
    classDef data fill:#f2e6ff,stroke:#663399,color:#663399;
    classDef utils fill:#e0e0e0,stroke:#505050,color:#505050;
    classDef third fill:#ccf2f2,stroke:#007373,color:#007373;
    classDef ext fill:#f0e6ff,stroke:#8033cc,color:#8033cc;
```
