janakhpon commited on
Commit
00521fc
·
1 Parent(s): a51be11

fix: the sidecars declared a 912-character charset for a 316-class model

Browse files

Both 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.

Files changed (3) hide show
  1. README.md +37 -4
  2. monocr.json +13 -3
  3. onnx/monocr.json +14 -3
README.md CHANGED
@@ -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.05$)
75
 
76
  ## Technical Specification
77
 
78
- - **Input Tensors**: Grayscale (1-channel), 128px Height, 1024px Width (padded).
79
- - **Image Preprocessing**: Aspect-ratio preserving resize to 128px height, padded to 1024px with white background, followed by `[-1, 1]` pixel normalization.
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 models use dynamic axes for width to support varying word lengths without padding.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
 
monocr.json CHANGED
@@ -1,7 +1,17 @@
1
  {
2
- "charset": " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~£¥¦§©«¬°±²³´µ·¸¹º»¾ÀÁÂÄÅÆÇÉÊÌÍÑÓÖרÜÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüþĀāăćčĐđĒēėěğġĦħīİıņŋŌōőŒœŚśşŠšţũŪūŻŽžƒơƭưƿǎǐǔșɐɑɒɓɔɕɖɗəɛɜɡɣɦɨɪɬɰɲɳɴɹɾʁʃʄʈʊʋʑʒʔʰʲʷʻʾʿˀˈˌː˥˦̟̥̩̪̰̀́̂̃̄̋̏̚͡ΆΒΔΕΜΝΠΣΤΧάέήίαβγδεζηθικλμνξοπρςστυφχψωόύώАБДЗИМНОРСТабвгдежзийклмнопрстухцчшщыьэюяүӨөְֱִֵֶַָֹּׁׂאבדהוחיכלםמןסעפקרשתءأإئابةتثجحخدرسفقكلمنهويَِْٹپکگیंअआईकखगङचजटठडढणतथदधनपफबभमयरलळवशषसह़ािीुूृेैोौ्ংআউকখগঙচজঝঠঢণতদধনপবভমযরলশষহ়ািীুূেৈো্ৰਖਚਤਨਮਰਲਸਿੀੂੇੰੱੴકચતરાૈ્ଆକଖଢଣତଦଧପବଭମରଶଷାିୁୂୈ୍அஇகஙசஞடணதநனபமயரலளழவாிுூெேை்ంకఖగచణతదధపబమరవశాిీుైౌ్ಂಅಆಕಖಗಚಣತದಧನಪಬಮಯರಲಳವಶಾಿುೆೇೈೌ್ംകചടണതപമയരറലളവഷസിൂെൈ്අඕකතදධනබමයරවසහ්ාිුෙෝกขคฆงจฉชซญฎฏฐฑฒณดตถทธนบปผฝพฟภมยรฤลวศษสหฬอฮฯะัาำิีึืฺุูเแโใไๆ็่้๊์ํ๑๒๕๖๘ຂງຊດທບພຣວສຫະາິູຼ་།༥ཀགཆདནཔབམཛཟའརཤསིེོུྟྱྲླကခဂဃငစဆဇဈဉညဋဌဍဎဏတထဒဓနပဖဗဘမယရလဝသဟဠအဢဣဤဥဦဧဨဩဪါာိီုူေဲဳဴဵံ့း္်ျြွှဿ၀၁၂၃၄၅၆၇၈၉၊။၌၍၎၏ၐၑၓၚၛၜၝၞၟၠၡၢၣၤၥၨၪၰၱၲၳၴၵၷၸၹၺၻၼၾၿႀႄႅႆႇႈႉႊႏ႐႒႓႔႕႘႙ႜႝ႟ὴ–‘’‚“”•−",
3
  "img_height": 128,
 
4
  "model_version": "2.0",
5
- "format": "mlpackage",
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
  }
onnx/monocr.json CHANGED
@@ -1,7 +1,18 @@
1
  {
2
- "charset": " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~£¥¦§©«¬°±²³´µ·¸¹º»¾ÀÁÂÄÅÆÇÉÊÌÍÑÓÖרÜÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüþĀāăćčĐđĒēėěğġĦħīİıņŋŌōőŒœŚśşŠšţũŪūŻŽžƒơƭưƿǎǐǔșɐɑɒɓɔɕɖɗəɛɜɡɣɦɨɪɬɰɲɳɴɹɾʁʃʄʈʊʋʑʒʔʰʲʷʻʾʿˀˈˌː˥˦̟̥̩̪̰̀́̂̃̄̋̏̚͡ΆΒΔΕΜΝΠΣΤΧάέήίαβγδεζηθικλμνξοπρςστυφχψωόύώАБДЗИМНОРСТабвгдежзийклмнопрстухцчшщыьэюяүӨөְֱִֵֶַָֹּׁׂאבדהוחיכלםמןסעפקרשתءأإئابةتثجحخدرسفقكلمنهويَِْٹپکگیंअआईकखगङचजटठडढणतथदधनपफबभमयरलळवशषसह़ािीुूृेैोौ्ংআউকখগঙচজঝঠঢণতদধনপবভমযরলশষহ়ািীুূেৈো্ৰਖਚਤਨਮਰਲਸਿੀੂੇੰੱੴકચતરાૈ્ଆକଖଢଣତଦଧପବଭମରଶଷାିୁୂୈ୍அஇகஙசஞடணதநனபமயரலளழவாிுூெேை்ంకఖగచణతదధపబమరవశాిీుైౌ్ಂಅಆಕಖಗಚಣತದಧನಪಬಮಯರಲಳವಶಾಿುೆೇೈೌ್ംകചടണതപമയരറലളവഷസിൂെൈ്අඕකතදධනබමයරවසහ්ාිුෙෝกขคฆงจฉชซญฎฏฐฑฒณดตถทธนบปผฝพฟภมยรฤลวศษสหฬอฮฯะัาำิีึืฺุูเแโใไๆ็่้๊์ํ๑๒๕๖๘ຂງຊດທບພຣວສຫະາິູຼ་།༥ཀགཆདནཔབམཛཟའརཤསིེོུྟྱྲླကခဂဃငစဆဇဈဉညဋဌဍဎဏတထဒဓနပဖဗဘမယရလဝသဟဠအဢဣဤဥဦဧဨဩဪါာိီုူေဲဳဴဵံ့း္်ျြွှဿ၀၁၂၃၄၅၆၇၈၉၊။၌၍၎၏ၐၑၓၚၛၜၝၞၟၠၡၢၣၤၥၨၪၰၱၲၳၴၵၷၸၹၺၻၼၾၿႀႄႅႆႇႈႉႊႏ႐႒႓႔႕႘႙ႜႝ႟ὴ–‘’‚“”•−",
3
  "img_height": 128,
 
 
4
  "model_version": "2.0",
5
- "format": "mlpackage",
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
  }