# 25thmello/anrp_dip architecture

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

- Interactive diagram: https://gitdiagram.com/25thmello/anrp_dip
- Repository: https://github.com/25thmello/anrp_dip

## Overview

1. This repository is a single Python package, `anpr_tn`, centered on an end-to-end Automatic Number Plate Recognition pipeline for Tamil Nadu plates. The architecture is split into inference/runtime code, training code, and persisted data/artifacts.

2. The primary runtime entrypoint is `anpr_tn/main.py`. It orchestrates two modes: full evaluation over a prepared image set, and single-image inference. It also owns result writing and comparison against ground truth, so it is the main boundary between pipeline outputs and persisted evaluation artifacts.

3. The inference pipeline is explicitly three-stage:
   - Stage 1: `pipeline/stage1_detection.py` runs YOLO-based license plate detection.
   - Stage 2: `pipeline/stage2_enhancement.py` applies OpenCV preprocessing to produce OCR-friendly plate crops/candidates.
   - Stage 3: `pipeline/stage3_ocr.py` uses PaddleOCR to read text and then normalizes it toward the Tamil Nadu plate pattern.
   Data flows left-to-right through these stages: image input → detected plate region → enhanced candidates → recognized text.

4. `anpr_tn/config.py` is the central coordination point for filesystem paths, thresholds, and shared constants. Architecturally, it decouples the pipeline stages from hardcoded locations such as model files, datasets, evaluation metadata, and output directories.

5. Model assets are kept under `anpr_tn/models/`. The tree includes `yolo_best.pt` and `yolov8n.pt`, indicating the detector is based on Ultralytics YOLO weights. Detection is therefore a pretrained-model boundary, while OCR is handled by a separate external engine rather than being trained in this repo.

6. Training is isolated from inference in `anpr_tn/training/`. `training/train.py` and `training/data.yaml` define the detector training workflow, which consumes the YOLO-formatted dataset under `datasets/indian_lpr_yolo/`. This is a separate subsystem whose output is a detector checkpoint used by the runtime pipeline.

7. The dataset layout follows standard YOLO conventions: images and labels are separated into `train` and `val` partitions, with label cache files present. This indicates the training boundary expects object-detection annotations rather than OCR labels, reinforcing that the learned model is only for plate localization.

8. Evaluation inputs live under `metadata/tamil_nadu_eval/`, and the corresponding ground truth is stored in `metadata/ground_truth.csv`. The main runtime likely joins detector/OCR outputs with this ground truth to compute or record performance. This makes `metadata/` the evaluation contract for the pipeline.

9. Generated artifacts are written into `results/`, which is subdivided into `crops/`, `detections/`, and `enhanced/`, plus a `logs.csv`. That structure mirrors the three pipeline stages and is useful for diagramming where intermediate products are persisted between processing and evaluation.

10. The external technology boundaries are important: Python is the runtime, Ultralytics YOLO handles detection, OpenCV handles image enhancement, and PaddleOCR handles text recognition. The repository’s architecture is therefore a staged CV pipeline with a trained detector, deterministic preprocessing, and OCR-based text extraction, all coordinated by a thin orchestration layer in `main.py`.

Main entry points: [`anpr_tn/results`](https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/results) (Results), [`anpr_tn/main.py`](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/main.py) (Main), [`anpr_tn/pipeline/stage1_detection.py`](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/pipeline/stage1_detection.py) (Detect), [`anpr_tn/pipeline/stage2_enhancement.py`](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/pipeline/stage2_enhancement.py) (Enhance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>runtime orchestrator<br/>[main.py]"]
  node_config["Config<br/>shared paths<br/>[config.py]"]
  node_detect["Detect"]
  node_enhance["Enhance<br/>OpenCV preprocess"]
  node_ocr["OCR<br/>[stage3_ocr.py]"]
end

subgraph group_training["Training"]
  node_train["Train<br/>[train.py]"]
  node_data_yaml["Data YAML<br/>training config<br/>[data.yaml]"]
  node_dataset[("YOLO Dataset<br/>annotated images")]
end

subgraph group_data["Data & Artifacts"]
  node_yolo_weights[("YOLO Weights<br/>pretrained detector<br/>[yolo_best.pt]")]
  node_base_weights[("Base Weights<br/>model baseline<br/>[yolov8n.pt]")]
  node_eval_meta[("Eval Set<br/>evaluation images")]
  node_ground_truth["Ground Truth<br/>eval labels<br/>[ground_truth.csv]"]
  node_results[("Results<br/>output store")]
  node_crops["Crops"]
  node_detections["Detections<br/>prediction records"]
  node_enhanced_out["Enhanced<br/>preprocessed crops"]
  node_logs["Logs<br/>metrics csv<br/>[logs.csv]"]
end

node_main -->|"reads paths"| node_config
node_main -->|"runs stage 1"| node_detect
node_detect -->|"loads model"| node_yolo_weights
node_detect -->|"crops plates"| node_enhance
node_enhance -->|"feeds candidates"| node_ocr
node_ocr -->|"writes output"| node_results
node_detect -->|"writes detections"| node_results
node_enhance -->|"writes crops"| node_results
node_results -->|"contains"| node_crops
node_results -->|"contains"| node_detections
node_results -->|"contains"| node_enhanced_out
node_results -->|"contains"| node_logs
node_main -->|"evaluates on"| node_eval_meta
node_main -->|"compares with"| node_ground_truth
node_train -->|"uses config"| node_data_yaml
node_data_yaml -->|"points to"| node_dataset
node_train -.->|"produces"| node_yolo_weights
node_base_weights -.->|"initializes"| node_train

click node_main "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/main.py"
click node_config "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/config.py"
click node_detect "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/pipeline/stage1_detection.py"
click node_enhance "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/pipeline/stage2_enhancement.py"
click node_ocr "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/pipeline/stage3_ocr.py"
click node_yolo_weights "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/models/yolo_best.pt"
click node_base_weights "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/models/yolov8n.pt"
click node_eval_meta "https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/metadata/tamil_nadu_eval"
click node_ground_truth "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/metadata/ground_truth.csv"
click node_results "https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/results"
click node_crops "https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/results/crops"
click node_detections "https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/results/detections"
click node_enhanced_out "https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/results/enhanced"
click node_logs "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/results/logs.csv"
click node_train "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/training/train.py"
click node_data_yaml "https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/training/data.yaml"
click node_dataset "https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/datasets/indian_lpr_yolo"

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_main,node_config,node_detect,node_enhance,node_ocr toneBlue
class node_train,node_data_yaml,node_dataset toneAmber
class node_yolo_weights,node_base_weights,node_eval_meta,node_ground_truth,node_results,node_crops,node_detections,node_enhanced_out,node_logs toneMint
```

## Components

### Runtime

Inference, orchestration, and shared configuration

- [Main](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/main.py): runtime orchestrator · Entry point for single-image inference and batch evaluation; writes results and compares against ground truth · `anpr_tn/main.py`
- [Config](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/config.py): shared paths · Central filesystem, threshold, and constant coordination for the package · `anpr_tn/config.py`
- [Detect](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/pipeline/stage1_detection.py): YOLO detection · Stage 1 license-plate detection using Ultralytics YOLO weights · `anpr_tn/pipeline/stage1_detection.py`
- [Enhance](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/pipeline/stage2_enhancement.py): OpenCV preprocess · Stage 2 plate crop preprocessing and candidate enhancement · `anpr_tn/pipeline/stage2_enhancement.py`
- [OCR](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/pipeline/stage3_ocr.py): PaddleOCR normalize · Stage 3 text recognition and Tamil Nadu plate normalization · `anpr_tn/pipeline/stage3_ocr.py`

### Training

Detector training workflow and YOLO dataset

- [Train](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/training/train.py): YOLO training · Detector training entrypoint for the plate-localization model · `anpr_tn/training/train.py`
- [Data YAML](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/training/data.yaml): training config · YOLO dataset configuration for training and validation splits · `anpr_tn/training/data.yaml`
- [YOLO Dataset](https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/datasets/indian_lpr_yolo): annotated images · Train/val images and labels in YOLO detection format · `anpr_tn/datasets/indian_lpr_yolo`

### Data & Artifacts

Evaluation metadata, model weights, and generated outputs

- [YOLO Weights](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/models/yolo_best.pt): pretrained detector · Detector model assets used at runtime · `anpr_tn/models/yolo_best.pt`
- [Base Weights](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/models/yolov8n.pt): model baseline · Additional YOLO weight file present in the repo · `anpr_tn/models/yolov8n.pt`
- [Eval Set](https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/metadata/tamil_nadu_eval): evaluation images · Prepared evaluation image set used by the runtime pipeline · `anpr_tn/metadata/tamil_nadu_eval`
- [Ground Truth](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/metadata/ground_truth.csv): eval labels · CSV ground truth used for comparison and reporting · `anpr_tn/metadata/ground_truth.csv`
- [Results](https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/results): output store · Persisted detections, crops, enhanced images, and logs · `anpr_tn/results`
- [Crops](https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/results/crops): plate crops · Saved plate-region crops from detection · `anpr_tn/results/crops`
- [Detections](https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/results/detections): prediction records · Saved detection outputs and summaries · `anpr_tn/results/detections`
- [Enhanced](https://github.com/25thmello/anrp_dip/tree/main/anpr_tn/results/enhanced): preprocessed crops · Saved OCR-friendly intermediate images · `anpr_tn/results/enhanced`
- [Logs](https://github.com/25thmello/anrp_dip/blob/main/anpr_tn/results/logs.csv): metrics csv · Run logs and evaluation records · `anpr_tn/results/logs.csv`

## Connections

- Main → Config: reads paths · Main uses shared configuration for inputs, outputs, and thresholds
- Main → Detect: runs stage 1 · Main invokes the detection stage on each image
- Detect → YOLO Weights: loads model · Detection stage uses trained YOLO weights
- Detect → Enhance: crops plates · Detected plate regions are passed to preprocessing
- Enhance → OCR: feeds candidates · Enhanced plate crops are sent to OCR
- OCR → Results: writes output · Recognized text and normalized predictions are persisted
- Detect → Results: writes detections · Detection outputs are saved for inspection and evaluation
- Enhance → Results: writes crops · Preprocessed intermediate images are saved
- Results → Crops: contains · Crops are stored under the results directory
- Results → Detections: contains · Detection records are stored under the results directory
- Results → Enhanced: contains · Enhanced intermediates are stored under the results directory
- Results → Logs: contains · Run logs are stored alongside outputs
- Main → Eval Set: evaluates on · Batch evaluation reads prepared evaluation images
- Main → Ground Truth: compares with · Evaluation joins predictions against ground truth
- Train → Data YAML: uses config · Training is driven by YOLO dataset configuration
- Data YAML → YOLO Dataset: points to · Training config references the annotated dataset
- Train → YOLO Weights: produces · Training outputs the detector checkpoint used by runtime
- Base Weights → Train: initializes · Additional YOLO weights are present for training or baseline use
