# binamira/ros-rl-terrain architecture

> Architecture diagram of the GitHub repository binamira/ros-rl-terrain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/binamira/ros-rl-terrain
- Repository: https://github.com/binamira/ros-rl-terrain

## Overview

This repository is a configuration-driven procedural terrain generator for robotics training, with Gazebo export, runtime terrain queries, curriculum/reset utilities, and a browser preview. Its principal workflow configures and generates terrain cells, merges them into a world mesh, then exports simulator assets and metadata; the metadata also supports runtime spawn and height queries. The README documents the generation/export stages, while excerpts confirm several implementation calls. Some subsystem details are documented but unsampled, so those connections are shown only where the README supports them.

Main entry points: [`simulators/gazebo/exporter.py`](https://github.com/binamira/ros-rl-terrain/blob/main/simulators/gazebo/exporter.py) (Gazebo exporter), [`terrain/generator.py`](https://github.com/binamira/ros-rl-terrain/blob/main/terrain/generator.py) (Grid generator), [`scripts/generate_terrain.py`](https://github.com/binamira/ros-rl-terrain/blob/main/scripts/generate_terrain.py) (Generation CLI), [`web/static/controls.js`](https://github.com/binamira/ros-rl-terrain/blob/main/web/static/controls.js) (Configurator controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Terrain generation"]
  node_cli["Generation CLI"]
  node_config["Terrain config<br/>[config.py]"]
  node_orchestrator["Grid generator<br/>[generator.py]"]
  node_families["Terrain families"]
  node_isaac["Isaac terrain replicas<br/>[isaac.py]"]
  node_features["Cell features<br/>[features.py]"]
  node_geometry["Cell and world geometry<br/>[geometry.py]"]
  node_merger["Mesh merger<br/>[merger.py]"]
end

subgraph group_export["Simulator export"]
  node_exporter["Gazebo exporter<br/>[exporter.py]"]
  node_meshwriter["Collada mesh writer<br/>[mesh_writer.py]"]
  node_sdfwriter["SDF model writer<br/>[sdf_writer.py]"]
  node_collision["Cell collision models<br/>[cell_collision.py]"]
end

subgraph group_runtime["Training runtime"]
  node_metadata["Terrain metadata IO<br/>[metadata_io.py]"]
  node_registry["Terrain registry<br/>[registry.py]"]
  node_curriculum["Curriculum manager"]
  node_reset["Reset manager<br/>[reset_manager.py]"]
end

subgraph group_preview["Web preview"]
  node_controls["Configurator controls<br/>[controls.js]"]
  node_server["Preview API<br/>[server.py]"]
  node_viewer["Terrain viewer<br/>[terrain.js]"]
end

node_user(("Operator"))
node_yaml["Terrain YAML"]
node_webuser(("Preview user"))

node_user -->|"sets parameters"| node_yaml
node_yaml -->|"configures"| node_cli
node_cli -->|"starts generation"| node_orchestrator
node_config -->|"configures"| node_orchestrator
node_orchestrator -->|"generates cells"| node_families
node_orchestrator -->|"passes cell meshes"| node_merger
node_merger -->|"produces terrain geometry"| node_geometry
node_families -.->|"measures cell properties"| node_features
node_isaac -.->|"supplies terrain types"| node_orchestrator
node_cli -->|"exports terrain"| node_exporter
node_exporter -->|"writes mesh"| node_meshwriter
node_exporter -->|"writes model files"| node_sdfwriter
node_exporter -->|"exports geometry"| node_geometry
node_exporter -->|"writes metadata"| node_metadata
node_metadata -->|"loads query data"| node_registry
node_curriculum -->|"selects cell for"| node_reset
node_reset -->|"gets spawn origins"| node_registry
node_webuser -.->|"configures preview"| node_controls
node_controls -->|"requests generation"| node_server
node_server -->|"generates terrain"| node_orchestrator
node_controls -.->|"updates display"| node_viewer
node_server -->|"serves preview UI"| node_viewer
node_exporter -.->|"supports collision export"| node_collision

click node_yaml "https://github.com/binamira/ros-rl-terrain/blob/main/config/terrain_go2_isaac_training_1col.yaml"
click node_cli "https://github.com/binamira/ros-rl-terrain/blob/main/scripts/generate_terrain.py"
click node_config "https://github.com/binamira/ros-rl-terrain/blob/main/terrain/config.py"
click node_orchestrator "https://github.com/binamira/ros-rl-terrain/blob/main/terrain/generator.py"
click node_families "https://github.com/binamira/ros-rl-terrain/tree/main/terrain/generators"
click node_isaac "https://github.com/binamira/ros-rl-terrain/blob/main/terrain/generators/isaac.py"
click node_features "https://github.com/binamira/ros-rl-terrain/blob/main/terrain/features.py"
click node_geometry "https://github.com/binamira/ros-rl-terrain/blob/main/terrain/geometry.py"
click node_merger "https://github.com/binamira/ros-rl-terrain/blob/main/terrain/merger.py"
click node_exporter "https://github.com/binamira/ros-rl-terrain/blob/main/simulators/gazebo/exporter.py"
click node_meshwriter "https://github.com/binamira/ros-rl-terrain/blob/main/simulators/gazebo/mesh_writer.py"
click node_sdfwriter "https://github.com/binamira/ros-rl-terrain/blob/main/simulators/gazebo/sdf_writer.py"
click node_collision "https://github.com/binamira/ros-rl-terrain/blob/main/simulators/gazebo/cell_collision.py"
click node_metadata "https://github.com/binamira/ros-rl-terrain/blob/main/terrain/metadata_io.py"
click node_registry "https://github.com/binamira/ros-rl-terrain/blob/main/terrain/registry.py"
click node_curriculum "https://github.com/binamira/ros-rl-terrain/blob/main/managers/curriculum_manager.py"
click node_reset "https://github.com/binamira/ros-rl-terrain/blob/main/managers/reset_manager.py"
click node_controls "https://github.com/binamira/ros-rl-terrain/blob/main/web/static/controls.js"
click node_server "https://github.com/binamira/ros-rl-terrain/blob/main/web/server.py"
click node_viewer "https://github.com/binamira/ros-rl-terrain/blob/main/web/static/terrain.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_orchestrator,node_families,node_isaac,node_features,node_geometry,node_merger,node_webuser toneBlue
class node_exporter,node_meshwriter,node_sdfwriter,node_collision toneAmber
class node_metadata,node_registry,node_curriculum,node_reset toneMint
class node_controls,node_server,node_viewer toneRose
class node_user toneIndigo
class node_yaml toneTeal
```

## Components

### Terrain generation

- [Generation CLI](https://github.com/binamira/ros-rl-terrain/blob/main/scripts/generate_terrain.py): `scripts/generate_terrain.py`
- [Terrain config](https://github.com/binamira/ros-rl-terrain/blob/main/terrain/config.py): `terrain/config.py`
- [Grid generator](https://github.com/binamira/ros-rl-terrain/blob/main/terrain/generator.py): `terrain/generator.py`
- [Terrain families](https://github.com/binamira/ros-rl-terrain/tree/main/terrain/generators): `terrain/generators`
- [Isaac terrain replicas](https://github.com/binamira/ros-rl-terrain/blob/main/terrain/generators/isaac.py): `terrain/generators/isaac.py`
- [Cell features](https://github.com/binamira/ros-rl-terrain/blob/main/terrain/features.py): `terrain/features.py`
- [Cell and world geometry](https://github.com/binamira/ros-rl-terrain/blob/main/terrain/geometry.py): `terrain/geometry.py`
- [Mesh merger](https://github.com/binamira/ros-rl-terrain/blob/main/terrain/merger.py): `terrain/merger.py`

### Simulator export

- [Gazebo exporter](https://github.com/binamira/ros-rl-terrain/blob/main/simulators/gazebo/exporter.py): `simulators/gazebo/exporter.py`
- [Collada mesh writer](https://github.com/binamira/ros-rl-terrain/blob/main/simulators/gazebo/mesh_writer.py): `simulators/gazebo/mesh_writer.py`
- [SDF model writer](https://github.com/binamira/ros-rl-terrain/blob/main/simulators/gazebo/sdf_writer.py): `simulators/gazebo/sdf_writer.py`
- [Cell collision models](https://github.com/binamira/ros-rl-terrain/blob/main/simulators/gazebo/cell_collision.py): `simulators/gazebo/cell_collision.py`

### Training runtime

- [Terrain metadata IO](https://github.com/binamira/ros-rl-terrain/blob/main/terrain/metadata_io.py): `terrain/metadata_io.py`
- [Terrain registry](https://github.com/binamira/ros-rl-terrain/blob/main/terrain/registry.py): `terrain/registry.py`
- [Curriculum manager](https://github.com/binamira/ros-rl-terrain/blob/main/managers/curriculum_manager.py): `managers/curriculum_manager.py`
- [Reset manager](https://github.com/binamira/ros-rl-terrain/blob/main/managers/reset_manager.py): `managers/reset_manager.py`

### Web preview

- [Configurator controls](https://github.com/binamira/ros-rl-terrain/blob/main/web/static/controls.js): `web/static/controls.js`
- [Preview API](https://github.com/binamira/ros-rl-terrain/blob/main/web/server.py): `web/server.py`
- [Terrain viewer](https://github.com/binamira/ros-rl-terrain/blob/main/web/static/terrain.js): `web/static/terrain.js`

### Other components

- **Operator**
- [Terrain YAML](https://github.com/binamira/ros-rl-terrain/blob/main/config/terrain_go2_isaac_training_1col.yaml): `config/terrain_go2_isaac_training_1col.yaml`
- **Preview user**

## Connections

- Operator → Terrain YAML: sets parameters (evidence: `README.md`)
- Terrain YAML → Generation CLI: configures (evidence: `README.md`)
- Generation CLI → Grid generator: starts generation (evidence: `README.md`)
- Terrain config → Grid generator: configures (evidence: `README.md`)
- Grid generator → Terrain families: generates cells (evidence: `README.md`)
- Grid generator → Mesh merger: passes cell meshes (evidence: `README.md`)
- Mesh merger → Cell and world geometry: produces terrain geometry (evidence: `README.md`)
- Terrain families → Cell features: measures cell properties
- Isaac terrain replicas → Grid generator: supplies terrain types
- Generation CLI → Gazebo exporter: exports terrain (evidence: `README.md`)
- Gazebo exporter → Collada mesh writer: writes mesh (evidence: `simulators/gazebo/exporter.py`)
- Gazebo exporter → SDF model writer: writes model files (evidence: `simulators/gazebo/exporter.py`)
- Gazebo exporter → Cell and world geometry: exports geometry (evidence: `README.md`)
- Gazebo exporter → Terrain metadata IO: writes metadata (evidence: `README.md`)
- Terrain metadata IO → Terrain registry: loads query data (evidence: `README.md`)
- Curriculum manager → Reset manager: selects cell for (evidence: `managers/reset_manager.py`)
- Reset manager → Terrain registry: gets spawn origins (evidence: `managers/reset_manager.py`)
- Preview user → Configurator controls: configures preview
- Configurator controls → Preview API: requests generation (evidence: `web/static/controls.js`)
- Preview API → Grid generator: generates terrain (evidence: `web/server.py`)
- Configurator controls → Terrain viewer: updates display
- Preview API → Terrain viewer: serves preview UI (evidence: `web/server.py`)
- Gazebo exporter → Cell collision models: supports collision export
