# patlevin/face-detection-tflite architecture

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

- Interactive diagram: https://gitdiagram.com/patlevin/face-detection-tflite
- Repository: https://github.com/patlevin/face-detection-tflite

## Overview

##### Project type and purpose
- This is an open-source Python library (face-detection-tflite) that re-implements parts of Google’s MediaPipe face and iris detection models in pure Python.
- It provides a simple API for:
- Loading a TFLite model (several variants for front/back cameras and different ranges)
- Running inference on an image (via Numpy + PIL + TFLite)
- Post-processing (non-max suppression, coordinate transforms, landmark extraction)

##### File structure
Top-level:
- README, setup.py, pyproject.toml, etc. – packaging/configuration
- docs/ – user tutorials and examples
- fdlite/ – core library code and data

fdlite/:
- data/ – shipped .tflite model files and auxiliary data (camdb.csv/txt)
- face_detection.py, face_landmark.py, iris_landmark.py – model wrappers
- nms.py – non-max suppression
- transform.py – coordinate conversions between image and model space
- render.py – conversion of detections into drawable primitives
- exif.py – image orientation handling
- types.py – definitions of Detection, Landmark, etc.
- examples/ – sample scripts (e.g. iris_recoloring.py)
- errors.py – custom exception classes

##### Extract additional insights from README
- Dependencies: numpy, Pillow, TFLite runtime
- No protobuf graphs; lightweight, easily introspectable pipeline
- Models: five face-detection variants + landmark and iris detectors

##### Main components & interactions
A. Model Loader & Inference
- FaceDetection, FaceLandmark, IrisLandmark classes
- Internally: select .tflite file → initialize TFLite interpreter → allocate tensors

B. Preprocessing
- exif.py reads orientation; transform.py resizes / normalizes image → Numpy array

C. Inference
- Numpy array → TFLite interpreter invoke() → raw output tensors

D. Post-processing
- nms.py performs non-max suppression on raw detections
- types.py packages results into Python objects

E. Rendering
- detections_to_render_data() & render_to_image() in render.py

F. Examples & CLI
- example scripts in fdlite/examples/ demonstrate usage
- docs/tutorial.md explains end-to-end examples

##### Architectural patterns & design principles
- Modular separation:
- Loader/Inference ↔ Preprocess ↔ Postprocess ↔ Rendering
- Clear layer boundaries: each step is a pure function or class method
- Minimal external dependencies: only numpy, PIL, TFLite runtime
- Extensibility: add new models by dropping .tflite into data/ and wrapping

##### Elements
- Model Loader & TFLite Interpreter
- Preprocessing (exif + transform)
- Post-processing (nms + transform)
- Data types (types.py)
- Rendering (render.py)
- Data store (fdlite/data/*.tflite)
- External dependencies: Numpy, PIL, TFLite Runtime
- Image file → PIL → Preprocess → Interpreter → Raw tensors → NMS → Detections → Render → Output image
- Orange: external libraries

##### Detail and clarity
- Core modules vs. resources vs. external libs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        US["User Script\n(fdlite/examples/iris_recoloring.py)"]:::core
    end
    click US "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/examples/iris_recoloring.py"

    %% API Layer
    subgraph "API Layer"
        FD["FaceDetection\n(face_detection.py)"]:::core
        FL["FaceLandmark\n(face_landmark.py)"]:::core
        IL["IrisLandmark\n(iris_landmark.py)"]:::core
    end
    click FD "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/face_detection.py"
    click FL "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/face_landmark.py"
    click IL "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/iris_landmark.py"

    %% Preprocessing Layer
    subgraph "Preprocessing"
        EX["EXIF Handler\n(exif.py)"]:::core
        TR["Transform\n(transform.py)"]:::core
    end
    click EX "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/exif.py"
    click TR "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/transform.py"

    %% Interpreter
    TI["TFLite Interpreter"]:::core

    %% Post-processing Layer
    subgraph "Post-processing"
        NMS["Non-Max Suppression\n(nms.py)"]:::core
        TPTR["Transform\n(transform.py)"]:::core
        TY["Data Types\n(types.py)"]:::core
    end
    click NMS "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/nms.py"
    click TPTR "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/transform.py"
    click TY "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/types.py"

    %% Rendering Layer
    subgraph "Rendering"
        RD["Renderer\n(render.py)"]:::core
    end
    click RD "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/render.py"

    %% Data Store
    subgraph "Data Store\n(fdlite/data)" 
        M1["face_detection_back.tflite"]:::resource
        M2["face_detection_front.tflite"]:::resource
        M3["face_detection_full_range.tflite"]:::resource
        M4["face_detection_full_range_sparse.tflite"]:::resource
        M5["face_detection_short_range.tflite"]:::resource
        M6["face_landmark.tflite"]:::resource
        M7["iris_landmark.tflite"]:::resource
        M8["camdb.csv"]:::resource
        M9["camdb.txt"]:::resource
    end
    click M1 "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/data/face_detection_back.tflite"
    click M2 "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/data/face_detection_front.tflite"
    click M3 "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/data/face_detection_full_range.tflite"
    click M4 "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/data/face_detection_full_range_sparse.tflite"
    click M5 "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/data/face_detection_short_range.tflite"
    click M6 "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/data/face_landmark.tflite"
    click M7 "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/data/iris_landmark.tflite"
    click M8 "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/data/camdb.csv"
    click M9 "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/data/camdb.txt"

    %% Examples & Docs
    subgraph "Examples & Tutorials"
        EXS["iris_recoloring.py"]:::core
        DOC["Tutorial\n(docs/tutorial.md)"]:::core
    end
    click EXS "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/examples/iris_recoloring.py"
    click DOC "https://github.com/patlevin/face-detection-tflite/blob/main/docs/tutorial.md"

    %% Error Handling
    EH["Errors\n(errors.py)"]:::core
    click EH "https://github.com/patlevin/face-detection-tflite/blob/main/fdlite/errors.py"

    %% Output
    OUT["Output Image / Data"]:::core

    %% External Dependencies
    subgraph "External Libraries"
        NP["NumPy"]:::external
        PL["Pillow"]:::external
        TRT["TFLite Runtime"]:::external
    end

    %% Data Flow
    US -->|"calls API"| FD
    US -->|"calls API"| FL
    US -->|"calls API"| IL

    FD -->|"reads orientation"| EX
    FL --> EX
    IL --> EX

    EX -->|"RGB array"| TR
    TR -->|"formatted tensor input"| TI

    M1 & M2 & M3 & M4 & M5 & M6 & M7 --> TI

    TI -->|"raw tensor outputs"| NMS
    NMS -->|"filtered detections"| TPTR
    TPTR -->|"mapped coords"| TY
    TY -->|"Detection objects"| RD
    RD -->|"drawn image"| OUT

    %% External usage
    NP -.-> EX
    NP -.-> TR
    NP -.-> NMS
    NP -.-> TY
    PL -.-> RD
    TRT -.-> TI

    %% Legend
    subgraph Legend
        C1["Core Modules"]:::core
        C2["Resources"]:::resource
        C3["External"]:::external
    end

    classDef core fill:#AED6F1,stroke:#1F618D,color:#1B2631;
    classDef resource fill:#ABEBC6,stroke:#196F3D,color:#1B2631;
    classDef external fill:#F5B041,stroke:#B9770E,color:#1B2631;
```
