pyvale 2025.5.3__cp311-cp311-macosx_14_0_arm64.whl → 2025.7.0__cp311-cp311-macosx_14_0_arm64.whl

pyvale/dicresults.py

@@ -0,0 +1,55 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
+
+from dataclasses import dataclass
+import numpy as np
+
+@dataclass(slots=True)
+class DICResults:
+    """
+    Data container for Digital Image Correlation (DIC) analysis results.
+
+    This dataclass stores the displacements, convergence info, and correlation data
+    associated with a DIC computation.
+
+    Attributes
+    ----------
+    ss_x : np.ndarray
+        The x-coordinates of the subset centers (in pixels).
+    ss_y : np.ndarray
+        The y-coordinates of the subset centers (in pixels).
+    u : np.ndarray
+        Horizontal displacements at each subset location.
+    v : np.ndarray
+        Vertical displacements at each subset location.
+    mag : np.ndarray
+        Displacement magnitude at each subset location, typically computed as sqrt(u^2 + v^2).
+    converged : np.ndarray
+        boolean value for whether the subset has converged or not.
+    cost : np.ndarray
+        Final cost or residual value from the correlation optimization (e.g., ZNSSD).
+    ftol : np.ndarray
+        Final `ftol` value from the optimization routine, indicating function tolerance.
+    xtol : np.ndarray
+        Final `xtol` value from the optimization routine, indicating solution tolerance.
+    niter : np.ndarray
+        Number of iterations taken to converge for each subset point.
+    filenames : list[str]
+        name of DIC result files that have been found
+    """
+
+    ss_x: np.ndarray
+    ss_y: np.ndarray
+    u: np.ndarray
+    v: np.ndarray
+    mag: np.ndarray
+    converged: np.ndarray
+    cost: np.ndarray
+    ftol: np.ndarray
+    xtol: np.ndarray
+    niter: np.ndarray
+    filenames: list[str]

pyvale/dicspecklegenerator.py

@@ -0,0 +1,238 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
+
+from dataclasses import dataclass
+import numpy as np
+from scipy.ndimage import gaussian_filter
+import matplotlib.pyplot as plt
+import PIL
+
+
+class DICSpeckleGen:
+    """
+    Dataclass holding summary information for the speckle pattern
+    """
+    def __init__(self,
+                 seed=None,
+                 px_vertical: int=720,
+                 px_horizontal: int=1280,
+                 size_radius: int=3,
+                 size_stddev: float=0.0,
+                 loc_variance: float=0.6,
+                 loc_spacing: int=7,
+                 smooth: bool=True,
+                 smooth_stddev: float=1.0,
+                 gray_level: int=4096,
+                 pattern_digitisation: bool=True):
+
+        self.seed = seed
+        self.px_vertical = px_vertical
+        self.px_horizontal = px_horizontal
+        self.size_radius = size_radius
+        self.size_stddev = size_stddev
+        self.loc_variance = loc_variance
+        self.loc_spacing = loc_spacing
+        self.smooth = smooth
+        self.smooth_stddev = smooth_stddev
+        self.gray_level = gray_level
+        self.pattern_digitisation = pattern_digitisation
+        self.array = None
+
+        # ensure gray level is valid
+        if self.gray_level not in {256, 4096, 65536}:
+            raise ValueError("gray_level must be one of {256, 4096, 65536}")
+
+        # generate pattern and store in memory upon calling class
+        self.generate_array()
+
+
+
+    def generate_array(self) -> None:
+
+        """
+        Generate a speckle pattern based on default or user provided paramters.
+
+        Args:
+            None
+
+        Returns:
+            np.array: 2D speckle pattern.
+        """
+
+        # intialise speckle pattern based on datatype
+        pattern_dtype = np.int32 if self.pattern_digitisation else np.float64          
+        self.array = np.zeros((self.px_vertical, self.px_horizontal), dtype=pattern_dtype)
+
+
+        # set random seed
+        np.random.seed(self.seed)
+
+        # speckles per row/col
+        nspeckles_x = self.px_vertical // self.loc_spacing
+        nspeckles_y = self.px_horizontal // self.loc_spacing
+
+        # total number of speckles
+        nspeckles = nspeckles_x * nspeckles_y
+
+        # uniformly spaced grid of speckles.
+        grid_x_uniform, grid_y_uniform = self._create_flattened_grid(nspeckles_x, nspeckles_y)
+
+        # apply random shift
+        low  = -self.loc_variance * self.loc_spacing
+        high =  self.loc_variance * self.loc_spacing
+        grid_x = self._random_shift_grid(grid_x_uniform, low, high, nspeckles)
+        grid_y = self._random_shift_grid(grid_y_uniform, low, high, nspeckles)
+
+
+        # pull speckle size from a normal distribution
+        radii = np.random.normal(self.size_radius, self.size_stddev, nspeckles).astype(int)
+
+        # loop over all grid points and create a circle mask. Mask then applied to pattern array.
+        for ii in range(0, nspeckles):
+            x,y,mask = self._circle_mask(grid_x[ii], grid_y[ii], radii[ii])
+            self.array[x[mask], y[mask]] = self.gray_level-1
+
+
+        # apply smoothing
+        if self.smooth is True:
+            self.array = gaussian_filter(self.array, self.smooth_stddev).astype(pattern_dtype)
+
+        return None
+
+
+    def get_array(self) -> np.ndarray:
+
+        return self.array
+
+
+
+    def show(self) -> None:
+        """
+        Display pattern as an image using Matplotlib.
+
+        Returns:
+        None
+        """
+        plt.figure()
+        plt.xlabel('Pixel')
+        plt.ylabel('Pixel')
+        plt.imshow(self.array,cmap='gray', vmin=0, vmax=self.gray_level-1)
+        plt.colorbar()
+        plt.show()
+
+        return None
+
+
+    def save(self,filename: str) -> None:
+        """
+        Save the speckle pattern array as an image with PIL package.
+        Image can either be saved as 8bit or 16bit image.
+        Image Saved in .tiff format.
+
+        Args:
+        filename   (str): name/location of output image
+
+        Returns:
+        None: Saves image to directory withuser specified details.
+        """
+
+        if self.gray_level == 256:
+            image = PIL.Image.fromarray((self.array).astype(np.uint8))
+        elif (self.gray_level == 4096) or (self.gray_level == 65536):
+            image = PIL.Image.fromarray((self.array).astype(np.uint16))
+        else:
+            raise ValueError("gray_level must be one of {256, 4096, 65536}")
+
+
+        image.save(filename, format="TIFF")
+
+        return None
+
+
+
+
+    def _create_flattened_grid(self,
+                               nspeckles_x: int,
+                               nspeckles_y: int) -> tuple[np.ndarray,np.ndarray]:
+        """
+        Return a flattened grid for speckle locations.
+        Evenly spaced grid based on axis size and the no. speckles along axis.
+        Args:
+            nspeckles_x (int): Number of speckles along x-axis
+            nspeckles_y (int): Number of speckles along y-axis
+
+        Returns:
+            tuple (np.array, np.array): speckle indexes for each axis.
+        """
+
+        grid_x, grid_y = np.meshgrid(np.linspace(0, self.px_vertical-1,  nspeckles_x),
+                                        np.linspace(0, self.px_horizontal-1, nspeckles_y))
+
+        grid_flattened_x = grid_x.flatten()
+        grid_flattened_y = grid_y.flatten()
+
+        return grid_flattened_x, grid_flattened_y
+
+
+    def _random_shift_grid(self,
+                           grid: np.array,
+                           low: int,
+                           high: int,
+                           nsamples: int) -> np.array:
+        """
+        Takes a uniformly spaced grid as input as applies a unifirm random shift to each position.
+        Args:
+            grid   (np.array): grid to apply shifts
+            low         (int): lowest possible value returned from shift
+            high        (int): high possible value returned from shift
+            nsamples    (int): number of speckles for shift.
+
+        Returns:
+            np.array: a numpy array of updated speckle locations after applying a random shift.
+        """
+
+        rand_shift_size = np.random.uniform(low, high, nsamples).astype(int)
+        updated_grid = grid.astype(int) + rand_shift_size
+
+        return updated_grid
+
+
+
+
+
+    def _circle_mask(self,
+                     pos_x: int,
+                     pos_y: int,
+                     radius: int) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Generates a circular mask centered at speckle location position with a given radius. 
+        The mask is applied within image bounds.
+
+        Args:
+            pos_x       (int): The x-coordinate of the center of the circle.
+            pos_y       (int): The y-coordinate of the center of the circle.
+            radius      (int): The radius of the circle (in pixels).
+
+        Returns:
+            tuple: A tuple containing:
+                - x (np.ndarray): The x-coordinates of mask region.
+                - y (np.ndarray): The y-coordinates of mask region.
+                - mask (np.ndarray): Bool array containing speckle area.
+        """
+
+        min_x = max(pos_x - radius, 0)
+        min_y = max(pos_y - radius, 0)
+        max_x = min(pos_x + radius + 1, self.px_vertical)
+        max_y = min(pos_y + radius + 1, self.px_horizontal)
+
+        # Generate mesh grid of possible (xx, yy) points
+        x, y = np.meshgrid(np.arange(min_x, max_x), np.arange(min_y, max_y))
+
+        # Update the pattern for points inside the circle's radius
+        mask = (x - pos_x)**2 + (y - pos_y)**2 <= radius**2
+
+        return x, y, mask

pyvale/dicspecklequality.py

@@ -0,0 +1,305 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
+
+import math
+import numpy as np
+import matplotlib.pyplot as plt
+import cv2
+import scipy.ndimage as ndi
+from numba import jit
+
+
+
+class DICSpeckleQuality:
+
+    def __init__(self, pattern: np.ndarray, subset_size: int, subset_step: int, gray_level: int):
+        self.pattern = pattern
+        self.subset_size = subset_size
+        self.subset_step = subset_step
+        self.gray_level = gray_level
+
+        # Internal cache for speckle sizes
+        self._speckle_sizes = None
+        self._subset_average = None
+        self._xvalues = None
+        self._yvalues = None
+
+        #TODO: regoin of interest for staticistics
+        # this needs to be a 'sub' array of the overall image
+
+
+
+    def mean_intensity_gradient(self) -> float:
+        """ 
+        Mean Intensity Gradient. Based on the below: 
+        https://www.sciencedirect.com/science/article/abs/pii/S0143816613001103 
+
+        Returns:
+        mean_intensity_gradient (float): float value for mean_intensity gradient
+        """
+
+        gradient_x, gradient_y = np.gradient(self.pattern)
+
+        # mag
+        gradient_magnitude = np.sqrt(gradient_x**2 + gradient_y**2)
+
+        # plot for debugging
+        plt.figure()
+        plt.imshow(gradient_magnitude)
+        plt.colorbar(label='Magnitude')
+        plt.show()
+
+        #get mean of 2d array.
+        mean_gradient = np.mean(gradient_magnitude)
+
+        return mean_gradient
+
+    
+    def shannon_entropy(self) -> float:
+        """ 
+        shannon entropy for speckle patterns. Based on the below: 
+        https://www.sciencedirect.com/science/article/abs/pii/S0030402615007950 
+
+        
+        Returns:
+        shannon_entropy (float): float value for shannon entropy
+        """
+
+        #count occurances of each value. bincount doesn't like 2d arrays. flatten to 1d.
+        bins = np.bincount(self.pattern.flatten()) / self.pattern.size
+
+        # reset shannon_entropy
+        shannon_entropy = 0.0
+
+        # loop over gray leves
+        for i in range(0,2):
+            shannon_entropy -= bins[i] * math.log2(bins[i])
+
+        return shannon_entropy
+
+    def gray_level_histogram(self) -> None:
+        """
+        Count the number of occurrences of each gray value.
+        plot results as a histogram
+        """
+
+        # Count occurrences of each gray value
+        unique_values, counts = np.unique(self.pattern, return_counts=True)
+
+        # Plot histogram
+        plt.figure(figsize=(8, 5))
+        plt.bar(unique_values, counts, width=1.0, color='gray', edgecolor='black')
+        plt.title('Histogram of Gray Levels')
+        plt.xlabel('Gray Level (0-255)')
+        plt.ylabel('Count')
+        plt.grid(axis='y', linestyle='--', alpha=0.7)
+        plt.show()
+
+        return None
+
+
+
+
+
+    def speckle_size(self) -> tuple[int, np.ndarray, np.ndarray]:
+        """
+        Calculates the Speckle sizes using a binary map calculaed from otsu threshholding
+        (https://learnopencv.com/otsu-thresholding-with-opencv/)
+
+        
+        Returns:
+        tuple containing:
+        num_speckles                   (int): total number of speckles identified in the binary map
+        equivalent_diameters    (np.ndarray): Speckle diameter if circle with same area
+        labeled_speckles        (np.ndarray): Label of the connected elements within speckle
+        """
+
+        # calculate binary map using otsu thresholding with opencv
+        _, binary_image = cv2.threshold(self.pattern,
+                                        0,
+                                        self.gray_level - 1, 
+                                        cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+
+        # Label connected components (speckles)
+        labeled_speckles, num_speckles = ndi.label(binary_image)
+        speckle_sizes = np.array(ndi.sum(binary_image > 0, 
+                                         labeled_speckles, 
+                                         index=np.arange(1, num_speckles + 1)))
+        
+        equivalent_diameters = 2 * np.sqrt(speckle_sizes / np.pi)
+
+        # assign values to cached tuple
+        self._speckle_sizes = (num_speckles, equivalent_diameters, labeled_speckles)
+
+        # Raise exception if there's no speckles
+        if num_speckles ==  0:
+            raise ValueError("No speckles identified.")
+        
+        return self._speckle_sizes
+
+
+    def speckle_size_plot(self) -> None:
+
+        # get speckle sizes if not computed already
+        if self._speckle_sizes is None:
+            self.speckle_size()
+
+        # assign each speckle to a classification group.
+        # Group is jst the 'size' unsure whether to bin to discrete sizes
+        classifications = self._classify_speckles()
+
+        # plotting
+        fig, axes = plt.subplots(1, 2, figsize=(12, 6), sharex=True, sharey=True)
+
+        im1 = axes[0].imshow(self.pattern, cmap='gray', vmin=0, vmax=255)
+        axes[0].set_title("Speckle Pattern")
+        axes[0].axis("off")
+        fig.colorbar(im1,ax=axes[0],fraction=0.046, pad=0.04)
+
+
+        im2 = axes[1].imshow(classifications, cmap="turbo", vmin=0, vmax=15)
+        axes[1].set_title("Speckle Size")
+        axes[1].axis("off")
+        fig.colorbar(im2,ax=axes[1],fraction=0.046, pad=0.04)
+
+        plt.show()
+
+        return None
+
+
+    def _classify_speckles(self) -> np.ndarray:
+        """
+        Calculates the Speckle sizes using a binary map calculaed from otsu threshholding
+        (https://learnopencv.com/otsu-thresholding-with-opencv/)
+
+
+        Returns:
+        classifications  (np.ndarray): speckle sizes classified by bin sizes for plots.
+                                       To discuss which bins are appropriate.
+                                       My proposed bins:
+                                       0-3 small, 3-5 ideal, 5 < big.
+        """
+
+
+        num_speckles, speckle_sizes, labeled_speckles = self._speckle_sizes
+        classifications = np.zeros_like(labeled_speckles, dtype=np.uint8)
+
+        #TODO: Not sure whether to bin into three catagorories:
+        # 0-3 kinda small, 3-5 ideal, 5 < kinda big.
+        # I'm leaving the logic in to deal with this but going to assume continous is probs best
+        for i in range(1, num_speckles + 1):
+            size = speckle_sizes[i - 1]
+            if size <= 3:
+                classifications[labeled_speckles == i] = size #1
+            elif 3 < size <= 5:
+                classifications[labeled_speckles == i] = size #3
+            else:
+                classifications[labeled_speckles == i] = size #2 
+
+        return classifications
+
+
+    def balance_subset(self) -> np.ndarray:
+
+        # dont use subsets if rows/cols < edge_cutoff
+        edge_cutoff = 100
+
+        min_x = self.subset_size // 2
+        min_y = self.subset_size // 2
+        max_x = self.pattern.shape[1] - self.subset_size // 2
+        max_y = self.pattern.shape[0] - self.subset_size // 2
+
+        # image coordiantes array containing the central pixel for each subset
+        self._xvalues = np.arange(min_x+edge_cutoff, max_x-edge_cutoff, self.subset_step)
+        self._yvalues = np.arange(min_y+edge_cutoff, max_y-edge_cutoff, self.subset_step)
+        
+        # init array to store black/white balance value
+        shape = (len(self._yvalues), len(self._xvalues))
+        self._subset_average = np.zeros(shape)
+
+
+        # looping over the subsets
+        for i, x in enumerate(self._xvalues):
+            for j, y in enumerate(self._yvalues):
+
+                subset = extract_subset(self.pattern, x, y, self.subset_size)
+
+                # plt.figure()
+                # plt.imshow(subset)
+                # plt.show()
+
+                self._subset_average[j,i] = np.average(subset) / self.gray_level
+
+        return self._subset_average
+    
+
+    def balance_image(self) -> float:
+
+        avg = np.mean(self.pattern) / self.gray_level
+
+        return avg
+
+    def balance_subset_avg(self) -> float:
+
+        if self._subset_average is None:
+            self.balance_subset()
+
+        subset_avg = np.mean(self._subset_average)
+
+        return subset_avg
+
+
+
+    def balance_subset_plot(self) -> None:
+
+        if self._subset_average is None:
+            self.balance_subset()
+
+        plt.figure(figsize=(10, 10))
+        plt.imshow(self.pattern, cmap='gray', interpolation='none')
+        extent = [self._xvalues[0], self._xvalues[-1], self._yvalues[-1], self._yvalues[0]]  # Match coordinates
+        plt.imshow(self._subset_average, cmap='jet', alpha=0.3, extent=extent, interpolation='none')
+        plt.xlim(0,self.pattern.shape[1])
+        plt.ylim(self.pattern.shape[0],0)
+        plt.colorbar(label='Normalized Subset Average')
+        plt.title("Black/White Balance Overlay")
+        plt.show()
+
+        return None
+
+
+
+#TODO: This is going to become c++ at some point.
+# I think this is OK to keep in python for calculation of black/white balance
+@jit(nopython=True)
+def extract_subset(image: np.ndarray, x: int, y: int, subset_size: int) -> np.ndarray:
+    """
+    Parameters
+    x (int): x-coord of subset center in image
+    y (int): y-coord of subset center in image
+
+    """
+
+    half_size = subset_size // 2
+
+    # reference image subset
+    x1, x2 = x - half_size, x + half_size + 1
+    y1, y2 = y - half_size, y + half_size + 1
+
+    # Ensure indices are within bounds
+    #TODO: Update this when implementing ROI
+    if (x1 < 0 or y1 < 0 or x2 > image.shape[1] or y2 > image.shape[0]):
+        raise ValueError(f"Subset exceeds image boundaries.\nSubset Pixel Range:\n"
+                        f"x1: {x1}\n"
+                        f"x2: {x2}\n"
+                        f"y1: {y1}\n"
+                        f"y2: {y2}")
+
+    # Extract subsets
+    subset = image[y1:y2, x1:x2]
+
+    return subset