JZ-Glyph

KO | EN

gitlite — search

#python #react #typescript #llm #golang #android #rust #deep-learning #macos #awesome #vue #pytorch #mcp #ios

(★ 9)

JZ-Glyph: Zero-shot Jianzi Recognition as Structured Visual Information Extraction in Open Compositional Symbolic Systems (ACL 2026)

JZ-Glyph Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# JZ-Glyph

Official code skeleton for **JZ-Glyph: Zero-shot Jianzi Recognition as Structured Visual Information Extraction in Open Compositional Symbolic Systems** (ACL 2026).

JZ-Glyph formulates single-glyph Jianzi recognition as image-to-sequence prediction under an open compositional symbol space. Given one segmented Jianzi image, the model predicts a canonical component sequence such as `名十挑六`. The zero-shot split ensures that no complete canonical sequence is shared between train/dev/test.

## What Is Released

This repository is organized around the modules described in the paper:

- `data_preprocessing/guangling/`: scripts for extracting and canonicalizing public Guangling Shenqi metadata into `all_chars.json`-style records.
- `data_preprocessing/synthesis/`: component-level rendering and manuscript-style augmentation utilities for building Synthetic-JZ.
- `eval/`: evaluation for sequence accuracy, CER, character precision/recall/F1, and complexity buckets.
- `legality/`: Bi-GRU legality-guided correction module used to score and rerank candidate component sequences.
- `training/`: LLaMA-Factory configuration notes. The full LLaMA-Factory framework and LoRA weights are not vendored here.

## Data Policy

The Real-JZ test set is included in this repository for reproducible evaluation. The full generated Synthetic-JZ training set and LoRA checkpoints are not included. The underlying Jianzi composition records come from public Guangling Shenqi metadata, but this release focuses on reproducible preprocessing code rather than redistributing the whole derived training dataset.

Expected local layout after data preparation:

```text
data/
  Synthetic-JZ/
    train.json
    dev.json
    test.json
    images/
  Real-JZ/
    test.json
    GuangLing_zero_test/
```

`Real-JZ` is the manually annotated benchmark described in the paper and is released under `data/Real-JZ/`. The JSON follows LLaMA-Factory multimodal format:

```json
{
  "messages": [
    {"role": "user", "content": "<image> 減字識別"},
    {"role": "assistant", "content": "名十挑六"}
  ],
  "images": ["images/char_0001.png"]
}
```

## Guangling Shenqi Metadata

Install Guangling Shenqi from the official forum release page:

- Guangling Shenqi download page: `https://www.guanglingsan.com/thread-8041-1.html`

After installation, locate your own Guangling Shenqi program root directory and copy out the `x.jdb` database file. The installation path depends on your operating system and installation choices. On one Windows machine, for example, the root directory looked like:

```text
C:\Users\<YOUR_USER_NAME>\AppData\Local\Programs\廣陵神器
```

In general, use the database file at:

```text
<GUANGLING_SHENQI_ROOT>\x.jdb
```

The paper uses records from the Guangling community platform (`https://www.guanglingsan.com/`) as public composition metadata.

Example preprocessing:

```bash
python data_preprocessing/guangling/parse_x_jdb.py /path/to/x.jdb --outdir outputs/dump_x_jdb
python data_preprocessing/guangling/process_all_chars.py --input outputs/all_chars.json --output outputs/processed_all_chars.json
python data_preprocessing/guangling/generate_guangling_json.py --input outputs/final_matched_dataset.json --output data/Synthetic-JZ/train.json
```

The exact cleaning rules should retain only samples with exact component-metadata alignment, matching Section 3.3 of the paper.

## Evaluation

Evaluate a local OpenAI-compatible VLM endpoint:

```bash
python eval/evaluate.py \
  --data data/Real-JZ/test.json \
  --image-root data/Real-JZ \
  --api-url http://localhost:8000/v1 \
  --api-key EMPTY \
  --model default \
  --output-dir outputs/real_jz_eval
```

If `eval_results_detailed.csv` already exists, recompute metrics only:

```bash
python eval/evaluate.py --output-dir outputs/real_jz_eval --report-only
```

## Training

The paper fine-tunes VLM backbones with LoRA. For the default Qwen3-VL-8B backbone, use LLaMA-Factory externally and point it to the generated `Synthetic-JZ` JSON files.

- LLaMA-Factory repository: `https://github.com/hiyouga/LLaMA-Factory`

JZ-Glyph

JZ-Glyph Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

JZ-Glyph

JZ-Glyph Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README