# fan-ziqi/robot_lab architecture

> Architecture diagram of the GitHub repository fan-ziqi/robot_lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fan-ziqi/robot_lab
- Repository: https://github.com/fan-ziqi/robot_lab

## Overview

##### Project type and purpose
- Project type: A **robotics‑focused RL extension library** (not a web app)
- Purpose: Provide Gym‑style learning environments for various robots (quadruped, humanoid, wheeled) that run inside IsaacSim (Omniverse) via IsaacLab extension.

- **Developer Shell** → invokes **CLI scripts**
- CLI scripts import **robot_lab extension** & **third‑party libraries**
- **robot_lab code** registers environments with **Gym**, instantiates **ManagerBasedRLEnv**
- **ManagerBasedRLEnv** ↔ exchanges state/action data with **IsaacSim**
- **RL Runner** (rsl_rl_ppo or AMP variants) ↔ **ManagerBasedRLEnv**
- **Simulation** reads USD assets / URDF conversion scripts produce USD assets
- **RL Runner** → writes **logs** and **checkpoints**
- **TensorBoard** reads logs
- **Docker Compose** orchestrates containers: simulation + services

##### Architectural patterns & design principles
- **Plugin‑based extension**: robot_lab loaded by IsaacLab’s extension manager
- **Modular environment registration**: one folder per robot/config, Gym registry
- **Separation of concerns**:
– CLI layer (scripts/)
– Core library (source/robot_lab)
– Third‑party algorithms (amp_utils, rsl_rl_amp)
– Data assets and config files
- **Configuration via code and TOML/YAML** (configclass decorator)

##### Detail level
- Don’t clutter with every single file—focus on logical groupings (scripts, core, assets, third‑party, deployment)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Entry
    DevShell["Developer Shell"]:::external

    subgraph "CLI / Entry Points"
        direction TB
        train_base["rsl_rl/base/train.py"]:::cli
        play_base["rsl_rl/base/play.py"]:::cli
        train_amp["rsl_rl/amp/train.py"]:::cli
        play_amp["rsl_rl/amp/play.py"]:::cli
        replay_amp["rsl_rl/amp/replay_amp_data.py"]:::cli
        convert_urdf["tools/convert_urdf.py"]:::cli
        list_envs["tools/list_envs.py"]:::cli
    end

    subgraph "Core Extension (robot_lab)"
        direction TB
        ext_toml["config/extension.toml"]:::core
        init_py["robot_lab/__init__.py"]:::core
        ui_example["ui_extension_example.py"]:::core
        env_velocity["tasks/locomotion/velocity"]:::core
        core_assets["robot_lab/assets"]:::core
    end

    subgraph "Simulation Engine"
        direction TB
        IsaacSim["NVIDIA IsaacSim (Omniverse)"]:::sim
        USDAssets["data/Robots/*.usd"]:::assets
        convert_urdf_v1["tools/convert_urdf_v1.py"]:::sim
    end

    subgraph "RL Algorithms & Third-Party Libraries"
        direction TB
        rsl_rl_amp["third_party/rsl_rl_amp"]:::rl
        amp_utils["third_party/amp_utils"]:::rl
    end

    subgraph "Deployment / Docker"
        direction TB
        env_base[".env.base"]:::deploy
        dockerfile["Dockerfile"]:::deploy
        docker_compose["docker-compose.yaml"]:::deploy
    end

    subgraph "Storage & Logging"
        direction TB
        logs_dir["logs/"]:::storage
        checkpoints["Checkpoints"]:::storage
        tensorboard["TensorBoard"]:::storage
    end

    %% Relationships
    DevShell -->|"invokes"| train_base
    DevShell --> play_base
    DevShell --> train_amp
    DevShell --> play_amp
    DevShell --> replay_amp
    DevShell --> convert_urdf
    DevShell --> list_envs

    train_base -->|"imports"| init_py
    play_base --> init_py
    train_amp --> init_py
    play_amp --> init_py
    replay_amp --> init_py

    init_py --> ext_toml
    init_py --> env_velocity
    init_py --> core_assets

    env_velocity -->|"registers with Gym"| ManagerEnv[ManagerBasedRLEnv]:::core
    ManagerEnv -->|"state↔action"| IsaacSim

    IsaacSim -->|"loads USD assets"| USDAssets
    convert_urdf_v1 --> USDAssets

    ManagerEnv --> rsl_rl_amp
    ManagerEnv --> amp_utils

    rsl_rl_amp --> checkpoints
    amp_utils --> checkpoints

    rsl_rl_amp --> logs_dir
    amp_utils --> logs_dir
    logs_dir --> tensorboard

    docker_compose --> IsaacSim
    docker_compose --> init_py
    docker_compose --> rsl_rl_amp

    %% Click Events
    click train_base "https://github.com/fan-ziqi/robot_lab/blob/main/scripts/rsl_rl/base/train.py"
    click play_base "https://github.com/fan-ziqi/robot_lab/blob/main/scripts/rsl_rl/base/play.py"
    click train_amp "https://github.com/fan-ziqi/robot_lab/blob/main/scripts/rsl_rl/amp/train.py"
    click play_amp "https://github.com/fan-ziqi/robot_lab/blob/main/scripts/rsl_rl/amp/play.py"
    click replay_amp "https://github.com/fan-ziqi/robot_lab/blob/main/scripts/rsl_rl/amp/replay_amp_data.py"
    click convert_urdf "https://github.com/fan-ziqi/robot_lab/blob/main/scripts/tools/convert_urdf.py"
    click list_envs "https://github.com/fan-ziqi/robot_lab/blob/main/scripts/tools/list_envs.py"
    click ext_toml "https://github.com/fan-ziqi/robot_lab/blob/main/source/robot_lab/config/extension.toml"
    click init_py "https://github.com/fan-ziqi/robot_lab/blob/main/source/robot_lab/robot_lab/__init__.py"
    click ui_example "https://github.com/fan-ziqi/robot_lab/blob/main/source/robot_lab/robot_lab/ui_extension_example.py"
    click env_velocity "https://github.com/fan-ziqi/robot_lab/tree/main/source/robot_lab/robot_lab/tasks/locomotion/velocity"
    click core_assets "https://github.com/fan-ziqi/robot_lab/tree/main/source/robot_lab/robot_lab/assets"
    click USDAssets "https://github.com/fan-ziqi/robot_lab/tree/main/source/robot_lab/data/Robots"
    click convert_urdf_v1 "https://github.com/fan-ziqi/robot_lab/blob/main/scripts/tools/convert_urdf_v1.py"
    click rsl_rl_amp "https://github.com/fan-ziqi/robot_lab/tree/main/source/robot_lab/robot_lab/third_party/rsl_rl_amp"
    click amp_utils "https://github.com/fan-ziqi/robot_lab/tree/main/source/robot_lab/robot_lab/third_party/amp_utils"
    click env_base "https://github.com/fan-ziqi/robot_lab/blob/main/docker/.env.base"
    click dockerfile "https://github.com/fan-ziqi/robot_lab/tree/main/docker/Dockerfile"
    click docker_compose "https://github.com/fan-ziqi/robot_lab/blob/main/docker/docker-compose.yaml"

    %% Styles
    classDef external fill:#ffffff,stroke:#000000,color:#000000;
    classDef cli fill:#d3d3d3,stroke:#333333,color:#000000;
    classDef core fill:#a8ddb5,stroke:#2b8cbe,color:#000000;
    classDef sim fill:#fdae61,stroke:#e6550d,color:#000000;
    classDef assets fill:#9e9ac8,stroke:#6a51a3,color:#000000;
    classDef rl fill:#3182bd,stroke:#08519c,color:#ffffff;
    classDef deploy fill:#969696,stroke:#333333,color:#ffffff;
    classDef storage fill:#bdbdbd,stroke:#636363,color:#000000;
```
