# nitin3560/sim-val architecture

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

- Interactive diagram: https://gitdiagram.com/nitin3560/sim-val
- Repository: https://github.com/nitin3560/sim-val

## Overview

SimVal compares paired Gazebo and Isaac Sim UAV recordings, aligns their trajectories, computes camera and (when paired data exists) LiDAR fidelity, and optionally evaluates TwinGuard trust/authority deltas before writing a gap report. Isaac scenarios can be built and run separately; reports can then be plotted. Edges reflect the README and shown imports/calls. Some runner output and report-plot wiring is documented but not shown in source excerpts.

Main entry points: [`pipeline/run_pipeline.py`](https://github.com/nitin3560/sim-val/blob/main/pipeline/run_pipeline.py) (Comparison pipeline), [`isaac/run_scenario.py`](https://github.com/nitin3560/sim-val/blob/main/isaac/run_scenario.py) (Scenario runner), [`gazebo/extract_gazebo.py`](https://github.com/nitin3560/sim-val/blob/main/gazebo/extract_gazebo.py) (Gazebo extractor), [`isaac/extract_isaac.py`](https://github.com/nitin3560/sim-val/blob/main/isaac/extract_isaac.py) (Isaac extractor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Scenario capture"]
  node_scenarios["Scenario configs"]
  node_gazebo{{"Gazebo / ROS 2"}}
  node_gazebo_extract["Gazebo extractor<br/>[extract_gazebo.py]"]
  node_isaac_sim{{"Isaac Sim RTX"}}
  node_scene_builder["USD scene builder<br/>[build_scene.py]"]
  node_scenario_runner["Scenario runner<br/>[run_scenario.py]"]
  node_isaac_extract["Isaac extractor<br/>[extract_isaac.py]"]
end

subgraph group_records["Records and alignment"]
  node_sensor_record["SensorRecord<br/>[sensor_record.py]"]
  node_alignment["Trajectory alignment"]
end

subgraph group_analysis["Fidelity analysis"]
  node_pipeline["Comparison pipeline<br/>[run_pipeline.py]"]
  node_camera_metrics["Camera metrics<br/>[camera_metrics.py]"]
  node_lidar_metrics["LiDAR metrics<br/>[lidar_metrics.py]"]
  node_ekf_metrics["EKF propagation<br/>[ekf_propagation.py]"]
end

subgraph group_reporting["Reports and plots"]
  node_gap_report["Gap report<br/>[run_pipeline.py]"]
  node_plotter["Report plots<br/>[plot_metrics.py]"]
end

node_engineer(("Engineer"))

node_engineer -->|"selects"| node_scenarios
node_scenarios -->|"configures"| node_scene_builder
node_engineer -->|"runs"| node_scenario_runner
node_scenario_runner -->|"builds if missing"| node_scene_builder
node_scenario_runner -->|"runs simulation"| node_isaac_sim
node_gazebo -->|"provides bags"| node_gazebo_extract
node_gazebo_extract -->|"creates"| node_sensor_record
node_scenario_runner -->|"writes runner outputs"| node_isaac_extract
node_isaac_extract -->|"creates"| node_sensor_record
node_engineer -->|"starts comparison"| node_pipeline
node_pipeline -->|"extracts Gazebo data"| node_gazebo_extract
node_pipeline -->|"extracts Isaac data"| node_isaac_extract
node_pipeline -->|"aligns records"| node_alignment
node_alignment -->|"resamples records"| node_sensor_record
node_pipeline -->|"computes camera gap"| node_camera_metrics
node_pipeline -->|"computes when paired"| node_lidar_metrics
node_pipeline -->|"computes optional deltas"| node_ekf_metrics
node_pipeline -->|"writes report"| node_gap_report
node_engineer -->|"generates plots"| node_plotter
node_gap_report -->|"reads reports"| node_plotter

click node_scenarios "https://github.com/nitin3560/sim-val/tree/main/config"
click node_gazebo_extract "https://github.com/nitin3560/sim-val/blob/main/gazebo/extract_gazebo.py"
click node_scene_builder "https://github.com/nitin3560/sim-val/blob/main/isaac/build_scene.py"
click node_scenario_runner "https://github.com/nitin3560/sim-val/blob/main/isaac/run_scenario.py"
click node_isaac_extract "https://github.com/nitin3560/sim-val/blob/main/isaac/extract_isaac.py"
click node_sensor_record "https://github.com/nitin3560/sim-val/blob/main/schema/sensor_record.py"
click node_alignment "https://github.com/nitin3560/sim-val/blob/main/pipeline/align_trajectories.py"
click node_pipeline "https://github.com/nitin3560/sim-val/blob/main/pipeline/run_pipeline.py"
click node_camera_metrics "https://github.com/nitin3560/sim-val/blob/main/metrics/camera_metrics.py"
click node_lidar_metrics "https://github.com/nitin3560/sim-val/blob/main/metrics/lidar_metrics.py"
click node_ekf_metrics "https://github.com/nitin3560/sim-val/blob/main/pipeline/ekf_propagation.py"
click node_gap_report "https://github.com/nitin3560/sim-val/blob/main/pipeline/run_pipeline.py"
click node_plotter "https://github.com/nitin3560/sim-val/blob/main/report/plot_metrics.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_scenarios,node_gazebo,node_gazebo_extract,node_isaac_sim,node_scene_builder,node_scenario_runner,node_isaac_extract toneBlue
class node_sensor_record,node_alignment toneAmber
class node_pipeline,node_camera_metrics,node_lidar_metrics,node_ekf_metrics toneMint
class node_gap_report,node_plotter toneRose
class node_engineer toneIndigo
```

## Components

### Scenario capture

- [Scenario configs](https://github.com/nitin3560/sim-val/tree/main/config): `config`
- **Gazebo / ROS 2**
- [Gazebo extractor](https://github.com/nitin3560/sim-val/blob/main/gazebo/extract_gazebo.py): `gazebo/extract_gazebo.py`
- **Isaac Sim RTX**
- [USD scene builder](https://github.com/nitin3560/sim-val/blob/main/isaac/build_scene.py): `isaac/build_scene.py`
- [Scenario runner](https://github.com/nitin3560/sim-val/blob/main/isaac/run_scenario.py): `isaac/run_scenario.py`
- [Isaac extractor](https://github.com/nitin3560/sim-val/blob/main/isaac/extract_isaac.py): `isaac/extract_isaac.py`

### Records and alignment

- [SensorRecord](https://github.com/nitin3560/sim-val/blob/main/schema/sensor_record.py): `schema/sensor_record.py`
- [Trajectory alignment](https://github.com/nitin3560/sim-val/blob/main/pipeline/align_trajectories.py): `pipeline/align_trajectories.py`

### Fidelity analysis

- [Comparison pipeline](https://github.com/nitin3560/sim-val/blob/main/pipeline/run_pipeline.py): `pipeline/run_pipeline.py`
- [Camera metrics](https://github.com/nitin3560/sim-val/blob/main/metrics/camera_metrics.py): `metrics/camera_metrics.py`
- [LiDAR metrics](https://github.com/nitin3560/sim-val/blob/main/metrics/lidar_metrics.py): `metrics/lidar_metrics.py`
- [EKF propagation](https://github.com/nitin3560/sim-val/blob/main/pipeline/ekf_propagation.py): `pipeline/ekf_propagation.py`

### Reports and plots

- [Gap report](https://github.com/nitin3560/sim-val/blob/main/pipeline/run_pipeline.py): `pipeline/run_pipeline.py`
- [Report plots](https://github.com/nitin3560/sim-val/blob/main/report/plot_metrics.py): `report/plot_metrics.py`

### Other components

- **Engineer**

## Connections

- Engineer → Scenario configs: selects (evidence: `README.md`)
- Scenario configs → USD scene builder: configures (evidence: `README.md`)
- Engineer → Scenario runner: runs (evidence: `README.md`)
- Scenario runner → USD scene builder: builds if missing (evidence: `isaac/run_scenario.py`)
- Scenario runner → Isaac Sim RTX: runs simulation (evidence: `README.md`)
- Gazebo / ROS 2 → Gazebo extractor: provides bags (evidence: `README.md`)
- Gazebo extractor → SensorRecord: creates (evidence: `gazebo/extract_gazebo.py`)
- Scenario runner → Isaac extractor: writes runner outputs (evidence: `README.md`)
- Isaac extractor → SensorRecord: creates (evidence: `isaac/extract_isaac.py`)
- Engineer → Comparison pipeline: starts comparison (evidence: `README.md`)
- Comparison pipeline → Gazebo extractor: extracts Gazebo data (evidence: `pipeline/run_pipeline.py`)
- Comparison pipeline → Isaac extractor: extracts Isaac data (evidence: `pipeline/run_pipeline.py`)
- Comparison pipeline → Trajectory alignment: aligns records (evidence: `pipeline/run_pipeline.py`)
- Trajectory alignment → SensorRecord: resamples records (evidence: `pipeline/align_trajectories.py`)
- Comparison pipeline → Camera metrics: computes camera gap (evidence: `pipeline/run_pipeline.py`)
- Comparison pipeline → LiDAR metrics: computes when paired (evidence: `pipeline/run_pipeline.py`)
- Comparison pipeline → EKF propagation: computes optional deltas (evidence: `pipeline/run_pipeline.py`)
- Comparison pipeline → Gap report: writes report (evidence: `pipeline/run_pipeline.py`)
- Engineer → Report plots: generates plots (evidence: `README.md`)
- Gap report → Report plots: reads reports (evidence: `README.md`)
