ocr-studio/README_STUDIO.md

English | Tiếng Việt

Cham OCR Studio: Paleographic Transcription & Diagnostic Workbench

Cham OCR Studio is an interactive paleographic document analysis and transcription environment designed for digitized historical Cham manuscripts (Akhar Thrah and Cam Srak). It features deep neural text recognition (PP-OCRv4 SVTR), Indic Line Segmentation (PaddleOCR DBNet + Valley-Cut Heuristics), continuous ground-truth editing, and a built-in virtual paleographic keyboard.

🌟 Live Interactive Web Demo: https://ocr.cham.asia (mirrored on Hugging Face Spaces)

---

📁 Studio Directory Structure

ocr-studio/
├── README_STUDIO.md                    # This documentation (English)
├── README_STUDIO_VI.md                 # Vietnamese documentation
├── app.py                              # HTTP Server backend & multi-crop orchestrator
├── index.html                          # Frontend UI (Claude Warm Light Theme, Google Sans Flex)
├── start_studio.py                     # Quick-launch helper script
├── PaddleOCR/                          # Standalone PaddleOCR inference library
└── data/                               # Inference data & model assets
    ├── ocr_corrections.txt             # Verified textline corrections log
    ├── cham_dict_v*.txt                # Character dictionaries for model versions
    └── output/                         # Exported model checkpoints (inference format)
        ├── rec_cham_inference_v24/
        ├── rec_cham_inference_v23/
        ├── rec_cham_inference_v22/
        └── rec_cham_inference_v21/

---

⚡ System Requirements & Installation

1. Install project dependencies from the repository root:

   pip install -r requirements.txt
   

   Note: On modern Python runtimes (Python 3.10+ / 3.13+), NumPy 2.x backward-compatibility monkeypatching is automatically applied.

2. Verify that inference models are present in ocr-studio/data/output/ alongside the corresponding dictionaries in ocr-studio/data/.

---

🚀 Launching the Studio

Run the application from the repository root or from within the ocr-studio directory:

python ocr-studio/app.py

Alternatively, use the quick-launch script:

python ocr-studio/start_studio.py

The server automatically binds to an open port (defaulting to 7860, 8080, 8081...): ```

🚀 Cham OCR Diagnostic Studio is running at: http://localhost:7860 📁 Corrections will be saved to: ocr-studio/data/ocr_corrections.txt

Open your browser and visit `http://localhost:7860`.

---

## ⌨️ Reviewer Keybindings

| Key | Action | Description |
| :---: | :--- | :--- |
| **A** | **Approve** | Marks current line as verified ($100\%$ confidence) and moves to the next line. |
| **M** | **Merge Below** | Merges selected line with the subsequent line below into a unified crop. |
| **S** | **Split Line** | Splits selected line into two equal halves. |
| **W** | **Flag Error** | Flags current line as inaccurate ($0\%$ confidence) for retraining. |
| **Alt + K** | **Virtual Keyboard** | Toggles the Cham paleographic virtual keyboard drawer. |
| **Arrow Up / Down** | **Navigation** | Traverses previous and subsequent textlines. |
| **Double Click** | **In-Place Edit** | Activates inline text editing for the target line. |