pyvale.dic.dic3d module

calculate_3d(reference, deformed, roi_mask, calibration, seed, subset_size=21, subset_step=10, correlation_criteria=ECorrCrit.ZNSSD, shape_function=EShape.AFFINE, interpolation_routine=EInterp.BSPLINE, max_iterations=40, precision=0.001, threshold=0.9, num_threads=None, max_displacement=128, epi_distance=300, method=EScanMethod.MULTIWINDOW_RG, incremental_update=EIncrementalMethod.OFF, incremental_update_value=1, multiwindow_overlap=0.0, multiwindow_subset_sizes=[], multiwindow_search_areas=[], fft_filter=True, fft_filter_threshold=3.0, fft_filter_radius=3, fft_filter_corr_power=2.0, fft_save=False, fft_precision='F32', output_basepath='./', output_binary=False, output_prefix='dic_results_', output_delimiter=',', output_below_threshold=False, output_shape_params=False, print_level=2)[source]

Perform Stereo 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 , pathlib.Path or list[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], list[tuple[int, int]] or np.ndarray) – Coordinates of the seed points for Reliability-Guided (RG) scanning. Accepts either the existing flat format [x0, y0, x1, y1, ...] or tuple format [(x0, y0), (x1, y1), ...]. If the method is not RG, this will be ignored.

  • 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. Options are "BSPLINE" and "HERMITE". Implementation details can be found in our DIC theory documentation. (default: “BSPLINE”).

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

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

  • threshold (float, optional) – Minimum correlation/cost coefficient value to be considered a matching subset (default: 0.9).

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

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

  • epi_distance (int, optional) – Estimate for the maximum distance along the epipolar line (in pixels) between a identical point in the left and right image (default: 300).

  • method (str, optional) –

    The core algorithmic method used to perform the DIC.

    Options include:

    • "MULTIWINDOW_RG": Multi-window Reliability-Guided DIC (best overall approach).

    • "SINGLEWINDOW_RG": Uses a single window for the rigid estimate for each subset. The size of the window is determined by the max_displacement parameter.

    • "MULTIWINDOW": Uses only the multi-window FFT strategy.

    • "RASTER": No FFT initialization. Performs a raster scan of the image.

  • incremental_update (str or EIncrementalMethod, optional) – Condition for updating reference images. Use "OFF" to disable incremental reference updates. Options include: "IMAGE" to update every N images, "COST" to update when the average ZNCC cost value falls below a threshold, "ITER" to update when the average number of subset optimizer iterations exceeds a threshold. (default: "OFF").

  • incremental_update_value (float, optional) – Value corresponding to incremental_update. For example, if the condition is “IMAGE”, this would be the number of images after which to update the reference. If the condition is "COST", this would be the cost threshold for updating. If the condition is "ITER", this would be the iteration threshold for updating. (default: 1).

  • multiwindow_overlap (int, optional) – For multi-window methods, the percentage overlap between adjacent FFT windows at each level (default: 50).

  • multiwindow_template (list[int], optional) – List of template window sizes for the multi-window FFT approach. If None, defaults to powers of 2 with the largest window size determined by the next power of 2 above max_displacement (default: None).

  • multiwindow_search (list[int], optional) – List of search window sizes for the multi-window FFT approach. If None, defaults to the corresponding template window size (default: None).

  • fft_filter (bool, optional) – Enables outlier filtering for rigid FFT displacement estimates at each FFTCC window size. (default: False)

  • fft_filter_threshold (float, optional) – Rejection threshold for the FFT displacement outlier filter. Larger values are more tolerant, while smaller values reject more vectors. (default: 3.0)

  • fft_filter_radius (int, optional) – Neighbourhood radius, in subset-grid steps, used by the FFT displacement outlier filter. (default: 3)

  • fft_filter_corr_power (float, optional) – Exponent applied to correlation confidence when weighting neighbours in the FFT displacement outlier filter. (default: 2.0)

  • fft_precision (str, optional) – Floating-point precision for FFT-only windowing buffers. Options are "F32" for single precision and "F64" for double precision. (default: "F32").

  • 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_below_threshold (bool, optional) – If True, subset results with cost values that did not exceed the cost threshold will still be present in output (default: False).

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

  • print_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.