dicchecks.py

check_output_directory(output_basepath, output_prefix)

Check for existing output files in a directory and prompt user confirmation before overwriting.

This function verifies whether the specified output directory exists and checks for any existing files that match a given prefix and have .csv or .dic2d extensions. If such files are found, a list is displayed and the user is prompted to confirm whether to continue. If the user declines, the program exits to prevent data loss.

Parameters:

• output_basepath (str) – Path to the output directory where files are or will be saved.

• output_prefix (str) – Filename prefix used to identify potential conflicting output files.

Raises:

SystemExit – If the output directory does not exist or the user chooses not to proceed after being warned about existing files.

check_correlation_criteria(correlation_criteria)

Validate that the correlation criteria is one of the allowed values.

Checks whether input correlation_criteria is among the accepted options: “SSD”, “NSSD”, or “ZNSSD”. If not, raises a ValueError.

Parameters:

correlation_criteria (str) – The correlation type. Must be one of: “SSD”, “NSSD”, or “ZNSSD”.

Raises:

ValueError – If correlation_criteria is not one of the allowed values.

check_shape_function(shape_function)

Checks whether input shape_function is one of the allowed values (“RIGID” or “AFFINE”). If valid, it returns the number of transformation parameters associated with that shape function.

Parameters:

shape_function (str) – The shape function type. Must be either “RIGID” or “AFFINE”.

Returns:

int – The number of parameters for the specified shape function: - 2 for “RIGID” - 6 for “AFFINE”

Raises:

ValueError – If shape_function is not one of the allowed values.

check_interpolation(interpolation_routine)

Validate that the interpolation routine is one of the allowed methods.

Checks whether interpolation_routine is a supported interpolation method. Allowed values are “BILINEAR” and “BICUBIC”. If the input is not one of these, a ValueError is raised.

Parameters:

interpolation_routine (str) – The interpolation method to validate. Must be either “BILINEAR” or “BICUBIC”.

Raises:

ValueError – If interpolation_routine is not a supported value.

check_scanning_method(scanning_method)

Validate that the scan type one of the allowed methods.

Allowed values are “RG”, “IMAGE_SCAN”, “FFT”, “IMAGE_SCAN_WITH_BF”, “FFT_test”. If scanning_method is not one of these, a ValueError is raised.

Parameters:

interpolation_routine (str) – The interpolation method to validate. Must be either “BILINEAR” or “BICUBIC”.

Raises:

ValueError – If interpolation_routine is not a supported value.

check_thresholds(opt_threshold, bf_threshold, opt_precision)

Ensures that opt_threshold, bf_threshold, and opt_precision are all floats strictly between 0 and 1. Raises a ValueError if any condition fails.

Parameters:

• opt_threshold (float) – Threshold for the Levenberg optimization method.

• bf_threshold (float) – Threshold for the brute-force optimization method.

• opt_precision (float) – Desired precision for the optimizer.

Raises:

ValueError – If any input value is not a float strictly between 0 and 1.

check_subsets(subset_size, subset_step)

Parameters:

• subset_size (int) – Threshold for the Levenberg optimization method.

• subset_step (int) – Threshold for the brute-force optimization method.

Raises:

ValueError – If any input value is not a float strictly between 0 and 1.

check_and_update_rg_seed(seed, roi_mask, scanning_method, px_hori, px_vert, subset_size, subset_step)

Validate and update the region-growing seed location to align with image bounds and subset spacing.

This function checks the format and bounds of the seed coordinates used for a region-growing (RG) scanning method. It adjusts the seed to the nearest valid grid point based on the subset step size, clamps it to the image dimensions, and ensures it lies within the region of interest (ROI) mask.

If the scanning method is not “RG”, the function returns a default seed of [0, 0]. This seed is not used any other scan method methods.

Parameters:

• seed (list[int], list[np.int32] or np.ndarray) – The initial seed coordinates as a list of two integers: [x, y].

• roi_mask (np.ndarray) – A 2D binary mask (same size as the image) indicating the region of interest.

• scanning_method (str) – The scanning method to be used. Only “RG” triggers validation and adjustment logic.

• px_hori (int) – Width of the image in pixels.

• px_vert (int) – Height of the image in pixels.

• subset_step (int) – Step size used for subset spacing; seed is aligned to this grid.

Returns:

list of int – The adjusted seed coordinates [x, y] aligned to the subset grid and within bounds.

Raises:

ValueError – If the seed is improperly formatted, out of image bounds, or not a list of two integers.

check_and_get_images(reference, deformed, roi)

Load and validate reference and deformed images, checks consistency in shape/format.

This function accepts either: - A file path to a reference image and a glob pattern for a sequence of deformed image files, or - Numpy arrays for both reference and deformed images.

It ensures: - The reference and deformed images are the same type (both paths or both arrays). - The reference image exists and is readable (if passed as a path). - All deformed images exist and match the reference image shape. - If images are RGB or multi-channel, only the first channel is used. - The roi (region of interest) has the same shape as the reference image (when arrays are used directly).

Parameters:

• reference (np.ndarray, str, pathlib.Path) – Either a NumPy array representing the reference image, or a file path to a reference image.

• deformed (np.ndarray, str, pathlib.Path) – Either a NumPy array representing a sequence of deformed images (shape: [N, H, W]), or a glob pattern string pointing to multiple image files.

• roi (np.ndarray) – A 2D NumPy array defining the region of interest. Must match the reference image shape if reference is an array.

Returns:

• ref_arr (np.ndarray) – The reference image as a 2D NumPy array.

• def_arr (np.ndarray) – A 3D NumPy array containing all deformed images with shape (N, H, W).

• filenames (list of str) – List of base filenames of deformed images (empty if deformed images were passed as arrays).

Raises:

• ValueError – If there is a type mismatch between reference and deformed, if image files are not found or unreadable, or if image shapes do not match.

• FileNotFoundError – If no files are found matching the deformed image pattern.

check_strain_files(strain_files)

print_title(a)