mkpoli/han2ids-v0.3

han2ids v0.3

Read an ideographic description sequence (IDS) from a Mincho / 宋体 glyph image. Input is one glyph image; output is a sequence such as ⿰𠤕⿱龴疋. Mincho and Song serif faces only; Kai, handwriting and sans are out of scope.

Results

The test split is 8,730 images over 4,752 characters, mixed across Noto Serif CJK JP, IPAmj Mincho and the Jigmo family.

	exact IDS	same tree	valid IDS
overall	82.93%	86.48%	100%
Noto Serif CJK JP	92.43%
IPAmj Mincho	83.60%
Jigmo family	79.67%

v0.2 reaches 80.24% exact on the same em-box renders.

Architecture

• 35.2M parameters.
• ViT-S/16 encoder (vit_small_patch16_224.augreg_in21k_ft_in1k), 224×224 grayscale repeated to RGB.
• Four transformer decoder layers, 384 wide, 6 heads, cross-attention.
• Character-level output vocabulary of 10,423 tokens, maximum length 48.
• Greedy decoding constrained by the IDS operand stack.

han2ids-v0.3.pt is a state dict with itos and args; load it with han2ids.infer.Han2IDS.

Usage

pip install git+https://github.com/mkpoli/han2ids
huggingface-cli download mkpoli/han2ids-v0.3 han2ids-v0.3.pt --local-dir models
han2ids glyph.png --checkpoint models/han2ids-v0.3.pt

Beam alternatives:

han2ids glyph.png --checkpoint models/han2ids-v0.3.pt --top-k 3 --json

Training data

• 95,927 Han characters from BabelStone IDS (public domain), with Japanese-region labels and three image overrides: 船 ⿰舟㕣, 勇 ⿱龴男, 屄 ⿸尸宂.
• 176,965 images: Noto Serif CJK JP, IPAmj Mincho 006.01 and the Jigmo family.
• Common em-box rendering: 200-unit em box, baseline at 0.88 em, fitted to 224.
• Four epochs, batch 32; ImageNet-21k encoder, decoder from scratch.

崢 stays a reviewed miss against ⿰山爭 while the 争/爭 review is open. The label audit lists all 79 characters.

Limits

Trained on clean em-box renders. Tight crops, scans, unusual weights and Kai or sans faces are outside the training distribution. Variant components without an IDS code point cannot be named.

Terms

Code MIT. Fonts and labels keep their own terms; see NOTICE.md and LICENSE. The checkpoint is derived from renders of Noto Serif CJK JP (SIL OFL 1.1), IPAmj Mincho (IPA Font License 1.0) and Jigmo (CC0 1.0).