How dair-group/fw-gan works
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: model.py Model · train.py train.py · generate.py generate.py · datasets.py Datasets
Components 21
Orchestration
Entry points for training and sample generation.
- train.py · Main training driver.
train.py - generate.py · Sample generation and evaluation driver.
generate.py - IAM config · Dataset and runtime settings for IAM.
configs/fw_gan_iam.yml - VN config · Dataset and runtime settings for HANDS-VNOnDB.
configs/fw_gan_vn.yml
Core
Reusable data, text, and model code.
- Alphabet · Character set and text indexing.
lib/alphabet.py - Datasets · Dataset abstraction for training and test batches.
lib/datasets.py - Path config · Central filesystem and artifact locations.
lib/path_config.py - Lib utils · Shared runtime helpers and utility functions.
lib/utils.py - Model · Top-level generator/discriminator wiring.
networks/model.py - Losses · Training objective functions.
networks/loss.py - BigGAN nets · BigGAN-inspired generator/discriminator components.
networks/BigGAN_networks.py - BigGAN layers · Reusable neural layers and blocks.
networks/BigGAN_layers.py - Blocks · Architecture blocks used to assemble the model.
networks/blocks.py - Module · Shared module definitions for the network stack.
networks/module.py - Rand dist · Latent and stochastic input sampling.
networks/rand_dist.py - Net utils · Model-side helper functions.
networks/utils.py
Evaluation
FID/KID scoring pipeline and feature extraction.
Assets
Vocabulary files and visual resources.
- English words · English word list used by the dataset pipeline.
data/english_words.txt - Vietnamese words · Vietnamese word list used by the dataset pipeline.
data/vietnamese_words.txt - Fonts · Font resources supporting handwriting rendering or preprocessing.
font
Connections 26
- 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.