# ameliacmu/ameliascenes architecture

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

- Interactive diagram: https://gitdiagram.com/ameliacmu/ameliascenes
- Repository: https://github.com/ameliacmu/ameliascenes

## Overview

AmeliaScenes turns AmeliaSWIM airport trajectory files into scene pickles, optionally scores those scenes with agent- and scene-level metadata, and provides visualization and characterization tools. A separate workflow creates train/validation/test splits using random, daily, or monthly strategies. The graph preserves the documented capabilities and sampled module relationships; some visualization and processing internals were not excerpted, so their links are shown only where the README or SOURCE INDEX supports them.

Main entry points: [`amelia_scenes/processing/scene_meta_processor.py`](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/processing/scene_meta_processor.py) (Metadata generation), [`amelia_scenes/processing/scene_processor.py`](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/processing/scene_processor.py) (Scene generation), [`amelia_scenes/visualization/scene_viz.py`](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/scene_viz.py) (Scene visualization router), [`amelia_scenes/viz_characterization.py`](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/viz_characterization.py) (Agent characterization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_processing["Scene processing"]
  node_processor_entry["Processor entry point<br/>[run_processor.py]"]
  node_scene_processor["Scene generation<br/>[scene_processor.py]"]
  node_scenes["Scene pickles"]
  node_meta_processor["Metadata generation"]
  node_scene_meta["Scene metadata"]
  node_common_utils["Shared data utilities<br/>[common.py]"]
  node_global_masks["Trajectory field masks<br/>[global_masks.py]"]
end

subgraph group_analysis["Scoring and characterization"]
  node_kinematic["Kinematic scoring<br/>[kinematic.py]"]
  node_interactive["Interaction scoring<br/>[interactive.py]"]
  node_crowdedness["Crowdedness scoring<br/>[crowdedness.py]"]
  node_critical["Critical scoring<br/>[critical.py]"]
  node_characterization["Agent characterization"]
end

subgraph group_visualization["Visualization"]
  node_scene_viz["Scene visualization router<br/>[scene_viz.py]"]
  node_viz_common["Plotting primitives<br/>[common.py]"]
  node_benchmark_viz["Benchmark plots<br/>[benchmark_viz.py]"]
  node_marginal_viz["Marginal prediction plots"]
  node_scoring_viz["Score plots<br/>[scoring_viz.py]"]
end

subgraph group_dataset["Dataset preparation"]
  node_dataset_utils["Dataset access<br/>[dataset.py]"]
  node_splits_entry["Split generation"]
  node_split_files["Train/val/test lists"]
end

node_researcher(("Dataset user"))
node_rawdata["Raw trajectories"]

node_researcher -->|"runs processing"| node_processor_entry
node_rawdata -->|"supplies trajectories"| node_scene_processor
node_processor_entry -->|"dispatches processing"| node_scene_processor
node_scene_processor -->|"writes scenes"| node_scenes
node_processor_entry -->|"dispatches metadata"| node_meta_processor
node_meta_processor -->|"reads scenes"| node_scenes
node_meta_processor -->|"writes scores"| node_scene_meta
node_scene_processor -->|"uses utilities"| node_common_utils
node_scene_processor -->|"uses dataset helpers"| node_dataset_utils
node_scene_processor -->|"uses field masks"| node_global_masks
node_meta_processor -->|"uses utilities"| node_common_utils
node_meta_processor -->|"computes scores"| node_kinematic
node_meta_processor -->|"computes scores"| node_interactive
node_meta_processor -->|"computes scores"| node_crowdedness
node_meta_processor -->|"aggregates scores"| node_critical
node_kinematic -->|"uses constants"| node_common_utils
node_kinematic -->|"indexes trajectories"| node_global_masks
node_interactive -->|"uses constants"| node_common_utils
node_interactive -->|"indexes trajectories"| node_global_masks
node_crowdedness -->|"reads weights"| node_common_utils
node_researcher -->|"requests split"| node_splits_entry
node_splits_entry -->|"uses dataset helpers"| node_dataset_utils
node_splits_entry -->|"writes split lists"| node_split_files
node_researcher -->|"runs characterization"| node_characterization
node_characterization -->|"loads assets"| node_dataset_utils
node_characterization -->|"computes features"| node_kinematic
node_characterization -->|"computes features"| node_interactive
node_characterization -->|"renders scenes"| node_scene_viz
node_researcher -->|"requests visualization"| node_scene_viz
node_scene_viz -->|"routes benchmark plots"| node_benchmark_viz
node_scene_viz -->|"routes prediction plots"| node_marginal_viz
node_scene_viz -->|"routes score plots"| node_scoring_viz
node_scene_viz -->|"uses plotting tools"| node_viz_common
node_benchmark_viz -->|"uses plotting tools"| node_viz_common
node_marginal_viz -->|"uses plotting tools"| node_viz_common
node_scoring_viz -->|"uses plotting tools"| node_viz_common

click node_processor_entry "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/run_processor.py"
click node_scene_processor "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/processing/scene_processor.py"
click node_meta_processor "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/processing/scene_meta_processor.py"
click node_common_utils "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/utils/common.py"
click node_dataset_utils "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/utils/dataset.py"
click node_global_masks "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/utils/global_masks.py"
click node_kinematic "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/scoring/kinematic.py"
click node_interactive "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/scoring/interactive.py"
click node_crowdedness "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/scoring/crowdedness.py"
click node_critical "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/scoring/critical.py"
click node_characterization "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/viz_characterization.py"
click node_scene_viz "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/scene_viz.py"
click node_viz_common "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/common.py"
click node_benchmark_viz "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/benchmark_viz.py"
click node_marginal_viz "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/marginal_predictions.py"
click node_scoring_viz "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/scoring_viz.py"
click node_splits_entry "https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/run_create_splits.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_processor_entry,node_scene_processor,node_scenes,node_meta_processor,node_scene_meta,node_common_utils,node_global_masks,node_researcher toneBlue
class node_kinematic,node_interactive,node_crowdedness,node_critical,node_characterization toneAmber
class node_scene_viz,node_viz_common,node_benchmark_viz,node_marginal_viz,node_scoring_viz toneMint
class node_dataset_utils,node_splits_entry,node_split_files toneRose
class node_rawdata toneIndigo
```

## Components

### Scene processing

- [Processor entry point](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/run_processor.py): `amelia_scenes/run_processor.py`
- [Scene generation](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/processing/scene_processor.py): `amelia_scenes/processing/scene_processor.py`
- **Scene pickles**
- [Metadata generation](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/processing/scene_meta_processor.py): `amelia_scenes/processing/scene_meta_processor.py`
- **Scene metadata**
- [Shared data utilities](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/utils/common.py): `amelia_scenes/utils/common.py`
- [Trajectory field masks](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/utils/global_masks.py): `amelia_scenes/utils/global_masks.py`

### Scoring and characterization

- [Kinematic scoring](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/scoring/kinematic.py): `amelia_scenes/scoring/kinematic.py`
- [Interaction scoring](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/scoring/interactive.py): `amelia_scenes/scoring/interactive.py`
- [Crowdedness scoring](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/scoring/crowdedness.py): `amelia_scenes/scoring/crowdedness.py`
- [Critical scoring](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/scoring/critical.py): `amelia_scenes/scoring/critical.py`
- [Agent characterization](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/viz_characterization.py): `amelia_scenes/viz_characterization.py`

### Visualization

- [Scene visualization router](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/scene_viz.py): `amelia_scenes/visualization/scene_viz.py`
- [Plotting primitives](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/common.py): `amelia_scenes/visualization/common.py`
- [Benchmark plots](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/benchmark_viz.py): `amelia_scenes/visualization/benchmark_viz.py`
- [Marginal prediction plots](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/marginal_predictions.py): `amelia_scenes/visualization/marginal_predictions.py`
- [Score plots](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/visualization/scoring_viz.py): `amelia_scenes/visualization/scoring_viz.py`

### Dataset preparation

- [Dataset access](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/utils/dataset.py): `amelia_scenes/utils/dataset.py`
- [Split generation](https://github.com/ameliacmu/ameliascenes/blob/main/amelia_scenes/run_create_splits.py): `amelia_scenes/run_create_splits.py`
- **Train/val/test lists**

### Other components

- **Dataset user**
- **Raw trajectories**

## Connections

- Dataset user → Processor entry point: runs processing (evidence: `README.md`)
- Raw trajectories → Scene generation: supplies trajectories (evidence: `README.md`)
- Processor entry point → Scene generation: dispatches processing (evidence: `amelia_scenes/run_processor.py`)
- Scene generation → Scene pickles: writes scenes (evidence: `README.md`)
- Processor entry point → Metadata generation: dispatches metadata (evidence: `amelia_scenes/run_processor.py`)
- Metadata generation → Scene pickles: reads scenes (evidence: `amelia_scenes/processing/scene_meta_processor.py`)
- Metadata generation → Scene metadata: writes scores (evidence: `amelia_scenes/processing/scene_meta_processor.py`)
- Scene generation → Shared data utilities: uses utilities (evidence: `amelia_scenes/processing/scene_processor.py`)
- Scene generation → Dataset access: uses dataset helpers (evidence: `amelia_scenes/processing/scene_processor.py`)
- Scene generation → Trajectory field masks: uses field masks (evidence: `amelia_scenes/processing/scene_processor.py`)
- Metadata generation → Shared data utilities: uses utilities (evidence: `amelia_scenes/processing/scene_meta_processor.py`)
- Metadata generation → Kinematic scoring: computes scores (evidence: `amelia_scenes/processing/scene_meta_processor.py`)
- Metadata generation → Interaction scoring: computes scores (evidence: `amelia_scenes/processing/scene_meta_processor.py`)
- Metadata generation → Crowdedness scoring: computes scores (evidence: `amelia_scenes/processing/scene_meta_processor.py`)
- Metadata generation → Critical scoring: aggregates scores (evidence: `amelia_scenes/processing/scene_meta_processor.py`)
- Kinematic scoring → Shared data utilities: uses constants (evidence: `amelia_scenes/scoring/kinematic.py`)
- Kinematic scoring → Trajectory field masks: indexes trajectories (evidence: `amelia_scenes/scoring/kinematic.py`)
- Interaction scoring → Shared data utilities: uses constants (evidence: `amelia_scenes/scoring/interactive.py`)
- Interaction scoring → Trajectory field masks: indexes trajectories (evidence: `amelia_scenes/scoring/interactive.py`)
- Crowdedness scoring → Shared data utilities: reads weights (evidence: `amelia_scenes/scoring/crowdedness.py`)
- Dataset user → Split generation: requests split (evidence: `README.md`)
- Split generation → Dataset access: uses dataset helpers (evidence: `amelia_scenes/run_create_splits.py`)
- Split generation → Train/val/test lists: writes split lists (evidence: `README.md`)
- Dataset user → Agent characterization: runs characterization (evidence: `amelia_scenes/viz_characterization.py`)
- Agent characterization → Dataset access: loads assets (evidence: `amelia_scenes/viz_characterization.py`)
- Agent characterization → Kinematic scoring: computes features (evidence: `amelia_scenes/viz_characterization.py`)
- Agent characterization → Interaction scoring: computes features (evidence: `amelia_scenes/viz_characterization.py`)
- Agent characterization → Scene visualization router: renders scenes (evidence: `amelia_scenes/viz_characterization.py`)
- Dataset user → Scene visualization router: requests visualization (evidence: `README.md`)
- Scene visualization router → Benchmark plots: routes benchmark plots (evidence: `amelia_scenes/visualization/scene_viz.py`)
- Scene visualization router → Marginal prediction plots: routes prediction plots (evidence: `amelia_scenes/visualization/scene_viz.py`)
- Scene visualization router → Score plots: routes score plots (evidence: `amelia_scenes/visualization/scene_viz.py`)
- Scene visualization router → Plotting primitives: uses plotting tools (evidence: `amelia_scenes/visualization/scene_viz.py`)
- Benchmark plots → Plotting primitives: uses plotting tools (evidence: `amelia_scenes/visualization/benchmark_viz.py`)
- Marginal prediction plots → Plotting primitives: uses plotting tools (evidence: `amelia_scenes/visualization/marginal_predictions.py`)
- Score plots → Plotting primitives: uses plotting tools (evidence: `amelia_scenes/visualization/scoring_viz.py`)
