# novendrastywn/facelivt architecture

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

- Interactive diagram: https://gitdiagram.com/novendrastywn/facelivt
- Repository: https://github.com/novendrastywn/facelivt

## Overview

FaceLiVT is a face-recognition model repository with two CNN–Transformer generations. Its user-facing workflow aligns a face image, preprocesses it, and runs a selected backbone to produce an embedding; training and benchmark evaluation are major supporting workflows. The graph also preserves the documented v1/v2 model families and training configurations. Some subsystem connections rely on README or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`train_v2.py`](https://github.com/novendrastywn/facelivt/blob/main/train_v2.py) (Distributed training), [`face_alignment/mtcnn.py`](https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn.py) (MTCNN detector), [`backbones/__init__.py`](https://github.com/novendrastywn/facelivt/blob/main/backbones/__init__.py) (Model selection), [`inference.py`](https://github.com/novendrastywn/facelivt/blob/main/inference.py) (Embedding inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_models["Recognition models"]
  node_inference["Embedding inference<br/>[inference.py]"]
  node_registry["Model selection<br/>[__init__.py]"]
  node_v1["FaceLiVT v1<br/>[facelivt.py]"]
  node_v2["FaceLiVT v2<br/>[facelivtv2.py]"]
  node_embedding["Face embedding"]
end

subgraph group_training["Training pipeline"]
  node_configs["Model configurations"]
  node_dataset["Training dataset<br/>[dataset.py]"]
  node_sampler["Distributed sampler"]
  node_training["Distributed training<br/>[train_v2.py]"]
  node_loss["Recognition losses<br/>[losses.py]"]
  node_partialfc["Partial FC<br/>[partial_fc_v2.py]"]
  node_scheduler["Learning-rate scheduler<br/>[lr_scheduler.py]"]
  node_callbacks["Training callbacks<br/>[utils_callbacks.py]"]
end

subgraph group_alignment["Face alignment"]
  node_aligned["Aligned face<br/>[align.py]"]
  node_mtcnn["MTCNN detector<br/>[mtcnn.py]"]
  node_landmarks["Detection stages<br/>[first_stage.py]"]
  node_nets["PNet RNet ONet<br/>[get_nets.py]"]
  node_boxes["Box operations<br/>[box_utils.py]"]
  node_transform["Face transform<br/>[align_trans.py]"]
  node_similarity["Similarity transform<br/>[matlab_cp2tform.py]"]
end

subgraph group_evaluation["Evaluation and export"]
  node_verification["Verification metrics<br/>[verification.py]"]
  node_ijbc["IJB-C evaluation<br/>[eval_ijbc.py]"]
  node_onnxhelper["ONNX utilities<br/>[onnx_helper.py]"]
  node_onnxijbc["ONNX IJB-C<br/>[onnx_ijbc.py]"]
end

node_user(("Face recognition user"))
node_image["Face image"]

node_user -->|"provides"| node_image
node_user -->|"requests alignment"| node_aligned
node_image -->|"aligns"| node_aligned
node_aligned -->|"detects and aligns"| node_mtcnn
node_mtcnn -->|"runs networks"| node_nets
node_mtcnn -->|"runs detection"| node_landmarks
node_mtcnn -->|"uses box operations"| node_boxes
node_mtcnn -->|"warps face"| node_transform
node_transform -->|"computes transform"| node_similarity
node_user -->|"requests embedding"| node_inference
node_inference -->|"selects model"| node_registry
node_registry -->|"exposes model"| node_v1
node_registry -->|"exposes model"| node_v2
node_inference -->|"produces"| node_embedding
node_aligned -->|"preprocesses input"| node_inference
node_training -->|"loads configuration"| node_configs
node_training -->|"loads batches"| node_dataset
node_training -->|"uses sampler"| node_sampler
node_dataset -->|"samples indices"| node_sampler
node_training -->|"creates backbone"| node_registry
node_training -->|"computes loss"| node_loss
node_training -->|"uses classifier"| node_partialfc
node_training -->|"schedules learning rate"| node_scheduler
node_training -->|"runs callbacks"| node_callbacks
node_callbacks -->|"evaluates checkpoints"| node_verification
node_ijbc -->|"loads backbone"| node_registry
node_ijbc -->|"uses inference helpers"| node_onnxhelper
node_onnxijbc -->|"uses utilities"| node_onnxhelper

click node_aligned "https://github.com/novendrastywn/facelivt/blob/main/face_alignment/align.py"
click node_mtcnn "https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn.py"
click node_landmarks "https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/first_stage.py"
click node_nets "https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/get_nets.py"
click node_boxes "https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/box_utils.py"
click node_transform "https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/align_trans.py"
click node_similarity "https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/matlab_cp2tform.py"
click node_inference "https://github.com/novendrastywn/facelivt/blob/main/inference.py"
click node_registry "https://github.com/novendrastywn/facelivt/blob/main/backbones/__init__.py"
click node_v1 "https://github.com/novendrastywn/facelivt/blob/main/backbones/facelivt.py"
click node_v2 "https://github.com/novendrastywn/facelivt/blob/main/backbones/facelivtv2.py"
click node_configs "https://github.com/novendrastywn/facelivt/tree/main/configs"
click node_dataset "https://github.com/novendrastywn/facelivt/blob/main/dataset.py"
click node_sampler "https://github.com/novendrastywn/facelivt/blob/main/utils/utils_distributed_sampler.py"
click node_training "https://github.com/novendrastywn/facelivt/blob/main/train_v2.py"
click node_loss "https://github.com/novendrastywn/facelivt/blob/main/losses.py"
click node_partialfc "https://github.com/novendrastywn/facelivt/blob/main/partial_fc_v2.py"
click node_scheduler "https://github.com/novendrastywn/facelivt/blob/main/lr_scheduler.py"
click node_callbacks "https://github.com/novendrastywn/facelivt/blob/main/utils/utils_callbacks.py"
click node_verification "https://github.com/novendrastywn/facelivt/blob/main/eval/verification.py"
click node_ijbc "https://github.com/novendrastywn/facelivt/blob/main/eval_ijbc.py"
click node_onnxhelper "https://github.com/novendrastywn/facelivt/blob/main/onnx_helper.py"
click node_onnxijbc "https://github.com/novendrastywn/facelivt/blob/main/onnx_ijbc.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_inference,node_registry,node_v1,node_v2,node_embedding,node_user toneBlue
class node_configs,node_dataset,node_sampler,node_training,node_loss,node_partialfc,node_scheduler,node_callbacks toneAmber
class node_aligned,node_mtcnn,node_landmarks,node_nets,node_boxes,node_transform,node_similarity toneMint
class node_verification,node_ijbc,node_onnxhelper,node_onnxijbc toneRose
class node_image toneIndigo
```

## Components

### Recognition models

- [Embedding inference](https://github.com/novendrastywn/facelivt/blob/main/inference.py): `inference.py`
- [Model selection](https://github.com/novendrastywn/facelivt/blob/main/backbones/__init__.py): `backbones/__init__.py`
- [FaceLiVT v1](https://github.com/novendrastywn/facelivt/blob/main/backbones/facelivt.py): `backbones/facelivt.py`
- [FaceLiVT v2](https://github.com/novendrastywn/facelivt/blob/main/backbones/facelivtv2.py): `backbones/facelivtv2.py`
- **Face embedding**

### Training pipeline

- [Model configurations](https://github.com/novendrastywn/facelivt/tree/main/configs): `configs`
- [Training dataset](https://github.com/novendrastywn/facelivt/blob/main/dataset.py): `dataset.py`
- [Distributed sampler](https://github.com/novendrastywn/facelivt/blob/main/utils/utils_distributed_sampler.py): `utils/utils_distributed_sampler.py`
- [Distributed training](https://github.com/novendrastywn/facelivt/blob/main/train_v2.py): `train_v2.py`
- [Recognition losses](https://github.com/novendrastywn/facelivt/blob/main/losses.py): `losses.py`
- [Partial FC](https://github.com/novendrastywn/facelivt/blob/main/partial_fc_v2.py): `partial_fc_v2.py`
- [Learning-rate scheduler](https://github.com/novendrastywn/facelivt/blob/main/lr_scheduler.py): `lr_scheduler.py`
- [Training callbacks](https://github.com/novendrastywn/facelivt/blob/main/utils/utils_callbacks.py): `utils/utils_callbacks.py`

### Face alignment

- [Aligned face](https://github.com/novendrastywn/facelivt/blob/main/face_alignment/align.py): `face_alignment/align.py`
- [MTCNN detector](https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn.py): `face_alignment/mtcnn.py`
- [Detection stages](https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/first_stage.py): `face_alignment/mtcnn_pytorch/src/first_stage.py`
- [PNet RNet ONet](https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/get_nets.py): `face_alignment/mtcnn_pytorch/src/get_nets.py`
- [Box operations](https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/box_utils.py): `face_alignment/mtcnn_pytorch/src/box_utils.py`
- [Face transform](https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/align_trans.py): `face_alignment/mtcnn_pytorch/src/align_trans.py`
- [Similarity transform](https://github.com/novendrastywn/facelivt/blob/main/face_alignment/mtcnn_pytorch/src/matlab_cp2tform.py): `face_alignment/mtcnn_pytorch/src/matlab_cp2tform.py`

### Evaluation and export

- [Verification metrics](https://github.com/novendrastywn/facelivt/blob/main/eval/verification.py): `eval/verification.py`
- [IJB-C evaluation](https://github.com/novendrastywn/facelivt/blob/main/eval_ijbc.py): `eval_ijbc.py`
- [ONNX utilities](https://github.com/novendrastywn/facelivt/blob/main/onnx_helper.py): `onnx_helper.py`
- [ONNX IJB-C](https://github.com/novendrastywn/facelivt/blob/main/onnx_ijbc.py): `onnx_ijbc.py`

### Other components

- **Face recognition user**
- **Face image**

## Connections

- Face recognition user → Face image: provides
- Face recognition user → Aligned face: requests alignment
- Face image → Aligned face: aligns
- Aligned face → MTCNN detector: detects and aligns (evidence: `face_alignment/align.py`)
- MTCNN detector → PNet RNet ONet: runs networks (evidence: `face_alignment/mtcnn.py`)
- MTCNN detector → Detection stages: runs detection (evidence: `face_alignment/mtcnn.py`)
- MTCNN detector → Box operations: uses box operations (evidence: `face_alignment/mtcnn.py`)
- MTCNN detector → Face transform: warps face (evidence: `face_alignment/mtcnn.py`)
- Face transform → Similarity transform: computes transform (evidence: `face_alignment/mtcnn_pytorch/src/align_trans.py`)
- Face recognition user → Embedding inference: requests embedding
- Embedding inference → Model selection: selects model (evidence: `inference.py`)
- Model selection → FaceLiVT v1: exposes model (evidence: `backbones/__init__.py`)
- Model selection → FaceLiVT v2: exposes model (evidence: `backbones/__init__.py`)
- Embedding inference → Face embedding: produces (evidence: `inference.py`)
- Aligned face → Embedding inference: preprocesses input
- Distributed training → Model configurations: loads configuration (evidence: `train_v2.py`)
- Distributed training → Training dataset: loads batches (evidence: `train_v2.py`)
- Distributed training → Distributed sampler: uses sampler (evidence: `train_v2.py`)
- Training dataset → Distributed sampler: samples indices (evidence: `dataset.py`)
- Distributed training → Model selection: creates backbone (evidence: `train_v2.py`)
- Distributed training → Recognition losses: computes loss (evidence: `train_v2.py`)
- Distributed training → Partial FC: uses classifier (evidence: `train_v2.py`)
- Distributed training → Learning-rate scheduler: schedules learning rate (evidence: `train_v2.py`)
- Distributed training → Training callbacks: runs callbacks (evidence: `train_v2.py`)
- Training callbacks → Verification metrics: evaluates checkpoints (evidence: `utils/utils_callbacks.py`)
- IJB-C evaluation → Model selection: loads backbone (evidence: `eval_ijbc.py`)
- IJB-C evaluation → ONNX utilities: uses inference helpers
- ONNX IJB-C → ONNX utilities: uses utilities (evidence: `onnx_ijbc.py`)
