# f1tenth/f1tenth_gym architecture

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

- Interactive diagram: https://gitdiagram.com/f1tenth/f1tenth_gym
- Repository: https://github.com/f1tenth/f1tenth_gym

## Overview

##### Project type and purpose
- This is a full-featured open-source simulation library packaged as an OpenAI Gym environment for the F1TENTH autonomous racing platform.
- It provides a configurable 2D/3D race-car simulator (physics, collision, sensor, rendering) behind a Gym-compatible API so RL agents can train and test control policies.

##### File structure
- Top-level:
- gym/f110_gym: the core Python package
- examples/: usage scripts (waypoint_follow.py, config files)
- docs/: Sphinx/Doxygen documentation, including API reference under docs/api
- Dockerfile, CI workflows, setup.py, requirements
- Inside gym/f110_gym/envs:
- base_classes.py – abstract Env, RaceCar, Simulator
- collision_models.py – collision testing utilities
- dynamic_models.py – vehicle dynamics definitions
- laser_models.py – LiDAR scan simulator
- f110_env.py – main Env implementation
- f110_env_backup.py – legacy Env
- rendering.py – Pyglet/OpenGL renderer
- maps/: environment map definitions (yaml, pgm)
- unittest folder: end-to-end and unit tests for each subsystem.

##### README for additional insights
- Confirms it’s a Gym environment (pip install-e .), provides a Docker setup for GPU rendering, and points to docs.
- Usage pattern: user does `gym.make("f110_gym")`, steps through env, receives observations (LiDAR, pose), applies actions (steering, throttle).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Interfaces
    subgraph "External Interfaces"
        direction TB
        RLAgent["User RL Agent"]:::external
        DockerGPU["Docker GPU Support"]:::external
        CIPipeline["CI Pipeline"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        F110Env["F110Env (Gym Wrapper)"]:::api
        F110EnvBackup["F110Env_Backup (Legacy)"]:::api
    end

    %% Simulation Core
    subgraph "Simulation Core"
        direction TB
        BaseClasses["BaseClasses (Simulator & RaceCar)"]:::core
        DynamicModels["DynamicModels"]:::core
        CollisionModels["CollisionModels"]:::core
        LaserModels["LaserModels"]:::core
        MapLoader["Map Loader"]:::core
    end

    %% Visualization
    subgraph "Visualization"
        direction TB
        Rendering["Rendering Engine"]:::viz
    end

    %% Utilities & Dev Tools
    subgraph "Utilities & Dev Tools"
        direction TB
        Examples["Examples & Configs"]:::dev
        TestSuite["Unit & Integration Tests"]:::dev
        PackageSetup["Package Setup & Deps"]:::dev
    end

    %% Connections
    RLAgent -->|"action"| F110Env
    F110Env -->|"calls"| BaseClasses
    BaseClasses -->|"uses"| DynamicModels
    BaseClasses -->|"uses"| CollisionModels
    BaseClasses -->|"uses"| LaserModels
    MapLoader -->|"feeds world geometry"| BaseClasses
    F110Env -->|"returns obs,reward"| RLAgent
    Rendering -->|"taps state"| BaseClasses
    Examples -->|"demonstrate"| F110Env
    TestSuite -->|"validate"| DynamicModels
    TestSuite -->|"validate"| CollisionModels
    TestSuite -->|"validate"| LaserModels
    DockerGPU -->|"containerizes"| Rendering
    CIPipeline -->|"runs tests & build"| TestSuite
    PackageSetup -->|"setup env"| F110Env

    %% Click Events
    click F110Env "https://github.com/f1tenth/f1tenth_gym/blob/main/gym/f110_gym/envs/f110_env.py"
    click F110EnvBackup "https://github.com/f1tenth/f1tenth_gym/blob/main/gym/f110_gym/envs/f110_env_backup.py"
    click BaseClasses "https://github.com/f1tenth/f1tenth_gym/blob/main/gym/f110_gym/envs/base_classes.py"
    click DynamicModels "https://github.com/f1tenth/f1tenth_gym/blob/main/gym/f110_gym/envs/dynamic_models.py"
    click CollisionModels "https://github.com/f1tenth/f1tenth_gym/blob/main/gym/f110_gym/envs/collision_models.py"
    click LaserModels "https://github.com/f1tenth/f1tenth_gym/blob/main/gym/f110_gym/envs/laser_models.py"
    click MapLoader "https://github.com/f1tenth/f1tenth_gym/tree/main/gym/f110_gym/envs/maps/"
    click Rendering "https://github.com/f1tenth/f1tenth_gym/blob/main/gym/f110_gym/envs/rendering.py"
    click Examples "https://github.com/f1tenth/f1tenth_gym/blob/main/examples/waypoint_follow.py"
    click TestSuite "https://github.com/f1tenth/f1tenth_gym/tree/main/gym/f110_gym/unittest/"
    click DockerGPU "https://github.com/f1tenth/f1tenth_gym/tree/main/Dockerfile"
    click CIPipeline "https://github.com/f1tenth/f1tenth_gym/blob/main/.github/workflows/ci.yml"
    click PackageSetup "https://github.com/f1tenth/f1tenth_gym/blob/main/setup.py"

    %% Styles
    classDef api fill:#cce5ff,stroke:#66b2ff;
    classDef core fill:#d4edda,stroke:#28a745;
    classDef viz fill:#ffe5b4,stroke:#ff9900;
    classDef external fill:#f0f0f0,stroke:#999999;
    classDef dev fill:#e2e3e5,stroke:#6c757d;
```
