# bconstanzo/phantom architecture

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

- Interactive diagram: https://gitdiagram.com/bconstanzo/phantom
- Repository: https://github.com/bconstanzo/phantom

## Overview

- Alignment and Enhancement (phantom/align.py and phantom/enhance.py)
- Face Processing (phantom/faces/ folder with alignment and face detection routines)
- Geometry (phantom/geometry.py)
- Measures (phantom/measures/ folder for calibration and measurement)
- Similarity (phantom/similarity.py)
- Utilities (phantom/utils.py)
- Video Processing (phantom/video.py)
- Models: The phantom/models folder contains various pre-trained model files (ONNX, .dat, etc.) used by the algorithms in the library.
- Example Applications: “examples” directory contains demonstration scripts (e.g., cam_detect.py, cam_morph.py, cluster.py, etc.) that show how the library can be integrated in real-world forensic imaging scenarios.
- Tools: The “tools” directory includes specialized utilities and scripts that work with or extend the core library. These are broken into further discrete components:
- Descriptors (for object matching or image descriptors)
- Gender classification utilities (with training and testing scripts)
- Object Detector examples and associated training data

##### Relationships and Interactions
- Example scripts and Tools invoke the Core Library functions.
- Core Library modules load and apply Models for tasks such as face detection, gender classification, etc.
- Tools for “gender” and “object detector” likely call on functions within the Core Library and possibly use external machine learning models (located in the models folder).

##### Architectural Patterns and Design Principles
- Modular Structure: Emphasize the separation into discrete modules (faces, measures, video, etc.) which simplifies maintenance and extension.
- Pipeline/Flow: The image (or video) processing flow can be shown as a pipeline from image input to various processing steps (alignment, face detection, enhancement, measurement) and then to output or analysis.
- Extensibility: The existence of an examples folder and separate Tools directory highlights that the system is designed to be used as a library as well as extended via auxiliary scripts.
- Abstraction Layers: Illustrate that the Core Library abstracts lower-level image processing tasks and model operations from higher-level application code found in examples/tools.

##### Relevant Technologies
- Python version compatibility is noted, so include a note that the system runs on Python 3.10+ (with backwards support for older versions).
- Libraries that are central to the process: NumPy, SciPy, OpenCV, matplotlib, scikit-learn, and dlib. Optionally, denote where ONNX plays a role in loading some of the model files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        D1["OpenCV"]:::ext
        D2["dlib"]:::ext
        D3["scikit-learn"]:::ext
        D4["NumPy"]:::ext
        D5["SciPy"]:::ext
        D6["matplotlib"]:::ext
        D7["ONNX"]:::ext
    end

    %% Usage Components
    E["Examples"]:::examples
    subgraph "Tools"
        T1["Descriptors"]:::tools
        T2["Gender Classification"]:::tools
        T3["Object Detector"]:::tools
    end

    %% Core Library with Modules
    subgraph "Core Library: phantom"
        P1["Phantom Core"]:::core
        P2["Align"]:::module
        P3["Enhance"]:::module
        P4["Face Processing"]:::module
        P5["Geometry"]:::module
        P6["Measures"]:::module
        P7["Similarity"]:::module
        P8["Utilities"]:::module
        P9["Video Processing"]:::module
    end

    %% Models Component
    M["Models"]:::models

    %% Internal module breakdown of Core Library
    P1 -->|"branch"| P2
    P1 -->|"branch"| P3
    P1 -->|"branch"| P4
    P1 -->|"branch"| P5
    P1 -->|"branch"| P6
    P1 -->|"branch"| P7
    P1 -->|"branch"| P8
    P1 -->|"branch"| P9

    %% Data flows and dependencies
    %% External Dependencies provide libraries to Phantom Core
    D1 -->|"provide"| P1
    D2 -->|"provide"| P1
    D3 -->|"provide"| P1
    D4 -->|"provide"| P1
    D5 -->|"provide"| P1
    D6 -->|"provide"| P1
    D7 -->|"support"| M

    %% Usage components invoke functions from Phantom Core
    E -->|"invoke"| P1
    T1 -->|"invoke"| P1
    T2 -->|"invoke"| P1
    T3 -->|"invoke"| P1

    %% Core Library loads models
    P1 -->|"load_models"| M

    %% Click Events
    click P1 "https://github.com/bconstanzo/phantom/tree/master/phantom/"
    click P2 "https://github.com/bconstanzo/phantom/blob/master/phantom/align.py"
    click P3 "https://github.com/bconstanzo/phantom/blob/master/phantom/enhance.py"
    click P4 "https://github.com/bconstanzo/phantom/tree/master/phantom/faces/"
    click P5 "https://github.com/bconstanzo/phantom/blob/master/phantom/geometry.py"
    click P6 "https://github.com/bconstanzo/phantom/tree/master/phantom/measures/"
    click P7 "https://github.com/bconstanzo/phantom/blob/master/phantom/similarity.py"
    click P8 "https://github.com/bconstanzo/phantom/blob/master/phantom/utils.py"
    click P9 "https://github.com/bconstanzo/phantom/blob/master/phantom/video.py"
    click M "https://github.com/bconstanzo/phantom/tree/master/phantom/models/"
    click E "https://github.com/bconstanzo/phantom/tree/master/examples/"
    click T1 "https://github.com/bconstanzo/phantom/tree/master/tools/descriptors/"
    click T2 "https://github.com/bconstanzo/phantom/tree/master/tools/gender/"
    click T3 "https://github.com/bconstanzo/phantom/tree/master/tools/object detector/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef module fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef models fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef examples fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef tools fill:#F9EBEA,stroke:#C0392B,stroke-width:2px;
    classDef ext fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
