# shalikha/thesis architecture

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

- Interactive diagram: https://gitdiagram.com/shalikha/thesis
- Repository: https://github.com/shalikha/thesis

## Overview

This repository provides monocular-video traffic analysis: calibration maps image pixels to world coordinates, then vehicle geometry supports speed and inter-vehicle analysis. Users can also compare localization approaches, refine 3D boxes interactively, or run a segmentation/keypoint fallback pipeline. A separate calibration utility selects reference points and builds a lookup table, with optional video stabilization and ROI tools. The README documents these capabilities; arrows between independently documented tools are omitted unless a source excerpt shows the call. Some implementation details, especially comparison and fallback internals, were not fully sampled.

Main entry points: [`utils/calibration_tool/main.py`](https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/main.py) (Calibration Runner), [`src/speed_estimator.py`](https://github.com/shalikha/thesis/blob/main/src/speed_estimator.py) (Speed Estimator), [`src/distance_analyzer.py`](https://github.com/shalikha/thesis/blob/main/src/distance_analyzer.py) (Distance and Overtaking), [`src/bbox_3d_generator.py`](https://github.com/shalikha/thesis/blob/main/src/bbox_3d_generator.py) (3D Box Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calibration["Calibration Tools"]
  node_calibration_entry["Calibration Runner<br/>[main.py]"]
  node_point_selector["Reference Point Selector<br/>[selectPoints.py]"]
  node_calibration_math["Calibration Mapping<br/>[calibration.py]"]
  node_stabilization["Video Stabilization<br/>[stabilization.py]"]
  node_roi["ROI Selection<br/>[roi.py]"]
  node_lookup["Calibration Lookup"]
end

subgraph group_geometry["Vehicle Geometry"]
  node_bbox_generator["3D Box Generator"]
  node_interactive_boxes["Interactive Box Refinement"]
end

subgraph group_analysis["Traffic Analysis"]
  node_speed_estimator["Speed Estimator<br/>[speed_estimator.py]"]
  node_distance_analyzer["Distance and Overtaking"]
  node_results["Analysis Outputs"]
end

subgraph group_evaluation["Alternative Methods"]
  node_comparison["Approach Comparison"]
  node_fallback["Contact-Point Fallback<br/>[fallback.py]"]
end

node_operator(("Video Analyst"))

node_operator -->|"runs calibration"| node_calibration_entry
node_calibration_entry -->|"selects points"| node_point_selector
node_calibration_entry -->|"builds lookup"| node_calibration_math
node_calibration_math -->|"generates mapping"| node_lookup
node_operator -->|"stabilizes video"| node_stabilization
node_stabilization -->|"uses ROI tool"| node_roi
node_operator -->|"estimates speed"| node_speed_estimator
node_speed_estimator -->|"processes frames"| node_bbox_generator
node_operator -->|"analyzes spacing"| node_distance_analyzer
node_distance_analyzer -->|"generates 3D boxes"| node_bbox_generator
node_operator -->|"refines boxes"| node_interactive_boxes
node_interactive_boxes -->|"detects vehicles"| node_bbox_generator
node_operator -->|"compares approaches"| node_comparison
node_operator -->|"runs fallback"| node_fallback
node_speed_estimator -->|"exports video"| node_results
node_distance_analyzer -->|"exports video"| node_results
node_fallback -->|"exports CSV"| node_results

click node_calibration_entry "https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/main.py"
click node_point_selector "https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/utils/selectPoints.py"
click node_calibration_math "https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/utils/calibration.py"
click node_stabilization "https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/stabilization.py"
click node_roi "https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/utils/roi.py"
click node_lookup "https://github.com/shalikha/thesis/blob/main/data/calibration-lookup-table.npy"
click node_bbox_generator "https://github.com/shalikha/thesis/blob/main/src/bbox_3d_generator.py"
click node_interactive_boxes "https://github.com/shalikha/thesis/blob/main/src/interactive_3d_bbox.py"
click node_speed_estimator "https://github.com/shalikha/thesis/blob/main/src/speed_estimator.py"
click node_distance_analyzer "https://github.com/shalikha/thesis/blob/main/src/distance_analyzer.py"
click node_comparison "https://github.com/shalikha/thesis/blob/main/src/compare_all_approaches.py"
click node_fallback "https://github.com/shalikha/thesis/blob/main/src/fallback.py"
click node_results "https://github.com/shalikha/thesis/tree/main/output"

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_calibration_entry,node_point_selector,node_calibration_math,node_stabilization,node_roi,node_lookup toneBlue
class node_bbox_generator,node_interactive_boxes toneAmber
class node_speed_estimator,node_distance_analyzer,node_results toneMint
class node_comparison,node_fallback toneRose
class node_operator toneIndigo
```

## Components

### Calibration Tools

- [Calibration Runner](https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/main.py): `utils/calibration_tool/main.py`
- [Reference Point Selector](https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/utils/selectPoints.py): `utils/calibration_tool/utils/selectPoints.py`
- [Calibration Mapping](https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/utils/calibration.py): `utils/calibration_tool/utils/calibration.py`
- [Video Stabilization](https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/stabilization.py): `utils/calibration_tool/stabilization.py`
- [ROI Selection](https://github.com/shalikha/thesis/blob/main/utils/calibration_tool/utils/roi.py): `utils/calibration_tool/utils/roi.py`
- [Calibration Lookup](https://github.com/shalikha/thesis/blob/main/data/calibration-lookup-table.npy): `data/calibration-lookup-table.npy`

### Vehicle Geometry

- [3D Box Generator](https://github.com/shalikha/thesis/blob/main/src/bbox_3d_generator.py): `src/bbox_3d_generator.py`
- [Interactive Box Refinement](https://github.com/shalikha/thesis/blob/main/src/interactive_3d_bbox.py): `src/interactive_3d_bbox.py`

### Traffic Analysis

- [Speed Estimator](https://github.com/shalikha/thesis/blob/main/src/speed_estimator.py): `src/speed_estimator.py`
- [Distance and Overtaking](https://github.com/shalikha/thesis/blob/main/src/distance_analyzer.py): `src/distance_analyzer.py`
- [Analysis Outputs](https://github.com/shalikha/thesis/tree/main/output): `output`

### Alternative Methods

- [Approach Comparison](https://github.com/shalikha/thesis/blob/main/src/compare_all_approaches.py): `src/compare_all_approaches.py`
- [Contact-Point Fallback](https://github.com/shalikha/thesis/blob/main/src/fallback.py): `src/fallback.py`

### Other components

- **Video Analyst**

## Connections

- Video Analyst → Calibration Runner: runs calibration (evidence: `README.md`)
- Calibration Runner → Reference Point Selector: selects points (evidence: `utils/calibration_tool/main.py`)
- Calibration Runner → Calibration Mapping: builds lookup (evidence: `utils/calibration_tool/main.py`)
- Calibration Mapping → Calibration Lookup: generates mapping
- Video Analyst → Video Stabilization: stabilizes video (evidence: `README.md`)
- Video Stabilization → ROI Selection: uses ROI tool (evidence: `utils/calibration_tool/stabilization.py`)
- Video Analyst → Speed Estimator: estimates speed (evidence: `README.md`)
- Speed Estimator → 3D Box Generator: processes frames (evidence: `src/speed_estimator.py`)
- Video Analyst → Distance and Overtaking: analyzes spacing (evidence: `README.md`)
- Distance and Overtaking → 3D Box Generator: generates 3D boxes (evidence: `src/distance_analyzer.py`)
- Video Analyst → Interactive Box Refinement: refines boxes (evidence: `README.md`)
- Interactive Box Refinement → 3D Box Generator: detects vehicles (evidence: `src/interactive_3d_bbox.py`)
- Video Analyst → Approach Comparison: compares approaches (evidence: `README.md`)
- Video Analyst → Contact-Point Fallback: runs fallback (evidence: `README.md`)
- Speed Estimator → Analysis Outputs: exports video (evidence: `README.md`)
- Distance and Overtaking → Analysis Outputs: exports video (evidence: `README.md`)
- Contact-Point Fallback → Analysis Outputs: exports CSV (evidence: `README.md`)
