SmartKhOCR 🇰🇭

SmartKhOCR is a state-of-the-art Khmer Optical Character Recognition (OCR) and Language Correction engine built with Deep Learning Vision Transformers (ViT) and Khmer phonetic language shaping models.

It provides real-time line-by-line streaming, native PDF multi-page recognition, and contextual Coeng (ជើង) & compound auto-correction.

---

✨ Features

• 🚀 Deep Learning Vision Engine: Vision Transformer + CTC/Beam Search specifically fine-tuned on modern document scripts, headers, body text, and complex font styles.
• ✨ Coeng & Compound Auto-Correction: Context-aware corrector that fixes hanging Coeng (e.g., ឆ្នាំ $\to$ ឆ្នាំ), accidental subscripts (សាលា $\to$ សាលា), and missing Coeng compounds (រាជធានីភំពើញ $\to$ រាជធានីភ្នំពេញ).
• ⚡ Ultra-Fast Real-Time Streaming: Native line-by-line streaming across images and multi-page PDFs with page numbers and start-of-page markers.
• 📄 Native Multi-Page PDF Pipeline: Direct PDF processing with on-the-fly rendering, batch execution, or continuous line-by-line streaming across pages.
• 🔍 Side-by-Side Comparison Studio: Integrated web dashboard with bounding box visualization and parallel Tesseract OCR (khm+eng) benchmark comparisons.
• 💻 CLI & REST API Ready: Built-in CLI tool and FastAPI Server-Sent Events (SSE) streaming server.

---

📦 Installation

# Clone the repository
git clone https://github.com/devnsmtech/smart-kh-ocr
cd smart-kh-ocr

# Install dependencies using uv or pip
uv pip install -e .
# or
pip install -e .

---

🚀 Quickstart (Python API)

1. Basic Image OCR

from SmartKhOCR import SmartKhOCR

# Initialize OCR engine (auto-selects CUDA if available)
model = SmartKhOCR(decode_method="fast")

# Recognize text with Coeng auto-correction
result = model("chapter.png", correct_word=True)

print("Recognized Text:")
print(result.text)

# Save annotated visualization with detected line boxes
result.save("output_annotated.jpg")

2. Multi-Page PDF Processing (Batch)

from SmartKhOCR import SmartKhOCR

model = SmartKhOCR()

# Process multi-page PDF directly (returns list of OCRResult objects)
pages = model("document.pdf", correct_word=True)

for idx, page in enumerate(pages, 1):
    print(f"\n--- Page {idx} ---")
    print(page.text)

3. Native Multi-Page PDF Streaming (Line-by-Line)

Stream lines in real time across pages without waiting for the whole PDF to process:

from SmartKhOCR import SmartKhOCR

model = SmartKhOCR(decode_method="fast")

for line in model("document.pdf", stream=True, correct_word=True):
    # line.page_start is True only on the first line of each page
    if line.page_start:
        print(f"\n=== Starting Page {line.page} ===")
    
    print(f"[{line.box}] (Conf: {line.confidence:.2f}) {line.text}")

4. Character-by-Character Streaming (Typewriter Effect)

For interactive typing or chat-style UI animations:

for chunk in model.stream_chars("document.png"):
    print(chunk["token"], end="", flush=True)

---

📋 OCRLine Structure

When streaming or inspecting results, each line is an OCRLine object with:

Property	Type	Description
line.text	str	Recognized & corrected Khmer text
line.page	int	1-based page number (e.g. 1, 2, 3...)
line.page_start	bool	True for the first line of each page; False otherwise
line.box	List[int]	Detected bounding box [x, y, w, h]
line.padded_box	List[int]	Context-padded crop box fed to the ViT recognizer
line.confidence	float	Model confidence score (0.0 to 1.0)
line.raw_text	str	Raw decoded text before post-correction
line.to_dict()	dict	JSON-serializable dictionary with all above fields

---

🖥️ Command Line Interface (CLI)

SmartKhOCR installs command-line aliases (SmartKhOCR, smart-kh-ocr, smartkhocr):

# Run OCR on an image or PDF
SmartKhOCR document.pdf --correct-word --output-txt transcript.txt

# Export model to high-performance inference engines
SmartKhOCR --export engine       # TensorRT engine
SmartKhOCR --export onnx         # ONNX graph

---

🌐 Web Studio & Streaming REST API

SmartKhOCR comes with a real-time web dashboard and SSE streaming API:

uv run fastapi run app_ui.py

1. Web Dashboard: Open http://localhost:8000 in your browser.
2. REST API Streaming (Server-Sent Events):

curl -N -X POST http://localhost:8000/api/ocr/stream \
  -F "file=@document.pdf" \
  -F "correct_word=true" \
  -F "fast_mode=true" \
  -F "compare_tesseract=true"

---

🏷️ Package Architecture

Import using either convention:

# Direct class import (Recommended)
from SmartKhOCR import SmartKhOCR, OCRLine, OCRResult

# Snake_case module import
from smart_kh_ocr import SmartKhOCR, KhmerOCR

---

📄 License

MIT License. Designed and developed for high-accuracy Khmer text processing.

smart-kh-ocr