README.md

---
license: apache-2.0
language:
- ko
tags:
- hangul
- korean
- font-classification
- font-recognition
- image-classification
- pytorch
pipeline_tag: image-classification
---

# Hangul Font Classification Model (HFC)

A PyTorch model that recognizes **which font** a printed Hangul (Korean) syllable glyph
was rendered in, and jointly recognizes **which syllable** the glyph represents.

Given a single 64x64 grayscale glyph image, the model predicts:

- **Font** — the source font, out of 3,480 classes (`model/index.csv`)
- **Character** — the Hangul syllable, decoded from separately predicted
  cho (initial consonant) / jung (medial vowel) / jong (final consonant) logits

## Model Details

- **Architecture**: shared ResNet-style CNN encoder → global average pooling →
  two projection heads that split the pooled feature into a *content* code
  (128-dim, describes which syllable it is) and a *style* code (512-dim, L2
  normalized, describes which font it is)
  - **Hangul head**: three small MLPs on the content code, predicting
    cho / jung / jong logits independently (19 / 21 / 28 classes)
  - **Font head**: an MLP + linear classifier on the style code, predicting
    font logits (3,480 classes)
  - **Decoder**: reconstructs the 64x64 input from `concat(content, style)`;
    used only as an auxiliary training signal, not required for inference
- **Input**: single-channel (grayscale) 64x64 image, black glyph on white
  background, pixel values scaled to `[0, 1]` (no further normalization)
- **Output**: `cho_logits`, `jung_logits`, `jong_logits`, `font_logits`
  (plus the intermediate `content` / `style` codes and, if `forward()` is
  used, a reconstructed image)
- **Framework**: PyTorch (`torch>=2.6`)
- **File**: [`model/hfc.pt`](model/hfc.pt) — a checkpoint dict with a
  `"model"` key holding the `state_dict`
- **Font label map**: [`model/index.csv`](model/index.csv) — maps each
  `id` (0-3479) used by `font_logits` to its human-readable `font_name`

## Intended Use

This model is intended for **font identification / classification** of
printed Hangul glyphs (e.g. document analysis, digital typography tooling,
font cataloguing) and for research on Hangul character recognition. It is
**not** intended to generate, synthesize, or reproduce font glyphs — the
decoder exists only to regularize training and is not distributed as a
generative tool.

## Usage

Model definition and a runnable example live under [`example/`](example):

- [`example/model.py`](example/model.py) — `FontRecognitionModel` and the
  Hangul cho/jung/jong composition/decomposition utilities
- [`example/demo.py`](example/demo.py) — loads the checkpoint, runs
  inference on a sample glyph, and prints the predicted character and
  top-k font candidates

```bash
uv sync
uv run python example/demo.py --image path/to/glyph.png --topk 10
```

Minimal inference snippet:

```python
import torch
from PIL import Image

from example.model import CHAR_SIZE, FontRecognitionModel, decode_open, decode_restricted

checkpoint = torch.load("model/hfc.pt", map_location="cpu", weights_only=False)

num_font_classes = 3480  # number of rows in model/index.csv
model = FontRecognitionModel(num_font_classes)
model.load_state_dict(checkpoint["model"])
model.eval()

image = Image.open("path/to/glyph.png").convert("L").resize((CHAR_SIZE, CHAR_SIZE))
x = torch.frombuffer(bytearray(image.tobytes()), dtype=torch.uint8)
x = x.reshape(1, 1, CHAR_SIZE, CHAR_SIZE).float() / 255.0

with torch.no_grad():
    out = model.encode(x)

print(decode_restricted(out.cho_logits, out.jung_logits, out.jong_logits))  # KS X 1001, 2,350 chars
print(decode_open(out.cho_logits, out.jung_logits, out.jong_logits))        # all 11,172 syllables
print(out.font_logits.softmax(-1).topk(5))
```

The image must be a single Hangul glyph, roughly centered, black-on-white,
and will be resized to 64x64 if it isn't already.

## Training Data

This model was trained on a private dataset of scanned images of printed Hangul characters. The dataset contains Hangul syllable images generated from multiple fonts and collected through a print-and-scan process.

The training dataset is not redistributed with this model.

Users should note that the source fonts may be governed by their respective licenses. This model is intended for font classification and research use, and it is not designed to reproduce or generate font glyphs.

## Limitations

- Font coverage is limited to the 3,480 fonts listed in `model/index.csv`;
  fonts not seen during training cannot be predicted correctly.
- The model expects a single, roughly-centered glyph per image, not full
  lines or pages of text — it does not perform text detection or
  segmentation.
- Because training images come from a print-and-scan pipeline, performance
  on purely digital (anti-aliased, vector-rendered) glyphs may differ from
  the reported training-time behavior.

## License

The model weights and code in this repository are released under the
[Apache License 2.0](LICENSE). This license covers the model and code
only — it does not extend any rights to the third-party fonts referenced
in `model/index.csv`, which remain governed by their own respective
licenses.