Installation

Installation

The v0.2 distribution is ocr-foundry. Both ocr-foundry and the compatible khocr-gen executable are installed from the same package. Keep existing Python imports, Rust package names and KHOCR_GEN_* settings. See branding and compatibility.

Requirements

Requirement	Version	Needed for
Python	≥ 3.12	everything
pip	any recent	PyPI install
Rust toolchain (cargo, rustc)	edition 2021	building the optional _rust_accel extension
uv	any recent	recommended for development

No GPU is required. Generation is CPU-bound image work.

From PyPI

pip install ocr-foundry

The old khocr-gen PyPI distribution is separate and is not automatically renamed or updated by publishing ocr-foundry. Install ocr-foundry for v0.2.

This installs the Python package. The Rust acceleration extension is not included in the PyPI wheel; without it every accelerated code path transparently falls back to pure Python/OpenCV. See Rust Acceleration.

Verify the install:

ocr-foundry --version
ocr-foundry --help

From source

git clone https://github.com/0x1d1e/ocr-foundry.git
cd ocr-foundry
pip install .

From source with uv (recommended for development)

uv sync --extra dev               # pure-Python development tools
uv sync --extra dev --extra rust  # also build and install the native Rust acceleration extension

The rust extra pulls in khocr-gen-core, the native extension declared as an editable path dependency in pyproject.toml:

[tool.uv.sources]
khocr-gen-core = { path = "rust", editable = true }

uv sync --extra rust therefore compiles the Rust crate via maturin as part of dependency resolution. The Python package then imports the extension as khocr_gen._rust_accel.

Check whether acceleration is active:

uv run python -c "from khocr_gen import _rust_accel as ra; print(ra.HAS_RUST_ACCEL)"

HAS_RUST_ACCEL is detected once at import time. True means the native extension loaded.

If you don't have Rust

Use uv sync --extra dev for development without native acceleration. It does not require Rust. Add --extra rust only when the Rust toolchain is available.

Optional extras

Extra	Adds
rust	khocr-gen-core only: the native acceleration extension
dev	pytest, pytest-cov, ruff, ty (no Rust dependency)

uv sync --extra rust      # acceleration without the test/lint toolchain
uv sync --extra dev       # pure-Python development environment

Runtime dependencies

Package	Purpose
opencv-python-headless	image processing and augmentation kernels
numpy	array operations
pillow	font rendering and image creation
albumentations	augmentation primitives for blur, distortion, albu_noise
tqdm	progress bars
khmernormalizer	Khmer text normalization
pyyaml	--config YAML loading
lmdb	LMDB packing and reading

Platform notes

• Linux / macOS / Windows are all supported for the Python package.
• The Rust extension builds on all three; building requires a working C toolchain (cc/link.exe) in addition to cargo.
• On headless servers, opencv-python-headless avoids pulling GUI libraries.

Next steps

• Getting Started: first dataset end to end
• Rust Acceleration: building and iterating on rust/
• Development: running the test suite and CI checks locally