# wingg001/ps26168 architecture

> Architecture diagram of the GitHub repository wingg001/ps26168, 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/wingg001/ps26168
- Repository: https://github.com/wingg001/ps26168

## Overview

PS26168 is a smartphone-based dead-reckoning and GNSS/INS fusion system for vehicle navigation during degraded or absent GNSS. Its main workflow loads and prepares phone/vehicle recordings, runs the Phase 3 estimator to produce a trajectory, then optionally snaps that trajectory to a road network. README capabilities include inertial mechanization, UKF fusion, motion constraints, GNSS health/adaptive noise, and HMM map matching. Some estimator wiring is supported by the runner excerpt and SOURCE INDEX; unsampled integration details are not inferred.

Main entry points: [`src/eval/run_phase3.py`](https://github.com/wingg001/ps26168/blob/main/src/eval/run_phase3.py) (Phase 3 estimator), [`src/phase1/pipeline.py`](https://github.com/wingg001/ps26168/blob/main/src/phase1/pipeline.py) (Phase 1 preparation), [`src/maps/map_match.py`](https://github.com/wingg001/ps26168/blob/main/src/maps/map_match.py) (Nearest-edge matching), [`src/phase1/loaders.py`](https://github.com/wingg001/ps26168/blob/main/src/phase1/loaders.py) (CSV loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_phase1_runner["Phase 1 preparation<br/>[pipeline.py]"]
  node_phase1_loader["CSV loading<br/>[loaders.py]"]
  node_schema["Schema utilities<br/>[schema_utils.py]"]
  node_time_align["Time alignment<br/>[time_alignment.py]"]
  node_calibration["Static calibration<br/>[calibration.py]"]
  node_frame_align["Frame alignment<br/>[alignment.py]"]
end

subgraph group_estimate["Navigation estimation"]
  node_phase3_runner["Phase 3 estimator<br/>[run_phase3.py]"]
  node_mechanization["INS mechanization<br/>[mechanization.py]"]
  node_coordinates["Coordinate transforms<br/>[coordinates.py]"]
  node_ukf["15-state UKF<br/>[ukf.py]"]
  node_constraints["Motion constraints<br/>[constraints.py]"]
  node_speed_model["CNN speed model"]
  node_trajectory["Estimated trajectory"]
end

subgraph group_health["GNSS quality"]
  node_gnss_noise["GNSS noise calibration<br/>[gnss_noise.py]"]
  node_gnss_manager["GNSS health manager<br/>[gnss_deficit.py]"]
end

subgraph group_mapping["Road matching"]
  node_road_graph[("Road graph<br/>[road_graph.py]")]
  node_nearest_match["Nearest-edge matching<br/>[map_match.py]"]
  node_hmm_match["HMM matching<br/>[hmm_match.py]"]
end

node_recordings(("Phone and vehicle data"))

node_recordings -->|"loads recordings"| node_phase1_runner
node_phase1_runner -->|"loads CSVs"| node_phase1_loader
node_phase1_loader -->|"uses schema"| node_schema
node_phase1_runner -->|"aligns clocks"| node_time_align
node_phase1_runner -->|"calibrates sensors"| node_calibration
node_phase1_runner -->|"aligns frames"| node_frame_align
node_phase1_runner -.->|"provides prepared data"| node_phase3_runner
node_phase3_runner -->|"uses alignment"| node_time_align
node_phase3_runner -->|"transforms positions"| node_coordinates
node_phase3_runner -->|"propagates state"| node_mechanization
node_phase3_runner -->|"updates filter"| node_ukf
node_phase3_runner -->|"applies constraints"| node_constraints
node_phase3_runner -->|"calibrates GNSS noise"| node_gnss_noise
node_phase3_runner -->|"tracks signal health"| node_gnss_manager
node_phase3_runner -.->|"uses speed estimate"| node_speed_model
node_phase3_runner -->|"produces trajectory"| node_trajectory
node_trajectory -->|"matches positions"| node_nearest_match
node_nearest_match -->|"queries edges"| node_road_graph
node_hmm_match -->|"uses candidates"| node_nearest_match
node_trajectory -->|"decodes path"| node_hmm_match

click node_phase1_runner "https://github.com/wingg001/ps26168/blob/main/src/phase1/pipeline.py"
click node_phase1_loader "https://github.com/wingg001/ps26168/blob/main/src/phase1/loaders.py"
click node_schema "https://github.com/wingg001/ps26168/blob/main/src/phase1/schema_utils.py"
click node_time_align "https://github.com/wingg001/ps26168/blob/main/src/phase1/time_alignment.py"
click node_calibration "https://github.com/wingg001/ps26168/blob/main/src/phase1/calibration.py"
click node_frame_align "https://github.com/wingg001/ps26168/blob/main/src/phase1/alignment.py"
click node_phase3_runner "https://github.com/wingg001/ps26168/blob/main/src/eval/run_phase3.py"
click node_mechanization "https://github.com/wingg001/ps26168/blob/main/src/filters/mechanization.py"
click node_coordinates "https://github.com/wingg001/ps26168/blob/main/src/filters/coordinates.py"
click node_ukf "https://github.com/wingg001/ps26168/blob/main/src/filters/ukf.py"
click node_constraints "https://github.com/wingg001/ps26168/blob/main/src/filters/constraints.py"
click node_speed_model "https://github.com/wingg001/ps26168/tree/main/models"
click node_gnss_noise "https://github.com/wingg001/ps26168/blob/main/src/calibration/gnss_noise.py"
click node_gnss_manager "https://github.com/wingg001/ps26168/blob/main/src/filters/gnss_deficit.py"
click node_road_graph "https://github.com/wingg001/ps26168/blob/main/src/maps/road_graph.py"
click node_nearest_match "https://github.com/wingg001/ps26168/blob/main/src/maps/map_match.py"
click node_hmm_match "https://github.com/wingg001/ps26168/blob/main/src/maps/hmm_match.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_phase1_runner,node_phase1_loader,node_schema,node_time_align,node_calibration,node_frame_align toneBlue
class node_phase3_runner,node_mechanization,node_coordinates,node_ukf,node_constraints,node_speed_model,node_trajectory toneAmber
class node_gnss_noise,node_gnss_manager toneMint
class node_road_graph,node_nearest_match,node_hmm_match toneRose
class node_recordings toneIndigo
```

## Components

### Data preparation

- [Phase 1 preparation](https://github.com/wingg001/ps26168/blob/main/src/phase1/pipeline.py): `src/phase1/pipeline.py`
- [CSV loading](https://github.com/wingg001/ps26168/blob/main/src/phase1/loaders.py): `src/phase1/loaders.py`
- [Schema utilities](https://github.com/wingg001/ps26168/blob/main/src/phase1/schema_utils.py): `src/phase1/schema_utils.py`
- [Time alignment](https://github.com/wingg001/ps26168/blob/main/src/phase1/time_alignment.py): `src/phase1/time_alignment.py`
- [Static calibration](https://github.com/wingg001/ps26168/blob/main/src/phase1/calibration.py): `src/phase1/calibration.py`
- [Frame alignment](https://github.com/wingg001/ps26168/blob/main/src/phase1/alignment.py): `src/phase1/alignment.py`

### Navigation estimation

- [Phase 3 estimator](https://github.com/wingg001/ps26168/blob/main/src/eval/run_phase3.py): `src/eval/run_phase3.py`
- [INS mechanization](https://github.com/wingg001/ps26168/blob/main/src/filters/mechanization.py): `src/filters/mechanization.py`
- [Coordinate transforms](https://github.com/wingg001/ps26168/blob/main/src/filters/coordinates.py): `src/filters/coordinates.py`
- [15-state UKF](https://github.com/wingg001/ps26168/blob/main/src/filters/ukf.py): `src/filters/ukf.py`
- [Motion constraints](https://github.com/wingg001/ps26168/blob/main/src/filters/constraints.py): `src/filters/constraints.py`
- [CNN speed model](https://github.com/wingg001/ps26168/tree/main/models): `models`
- **Estimated trajectory**

### GNSS quality

- [GNSS noise calibration](https://github.com/wingg001/ps26168/blob/main/src/calibration/gnss_noise.py): `src/calibration/gnss_noise.py`
- [GNSS health manager](https://github.com/wingg001/ps26168/blob/main/src/filters/gnss_deficit.py): `src/filters/gnss_deficit.py`

### Road matching

- [Road graph](https://github.com/wingg001/ps26168/blob/main/src/maps/road_graph.py): `src/maps/road_graph.py`
- [Nearest-edge matching](https://github.com/wingg001/ps26168/blob/main/src/maps/map_match.py): `src/maps/map_match.py`
- [HMM matching](https://github.com/wingg001/ps26168/blob/main/src/maps/hmm_match.py): `src/maps/hmm_match.py`

### Other components

- **Phone and vehicle data**

## Connections

- Phone and vehicle data → Phase 1 preparation: loads recordings (evidence: `src/phase1/pipeline.py`)
- Phase 1 preparation → CSV loading: loads CSVs (evidence: `src/phase1/pipeline.py`)
- CSV loading → Schema utilities: uses schema (evidence: `src/phase1/loaders.py`)
- Phase 1 preparation → Time alignment: aligns clocks (evidence: `src/phase1/pipeline.py`)
- Phase 1 preparation → Static calibration: calibrates sensors (evidence: `src/phase1/pipeline.py`)
- Phase 1 preparation → Frame alignment: aligns frames (evidence: `src/phase1/pipeline.py`)
- Phase 1 preparation → Phase 3 estimator: provides prepared data
- Phase 3 estimator → Time alignment: uses alignment (evidence: `src/eval/run_phase3.py`)
- Phase 3 estimator → Coordinate transforms: transforms positions (evidence: `src/eval/run_phase3.py`)
- Phase 3 estimator → INS mechanization: propagates state (evidence: `src/eval/run_phase3.py`)
- Phase 3 estimator → 15-state UKF: updates filter (evidence: `src/eval/run_phase3.py`)
- Phase 3 estimator → Motion constraints: applies constraints (evidence: `src/eval/run_phase3.py`)
- Phase 3 estimator → GNSS noise calibration: calibrates GNSS noise (evidence: `src/eval/run_phase3.py`)
- Phase 3 estimator → GNSS health manager: tracks signal health (evidence: `src/eval/run_phase3.py`)
- Phase 3 estimator → CNN speed model: uses speed estimate (evidence: `README.md`)
- Phase 3 estimator → Estimated trajectory: produces trajectory (evidence: `README.md`)
- Estimated trajectory → Nearest-edge matching: matches positions (evidence: `README.md`)
- Nearest-edge matching → Road graph: queries edges (evidence: `src/maps/map_match.py`)
- HMM matching → Nearest-edge matching: uses candidates (evidence: `src/maps/hmm_match.py`)
- Estimated trajectory → HMM matching: decodes path (evidence: `README.md`)