pyvale 2025.7.1__cp311-cp311-win_amd64.whl → 2025.8.1__cp311-cp311-win_amd64.whl

pyvale/{dic2d.py → dic/dic2d.py}

@@ -9,33 +9,38 @@
 import numpy as np
 from pathlib import Path
 
-# import cython module
-import pyvale.dic2dcpp as dic2dcpp
-import pyvale.dicchecks as dicchecks
-
-
-def dic_2d(reference: np.ndarray | str | Path,
-          deformed: np.ndarray | str | Path,
-          roi_mask: np.ndarray,
-          seed: list[int],
-          subset_size: int = 21,
-          subset_step: int = 10,
-          correlation_criteria: str="ZNSSD",
-          shape_function: str="AFFINE",
-          interpolation_routine: str="BICUBIC",
-          max_iterations: int=40,
-          opt_precision: float=0.001,
-          opt_threshold: float=0.9,
-          bf_threshold: float=0.6,
-          max_displacement: int=128,
-          scanning_method: str="RG",
-          fft_mad: bool=False,
-          fft_mad_scale: float=3.0,
-          output_at_end: bool=False,
-          output_basepath: Path | str = "./",
-          output_binary: bool=False,
-          output_prefix: str="dic_results_",
-          output_delimiter: str=",") -> None:
+# pyvale
+import pyvale.dic.dic2dcpp as dic2dcpp
+import pyvale.dic.dicchecks as dicchecks
+
+
+def two_dimensional(reference: np.ndarray | str | Path,
+                    deformed: np.ndarray | str | Path,
+                    roi_mask: np.ndarray,
+                    seed: list[int] | list[np.int32] | np.ndarray,
+                    subset_size: int = 21,
+                    subset_step: int = 10,
+                    correlation_criteria: str="ZNSSD",
+                    shape_function: str="AFFINE",
+                    interpolation_routine: str="BICUBIC",
+                    max_iterations: int=40,
+                    opt_precision: float=0.001,
+                    opt_threshold: float=0.9,
+                    bf_threshold: float=0.6,
+                    num_threads: int | None = None,
+                    max_displacement: int=128,
+                    scanning_method: str="RG",
+                    fft_mad: bool=False,
+                    fft_mad_scale: float=3.0,
+                    output_at_end: bool=False,
+                    output_basepath: Path | str = "./",
+                    output_binary: bool=False,
+                    output_prefix: str="dic_results_",
+                    output_delimiter: str=",",
+                    output_unconverged: bool=False,
+                    output_shape_params: bool=False,
+                    debug_level: int=0) -> None:
+
     """
     Perform 2D Digital Image Correlation (DIC) between a reference image and one or more deformed images.
 
@@ -51,7 +56,7 @@ def dic_2d(reference: np.ndarray | str | 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 of int, optional
+    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).
@@ -70,6 +75,8 @@ def dic_2d(reference: np.ndarray | str | Path,
         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).
@@ -103,6 +110,12 @@ def dic_2d(reference: np.ndarray | str | Path,
         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
     -------
@@ -151,6 +164,7 @@ def dic_2d(reference: np.ndarray | str | Path,
     config.filenames = filenames
     config.fft_mad = fft_mad
     config.fft_mad_scale = fft_mad_scale
+    config.debug_level = debug_level
 
     # assigning c++ struct vals for save config
     saveconf = dic2dcpp.SaveConfig()
@@ -159,6 +173,14 @@ def dic_2d(reference: np.ndarray | str | Path,
     saveconf.prefix = output_prefix
     saveconf.delimiter = output_delimiter
     saveconf.at_end = output_at_end
+    saveconf.output_unconverged = output_unconverged
+    saveconf.shape_params = output_shape_params
+
+
+    #set the number of OMP threads
+    if num_threads is not None:
+        dic2dcpp.set_num_threads(num_threads)
 
     # calling the c++ dic engine
-    dic2dcpp.dic_engine(ref_arr, def_arr, roi_c, config, saveconf)
+    with dic2dcpp.ostream_redirect(stdout=True, stderr=True):
+        dic2dcpp.dic_engine(ref_arr, def_arr, roi_c, config, saveconf)

pyvale/dic/dic2dconv.py

@@ -0,0 +1,6 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+

pyvale/{dicchecks.py → dic/dicchecks.py}

@@ -55,16 +55,18 @@ def check_output_directory(output_basepath: str,
 
     if conflicting_files:
         conflicting_files.sort()
-        print("The following output files already exist and may be overwritten:")
+        print("WARNING: The following output files already exist and may be overwritten:")
         for f in conflicting_files:
             print(f"  - {os.path.join(output_basepath, f)}")
         print("")
 
-        user_input = input("Do you want to continue? (y/n): ").strip().lower()
 
-        if user_input not in ("y", "yes", "Y", "YES"):
-            print("Aborting to avoid overwriting data in output directory.")
-            exit(0)
+        ###### TURNING USER INPUT OFF FOR NOW ######
+        # user_input = input("Do you want to continue? (y/n): ").strip().lower()
+
+        # if user_input not in ("y", "yes", "Y", "YES"):
+        #     print("Aborting to avoid overwriting data in output directory.")
+        #     exit(0)
 
 
 def check_correlation_criteria(correlation_criteria: str) -> None:
@@ -247,7 +249,7 @@ def check_subsets(subset_size: int, subset_step: int) -> None:
 
 
 
-def check_and_update_rg_seed(seed: list[int], roi_mask: np.ndarray, scanning_method: str, px_hori: int, px_vert: int, subset_size: int, subset_step: int) -> list[int]:
+def check_and_update_rg_seed(seed: list[int] | list[np.int32] | np.ndarray, roi_mask: np.ndarray, scanning_method: str, px_hori: int, px_vert: int, subset_size: int, subset_step: int) -> list[int]:
     """
     Validate and update the region-growing seed location to align with image bounds and subset spacing.
 
@@ -260,7 +262,7 @@ def check_and_update_rg_seed(seed: list[int], roi_mask: np.ndarray, scanning_met
 
     Parameters
     ----------
-    seed : list of int
+    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.
@@ -287,11 +289,19 @@ def check_and_update_rg_seed(seed: list[int], roi_mask: np.ndarray, scanning_met
     if scanning_method != "RG":
         return [0,0]
 
-    if not (isinstance(seed, list) and len(seed) == 2 and all(isinstance(coord, int) for coord in seed)):
-        raise ValueError("Reliability Guided seed is either missing or has been defined incorrectly. must be a list of two integers: seed=[x, y]")
+    if (len(seed) != 2):
+        raise ValueError(f"Reliability Guided seed does not have two elements: " \
+                         f"seed={seed}. Seed " \
+                         f" must be a list of two integers: seed=[x, y]")
+
+    if not isinstance(seed, (list, np.ndarray)) or not all(isinstance(coord, (int, np.int32)) for coord in seed):
+        raise ValueError("Reliability Guided seed must be a list of two integers: seed=[x, y]")
 
     x, y = seed
 
+    if x < 0 or x >= px_hori or y < 0 or y >= px_vert:
+        raise ValueError(f"Seed ({x}, {y}) goes outside the image bounds: ({px_hori}, {px_vert})")
+
     corner_x = x - subset_size//2
     corner_y = y - subset_size//2
 
@@ -302,17 +312,11 @@ def check_and_update_rg_seed(seed: list[int], roi_mask: np.ndarray, scanning_met
     new_x = round_to_step(corner_x, subset_step)
     new_y = round_to_step(corner_y, subset_step)
 
-
-    # Clamp to image bounds
-    new_x = min(max(new_x, 0), px_hori - 1)
-    new_y = min(max(new_y, 0), px_vert - 1)
-
     # check if all pixel values within the seed location are within the ROI
     # seed coordinates are the central pixel to the subset
     max_x = new_x + subset_size//2+1
     max_y = new_y + subset_size//2+1
 
-
     # Check if all pixel values in the ROI are valid
     for i in range(corner_x, max_x):
         for j in range(corner_y, max_y):
@@ -435,9 +439,17 @@ def check_and_get_images(reference: np.ndarray | str | Path,
         ref_arr = reference
         def_arr = deformed
 
-        if (reference.shape != deformed[0].shape or reference.shape != roi.shape):
+        # user might only pass a single deformed image. need to convert to 'stack'
+        if (reference.shape == deformed.shape):
+            def_arr = def_arr.reshape((1,def_arr.shape[0],def_arr.shape[1]))
+
+        elif (reference.shape != deformed[0].shape or reference.shape != roi.shape):
             raise ValueError(f"Shape mismatch: reference {reference.shape}, "
                              f"deformed[0] {deformed[0].shape}, roi {roi.shape}")
+        
+
+        # need to set some dummy filenames in the case that the user passes numpy arrays
+        filenames = [f"deformed image {i}" for i in range(def_arr.shape[0])]
     
     # it might be the case that the roi has been manipulated prior to DIC run
     # and therefore we need to to prevent the roi mask from being a 'view'

pyvale/dic/dicdataimport.py

@@ -0,0 +1,370 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
+
+
+import numpy as np
+import glob
+import os
+from pathlib import Path
+
+# Pyvale modules
+from pyvale.dic.dicresults import Results
+
+"""
+Module responsible for handling importing of DIC results from completed
+calculations.
+"""
+
+
+def data_import(data: str | Path,
+                   binary: bool = False,
+                   layout: str = "matrix",
+                   delimiter: str = ",") -> Results:
+    """
+    Import DIC result data from human readable text or binary files.
+
+    Parameters
+    ----------
+
+    data : str or pathlib.Path
+        Path pattern to the data files (can include wildcards). Default is "./".
+
+    layout : str, optional
+        Format of the output data layout: "column" (flat array per frame) or "matrix" 
+        (reshaped grid per frame). Default is "column".
+
+    binary : bool, optional
+        If True, expects files in a specific binary format. If False, expects text data. 
+        Default is False.
+
+    delimiter : str, optional
+        Delimiter used in text data files. Ignored if binary=True. Default is a single space.
+
+    Returns
+    -------
+    Results
+        A named container with the following fields:
+            - ss_x, ss_y (grid arrays if layout=="matrix"; otherwise, 1D integer arrays)
+            - u, v, m, converged, cost, ftol, xtol, niter (arrays with shape depending on layout)
+            - filenames (python list)
+
+    Raises
+    ------
+    ValueError:
+        If `layout` is not "column" or "matrix", or text data has insufficient columns,
+        or binary rows are malformed.
+        import cython module
+    FileNotFoundError:
+        If no matching data files are found.
+    """
+
+
+    print("")
+    print("Attempting DIC Data import...")
+    print("")
+
+    # convert to str 
+    if isinstance(data, Path):
+        data = str(data)
+
+    files = sorted(glob.glob(data))
+    filenames = files
+    if not files:
+        raise FileNotFoundError(f"No results found in: {data}")
+
+    print(f"Found {len(files)} files containing DIC results:")
+    for file in files:
+        print(f"  - {file}")
+    print("")
+
+
+    # Read first file to define reference coordinates
+    read_data = read_binary if binary else read_text
+    ss_x_ref, ss_y_ref, *fields = read_data(files[0], delimiter=delimiter)
+    frames = [list(fields)]
+
+    for file in files[1:]:
+        ss_x, ss_y, *f = read_data(file, delimiter)
+        if not (np.array_equal(ss_x_ref, ss_x) and np.array_equal(ss_y_ref, ss_y)):
+            raise ValueError("Mismatch in coordinates across frames.")
+        frames.append(f)
+
+    # Stack results (except ss_x and ss_y) into arrays
+    arrays = [np.stack([frame[i] for frame in frames]) for i in range(len(fields))]
+
+    if layout == "matrix":
+
+        # convert x and y data to meshgrid
+        x_unique = np.unique(ss_x_ref)
+        y_unique = np.unique(ss_y_ref)
+        X, Y = np.meshgrid(x_unique, y_unique)
+        shape = (len(files), len(y_unique), len(x_unique))
+
+
+        arrays = [to_grid(a,shape,ss_x_ref, ss_y_ref, x_unique,y_unique) for a in arrays]
+
+
+        # sorting out shape function parameters if they are present in the files
+        current_shape = arrays[0].shape  # (file,x,y)
+        shape_params = np.zeros(())
+
+        # rigid
+        if len(fields) == 10:
+            shape_params = np.zeros(current_shape+(2,))
+            shape_params[:,:,:,0] = arrays[8]
+            shape_params[:,:,:,1] = arrays[9]
+        if len(fields) == 14:
+            shape_params = np.zeros(current_shape+(6,))
+            shape_params[:,:,:,0] = arrays[8]
+            shape_params[:,:,:,1] = arrays[9]
+            shape_params[:,:,:,2] = arrays[10]
+            shape_params[:,:,:,3] = arrays[11]
+            shape_params[:,:,:,4] = arrays[12]
+            shape_params[:,:,:,5] = arrays[13]
+
+
+
+
+        return Results(X, Y, arrays[0], arrays[1], arrays[2], arrays[3],
+                          arrays[4], arrays[5], arrays[6], arrays[7], 
+                          shape_params, filenames)
+    # column layout
+    else:
+
+        shape_params = np.zeros(())
+        current_shape = arrays[0].shape # (file,(x,y))
+        # rigid
+        if len(fields) == 10:
+            shape_params = np.zeros(current_shape+(2,))
+            shape_params[:,:,0] = arrays[8]
+            shape_params[:,:,1] = arrays[9]
+        if len(fields) == 14:
+            shape_params = np.zeros(current_shape+(6,))
+            shape_params[:,:,0] = arrays[8]
+            shape_params[:,:,1] = arrays[9]
+            shape_params[:,:,2] = arrays[10]
+            shape_params[:,:,3] = arrays[11]
+            shape_params[:,:,4] = arrays[12]
+            shape_params[:,:,5] = arrays[13]
+
+        return Results(ss_x_ref, ss_y_ref, arrays[0], arrays[1], arrays[2], arrays[3],
+                          arrays[4], arrays[5], arrays[6], arrays[7], 
+                          shape_params, filenames)
+
+
+
+
+
+def read_binary(file: str, delimiter: str):
+    """
+    Read a binary DIC result file and extract DIC fields.
+
+    Assumes a fixed binary structure with each row containing:
+    - 2 × int32 (subset coordinates)
+    - 6 × float64 (u, v, match quality, cost, ftol, xtol)
+    - 1 × int32 (number of iterations)
+    - 1 × uint8 (convergence flag) 
+    - 2 or 6 × float64 (shape parameters)
+
+    Parameters
+    ----------
+    file : str
+        Path to the binary result file.
+
+    delimiter : str
+        Ignored for binary data (included for API consistency).
+
+    Returns
+    -------
+    tuple of np.ndarray
+        Arrays corresponding to:
+        (ss_x, ss_y, u, v, m, cost, ftol, xtol, niter)
+
+    Raises
+    ------
+    ValueError
+        If the binary file size does not align with expected row size.
+    """
+    
+    # row size can either be 3×4 + 6×8 + 1 = 61 bytes (without shape params)
+    # or 3×4 + 6×8 + 1 + 6×8 = 109 bytes (with shape params)
+    with open(file, "rb") as f:
+        raw = f.read()
+
+    has_shape_params = False
+    has_rigid_params = False
+    has_affine_params = False
+
+    row_size_basic = 3 * 4 + 6 * 8 + 1           # 61 bytes
+    row_size_with_rigid = row_size_basic + 2 * 8 # 77 bytes
+    row_size_with_affine = row_size_basic + 6 * 8 # 109 bytes
+
+    if len(raw) % row_size_basic == 0:
+        row_size = row_size_basic
+        has_shape_params = False
+    elif len(raw) % row_size_with_rigid == 0:
+        has_shape_params = True
+        row_size = row_size_with_rigid
+        has_rigid_params = True
+        has_affine_params = False
+    elif len(raw) % row_size_with_affine == 0:
+        has_shape_params = True
+        row_size = row_size_with_affine
+        has_affine_params = True
+        has_rigid_params = False
+    else:
+        raise ValueError(
+            f"Binary file has incomplete rows: {file}. "
+            f"Expected row size: 65 ((without shape params), "
+            f"81 (with rigid shape params) bytes, "
+            f"109 (with affine shape params). "
+            f"Actual size: {len(raw)} bytes."
+        )
+
+    rows = len(raw) // row_size
+    arr = np.frombuffer(raw, dtype=np.uint8).reshape(rows, row_size)
+
+    def extract(col, dtype, start):
+        return np.frombuffer(arr[:, start:start+col].copy(), dtype=dtype)
+
+    ss_x  = extract(4, np.int32, 0)
+    ss_y  = extract(4, np.int32, 4)
+    u     = extract(8, np.float64, 8)
+    v     = extract(8, np.float64, 16)
+    m     = extract(8, np.float64, 24)
+    conv  = extract(1, np.uint8, 32).astype(bool)
+    cost  = extract(8, np.float64, 33)
+    ftol  = extract(8, np.float64, 41)
+    xtol  = extract(8, np.float64, 49)
+    niter = extract(4, np.int32, 57)
+
+    if has_shape_params:
+        if has_rigid_params:
+            p0 = extract(8, np.float64, 61)
+            p1 = extract(8, np.float64, 69)
+            return ss_x, ss_y, u, v, m, conv, cost, ftol, xtol, niter, p0,p1
+        if has_affine_params:
+            p0 = extract(8, np.float64, 61)
+            p1 = extract(8, np.float64, 69)
+            p2 = extract(8, np.float64, 77)
+            p3 = extract(8, np.float64, 85)
+            p4 = extract(8, np.float64, 93)
+            p5 = extract(8, np.float64, 101)
+            return ss_x, ss_y, u, v, m, conv, cost, ftol, xtol, niter, p0,p1,p2,p3,p4,p5
+    else:
+        return ss_x, ss_y, u, v, m, conv, cost, ftol, xtol, niter
+
+
+
+
+def read_text(file: str, delimiter: str):
+    """
+    Read a human-readable text DIC result file and extract DIC fields.
+
+    Expects at least 9 columns:
+    [ss_x, ss_y, u, v, m, conv, cost, ftol, xtol, niter]
+    Could also include shape parameters if present.
+
+    Parameters
+    ----------
+    file : str
+        Path to the text result file.
+
+    delimiter : str
+        Delimiter used in the text file (e.g., space, tab, comma).
+
+    Returns
+    -------
+    tuple of np.ndarray
+        Arrays corresponding to:
+        (ss_x, ss_y, u, v, m, conv, cost, ftol, xtol, niter, shape_params)
+
+    Raises
+    ------
+    ValueError
+        If the text file has fewer than 9 columns.
+    """
+
+    data = np.loadtxt(file, delimiter=delimiter, skiprows=1)
+    
+    if data.shape[1] < 9:
+        raise ValueError("Text data must have at least 9 columns.")
+    
+    if data.shape[1] == 10:
+        return (
+            data[:, 0].astype(np.int32),  # ss_x
+            data[:, 1].astype(np.int32),  # ss_y
+            data[:, 2], data[:, 3], data[:, 4], # u, v, mag
+            data[:, 5].astype(np.bool_), # convergence
+            data[:, 6], data[:, 7], data[:,8], # cost, ftol, xtol
+            data[:, 9].astype(np.int32) #niter
+        )
+    #rigid
+    elif data.shape[1]==12:
+        return (
+            data[:, 0].astype(np.int32),  # ss_x
+            data[:, 1].astype(np.int32),  # ss_y
+            data[:, 2], data[:, 3], data[:, 4], # u, v, mag
+            data[:, 5].astype(np.bool_), # convergence
+            data[:, 6], data[:, 7], data[:,8], # cost, ftol, xtol
+            data[:, 9].astype(np.int32), #niter
+            data[:,10], data[:,11] # shape params (rigid)
+        )
+    #affine
+    elif data.shape[1]==16:
+        return (
+            data[:, 0].astype(np.int32),  # ss_x
+            data[:, 1].astype(np.int32),  # ss_y
+            data[:, 2], data[:, 3], data[:, 4], # u, v, mag
+            data[:, 5].astype(np.bool_), # convergence
+            data[:, 6], data[:, 7], data[:,8], # cost, ftol, xtol
+            data[:, 9].astype(np.int32), #niter
+            data[:,10], data[:,11], data[:,12], data[:,13], data[:,14], data[:,15] # shape params (affine)
+        )
+
+
+
+def to_grid(data, shape, ss_x_ref, ss_y_ref, x_unique, y_unique):
+    """
+    Reshape a 2D DIC field from flat (column) format into grid (matrix) format.
+
+    This is used when output layout is specified as "matrix".
+    Maps values using reference subset coordinates (ss_x_ref, ss_y_ref).
+
+    Parameters
+    ol
+    ----------
+    data : np.ndarray
+        Array of shape (n_frames, n_points) to be reshaped into (n_frames, height, width).
+
+    shape : tuple
+        Target shape of output array: (n_frames, height, width).
+
+    ss_x_ref : np.ndarray
+        X coordinates of subset centers.
+
+    ss_y_ref : np.ndarray
+        Y coordinates of subset centers.
+
+    x_unique : np.ndarray
+        Sorted unique X coordinates in the grid.
+
+    y_unique : np.ndarray
+        Sorted unique Y coordinates in the grid.
+
+    Returns
+    -------
+    np.ndarray
+        Reshaped array with shape `shape`, filled with NaNs where no data exists.
+    """
+
+    grid = np.full(shape, np.nan)
+    for i, (x, y) in enumerate(zip(ss_x_ref, ss_y_ref)):
+        x_idx = np.where(x_unique == x)[0][0]
+        y_idx = np.where(y_unique == y)[0][0]
+        grid[:, y_idx, x_idx] = data[:, i]
+    return grid