# jeffheaton/dynaface architecture

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

- Interactive diagram: https://gitdiagram.com/jeffheaton/dynaface
- Repository: https://github.com/jeffheaton/dynaface

## Overview

##### Project type and purpose
- Dynaface is a two-part system:
- A Python library (dynaface-lib) that implements the core facial-landmark detection, symmetry measures, data loading pipelines, and ML inference.
- Its purpose is to automatically locate 97 facial landmarks on still images or video, compute symmetry/asymmetry measures via advanced AI (CNN/GNN), and export results for research.

##### File structure
Top level
- dynaface-app: UI code, command definitions, worker threads, deploy subfolders (Mac/Windows) with PyInstaller specs, build scripts.
- dynaface-lib: core library packages (dynaface/…), a spiga submodule with data loaders, inference framework, CNN/GNN models, pretrained weights, plus tests and examples.
- CI/CD: Jenkinsfile-lib (build/test library), Jenkinsfile-deploy (build and package app), build_all.sh, scripts/test_whl.*.
- Configuration: requirements.txt (app), constraints.txt, setup.py/setup.cfg (lib), .flake8, .gitignore.

##### README for additional insights
- Confirms dual nature (app + library), AI references, output formats, user guide link.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UI["UI: jth_ui"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        CMD["Commands: cmds.py"]:::frontend
        CTRL["Custom Control: custom_control.py"]:::frontend
        WORKERS["Worker Threads: worker_threads.py"]:::frontend
        APPCORE["App Core: dynaface_app.py"]:::frontend
        WINDOW["Window: dynaface_window.py"]:::frontend
    end

    %% Library/API Layer
    subgraph "Library/API Layer"
        direction TB
        CONFIG["Config: config.py"]:::library
        CONST["Constants: const.py"]:::library
        IMAGE["Image I/O: image.py"]:::library
        FACIAL["Facial Landmark: facial.py"]:::library
        LATERAL["Lateral Symmetry: lateral.py"]:::library
        MEASURES["Measures: measures*.py"]:::library
        MODELS_API["Models API: models.py"]:::library
        UTIL["Utilities: util.py"]:::library
    end

    %% Inference Engine
    subgraph "Inference Engine"
        direction TB
        FRAMEWORK["Framework: framework.py"]:::inference
        PRETREAT["Pre-treatment: pretreatment.py"]:::inference
        INF_CONF["Inf Config: config.py"]:::inference
    end

    %% ML Model Layer
    subgraph "ML Model Layer"
        direction TB
        subgraph "CNN Models"
            direction TB
            CNN_MT["cnn_multitask.py"]:::model
            COORD["coord_conv.py"]:::model
            HOUR["hourglass.py"]:::model
            LAYERS_C["layers.py"]:::model
            TRANS["transform_e2p.py"]:::model
        end
        subgraph "GNN Models"
            direction TB
            GAT["gat.py"]:::model
            GLAYERS["layers.py"]:::model
            POSE["pose_proj.py"]:::model
            STEP["step_regressor.py"]:::model
        end
        WEIGHTS["Weights: weights/"]:::model
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ANNO["Annotations: annotations/"]:::data
        LOADERS["Loaders: loaders/"]:::data
        MODELS3D["3D Models: models3D/"]:::data
    end

    %% CI/CD & Deployment Layer
    subgraph "CI/CD & Deployment"
        direction TB
        JLIB["Jenkinsfile-lib"]:::ci
        JDEP["Jenkinsfile-deploy"]:::ci
        BUILDALL["build_all.sh"]:::ci
        BUILDDBG["build_debug.sh/ps1"]:::ci
        TESTWHL["test_whl.sh/ps1"]:::ci
        DEPLOY_MAC["deploy/macos/"]:::ci
        DEPLOY_WIN["deploy/windows/"]:::ci
    end

    %% Connections
    UI -->|invokes| APPCORE
    CMD -->|routes| APPCORE
    CTRL -->|manages| APPCORE
    WORKERS -->|runs async| FRAMEWORK

    APPCORE -->|calls API| CONFIG
    APPCORE --> CONST
    APPCORE --> IMAGE
    APPCORE --> FACIAL
    APPCORE --> LATERAL
    APPCORE --> MEASURES
    APPCORE --> MODELS_API
    APPCORE --> UTIL

    CONFIG --> PRETREAT
    IMAGE --> PRETREAT
    PRETREAT --> FRAMEWORK
    FRAMEWORK --> CNN_MT
    FRAMEWORK --> GAT
    CNN_MT --> WEIGHTS
    GAT --> WEIGHTS

    FRAMEWORK -->|returns landmarks| MEASURES
    MEASURES --> APPCORE
    APPCORE -->|displays/exports| UI

    IMAGE -->|loads media| ANNO
    LOADERS --> PRETREAT
    MODELS3D --> PRETREAT

    %% Build Pipeline
    JLIB --> BUILDALL
    JDEP --> DEPLOY_MAC
    JDEP --> DEPLOY_WIN
    BUILDALL -->|packages| BUILDDBG
    BUILDDBG -->|tests| TESTWHL

    %% Click Events
    click UI "https://github.com/jeffheaton/dynaface/tree/main/dynaface-app/jth_ui/"
    click CMD "https://github.com/jeffheaton/dynaface/blob/main/dynaface-app/cmds.py"
    click CTRL "https://github.com/jeffheaton/dynaface/blob/main/dynaface-app/custom_control.py"
    click WORKERS "https://github.com/jeffheaton/dynaface/blob/main/dynaface-app/worker_threads.py"
    click APPCORE "https://github.com/jeffheaton/dynaface/blob/main/dynaface-app/dynaface_app.py"
    click WINDOW "https://github.com/jeffheaton/dynaface/blob/main/dynaface-app/dynaface_window.py"
    click CONFIG "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/config.py"
    click CONST "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/const.py"
    click IMAGE "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/image.py"
    click FACIAL "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/facial.py"
    click LATERAL "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/lateral.py"
    click MEASURES "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/measures.py"
    click MODELS_API "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/models.py"
    click UTIL "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/util.py"
    click FRAMEWORK "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/inference/framework.py"
    click PRETREAT "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/inference/pretreatment.py"
    click INF_CONF "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/inference/config.py"
    click CNN_MT "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/models/cnn/cnn_multitask.py"
    click COORD "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/models/cnn/coord_conv.py"
    click HOUR "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/models/cnn/hourglass.py"
    click LAYERS_C "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/models/cnn/layers.py"
    click TRANS "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/models/cnn/transform_e2p.py"
    click GAT "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/models/gnn/gat.py"
    click GLAYERS "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/models/gnn/layers.py"
    click POSE "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/models/gnn/pose_proj.py"
    click STEP "https://github.com/jeffheaton/dynaface/blob/main/dynaface-lib/dynaface/spiga/models/gnn/step_regressor.py"
    click WEIGHTS "https://github.com/jeffheaton/dynaface/tree/main/dynaface-lib/dynaface/spiga/models/weights/"
    click ANNO "https://github.com/jeffheaton/dynaface/tree/main/dynaface-lib/dynaface/spiga/data/annotations/"
    click LOADERS "https://github.com/jeffheaton/dynaface/tree/main/dynaface-lib/dynaface/spiga/data/loaders/"
    click MODELS3D "https://github.com/jeffheaton/dynaface/tree/main/dynaface-lib/dynaface/spiga/data/models3D/"
    click JLIB "https://github.com/jeffheaton/dynaface/tree/main/Jenkinsfile-lib"
    click JDEP "https://github.com/jeffheaton/dynaface/tree/main/Jenkinsfile-deploy"
    click BUILDALL "https://github.com/jeffheaton/dynaface/blob/main/build_all.sh"
    click BUILDDBG "https://github.com/jeffheaton/dynaface/blob/main/build_debug.sh"
    click TESTWHL "https://github.com/jeffheaton/dynaface/blob/main/scripts/test_whl.sh"
    click DEPLOY_MAC "https://github.com/jeffheaton/dynaface/tree/main/dynaface-app/deploy/macos/"
    click DEPLOY_WIN "https://github.com/jeffheaton/dynaface/tree/main/dynaface-app/deploy/windows/"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef library fill:#D5F5E3,stroke:#333,stroke-width:1px
    classDef inference fill:#FDEBD0,stroke:#333,stroke-width:1px
    classDef model fill:#FADBD8,stroke:#333,stroke-width:1px
    classDef data fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef ci fill:#E5E8E8,stroke:#333,stroke-width:1px
```
