Metadata-Version: 2.4
Name: smart-kh-ocr
Version: 0.1.0
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 GPU Streaming**: Real-time line-by-line and page-by-page streaming generator (13.9 ms/line CTC decoding on NVIDIA RTX GPUs).
- **📄 Native PDF & Image Pipeline**: Direct multi-page PDF processing with on-the-fly rendering and lightweight RAM footprint.
- **🔍 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/SmartKhOCR.git
cd SmartKhOCR

# 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
```python
from SmartKhOCR import SmartKhOCR

model = SmartKhOCR()

# Process multi-page PDF directly
pages = model("document.pdf", correct_word=True)

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

### 3. Real-Time Streaming Generator
```python
from SmartKhOCR import SmartKhOCR

model = SmartKhOCR(decode_method="fast")

# Stream lines in real-time as they are decoded
for line in model("document.png", stream=True, correct_word=True):
    print(f"[{line.box}] {line.text}")
```

---

## 🖥️ Command Line Interface (CLI)

SmartKhOCR installs a command-line tool directly into your environment:

```bash
# Run OCR on an image or PDF
SmartKhOCR document.png --correct-word --output-txt transcript.txt --save boxes.jpg

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

---

## 🌐 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 --host 0.0.0.0 --port 8000
```

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

You can import SmartKhOCR using either convention:

```python
# Direct class import (Recommended)
from SmartKhOCR import SmartKhOCR

# Snake_case module import
from smart_kh_ocr import SmartKhOCR

# Backward-compatibility alias
from khmer_ocr import KhmerOCR
```

---

## 📄 License

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