README.md

---
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.

<p align="center">
  <img src="./docs/architecture.png" alt="SpiS-GAN architecture overview" width="92%">
</p>

## 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

<p align="center">
  <img src="./docs/Visualization_gen.png" alt="English handwriting generation results" width="92%">
</p>

### English Handwriting Reconstruction

<p align="center">
  <img src="./docs/Visualization_reconstruction.png" alt="English handwriting reconstruction results" width="92%">
</p>

### Vietnamese Handwriting Generation

<p align="center">
  <img src="./docs/Visualization_Vietnamese.png" alt="Vietnamese handwriting generation results" width="92%">
</p>

## 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

```text
.
|-- 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:

```bash
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`:

```bash
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/`:

```text
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:

```bash
pip install -r requirements.txt
```

## Generate Samples

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

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

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

Generate IAM samples:

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

Generate Vietnamese samples:

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

Use random lexicon sampling:

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

Generated outputs are written under `runs/`.

## Training

Train on IAM English handwriting:

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

Train on Vietnamese handwriting:

```bash
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:

```text
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.