# thaitom/tdetectors architecture

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

- Interactive diagram: https://gitdiagram.com/thaitom/tdetectors
- Repository: https://github.com/thaitom/tdetectors

## Overview

##### Project Type and Purpose
- This is a **domain-specific computer vision pipeline** (not a typical web full-stack app).
- Purpose: ingest multi-camera video streams, run a cascade of CV models (vehicle & plate detection, plate OCR, vehicle re-identification, multi-object tracking), and expose results (video output, clusters) via scripts and an API.

##### File Structure
- Top-level entry points:
- `main.py` (root)
- `src/main.py` & `src/Vehicle_and_License.py` & `src/tracking.py` (alternative CLI wrappers)
- API layer: `api/routes.py`
- Configuration: `config/global_config.example.yml`
- Data ingestion / preparation: `data/…` (multiple datasets, camera lists, raw data scripts)
- Model definitions & training: `models/MOT` (BoT-SORT config),
`models/ReID` (triplet sampler, loss, scheduler, embeddings),
`models/modelLicensePlate` (YOLOv12 detection & OCR)
- Utilities: `utils/` (crop & extract helpers)
- Demo assets: `demo/` (images/videos)

##### Extract Key Architectural Insights from the README
- Pipeline stages are optimized with **Intel OpenVINO**
- YOLOv12 used for detection, CCT for OCR, multi-branch networks for Re-ID, BoT-SORT for tracking
- CLI usage and Python API both supported

##### Main Components & Their Interactions
a. **External Inputs**
- Traffic cameras (live RTSP or video files)
- Pre-collected datasets (Roboflow, MTMC, Vehicle-1M, etc.)
b. **Data Ingestion & Pre-processing**
- `data/…` scripts and `utils/crop_and_extract.py` prepare frames, normalize, annotate
- Configuration loader (`config/global_config.yml`) defines camera lists, model paths
c. **Inference Pipeline**
1. **Vehicle & Plate Detection** (YOLOv12 via OpenVINO)
2. **License Plate Recognition** (CCT model)
3. **Feature Embedding** (Re-ID network: triplet sampler, multi-branch learner)
4. **Multi-Object Tracking** (BoT-SORT algorithm)
d. **API Server** (`api/routes.py`)
- Exposes endpoints to submit video streams / frames and retrieve JSON results or annotated video
e. **Output & Storage**
- Annotated videos in `demo/videos` or `output/`
- Re-ID clusters via `models/ReID/cluster_from_camera_hcm.py`
- Logs & metrics via TensorBoard (`models/ReID/tensorboard_log.py`)
f. **CLI & Demo** (`src/…` wrappers, `main.py` for local testing)

##### Architectural Patterns & Design Principles
- **Pipeline (staged)**: each stage is a clear module (Detection → OCR → Embedding → Tracking)
- **Modularity/Separation of Concerns**: separate folders for data, models, API, utilities
- **Configuration-driven**: YAML configs to swap cameras or model weights without code changes
- **Optional Microservice Split**: detection and re-ID/tracking can be extracted to independent services behind the API

##### Final Checklist
- [ ] All major components represented (Camera Inputs, Ingestion, Detection, OCR, Re-ID, Tracking, API, Storage)
- [ ] Configuration service or file store noted

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Inputs
    subgraph "External Inputs"
        CameraCam["RTSP Feeds / Video Files"]:::external
        DatasetRoboflow["Pre-collected Datasets"]:::external
    end

    %% Data Ingestion & Pre-processing
    subgraph "Data Ingestion & Pre-processing"
        CameraInfo["get_info.py"]:::service
        CameraMain["main.py"]:::service
        LP_RawRoboflow["raw_data_from_roboflow.py (LicensePlateDataset)"]:::service
        LP_Train["train.py (LicensePlateDataset)"]:::service
        MTMC_Read["read_data_mtmc.py"]:::service
        Veh_RawRoboflow["raw_data_from_roboflow.py (VehicleDataset)"]:::service
        CropExtract["crop_and_extract.py"]:::service
        ConfigLoader["global_config.example.yml"]:::datastore
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        Detection["YOLOv12 Detector (OpenVINO)"]:::service
        OCR["License Plate OCR (CCT)"]:::service
        Embedding["Re-ID Embedding Service"]:::service
        Tracking["BoT-SORT Tracker"]:::service
    end

    %% API & CLI Access
    subgraph "API & CLI Access"
        API["API Server"]:::service
        CLI_MainRoot["main.py (root)"]:::service
        CLI_srcMain["src/main.py"]:::service
        CLI_VL["src/Vehicle_and_License.py"]:::service
        CLI_Track["src/tracking.py"]:::service
    end

    %% Output & Storage
    subgraph "Output & Storage"
        AnnotatedVids["Annotated Videos"]:::datastore
        ReID_Cluster["cluster_from_camera_hcm.py"]:::service
        Tensorboard["tensorboard_log.py"]:::service
    end

    %% Data Flows
    CameraCam --> CameraInfo --> CameraMain --> Detection
    DatasetRoboflow --> LP_RawRoboflow --> LP_Train --> CropExtract --> Detection
    MTMC_Read --> CropExtract
    Veh_RawRoboflow --> CropExtract
    CropExtract --> Detection
    ConfigLoader -.-> CameraInfo
    ConfigLoader -.-> CameraMain
    ConfigLoader -.-> LP_RawRoboflow
    ConfigLoader -.-> LP_Train
    ConfigLoader -.-> MTMC_Read
    ConfigLoader -.-> Veh_RawRoboflow
    ConfigLoader -.-> CropExtract

    Detection --> OCR --> Embedding --> Tracking
    Tracking --> AnnotatedVids
    Tracking --> ReID_Cluster
    Embedding --> Tensorboard
    Tracking --> API
    API --> AnnotatedVids
    API --> ReID_Cluster

    CLI_MainRoot --> Detection
    CLI_srcMain --> Detection
    CLI_VL --> Detection
    CLI_Track --> Tracking

    %% Click Events for Ingestion
    click CameraInfo "https://github.com/thaitom/tdetectors/blob/master/data/cameraHCM/get_info.py"
    click CameraMain "https://github.com/thaitom/tdetectors/blob/master/data/cameraHCM/main.py"
    click LP_RawRoboflow "https://github.com/thaitom/tdetectors/blob/master/data/LicensePlateDataset/raw_data_from_roboflow.py"
    click LP_Train "https://github.com/thaitom/tdetectors/blob/master/data/LicensePlateDataset/train.py"
    click MTMC_Read "https://github.com/thaitom/tdetectors/blob/master/data/MTMC/read_data_mtmc.py"
    click Veh_RawRoboflow "https://github.com/thaitom/tdetectors/blob/master/data/VehicleDataset/raw_data_from_roboflow.py"
    click CropExtract "https://github.com/thaitom/tdetectors/blob/master/utils/crop_and_extract.py"
    click ConfigLoader "https://github.com/thaitom/tdetectors/blob/master/config/global_config.example.yml"

    %% Click Events for Detection & OCR
    click Detection "https://github.com/thaitom/tdetectors/blob/master/models/modelLicensePlate/modelCompare.py"
    click Detection "https://github.com/thaitom/tdetectors/blob/master/models/modelLicensePlate/runs/detect/train/weights/*.xml"
    click Detection "https://github.com/thaitom/tdetectors/blob/master/models/modelLicensePlate/runs/detect/train/weights/*.bin"

    %% Click Events for Embedding
    click Embedding "https://github.com/thaitom/tdetectors/blob/master/models/ReID/models/models.py"
    click Embedding "https://github.com/thaitom/tdetectors/blob/master/models/ReID/data/triplet_sampler.py"
    click Embedding "https://github.com/thaitom/tdetectors/blob/master/models/ReID/loss/losses.py"
    click Embedding "https://github.com/thaitom/tdetectors/blob/master/models/ReID/lr_scheduler/sche_optim.py"
    click Embedding "https://github.com/thaitom/tdetectors/blob/master/models/ReID/processor.py"
    click Embedding "https://github.com/thaitom/tdetectors/blob/master/models/ReID/predict.py"

    %% Click Events for Tracking
    click Tracking "https://github.com/thaitom/tdetectors/blob/master/models/MOT/botsort.yaml"
    click Tracking "https://github.com/thaitom/tdetectors/blob/master/models/MOT/test.py"

    %% Click Events for API & CLI & Output
    click API "https://github.com/thaitom/tdetectors/blob/master/api/routes.py"
    click CLI_MainRoot "https://github.com/thaitom/tdetectors/blob/master/main.py"
    click CLI_srcMain "https://github.com/thaitom/tdetectors/blob/master/src/main.py"
    click CLI_VL "https://github.com/thaitom/tdetectors/blob/master/src/Vehicle_and_License.py"
    click CLI_Track "https://github.com/thaitom/tdetectors/blob/master/src/tracking.py"
    click AnnotatedVids "https://github.com/thaitom/tdetectors/tree/master/demo/videos/"
    click ReID_Cluster "https://github.com/thaitom/tdetectors/blob/master/models/ReID/cluster_from_camera_hcm.py"
    click Tensorboard "https://github.com/thaitom/tdetectors/blob/master/models/ReID/tensorboard_log.py"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef service fill:#88ccff,stroke:#333,stroke-width:1px
    classDef datastore fill:#ccff88,stroke:#333,stroke-width:1px
```
