# sasha071201/tensorflow-lite-object-detection architecture

> Architecture diagram of the GitHub repository sasha071201/tensorflow-lite-object-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sasha071201/tensorflow-lite-object-detection
- Repository: https://github.com/sasha071201/tensorflow-lite-object-detection

## Overview

This repository is a small utility toolkit around a TensorFlow Lite object-detection workflow. It does not contain a full application or model codebase; instead, it appears to focus on preparing data and evaluating detection results for an external training/inference pipeline.

1. Repository purpose  
The repo is centered on dataset preparation and evaluation for object detection, likely as support code for TensorFlow / TensorFlow Lite models.

2. Main boundary: data-prep utilities only  
All executable logic is under `util_scripts/`. There are no model definitions, serving components, UI layers, or deployment manifests in the tree provided.

3. Input data boundary  
The scripts likely consume a labeled image dataset plus annotation metadata. The exact annotation format is not shown, but the presence of CSV and TFRecord generators suggests the source data is first normalized into tabular form.

4. Dataset splitting subsystem  
`util_scripts/train_val_test_split.py` is the partitioning step. Its role is to divide the dataset into training, validation, and test subsets, which is the first stage in the pipeline and a clear architectural boundary between raw data and model-ready data.

5. Annotation normalization subsystem  
`util_scripts/create_csv.py` likely converts annotation data into a CSV representation. In an object-detection pipeline, this usually serves as an intermediate canonical format that is easier to validate, inspect, and transform.

6. TFRecord generation subsystem  
`util_scripts/create_tfrecord.py` is the TensorFlow-specific packaging step. TFRecord is the input format commonly used by TensorFlow Object Detection workflows, so this script is the handoff point from generic dataset metadata into TensorFlow training input.

7. Evaluation subsystem  
`util_scripts/calculate_map_cartucho.py` appears to compute mAP-style detection metrics, probably using the “Cartucho” implementation or a variant of it. This suggests a separate evaluation path from training, used to score predictions against ground truth.

8. End-to-end data flow  
The likely flow is: raw images + annotations -> split into train/val/test -> transform annotations to CSV -> convert to TFRecord -> train/evaluate object detector externally -> compute detection metrics with the mAP script.

9. External runtime assumptions  
Because the repo is named for TensorFlow Lite, these utilities probably support a broader TensorFlow/TFLite object-detection pipeline, but the actual model training, export to TFLite, and runtime inference are not present here.

10. Architectural role of the scripts  
Each script is a one-purpose batch utility rather than a service or library module. The repository is therefore best diagrammed as a preprocessing and evaluation layer feeding an external ML training pipeline.

11. Likely integration points  
The key integration boundary is file-based: images, annotations, CSVs, TFRecords, and prediction outputs. There is no evidence of network APIs, databases, queues, or long-running workers in the provided tree.

12. What to show in an architecture diagram  
A diagram should emphasize the linear dataset pipeline, the TensorFlow-specific TFRecord boundary, and the separate evaluation step for mAP. It should also mark the absence of training/inference code in this repo, since those likely live elsewhere.

Main entry points: [`util_scripts/calculate_map_cartucho.py`](https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/calculate_map_cartucho.py) (Calculate mAP), [`util_scripts/train_val_test_split.py`](https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/train_val_test_split.py) (Split data), [`util_scripts/create_csv.py`](https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/create_csv.py) (Create CSV), [`util_scripts/create_tfrecord.py`](https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/create_tfrecord.py) (Create TFRecord)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_util_scripts["Utility scripts"]
  node_util_scripts_train_val_test_split_py["Split data<br/>python script"]
  node_util_scripts_create_csv_py["Create CSV<br/>python script<br/>[create_csv.py]"]
  node_util_scripts_create_tfrecord_py["Create TFRecord<br/>python script<br/>[create_tfrecord.py]"]
  node_util_scripts_calculate_map_cartucho_py["Calculate mAP<br/>python script"]
end

subgraph group_external["External pipeline"]
  node_raw_dataset[("Raw dataset<br/>data source")]
  node_split_subsets[("Train/val/test<br/>dataset split")]
  node_csv_annotations["Annotation CSV<br/>normalized metadata"]
  node_tfrecords["TFRecords<br/>training input"]
  node_external_trainer["Trainer<br/>external ML pipeline"]
  node_predictions["Predictions<br/>inference outputs"]
  node_map_report["mAP report<br/>evaluation metrics"]
end

node_raw_dataset -->|"input"| node_util_scripts_train_val_test_split_py
node_util_scripts_train_val_test_split_py -->|"outputs"| node_split_subsets
node_split_subsets -->|"annotate"| node_util_scripts_create_csv_py
node_util_scripts_create_csv_py -->|"writes"| node_csv_annotations
node_csv_annotations -->|"feed"| node_util_scripts_create_tfrecord_py
node_util_scripts_create_tfrecord_py -->|"writes"| node_tfrecords
node_tfrecords -->|"train"| node_external_trainer
node_external_trainer -->|"infer"| node_predictions
node_raw_dataset -->|"ground truth"| node_util_scripts_calculate_map_cartucho_py
node_predictions -->|"predictions"| node_util_scripts_calculate_map_cartucho_py
node_util_scripts_calculate_map_cartucho_py -->|"reports"| node_map_report

click node_util_scripts_train_val_test_split_py "https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/train_val_test_split.py"
click node_util_scripts_create_csv_py "https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/create_csv.py"
click node_util_scripts_create_tfrecord_py "https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/create_tfrecord.py"
click node_util_scripts_calculate_map_cartucho_py "https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/calculate_map_cartucho.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_util_scripts_train_val_test_split_py,node_util_scripts_create_csv_py,node_util_scripts_create_tfrecord_py,node_util_scripts_calculate_map_cartucho_py toneBlue
class node_raw_dataset,node_split_subsets,node_csv_annotations,node_tfrecords,node_external_trainer,node_predictions,node_map_report toneAmber
```

## Components

### Utility scripts

Batch preprocessing and evaluation scripts in this repository.

- [Split data](https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/train_val_test_split.py): python script · Divides the dataset into train, validation, and test subsets. · `util_scripts/train_val_test_split.py`
- [Create CSV](https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/create_csv.py): python script · Converts annotation data into a CSV intermediate format. · `util_scripts/create_csv.py`
- [Create TFRecord](https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/create_tfrecord.py): python script · Packages CSV or annotation data into TensorFlow TFRecord files. · `util_scripts/create_tfrecord.py`
- [Calculate mAP](https://github.com/sasha071201/tensorflow-lite-object-detection/blob/master/util_scripts/calculate_map_cartucho.py): python script · Computes detection evaluation metrics using a Cartucho-style mAP workflow. · `util_scripts/calculate_map_cartucho.py`

### External pipeline

Inputs and outputs that live outside this repo, including datasets and model training/inference.

- **Raw dataset**: data source · Labeled images plus annotation metadata consumed by the utilities.
- **Train/val/test**: dataset split · Partitioned dataset subsets produced by the split step.
- **Annotation CSV**: normalized metadata · Tabular intermediate representation of detection annotations.
- **TFRecords**: training input · TensorFlow-ready serialized records used by downstream training.
- **Trainer**: external ML pipeline · Training/export workflow that is not implemented in this repository.
- **Predictions**: inference outputs · Model detections produced by the external pipeline for evaluation.
- **mAP report**: evaluation metrics · Detection quality metrics computed from predictions and ground truth.

## Connections

- Raw dataset → Split data: input · Dataset and annotations are fed into the splitting step.
- Split data → Train/val/test: outputs · Produces train, validation, and test partitions.
- Train/val/test → Create CSV: annotate · Split data is normalized into CSV form.
- Create CSV → Annotation CSV: writes · Emits a canonical CSV annotation dataset.
- Annotation CSV → Create TFRecord: feed · CSV annotations are converted into TensorFlow records.
- Create TFRecord → TFRecords: writes · Produces TFRecord files for training input.
- TFRecords → Trainer: train · Downstream training consumes TFRecords outside this repo.
- Trainer → Predictions: infer · Trained model outputs detections for evaluation.
- Raw dataset → Calculate mAP: ground truth · Ground truth annotations are used when scoring detections.
- Predictions → Calculate mAP: predictions · Detection outputs are evaluated against the ground truth.
- Calculate mAP → mAP report: reports · Produces mAP-style evaluation metrics and summaries.