Configuration

OcrConfig aggregates four per-stage structs. Every struct is #[serde(default, deny_unknown_fields)], so it loads from partial TOML/JSON and rejects unknown fields (a typo fails loudly rather than silently doing nothing), and is entirely backend-agnostic.

pub struct OcrConfig {
    pub detection: DetectionConfig,
    pub recognition: RecognitionConfig,
    pub concurrency: ConcurrencyConfig,
    pub model: ModelConfig,
}

Precedence

OcrConfig’s designed layering is:

defaults < config file < environment < CLI flags

Each layer only overrides the fields it sets; anything unset falls through to the layer below. Today only the defaults < flags ends of that chain exist. The CLI starts from OcrConfig::default() and applies the shared overrides (--lang, --threads, --backend, --accelerator, --text-threshold, --link-threshold, --canvas-size) on top.

There is no config-file loader and no SCEPTRE_* environment variable. The structs derive Serialize/Deserialize, so you can deserialize an OcrConfig from TOML or JSON in your own code, but nothing in the library or the CLI reads a file or an environment variable to populate one. (Two environment variables do exist, but neither is an OcrConfig layer: EASYOCR_LOG sets the CLI’s --log-level, and the Hugging Face cache variables are read at model-resolution time when cache_dir is left None.) Fields with no CLI flag — cache_dir, registry_owner, detector_path, recognizer_path — are reachable only from library code. From there, build the layering yourself by starting from OcrConfig::default() and overriding fields (see Library).

`DetectionConfig`

CRAFT detection and box-grouping parameters. Defaults mirror EasyOCR’s readtext detection parameters.

Field	Default	Description
`text_threshold`	`0.7`	Text confidence threshold (region score).
`link_threshold`	`0.4`	Link confidence threshold (affinity score).
`low_text`	`0.4`	Low-bound text score for region growth.
`canvas_size`	`2560`	Maximum image dimension before down-scaling.
`mag_ratio`	`1.0`	Magnification ratio applied before detection.
`min_size`	`20`	Minimum box size (px) to keep.
`slope_ths`	`0.1`	Slope threshold for splitting horizontal vs. free boxes.
`ycenter_ths`	`0.5`	Vertical-center threshold for line merging.
`height_ths`	`0.5`	Height threshold for line merging.
`width_ths`	`0.5`	Width threshold for line merging.
`add_margin`	`0.1`	Fractional margin added around each box.

`RecognitionConfig`

CRNN recognition and CTC decoding parameters.

Field	Default	Description
`decoder`	`Decoder::Greedy`	CTC decoding strategy. `BeamSearch` and `WordBeamSearch` are reserved variants — not yet implemented; setting either is a hard error at recognition time.
`beam_width`	`5`	Reserved for a future beam-search decoder. Not yet implemented — has no effect while `decoder` is `Greedy`.
`batch_size`	`1`	Recognition batch size.
`allowlist`	`""` (empty)	Only these characters may be produced; empty uses the model’s full charset.
`blocklist`	`""` (empty)	These characters are never produced.
`contrast_ths`	`0.1`	Contrast below which a low-confidence second pass runs.
`adjust_contrast`	`0.5`	Target contrast for the adjustment pass.
`filter_ths`	`0.1`	Minimum confidence a recognized region needs to be emitted; results below it are dropped. Validated to `[0, 1]`.

The recognizer’s fixed input height (imgH, 64) is an internal constant, not a config field.

`ConcurrencyConfig`

Field	Default	Description
`max_threads`	`None` (auto: `num_cpus`, capped at `8`)	Maximum threads for every internal pool — Rayon and, once wired, the backend’s intra-op threads.

See Backends for why this is a single shared budget.

`ModelConfig`

Field	Default	Description
`languages`	`[Language::English]`	Recognition languages to load. Repeatable — one recognizer per entry, duplicates preserved.
`backend`	`Backend::Ort`	Inference backend: `Ort`, `Tract`, or `Candle`.
`accelerator`	`Accelerator::Cpu`	Hardware the backend runs the graph on: `Cpu`, `Auto`, `CoreMl`, `DirectMl`, `Metal`, or `Cuda`. Which values a backend accepts is given by `Backend::hardware_accelerators()`; anything else is rejected by validation. See Backends.
`detector_path`	`None`	Explicit local CRAFT ONNX path for host-managed assets. Must be set together with `recognizer_path`; when both are set the default provider bypasses Hugging Face entirely. Library-only — no CLI flag.
`recognizer_path`	`None`	Explicit local recognizer ONNX path for the configured language group. Must be set together with `detector_path`. Library-only — no CLI flag.
`cache_dir`	`None`	Override for the Hugging Face hub cache root. `None` resolves from `HF_HUB_CACHE` → `HUGGINGFACE_HUB_CACHE` → `$HF_HOME/hub` → `~/.cache/huggingface/hub`. Library-only — no CLI flag.
`registry_owner`	`None`	Override for the Hugging Face registry owner. `None` uses the first-party `xberg-io` org (repos are named `xberg-io/sceptre-<model>`); only the owner segment of each model repo id changes. Library-only — no CLI flag.

Setting only one of detector_path / recognizer_path is a config error naming the missing field, rather than a silent half-local provisioning.

Feature-flag interaction

Selecting Backend::Tract requires the crate built with the tract feature; Backend::Ort requires ort (via ort-bundled or ort-dynamic); Backend::Candle requires candle. A non-CPU accelerator additionally requires the matching feature — ort-coreml, ort-directml, ort-cuda on the ort backend, or candle-metal, candle-cuda on candle — and for ort, an ONNX Runtime build that carries that provider.

cache_dir/registry_owner and model provisioning (model_manifest, download_models) only fetch missing artifacts when the download feature is enabled — without it, download_models returns an OcrError::Model describing the missing feature, while model_manifest’s offline cache inspection works either way. See Feature flags and Offline and CI.