# cydal/lewm-car-nav architecture

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

- Interactive diagram: https://gitdiagram.com/cydal/lewm-car-nav
- Repository: https://github.com/cydal/lewm-car-nav

## Overview

This repository instruments an external 3D car-navigation simulator to collect, validate, and inspect trajectory datasets, then trains and evaluates a vector-observation LeWM model. The main workflow runs collection through the CLI, records episodes using configured driving policies, validates and reads the resulting dataset, and exports it for Stage 1 training. The graph also preserves the documented pilot, privileged-state capture, RGB/beacon options, and evaluation branches. Some subsystem links are documented rather than visible in the sampled implementation; those are dashed where appropriate.

Main entry points: [`lewm/collector.py`](https://github.com/cydal/lewm-car-nav/blob/main/lewm/collector.py) (Trajectory collector), [`lewm/__main__.py`](https://github.com/cydal/lewm-car-nav/blob/main/lewm/__main__.py) (CLI commands), [`lewm/pilot.py`](https://github.com/cydal/lewm-car-nav/blob/main/lewm/pilot.py) (Pilot analysis), [`lewm/dataset.py`](https://github.com/cydal/lewm-car-nav/blob/main/lewm/dataset.py) (Dataset views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Data collection"]
  node_config["Collection config<br/>[config.py]"]
  node_policies["Driving profiles<br/>[policies.py]"]
  node_collector["Trajectory collector<br/>[collector.py]"]
  node_privileged["Ground-truth capture<br/>[state.py]"]
  node_beacon["Goal beacon option<br/>[config.py]"]
end

subgraph group_dataset["Dataset and validation"]
  node_dataset_api["Dataset views<br/>[dataset.py]"]
  node_dataset_store[("Episode files<br/>[dataset.py]")]
  node_validator["Dataset validator<br/>[validate.py]"]
end

subgraph group_training["Stage 1 modeling"]
  node_exporter["HDF5 exporter<br/>[export_hdf5.py]"]
  node_hdf5[("Training arrays<br/>[export_hdf5.py]")]
  node_loader["Windowed batches<br/>[fast_loader.py]"]
  node_model["Vector JEPA<br/>[model.py]"]
  node_trainer["Training loop<br/>[train.py]"]
  node_evaluation["Model evaluation<br/>[baseline_eval.py]"]
end

subgraph group_operations["Pilot and interface"]
  node_cli["CLI commands<br/>[__main__.py]"]
  node_pilot["Pilot analysis<br/>[pilot.py]"]
end

node_user(("Experimenter"))
node_simulator["Car simulator"]
node_official["Official LeWM code"]
node_wandb["Weights and Biases"]

node_user -->|"runs"| node_cli
node_cli -->|"dispatches"| node_collector
node_cli -->|"dispatches"| node_pilot
node_cli -->|"dispatches"| node_validator
node_collector -->|"uses"| node_config
node_collector -->|"uses"| node_policies
node_collector -->|"records"| node_privileged
node_collector -->|"steps"| node_simulator
node_collector -.->|"writes"| node_dataset_store
node_dataset_api -->|"reads"| node_dataset_store
node_validator -->|"checks"| node_dataset_api
node_pilot -->|"collects"| node_collector
node_pilot -->|"validates"| node_validator
node_pilot -->|"inspects"| node_dataset_api
node_config -->|"configures"| node_beacon
node_exporter -->|"reads"| node_dataset_api
node_exporter -.->|"writes"| node_hdf5
node_loader -->|"loads"| node_hdf5
node_trainer -->|"batches"| node_loader
node_trainer -->|"trains"| node_model
node_model -->|"extends"| node_official
node_trainer -.->|"logs optionally"| node_wandb
node_evaluation -->|"loads"| node_loader
node_evaluation -->|"evaluates"| node_model

click node_cli "https://github.com/cydal/lewm-car-nav/blob/main/lewm/__main__.py"
click node_config "https://github.com/cydal/lewm-car-nav/blob/main/lewm/config.py"
click node_policies "https://github.com/cydal/lewm-car-nav/blob/main/lewm/policies.py"
click node_collector "https://github.com/cydal/lewm-car-nav/blob/main/lewm/collector.py"
click node_privileged "https://github.com/cydal/lewm-car-nav/blob/main/lewm/state.py"
click node_dataset_api "https://github.com/cydal/lewm-car-nav/blob/main/lewm/dataset.py"
click node_dataset_store "https://github.com/cydal/lewm-car-nav/blob/main/lewm/dataset.py"
click node_validator "https://github.com/cydal/lewm-car-nav/blob/main/lewm/validate.py"
click node_pilot "https://github.com/cydal/lewm-car-nav/blob/main/lewm/pilot.py"
click node_beacon "https://github.com/cydal/lewm-car-nav/blob/main/lewm/config.py"
click node_exporter "https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/export_hdf5.py"
click node_hdf5 "https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/export_hdf5.py"
click node_loader "https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/fast_loader.py"
click node_model "https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/model.py"
click node_trainer "https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/train.py"
click node_evaluation "https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/baseline_eval.py"

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_config,node_policies,node_collector,node_privileged,node_beacon toneBlue
class node_dataset_api,node_dataset_store,node_validator toneAmber
class node_exporter,node_hdf5,node_loader,node_model,node_trainer,node_evaluation toneMint
class node_cli,node_pilot toneRose
class node_user,node_simulator,node_official,node_wandb toneIndigo
```

## Components

### Data collection

- [Collection config](https://github.com/cydal/lewm-car-nav/blob/main/lewm/config.py): `lewm/config.py`
- [Driving profiles](https://github.com/cydal/lewm-car-nav/blob/main/lewm/policies.py): `lewm/policies.py`
- [Trajectory collector](https://github.com/cydal/lewm-car-nav/blob/main/lewm/collector.py): `lewm/collector.py`
- [Ground-truth capture](https://github.com/cydal/lewm-car-nav/blob/main/lewm/state.py): `lewm/state.py`
- [Goal beacon option](https://github.com/cydal/lewm-car-nav/blob/main/lewm/config.py): `lewm/config.py`

### Dataset and validation

- [Dataset views](https://github.com/cydal/lewm-car-nav/blob/main/lewm/dataset.py): `lewm/dataset.py`
- [Episode files](https://github.com/cydal/lewm-car-nav/blob/main/lewm/dataset.py): `lewm/dataset.py`
- [Dataset validator](https://github.com/cydal/lewm-car-nav/blob/main/lewm/validate.py): `lewm/validate.py`

### Stage 1 modeling

- [HDF5 exporter](https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/export_hdf5.py): `stage1_vector/export_hdf5.py`
- [Training arrays](https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/export_hdf5.py): `stage1_vector/export_hdf5.py`
- [Windowed batches](https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/fast_loader.py): `stage1_vector/fast_loader.py`
- [Vector JEPA](https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/model.py): `stage1_vector/model.py`
- [Training loop](https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/train.py): `stage1_vector/train.py`
- [Model evaluation](https://github.com/cydal/lewm-car-nav/blob/main/stage1_vector/baseline_eval.py): `stage1_vector/baseline_eval.py`

### Pilot and interface

- [CLI commands](https://github.com/cydal/lewm-car-nav/blob/main/lewm/__main__.py): `lewm/__main__.py`
- [Pilot analysis](https://github.com/cydal/lewm-car-nav/blob/main/lewm/pilot.py): `lewm/pilot.py`

### Other components

- **Experimenter**
- **Car simulator**
- **Official LeWM code**
- **Weights and Biases**

## Connections

- Experimenter → CLI commands: runs (evidence: `README.md`)
- CLI commands → Trajectory collector: dispatches (evidence: `lewm/__main__.py`)
- CLI commands → Pilot analysis: dispatches (evidence: `lewm/__main__.py`)
- CLI commands → Dataset validator: dispatches (evidence: `lewm/__main__.py`)
- Trajectory collector → Collection config: uses (evidence: `lewm/collector.py`)
- Trajectory collector → Driving profiles: uses (evidence: `lewm/collector.py`)
- Trajectory collector → Ground-truth capture: records (evidence: `lewm/collector.py`)
- Trajectory collector → Car simulator: steps (evidence: `lewm/collector.py`)
- Trajectory collector → Episode files: writes (evidence: `lewm/collector.py`)
- Dataset views → Episode files: reads (evidence: `lewm/dataset.py`)
- Dataset validator → Dataset views: checks (evidence: `lewm/validate.py`)
- Pilot analysis → Trajectory collector: collects (evidence: `lewm/pilot.py`)
- Pilot analysis → Dataset validator: validates (evidence: `lewm/pilot.py`)
- Pilot analysis → Dataset views: inspects (evidence: `lewm/pilot.py`)
- Collection config → Goal beacon option: configures (evidence: `README.md`)
- HDF5 exporter → Dataset views: reads (evidence: `stage1_vector/export_hdf5.py`)
- HDF5 exporter → Training arrays: writes (evidence: `stage1_vector/export_hdf5.py`)
- Windowed batches → Training arrays: loads (evidence: `stage1_vector/fast_loader.py`)
- Training loop → Windowed batches: batches (evidence: `stage1_vector/train.py`)
- Training loop → Vector JEPA: trains (evidence: `stage1_vector/train.py`)
- Vector JEPA → Official LeWM code: extends (evidence: `stage1_vector/model.py`)
- Training loop → Weights and Biases: logs optionally (evidence: `stage1_vector/train.py`)
- Model evaluation → Windowed batches: loads (evidence: `stage1_vector/baseline_eval.py`)
- Model evaluation → Vector JEPA: evaluates (evidence: `stage1_vector/baseline_eval.py`)
