Metadata-Version: 2.4
Name: asterocr
Version: 1.0.1
Summary: AsterOCR: High-Performance Non-Autoregressive Vietnamese Optical Character Recognition Engine
Author-email: asterxlabs <contact@asterxlabs.com>
License: MIT
Project-URL: Homepage, https://huggingface.co/asterxlabs/asternet-vietnamese-ocr
Project-URL: Bug Tracker, https://github.com/asterxlabs/asterOCR/issues
Project-URL: Demo Space, https://huggingface.co/spaces/asterxlabs/asternet-vietnamese-ocr-demo
Keywords: ocr,vietnamese,document-ai,text-recognition,onnx,deep-learning
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: Pillow>=8.0.0
Requires-Dist: onnxruntime>=1.14.0
Requires-Dist: huggingface_hub>=0.19.0
Provides-Extra: torch
Requires-Dist: torch>=2.0.0; extra == "torch"
Provides-Extra: all
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: gradio>=4.0.0; extra == "all"

# 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](https://img.shields.io/pypi/v/asterocr?color=blue)](https://pypi.org/project/asterocr/)
[![Python Versions](https://img.shields.io/pypi/pyversions/asterocr)](https://pypi.org/project/asterocr/)
[![Hugging Face Model](https://img.shields.io/badge/Hugging%20Face-Model%20Hub-orange)](https://huggingface.co/asterxlabs/asternet-vietnamese-ocr)
[![Live Demo](https://img.shields.io/badge/Gradio-Live%20Demo-blue)](https://huggingface.co/spaces/asterxlabs/asternet-vietnamese-ocr-demo)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](https://opensource.org/licenses/MIT)

---

## 1. Architectural Blueprint and Parameter Profile

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

```mermaid
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

```bash
pip install asterocr
```

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

### 5.2. Python API

```python
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

```python
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)

```bash
asterocr path/to/image.jpg
```

---

## 6. Multi-Platform Distribution Ecosystem

| Platform | Package | Runtime Engine | Repository / Registry |
| :--- | :--- | :--- | :--- |
| **Python** | `asterocr` | `onnxruntime` / `torch` | [pypi.org/project/asterocr](https://pypi.org/project/asterocr/) |
| **Node.js** | `@asterxlabs/asterocr` | `onnxruntime-node` | [npmjs.com/package/@asterxlabs/asterocr](https://www.npmjs.com/package/@asterxlabs/asterocr) |
| **Flutter** | `asterocr_flutter` | `onnxruntime_flutter` | [github.com/asterxlabs/asterOCR](https://github.com/asterxlabs/asterOCR) |
| **Model Registry** | `asternet-vietnamese-ocr` | ONNX / PyTorch | [huggingface.co/asterxlabs/asternet-vietnamese-ocr](https://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).
