corrmatch 0.1.0

CPU-first template matching with ZNCC/SSD and coarse-to-fine pyramid search
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

//! CorrMatch is a CPU-first template matching library for grayscale images.
//!
//! It provides a coarse-to-fine matcher with optional rotation search and
//! two metrics: ZNCC and SSD. The primary entry points are `Template`,
//! `CompiledTemplate`, and `Matcher`.
//!
//! # Quick start
//! ```no_run
//! use corrmatch::{
//!     CompileConfig, MatchConfig, Matcher, RotationMode, Template, ImageView,
//! };
//!
//! # fn run(image: &[u8], width: usize, height: usize, tpl: Vec<u8>, tw: usize, th: usize)
//! #     -> corrmatch::CorrMatchResult<corrmatch::Match> {
//! let template = Template::new(tpl, tw, th)?;
//! let compiled = template.compile(CompileConfig::default())?;
//! let matcher = Matcher::new(compiled).with_config(MatchConfig {
//!     rotation: RotationMode::Enabled,
//!     ..MatchConfig::default()
//! });
//! let image_view = ImageView::from_slice(image, width, height)?;
//! matcher.match_image(image_view)
//! # }
//! ```
//!
//! # Concepts
//! - `Template`: owned template pixels.
//! - `CompiledTemplate`: precomputed template pyramid and (optionally) angle banks.
//! - `Matcher`: runs the coarse-to-fine search and returns the best match.
//! - `CompiledTemplate::compile_unrotated`: lightweight assets for translation-only matching.
//!
//! # Data model
//! - Images and templates are grayscale `u8` buffers in row-major order.
//! - `ImageView` supports explicit row stride; results report top-left coordinates at level 0.
//! - Scores: ZNCC in roughly `[-1, 1]`, SSD reported as negative SSE (higher is better).
//!
//! # Determinism
//! Matching is deterministic; enabling `rayon` via `MatchConfig.parallel` keeps results stable.
//!
//! # Feature flags
//! - `rayon`: parallel search execution.
//! - `simd`: SIMD-accelerated kernels (currently: unmasked translation-only path).
//! - `image-io`: file I/O helpers via the `image` crate.
//!
//! # Low-level API
//! Advanced building blocks are available under `corrmatch::lowlevel`.
//!
//! # CLI
//! A JSON-driven CLI lives in the `corrmatch-cli` workspace crate.

// Macros must be defined before modules that use them
#[macro_use]
mod trace;

mod bank;
mod candidate;
mod image;
mod kernel;
pub mod lowlevel;
mod refine;
mod search;
mod template;
mod util;

pub use bank::{CompileConfig, CompileConfigNoRot, CompiledTemplate};
pub use image::pyramid::ImagePyramid;
pub use image::{ImageView, OwnedImage};
pub use template::Template;
pub use util::{CorrMatchError, CorrMatchResult};

pub use search::{Match, MatchConfig, Matcher, Metric, RotationMode};

/// Image I/O helpers available when the `image-io` feature is enabled.
#[cfg(feature = "image-io")]
pub mod io {
    pub use crate::image::io::{
        load_gray_image, owned_from_dynamic_image, owned_from_gray_image, view_from_gray_image,
    };
}