Publish complete model card with 2x2 captcha gallery

README.md

@@ -17,19 +17,26 @@ tags:
 A TrOCR model fine-tuned to recognize short mathematical captcha
 expressions such as `26+7=?` and `45-6=?`.
 
-<div style="display: flex; flex-wrap: nowrap; gap: 6px; overflow-x: auto;"><img src="assets/captcha-sample-clean-14-plus-8.png" alt="Captcha example" width="300" height="100"><img src="assets/captcha-sample-handwritten-9-plus-16.png" alt="Captcha example" width="300" height="100"><img src="assets/captcha-sample-omex-37-plus-13.png" alt="Captcha example" width="300" height="100"><img src="assets/captcha-sample-distorted-arithmetic.png" alt="Captcha example" width="300" height="100"></div>
+<div align="center">
+<img src="assets/captcha-handwritten-7-plus-12.png" alt="Handwritten mathematical captcha" width="300" height="100">&nbsp;<img src="assets/captcha-clean-10-plus-3.png" alt="Clean mathematical captcha" width="300" height="100"><br>
+<img src="assets/captcha-distorted-18-plus-5.png" alt="Distorted mathematical captcha" width="300" height="100">&nbsp;<img src="assets/captcha-omex-37-plus-13.png" alt="OMEX mathematical captcha" width="300" height="100">
+</div>
 
 ## Model details
 
 - **Architecture:** Vision Encoder-Decoder / TrOCR
 - **Base model:** `microsoft/trocr-base-printed`
 - **Task:** Image-to-text OCR
-- **Target geometry:** 130x30 RGB images
-- **Output:** Mathematical expressions without spaces
+- **Training target geometry:** 130x30 RGB images
+- **Model-card example size:** 300x100 pixels
+- **Output format:** Mathematical expressions without spaces
+- **Supported operators:** `+` and `-`
+- **Expected expression format:** `number operator number = ?`
 
 ## Training data
 
-The model was fine-tuned on 10,000 target-matched synthetic images:
+The model was fine-tuned on 10,000 target-matched synthetic captcha
+images.
 
 | Split | Samples |
 |---|---:|
@@ -37,9 +44,31 @@ The model was fine-tuned on 10,000 target-matched synthetic images:
 | Validation | 1,000 |
 | Test | 500 |
 
-The generator balances `+` and `-`, includes `=` and `?`, and simulates
-thin low-contrast symbols, pastel circle overlap, blur, JPEG compression,
-background noise, and small character displacement.
+The synthetic generator balances `+` and `-` expressions and includes
+`=` and `?` symbols. It simulates several real captcha characteristics:
+
+- Thin and low-contrast arithmetic symbols
+- Pastel circle and ring overlap
+- Background noise
+- Blur and interpolation artifacts
+- JPEG compression
+- Small character displacement
+- Variable character spacing
+- Different foreground contrast levels
+
+Labels contain no spaces and use ASCII `-` for subtraction. Visual
+spacing is applied only while rendering the image.
+
+## Training procedure
+
+The complete Vision Encoder-Decoder model was fine-tuned using an
+operator-weighted sequence loss. Tokens representing `+`, `-`, `=`,
+and `?` received additional weight so that digit tokens did not dominate
+the training objective.
+
+Checkpoint selection used exact-expression accuracy on the validation
+split. The held-out test split was evaluated only after the best
+validation checkpoint had been restored.
 
 ## Training configuration
 
@@ -53,29 +82,102 @@ background noise, and small character displacement.
 | Generation beams | 4 |
 | Maximum output length | 32 |
 
+## Evaluation
+
+Evaluation measures both complete expression recognition and individual
+character groups.
+
+| Metric | Validation | Test |
+|---|---:|---:|
+| Character error rate | 0.000% | 0.000% |
+| Character accuracy | 100.000% | 100.000% |
+| Exact-expression accuracy | 100.000% | 100.000% |
+| Arithmetic-operator accuracy | 100.000% | 100.000% |
+| Symbol-sequence accuracy | 100.000% | 100.000% |
+| Digit-sequence accuracy | 100.000% | 100.000% |
+
+These results measure the synthetic rendering family used during
+fine-tuning. They do not guarantee identical accuracy for every real
+captcha provider, unseen font, or previously unseen visual style.
+
 ## Usage
 
 ```python
+import torch
 from PIL import Image
 from transformers import TrOCRProcessor, VisionEncoderDecoderModel
 
 repo_id = "arkhabbazan/ocr-match-captcha"
-processor = TrOCRProcessor.from_pretrained(repo_id, token=True)
-model = VisionEncoderDecoderModel.from_pretrained(repo_id, token=True)
+device = "cuda" if torch.cuda.is_available() else "cpu"
+
+processor = TrOCRProcessor.from_pretrained(
+    repo_id,
+    token=True,
+)
+
+model = VisionEncoderDecoderModel.from_pretrained(
+    repo_id,
+    token=True,
+).to(device).eval()
 
 image = Image.open("captcha.jpeg").convert("RGB")
-pixel_values = processor(images=image, return_tensors="pt").pixel_values
-generated_ids = model.generate(pixel_values, num_beams=4, max_length=32)
+
+# Keep the original image aspect ratio. The TrOCR processor performs
+# the model's required resizing and normalization.
+pixel_values = processor(
+    images=image,
+    return_tensors="pt",
+).pixel_values.to(device)
+
+with torch.inference_mode():
+    generated_ids = model.generate(
+        pixel_values,
+        num_beams=4,
+        max_length=32,
+    )
+
 prediction = processor.batch_decode(
-    generated_ids, skip_special_tokens=True
+    generated_ids,
+    skip_special_tokens=True,
 )[0]
-print(prediction.replace(" ", ""))
+
+prediction = prediction.replace(" ", "")
+print(prediction)
 ```
 
+Example output:
+
+```text
+26+7=?
+```
+
+## Input preprocessing
+
+Pass the original RGB captcha image directly to `TrOCRProcessor`.
+Do not manually stretch a wide captcha to a square such as 130x130,
+because that introduces a mismatch between training and inference.
+
+The 300x100 dimensions used by the four images in this model card are
+only for consistent presentation. They are not a required inference
+input size.
+
+## Intended use
+
+This model is intended for:
+
+- Short mathematical captcha OCR
+- Authorized captcha-processing workflows
+- OCR experimentation
+- Synthetic-to-real domain adaptation research
+- Arithmetic-symbol recognition evaluation
+
 ## Limitations
 
-- Training data is primarily synthetic.
-- Unseen fonts and layouts may reduce accuracy.
-- Very faint or heavily occluded operators may be missed.
 - The model is intended for short expressions, not document OCR.
 - Usage must be authorized and compliant with applicable policies.
+
+## Responsible use
+
+Use this model only on systems and captcha images that you are
+authorized to process. Users are responsible for complying with
+applicable laws, service terms, and access-control policies.