# sczhou/codeformer architecture

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

- Interactive diagram: https://gitdiagram.com/sczhou/codeformer
- Repository: https://github.com/sczhou/codeformer

## Overview

CodeFormer is a face-restoration application and BasicSR-based training framework. Its primary user workflow accepts an image or video, restores faces with a fidelity-controlled CodeFormer model, optionally enhances background or face resolution, and saves results; whole-image processing uses face detection, alignment, and compositing. Separate entry points provide face colorization and inpainting. The graph also covers training data, model/loss/metric layers, and documented video and demo support. Source excerpts show only parts of several paths, so unsampled capability links rely on README statements or are omitted.

Main entry points: [`inference_codeformer.py`](https://github.com/sczhou/codeformer/blob/master/inference_codeformer.py) (Face Restoration), [`basicsr/models`](https://github.com/sczhou/codeformer/tree/master/basicsr/models) (Training Models), [`inference_colorization.py`](https://github.com/sczhou/codeformer/blob/master/inference_colorization.py) (Face Colorization), [`inference_inpainting.py`](https://github.com/sczhou/codeformer/blob/master/inference_inpainting.py) (Face Inpainting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["User Inference"]
  node_restoration["Face Restoration"]
  node_colorization["Face Colorization"]
  node_inpainting["Face Inpainting"]
end

subgraph group_face["Face Processing"]
  node_face_helper["Face Helper"]
  node_detectors["Face Detection"]
  node_parsing["Face Parsing"]
end

subgraph group_networks["Neural Networks"]
  node_codeformer_arch["CodeFormer Network<br/>[codeformer_arch.py]"]
  node_rrdb["RRDBNet<br/>[rrdbnet_arch.py]"]
  node_vqgan["VQGAN Network<br/>[vqgan_arch.py]"]
  node_arch_utils["Architecture Utilities<br/>[arch_util.py]"]
end

subgraph group_training["Training System"]
  node_trainer["Training Runner<br/>[train.py]"]
  node_training_models["Training Models"]
  node_datasets["Training Datasets"]
  node_prefetch["Data Prefetch"]
  node_losses["Training Losses<br/>[losses.py]"]
  node_metrics["Evaluation Metrics<br/>[psnr_ssim.py]"]
  node_base_model["Model Base<br/>[base_model.py]"]
end

subgraph group_support["Media and Support"]
  node_video["Video I/O<br/>[video_util.py]"]
  node_realesrgan["Real-ESRGAN Support"]
  node_registry["Component Registry<br/>[registry.py]"]
  node_file_client["Storage Access<br/>[file_client.py]"]
end

node_user(("User"))
node_input["Image or Video"]
node_results["Saved Results"]

node_user -->|"runs"| node_restoration
node_input -->|"provides media"| node_restoration
node_restoration -->|"loads model"| node_codeformer_arch
node_restoration -->|"processes faces"| node_face_helper
node_face_helper -->|"detects faces"| node_detectors
node_face_helper -->|"parses faces"| node_parsing
node_restoration -.->|"optionally upsamples"| node_realesrgan
node_restoration -->|"reads and writes video"| node_video
node_restoration -->|"saves outputs"| node_results
node_user -->|"runs"| node_colorization
node_input -->|"provides face"| node_colorization
node_colorization -->|"loads model"| node_codeformer_arch
node_colorization -->|"saves outputs"| node_results
node_user -->|"runs"| node_inpainting
node_input -->|"provides masked face"| node_inpainting
node_inpainting -->|"loads model"| node_codeformer_arch
node_inpainting -->|"saves outputs"| node_results
node_trainer -->|"builds loaders"| node_datasets
node_trainer -->|"selects prefetcher"| node_prefetch
node_trainer -->|"runs training"| node_training_models
node_training_models -->|"extends base"| node_base_model
node_training_models -->|"builds network"| node_codeformer_arch
node_training_models -->|"builds codebook target"| node_vqgan
node_training_models -->|"builds losses"| node_losses
node_training_models -->|"uses metrics"| node_metrics
node_losses -.->|"uses feature network"| node_arch_utils
node_rrdb -->|"uses utilities"| node_arch_utils
node_restoration -->|"looks up network"| node_registry
node_colorization -->|"looks up network"| node_registry
node_inpainting -->|"looks up network"| node_registry
node_file_client -.->|"reads stored data"| node_input

click node_restoration "https://github.com/sczhou/codeformer/blob/master/inference_codeformer.py"
click node_colorization "https://github.com/sczhou/codeformer/blob/master/inference_colorization.py"
click node_inpainting "https://github.com/sczhou/codeformer/blob/master/inference_inpainting.py"
click node_face_helper "https://github.com/sczhou/codeformer/blob/master/facelib/utils/face_restoration_helper.py"
click node_detectors "https://github.com/sczhou/codeformer/tree/master/facelib/detection"
click node_parsing "https://github.com/sczhou/codeformer/tree/master/facelib/parsing"
click node_codeformer_arch "https://github.com/sczhou/codeformer/blob/master/basicsr/archs/codeformer_arch.py"
click node_rrdb "https://github.com/sczhou/codeformer/blob/master/basicsr/archs/rrdbnet_arch.py"
click node_vqgan "https://github.com/sczhou/codeformer/blob/master/basicsr/archs/vqgan_arch.py"
click node_arch_utils "https://github.com/sczhou/codeformer/blob/master/basicsr/archs/arch_util.py"
click node_trainer "https://github.com/sczhou/codeformer/blob/master/basicsr/train.py"
click node_training_models "https://github.com/sczhou/codeformer/tree/master/basicsr/models"
click node_datasets "https://github.com/sczhou/codeformer/tree/master/basicsr/data"
click node_prefetch "https://github.com/sczhou/codeformer/blob/master/basicsr/data/prefetch_dataloader.py"
click node_losses "https://github.com/sczhou/codeformer/blob/master/basicsr/losses/losses.py"
click node_metrics "https://github.com/sczhou/codeformer/blob/master/basicsr/metrics/psnr_ssim.py"
click node_base_model "https://github.com/sczhou/codeformer/blob/master/basicsr/models/base_model.py"
click node_video "https://github.com/sczhou/codeformer/blob/master/basicsr/utils/video_util.py"
click node_realesrgan "https://github.com/sczhou/codeformer/blob/master/basicsr/utils/realesrgan_utils.py"
click node_registry "https://github.com/sczhou/codeformer/blob/master/basicsr/utils/registry.py"
click node_file_client "https://github.com/sczhou/codeformer/blob/master/basicsr/utils/file_client.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_restoration,node_colorization,node_inpainting,node_user toneBlue
class node_face_helper,node_detectors,node_parsing toneAmber
class node_codeformer_arch,node_rrdb,node_vqgan,node_arch_utils toneMint
class node_trainer,node_training_models,node_datasets,node_prefetch,node_losses,node_metrics,node_base_model toneRose
class node_video,node_realesrgan,node_registry,node_file_client,node_input,node_results toneIndigo
```

## Components

### User Inference

- [Face Restoration](https://github.com/sczhou/codeformer/blob/master/inference_codeformer.py): `inference_codeformer.py`
- [Face Colorization](https://github.com/sczhou/codeformer/blob/master/inference_colorization.py): `inference_colorization.py`
- [Face Inpainting](https://github.com/sczhou/codeformer/blob/master/inference_inpainting.py): `inference_inpainting.py`

### Face Processing

- [Face Helper](https://github.com/sczhou/codeformer/blob/master/facelib/utils/face_restoration_helper.py): `facelib/utils/face_restoration_helper.py`
- [Face Detection](https://github.com/sczhou/codeformer/tree/master/facelib/detection): `facelib/detection`
- [Face Parsing](https://github.com/sczhou/codeformer/tree/master/facelib/parsing): `facelib/parsing`

### Neural Networks

- [CodeFormer Network](https://github.com/sczhou/codeformer/blob/master/basicsr/archs/codeformer_arch.py): `basicsr/archs/codeformer_arch.py`
- [RRDBNet](https://github.com/sczhou/codeformer/blob/master/basicsr/archs/rrdbnet_arch.py): `basicsr/archs/rrdbnet_arch.py`
- [VQGAN Network](https://github.com/sczhou/codeformer/blob/master/basicsr/archs/vqgan_arch.py): `basicsr/archs/vqgan_arch.py`
- [Architecture Utilities](https://github.com/sczhou/codeformer/blob/master/basicsr/archs/arch_util.py): `basicsr/archs/arch_util.py`

### Training System

- [Training Runner](https://github.com/sczhou/codeformer/blob/master/basicsr/train.py): `basicsr/train.py`
- [Training Models](https://github.com/sczhou/codeformer/tree/master/basicsr/models): `basicsr/models`
- [Training Datasets](https://github.com/sczhou/codeformer/tree/master/basicsr/data): `basicsr/data`
- [Data Prefetch](https://github.com/sczhou/codeformer/blob/master/basicsr/data/prefetch_dataloader.py): `basicsr/data/prefetch_dataloader.py`
- [Training Losses](https://github.com/sczhou/codeformer/blob/master/basicsr/losses/losses.py): `basicsr/losses/losses.py`
- [Evaluation Metrics](https://github.com/sczhou/codeformer/blob/master/basicsr/metrics/psnr_ssim.py): `basicsr/metrics/psnr_ssim.py`
- [Model Base](https://github.com/sczhou/codeformer/blob/master/basicsr/models/base_model.py): `basicsr/models/base_model.py`

### Media and Support

- [Video I/O](https://github.com/sczhou/codeformer/blob/master/basicsr/utils/video_util.py): `basicsr/utils/video_util.py`
- [Real-ESRGAN Support](https://github.com/sczhou/codeformer/blob/master/basicsr/utils/realesrgan_utils.py): `basicsr/utils/realesrgan_utils.py`
- [Component Registry](https://github.com/sczhou/codeformer/blob/master/basicsr/utils/registry.py): `basicsr/utils/registry.py`
- [Storage Access](https://github.com/sczhou/codeformer/blob/master/basicsr/utils/file_client.py): `basicsr/utils/file_client.py`

### Other components

- **User**
- **Image or Video**
- **Saved Results**

## Connections

- User → Face Restoration: runs
- Image or Video → Face Restoration: provides media (evidence: `inference_codeformer.py`)
- Face Restoration → CodeFormer Network: loads model (evidence: `inference_codeformer.py`)
- Face Restoration → Face Helper: processes faces (evidence: `inference_codeformer.py`)
- Face Helper → Face Detection: detects faces (evidence: `facelib/utils/face_restoration_helper.py`)
- Face Helper → Face Parsing: parses faces (evidence: `facelib/utils/face_restoration_helper.py`)
- Face Restoration → Real-ESRGAN Support: optionally upsamples (evidence: `inference_codeformer.py`)
- Face Restoration → Video I/O: reads and writes video (evidence: `inference_codeformer.py`)
- Face Restoration → Saved Results: saves outputs (evidence: `inference_codeformer.py`)
- User → Face Colorization: runs
- Image or Video → Face Colorization: provides face
- Face Colorization → CodeFormer Network: loads model (evidence: `inference_colorization.py`)
- Face Colorization → Saved Results: saves outputs
- User → Face Inpainting: runs
- Image or Video → Face Inpainting: provides masked face (evidence: `inference_inpainting.py`)
- Face Inpainting → CodeFormer Network: loads model (evidence: `inference_inpainting.py`)
- Face Inpainting → Saved Results: saves outputs
- Training Runner → Training Datasets: builds loaders (evidence: `basicsr/train.py`)
- Training Runner → Data Prefetch: selects prefetcher (evidence: `basicsr/train.py`)
- Training Runner → Training Models: runs training (evidence: `basicsr/train.py`)
- Training Models → Model Base: extends base (evidence: `basicsr/models/sr_model.py`)
- Training Models → CodeFormer Network: builds network (evidence: `basicsr/models/codeformer_joint_model.py`)
- Training Models → VQGAN Network: builds codebook target (evidence: `basicsr/models/codeformer_joint_model.py`)
- Training Models → Training Losses: builds losses (evidence: `basicsr/models/codeformer_joint_model.py`)
- Training Models → Evaluation Metrics: uses metrics (evidence: `basicsr/models/codeformer_joint_model.py`)
- Training Losses → Architecture Utilities: uses feature network
- RRDBNet → Architecture Utilities: uses utilities (evidence: `basicsr/archs/rrdbnet_arch.py`)
- Face Restoration → Component Registry: looks up network (evidence: `inference_codeformer.py`)
- Face Colorization → Component Registry: looks up network (evidence: `inference_colorization.py`)
- Face Inpainting → Component Registry: looks up network (evidence: `inference_inpainting.py`)
- Storage Access → Image or Video: reads stored data
