Struct MonOcrBuilder 

pub struct MonOcrBuilder { /* private fields */ }

Builder for configuring and creating MonOcr instances

The builder pattern allows flexible configuration of OCR settings before creating an instance. All settings have sensible defaults.

Configuration Options

• model_path: Custom path to the ONNX model file (default: download from HuggingFace)
• charset: Custom character set for OCR (default: built-in Mon charset)
• min_line_height: Minimum height for line segmentation (default: 10 pixels)
• smooth_window: Window size for smoothing projection profile (default: 3)
• density_threshold_ratio: Gap threshold as a fraction of mean row density (default: 0.05)

Example

use monocr_onnx::MonOcr;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut ocr = MonOcr::builder()
        .min_line_height(15)
        .smooth_window(5)
        .build()
        .await?;

    let text = ocr.read_image("document.png").await?;
    println!("{text}");
    Ok(())
}

Implementations

impl MonOcrBuilder

pub fn new() -> Self

Create a new builder with default settings

This is equivalent to calling MonOcrBuilder::default().

Returns

A new MonOcrBuilder instance with default configuration

Example

use monocr_onnx::MonOcrBuilder;

let builder = MonOcrBuilder::new();

pub fn model_path(self, path: impl AsRef<Path>) -> Self

Set the path to the ONNX model file

By default, the model is downloaded from HuggingFace if not found in cache. Use this method to specify a custom model file location.

Arguments

• path - Path to the ONNX model file

Returns

The builder with the model path set

Example

use monocr_onnx::MonOcr;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ocr = MonOcr::builder()
        .model_path("./models/monocr.onnx")
        .build()
        .await?;
    Ok(())
}

pub fn charset(self, charset: impl Into<String>) -> Self

Set the charset string directly

The charset defines all characters that the OCR model can recognize. It should be a string containing all valid characters in order.

Arguments

• charset - A string containing the character set

Returns

The builder with the charset set

Note

The charset must match the one used during model training. The default charset is built-in and suitable for Mon text.

pub fn min_line_height(self, height: u32) -> Self

Set the minimum line height for segmentation

During line segmentation, any detected region shorter than this value will be ignored. This helps filter out noise and small artifacts.

Arguments

• height - Minimum line height in pixels (default: 10)

Returns

The builder with the minimum line height set

Recommendation

Increase this value for noisy documents or decrease for documents with small font sizes.

pub fn smooth_window(self, window: u32) -> Self

Set the smoothing window for projection profile

The smoothing window is used when computing the horizontal projection profile for line detection. A larger window produces smoother results but may merge close lines.

Arguments

• window - Window size for smoothing (default: 3, use 1 for no smoothing)

Returns

The builder with the smooth window set

pub fn tile_wide_lines(self, tile: bool) -> Self

Set the gap threshold for line segmentation

A row counts as a gap between lines when its ink density falls below ratio times the mean density of the page’s non-empty rows. Lower it to split lines that are being merged; raise it to stop faint texture between lines from cutting one line in two.

Arguments

• ratio - Fraction of mean row density, greater than 0 (default: 0.05)

Why this is exposed

The right value is a property of the input class, not a constant waiting to be settled. mon_OCR/docs/LIMITATIONS.md:304-334 measured the ordering reversing between a book page and a photographed poster: a six-line slide returned 3 lines at the low ratio and all 6 at 0.50, and the response to the ratio is explicitly non-monotone. So a caller that knows what it is reading can do better than any single default, and every port of this pipeline picked a different number.

Errors

build fails if ratio is not finite or not positive. At 0 every row clears the threshold and the page comes back as one band, which is a wrong result rather than a degraded one. Squeeze wide lines into the window instead of tiling them.

Tiling is the default and should stay the default. This exists so the two strategies can be measured against each other on the same pipeline, which mon_OCR/docs/ROADMAP.md item 4.5.6 requires before either is trusted, and which was impossible while the squeeze arm was unreachable.

The measurement in mon_OCR/eval/tiling-ab-2026-08-22.md found the answer is width-dependent: squeezing is mildly better up to 3 tiles and 3.7x to 24x worse from 4 tiles up, where it drives CER above 0.9. Tiling is the safe default because its downside is bounded and squeezing’s is not.

Examples found in repository

examples/tiling_ab.rs (line 101)

async fn main() -> Result<()> {
    let dir: PathBuf = std::env::args()
        .nth(1)
        .context("usage: tiling_ab <dir with line_*.png and labels.txt>")?
        .into();

    let labels_path = dir.join("labels.txt");
    let labels_raw = std::fs::read_to_string(&labels_path)
        .with_context(|| format!("cannot read {}", labels_path.display()))?;

    let mut labels: Vec<(PathBuf, String)> = Vec::new();
    for line in labels_raw.lines() {
        let Some((name, text)) = line.split_once('\t') else {
            continue;
        };
        labels.push((dir.join(name), text.to_string()));
    }
    if labels.is_empty() {
        anyhow::bail!(
            "{} contained no tab-separated entries",
            labels_path.display()
        );
    }
    eprintln!("{} labelled lines", labels.len());

    // Null baseline, asserted before any real number is produced. If the metric
    // arithmetic is wrong every rate below is wrong in the same direction, and
    // nothing else in this example would reveal it.
    assert_eq!(
        char_cer("", "abc"),
        1.0,
        "empty prediction must score exactly 1.0"
    );
    assert_eq!(
        char_cer("abc", "abc"),
        0.0,
        "identity must score exactly 0.0"
    );
    eprintln!("null baseline ok");

    // Two sessions rather than rebuilding one per arm: the flag is fixed at build
    // time, and reloading the graph 240 times would dominate the runtime.
    let mut tiled = MonOcr::builder().tile_wide_lines(true).build().await?;
    let mut squeezed = MonOcr::builder().tile_wide_lines(false).build().await?;

    let mut rows: Vec<Row> = Vec::new();
    for (i, (path, truth)) in labels.iter().enumerate() {
        let t = tiled.predict_single_line(path).await?;
        let s = squeezed.predict_single_line(path).await?;

        // Recovered from the geometry: a tiled read reports the union of its
        // tiles, so width over the window width is the tile count.
        let img = image::open(path)?.to_luma8();
        let (w, h) = img.dimensions();
        let scaled = (w as f64 * (160.0 / h as f64)) as u32;
        let tiles = ((scaled as f64) / 1024.0).ceil().max(1.0) as usize;

        rows.push(Row {
            tiles,
            cer_tiled: char_cer(&t.text, truth),
            cer_squeezed: char_cer(&s.text, truth),
        });

        if (i + 1) % 25 == 0 {
            eprintln!("  {}/{}", i + 1, labels.len());
        }
    }

    let mean =
        |f: fn(&Row) -> f64, rs: &[Row]| -> f64 { rs.iter().map(f).sum::<f64>() / rs.len() as f64 };
    let m_sq = mean(|r| r.cer_squeezed, &rows);
    let m_ti = mean(|r| r.cer_tiled, &rows);

    println!("\nn                {}", rows.len());
    println!("squeezed CER     {m_sq:.4}");
    println!("tiled CER        {m_ti:.4}");
    println!("ratio sq/tiled   {:.2}x", m_sq / m_ti);
    println!(
        "tiled better on  {}/{}",
        rows.iter().filter(|r| r.cer_tiled < r.cer_squeezed).count(),
        rows.len()
    );

    // The band table is the finding; the aggregate depends entirely on the width
    // mix of whatever sample was handed in.
    let mut bands: BTreeMap<usize, Vec<&Row>> = BTreeMap::new();
    for r in &rows {
        bands.entry(r.tiles).or_default().push(r);
    }
    println!("\n tiles     n   squeezed     tiled    ratio");
    for (band, sub) in &bands {
        if sub.len() < 3 {
            continue;
        }
        let s_m = sub.iter().map(|r| r.cer_squeezed).sum::<f64>() / sub.len() as f64;
        let t_m = sub.iter().map(|r| r.cer_tiled).sum::<f64>() / sub.len() as f64;
        println!(
            " {band:>5}  {:>4}   {s_m:>8.4}  {t_m:>8.4}  {:>6.1}x",
            sub.len(),
            s_m / t_m
        );
    }
    Ok(())
}

pub fn density_threshold_ratio(self, ratio: f32) -> Self

pub async fn build(self) -> Result<MonOcr>

Build the MonOcr instance

This method initializes the ONNX runtime session and prepares the OCR engine for use. It may download the model if not cached.

Returns

• Ok(MonOcr) - Ready-to-use OCR instance
• Err(anyhow::Error) - If model loading fails

Async

This function is async because model initialization may involve downloading the model file from the network.

Examples found in repository

examples/tiling_ab.rs (line 101)

async fn main() -> Result<()> {
    let dir: PathBuf = std::env::args()
        .nth(1)
        .context("usage: tiling_ab <dir with line_*.png and labels.txt>")?
        .into();

    let labels_path = dir.join("labels.txt");
    let labels_raw = std::fs::read_to_string(&labels_path)
        .with_context(|| format!("cannot read {}", labels_path.display()))?;

    let mut labels: Vec<(PathBuf, String)> = Vec::new();
    for line in labels_raw.lines() {
        let Some((name, text)) = line.split_once('\t') else {
            continue;
        };
        labels.push((dir.join(name), text.to_string()));
    }
    if labels.is_empty() {
        anyhow::bail!(
            "{} contained no tab-separated entries",
            labels_path.display()
        );
    }
    eprintln!("{} labelled lines", labels.len());

    // Null baseline, asserted before any real number is produced. If the metric
    // arithmetic is wrong every rate below is wrong in the same direction, and
    // nothing else in this example would reveal it.
    assert_eq!(
        char_cer("", "abc"),
        1.0,
        "empty prediction must score exactly 1.0"
    );
    assert_eq!(
        char_cer("abc", "abc"),
        0.0,
        "identity must score exactly 0.0"
    );
    eprintln!("null baseline ok");

    // Two sessions rather than rebuilding one per arm: the flag is fixed at build
    // time, and reloading the graph 240 times would dominate the runtime.
    let mut tiled = MonOcr::builder().tile_wide_lines(true).build().await?;
    let mut squeezed = MonOcr::builder().tile_wide_lines(false).build().await?;

    let mut rows: Vec<Row> = Vec::new();
    for (i, (path, truth)) in labels.iter().enumerate() {
        let t = tiled.predict_single_line(path).await?;
        let s = squeezed.predict_single_line(path).await?;

        // Recovered from the geometry: a tiled read reports the union of its
        // tiles, so width over the window width is the tile count.
        let img = image::open(path)?.to_luma8();
        let (w, h) = img.dimensions();
        let scaled = (w as f64 * (160.0 / h as f64)) as u32;
        let tiles = ((scaled as f64) / 1024.0).ceil().max(1.0) as usize;

        rows.push(Row {
            tiles,
            cer_tiled: char_cer(&t.text, truth),
            cer_squeezed: char_cer(&s.text, truth),
        });

        if (i + 1) % 25 == 0 {
            eprintln!("  {}/{}", i + 1, labels.len());
        }
    }

    let mean =
        |f: fn(&Row) -> f64, rs: &[Row]| -> f64 { rs.iter().map(f).sum::<f64>() / rs.len() as f64 };
    let m_sq = mean(|r| r.cer_squeezed, &rows);
    let m_ti = mean(|r| r.cer_tiled, &rows);

    println!("\nn                {}", rows.len());
    println!("squeezed CER     {m_sq:.4}");
    println!("tiled CER        {m_ti:.4}");
    println!("ratio sq/tiled   {:.2}x", m_sq / m_ti);
    println!(
        "tiled better on  {}/{}",
        rows.iter().filter(|r| r.cer_tiled < r.cer_squeezed).count(),
        rows.len()
    );

    // The band table is the finding; the aggregate depends entirely on the width
    // mix of whatever sample was handed in.
    let mut bands: BTreeMap<usize, Vec<&Row>> = BTreeMap::new();
    for r in &rows {
        bands.entry(r.tiles).or_default().push(r);
    }
    println!("\n tiles     n   squeezed     tiled    ratio");
    for (band, sub) in &bands {
        if sub.len() < 3 {
            continue;
        }
        let s_m = sub.iter().map(|r| r.cer_squeezed).sum::<f64>() / sub.len() as f64;
        let t_m = sub.iter().map(|r| r.cer_tiled).sum::<f64>() / sub.len() as f64;
        println!(
            " {band:>5}  {:>4}   {s_m:>8.4}  {t_m:>8.4}  {:>6.1}x",
            sub.len(),
            s_m / t_m
        );
    }
    Ok(())
}

Trait Implementations

impl Default for MonOcrBuilder

fn default() -> Self

Create a MonOcrBuilder with default settings

Default values:

• model_path: None (will download from HuggingFace)
• charset: None (uses the charset published with the pinned model, falling back to the built-in Mon charset)
• min_line_height: 10 pixels
• smooth_window: 3
• density_threshold_ratio: 0.05