Cargo Features

August 20, 2026 · View on GitHub

The root oar-ocr crate exposes optional Cargo features. Each feature is forwarded to oar-ocr-core under the same name.

The Cargo feature named default is not an additional capability. It is a feature set that enables download-binaries and simd.

At a Glance

Feature	Enabled by default	Category	Purpose
`simd`	Yes	CPU optimization	Accelerates CHW image normalization and CTC argmax decoding
`cuda`	No	Execution provider	Enables the ONNX Runtime CUDA provider for NVIDIA GPUs
`tensorrt`	No	Execution provider	Enables the ONNX Runtime TensorRT provider
`directml`	No	Execution provider	Enables the DirectML provider on Windows
`coreml`	No	Execution provider	Enables the Core ML provider on macOS and iOS
`webgpu`	No	Execution provider	Enables the WebGPU provider on supported ONNX Runtime targets
`openvino`	No	Execution provider	Enables the Intel OpenVINO provider
`download-binaries`	Yes	Build setup	Downloads a compatible ONNX Runtime distribution during the build
`auto-download`	No	Model management	Downloads registered OCR model files from ModelScope when first used

Default Configuration

The standard dependency declaration enables download-binaries and simd:

cargo add oar-ocr

This configuration uses the CPU execution provider unless an accelerator is enabled and selected through OrtSessionConfig. It also downloads the ONNX Runtime binaries required for linking and enables the optimized CPU preprocessing kernels.

Disable both defaults with:

cargo add oar-ocr --no-default-features

With default features disabled, CPU preprocessing uses scalar fallbacks. An ONNX Runtime installation must also be supplied before linking. See download-binaries for the system-runtime setup.

CPU Optimization

`simd`

simd accelerates two hot CPU paths in oar-ocr-core:

Per-pixel CHW image normalization
Per-timestep CTC argmax decoding

The implementation uses wide and multiversion to select an available instruction set at runtime. Supported targets can use AVX2, SSE4.2, or NEON without compiling with target-cpu=native. The SIMD and scalar paths are tested for identical output.

This feature improves CPU pre-processing and post-processing only. It does not change the ONNX Runtime execution provider.

To keep automatic ONNX Runtime setup while disabling SIMD:

cargo add oar-ocr --no-default-features --features download-binaries

Execution Provider Features

The execution provider features make their corresponding ONNX Runtime providers available to the crate. Enabling a feature does not select that provider automatically. Configure the provider explicitly and place the CPU provider last when a fallback is desired.

use oar_ocr::core::config::{OrtExecutionProvider, OrtSessionConfig};

let ort_config = OrtSessionConfig::new().with_execution_providers(vec![
    OrtExecutionProvider::CUDA {
        device_id: Some(0),
        gpu_mem_limit: None,
        arena_extend_strategy: None,
        cudnn_conv_algo_search: None,
        cudnn_conv_use_max_workspace: None,
    },
    OrtExecutionProvider::CPU,
]);

Pass the configuration to OAROCRBuilder::ort_session or OARStructureBuilder::ort_session. Requesting a provider without its matching Cargo feature returns a configuration error.

`cuda`

Enables the NVIDIA CUDA execution provider. It is intended for supported Linux and Windows targets and requires a compatible NVIDIA driver, CUDA runtime, and cuDNN installation.

cargo add oar-ocr --features cuda

The CUDA provider supports device selection, a GPU memory limit, arena growth strategy, cuDNN convolution algorithm selection, and maximum-workspace control through OrtExecutionProvider::CUDA.

`tensorrt`

Enables the NVIDIA TensorRT execution provider on supported Linux and Windows targets. The host must provide compatible TensorRT and CUDA runtimes.

TensorRT can fall back directly to CPU. For the usual TensorRT to CUDA to CPU provider chain, enable both accelerator features:

cargo add oar-ocr --features tensorrt,cuda

OrtExecutionProvider::TensorRT exposes workspace, FP16, timing-cache, engine-cache, and embedded-engine context options.

`directml`

Enables the DirectML execution provider for Windows devices supported by DirectX 12. Select a device with the device_id field on OrtExecutionProvider::DirectML.

cargo add oar-ocr --features directml

`coreml`

Enables the Core ML execution provider on macOS and iOS. Its configuration can prefer the Apple Neural Engine and can enable subgraph execution.

cargo add oar-ocr --features coreml

This feature controls the ONNX Runtime Core ML provider used by the classic pipeline. The metal feature in oar-ocr-vl is separate.

OrtExecutionProvider::CoreML retains its original ane_only and subgraphs fields. OrtSessionConfig::with_coreml_config adds compute-unit selection, MLProgram versus legacy NeuralNetwork format, static-input filtering, specialization strategy, low-precision GPU accumulation, profiling, and a compiled-model cache path without changing that provider variant's shape. The OCR example accepts coreml[:gpu|ane|cpu], coreml-nn[:...], and coreml-static[:...].

static_input_shapes only controls which graphs Core ML will claim. It does not turn a dynamic ONNX model into a fixed-shape model: the ONNX input itself must contain concrete dimensions, and preprocessing must produce that exact shape. Static Core ML is most useful for larger models processing repeated, fixed-size pages; compilation and provider handoff can outweigh the benefit for small mobile models or one-off requests.

`webgpu`

Enables the ONNX Runtime WebGPU execution provider. Target and binary support depends on the ONNX Runtime distribution used for the build.

cargo add oar-ocr --features webgpu

Select it with OrtExecutionProvider::WebGPU.

`openvino`

Enables the Intel OpenVINO execution provider on supported Linux and Windows targets. OrtExecutionProvider::OpenVINO accepts a device type and an optional thread count.

cargo add oar-ocr --features openvino

Runtime and Model Downloads

`download-binaries`

download-binaries asks the pinned ort dependency to fetch a compatible ONNX Runtime distribution during the build. It is enabled by default and uses the platform certificate store for TLS.

This feature supplies the inference runtime. It does not download OCR model files.

For offline, enterprise, or custom ONNX Runtime builds, disable the default features and point ORT_LIB_LOCATION at the directory containing the ONNX Runtime libraries:

ORT_LIB_LOCATION=/opt/onnxruntime/lib \
    cargo build --no-default-features --features simd

If an execution provider feature is enabled, the supplied ONNX Runtime build must contain that provider and its runtime dependencies. Prebuilt availability also varies by target and provider combination.

`auto-download`

auto-download fetches registered OCR model files from greatv/oar-ocr on ModelScope when a builder receives a missing bare model name. Files are cached under $OAR_HOME, which defaults to ~/.oar, and are verified against the bundled size and SHA-256 registry.

cargo add oar-ocr --features auto-download

Existing files and explicit paths remain under caller control. In-memory ONNX sources also bypass the download resolver. See the model guide for the complete path-resolution and cache rules.

auto-download supplies model files at runtime. It does not install ONNX Runtime or any accelerator dependencies.

`oar-ocr-vl` needs none of this

oar-ocr-vl is a separate, self-contained crate. It runs every model on Candle — including layout detection, through oar_ocr_vl::PpDocLayout, a native port of PP-DocLayoutV2/V3 — so it depends on neither oar-ocr-core nor ONNX Runtime, and none of the features above apply to it. All model implementations are always available; only its accelerator features are optional and both are off by default.

Feature	Purpose
`cuda`	Candle CUDA backend
`metal`	Candle Metal backend

To source layout from somewhere else, implement oar_ocr_vl::LayoutSource and pass it to DocParser::parse.

Recommended Combinations

Use case	Features
Standard CPU inference	Defaults only
CPU inference with automatic model downloads	`auto-download`
NVIDIA CUDA	`cuda`
NVIDIA CUDA with automatic model downloads	`cuda,auto-download`
NVIDIA TensorRT with CUDA and CPU fallbacks	`tensorrt,cuda`
Windows DirectML	`directml`
Apple Core ML	`coreml`
Intel OpenVINO	`openvino`
WebGPU on a supported target	`webgpu`

Features listed in this table are added to the two default features unless --no-default-features is supplied.

Selection Rules and Common Pitfalls

Cargo features are additive. Another dependency in the graph can re-enable a feature that was disabled locally.
CPU execution is always available and does not have a dedicated feature.
Execution provider order matters. ONNX Runtime tries providers in the order supplied to OrtSessionConfig.
Feature flags compile provider support but do not install GPU drivers, TensorRT, DirectML, Core ML, OpenVINO, or other system runtimes.
Avoid --all-features for normal builds. Several providers are platform-specific and some provider combinations have no matching prebuilt ONNX Runtime distribution.
The oar-ocr-vl crate is independent of everything documented here; see oar-ocr-vl needs none of this.

Inspect the resolved feature graph with:

cargo tree -e features -i oar-ocr