fix: the sidecars declared a 912-character charset for a 316-class model
Browse filesBoth monocr.json and onnx/monocr.json carried the 912-character corpus-scanned
string. The model has 316 output classes, so exactly 150 of 315 indices mapped
to the wrong character and any consumer reading these files decoded Mon into
Latin and IPA with no error anywhere.
The correct 315-character string was already in this repository, in
charset.txt beside them. It was taken programmatically from that file, not
retyped, and it is not a truncation of the 912: the long string is missing
U+2026, which the real charset carries, so no consumer could have recovered by
trimming.
How it happened, because a re-export will do it again: df456df was a Core ML
export that wrote the CoreML sidecar over both other formats. That is also why
onnx/monocr.json said "format": "mlpackage" and had lost its opset_version.
The Core ML package still has no sidecar of its own.
- charset 912 -> 315 in both; onnx/ regains format "onnx" and opset_version 17
- root sidecar sits beside monocr.ckpt, so its format is "pytorch"
- adds the fields whose absence made this undetectable, matching mon_OCR's
exporter schema: num_classes, img_width, rnn_hidden_size, rnn_layers,
backbone, input_normalization, and a _provenance string. Both files now pass
mon_OCR's own _check_charset_contract, which the old ones fail
- model_version stays "2.0": api.py gates on startswith("3.5"), so "2.0-legacy"
would be behaviourally identical, and it is a machine-read field on a
published artifact four SDKs consume. The legacy status is in _provenance
- card: the 78-vs-89 width contradiction resolved in favour of the graph,
label smoothing corrected to the checkpoint's 0.1, an evaluation-protocol
note, and the limitations ADR-0008 makes mandatory
opset 17 is the pinned opset across every inspectable v2 export, but df456df
also replaced the ONNX binary, so it is unverified against the file currently
served. That limitation is recorded in _provenance.
- README.md +37 -4
- monocr.json +13 -3
- onnx/monocr.json +14 -3
|
@@ -50,6 +50,22 @@ Unified SDKs are available for seamless integration into existing applications.
|
|
| 50 |
| **Epochs** | 27 |
|
| 51 |
| **Best Checkpoint** | `monocr-epoch=27-val_loss=1.157-val_cer=0.025.ckpt` |
|
| 52 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 53 |
## Dataset Summary
|
| 54 |
|
| 55 |
- **Total samples**: 3,030,000
|
|
@@ -71,12 +87,12 @@ Unified SDKs are available for seamless integration into existing applications.
|
|
| 71 |
- **Optimizer**: AdamW
|
| 72 |
- **Learning rate**: 0.0001 (Warmup + Cosine Annealing)
|
| 73 |
- **Batch size**: 48 (with Gradient Accumulation = 4)
|
| 74 |
-
- **Loss function**: CTCLoss (with label smoothing $\epsilon=0.
|
| 75 |
|
| 76 |
## Technical Specification
|
| 77 |
|
| 78 |
-
- **Input Tensors**: Grayscale (1-channel), 128px
|
| 79 |
-
- **Image Preprocessing**: Aspect-ratio preserving resize to 128px height,
|
| 80 |
- **Decoding Strategy**: Connectionist Temporal Classification (CTC) Greedy Decoding (Default).
|
| 81 |
- **Vocabulary**: 315 characters (Mon, Burmese, digits, punctuation, and symbols). Encoding is standard UTF-8 (see `charset.txt`).
|
| 82 |
|
|
@@ -86,7 +102,24 @@ For developers building custom drivers:
|
|
| 86 |
|
| 87 |
1. Refer to `charset.txt` for the index-to-character mapping (Index 0 is reserved for `<blank>`).
|
| 88 |
2. Ensure input images are high-contrast and properly scaled to 128px height.
|
| 89 |
-
3. ONNX
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 90 |
|
| 91 |
## License
|
| 92 |
|
|
|
|
| 50 |
| **Epochs** | 27 |
|
| 51 |
| **Best Checkpoint** | `monocr-epoch=27-val_loss=1.157-val_cer=0.025.ckpt` |
|
| 52 |
|
| 53 |
+
**How these were measured.** CER 0.025 is `val_cer` on the **synthetic validation
|
| 54 |
+
split** at epoch 27. The checkpoint published here records it internally
|
| 55 |
+
(`monitor: val_cer`, `best_model_score` 0.0252, step 218,949), so the figure is
|
| 56 |
+
attributable to this artifact. Two things it is not: it is a *validation* number
|
| 57 |
+
rather than a held-out test number, and its split was rendered by the same
|
| 58 |
+
generator **and the same typefaces** as training — font-disjoint splits were
|
| 59 |
+
introduced after this checkpoint was trained. It therefore measures fit to unseen
|
| 60 |
+
*text* in fonts the model had already seen, which is a substantially easier task
|
| 61 |
+
than reading an unseen typeface.
|
| 62 |
+
|
| 63 |
+
**WER 0.211 has no recorded provenance.** It could not be traced to this
|
| 64 |
+
checkpoint or to any training record, and it should be treated as unverified
|
| 65 |
+
until re-measured.
|
| 66 |
+
|
| 67 |
+
No figure on this card describes accuracy on a photographed page.
|
| 68 |
+
|
| 69 |
## Dataset Summary
|
| 70 |
|
| 71 |
- **Total samples**: 3,030,000
|
|
|
|
| 87 |
- **Optimizer**: AdamW
|
| 88 |
- **Learning rate**: 0.0001 (Warmup + Cosine Annealing)
|
| 89 |
- **Batch size**: 48 (with Gradient Accumulation = 4)
|
| 90 |
+
- **Loss function**: CTCLoss (with label smoothing $\epsilon=0.1$)
|
| 91 |
|
| 92 |
## Technical Specification
|
| 93 |
|
| 94 |
+
- **Input Tensors**: Grayscale (1-channel), float32, fixed 128px height. The ONNX graph is `[1, 1, 128, width]`: batch is fixed at 1 and the **width axis is dynamic**.
|
| 95 |
+
- **Image Preprocessing**: Aspect-ratio preserving resize to 128px height, then `pixel / 127.5 - 1.0` into the `[-1, 1]` range. Where padding is used it must be **white** — `+1.0` after normalization, not `0.0`. Training padded to 1024px width; since the width axis is dynamic, 1024 is the width the model was trained at rather than a required input size.
|
| 96 |
- **Decoding Strategy**: Connectionist Temporal Classification (CTC) Greedy Decoding (Default).
|
| 97 |
- **Vocabulary**: 315 characters (Mon, Burmese, digits, punctuation, and symbols). Encoding is standard UTF-8 (see `charset.txt`).
|
| 98 |
|
|
|
|
| 102 |
|
| 103 |
1. Refer to `charset.txt` for the index-to-character mapping (Index 0 is reserved for `<blank>`).
|
| 104 |
2. Ensure input images are high-contrast and properly scaled to 128px height.
|
| 105 |
+
3. The ONNX width axis is dynamic, so crops of differing width can be fed directly without padding to 1024. Batch is fixed at 1.
|
| 106 |
+
4. Read `num_classes` from the JSON sidecar and check it equals `len(charset) + 1` before decoding. If the two disagree, the model will still return confident text — it will just be the wrong text, with no error raised.
|
| 107 |
+
|
| 108 |
+
## Limitations — what no number here covers
|
| 109 |
+
|
| 110 |
+
Stated so that an unmeasured property is not read as a measured one:
|
| 111 |
+
|
| 112 |
+
- **Real photographs.** Every evaluation sample was synthetic, rendered by the
|
| 113 |
+
same generator the model trained on. The reported CER measures generalisation
|
| 114 |
+
to unseen text, not to an unseen renderer. A defect in the renderer is learned,
|
| 115 |
+
validated against and tested against identically, and scores well throughout.
|
| 116 |
+
- **Unseen typefaces.** This checkpoint's validation split shared its fonts with
|
| 117 |
+
training, so no figure here separates typographic generalisation from text
|
| 118 |
+
generalisation.
|
| 119 |
+
- **Page layout and line segmentation.** Inputs are pre-cropped single lines.
|
| 120 |
+
- **Handwriting.** Not covered.
|
| 121 |
+
- **Beam-search decoding.** Greedy only; the reported figures are greedy.
|
| 122 |
+
- **Per-line latency.** No latency tail has been measured.
|
| 123 |
|
| 124 |
## License
|
| 125 |
|
|
@@ -1,7 +1,17 @@
|
|
| 1 |
{
|
| 2 |
-
"charset": " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~£¥¦§©«¬°±²³´µ·¸¹º»¾ÀÁÂÄÅÆÇÉÊÌÍÑÓÖרÜÞßàáâãäåæçèéêëìíîïðñòóôõö÷
|
| 3 |
"img_height": 128,
|
|
|
|
| 4 |
"model_version": "2.0",
|
| 5 |
-
"format": "
|
| 6 |
-
"architecture": "MobileNetV3-Large + BiLSTM + CTC"
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7 |
}
|
|
|
|
| 1 |
{
|
| 2 |
+
"charset": " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~£¥¦§©«¬°±²³´µ·¸¹º»¾ÀÁÂÄÅÆÇÉÊÌÍÑÓÖרÜÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüþĀāıŒœŠšŽžƒːμπကခဂဃငစဆဇဈဉညဋဌဍဎဏတထဒဓနပဖဗဘမယရလဝသဟဠအဢဣဤဥဦဧဨဩဪါာိီုူေဲဳဴဵံ့း္်ျြွှဿ၀၁၂၃၄၅၆၇၈၉၊။၌၍၎၏ၐၑၓၚၛၜၝၞၟၠၡၢၣၤၥၨၪၰၱၲၳၴၵၷၸၹၺၻၼၾၿႀႄႅႆႇႈႉႊႏ႐႒႓႔႕႘႙ႜႝ႟–‘’‚“”•…−",
|
| 3 |
"img_height": 128,
|
| 4 |
+
"img_width": 1024,
|
| 5 |
"model_version": "2.0",
|
| 6 |
+
"format": "pytorch",
|
| 7 |
+
"architecture": "MobileNetV3-Large + BiLSTM(384) + CTC",
|
| 8 |
+
"num_classes": 316,
|
| 9 |
+
"rnn_hidden_size": 384,
|
| 10 |
+
"rnn_layers": 2,
|
| 11 |
+
"backbone": "mobilenetv3_large",
|
| 12 |
+
"input_normalization": "pixel / 127.5 - 1.0",
|
| 13 |
+
"input_dtype": "float32",
|
| 14 |
+
"input_channels": 1,
|
| 15 |
+
"input_colorspace": "grayscale",
|
| 16 |
+
"_provenance": "Charset repaired 2026-08-14. This sidecar declared a 912-character corpus-scanned charset against a 316-class model, so 150 of the 315 decodable indices mapped to the wrong character and any consumer decoded Mon as Latin/IPA text with no error and no lookup miss. The charset here is the 315-character allowlist read from charset.txt in this repository (git blob 08b1c23299dd1f68f14b7bdb4be586dd52d27c5d); it is byte-identical to the repaired sidecar in mon_OCR data/models/archive-v2-2026-03/, which was confirmed by decoding validation samples against their labels. num_classes is recorded here so this class of mismatch is checkable: CTC reserves index 0 for blank, so num_classes must equal len(charset) + 1. It is confirmed by fc.weight (316, 768) and hyper_parameters['num_classes'] in the published monocr.ckpt. The 912-character string arrived in commit df456df, a Core ML export that overwrote both this file and the root monocr.json with the Core ML variant -- which is also why the ONNX sidecar had lost opset_version and declared format 'mlpackage'. A re-export that writes only one sidecar will reintroduce that. model_version stays '2.0': mon_OCR names this artifact '2.0-legacy' internally, but that string is a judgement relative to unpublished v3.5 code and changing a published contract field could break an exact-match check in the four SDKs the model card lists. The v2 graph takes [1, 1, 128, width] float32 grayscale: batch is fixed at 1 and the width axis is dynamic. img_width 1024 is the width training preprocessing pads to, not a graph constraint -- README.md states both and reads as a contradiction. This file sits beside monocr.ckpt, a PyTorch Lightning checkpoint, so it carries no opset_version; the ONNX sidecar is onnx/monocr.json. It previously declared format 'mlpackage', which described neither this checkpoint nor anything else at the repository root."
|
| 17 |
}
|
|
@@ -1,7 +1,18 @@
|
|
| 1 |
{
|
| 2 |
-
"charset": " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~£¥¦§©«¬°±²³´µ·¸¹º»¾ÀÁÂÄÅÆÇÉÊÌÍÑÓÖרÜÞßàáâãäåæçèéêëìíîïðñòóôõö÷
|
| 3 |
"img_height": 128,
|
|
|
|
|
|
|
| 4 |
"model_version": "2.0",
|
| 5 |
-
"format": "
|
| 6 |
-
"architecture": "MobileNetV3-Large + BiLSTM + CTC"
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7 |
}
|
|
|
|
| 1 |
{
|
| 2 |
+
"charset": " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~£¥¦§©«¬°±²³´µ·¸¹º»¾ÀÁÂÄÅÆÇÉÊÌÍÑÓÖרÜÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüþĀāıŒœŠšŽžƒːμπကခဂဃငစဆဇဈဉညဋဌဍဎဏတထဒဓနပဖဗဘမယရလဝသဟဠအဢဣဤဥဦဧဨဩဪါာိီုူေဲဳဴဵံ့း္်ျြွှဿ၀၁၂၃၄၅၆၇၈၉၊။၌၍၎၏ၐၑၓၚၛၜၝၞၟၠၡၢၣၤၥၨၪၰၱၲၳၴၵၷၸၹၺၻၼၾၿႀႄႅႆႇႈႉႊႏ႐႒႓႔႕႘႙ႜႝ႟–‘’‚“”•…−",
|
| 3 |
"img_height": 128,
|
| 4 |
+
"img_width": 1024,
|
| 5 |
+
"opset_version": 17,
|
| 6 |
"model_version": "2.0",
|
| 7 |
+
"format": "onnx",
|
| 8 |
+
"architecture": "MobileNetV3-Large + BiLSTM(384) + CTC",
|
| 9 |
+
"num_classes": 316,
|
| 10 |
+
"rnn_hidden_size": 384,
|
| 11 |
+
"rnn_layers": 2,
|
| 12 |
+
"backbone": "mobilenetv3_large",
|
| 13 |
+
"input_normalization": "pixel / 127.5 - 1.0",
|
| 14 |
+
"input_dtype": "float32",
|
| 15 |
+
"input_channels": 1,
|
| 16 |
+
"input_colorspace": "grayscale",
|
| 17 |
+
"_provenance": "Charset repaired 2026-08-14. This sidecar declared a 912-character corpus-scanned charset against a 316-class model, so 150 of the 315 decodable indices mapped to the wrong character and any consumer decoded Mon as Latin/IPA text with no error and no lookup miss. The charset here is the 315-character allowlist read from charset.txt in this repository (git blob 08b1c23299dd1f68f14b7bdb4be586dd52d27c5d); it is byte-identical to the repaired sidecar in mon_OCR data/models/archive-v2-2026-03/, which was confirmed by decoding validation samples against their labels. num_classes is recorded here so this class of mismatch is checkable: CTC reserves index 0 for blank, so num_classes must equal len(charset) + 1. It is confirmed by fc.weight (316, 768) and hyper_parameters['num_classes'] in the published monocr.ckpt. The 912-character string arrived in commit df456df, a Core ML export that overwrote both this file and the root monocr.json with the Core ML variant -- which is also why the ONNX sidecar had lost opset_version and declared format 'mlpackage'. A re-export that writes only one sidecar will reintroduce that. model_version stays '2.0': mon_OCR names this artifact '2.0-legacy' internally, but that string is a judgement relative to unpublished v3.5 code and changing a published contract field could break an exact-match check in the four SDKs the model card lists. The v2 graph takes [1, 1, 128, width] float32 grayscale: batch is fixed at 1 and the width axis is dynamic. img_width 1024 is the width training preprocessing pads to, not a graph constraint -- README.md states both and reads as a contradiction. opset_version 17 is read from the v2 fp32, fp16 and int8 ONNX exports, the fp32 of which is byte-identical to the ONNX published here at commit d29385b; the binary currently published (LFS oid f212ab7e) is a later re-export that has not been re-inspected."
|
| 18 |
}
|