dic2d.py

two_dimensional(reference, deformed, roi_mask, seed, subset_size=21, subset_step=10, correlation_criteria='ZNSSD', shape_function='AFFINE', interpolation_routine='BICUBIC', max_iterations=40, opt_precision=0.001, opt_threshold=0.9, bf_threshold=0.6, num_threads=None, max_displacement=128, scanning_method='RG', fft_mad=False, fft_mad_scale=3.0, output_at_end=False, output_basepath='./', output_binary=False, output_prefix='dic_results_', output_delimiter=',', output_unconverged=False, output_shape_params=False, debug_level=0)[source]

Perform 2D Digital Image Correlation (DIC) between a reference image and one or more deformed images.

This function wraps a C++ DIC engine by preparing configuration parameters, performing input validation, and dispatching image data and settings. It supports pixel-level displacement and strain measurement over a defined region of interest (ROI).

Parameters:

  • reference (np.ndarray, str or pathlib.Path) – The reference image (2D array) or path to the image file.

  • deformed (np.ndarray, str or pathlib.Path) – The deformed image(s) (3D array for multiple images) or path/pattern to image files.

  • roi_mask (np.ndarray) – A binary mask indicating the Region of Interest (ROI) for analysis (same size as image).

  • seed (list[int], list[np.int32] or np.ndarray) – Coordinates [x, y] of the seed point for Reliability-Guided (RG) scanning, default is empty.

  • subset_size (int, optional) – Size of the square subset window in pixels (default: 21).

  • subset_step (int, optional) – Step size between subset centers in pixels (default: 10).

  • correlation_criteria (str, optional) – Metric for matching subsets: “ZNSSD”, “NSSD” or “SSD” (default: “ZNSSD”).

  • shape_function (str, optional) – Deformation model: e.g., “AFFINE”, “RIGID” (default: “AFFINE”).

  • interpolation_routine (str, optional) – Interpolation method used on image intensity. “BICUBIC” is currently the only supported option.

  • max_iterations (int, optional) – Maximum number of iterations allowed for subset optimization (default: 40).

  • opt_precision (float, optional) – Precision threshold for iterative optimization convergence (default: 0.001).

  • opt_threshold (float, optional) – Minimum correlation improvement threshold to continue iterations (default: 0.9).

  • num_threads (int, optional) – Number of threads to use for parallel computation (default: None, uses all available).

  • bf_threshold (float, optional) – Correlation threshold used in rigid bruteforce check for a subset to be considered a good match(default: 0.6).

  • max_displacement (int, optional) – Estimate for the Maximum displacement in any direction (in pixels) (default: 128).

  • scanning_method (str, optional) – Subset scanning method: “RG” for Reliability-Guided (best overall approach), “IMAGE_SCAN” for a standard scan across the image with no seeding (best performance with for subpixel displacements with high quality images), “FFT” for a multi-window FFT based approach (Good for large displacements)

  • fft_mad (bool, optional) – The option to smooth FFT windowing data by identifying and replacing outliers using a robust statistical method. For each subset, the function collects values from its neighboring subsets (within a 5x5 window, i.e., radius = 2), computes the median and Median Absolute Deviation (MAD), and determines whether the value at the current subset is an outlier. If it is, the value is replaced with the median of its neighbors. (default: False)

  • fft_mad_scale (bool, optional) – An outlier is defined as a value whose deviation from the local median exceeds fft_mad_scale times the MAD. This value choses the scaling factor that determines the threshold for detecting outliers relative to the MAD.

  • output_at_end (bool, optional) – If True, results will only be written at the end of processing (default: False).

  • output_basepath (str or pathlib.Path, optional) – Directory path where output files will be written (default: “./”).

  • output_binary (bool, optional) – Whether to write output in binary format (default: False).

  • output_prefix (str, optional) – Prefix for all output files (default: “dic_results_”). results will be named with output_prefix + original filename. THe extension will be changed to “.csv” or “.dic2d” depending on whether outputting as a binary.

  • output_delimiter (str, optional) – Delimiter used in text output files (default: “,”).

  • output_unconverged (bool, optional) – If True, subset results as they were for the final iteration of the optimization that did not converge will be saved (default: False).

  • output_shape_params (bool, optional) – If True, all shape parameters will be saved in the output files (default: False).

  • debug_level

Returns:

None – All outputs are written to files; no values are returned.

Raises:

  • ValueError – If input checks fail (e.g., invalid image sizes, unsupported parameters).

  • FileNotFoundError – If provided file paths do not exist.