# Sinogram Ambigrams

**A 180° turn can change more than the shape of a character.**

> **Research scope — two equally important, experimental tracks:** **Japanese kanji** (2,770 Jōyō + Jinmeiyō KanjiVG glyphs) **and Chinese hanzi** (6,763 GB2312 codepoints, Make Me a Hanzi source). **Neither track has established human readability**, and both explore natural rotation, geometric search, candidate construction, successful and unsuccessful experiments. Their source shapes, metrics, and unresolved regional-form questions differ, **not their standing within this project**. See [SCOPE.md](SCOPE.md), [research methods](methods/), and [limitations](findings/limitations.md).

**Read in:** English · [简体中文](docs/zh/README.md) · [日本語](docs/ja/README.md)

A research and art project by **Claudio Drews** exploring how Chinese *hanzi* and Japanese *kanji* can be transformed into **rotational ambigrams**: a single drawing designed to suggest one character upright and another after a half-turn. It brings together geometric search, stroke-level construction, structural decomposition and visual interpretation.

Inspired by the ambigram art of [Issei Nomura](https://x.com/IsseiNomura) and by a fascination with the intersection of **geometry, language, perception and meaning**. This is an independent project, not affiliated with or endorsed by the artist.

![Screenshot of the browser-based Ambigram Generator showing 甲 and 由](assets/generator-preview.png)

### Selected rotational candidates

![Four KanjiVG-derived ambigram candidates, each shown at 0 and 180 degrees](assets/rotation-gallery.png)

*Four exploratory SVG constructions generated by the browser application: 甲 ↔ 由, 吉 ↔ 阜, 目 ↔ 目 and 回 ↔ 回. Each design is shown upright and after a half-turn; judge the two intended readings visually.*

## Research tracks and methods tested

**Two equal-status experimental research tracks, with independent source geometries and evidence bases.** The Japanese track uses **2,770 KanjiVG kanji** (2,136 Jōyō + 634 Jinmeiyō); the Chinese/PRC-source track uses **6,763 GB2312 codepoints** from pinned Make Me a Hanzi data. A common character does **not** mean a common glyph outline, metric, or ranking. The original browser Generator is **one tool in the Japanese KanjiVG track**, even when its input-language selector says Chinese; the independent [PRC Explorer](prc/) is **one tool in the equally important Chinese track**, not the limit of that track's research.

**Start with the [interactive Research Methods map](methods/index.html)** ([GitHub Pages](https://claudiodrews.github.io/sinogram-ambigram/methods/)) or its [auditable method inventory](methods/RESEARCH_TRACKS.md). These separate **natural rotation screening**, **distinct A↔B candidate search**, **construction/synthesis**, and **perceptual evaluation**, and link to implementations, experimental PRs, demos, findings, and evidence limitations.

### Dedicated illustrated pages for every explored method

Each investigated **search**, **source-rotation**, and **construction** method has a dedicated page with its mathematical/algorithmic principle, a rotatable worked example, an optional 180° animation, provenance and limitations. **Japanese and Chinese have equal standing as experimental tracks.**

Japanese historical metric pages illustrate their input geometry with current KanjiVG vectors; those illustrations are **not** reconstructions of the original model runs. The Chinese construction pages show **actual algorithm outputs** generated from checksum-pinned Make Me a Hanzi geometry, including unchanged/no-op cases. Nothing in these diagrams proves readability.

| Track | Tested method — illustrated page | Example | What is displayed |
| --- | --- | --- | --- |
| Japanese / KanjiVG | [GPT · raster IoU](methods/jp-gpt-raster-iou/) | 甲 ↔ 由 | Current-source illustration of historical search inputs |
| Japanese / KanjiVG | [GLM · translated raster IoU](methods/jp-glm-translated-iou/) | 甲 ↔ 由 | Current-source illustration of historical search inputs |
| Japanese / KanjiVG | [Claude v1 · tolerant skeleton F-score](methods/jp-claude-skeleton-f1/) | 目 ↔ 目 | Current-source illustration of historical search inputs |
| Japanese / KanjiVG | [Claude v2 · W1 + warp + structure](methods/jp-claude-w1-warp/) | 甲 ↔ 由 | Current-source illustration of historical search inputs |
| Japanese / KanjiVG | [Kimi · FFT + raster IoU](methods/jp-kimi-fft-iou/) | 目 ↔ 目 | Current-source illustration of historical search inputs |
| Japanese / KanjiVG | [Mistral · median point clouds](methods/jp-mistral-medians/) | 王 ↔ 玉 | Current-source illustration of historical search inputs |
| Japanese / KanjiVG | [MiniMax · KanjiVG rotation graph](methods/jp-minimax-rotgraph/) | 甲 ↔ 由 | Current-source illustration of historical search inputs |
| Japanese / KanjiVG | [Natural C₂ / unmodified self-rotation](methods/jp-natural-self/) | 目 ↔ 目 | Current KanjiVG visual-mode output |
| Japanese / KanjiVG | [Natural distinct A↔B candidate](methods/jp-natural-pair/) | 甲 ↔ 由 | Current KanjiVG visual-mode output |
| Japanese / KanjiVG | [Direct overlay](methods/jp-overlay/) | 甲 ↔ 由 | Current KanjiVG visual-mode output |
| Japanese / KanjiVG | [Shared-stroke salience](methods/jp-salience/) | 甲 ↔ 由 | Current KanjiVG visual-mode output |
| Japanese / KanjiVG | [Shared structure extraction](methods/jp-shared/) | 王 ↔ 玉 | Current KanjiVG visual-mode output |
| Japanese / KanjiVG | [C₂ geometric blend](methods/jp-c2-blend/) | 田 ↔ 田 | Current KanjiVG visual-mode output |
| Chinese / MMah | [Natural C₂ / self-rotation](methods/cn-natural-self/) | 田 ↔ 田 | Actual pinned-source geometric output |
| Chinese / MMah | [Natural distinct-character search](methods/cn-natural-pair/) | 甲 ↔ 由 | Actual pinned-source geometric output |
| Chinese / MMah | [Simple source union](methods/cn-source-union/) | 甲 ↔ 由 | Actual pinned-source geometric output |
| Chinese / MMah | [Rotation centre optimisation](methods/cn-centre-optimisation/) | 田 ↔ 田 | Actual pinned-source geometric output |
| Chinese / MMah | [Terminal / extremity reconciliation](methods/cn-extremity-reconciliation/) | 田 ↔ 田 | Actual pinned-source geometric output |
| Chinese / MMah | [Deterministic sector thickness (R-SECT)](methods/cn-sector-deterministic/) | 田 ↔ 田 | Actual pinned-source geometric output |
| Chinese / MMah | [Constrained sector thickness search](methods/cn-sector-search/) | 目 ↔ 目 | Actual pinned-source geometric output |
| Chinese / MMah | [Corrected measured half-width](methods/cn-width-fixed/) | 田 ↔ 田 | Actual pinned-source geometric output |
| Chinese / MMah | [R-ODD local compensation](methods/cn-r-odd/) | 田 ↔ 田 | Actual pinned-source geometric output |
| Chinese / MMah | [C₂-even harmonic thickness field](methods/cn-harmonic/) | 目 ↔ 目 | Actual pinned-source geometric output |
| Chinese / MMah | [Registered A/B stroke fusion](methods/cn-ab-fusion/) | 甲 ↔ 由 | Actual pinned-source geometric output |

**[View the complete interactive method index](methods/)** · [Browse the 24 method pages](methods/catalog.json) · [Try the native-language Reader Gallery](evaluation/recognition/). The gallery includes examples of all **13 Japanese and 11 Chinese method families**, using 20 Japanese and 22 Chinese source-attributed visuals, clearly distinguishing reconstructed algorithm output from explanatory source-glyph illustrations. The original 48-item Japanese pilot is archived separately and unchanged.

### Japanese / KanjiVG

Historical computational searches compared **seven metric/algorithm variants across six coding runs**, not seven distinct final-drawing constructors. Their different glyph subsets, fonts, normalizations and tolerances prevent numeric score comparison:

| Search / comparison run | Tested method | Evidence |
| --- | --- | --- |
| GPT | Raster intersection-over-union (IoU); unshifted and small-alignment controls | [Metrics comparison](methods/metrics-comparison.md) |
| GLM | Raster IoU with translation search | [Metrics comparison](methods/metrics-comparison.md) |
| Claude v1 | Tolerant skeleton F-score | [Metrics comparison](methods/metrics-comparison.md) |
| Claude v2 | W1/profile filter, geometric warp and branch-aware structural score | [Metrics comparison](methods/metrics-comparison.md) |
| Kimi | FFT-aligned raster IoU; font-sensitive self-rotation | [Results summary](findings/results-summary.md) |
| Mistral | Stroke-median/point-cloud distances and matching | [Metrics comparison](methods/metrics-comparison.md) |
| MiniMax | KanjiVG rotation graph: symmetric Hausdorff, Chamfer, RMS and dilated IoU | [Rotation-graph method](methods/rotgraph-method.md) · [Data and exact/grid scales](data/README.md) |

The searches include **natural C₂ self-rotation candidates** (A↔A) and **natural distinct-character candidates** (A↔B), neither necessarily readable as the target. The full coarse Japanese inventory considers **3,837,835 unordered pairs including self-pairs**, with **5,180 selected refined rows** (2,770 self-pairs). See [C₂ Visual Lab](demo/c2/), [Rotation Lab](demo/), [pair evidence matrix](findings/pair-evidence-matrix.md), and [ranking biases](findings/debias-report.md).

The [KanjiVG Generator](generator/) offers four **visual operations**: **overlay**, **stroke salience**, **shared-stroke structure**, and **C₂ self-symmetry**. These are demonstrations/constructions based on geometric candidates, **not** the seven historical metrics and **not** seven validated ambigram styles. Its **v1-top and v2-top** strata name different *ranking/selection criteria* for the 48-item pilot, not independent visual synthesis algorithms. See [generator implementation](generator/README.md), [original 48-item evaluation protocol](methods/HUMAN_EVAL.md), and [simple Reader Gallery](evaluation/recognition/).

### Chinese / PRC-source / GB2312

The independent Chinese-source screening covers **natural self-rotation** and **distinct A↔B pairs** using coarse **37×37 rotation IoU**. The **106,347 shortlisted pairs** do not establish readability, are not exact Japanese stroke-graph ranks, and do not certify regional normative glyph forms. See [PRC Explorer](prc/), [coarse-search specification](methods/PRC_COARSE_SEARCH.md), and [source audit](methods/PRC_SOURCE_AUDIT.md).

| Construction / optimization family | Integrated or experimental status | Evidence and reproduction |
| --- | --- | --- |
| Source-vector union (A + rotated B) | Public, **unoptimized** visualization | [PRC Explorer](prc/) · [Reader Gallery](evaluation/recognition/) |
| Rotation-centre optimization | Implemented research code; no reader validation | [Construction theory](theory/prc-construction-method.md) · [Extremity findings](findings/prc-extremity-analysis.md) |
| Extremity/terminal reconciliation | Implemented experimental rules | [Construction implementation](code/prc_construct.py) · [Theory](theory/prc-construction-method.md) |
| Sector-wise thickness: deterministic rules | Implemented experimental operator | [Construction theory](theory/prc-construction-method.md) |
| Sector-wise thickness: constrained search | Implemented experimental search | [Construction code](code/prc_construct.py) · [Extremity findings](findings/prc-extremity-analysis.md) |
| Measured half-width correction | **Merged** via [PR #19](https://github.com/ClaudioDrews/sinogram-ambigram/pull/19); v1.16 replay preserved | [Width semantics](methods/PRC_WIDTH_SEMANTICS.md) · [32-glyph fidelity](findings/prc-width-contour-fidelity.md) |
| R-ODD local compensation | **Unmerged draft** [PR #14](https://github.com/ClaudioDrews/sinogram-ambigram/pull/14) | [Experimental PR](https://github.com/ClaudioDrews/sinogram-ambigram/pull/14) · [C₂ lab concepts](demo/c2/) |
| C₂-even harmonic thickness field | **Unmerged draft** [PR #15](https://github.com/ClaudioDrews/sinogram-ambigram/pull/15) | [Experimental PR](https://github.com/ClaudioDrews/sinogram-ambigram/pull/15) · [C₂ lab concepts](demo/c2/) |
| Registered A/B stroke fusion | **Unmerged draft** [PR #16](https://github.com/ClaudioDrews/sinogram-ambigram/pull/16); negative/no-op results | [Fusion diagnosis](findings/prc-ab-fusion-null-diagnosis.md) · [32-pair sensitivity PR #21](https://github.com/ClaudioDrews/sinogram-ambigram/pull/21) |

**Caution:** concept visualizations in the C₂ Lab illustrate principles of R-ODD/harmonic fields; they **are not their generated stroke outputs**. Likewise, improved original-outline IoU (median 0.4743 → 0.9083 on 32 pinned glyphs after PR #19) is **a fidelity result**, not a successful A↔B reading claim. A [52-image/208-observation blind VLM pilot](https://github.com/ClaudioDrews/sinogram-ambigram/pull/17) remains draft and is not a native-reader study.

### Where to explore the evidence

| Question | Interactive page | Reproducible/documented evidence |
| --- | --- | --- |
| Which characters survive a half-turn (C₂)? | [C₂ Visual Lab](demo/c2/) · [Rotation Lab](demo/) | [C₂ rows](data/c2_class.csv) · [Existence criterion](theory/existence-criterion.md) |
| Which **different** Japanese kanji are geometrically close? | [Japanese Generator](generator/) | [Rotation graph](methods/rotgraph-method.md) · [Pair evidence](findings/pair-evidence-matrix.md) |
| Which **different** GB2312 characters rank closely? | [PRC Explorer](prc/) | [Coarse screening](methods/PRC_COARSE_SEARCH.md) |
| What synthesis operators were attempted? | [Research Methods map](methods/index.html) | [PRC construction theory](theory/prc-construction-method.md) · [Draft PRs #13–#17](https://github.com/ClaudioDrews/sinogram-ambigram/pulls) |
| What happened, including negative results? | [C₂ Visual Lab](demo/c2/) | [Results summary](findings/results-summary.md) · [A/B null result](findings/prc-ab-fusion-null-diagnosis.md) |
| Can a reader perceive meaning? | [Simple Reader Gallery](evaluation/recognition/) | [Human-evaluation design](methods/HUMAN_EVAL.md) · [Limitations](findings/limitations.md) |

**Evidence boundary:** candidate search ≠ construction ≠ native-reader legibility. Natural glyph rotations are *source glyph candidates*; overlaid/adjusted glyphs are *constructed candidates*; a null operator outcome is still a scientific result. Not every tested operator has a distributable, independently audited example in the simplified Gallery, and none is claimed to have passed a controlled human validation. The [research-method inventory](methods/RESEARCH_TRACKS.md) records that gap explicitly; the historic 48-item pilot dataset remains unchanged.

## Explore the project

**[Visit the live project website](https://claudiodrews.github.io/sinogram-ambigram/)** or open the interactive tools:


| Interactive experience | What you can do |
| --- | --- |
| **[Ambigram Generator](https://claudiodrews.github.io/sinogram-ambigram/generator/)** | Enter a Chinese or Japanese character, inspect ranked rotational neighbors, build a vector candidate, rotate it and save the SVG. Includes a small, explicitly curated semantic-alternative fallback. |
| **[Rotation Lab](https://claudiodrews.github.io/sinogram-ambigram/demo/)** | Explore **16 examples**, including dense and complex characters; compare geometric overlays, shared strokes, salience, symmetry and component-layout demonstrations. |
| **[C₂ Visual Research Lab](https://claudiodrews.github.io/sinogram-ambigram/demo/c2/)** | Interactively decompose the same KanjiVG drawing into C₂-even/odd parts, move the rotation centre, and explore reproducible PRC width-geometry and A/B null-result measurements. Includes distinct conceptual local/harmonic field views, three interface languages, and **no readability claim**. |
| **[Mainland Chinese Explorer](https://claudiodrews.github.io/sinogram-ambigram/prc/)** | Browse the separate PRC-source GB2312 candidate shortlist, compare 180° rotated source overlays and inspect coarse geometric rankings. English, 简体中文 and 日本語. **No human legibility validation.** |

| **[Native Reader Gallery](https://claudiodrews.github.io/sinogram-ambigram/evaluation/recognition/)** | Choose **Chinese (汉字) or Japanese (漢字)**, tap each source-glyph candidate or experimental construction to rotate it 180°, and indicate whether meaning can be read in **both, one, or neither** orientation. See the actual source/construction method and evidence class, optionally add notes, and download CSV or TXT feedback. No account or proficiency questions. The two source tracks are exploratory and are not a validated readability benchmark. |\n\nThe original Generator and Rotation Lab use **Japanese KanjiVG geometry** even when the interface language or input character is Chinese. The new **PRC Explorer** uses separately sourced Chinese geometry and does not mix regional rankings. Source code: [`generator/`](generator/), [`demo/`](demo/), [`prc/`](prc/).

### A first example: 甲 ↔ 由

The generator looks for characters whose stroke geometry becomes similar after **180° rotation**. It uses a KanjiVG-based ranking to select potential partners and combines the original stroke skeleton with the rotated partner. The combined drawing is meant to be judged by rotating it and comparing it with the reference characters. It is an experimental drawing, not a claim that every candidate will be legible.

## How it works

```text
Input character
    │
    ├─ Rotation-graph search: identify geometric neighbors
    ├─ Vector construction: combine original and 180°-rotated strokes
    ├─ Explore methods: salience / overlay / shared skeleton / C₂ symmetry
    └─ If no suitable direct candidate: try a small curated semantic alternative
                 ↓
        Interactive, rotatable SVG + method explanation + feedback
```

**Core formal idea.** For rotation $R(x,y)=(-x,-y)$ in centered coordinates, a drawing $g$ is an A/B ambigram when it is perceived as **A** upright and **B** after applying $R$. The project's geometric scores rank *shapes*, while the visitor's visual assessment helps judge whether a particular drawing succeeds.

The current prototype is intentionally small: the generator indexes **5,180 refined measurements** over **2,770 characters** (including 2,770 self-pairs); it embeds vectors for **432 characters** and may load further KanjiVG paths on demand. Its fallback is a small set of curated semantic alternatives, **not** a comprehensive Chinese/Japanese synonym dictionary. The Rotation Lab offers 16 selected examples. Neither application requires an LLM or server-side runtime.

### PRC median-skeleton ingestion (implemented)

The implemented reproducible PRC stage reads the pinned Make Me a Hanzi stroke medians, checks the source SHA-256, and builds a local 109 × 109 point-cloud/distance-transform cache. See the [ingestion specification](docs/prc-ingest-spec.md) and [`code/stage12_prc_ingest.py`](code/stage12_prc_ingest.py). The intermediate cache is **not itself** a Chinese-wide ranking. The subsequent GB2312 repertoire preset and coarse search are implemented; however, the source forms have not been certified individually as normative Mainland simplified variants. Median distances must not be compared directly with filled-ink construction scores.

### Mainland Chinese: reproducible research stages

The independent [pinned-source reproduction](findings/prc-source-reproduction.md) verified **9,574** Make Me a Hanzi glyph records, **6,763/6,763** GB2312 characters covered, and two byte-identical full median-skeleton cache builds. The 9,534 figure in an earlier internal roadmap is not the count of this pinned source.

The [PRC ingestion stage](code/stage12_prc_ingest.py), [inventory preset builder](code/stage13_prc_presets.py) and [coarse rotation search](code/stage14_prc_search.py) can produce locally auditable candidates. The [coarse search method](methods/PRC_COARSE_SEARCH.md) documents its 37×37 IoU and full-cohort null model. **These are not a complete PRC ambigram generator or a human-validated ranking**: the licensed source geometry and intermediate caches remain local, while the public PRC Explorer distributes a compact numerical shortlist. Precise pair refinement and regional glyph-form certification remain separate research tasks. A small, controlled image-only VLM recognition **pilot has been completed on a draft branch**; it is not a human-reader validation (see the research-status section below). The archived 120/53 construction-cohort measurements have been [independently reproduced from pinned source geometry](methods/PRC_V116_REPRODUCTION.md).

### Experimental Mainland Chinese construction method

The separate **CN-S (Mainland simplified Chinese)** research track now includes a deterministic, synthetic-tested construction module at [`code/prc_construct.py`](code/prc_construct.py), with [`30 targeted tests`](code/test_prc_construct.py). It explores rotation-centre optimisation, terminal stroke reconciliation, and constrained sector-wise thickness changes. See the [mathematical method](theory/prc-construction-method.md) and [PRC geometric analysis](findings/prc-extremity-analysis.md).

**Integrated geometric correction:** [PR #19](https://github.com/ClaudioDrews/sinogram-ambigram/pull/19) merged the measured half-width fix into `code/prc_construct.py` while preserving the exact historical v1.16 implementation in `code/prc_construct_legacy_v116.py` for archived replay. Against 32 pinned source-outline cases, corrected original-outline IoU improved in **32/32** (median **0.4743 → 0.9083**). This is a geometric reconstruction result, **not** evidence of human readability. See the [width-semantics method](methods/PRC_WIDTH_SEMANTICS.md) and [fidelity findings](findings/prc-width-contour-fidelity.md).

**Scope boundary:** this remains an experimental *construction method*, not a Chinese-wide generator or a human-validated legibility result. The archived PRC construction-cohort measurements have a separate pinned-source reproduction documented above. The newly integrated R-ODD, harmonic-field and A/B fusion modules remain **experimental**, with actual source-pinned examples but **without established human readability**. Native-reader studies and certified regional forms remain outstanding. Japanese and PRC-source inventories must not be mixed in rankings.

### Historical experimental PRs and selective code integration

The original standalone experimental PRs remain separate and unmerged for provenance. **Their tested R-ODD, harmonic, and A/B fusion operator modules and regression tests have now been integrated through the research-methods publication PR #28**; each genuine algorithm image appears in the method-specific examples and Gallery. Keeping the original PRs open does not mean these operators are omitted from the integration. None establishes human readability.

| Draft work | Status and evidence |
| --- | --- |
| [PR #13](https://github.com/ClaudioDrews/sinogram-ambigram/pull/13) — original thickness draft | **Not merged directly.** Its geometric fix was integrated safely by PR #19 with historical replay preserved; #13 remains an open draft for provenance. |
| [PR #14](https://github.com/ClaudioDrews/sinogram-ambigram/pull/14) — R-ODD | Real integrated experimental module and [example](methods/cn-r-odd/), with original PR kept for provenance; not a validated ambigram generator. |
| [PR #15](https://github.com/ClaudioDrews/sinogram-ambigram/pull/15) — harmonic field | Integrated experimental module and [example](methods/cn-harmonic/). C₂ invariance is not evidence of readability. |
| [PR #16](https://github.com/ClaudioDrews/sinogram-ambigram/pull/16) — A/B fusion | Integrated experimental module, [no-op examples](methods/cn-ab-fusion/); neither tested distinct-character pair was recognized in the pilot. |
| [PR #17](https://github.com/ClaudioDrews/sinogram-ambigram/pull/17) — [blind VLM pilot](https://github.com/ClaudioDrews/sinogram-ambigram/tree/exp/vlm-reading-benchmark/experiments/vlm-reading-pilot-01) | Sanitized English/Chinese protocol, 52 image stimuli, 208 automated recognition responses, reproducible scoring and source-pinned image reconstruction. **Draft, not merged.** |
| [PR #21](https://github.com/ClaudioDrews/sinogram-ambigram/pull/21) — A/B fusion threshold study | Independent frozen cohort of 32 new A/B pairs, tested at thresholds 2, 4, 8, 12 and 16. At 16, 31/32 pairs registered at least one stroke, but **0/32 final raster images changed**. The no-op persists downstream of matching. [Diagnostic](findings/prc-ab-fusion-null-diagnosis.md) and [draft results](https://github.com/ClaudioDrews/sinogram-ambigram/blob/exp/ab-fusion-threshold-sensitivity/experiments/ab-fusion-threshold-v1/RESULTS.md). **Draft, not merged.** |

In the small, preselected self-rotation pilot, correct recognition of both orientations occurred in **10/20** model-by-glyph observations for the historical geometry, **14/20** for corrected thickness, **13/20** for R-ODD and **15/20** for harmonic construction. The two A/B pairs had **zero correct dual readings** across methods; A/B fusion produced the same images as the corrected simple-union control for those pairs. The separate 32-pair threshold study in draft PR #21 also produced unchanged final rasters across all 32 new pairs, despite registration succeeding for 31/32 at the highest tested threshold. Neither experiment establishes the general viability or impossibility of A/B fusion. These are **exploratory VLM observations**, not a calibrated perceptual success threshold, independent native-reader study or evidence of robust generalization.

## Research and implementation

| Directory | Contents |
| --- | --- |
| [`theory/`](theory/) | Rotational algebra, IDS composition, stroke families, word-level rules, the legibility-set formulation and stroke families. |
| [`methods/`](methods/) | Search algorithms, vector geometry, distance metrics and the Inoue–Takahashi hiragana method. |
| [`findings/`](findings/) | Experimental results, interesting pairs, disagreements and practical limitations. |
| [`data/`](data/) | [Documented CSV datasets](data/README.md), character lists and provenance of grid vs exact metrics. |
| [`code/`](code/) | Python rotation-graph pipeline components and experimental ambigram synthesis. |
| [`generator/`](generator/) | Standalone browser proof of concept, its technical README and attribution. |
| [`demo/`](demo/) | Rotation Lab: 16 interactive examples. |

The geometric experiment searched the **2,770-character Japanese Jōyō + Jinmeiyō inventory** and generated rankings for **3,837,835 unordered pairs including self-pairs**. The repository retains the selected refined results; it does not include the complete 3.84-million-row archive. This Japanese-derived inventory does **not** cover all Chinese hanzi.

### Try the Python modules

Requires **Python 3.12 or newer** for the versions pinned in `code/requirements.txt`.


```bash
python -m pip install -r code/requirements.txt
bash scripts/download_kanjivg.sh  # pinned source + checksum verification
python -m unittest discover -s code -p 'test_*.py' -v
```

The tests include real CLI execution on synthetic SVG glyphs. Paths default to repository-relative directories, with optional `ROTG_*` environment overrides. For the full numerical pipeline and computational requirements, see the [reproduction protocol](methods/rotgraph-method.md). The [dataset guide](data/README.md) distinguishes exact point-cloud distances from grid-screening approximations. After recomputing the grid pipeline, `python code/export_full_grid.py` optionally creates a complete, labelled CSV archive without adding it to the Git repository.

## Run the demonstrations

Open the [live project website](https://claudiodrews.github.io/sinogram-ambigram/), the [Ambigram Generator](https://claudiodrews.github.io/sinogram-ambigram/generator/) or the [Rotation Lab](https://claudiodrews.github.io/sinogram-ambigram/demo/). Both are hosted through GitHub Pages from the `main` branch. You can also download and open either `index.html` locally; the generator's embedded glyphs work offline, while fetching additional vectors requires internet access.

## Contribute and give feedback

Try a character, rotate the output and compare it with both references. If you see a better reading or a promising transformation, **[open an issue](https://github.com/ClaudioDrews/sinogram-ambigram/issues/new)** and include the character pair, screenshot/SVG, chosen method and your observations. You can also email **[Claudio Drews](mailto:21au6i06R3w55891@proton.me)**.

## Citation

Use the repository's [CITATION.cff](CITATION.cff) to cite Claudio Drews and this software/data release. The current version remains an exploratory prototype; no controlled native-reader validation has been published.

## Known limitations & cultural scope

Read this section before drawing any conclusion from the numbers. It is
summarised here and detailed in [`SCOPE.md`](SCOPE.md),
[`findings/limitations.md`](findings/limitations.md) and
[`LICENSE-AUDIT.md`](LICENSE-AUDIT.md).

**Two separate geometric sources, not one culturally neutral alphabet.** The Japanese research inventory contains 2,136 Jōyō plus 634 Jinmeiyō kanji, represented with **Japanese KanjiVG forms**. The independent PRC-source track covers all 6,763 GB2312 codepoints from **Make Me a Hanzi** and generated 106,347 coarse-screened candidate pairs. The original browser Generator still uses Japanese forms even for Chinese-character input; the separate PRC Explorer uses Chinese-source geometry. These sources are **never mixed** in the same ranking. GB2312 coverage certifies a *codepoint repertoire*, **not** normative simplified/traditional glyph shapes: the PRC source contains both forms and has not been independently audited against region-specific standards.

**A geometric match is a candidate, not a demonstrated ambigram.** Japanese ranking files measure geometric relations between stroke centre-lines; the separate PRC shortlist uses coarse 37×37 ink-overlap screening. Neither directly measures whether a person can read the resulting drawing. A [small blind automated VLM recognition pilot](https://github.com/ClaudioDrews/sinogram-ambigram/pull/17) exists on a **draft branch only**, but there is still **no controlled native-reader study, calibrated ε criterion or human-validated general-purpose recognizer**. Every proposed construction remains a candidate.

**The semantic fallback is tiny.** When a character has no shortlisted
geometric partner, the browser generator offers a related character from a
small hand-curated list. It is an example set, not a synonym dictionary, and
the substitution is shown to the user rather than hidden.

**Known metric biases.** The historical Japanese rotation graph has density and hub biases, and its baseline uses a fixed box-centre rotation; these observations do **not** imply that every newer PRC construction operator fixes the rotation centre. Distinct PRC metrics require separate calibration. Details are documented in
[`findings/limitations.md`](findings/limitations.md) and
[`findings/conflicts-and-corrections.md`](findings/conflicts-and-corrections.md).

**Only the half-turn.** 90° rotation, mirroring and figure–ground inversion
are out of scope. A mirror pair is *not* a rotational ambigram.

**Single glyphs, one writing mode.** The unit of analysis is one character.
Word-level composition, vertical writing and mixed-script strings are not
covered.

**On the cultural claims.** The project works with characters of Chinese
origin as *graphic forms*. It makes no claim about what a character means to
anyone, and it does not present its output as culturally authentic. Where a
traditional concept is discussed — *ma*, *shodō*, *wabi-sabi*, *kotodama* — it
is cited and defined in [`docs/GLOSSARY.md`](docs/GLOSSARY.md) as a lens, not
as a claim about the project's own results.

**Inspiration is not endorsement.** The ambigram art of Issei Nomura inspired
this project. The artist did not author, review or endorse this repository,
and no artwork of theirs is redistributed here.

## Credit and licensing

Original project code and prose by Claudio Drews: [MIT](LICENSE). **KanjiVG-derived vector artwork and adapted stroke data** embedded in the browser demos: [CC BY-SA 3.0](NOTICE.md). KanjiVG is © Ulrich Apel and contributors; see [KanjiVG](https://kanjivg.tagaini.net/). Licenses for the code, measurements and adapted artwork are distinguished in [`NOTICE.md`](NOTICE.md). The work of Issei Nomura is an inspiration, not content redistributed by this project.

**Research provenance:** model names in the experiment notes identify tools or experimental runs, not co-authors.