# devthayron/parking-vision architecture

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

- Interactive diagram: https://gitdiagram.com/devthayron/parking-vision
- Repository: https://github.com/devthayron/parking-vision

## Overview

#### Purpose and principal workflow

Parking Vision classifies configured parking spaces as free or occupied in each frame of a video, then overlays the classifications and available-space count and saves a result video. The workflow is initiated when an operator runs `python main.py`; a separate operator-run calibration workflow defines the parking regions.

#### Components

##### Video processing
- **Operator** — **Path: null (external actor).** Runs the command-line application, can quit with `Q`, and may run the separate calibration command.
- **CLI runner** — **Path: `main.py`.** Loads the saved space definitions and orchestrates video capture, per-frame detection, overlays, display, and output writing.
- **Input video** — **Path: `media/video.mp4`.** Repository-provided video used as the documented default processing input.
- **Occupancy detector** — **Path: `detector.py`.** Converts frames to a filtered binary image, counts detected pixels within each configured bounding box, and classifies and annotates each space using the threshold.
- **Result video** — **Path: null (generated output).** The runner writes annotated frames to the configured output video; the README documents `media/video_result.mp4`.

##### Space calibration and state
- **Region calibration tool** — **Path: `setup_spaces.py`.** Lets an operator select parking-space rectangles from an image, assigns IDs, and saves the resulting definitions.
- **Space definitions** — **Path: `spaces.pkl`.** Pickled IDs and bounding boxes are the persistent input shared by calibration and video processing.

#### Relationships

- **Operator -> CLI runner:** starts the main workflow by running `python main.py`.
- **CLI runner -> Space definitions:** reads the serialized parking-space definitions before processing; reports an error and exits if the file is missing or invalid.
- **CLI runner -> Input video:** opens the configured video and reads frames until the video ends or the operator quits.
- **CLI runner -> Occupancy detector:** calls detection for each frame with the loaded space definitions.
- **Occupancy detector -> CLI runner:** returns the available-space count and processed image; it also annotates the input frame with per-space labels and status rectangles.
- **CLI runner -> Result video:** writes each annotated frame and displays it during processing.
- **Operator -> Region calibration tool:** starts the separate region-definition workflow by running `python setup_spaces.py`.
- **Region calibration tool -> Space definitions:** writes selected IDs and bounding boxes when at least one space is selected.

#### Coverage limits

The sampled source establishes the video-processing and calibration flows. The configured parking-image path is not present in the supplied tree, and the README’s alternative-video workflow is not traced beyond configuration; details of those inputs are therefore not established here.

Main entry points: [`main.py`](https://github.com/devthayron/parking-vision/blob/main/main.py) (CLI Runner), [`detector.py`](https://github.com/devthayron/parking-vision/blob/main/detector.py) (Occupancy Detector), [`setup_spaces.py`](https://github.com/devthayron/parking-vision/blob/main/setup_spaces.py) (Region Calibration), [`spaces.pkl`](https://github.com/devthayron/parking-vision/blob/main/spaces.pkl) (Space Definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_video_processing["Video Processing"]
  node_cli_runner["CLI Runner<br/>Application entry point"]
  node_input_video["Input Video<br/>Video file"]
  node_occupancy_detector["Occupancy Detector<br/>Frame processor"]
  node_result_video["Result Video<br/>Generated output"]
end

subgraph group_calibration_state["Calibration and State"]
  node_region_calibration["Region Calibration<br/>Calibration tool"]
  node_space_definitions[("Space Definitions<br/>Persistent state")]
end

node_operator(("Operator<br/>External actor"))

node_operator -->|"runs"| node_cli_runner
node_cli_runner -->|"reads"| node_space_definitions
node_cli_runner -->|"opens and reads"| node_input_video
node_cli_runner -->|"detects each frame"| node_occupancy_detector
node_occupancy_detector -->|"returns results"| node_cli_runner
node_cli_runner -->|"writes frames"| node_result_video
node_operator -->|"runs"| node_region_calibration
node_region_calibration -->|"writes"| node_space_definitions

click node_cli_runner "https://github.com/devthayron/parking-vision/blob/main/main.py"
click node_input_video "https://github.com/devthayron/parking-vision/blob/main/media/video.mp4"
click node_occupancy_detector "https://github.com/devthayron/parking-vision/blob/main/detector.py"
click node_region_calibration "https://github.com/devthayron/parking-vision/blob/main/setup_spaces.py"
click node_space_definitions "https://github.com/devthayron/parking-vision/blob/main/spaces.pkl"

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_cli_runner,node_input_video,node_occupancy_detector,node_result_video toneBlue
class node_region_calibration,node_space_definitions toneAmber
class node_operator toneIndigo
```

## Components

### Video Processing

- [CLI Runner](https://github.com/devthayron/parking-vision/blob/main/main.py): Application entry point · `main.py`
- [Input Video](https://github.com/devthayron/parking-vision/blob/main/media/video.mp4): Video file · `media/video.mp4`
- [Occupancy Detector](https://github.com/devthayron/parking-vision/blob/main/detector.py): Frame processor · `detector.py`
- **Result Video**: Generated output

### Calibration and State

- [Region Calibration](https://github.com/devthayron/parking-vision/blob/main/setup_spaces.py): Calibration tool · `setup_spaces.py`
- [Space Definitions](https://github.com/devthayron/parking-vision/blob/main/spaces.pkl): Persistent state · `spaces.pkl`

### Other components

- **Operator**: External actor

## Connections

- Operator → CLI Runner: runs
- CLI Runner → Space Definitions: reads
- CLI Runner → Input Video: opens and reads
- CLI Runner → Occupancy Detector: detects each frame
- Occupancy Detector → CLI Runner: returns results
- CLI Runner → Result Video: writes frames
- Operator → Region Calibration: runs
- Region Calibration → Space Definitions: writes