# vail-ucla/navsafe-infty architecture

> Architecture diagram of the GitHub repository vail-ucla/navsafe-infty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vail-ucla/navsafe-infty
- Repository: https://github.com/vail-ucla/navsafe-infty
- Video tour (about a minute): https://gitdiagram.com/vail-ucla/navsafe-infty/video

## Overview

NavSafe benchmarks closed-loop driving-policy safety in reconstructed scenes. A user supplies scenario data, a policy adapter and checkpoint, then evaluation configures the simulator and renderer, obtains policy observations and actions, executes the ego alongside replay/traffic actors, and records scores and artifacts. The repository also contains log-ingestion and parsing paths for preparing scenarios, model implementations, sensor/render support, and visualization. The README documents scenario mining, reconstruction preparation, asset harvesting, and recipe authoring; their implementation directories are not present in the supplied tree, so those branches are not expanded here. Some runtime links remain uncertain because evaluator and environment implementations were not excerpted.

Main entry points: [`navsafe/evaluation/evaluator.py`](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/evaluation/evaluator.py) (Evaluator), [`navsafe/env/navsafe_env.py`](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/env/navsafe_env.py) (Simulation environment), [`navsafe/cli/eval_entry.py`](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/cli/eval_entry.py) (Evaluation CLI), [`navsafe/render/nurec_grpc.py`](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/render/nurec_grpc.py) (NuRec renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prepare["Scenario preparation"]
  node_ingest["Log ingestion<br/>[log_ingestion.py]"]
  node_navsim["NavSim parser<br/>[navsim_parser.py]"]
  node_scenario["Scenario format"]
end

subgraph group_runtime["Simulation runtime"]
  node_scene["Scene builder"]
  node_env["Simulation environment<br/>[navsafe_env.py]"]
  node_replay["Actor replay"]
  node_traffic["Traffic behaviors<br/>[navsafe.py]"]
end

subgraph group_policy["Policies and models"]
  node_sensor_policy["Sensor policy adapters<br/>[sensor_policy.py]"]
  node_state_policy["State policy adapters<br/>[state_policy.py]"]
  node_models["Model implementations"]
end

subgraph group_assessment["Evaluation and results"]
  node_cli["Evaluation CLI<br/>[eval_entry.py]"]
  node_evaluator["Evaluator<br/>[evaluator.py]"]
  node_routes["Route manager<br/>[route_manager.py]"]
  node_scoring["Trajectory scoring"]
  node_visuals["Evaluation visuals<br/>[vis_utils.py]"]
end

subgraph group_support["Rendering and control"]
  node_camera["Camera dispatch<br/>[camera_manager.py]"]
  node_renderer["NuRec renderer<br/>[nurec_grpc.py]"]
  node_control["Trajectory control<br/>[controllers.py]"]
  node_execution["Plan execution<br/>[plan_execution.py]"]
end

node_user(("Benchmark user"))
node_render_service["NuRec gRPC service"]

node_user -->|"runs evaluation"| node_cli
node_cli -->|"configures and runs"| node_evaluator
node_ingest -->|"uses parser"| node_navsim
node_navsim -->|"provides log data"| node_ingest
node_replay -->|"reads scenario"| node_scenario
node_scene -->|"builds from"| node_scenario
node_evaluator -->|"delegates routes"| node_routes
node_evaluator -.->|"scores policies"| node_scoring
node_evaluator -.->|"produces visuals"| node_visuals
node_cli -->|"selects adapter"| node_sensor_policy
node_cli -->|"selects adapter"| node_state_policy
node_sensor_policy -.->|"uses inference"| node_models
node_camera -->|"requests images"| node_renderer
node_renderer -->|"requests frames"| node_render_service
node_control -->|"uses plan execution"| node_execution
node_evaluator -.->|"runs in environment"| node_env
node_env -.->|"updates actors"| node_replay
node_env -.->|"simulates traffic"| node_traffic
node_env -->|"dispatches cameras"| node_camera
node_env -.->|"renders observations"| node_renderer
node_evaluator -.->|"executes plans"| node_control

click node_cli "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/cli/eval_entry.py"
click node_ingest "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/gs3d_converter/log_ingestion.py"
click node_navsim "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/gs3d_converter/navsim_parser.py"
click node_scenario "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/scenario/scenario_description.py"
click node_scene "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/scene/scenario_map_builder.py"
click node_env "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/env/navsafe_env.py"
click node_replay "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/manager/scenario_replay_manager.py"
click node_traffic "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/traffic/navsafe.py"
click node_evaluator "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/evaluation/evaluator.py"
click node_routes "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/evaluation/route_manager.py"
click node_scoring "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/evaluation/scorers/epdms_trajectory_scorer_fast.py"
click node_visuals "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/evaluation/vis_utils.py"
click node_sensor_policy "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/policy/sensor_policy.py"
click node_state_policy "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/policy/state_policy.py"
click node_models "https://github.com/vail-ucla/navsafe-infty/tree/main/navsafe/modelzoo"
click node_camera "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/env/camera_manager.py"
click node_renderer "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/render/nurec_grpc.py"
click node_control "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/core/controllers.py"
click node_execution "https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/core/plan_execution.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_ingest,node_navsim,node_scenario,node_user toneBlue
class node_scene,node_env,node_replay,node_traffic toneAmber
class node_sensor_policy,node_state_policy,node_models toneMint
class node_cli,node_evaluator,node_routes,node_scoring,node_visuals toneRose
class node_camera,node_renderer,node_control,node_execution,node_render_service toneIndigo
```

## Components

### Scenario preparation

- [Log ingestion](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/gs3d_converter/log_ingestion.py): `navsafe/gs3d_converter/log_ingestion.py`
- [NavSim parser](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/gs3d_converter/navsim_parser.py): `navsafe/gs3d_converter/navsim_parser.py`
- [Scenario format](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/scenario/scenario_description.py): `navsafe/scenario/scenario_description.py`

### Simulation runtime

- [Scene builder](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/scene/scenario_map_builder.py): `navsafe/scene/scenario_map_builder.py`
- [Simulation environment](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/env/navsafe_env.py): `navsafe/env/navsafe_env.py`
- [Actor replay](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/manager/scenario_replay_manager.py): `navsafe/manager/scenario_replay_manager.py`
- [Traffic behaviors](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/traffic/navsafe.py): `navsafe/traffic/navsafe.py`

### Policies and models

- [Sensor policy adapters](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/policy/sensor_policy.py): `navsafe/policy/sensor_policy.py`
- [State policy adapters](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/policy/state_policy.py): `navsafe/policy/state_policy.py`
- [Model implementations](https://github.com/vail-ucla/navsafe-infty/tree/main/navsafe/modelzoo): `navsafe/modelzoo`

### Evaluation and results

- [Evaluation CLI](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/cli/eval_entry.py): `navsafe/cli/eval_entry.py`
- [Evaluator](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/evaluation/evaluator.py): `navsafe/evaluation/evaluator.py`
- [Route manager](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/evaluation/route_manager.py): `navsafe/evaluation/route_manager.py`
- [Trajectory scoring](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/evaluation/scorers/epdms_trajectory_scorer_fast.py): `navsafe/evaluation/scorers/epdms_trajectory_scorer_fast.py`
- [Evaluation visuals](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/evaluation/vis_utils.py): `navsafe/evaluation/vis_utils.py`

### Rendering and control

- [Camera dispatch](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/env/camera_manager.py): `navsafe/env/camera_manager.py`
- [NuRec renderer](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/render/nurec_grpc.py): `navsafe/render/nurec_grpc.py`
- [Trajectory control](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/core/controllers.py): `navsafe/core/controllers.py`
- [Plan execution](https://github.com/vail-ucla/navsafe-infty/blob/main/navsafe/core/plan_execution.py): `navsafe/core/plan_execution.py`

### Other components

- **Benchmark user**
- **NuRec gRPC service**

## Connections

- Benchmark user → Evaluation CLI: runs evaluation (evidence: `README.md`)
- Evaluation CLI → Evaluator: configures and runs (evidence: `navsafe/cli/eval_entry.py`)
- Log ingestion → NavSim parser: uses parser (evidence: `navsafe/gs3d_converter/log_ingestion.py`)
- NavSim parser → Log ingestion: provides log data (evidence: `navsafe/gs3d_converter/navsim_parser.py`)
- Actor replay → Scenario format: reads scenario (evidence: `navsafe/manager/scenario_replay_manager.py`)
- Scene builder → Scenario format: builds from (evidence: `navsafe/scene/scenario_map_builder.py`)
- Evaluator → Route manager: delegates routes (evidence: `navsafe/evaluation/route_manager.py`)
- Evaluator → Trajectory scoring: scores policies
- Evaluator → Evaluation visuals: produces visuals
- Evaluation CLI → Sensor policy adapters: selects adapter (evidence: `README.md`)
- Evaluation CLI → State policy adapters: selects adapter (evidence: `README.md`)
- Sensor policy adapters → Model implementations: uses inference (evidence: `README.md`)
- Camera dispatch → NuRec renderer: requests images (evidence: `navsafe/env/camera_manager.py`)
- NuRec renderer → NuRec gRPC service: requests frames (evidence: `navsafe/render/nurec_grpc.py`)
- Trajectory control → Plan execution: uses plan execution (evidence: `navsafe/core/controllers.py`)
- Evaluator → Simulation environment: runs in environment
- Simulation environment → Actor replay: updates actors
- Simulation environment → Traffic behaviors: simulates traffic
- Simulation environment → Camera dispatch: dispatches cameras (evidence: `navsafe/env/camera_manager.py`)
- Simulation environment → NuRec renderer: renders observations
- Evaluator → Trajectory control: executes plans