# chengxuxin/extreme-parkour architecture

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

- Interactive diagram: https://gitdiagram.com/chengxuxin/extreme-parkour
- Repository: https://github.com/chengxuxin/extreme-parkour

## Overview

##### Project Type and Purpose
- This is a full-stack robotics Reinforcement Learning (RL) framework combining:
- A simulation/environment layer (legged_gym) built on NVIDIA Isaac Gym.
- An RL algorithm and training layer (rsl_rl) implemented in PyTorch.
- Command-line scripts for training, evaluation, playing back, saving JIT’d models, and visualization.
- The README confirms the goal: train and evaluate legged-robot parkour policies using Isaac Gym and PyTorch.

##### File Structure
- Top-level packages:
- legged_gym/… — defines environments, tasks, robot configurations, utilities, and simulation resources (URDFs, meshes, actuator nets).
- rsl_rl/… — implements RL algorithms (PPO), neural-network modules (actor-critic, recurrent, perception backbones), vectorized environment wrappers, runners (on-policy), and rollout storage.
- Resources and licensed assets (robots, terrains) live under legged_gym/resources.
- Installer logic (install.sh, setup.py files) and external-dependency manifests (requirements.txt).

##### README Insights
- Confirms two-stage training (base policy → distillation), CLI arguments, dependencies (Torch, Isaac Gym, numpy, wandb, Flask/web viewer).
- Usage patterns: scripts → initialize environment via legged_gym → interface to rsl_rl for learning updates → logs & artifacts.

##### Main Components & Their Relationships
a. Environment & Simulation Layer (legged_gym)
- Sub-components:
- Env configurations (a1, anymal, cassie, go1)
- BaseTask + LeggedRobot abstractions
- Terrain generator & utilities
- Webviewer server/client (Flask + webviewer.html)
- Dependencies: NVIDIA Isaac Gym binary (C++), URDF/meshes, actuator networks.
b. RL Core Layer (rsl_rl)
- Sub-components:
- Algorithms: PPO
- Neural modules: actor_critic, recurrent, depth_backbone, estimator
- VecEnv wrapper for parallel envs
- Runners: OnPolicyRunner orchestrates rollout collection and policy updates
- RolloutStorage for trajectories
c. CLI Scripts (legged_gym/scripts)
- Entry points for training, evaluation, playback, JIT exporting, visualization
- Parse CLI → instantiate rsl_rl runner + legged_gym env → loop
d. External Services & Tools
- Logging: wandb
- Model persistence: filesystem under legged_gym/logs
- Visualization: web viewer (Flask + browser), Isaac Gym GUI
e. Build & Installation
- install.sh + setup.py for editable installs
- requirements.txt lists Python packages

##### Architectural Patterns & Design Principles
- Modular separation into environment vs. learning algorithm.
- Runner pattern: decouples data collection (sim step) from policy update.
- Plugin-style env registration (task_registry) enabling new robots/terrains.
- Use of vectorized envs for throughput.
- JIT tracing for deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Scripts Layer
    subgraph "CLI Scripts"
        direction TB
        Train["train.py"]:::cli
        Evaluate["evaluate.py"]:::cli
        Play["play.py"]:::cli
        SaveJIT["save_jit.py"]:::cli
        Visualize["visualize.py"]:::cli
    end

    %% Simulation Engine Layer
    subgraph "Simulation Engine" 
        direction TB
        IsaacGym["Isaac Gym (Binary)"]:::external
        EnvA1["A1 Config"]:::sim
        EnvA1P["A1 Parkour Config"]:::sim
        AnymalB["Anymal B Config"]:::sim
        AnyC["Anymal C Config"]:::sim
        Cassie["Cassie Config"]:::sim
        Go1["Go1 Config"]:::sim
        BaseTask["BaseTask"]:::sim
        LeggedRobot["LeggedRobot"]:::sim
        LeggedRobotCfg["LeggedRobotConfig"]:::sim
        Terrain["Terrain Utils"]:::sim
        Helpers["Helper Utils"]:::sim
        Math["Math Utils"]:::sim
        TaskRegistry["Task Registry"]:::sim
        ResourcesRobots["Resources: Robots"]:::sim
        ResourcesAct["Actuator Nets"]:::sim
    end

    %% RL Engine Layer
    subgraph "RL Engine"
        direction TB
        VecEnv["VecEnv Wrapper"]:::rl
        Runner["OnPolicyRunner"]:::rl
        PPO["PPO Algorithm"]:::rl
        ActorCritic["ActorCritic Module"]:::rl
        ActorCriticRec["Recurrent Module"]:::rl
        DepthBB["Depth Backbone"]:::rl
        Estimator["Estimator Module"]:::rl
        RolloutStorage["RolloutStorage"]:::rl
        RLUtils["RL Utils"]:::rl
    end

    %% Logging & Storage Layer
    subgraph "Logging & Storage"
        direction TB
        Logger["Logger"]:::io
        StorageHelper["Storage Helper"]:::io
        Req["legged_gym requirements.txt"]:::io
    end

    %% Visualization Layer
    subgraph "Visualization"
        direction TB
        WebServer["WebViewer Server"]:::vis
        WebHTML["WebViewer HTML"]:::vis
        IsaacGUI["Isaac Gym GUI"]:::external
    end

    %% Build & Installation Layer
    subgraph "Build & Installation"
        direction TB
        Install["install.sh"]:::io
        Setup["setup.py"]:::io
        RootReq["requirements.txt"]:::io
    end

    %% Connections
    Train -->|"initialize"| IsaacGym
    Evaluate -->|"initialize"| IsaacGym
    Play -->|"initialize"| IsaacGym
    SaveJIT -->|"initialize"| IsaacGym
    Visualize -->|"initialize"| IsaacGym

    IsaacGym -->|"obs→"| Runner
    Runner -->|"action→"| IsaacGym
    Runner -->|"store→"| RolloutStorage
    RolloutStorage -->|"batch→"| PPO
    PPO -->|"update→"| Runner
    PPO -->|"checkpoint→"| StorageHelper

    Runner -->|"uses→"| VecEnv
    VecEnv -->|"wraps→"| IsaacGym

    PPO -->|"modules→"| ActorCritic
    PPO -->|"modules→"| ActorCriticRec
    PPO -->|"modules→"| DepthBB
    PPO -->|"modules→"| Estimator
    Runner -->|"utils→"| RLUtils

    Train -->|"log→"| Logger
    Evaluate -->|"log→"| Logger
    PPO -->|"metrics→"| Logger
    Logger -->|"save→"| StorageHelper

    Visualize -->|"http→"| WebServer
    WebServer -->|"serves→"| WebHTML
    WebHTML -->|"renders→"| IsaacGym

    Install --> Setup
    Setup --> RootReq
    Setup --> Req

    %% Click Events
    click Train "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/scripts/train.py"
    click Evaluate "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/scripts/evaluate.py"
    click Play "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/scripts/play.py"
    click SaveJIT "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/scripts/save_jit.py"
    click Visualize "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/scripts/visualize.py"

    click EnvA1 "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/envs/a1/a1_config.py"
    click EnvA1P "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/envs/a1/a1_parkour_config.py"
    click AnymalB "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/envs/anymal_b/anymal_b_config.py"
    click AnyC "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/envs/anymal_c/anymal.py"
    click Cassie "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/envs/cassie/cassie_config.py"
    click Go1 "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/envs/go1/go1_config.py"
    click BaseTask "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/envs/base/base_task.py"
    click LeggedRobot "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/envs/base/legged_robot.py"
    click LeggedRobotCfg "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/envs/base/legged_robot_config.py"
    click Terrain "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/utils/terrain.py"
    click Helpers "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/utils/helpers.py"
    click Math "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/utils/math.py"
    click TaskRegistry "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/utils/task_registry.py"
    click ResourcesRobots "https://github.com/chengxuxin/extreme-parkour/tree/main/legged_gym/resources/robots/"
    click ResourcesAct "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/resources/actuator_nets/anydrive_v3_lstm.pt"

    click PPO "https://github.com/chengxuxin/extreme-parkour/blob/main/rsl_rl/rsl_rl/algorithms/ppo.py"
    click ActorCritic "https://github.com/chengxuxin/extreme-parkour/blob/main/rsl_rl/rsl_rl/modules/actor_critic.py"
    click ActorCriticRec "https://github.com/chengxuxin/extreme-parkour/blob/main/rsl_rl/rsl_rl/modules/actor_critic_recurrent.py"
    click DepthBB "https://github.com/chengxuxin/extreme-parkour/blob/main/rsl_rl/rsl_rl/modules/depth_backbone.py"
    click Estimator "https://github.com/chengxuxin/extreme-parkour/blob/main/rsl_rl/rsl_rl/modules/estimator.py"
    click VecEnv "https://github.com/chengxuxin/extreme-parkour/blob/main/rsl_rl/rsl_rl/env/vec_env.py"
    click Runner "https://github.com/chengxuxin/extreme-parkour/blob/main/rsl_rl/rsl_rl/runners/on_policy_runner.py"
    click RolloutStorage "https://github.com/chengxuxin/extreme-parkour/blob/main/rsl_rl/rsl_rl/storage/rollout_storage.py"
    click RLUtils "https://github.com/chengxuxin/extreme-parkour/blob/main/rsl_rl/rsl_rl/utils/utils.py"

    click Logger "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/utils/logger.py"
    click StorageHelper "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/utils/storage.py"
    click Req "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/requirements.txt"

    click WebServer "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/utils/webviewer.py"
    click WebHTML "https://github.com/chengxuxin/extreme-parkour/blob/main/legged_gym/legged_gym/utils/webviewer.html"

    click Install "https://github.com/chengxuxin/extreme-parkour/blob/main/install.sh"
    click Setup "https://github.com/chengxuxin/extreme-parkour/blob/main/setup.py"
    click RootReq "https://github.com/chengxuxin/extreme-parkour/blob/main/requirements.txt"

    %% Styles
    classDef sim fill:#D0E8FF,stroke:#0066CC,stroke-width:1px
    classDef rl fill:#D0FFD8,stroke:#009933,stroke-width:1px
    classDef io fill:#FFE6B3,stroke:#FF9900,stroke-width:1px
    classDef vis fill:#E8D0FF,stroke:#6600CC,stroke-width:1px
    classDef cli fill:#B3F0FF,stroke:#00CCCC,stroke-width:1px
    classDef external fill:#F2F2F2,stroke:#666666,stroke-dasharray: 2 2,stroke-width:1px
```
