How harish2704/pottan-ocr works
Project type and purpose
• This is a specialized OCR engine for complex scripts (Malayalam) that provides:
• A core Python library (pottan_ocr/…) for data generation, model definition, training and inference
• A CLI wrapper (bin/pottan) exposing subcommands (extractWikiDump, datagen, train, ocr)
• An HTTP‐based OCR server (pottan_ocr/ocr_server.py) with a small static GUI (gui/web)
• A standalone browser demo (web-demo/…) that runs inference client-side via KerasJS/TF-JS
• Tooling scripts (tools/…) for data collection, glyph list generation and dependency installation
File structure
• Top level: project metadata, license, README, sample config
• pottan_ocr/: core engine modules
• data pipelines (dataset.py, data_gen.py, custom_dataset.py)
• model definition (model.py)
• training orchestration (train.py, custom_training.py)
• inference server (ocr_server.py, ocr_hocr.py)
• string conversion and utilities
• bin/pottan: entrypoint dispatching to the above modules
• gui/web: minimal static frontend for the Python OCR server
• web-demo: full JS/HTML/CSS demo built with KerasJS (Webpack, package.json)
• tools: shell/JS scripts for data collection, glyph list generation, installer
README for additional insights
• Core engine replaces Tesseract in Ocropy for single‐line recognition
• Training uses synthetic data (on‐the‐fly or cached) with fonts from system
• Dependencies: PyTorch, Ocropy, KerasJS, WebGL2
• Two usage modes: CLI & server + small GUI, and pure client‐side demo
a. Main components
1. Data Pipeline
• Wikipedia dump extractor (tools/collect-wiki-data.js)
• Glyph list generator (tools/gen-glyph-list.js)
• Synthetic data generator (data_gen.py)
2. Training Pipeline
• train.py & custom_training.py (PyTorch CRNN model)
• Cache directory for generated images
3. Model Repository
• Pretrained models pulled from GitHub (pottan-ocr-data)
4. Core OCR Engine
• model.py, ocr_hocr.py, string_converter.py
• Replaces Tesseract in Ocropy for line‐level recognition
5. CLI Interface
• bin/pottan command dispatcher
6. OCR Server + Static GUI
• ocr_server.py exposes REST endpoints (POST image → OCR result)
• Serves gui/web/index.html, CSS, JS
7. Client-side Web Demo
• web-demo folder: Webpack bundle (app.pottan-tfjs.js) runs model in browser
8. External Services & Dependencies
• Ocropy (layout detection, line segmentation)
• PyTorch (training / engine)
• KerasJS & WebGL2 (browser inference)
b. Relationships & interactions
• Tools → generate text corpus & fonts → feed into Data Pipeline
• Data Pipeline → synthetic images → Training Pipeline
• Training Pipeline → trained CRNN model → Model Repository
• CLI & Server both load model from Model Repository → Core OCR Engine
• OCR Server ↔ Static GUI (browser requests via HTTP)
• Web Demo (hosted or static serve) loads model artifact → runs inference client-side
• Core OCR Engine calls out to Ocropy for segmentation under the hood
c. Architectural patterns & design principles
• Modular Python library with clear separation of data, model, training, inference
• Single‐command CLI dispatcher (Command pattern)
• Thin server layer (REST API) with static asset serving (MVC-lite)
• Dual‐mode inference: server-side vs. client-side (decoupled frontends)
• Synthetic data generation on the fly (Cache-aside pattern)
d. Technologies
• Python, PyTorch, Ocropy, h5 model files
• Shell & NodeJS tooling scripts
• Flask or similar lightweight server in ocr_server.py
• HTML/CSS/JS for gui/web
• Webpack, KerasJS/TF-JS, WebGL2 for web-demo