Function ecc_match

pub fn ecc_match<I, P>(
    files: I,
    params: EccMatchParameters,
    scale_down_width: Option<f32>,
) -> Result<Mat, StackerError>
where
    I: IntoIterator<Item = P>,
    P: AsRef<Path>,

Aligns and stacks images using OpenCV’s Enhanced Correlation Coefficient (ECC) algorithm.

Performs intensity-based image alignment using pyramidal ECC maximization, with optional scaling for performance. The first image serves as the reference frame for alignment.

Algorithm Overview

1. Converts images to grayscale for alignment computation
2. Optionally scales images down for faster ECC computation
3. Estimates transformation (translation/affine/homography) using ECC maximization
4. Applies transformation to original full-resolution images
5. Averages all aligned images

When to Use

• When images need alignment but lack distinctive features for keypoint matching
• For alignment under illumination changes (ECC is illumination-invariant)
• When precise subpixel alignment is required

Parameters

• files: Iterator of image paths (any AsRef<Path> type)
• params: ECC configuration parameters:
  • motion_type: Type of transformation to estimate:
    • Translation, Euclidean, Affine, or Homography
  • max_count: Maximum iterations (None for OpenCV default)
  • epsilon: Convergence threshold (None for OpenCV default)
  • gauss_filt_size: Gaussian filter size for pyramid levels (odd number ≥1)
• scale_down_width: Performance/accuracy trade-off:
  • Some(width): Process ECC at specified width (faster)
  • None: Process at full resolution (more precise)
  • Must be < original width when specified

Returns

• Ok(Mat): Stacked image in CV_32F format (normalized 0-1 range)
• Err(StackerError) on:
  • No input files
  • Invalid scale width
  • Image loading/processing failures

Performance Notes

• Parallel processing for multi-image alignment
• Scaling provides 3-5x speedup with minor accuracy impact
• Computation complexity depends on:
  • Motion type (Translation < Affine < Homography)
  • Image resolution
  • Convergence criteria

Example

// Fast homography alignment with scaling
let aligned = ecc_match(
    ["1.jpg", "2.jpg", "3.jpg"],
    EccMatchParameters {
        motion_type: MotionType::Homography,
        max_count: Some(5000),
        epsilon: Some(1e-6),
        gauss_filt_size: 3,
    },
    Some(800.0)  // Scale to 800px width
)?;

// Precise affine alignment (full resolution)
let precise = ecc_match(
    vec!["1.tif", "2.tif"],
    EccMatchParameters {
        motion_type: MotionType::Affine,
        max_count: Some(5000),
        epsilon: Some(1e-6),
        gauss_filt_size: 3,
    },
    None  // No scaling
)?;

References

• Image Alignment Tutorial

Examples found in repository

examples/main.rs (lines 105-114)

fn main() -> Result<(), StackerError> {
    use libstacker::opencv::core::Point;

    let v = vec![Point::new(1, 5), Point::new(2, 5), Point::new(3, 5)];
    let _ = v
        .into_iter()
        .collect::<libstacker::opencv::core::Vector<Point>>();

    let files = collect_image_files(&path::PathBuf::from("image_stacking_py/images"))?;
    let now = std::time::Instant::now();
    let mut files = files
        .into_par_iter()
        .map(move |f| -> Result<_, StackerError> {
            let img_gray = imgcodecs::imread(f.to_str().unwrap(), imgcodecs::IMREAD_GRAYSCALE)?;
            Ok((
                f,
                libstacker::sharpness_modified_laplacian(&img_gray)?, // LAPM = 1
                libstacker::sharpness_variance_of_laplacian(&img_gray)?, // LAPV = 2
                libstacker::sharpness_tenengrad(&img_gray, 3)?,       // TENG = 3
                libstacker::sharpness_normalized_gray_level_variance(&img_gray)?, // GLVN = 4
            ))
        })
        .collect::<Result<Vec<_>, StackerError>>()?;
    println!("Calculated sharpness() in {:?}", now.elapsed());

    // sort images by sharpness using TENG for now
    files.sort_by_key(|f| ordered_float::OrderedFloat(f.3));

    println!("Files ordered by TENG (low quality first)");
    for f in files.iter() {
        println!(
            "{:?} LAPM:{: >8.5} LAPV:{: >9.5} TENG:{: >8.5} GLVN:{: >9.5}",
            f.0, f.1, f.2, f.3, f.4
        );
    }
    // only keep the filename and skip the first file (the bad one) and reverse the order
    // keeping the best image first.
    let files: Vec<_> = files.into_iter().map(|f| f.0).skip(1).rev().collect();

    let now = std::time::Instant::now();
    let keypoint_match_img = keypoint_match(
        &files,
        libstacker::KeyPointMatchParameters {
            method: opencv::calib3d::RANSAC,
            ransac_reproj_threshold: 5.0,
            match_ratio: 0.9,
            match_keep_ratio: 0.80,
            border_mode: opencv::core::BORDER_CONSTANT,
            border_value: opencv::core::Scalar::default(),
        },
        None,
    )?;
    let keypoint_match_img_duration = now.elapsed();
    println!(
        "Calculated keypoint_match() in {:?} dropped frames:{}",
        keypoint_match_img_duration, keypoint_match_img.0
    );

    let now = std::time::Instant::now();
    let keypoint_match_img_400 = keypoint_match(
        &files,
        libstacker::KeyPointMatchParameters {
            method: opencv::calib3d::RANSAC,
            ransac_reproj_threshold: 5.0,
            match_ratio: 0.9,
            match_keep_ratio: 0.80,
            border_mode: opencv::core::BORDER_CONSTANT,
            border_value: opencv::core::Scalar::default(),
        },
        Some(400.0),
    )?;
    let keypoint_match_400_img_duration = now.elapsed();
    println!(
        "Calculated keypoint_match(width=400) in {:?} dropped frames:{}",
        keypoint_match_400_img_duration, keypoint_match_img_400.0
    );

    let now = std::time::Instant::now();
    let ecc_match_img = libstacker::ecc_match(
        &files,
        libstacker::EccMatchParameters {
            motion_type: libstacker::MotionType::Homography,
            max_count: Some(5000),
            epsilon: Some(1e-5),
            gauss_filt_size: 5,
        },
        None,
    )?;
    let ecc_match_img_duration = now.elapsed();
    println!("Calculated ecc_match() in {:?}", ecc_match_img_duration);

    let now = std::time::Instant::now();
    let ecc_match_img_400 = libstacker::ecc_match(
        files,
        libstacker::EccMatchParameters {
            motion_type: libstacker::MotionType::Homography,
            max_count: Some(5000),
            epsilon: Some(1e-5),
            gauss_filt_size: 5,
        },
        Some(400.0),
    )?;
    let ecc_match_400_img_duration = now.elapsed();
    println!(
        "Calculated ecc_match(width=400) in {:?}",
        ecc_match_400_img_duration
    );

    while highgui::wait_key(33)? != 27 {
        highgui::imshow(
            format!(
                "KeyPoint match (full resolution) [{:?}]",
                keypoint_match_img_duration
            )
            .as_str(),
            &keypoint_match_img.1,
        )?;
        highgui::imshow(
            format!("ECC match (full resolution) [{:?}]", ecc_match_img_duration).as_str(),
            &ecc_match_img,
        )?;
        highgui::imshow(
            format!(
                "KeyPoint match (width 400) [{:?}]",
                keypoint_match_400_img_duration
            )
            .as_str(),
            &keypoint_match_img_400.1,
        )?;
        highgui::imshow(
            format!("ECC match (width 400) [{:?}]", ecc_match_400_img_duration).as_str(),
            &ecc_match_img_400,
        )?;
    }
    Ok(())
}