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

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.2
File Size Uploaded Provenance
asterocr-1.0.2.tar.gz 39.3 MB Without provenance Details

Built distribution (wheel)

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

Total release size: 78.7 MB

Release files / asterocr-1.0.2.tar.gz

Download URL asterocr-1.0.2.tar.gz
Size 39.3 MB
Tags Source
SHA-256 checksum
How to use checksums
706a71028dd2971ac5626f9cc1cbfbec7d563be4074dffa00e72c926e3fb9da7
BLAKE2b-256 checksum
How to use checksums
f08e5c93e061c5fd053f87082f72e7caa5f94d61da90fb834b9cb451aff70279
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.2-py3-none-any.whl

Download URL asterocr-1.0.2-py3-none-any.whl
Size 39.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
e9ac8bfdc4eaa5a7e78404f365a2c491d60186751c94f0ab473c7e42d68257c3
BLAKE2b-256 checksum
How to use checksums
5a28d6904bd098ecefbf2b812a7e1083c53fc4a602e017624f6221e84d7fe454
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.2

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