Skip to main content

AsterOCR: Vietnamese Neural Optical Character Recognition Engine

AsterOCR is a non-autoregressive neural Optical Character Recognition engine designed specifically for Vietnamese typography, administrative records (Citizen Identity Cards, passports, driving licenses), financial invoices, and smartphone document captures.

AsterOCR replaces legacy autoregressive Transformer models with an end-to-end convolutional-recurrent architecture accelerated via ONNX Runtime and PyTorch, delivering sub-60ms single-line inference on standard CPUs.

PyPI Version Python Versions Hugging Face Model Live Demo License: MIT


1. Architectural Blueprint and Parameter Profile

AsterOCR eliminates iterative autoregressive token decoding in favor of an end-to-end non-autoregressive sequence architecture.

graph TD
    A["Input Image Strip (32 x W x 3)"] --> B["HP-Stem: High-Pass Spatial Feature Filter"]
    B --> C["Backbone: Inverted Residual SE-ResNet (2.53M Params)"]
    C --> D["Map-to-Sequence (Feature Map -> 1D Temporal Slices)"]
    D --> E["Bidirectional LSTM (2 Layers, 256 Dim - 3.15M Params)"]
    E --> F["Multi-Head Self-Attention Fusion (4 Heads - 4.21M Params)"]
    F --> G["CTC Prediction Head (10.65M Total Params)"]
    G --> H["Neuro-Symbolic Linguistic Rescorer (Phonology & N-gram)"]
    H --> I["Output Vietnamese Text (Unicode NFC Standard)"]

Complete Parameter Profile (10,649,106 Total Parameters)

Neural Component Module Architecture Parameter Count Ratio (%) Operational Role
Input Stem High-Pass Spatial Laplacian Filter + Conv3x3 Included in Backbone — Preserves micro 1-2px Vietnamese accents (ă, â, ơ, ư)
Vision Backbone Inverted Residual MobileNetV3 + SE Channel Gating 2,525,249 23.7% Spatial feature extraction and background noise suppression
Sequence Modeler 2-Layer Bidirectional LSTM (hidden_size=256) 3,153,920 29.6% Bidirectional typographical stroke context dependencies
Language Fusion 4-Head Linear Multi-Head Self-Attention 4,206,592 39.5% Long-range compound word coherence across sentence
Output Classifier Linear Projection (hidden_dim -> 227 Classes) 116,451 1.1% CTC probability distributions across character vocabulary
Auxiliary Heads Multi-Task Tone and Diacritic Hat Classifiers 646,894 6.1% Explicit multi-task supervision during representation learning
TOTAL Full AsterNet Architecture 10,649,106 100.0% 40.76 MB ONNX Model (72% smaller than VietOCR 145MB)

2. Benchmark Accuracy Comparison vs VietOCR

Evaluated on 100 representative lines of the National Vietnamese Benchmark Suite (vi_00 / InkData):

Benchmark Metric AsterNet v1.0 VietOCR (Transformer) Delta / Gain
Exact Sentence Match (100% Match) 86.0% 76.0% +10.0% accuracy gain
Character Error Rate (CER) 3.45% 3.85% 1.1x lower character error
Word Error Rate (WER) 9.01% 8.23% Comparable word accuracy
Average Latency (Intel CPU) 60.25 ms 765.70 ms 12.8x faster inference
Throughput (Single CPU) 16.6 FPS 1.3 FPS Suitable for live video feeds
Model Size 40.76 MB ~145 MB 72% lighter footprint

3. Real-World CPU Performance and Hardware Matrix

AsterOCR is engineered for lightweight execution without requiring dedicated GPU infrastructure:

Hardware Platform Architecture Threads Latency / Line Throughput (FPS) Feasibility
Apple M3 / M4 Pro ARM64 (NEON) 4 28.4 ms 35.2 FPS Ultra Real-Time
Apple M1 / M2 ARM64 (NEON) 4 34.8 ms 28.7 FPS Ultra Real-Time
Intel Core i7-13700H x86_64 (AVX2/FMA) 1 60.2 ms 16.6 FPS Standard Desktop / Server
AMD Ryzen 7 7840HS x86_64 (AVX-512) 1 54.1 ms 18.5 FPS Standard Desktop / Server
Cloud vCPU (AWS c6i.large) x86_64 (AVX-512) 2 62.7 ms 15.9 FPS Low-Cost Cloud Instance
Raspberry Pi 5 (4GB) ARM Cortex-A76 4 118.0 ms 8.5 FPS Edge / IoT Hardware
NVIDIA RTX 3060 / T4 CUDA FP16 Batch 16 5.8 ms 275.0 FPS High-Concurrency API Server

4. Mathematical Formulations

4.1. High-Pass Spatial Feature Stem (HP-Stem)

Standard convolutional downsampling kernels act as low-pass filters, frequently obliterating subtle Vietnamese diacritics. HP-Stem introduces a learnable residual high-pass kernel $K_{hp}$:

$$F_{stem}(X) = \text{Conv}{3\times3}(X) + \gamma \cdot (X * K{hp})$$

where $\gamma$ is a dynamic scalar parameter amplifying edge gradients of high-frequency diacritic strokes before entering the pooling pyramid.

4.2. Inverted Residual with Squeeze-and-Excitation (SE-ResNet)

To suppress background paper discoloration, scanner artifacts, and watermark textures, AsterNet incorporates SE channel gating:

$$z_c = \frac{1}{H \times W} \sum_{i=1}^H \sum_{j=1}^W u_c(i, j)$$

$$s = \sigma\left(W_2 \cdot \text{ReLU}(W_1 z)\right)$$

$$\tilde{X}_c = s_c \cdot u_c$$

4.3. Contrast-Based Auto-Polarity Engine

Traditional CTC decoders fail on inverted text strips (white text on dark backgrounds, camera timestamps, dark mode). AsterOCR implements a mathematical contrast polarity check before tensor normalization:

$$\Delta_{bright} = P_{90}(X_{center}) - \text{Median}(X_{border})$$

$$\Delta_{dark} = \text{Median}(X_{border}) - P_{10}(X_{center})$$

$$\text{If } (\Delta_{bright} > \Delta_{dark} \text{ and } \Delta_{bright} > 20) \implies X \leftarrow (255 - X)$$


5. Quickstart (Python)

5.1. Installation

pip install asterocr

(No heavy PyTorch installation required by default. Runs using high-performance ONNX Runtime.)

5.2. Python API

from asterocr import AsterOCR

# Initialize engine (automatically fetches ONNX weights on first run)
ocr = AsterOCR()

# Recognize text from file path, PIL Image, bytes, or numpy array
text = ocr.predict("path/to/invoice.jpg")
print(text)
# Output: CỘNG HÒA XÃ HỘI CHỦ NGHĨA VIỆT NAM

5.3. Batch Recognition

results = ocr.predict_batch([
    "line_01.jpg",
    "line_02.jpg",
    "line_03.jpg"
])
for line in results:
    print(line)

5.4. Command Line Interface (CLI)

asterocr path/to/image.jpg

6. Multi-Platform Distribution Ecosystem

Platform Package Runtime Engine Repository / Registry
Python asterocr onnxruntime / torch pypi.org/project/asterocr
Node.js @asterxlabs/asterocr onnxruntime-node npmjs.com/package/@asterxlabs/asterocr
Flutter asterocr_flutter onnxruntime_flutter github.com/asterxlabs/asterOCR
Model Registry asternet-vietnamese-ocr ONNX / PyTorch huggingface.co/asterxlabs/asternet-vietnamese-ocr

7. Model Artifacts and Verification

  • asternet.onnx (40.76 MB): Production ONNX runtime model for cross-platform execution.
  • asternet_best.pth (40.78 MB): Production PyTorch checkpoint trained on 1.56M Vietnamese samples.
  • vocab.json: 227-character vocabulary mapping tokens to characters.
  • config.json: Model architecture specifications and normalization hyperparameters.

8. License and Citation

AsterOCR is released under the MIT License. Free for commercial and non-commercial applications.

Developed by asterxlabs (2026).

Metadata

Release files for asterocr 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for asterocr 1.0.1
File Size Uploaded Provenance
asterocr-1.0.1.tar.gz 122.9 kB Without provenance Details

Built distribution (wheel)

Table of built distributions (wheels) for asterocr 1.0.1
File Interpreter ABI Platform
asterocr-1.0.1-py3-none-any.whl Python 3 none any Details

Total release size: 257.0 kB

Release files / asterocr-1.0.1.tar.gz

Download URL asterocr-1.0.1.tar.gz
Size 122.9 kB
Tags Source
SHA-256 checksum
How to use checksums
584c70ce416edf21eb7a77a2cf72647f02a4300b551f31a906b322110bf64400
BLAKE2b-256 checksum
How to use checksums
49d1f521dd81690f0200c56bf21764f89a41622bbb2732399e80c9ddedbf9aba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / asterocr-1.0.1-py3-none-any.whl

Download URL asterocr-1.0.1-py3-none-any.whl
Size 134.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5590e773316842d9eea7386c95fb14b2ee008766c714778abc3799a9090d9a70
BLAKE2b-256 checksum
How to use checksums
670f7b99129810d1edfa8caefca0b4d425c8fa3b9978ef201dbe7e500da614e9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for asterocr 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page