Skip to main content

​
Overview

The retto-cli provides a command-line interface for running OCR inference on images using PaddleOCR models.

​
Installation

cargo install retto-cli

​
Usage

retto-cli [OPTIONS] --images <IMAGES>

​
Command Structure

pub struct Cli {
    det_model_path: String,
    cls_model_path: String,
    rec_model_path: String,
    rec_keys_path: String,
    images: String,
    device: DeviceKind,
    device_id: i32,
    use_hf_hub: bool,
}
Source: retto-cli/src/main.rs:20

​
Options

​
Model Paths

​
--det-model-path
string
default:"ch_PP-OCRv4_det_infer.onnx"
Path to the text detection model (ONNX format)
​
--cls-model-path
string
default:"ch_ppocr_mobile_v2.0_cls_infer.onnx"
Path to the text classification/angle model (ONNX format)
​
--rec-model-path
string
default:"ch_PP-OCRv4_rec_infer.onnx"
Path to the text recognition model (ONNX format)
​
--rec-keys-path
string
default:"ppocr_keys_v1.txt"
Path to the character dictionary file for recognition

​
Input

​
--images
string
required
Path to a directory containing images or a single image fileSupports recursive directory traversal to process all image files

​
Device Configuration

​
--device
enum
default:"cpu"
Execution device for inferenceOptions:
  • cpu - Use CPU execution (always available)
  • cuda - Use NVIDIA CUDA GPU (requires backend-ort-cuda feature)
  • directml - Use DirectML on Windows (requires backend-ort-directml feature)
​
--device-id
integer
default:"0"
Device ID when using GPU acceleration (CUDA or DirectML)Only applicable when --device is set to cuda or directml

​
Model Source

​
--use-hf-hub
boolean
default:"true"
Download models from Hugging Face Hub instead of using local filesRequires: hf-hub feature flagWhen enabled, downloads PaddleOCR v4 models from the default repository (pk5ls20/PaddleModel)

​
Examples

​
Basic Usage (CPU)

Process images using CPU with Hugging Face Hub models: 
retto-cli --images ./photos/

​
Using Local Models

Process with locally stored model files: 
retto-cli \
  --images ./photos/ \
  --use-hf-hub false \
  --det-model-path ./models/ch_PP-OCRv4_det_infer.onnx \
  --cls-model-path ./models/ch_ppocr_mobile_v2.0_cls_infer.onnx \
  --rec-model-path ./models/ch_PP-OCRv4_rec_infer.onnx \
  --rec-keys-path ./models/ppocr_keys_v1.txt

​
GPU Acceleration (CUDA)

Run inference on NVIDIA GPU device 0: 
retto-cli --images ./photos/ --device cuda --device-id 0

​
GPU Acceleration (DirectML)

Run inference using DirectML on Windows: 
retto-cli --images ./photos/ --device directml --device-id 0

​
Single Image

Process a single image file: 
retto-cli --images ./document.jpg

​
Custom Dictionary

Use a custom character dictionary: 
retto-cli \
  --images ./photos/ \
  --rec-keys-path ./custom_chars.txt

​
Output

The CLI processes all images and outputs performance metrics: 
[INFO] Found 15 files, processing...
[INFO] Successfully processed 15 images, avg time: 127.34ms

​
Log Levels

Set the log level using the RUST_LOG environment variable: 
# Debug mode - verbose output
RUST_LOG=debug retto-cli --images ./photos/

# Info mode (default)
RUST_LOG=info retto-cli --images ./photos/

# Minimal output
RUST_LOG=error retto-cli --images ./photos/
Default log configuration: 
EnvFilter::new("ort=debug,retto_core=debug,retto_cli=debug")

​
Implementation Details

​
Directory Walking

The CLI uses walkdir to recursively traverse directories: 
let walkers = WalkDir::new(&cli.images);
let files = walkers
    .into_iter()
    .filter_map(|e| e.ok())
    .filter(|e| e.file_type().is_file())
    .collect::<Vec<_>>();
Source: retto-cli/src/main.rs:72

​
Session Configuration

The CLI creates a session with the specified configuration: 
let cfg: RettoSessionConfig<RettoOrtWorker> = RettoSessionConfig {
    worker_config: RettoOrtWorkerConfig { device, models },
    ..Default::default()
};

let mut session = RettoSession::new(cfg)?;
Source: retto-cli/src/main.rs:67

​
Performance Measurement

Processing time is measured and averaged across all images: 
let start = Instant::now();
let results = files
    .iter()
    .map(|e| {
        let img = fs::read(e.path()).expect("Failed to read image file");
        session.run(img)
    })
    .collect::<Vec<_>>();
let duration = start.elapsed();
Source: retto-cli/src/main.rs:79

​
Features

The CLI supports different features that can be enabled during compilation: 
cargo build --release

​
Error Handling

Common errors and solutions:
Error: ModelNotFoundErrorSolution: Ensure model files exist at the specified paths, or enable --use-hf-hub to download them automatically.
Error: Failed to read image fileSolution: Check that the image path is correct and the file is readable. Supported formats depend on the image crate.
Error: Feature not enabledSolution: Rebuild with the appropriate feature flag: --features backend-ort-cuda or --features backend-ort-directml.
For best performance, use GPU acceleration with --device cuda on systems with NVIDIA GPUs.

Build docs developers (and LLMs) love

Get started for freeTalk to us