# joonhyung-lee/mujoco-robotics-usage architecture

> Architecture diagram of the GitHub repository joonhyung-lee/mujoco-robotics-usage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joonhyung-lee/mujoco-robotics-usage
- Repository: https://github.com/joonhyung-lee/mujoco-robotics-usage

## Overview

##### Project type and purpose
- This is an open-source robotics simulation/demo toolkit built on DeepMind’s MuJoCo engine.
- It provides hands-on Jupyter notebook demos for manipulator kinematics, trajectory planning, mobile planning, mobile-manipulator control, point-cloud processing and miscellaneous utilities.

##### File structure
- Top‐level “asset” directory: contains all MJCF/URDF robot and scene definitions (Husky, UR5e, Panda, realworld objects, Snapbot, etc.) plus meshes.
- “code” directory subdivided by domain:
- manipulator (inverse kinematics & trajectory planning demos)
- mobile (Husky motion planning)
- mobile_manipulator (Husky + UR5e whole-body demos)
- point-cloud (projection, voxelization demos)
- miscellaneous (viewers, segmentation demos)
- “utils” directory: parser and helper functions to load MJCF/URDF, wrap MuJoCo API, common math routines.
- README provides high-level description of algorithms, external dependencies (MuJoCo, mujoco-python-viewer, UCN, SAM).

##### README for additional insights
- Describes supported algorithms (IK variants, trajectory planners, global/local planners, point-cloud methods, segmentation integration).
- Lists external libraries (DeepMind MuJoCo, YAMT, MuJoCo-menagerie, UCN, SAM).

##### Elements
- Notebook → Demo Module → Utils → Engine → Assets (load)
- Engine → Viewer (render)
- Engine → Demo Module (state readout)
- Demo Module → External Libraries (segmentation)
- Red clouds for External Libraries

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        NB1["Manipulator Notebooks"]:::codeModule
        NB2["Mobile Notebooks"]:::codeModule
        NB3["Mobile-Manipulator Notebooks"]:::codeModule
        NB4["Point-Cloud Notebooks"]:::codeModule
        NB5["Miscellaneous Notebooks"]:::codeModule
        NB6["demo_multi_viewer.py"]:::codeModule
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        DM1["Manipulator Module"]:::codeModule
        DM2["Mobile Module"]:::codeModule
        DM3["Mobile-Manipulator Module"]:::codeModule
        DM4["Point-Cloud Module"]:::codeModule
        DM5["Miscellaneous Module"]:::codeModule
        UT1["mujoco_parser.py"]:::utils
        UT2["util.py"]:::utils
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        ENG["MuJoCo Engine & Viewer"]:::engine
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ASSET["Asset Repository"]:::assets
        EXT1["UCN"]:::external
        EXT2["SAM/OWL-ViT"]:::external
        EXT3["YAMT & mujoco_menagerie"]:::external
    end

    %% Connections
    NB1 -->|"imports calls"| DM1
    NB2 -->|"imports calls"| DM2
    NB3 -->|"imports calls"| DM3
    NB4 -->|"imports calls"| DM4
    NB5 -->|"imports calls"| DM5
    NB6 -->|"viewer script"| DM5

    DM1 -->|"uses"| UT1
    DM2 -->|"uses"| UT1
    DM3 -->|"uses"| UT1
    DM4 -->|"uses"| UT1
    DM5 -->|"uses"| UT1

    DM1 -->|"uses"| UT2
    DM2 -->|"uses"| UT2
    DM3 -->|"uses"| UT2
    DM4 -->|"uses"| UT2
    DM5 -->|"uses"| UT2

    UT1 -->|"load XML/URDF assets"| ENG
    UT2 -->|"math routines & wrappers"| ENG

    ENG -->|"load scene definitions"| ASSET
    ENG -->|"simulation loop outputs state"| DM1
    ENG -->|"simulation loop outputs state"| DM2
    ENG -->|"simulation loop outputs state"| DM3
    ENG -->|"simulation loop outputs state"| DM4
    ENG -->|"simulation loop outputs state"| DM5

    ENG -->|"render frames"| ENG

    DM5 -.->|"optional segmentation"| EXT1
    DM5 -.->|"optional segmentation"| EXT2
    DM5 -.->|"config & support"| EXT3

    %% Click Events
    click NB1 "https://github.com/joonhyung-lee/mujoco-robotics-usage/blob/main/code/manipulator/*.ipynb"
    click NB2 "https://github.com/joonhyung-lee/mujoco-robotics-usage/blob/main/code/mobile/*.ipynb"
    click NB3 "https://github.com/joonhyung-lee/mujoco-robotics-usage/blob/main/code/mobile_manipulator/*.ipynb"
    click NB4 "https://github.com/joonhyung-lee/mujoco-robotics-usage/blob/main/code/point-cloud/*.ipynb"
    click NB5 "https://github.com/joonhyung-lee/mujoco-robotics-usage/blob/main/code/miscellaneous/*.ipynb"
    click NB6 "https://github.com/joonhyung-lee/mujoco-robotics-usage/blob/main/code/miscellaneous/demo_multi_viewer.py"

    click DM1 "https://github.com/joonhyung-lee/mujoco-robotics-usage/tree/main/code/manipulator/"
    click DM2 "https://github.com/joonhyung-lee/mujoco-robotics-usage/tree/main/code/mobile/"
    click DM3 "https://github.com/joonhyung-lee/mujoco-robotics-usage/tree/main/code/mobile_manipulator/"
    click DM4 "https://github.com/joonhyung-lee/mujoco-robotics-usage/tree/main/code/point-cloud/"
    click DM5 "https://github.com/joonhyung-lee/mujoco-robotics-usage/tree/main/code/miscellaneous/"

    click UT1 "https://github.com/joonhyung-lee/mujoco-robotics-usage/blob/main/utils/mujoco_parser.py"
    click UT2 "https://github.com/joonhyung-lee/mujoco-robotics-usage/blob/main/utils/util.py"

    click ASSET "https://github.com/joonhyung-lee/mujoco-robotics-usage/tree/main/asset/"

    click EXT2 "https://github.com/joonhyung-lee/mujoco-robotics-usage/blob/main/code/miscellaneous/demo_sam.ipynb"

    %% Styles
    classDef codeModule fill:#D6EAF8,stroke:#3498DB,color:#154360
    classDef utils fill:#D6EAF8,stroke:#1F618D,color:#1B2631
    classDef engine fill:#FAD7A0,stroke:#D68910,color:#784212
    classDef assets fill:#ABEBC6,stroke:#27AE60,color:#1D8348
    classDef external fill:#F5B7B1,stroke:#C0392B,color:#641E16
```
