khocr-gen 0.1.0__tar.gz

khocr_gen-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.pytest_cache
+.ruff_cache
+.venv
+
+rust/target/
+
+__pycache__
+uv.lock

khocr_gen-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - Unreleased
+
+### Added
+- Initial release: synthetic OCR dataset generation for Khmer/English text
+- `generate` command: render text corpus to training images with augmentations
+- `combine` command: merge multiple datasets into one
+- `verify` command: render augmentation comparison grids for QA
+- `view` command: preview LMDB dataset contents
+- Configurable augmentation pipeline with min/max/prob per method
+- Multi-process parallel rendering
+- LMDB output packing
+- Khmer text normalization via khmernormalizer
+- Rust acceleration extension (`khocr-gen-core`, in `rust/`): native implementations of
+  21/24 augmentation methods, O(1) cmap-based font glyph checking (`FontFace`), and
+  script-span splitting, with automatic pure-Python fallback when unavailable. Built and
+  installed automatically by `uv sync` via a `[tool.uv.sources]` path dependency. See
+  [docs/RUST_ACCELERATION.md](docs/RUST_ACCELERATION.md).
+
+### Fixed
+- `ImageRenderer._render_mixed_font` passed a `(text, script)` tuple to `draw.text()`
+  instead of the span's text string, which would have crashed any mixed-font render
+  (dead code path prior to this fix, since `mixed_font_prob` defaults to `0.0`).

khocr_gen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kosal Seng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

khocr_gen-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: khocr-gen
+Version: 0.1.0
+Summary: Synthetic OCR training data generator for mixed Khmer/English text
+Project-URL: Homepage, https://github.com/LazyGreed/khocr-gen
+Project-URL: Repository, https://github.com/LazyGreed/khocr-gen
+Project-URL: Issues, https://github.com/LazyGreed/khocr-gen/issues
+Project-URL: Changelog, https://github.com/LazyGreed/khocr-gen/blob/main/CHANGELOG.md
+Author: Kosal Seng
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-generation,deep-learning,image-generation,khmer,ocr,synthetic-data,text-recognition
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Fonts
+Requires-Python: >=3.12
+Requires-Dist: albumentations>=1.3.0
+Requires-Dist: khmernormalizer>=0.0.4
+Requires-Dist: lmdb>=1.4.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: opencv-python-headless>=4.8.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tqdm>=4.64.0
+Provides-Extra: dev
+Requires-Dist: khocr-gen-core; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: rust
+Requires-Dist: khocr-gen-core; extra == 'rust'
+Description-Content-Type: text/markdown
+
+# khocr-gen
+
+Synthetic OCR training data generator for mixed Khmer/English text.
+
+## Features
+
+- **Mixed-script rendering:** per-span font selection for Khmer + English
+- **24 augmentation methods:** unified registry covering scanner/camera degradations and training-time transforms
+- **Rust acceleration:** 21/24 augmentation methods plus font glyph checking run through a native PyO3 extension, with automatic pure-Python fallback
+- **Isolated augmentation:** one effect per image, weighted by configurable probabilities
+- **Configurable intensity ranges:** per-method `[min, max]` with linear sampling
+- **Multiprocess generation:** parallel workers for throughput
+- **LMDB packing:** efficient key–value storage for training pipelines
+- **n-way dataset combine:** merge multiple generated datasets into one
+- **Built-in viewer:** preview and extract images from LMDB databases
+- **YAML config files:** reproducible generation recipes
+- **Khmer normalization:** canonical character ordering via `khmernormalizer`
+
+## Installation
+
+```bash
+# Clone and install with uv
+git clone https://github.com/LazyGreed/khocr-gen.git
+cd khocr-gen
+uv sync
+
+# Or install with pip
+pip install .
+```
+
+`uv sync` also compiles and installs the optional Rust acceleration extension
+(`khocr-gen-core`, from `rust/`). This requires a Rust toolchain (`cargo`/`rustc`) on
+`PATH` — see [RUST_ACCELERATION.md](docs/RUST_ACCELERATION.md). If the extension isn't
+available, khocr-gen falls back to pure-Python implementations automatically.
+
+### Requirements
+
+- Python >= 3.12
+- Rust toolchain (`cargo`/`rustc`, edition 2021) — only needed to build the optional
+  acceleration extension; the project works without it
+
+## Quick Start
+
+### 1. Prepare fonts
+
+```text
+fonts/
+├── khmer/     <- .ttf / .otf Khmer fonts
+└── english/   <- .ttf / .otf English fonts
+```
+
+Fonts placed directly in `fonts/` (not in a subdirectory) are added to both pools as fallbacks.
+
+### 2. Prepare corpus
+
+A plain UTF-8 text file, one string per line:
+
+```text
+សួស្តី
+Hello World
+ស្វាគមន៍ Welcome
+```
+
+### 3. Generate a dataset
+
+```bash
+khocr-gen generate --corpus corpus/corpus.txt --fonts fonts --output data --copies 3 --storage lmdb
+```
+
+### 4. Verify augmentation quality
+
+Renders every augmentation method at min and max intensity on clean canvases:
+
+```bash
+khocr-gen verify --fonts fonts --output verify_output
+```
+
+### 5. View generated images
+
+```bash
+# Summary of an LMDB database
+khocr-gen view --lmdb data/train/lmdb
+
+# Extract images
+khocr-gen view --lmdb data/train/lmdb --output-dir extracted
+
+# Show labels only
+khocr-gen view --lmdb data/train/lmdb --labels-only
+```
+
+### 6. Combine multiple datasets
+
+```bash
+khocr-gen combine data_run1 data_run2 data_run3 --output data_merged
+```
+
+## Configuration
+
+All generation parameters can be specified via CLI flags, a YAML config file, or both (CLI overrides YAML).
+See [CONFIG.md](docs/CONFIG.md) for details.
+
+```bash
+khocr-gen generate --config configs/generate.yml
+```
+
+Config loading order (highest priority wins):
+1. argparse built-in defaults
+2. YAML config file values
+3. Explicit CLI flags
+
+## Augmentation
+
+24 methods in a unified registry (21 of them Rust-accelerated).
+Each generated image receives exactly one augmentation, chosen probabilistically by weight.
+See [AUGMENTATION.md](docs/AUGMENTATION.md) for the full catalog and visual examples.
+
+## CLI Reference
+
+See [CLI_REFERENCE.md](docs/CLI_REFERENCE.md) for complete command documentation.
+
+## Rust Acceleration
+
+See [RUST_ACCELERATION.md](docs/RUST_ACCELERATION.md) for what's accelerated, how the
+native extension is built/installed, and how to iterate on the `rust/` crate.
+
+## Project Structure
+
+```text
+src/khocr_gen/
+├── cli.py              # CLI entry point
+├── config.py           # GenerationConfig + AugMethodConfig dataclasses
+├── config_loader.py    # YAML config loading
+├── corpus.py           # Corpus loading / filtering / counting
+├── fonts.py            # FontManager with script-aware font selection
+├── normalizer.py       # Khmer text normalization wrapper
+├── rendering.py        # ImageRenderer: text -> clean canvas -> augmentation
+├── augmentation.py     # 24 augmentation methods (unified registry)
+├── _rust_accel.py      # Native/pure-Python dispatch layer for the Rust extension
+├── parallel.py         # Multiprocess rendering workers
+├── lmdb_pack.py        # LMDB database packing
+├── combine.py          # n-way dataset merge
+├── data_generator.py   # DatasetGenerator orchestrator
+├── generate.py         # generate CLI command
+├── verify.py           # verify CLI command
+├── viewer.py           # view CLI command
+├── combine_cmd.py      # combine CLI command
+└── errors.py           # Exception hierarchy
+
+rust/                    # khocr-gen-core: PyO3/maturin native acceleration extension
+├── Cargo.toml
+├── pyproject.toml
+└── src/
+    ├── lib.rs           # PyO3 bindings + module registration
+    ├── augmentation.rs  # Accelerated augmentation methods
+    ├── fonts.rs         # FontManager + FontFace (cmap glyph lookup)
+    ├── rendering.rs     # Unwired canvas-rendering prototype (not yet bound to Python)
+    └── utils.rs
+```
+
+## Acknowledgments
+
+khocr-gen builds on excellent open-source libraries:
+
+- [khmernormalizer](https://github.com/seanghay/khmernormalizer) (MIT) - Khmer text normalization
+- [OpenCV](https://opencv.org/) (Apache 2.0) - Image processing and augmentation
+- [Pillow](https://python-pillow.org/) (HPND) - Font rendering and image creation
+- [Albumentations](https://albumentations.ai/) (MIT) - Augmentation primitives
+- [NumPy](https://numpy.org/) (BSD-3-Clause) - Numerical operations
+- [LMDB](https://www.symas.com/lmdb) (OpenLDAP 2.8) - Embedded database for training pipelines
+
+## License
+
+MIT

khocr_gen-0.1.0/README.md

@@ -0,0 +1,173 @@
+# khocr-gen
+
+Synthetic OCR training data generator for mixed Khmer/English text.
+
+## Features
+
+- **Mixed-script rendering:** per-span font selection for Khmer + English
+- **24 augmentation methods:** unified registry covering scanner/camera degradations and training-time transforms
+- **Rust acceleration:** 21/24 augmentation methods plus font glyph checking run through a native PyO3 extension, with automatic pure-Python fallback
+- **Isolated augmentation:** one effect per image, weighted by configurable probabilities
+- **Configurable intensity ranges:** per-method `[min, max]` with linear sampling
+- **Multiprocess generation:** parallel workers for throughput
+- **LMDB packing:** efficient key–value storage for training pipelines
+- **n-way dataset combine:** merge multiple generated datasets into one
+- **Built-in viewer:** preview and extract images from LMDB databases
+- **YAML config files:** reproducible generation recipes
+- **Khmer normalization:** canonical character ordering via `khmernormalizer`
+
+## Installation
+
+```bash
+# Clone and install with uv
+git clone https://github.com/LazyGreed/khocr-gen.git
+cd khocr-gen
+uv sync
+
+# Or install with pip
+pip install .
+```
+
+`uv sync` also compiles and installs the optional Rust acceleration extension
+(`khocr-gen-core`, from `rust/`). This requires a Rust toolchain (`cargo`/`rustc`) on
+`PATH` — see [RUST_ACCELERATION.md](docs/RUST_ACCELERATION.md). If the extension isn't
+available, khocr-gen falls back to pure-Python implementations automatically.
+
+### Requirements
+
+- Python >= 3.12
+- Rust toolchain (`cargo`/`rustc`, edition 2021) — only needed to build the optional
+  acceleration extension; the project works without it
+
+## Quick Start
+
+### 1. Prepare fonts
+
+```text
+fonts/
+├── khmer/     <- .ttf / .otf Khmer fonts
+└── english/   <- .ttf / .otf English fonts
+```
+
+Fonts placed directly in `fonts/` (not in a subdirectory) are added to both pools as fallbacks.
+
+### 2. Prepare corpus
+
+A plain UTF-8 text file, one string per line:
+
+```text
+សួស្តី
+Hello World
+ស្វាគមន៍ Welcome
+```
+
+### 3. Generate a dataset
+
+```bash
+khocr-gen generate --corpus corpus/corpus.txt --fonts fonts --output data --copies 3 --storage lmdb
+```
+
+### 4. Verify augmentation quality
+
+Renders every augmentation method at min and max intensity on clean canvases:
+
+```bash
+khocr-gen verify --fonts fonts --output verify_output
+```
+
+### 5. View generated images
+
+```bash
+# Summary of an LMDB database
+khocr-gen view --lmdb data/train/lmdb
+
+# Extract images
+khocr-gen view --lmdb data/train/lmdb --output-dir extracted
+
+# Show labels only
+khocr-gen view --lmdb data/train/lmdb --labels-only
+```
+
+### 6. Combine multiple datasets
+
+```bash
+khocr-gen combine data_run1 data_run2 data_run3 --output data_merged
+```
+
+## Configuration
+
+All generation parameters can be specified via CLI flags, a YAML config file, or both (CLI overrides YAML).
+See [CONFIG.md](docs/CONFIG.md) for details.
+
+```bash
+khocr-gen generate --config configs/generate.yml
+```
+
+Config loading order (highest priority wins):
+1. argparse built-in defaults
+2. YAML config file values
+3. Explicit CLI flags
+
+## Augmentation
+
+24 methods in a unified registry (21 of them Rust-accelerated).
+Each generated image receives exactly one augmentation, chosen probabilistically by weight.
+See [AUGMENTATION.md](docs/AUGMENTATION.md) for the full catalog and visual examples.
+
+## CLI Reference
+
+See [CLI_REFERENCE.md](docs/CLI_REFERENCE.md) for complete command documentation.
+
+## Rust Acceleration
+
+See [RUST_ACCELERATION.md](docs/RUST_ACCELERATION.md) for what's accelerated, how the
+native extension is built/installed, and how to iterate on the `rust/` crate.
+
+## Project Structure
+
+```text
+src/khocr_gen/
+├── cli.py              # CLI entry point
+├── config.py           # GenerationConfig + AugMethodConfig dataclasses
+├── config_loader.py    # YAML config loading
+├── corpus.py           # Corpus loading / filtering / counting
+├── fonts.py            # FontManager with script-aware font selection
+├── normalizer.py       # Khmer text normalization wrapper
+├── rendering.py        # ImageRenderer: text -> clean canvas -> augmentation
+├── augmentation.py     # 24 augmentation methods (unified registry)
+├── _rust_accel.py      # Native/pure-Python dispatch layer for the Rust extension
+├── parallel.py         # Multiprocess rendering workers
+├── lmdb_pack.py        # LMDB database packing
+├── combine.py          # n-way dataset merge
+├── data_generator.py   # DatasetGenerator orchestrator
+├── generate.py         # generate CLI command
+├── verify.py           # verify CLI command
+├── viewer.py           # view CLI command
+├── combine_cmd.py      # combine CLI command
+└── errors.py           # Exception hierarchy
+
+rust/                    # khocr-gen-core: PyO3/maturin native acceleration extension
+├── Cargo.toml
+├── pyproject.toml
+└── src/
+    ├── lib.rs           # PyO3 bindings + module registration
+    ├── augmentation.rs  # Accelerated augmentation methods
+    ├── fonts.rs         # FontManager + FontFace (cmap glyph lookup)
+    ├── rendering.rs     # Unwired canvas-rendering prototype (not yet bound to Python)
+    └── utils.rs
+```
+
+## Acknowledgments
+
+khocr-gen builds on excellent open-source libraries:
+
+- [khmernormalizer](https://github.com/seanghay/khmernormalizer) (MIT) - Khmer text normalization
+- [OpenCV](https://opencv.org/) (Apache 2.0) - Image processing and augmentation
+- [Pillow](https://python-pillow.org/) (HPND) - Font rendering and image creation
+- [Albumentations](https://albumentations.ai/) (MIT) - Augmentation primitives
+- [NumPy](https://numpy.org/) (BSD-3-Clause) - Numerical operations
+- [LMDB](https://www.symas.com/lmdb) (OpenLDAP 2.8) - Embedded database for training pipelines
+
+## License
+
+MIT

khocr_gen-0.1.0/docs/AUGMENTATION.md

@@ -0,0 +1,242 @@
+# Augmentation Reference
+
+`khocr-gen` provides 24 augmentation methods in a unified registry.
+Each generated image receives **exactly one** augmentation applied to a clean rendered canvas; effects are never stacked.
+
+21 of the 24 methods run through a native Rust extension when available (falling back to
+pure Python/OpenCV otherwise) — `distortion`, `albu_noise`, and `gradient_illumination`
+are the exceptions. See [RUST_ACCELERATION.md](RUST_ACCELERATION.md) for details.
+
+## Architecture
+
+```text
+Clean canvas -> pick 1 method (weighted by prob) -> sample intensity ∈ [min, max] -> apply -> output
+```
+
+### Selection
+
+From all methods with `prob > 0`, one is chosen with probability proportional to its `prob` weight:
+
+```
+P(method_i) = prob_i / Σ prob_j    (for all enabled methods j)
+```
+
+### Intensity
+
+Once a method is chosen, its intensity is sampled uniformly from its configured `[min, max]` range (both in [0, 1]).
+The method maps this to physical units:
+
+| Method | intensity -> physical |
+|--------|---------------------|
+| blur | kernel size [3, 15] |
+| rotation | degrees [0.5, 8.0] |
+| salt_pepper | pixel density [0.001, 0.04] |
+| jpeg_compression | quality [95, 25] (inverted) |
+| sauvola | k value [0.05, 0.50] |
+| geo_warp | corner displacement [0.5, 12] px |
+| lowdpi | downsample ratio [0.15, 0.80] |
+
+---
+
+## Augmentation Methods (24 methods)
+
+All methods are applied in isolation; one effect per image, chosen probabilistically from the unified registry.
+
+### `sauvola`: Sauvola Local Threshold Degradation
+
+Simulates degraded binarization artifacts common in scanned documents.
+
+- **Intensity -> k parameter** [0.05, 0.50]
+- Uses adaptive window (25 px, capped by image size)
+- Blends binary result with original via weighted alpha
+
+### `geo_warp`: Geometric Perspective Warp
+
+4-point perspective distortion simulating camera angle or page curl.
+
+- **Intensity -> corner displacement** [0.5, 12] px
+- Background color estimated from image border
+- Border filled with estimated background
+
+### `vertical_crop`: Vertical Crop
+
+Crops and pads top or bottom edge, simulating misaligned scanning.
+
+- **Intensity -> crop amount** [1, 8] px
+- Crops from foreground region edge
+- Pads with estimated background color
+
+### `blur`: Blur (Motion/Median/Gaussian)
+
+Uses Albumentations `OneOf` pipeline (falls back to OpenCV GaussianBlur).
+
+- **Intensity -> kernel size** [3, 15] (odd)
+- Random choice: MotionBlur, MedianBlur, or GaussianBlur
+- Pure OpenCV fallback if Albumentations unavailable
+
+### `distortion`: Distortion (Optical/Grid/Elastic)
+
+Uses Albumentations `OneOf` pipeline (no-op fallback without Albumentations).
+
+- **Intensity -> distort_limit** [0.05, 0.30]
+- Random choice: OpticalDistortion, GridDistortion, or ElasticTransform
+- Grid uses 5 steps; Elastic uses 20 sigma
+
+### `albu_noise`: Noise (Gaussian/Multiplicative)
+
+Uses Albumentations `OneOf` pipeline (OpenCV fallback available).
+
+- **Intensity -> std deviation** [0.005, 0.20] normalized units
+- Random choice: GaussNoise or MultiplicativeNoise
+- Fallback: additive Gaussian noise σ [3, 25]
+
+### `jpeg_compression`: JPEG Compression Artifacts
+
+Encodes and decodes the image at configurable quality levels.
+
+- **Intensity -> JPEG quality** [95, 25] (inverted: higher intensity = lower quality)
+- Uses cv2.imencode/imdecode round-trip
+- Handles both grayscale and RGB
+
+### `rotation`: Random Rotation
+
+Small-angle rotation with border fill.
+
+- **Intensity -> max degrees** [0.5, 8.0]
+- Direction: random clockwise or counter-clockwise
+- Border filled with estimated background color
+
+### `salt_pepper`: Salt-and-Pepper Noise
+
+Impulse noise: random white (salt) and black (pepper) pixels.
+
+- **Intensity -> pixel density** [0.001, 0.04]
+- Equal distribution of salt and pepper
+- Works on both grayscale and RGB
+
+### `background_texture`: Background Texture Overlay
+
+Procedural paper-like texture with three modes:
+
+1. **Fine grain**: per-pixel Gaussian noise
+2. **Coarse blotches**: low-resolution noise upscaled and blurred
+3. **Streaks**: horizontal line artifacts (scanner streaks)
+
+- **Intensity -> blend alpha** [0.05, 0.30]
+- Texture suppressed over dark ink regions (preserves text legibility)
+
+### `lowdpi`: Low-DPI Simulation
+
+Downscale-then-upscale using NEAREST for downsample and LANCZOS4 for upsample.
+
+- **Intensity -> downsample ratio** [0.15, 0.80] (inverted: higher = smaller = lower DPI)
+- Minimum output dimension: 2 px
+
+### `oversample`: Oversample Rendering
+
+Post-hoc sharpening filter (the rendering-mode oversample is handled in
+the renderer, not here).
+
+- **Intensity -> sharpen strength** [1.0, 1.5]
+- Uses a 3×3 unsharp mask kernel
+
+---
+
+## Training-time Augmentations
+
+These methods simulate augmentations typically applied during OCR training.
+They are disabled by default (`prob: 0.0`) but can be enabled to make generated data more closely match training-time conditions.
+
+### `perspective`: Online Perspective Warp
+
+Mild perspective distortion via OpenCV `getPerspectiveTransform`.
+
+- **Intensity -> max displacement fraction** [0.02, 0.12] of image size
+- Border filled with gray (128)
+
+### `elastic`: Online Elastic Distortion
+
+Displacement-field-based elastic deformation.
+
+- **Intensity -> displacement sigma** [0.02×size, 0.12×size]
+- Coarse grid scaled to full resolution
+
+### `random_crop`: Online Random Height Crop
+
+Crop top or bottom and resize back to original dimensions.
+
+- **Intensity -> crop fraction** [0.01, 0.08] of height
+
+### `online_blur`: Online Blur
+
+Gaussian or Motion blur.
+
+- **Intensity -> kernel size** [3, 7] (odd)
+- 50% chance of MotionBlur if Albumentations available
+
+### `online_noise`: Online Gaussian Noise
+
+Additive Gaussian noise.
+
+- **Intensity -> noise sigma** [3, 30]
+
+### `hsv`: HSV Color Jitter
+
+Saturation and value adjustments (grayscale images pass through unchanged).
+
+- **Intensity -> jitter factor** [0.60, 0.95]
+- Independent random multiplier for S and V channels
+
+### `reverse`: Color Reversal
+
+Inverts pixel values (dark <-> light). Common for handling negative/white-on-black text.
+
+- **Intensity ignored**: binary on/off effect
+- `255 - pixel` for every pixel
+
+### `brightness_contrast`: Brightness/Contrast Jitter
+
+Alpha (contrast) and beta (brightness) adjustments via `cv2.convertScaleAbs`.
+
+- **Intensity -> contrast spread** [0.02, 0.25], brightness [0, ±30]
+
+### `pixelation`: Pixelation
+
+Downscale then upscale to produce blocky/pixelated artifacts.
+
+- **Intensity -> scale fraction** [0.2, 0.9] (inverted: higher = more pixelated)
+- Random interpolation: NEAREST or LINEAR
+
+### `gradient_illumination`: Gradient Illumination
+
+Linear gradient overlay simulating uneven lighting.
+
+- **Intensity -> gradient strength** [0.1, 0.6]
+- Random direction: horizontal or vertical, left-to-right or right-to-left
+
+### `morphological`: Morphological Operations
+
+Erosion or dilation with a small kernel.
+
+- **Intensity 0.0–0.5 -> kernel size 2**; **0.5–1.0 -> kernel size 3**
+- Khmer-aware mode: 70% erode, 30% horizontal dilate
+- English mode: 50/50 erode/dilate with square kernel
+
+### `anisotropic_dilation`: Anisotropic Dilation
+
+Directional dilation simulating dot-matrix printer spread.
+
+- **Intensity 0.0–0.5 -> kernel size 2**; **0.5–1.0 -> kernel size 3 or 4**
+- Random direction: horizontal or vertical kernel
+
+---
+
+## Verify Command
+
+To see every method at min and max intensity on a clean canvas:
+
+```bash
+khocr-gen verify --fonts fonts --output verify_output
+```
+
+This produces one PNG per method showing the clean canvas with the method applied at intensity 0.0 (left half) and 1.0 (right half).