# hellod035/leggedlab architecture

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

- Interactive diagram: https://gitdiagram.com/hellod035/leggedlab
- Repository: https://github.com/hellod035/leggedlab

## Overview

##### Project type and purpose
- LeggedLab is a robotics simulation & reinforcement-learning framework built as an IsaacLab extension.
- It provides:
- Environment definitions for legged robots (Unitree G1, H1; FFT-AI gr2)
- Asset management (USD files, configurations)
- MDP logic (rewards, observations)
- CLI scripts for train/play workflows
- Integration with IsaacSim/IsaacLab and RSL_RL for multi-GPU/node RL.

##### File structure
Top-level modules:
- legged_lab/assets → USD robot assets & configs
- legged_lab/envs → Env definitions & configs per robot
- legged_lab/mdp → Reward functions
- legged_lab/terrains → RayCaster & terrain generator configs
- legged_lab/utils → CLI arg parsing, scene setup, keyboard, task registry
- legged_lab/scripts → train.py & play.py entrypoints
External config at root: setup.py, flake8, pre-commit, LICENSE, README

##### README for insights
- This is an extension to IsaacLab, requiring IsaacSim 4.5 / IsaacLab 2.1.
- Uses RSL_RL for RL back‐end; supports TensorBoard logging, multi-GPU/node.
- Workflows:
- `train.py` to launch RL training (gym-style envs + IsaacSim headless)

##### Main components & their relationships
a. User Interface
- CLI scripts (`train.py` / `play.py`)
- Accept `--task`, `--num_envs`, `--logger` flags
b. LeggedLab Extension (Python package)
- Task registry loads the selected env
- Env factories in legged_lab/envs create Gym-style envs
- MDP (legged_lab/mdp) defines reward & observation logic
- Terrain module (legged_lab/terrains) generates/loads terrain
- Asset module (legged_lab/assets) loads USD robot models & configs
- Utils set up the IsaacSim scene, configure physics, sensors
c. IsaacSim + IsaacLab Core
- Simulation engine that runs physics, rendering, sensor pipelines
- Exposes Python API (omni.isaac) to load USD, step sim
d. Reinforcement‐Learning Back-end
- RSL_RL orchestrates policy optimization (PPO/DPO)
- Handles multi-GPU / multi-node distribution
- Exchanges action/observation tensors with the env
e. Logging & Visualization
- TensorBoard, optionally console output
f. (Optionally) Real-robot deploy code (separate repo)
- Uses same robot USD → real robot mapping

##### Architectural patterns & design principles
- Modular, plugin‐style IsaacLab extension
- Factory pattern for env creation (legged_lab/envs)
- Config-driven asset & env setup (YAML + USD)
- Gym API compatibility → decouples env from RL back-end
- Separation of concerns: assets | env logic | MDP | RL training | CLI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Scripts
    subgraph "CLI Scripts"
        TS["train.py"]:::scripts
        PS["play.py"]:::scripts
    end

    %% LeggedLab Package
    subgraph "LeggedLab Package"
        subgraph "utils"
            UA["cli_args.py"]:::utils
            TR["task_registry.py"]:::utils
            KB["keyboard.py"]:::utils
            SU["scene.py"]:::utils
        end
        subgraph "envs"
            BE["base_env.py"]:::envs
            G1["g1_config.py"]:::envs
            GR2["gr2_config.py"]:::envs
            H1["h1_config.py"]:::envs
        end
        subgraph "mdp"
            MDP["rewards.py"]:::mdp
        end
        subgraph "terrains"
            TC["ray_caster.py"]:::terrains
            TCFG["terrain_generator_cfg.py"]:::terrains
        end
        subgraph "assets"
            FFT["fftai.py"]:::assets
            UT["unitree.py"]:::assets
        end
    end

    %% External Systems
    subgraph "External Systems"
        RL["RSL_RL (MPI/torch.distributed)"]:::external
        ISIM["IsaacSim Engine"]:::external
        TB["TensorBoard"]:::external
    end

    %% Flow Connections
    TS -->|"invokes"| TR
    PS -->|"invokes"| TR
    TR -->|"loads env"| BE
    TR -->|"loads env"| G1
    TR -->|"loads env"| GR2
    TR -->|"loads env"| H1
    BE -->|"defines MDP"| MDP
    G1 -->|"defines MDP"| MDP
    GR2 -->|"defines MDP"| MDP
    H1 -->|"defines MDP"| MDP
    BE -->|"loads assets"| FFT
    G1 -->|"loads assets"| UT
    GR2 -->|"loads assets"| FFT
    H1 -->|"loads assets"| UT
    BE -->|"generates terrain"| TC
    G1 -->|"generates terrain"| TC
    GR2 -->|"generates terrain"| TC
    H1 -->|"generates terrain"| TC
    FFT -->|"USD models"| ISIM
    UT -->|"USD models"| ISIM
    TC -->|"terrain data"| ISIM
    SU -->|"scene setup"| ISIM
    RL -->|"step Env"| BE
    RL -->|"step Env"| G1
    RL -->|"step Env"| GR2
    RL -->|"step Env"| H1
    BE -->|"obs/reward"| RL
    G1 -->|"obs/reward"| RL
    GR2 -->|"obs/reward"| RL
    H1 -->|"obs/reward"| RL
    RL -->|"logs"| TB

    %% Click Events
    click TS "https://github.com/hellod035/leggedlab/blob/main/legged_lab/scripts/train.py"
    click PS "https://github.com/hellod035/leggedlab/blob/main/legged_lab/scripts/play.py"
    click FFT "https://github.com/hellod035/leggedlab/blob/main/legged_lab/assets/fftai/fftai.py"
    click UT "https://github.com/hellod035/leggedlab/blob/main/legged_lab/assets/unitree/unitree.py"
    click BE "https://github.com/hellod035/leggedlab/blob/main/legged_lab/envs/base/base_env.py"
    click G1 "https://github.com/hellod035/leggedlab/blob/main/legged_lab/envs/g1/g1_config.py"
    click GR2 "https://github.com/hellod035/leggedlab/blob/main/legged_lab/envs/gr2/gr2_config.py"
    click H1 "https://github.com/hellod035/leggedlab/blob/main/legged_lab/envs/h1/h1_config.py"
    click MDP "https://github.com/hellod035/leggedlab/blob/main/legged_lab/mdp/rewards.py"
    click TC "https://github.com/hellod035/leggedlab/blob/main/legged_lab/terrains/ray_caster.py"
    click TCFG "https://github.com/hellod035/leggedlab/blob/main/legged_lab/terrains/terrain_generator_cfg.py"
    click UA "https://github.com/hellod035/leggedlab/blob/main/legged_lab/utils/cli_args.py"
    click TR "https://github.com/hellod035/leggedlab/blob/main/legged_lab/utils/task_registry.py"
    click KB "https://github.com/hellod035/leggedlab/blob/main/legged_lab/utils/keyboard.py"
    click SU "https://github.com/hellod035/leggedlab/blob/main/legged_lab/utils/env_utils/scene.py"

    %% Styles
    classDef scripts fill:#f9f,stroke:#333,stroke-width:1px;
    classDef utils fill:#ff9,stroke:#333,stroke-width:1px;
    classDef envs fill:#9f9,stroke:#333,stroke-width:1px;
    classDef mdp fill:#9cf,stroke:#333,stroke-width:1px;
    classDef terrains fill:#fc9,stroke:#333,stroke-width:1px;
    classDef assets fill:#cdf,stroke:#333,stroke-width:1px;
    classDef external fill:#eee,stroke-dasharray: 5 5,stroke:#666,stroke-width:1px;
```
