Metadata-Version: 2.4
Name: smart-kh-ocr
Version: 0.1.1
Summary: SmartKhOCR: High-Accuracy Vision OCR and Language Engine for Khmer Documents
License-Expression: MIT
Keywords: khmer,ocr,khmer-ocr,vision-transformer,deep-learning,text-recognition
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0.0
Requires-Dist: torchvision>=0.15.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pillow>=9.5.0
Requires-Dist: opencv-python-headless>=4.8.0
Requires-Dist: pypdfium2>=4.0.0
Requires-Dist: ultralytics>=8.0.0
Requires-Dist: kiri-ocr>=0.2.15
Provides-Extra: server
Requires-Dist: fastapi>=0.110.0; extra == "server"
Requires-Dist: uvicorn>=0.25.0; extra == "server"
Requires-Dist: python-multipart>=0.0.9; extra == "server"
Requires-Dist: pytesseract>=0.3.10; extra == "server"

# 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

```bash
# Clone the repository
git clone https://github.com/your-username/smart-kh-ocr.git
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
```python
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)
```python
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:

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

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

```bash
# 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:

```bash
uv run fastapi run app_ui.py
```

1. **Web Dashboard**: Open `http://localhost:8000` in your browser.
2. **REST API Streaming** (Server-Sent Events):
```bash
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:

```python
# 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
# smart-kh-ocr
# smart-kh-ocr
