# dair-group/fw-gan architecture

> Architecture diagram of the GitHub repository dair-group/fw-gan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dair-group/fw-gan
- Repository: https://github.com/dair-group/fw-gan

## Overview

1. **Project purpose**
   - FW-GAN is a handwriting synthesis system built around a GAN-style generator/discriminator setup, with support for two datasets/configurations: IAM and HANDS-VNOnDB.
   - The repo covers the full workflow: dataset loading, model definition, training, sample generation, and FID/KID evaluation.

2. **Top-level execution entry points**
   - `train.py` is the main training driver.
   - `generate.py` is the inference/sample-generation driver, used to produce outputs for evaluation and visualization.
   - These scripts are the main boundary between “experiment orchestration” and the reusable library/model code.

3. **Configuration layer**
   - `configs/fw_gan_iam.yml` and `configs/fw_gan_vn.yml` select dataset-specific settings.
   - Configuration appears to control dataset choice, model hyperparameters, paths, and runtime behavior, so the repo is designed to be switched between English/IAM and Vietnamese handwriting without changing code.

4. **Data layer**
   - `data/english_words.txt` and `data/vietnamese_words.txt` provide vocabulary/text content used by the system.
   - The README says the actual training/test corpora are stored as `train.hdf5` and `test.hdf5` in `data/`, which suggests the model reads prepackaged dataset tensors/records rather than raw images at runtime.
   - `lib/datasets.py` is likely the dataset abstraction that bridges those files into training batches.

5. **Text and alphabet handling**
   - `lib/alphabet.py` likely maps characters to indices and defines the supported character set.
   - This is a key preprocessing boundary: text input is normalized/encoded before entering the network, which matters for an architecture diagram because the text path is distinct from the image path.

6. **Core model package**
   - `networks/` contains the learnable model and training losses.
   - `networks/model.py` is likely the top-level model composition, wiring generator/discriminator and any auxiliary components together.
   - `networks/loss.py` holds the objective functions used during training.
   - `networks/module.py`, `blocks.py`, and `BigGAN_layers.py` suggest the architecture is assembled from reusable neural blocks, with some design borrowing from BigGAN-style components.

7. **Generator/discriminator and special layers**
   - `networks/BigGAN_networks.py` and `networks/BigGAN_layers.py` indicate the code uses BigGAN-inspired building blocks for adversarial training.
   - `networks/rand_dist.py` likely provides latent sampling or stochastic distributions for generator inputs.
   - `networks/utils.py` and `networks/__init__.py` support model construction and exports.
   - For a diagram, this subsystem should be shown as the “learned synthesis engine,” with text encoding and latent noise feeding the generator and an adversarial loss path feeding the discriminator.

8. **Utility and path management**
   - `lib/path_config.py` centralizes filesystem paths and dataset/weight locations.
   - `lib/utils.py` likely contains common helpers for logging, tensor handling, checkpointing, and experiment utilities.
   - These utilities sit below training/generation and above the filesystem, so they are infrastructure rather than model logic.

9. **Evaluation subsystem**
   - `fid_kid/` contains code for FID/KID scoring, including a local Inception implementation.
   - This is a separate evaluation boundary: generated samples are exported, then scored against real data using Inception-based feature statistics.
   - The README explicitly ties `generate.py` to FID evaluation, so generation is not just for visualization but also for quantitative reporting.

10. **Pretrained weights and outputs**
   - The README references `data/weights/FW-GAN.pth` as the pretrained model location.
   - That makes checkpoints an external artifact consumed by `generate.py` and likely by training resume logic in `train.py`.
   - In an architecture diagram, this is a persistent storage boundary between training outputs and later inference/evaluation.

11. **Fonts and visual rendering**
   - The `font/` directory likely contains font resources used for rendering or preprocessing handwriting-related data.
   - This is a supporting asset boundary rather than a learned component, but it may affect how samples or labels are visualized/prepared.

12. **Repository structure summary**
   - The main flow is: configuration selects dataset and paths → text/data loaders prepare batches → model in `networks/` synthesizes handwriting → training optimizes adversarial/loss objectives → `generate.py` produces samples → `fid_kid/` evaluates quality.
   - The repo is therefore best drawn as three layers: orchestration scripts, reusable library/model code, and data/evaluation assets.

Main entry points: [`networks/model.py`](https://github.com/dair-group/fw-gan/blob/main/networks/model.py) (Model), [`train.py`](https://github.com/dair-group/fw-gan/blob/main/train.py) (train.py), [`generate.py`](https://github.com/dair-group/fw-gan/blob/main/generate.py) (generate.py), [`lib/datasets.py`](https://github.com/dair-group/fw-gan/blob/main/lib/datasets.py) (Datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_train["train.py<br/>trainer<br/>[train.py]"]
  node_generate["generate.py<br/>inference<br/>[generate.py]"]
  node_cfg_iam["IAM config<br/>[fw_gan_iam.yml]"]
  node_cfg_vn["VN config<br/>[fw_gan_vn.yml]"]
end

subgraph group_core["Core"]
  node_alphabet["Alphabet<br/>text-encoding<br/>[alphabet.py]"]
  node_datasets["Datasets<br/>data-loader<br/>[datasets.py]"]
  node_paths["Path config<br/>paths<br/>[path_config.py]"]
  node_utils_lib["Lib utils<br/>helpers<br/>[utils.py]"]
  node_model["Model<br/>gan-compose<br/>[model.py]"]
  node_loss["Losses<br/>objectives<br/>[loss.py]"]
  node_biggan_net["BigGAN nets<br/>adversarial-backbone<br/>[BigGAN_networks.py]"]
  node_biggan_layers["BigGAN layers<br/>nn-layers<br/>[BigGAN_layers.py]"]
  node_blocks["Blocks<br/>[blocks.py]"]
  node_module["Module<br/>[module.py]"]
  node_rand["Rand dist<br/>latent-sampling<br/>[rand_dist.py]"]
  node_net_utils["Net utils<br/>network-helpers<br/>[utils.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_fidkid["FID/KID<br/>metrics<br/>[fid_kid.py]"]
  node_inception["Inception<br/>feature-extractor<br/>[inception.py]"]
end

subgraph group_assets["Assets"]
  node_words_en["English words<br/>vocab<br/>[english_words.txt]"]
  node_words_vn["Vietnamese words<br/>vocab"]
  node_font[("Fonts<br/>render-assets")]
end

node_train -.->|"selects"| node_cfg_iam
node_train -.->|"selects"| node_cfg_vn
node_generate -.->|"selects"| node_cfg_iam
node_generate -.->|"selects"| node_cfg_vn
node_train -->|"resolves"| node_paths
node_generate -->|"resolves"| node_paths
node_train -->|"loads"| node_datasets
node_generate -->|"loads"| node_datasets
node_datasets -->|"encodes"| node_alphabet
node_alphabet -->|"uses"| node_words_en
node_alphabet -->|"uses"| node_words_vn
node_train -->|"optimizes"| node_model
node_generate -->|"runs"| node_model
node_train -->|"applies"| node_loss
node_model -->|"composes"| node_biggan_net
node_model -->|"composes"| node_blocks
node_model -->|"depends on"| node_module
node_model -->|"samples"| node_rand
node_model -->|"uses"| node_biggan_layers
node_biggan_net -->|"builds from"| node_biggan_layers
node_model -->|"helpers"| node_net_utils
node_generate -->|"evaluates"| node_fidkid
node_fidkid -->|"features"| node_inception
node_train -->|"supports"| node_utils_lib
node_generate -->|"supports"| node_utils_lib
node_font -.->|"supports"| node_datasets

click node_train "https://github.com/dair-group/fw-gan/blob/main/train.py"
click node_generate "https://github.com/dair-group/fw-gan/blob/main/generate.py"
click node_cfg_iam "https://github.com/dair-group/fw-gan/blob/main/configs/fw_gan_iam.yml"
click node_cfg_vn "https://github.com/dair-group/fw-gan/blob/main/configs/fw_gan_vn.yml"
click node_alphabet "https://github.com/dair-group/fw-gan/blob/main/lib/alphabet.py"
click node_datasets "https://github.com/dair-group/fw-gan/blob/main/lib/datasets.py"
click node_paths "https://github.com/dair-group/fw-gan/blob/main/lib/path_config.py"
click node_utils_lib "https://github.com/dair-group/fw-gan/blob/main/lib/utils.py"
click node_model "https://github.com/dair-group/fw-gan/blob/main/networks/model.py"
click node_loss "https://github.com/dair-group/fw-gan/blob/main/networks/loss.py"
click node_biggan_net "https://github.com/dair-group/fw-gan/blob/main/networks/BigGAN_networks.py"
click node_biggan_layers "https://github.com/dair-group/fw-gan/blob/main/networks/BigGAN_layers.py"
click node_blocks "https://github.com/dair-group/fw-gan/blob/main/networks/blocks.py"
click node_module "https://github.com/dair-group/fw-gan/blob/main/networks/module.py"
click node_rand "https://github.com/dair-group/fw-gan/blob/main/networks/rand_dist.py"
click node_net_utils "https://github.com/dair-group/fw-gan/blob/main/networks/utils.py"
click node_fidkid "https://github.com/dair-group/fw-gan/blob/main/fid_kid/fid_kid.py"
click node_inception "https://github.com/dair-group/fw-gan/blob/main/fid_kid/inception.py"
click node_words_en "https://github.com/dair-group/fw-gan/blob/main/data/english_words.txt"
click node_words_vn "https://github.com/dair-group/fw-gan/blob/main/data/vietnamese_words.txt"
click node_font "https://github.com/dair-group/fw-gan/tree/main/font"

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_train,node_generate,node_cfg_iam,node_cfg_vn toneBlue
class node_alphabet,node_datasets,node_paths,node_utils_lib,node_model,node_loss,node_biggan_net,node_biggan_layers,node_blocks,node_module,node_rand,node_net_utils toneAmber
class node_fidkid,node_inception toneMint
class node_words_en,node_words_vn,node_font toneRose
```

## Components

### Orchestration

Entry points for training and sample generation.

- [train.py](https://github.com/dair-group/fw-gan/blob/main/train.py): trainer · Main training driver. · `train.py`
- [generate.py](https://github.com/dair-group/fw-gan/blob/main/generate.py): inference · Sample generation and evaluation driver. · `generate.py`
- [IAM config](https://github.com/dair-group/fw-gan/blob/main/configs/fw_gan_iam.yml): config · Dataset and runtime settings for IAM. · `configs/fw_gan_iam.yml`
- [VN config](https://github.com/dair-group/fw-gan/blob/main/configs/fw_gan_vn.yml): config · Dataset and runtime settings for HANDS-VNOnDB. · `configs/fw_gan_vn.yml`

### Core

Reusable data, text, and model code.

- [Alphabet](https://github.com/dair-group/fw-gan/blob/main/lib/alphabet.py): text-encoding · Character set and text indexing. · `lib/alphabet.py`
- [Datasets](https://github.com/dair-group/fw-gan/blob/main/lib/datasets.py): data-loader · Dataset abstraction for training and test batches. · `lib/datasets.py`
- [Path config](https://github.com/dair-group/fw-gan/blob/main/lib/path_config.py): paths · Central filesystem and artifact locations. · `lib/path_config.py`
- [Lib utils](https://github.com/dair-group/fw-gan/blob/main/lib/utils.py): helpers · Shared runtime helpers and utility functions. · `lib/utils.py`
- [Model](https://github.com/dair-group/fw-gan/blob/main/networks/model.py): gan-compose · Top-level generator/discriminator wiring. · `networks/model.py`
- [Losses](https://github.com/dair-group/fw-gan/blob/main/networks/loss.py): objectives · Training objective functions. · `networks/loss.py`
- [BigGAN nets](https://github.com/dair-group/fw-gan/blob/main/networks/BigGAN_networks.py): adversarial-backbone · BigGAN-inspired generator/discriminator components. · `networks/BigGAN_networks.py`
- [BigGAN layers](https://github.com/dair-group/fw-gan/blob/main/networks/BigGAN_layers.py): nn-layers · Reusable neural layers and blocks. · `networks/BigGAN_layers.py`
- [Blocks](https://github.com/dair-group/fw-gan/blob/main/networks/blocks.py): nn-blocks · Architecture blocks used to assemble the model. · `networks/blocks.py`
- [Module](https://github.com/dair-group/fw-gan/blob/main/networks/module.py): nn-module · Shared module definitions for the network stack. · `networks/module.py`
- [Rand dist](https://github.com/dair-group/fw-gan/blob/main/networks/rand_dist.py): latent-sampling · Latent and stochastic input sampling. · `networks/rand_dist.py`
- [Net utils](https://github.com/dair-group/fw-gan/blob/main/networks/utils.py): network-helpers · Model-side helper functions. · `networks/utils.py`

### Evaluation

FID/KID scoring pipeline and feature extraction.

- [FID/KID](https://github.com/dair-group/fw-gan/blob/main/fid_kid/fid_kid.py): metrics · Feature-statistics evaluation of generated samples. · `fid_kid/fid_kid.py`
- [Inception](https://github.com/dair-group/fw-gan/blob/main/fid_kid/inception.py): feature-extractor · Local Inception network for metric features. · `fid_kid/inception.py`

### Assets

Vocabulary files and visual resources.

- [English words](https://github.com/dair-group/fw-gan/blob/main/data/english_words.txt): vocab · English word list used by the dataset pipeline. · `data/english_words.txt`
- [Vietnamese words](https://github.com/dair-group/fw-gan/blob/main/data/vietnamese_words.txt): vocab · Vietnamese word list used by the dataset pipeline. · `data/vietnamese_words.txt`
- [Fonts](https://github.com/dair-group/fw-gan/tree/main/font): render-assets · Font resources supporting handwriting rendering or preprocessing. · `font`

## Connections

- train.py → IAM config: selects · Training can run with the IAM configuration.
- train.py → VN config: selects · Training can run with the Vietnamese configuration.
- generate.py → IAM config: selects · Generation uses the same dataset-specific configuration.
- generate.py → VN config: selects · Generation uses the same dataset-specific configuration.
- train.py → Path config: resolves · Training resolves dataset and checkpoint locations.
- generate.py → Path config: resolves · Generation resolves artifact and output locations.
- train.py → Datasets: loads · Training consumes batches from the dataset layer.
- generate.py → Datasets: loads · Generation reuses dataset access for conditioning or evaluation.
- Datasets → Alphabet: encodes · Dataset records are converted through the character mapping.
- Alphabet → English words: uses · English vocabulary supports the text pipeline.
- Alphabet → Vietnamese words: uses · Vietnamese vocabulary supports the text pipeline.
- train.py → Model: optimizes · Training drives the GAN model.
- generate.py → Model: runs · Generation uses the trained model for synthesis.
- train.py → Losses: applies · Training computes adversarial objectives.
- Model → BigGAN nets: composes · The top-level model is built from BigGAN-style network parts.
- Model → Blocks: composes · Model assembly reuses architectural blocks.
- Model → Module: depends on · Shared modules provide reusable network pieces.
- Model → Rand dist: samples · Latent noise and stochastic inputs feed the generator.
- Model → BigGAN layers: uses · Core model layers rely on reusable BigGAN layers.
- BigGAN nets → BigGAN layers: builds from · BigGAN networks are implemented with the layer library.
- Model → Net utils: helpers · Network utilities support construction and execution.
- generate.py → FID/KID: evaluates · Generated samples are scored with FID/KID.
- FID/KID → Inception: features · Metric computation uses an Inception feature extractor.
- train.py → Lib utils: supports · Shared utilities support training-time execution.
- generate.py → Lib utils: supports · Shared utilities support inference and export.
- Fonts → Datasets: supports · Font assets support rendering or preprocessing in the data pipeline.