README.md

metadata

license: mit
library_name: pytorch
pipeline_tag: image-to-image
tags:
  - handwriting-synthesis
  - generative-adversarial-network
  - pytorch
  - computer-vision
  - iam
  - vietnamese-handwriting
datasets:
  - DuyHieu63/SpiS_GAN

SpiS-GAN: Spiral-Modulated Handwriting Synthesis

SpiS-GAN is a PyTorch implementation of a GAN-based handwriting synthesis framework for generating realistic, legible, and writer-consistent handwritten word images. The repository includes model code, training and generation configs, 32px checkpoints, and the accompanying HDF5 data files used by the released configurations.

Model Summary

Field	Description
Task	Handwritten word image synthesis
Framework	PyTorch
Architecture	GAN-based handwriting generator with writer/style conditioning
Languages/Data	IAM English handwriting and Vietnamese handwriting data
Image Resolution	32px released; 64px configs included for reproducibility
Intended Use	Research, reproducibility, handwriting synthesis, and data augmentation experiments

Highlights

• Generates realistic handwritten word images from lexicon-driven text inputs.
• Supports IAM English and Vietnamese handwriting configurations.
• Includes released 32px checkpoints and matching dataset files.
• Provides training, generation, and FID/KID evaluation utilities in a single PyTorch codebase.

Qualitative Results

English Handwriting Generation

English Handwriting Reconstruction

Vietnamese Handwriting Generation

Released Artifacts

File	Purpose
data/bestIAM.pth	Released IAM 32px checkpoint
data/bestVN.pth	Released Vietnamese 32px checkpoint
data/train_32.hdf5	IAM train/validation split
data/test_32.hdf5	IAM test split
data/train_vn.h5	Vietnamese train/validation split
data/test_vn.h5	Vietnamese test split
data/english_words.txt	English lexicon
data/vietnamese_words.txt	Vietnamese lexicon

The 64px YAML configurations are included, but public 64px datasets/checkpoints are not part of this release.

Repository Structure

.
|-- configs/              # Training and generation configs
|-- data/                 # Checkpoints, HDF5 datasets, and lexicons
|-- docs/                 # Architecture and qualitative result figures
|-- fid_kid/              # FID/KID evaluation utilities
|-- font/                 # Font asset used by the pipeline
|-- lib/                  # Dataset, alphabet, path, and utility code
|-- networks/             # Generator, discriminator, recognizer, and model modules
|-- generate.py           # Generate handwriting samples from a trained checkpoint
|-- train.py              # Train SpiS-GAN from a config file
`-- requirements.txt

Quick Start

Clone this model repository with Git LFS:

git lfs install
git clone https://huggingface.co/DuyHieu63/SpiS-GAN
cd SpiS-GAN
pip install -r requirements.txt

Install PyTorch separately for your CUDA version if your environment does not already include it.

Download Checkpoints and Artifacts

The released checkpoints, HDF5 files, and lexicons are hosted in this Hugging Face repository. If you want to download only the runtime artifacts into another local checkout, use huggingface_hub:

pip install -U huggingface_hub
python - <<'PY'
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="DuyHieu63/SpiS-GAN",
    repo_type="model",
    local_dir=".",
    allow_patterns=[
        "data/*.pth",
        "data/*.h5",
        "data/*.hdf5",
        "data/*.txt",
        "configs/*.yml",
        "config.json",
        "README.md",
    ],
)
PY

The released 32px setup expects these files under data/:

data/
├── bestIAM.pth
├── bestVN.pth
├── train_32.hdf5
├── test_32.hdf5
├── train_vn.h5
├── test_vn.h5
├── english_words.txt
└── vietnamese_words.txt

Installation

Install PyTorch for your CUDA version first, then install the remaining dependencies:

pip install -r requirements.txt

Generate Samples

The released configs already point to the downloaded 32px checkpoints:

# configs/SpiS_gan_iam_32.yml
ckpt: './data/bestIAM.pth'

# configs/SpiS_gan_vn_32.yml
ckpt: './data/bestVN.pth'

Generate IAM samples:

python generate.py --config configs/SpiS_gan_iam_32.yml

Generate Vietnamese samples:

python generate.py --config configs/SpiS_gan_vn_32.yml

Use random lexicon sampling:

python generate.py --config configs/SpiS_gan_vn_32.yml --random_lexicon

Generated outputs are written under runs/.

Training

Train on IAM English handwriting:

python train.py --config configs/SpiS_gan_iam_32.yml

Train on Vietnamese handwriting:

python train.py --config configs/SpiS_gan_vn_32.yml

Training outputs, logs, samples, and checkpoints are saved under runs/<config-name>-<timestamp>/.

Data Format

The dataset loader expects HDF5 files under ./data/. The currently released 32px files are:

data/
|-- train_32.hdf5
|-- test_32.hdf5
|-- train_vn.h5
`-- test_vn.h5

Path mappings are defined in lib/path_config.py.

Citation

Citation information will be added when available.