pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/sensorsim/imagetools.py

@@ -0,0 +1,137 @@
+#===============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+#===============================================================================
+import warnings
+from enum import Enum
+from pathlib import Path
+import numpy as np
+import matplotlib.image as mplim
+from PIL import Image
+
+class EImageType(Enum):
+    TIFF = ".tiff"
+    BMP = ".bmp"
+
+    def __str__(self):
+        return self.value
+
+
+
+class ImageTools:
+    @staticmethod
+    def load_image_rgb(im_path: Path) -> np.ndarray:
+        return mplim.imread(im_path).astype(np.float64)
+
+
+    @staticmethod
+    def load_image_greyscale(im_path: Path) -> np.ndarray:
+
+        input_im = mplim.imread(im_path).astype(np.float64)
+        # If we have RGB then get rid of it
+        # TODO: make sure this is collapsing RGB to grey scale correctly
+        if input_im.ndim > 2:
+            input_im = input_im[:,:,0]
+
+        return input_im
+
+    @staticmethod
+    def save_image(save_file: Path,
+                   image: np.ndarray,
+                   image_type: EImageType,
+                   bits: int = 16) -> None:
+
+        # TODO: check this flip is needed
+        image_save = np.copy(image[::-1,:])
+        im = Image.fromarray(_image_to_uint(image_save,bits))
+        im.save(save_file.with_suffix(image_type.value))
+
+    @staticmethod
+    def scale_digitise_save(save_file: Path,
+                            image: np.ndarray,
+                            image_type: EImageType,
+                            bits: int = 16,
+                            min_frac: float = 0.0,
+                            max_frac: float = 1.0,
+                            background: float = 0.5) -> None:
+
+        image_save = ImageTools.digitise(image,bits,min_frac,max_frac,background)
+        # TODO: check this flip is needed
+        image_save = image_save[::-1,:]
+        im = Image.fromarray(_image_to_uint(image_save,bits))
+        im.save(save_file.with_suffix(image_type.value))
+
+
+    @staticmethod
+    def scale(image: np.ndarray, min_frac: float = 0.0, max_frac: float = 1.0) -> np.ndarray:
+
+        im_scale = np.copy(image)
+        im_max = np.nanmax(np.nanmax(image,axis=0),axis=0)
+        im_min = np.nanmin(np.nanmin(image,axis=0),axis=0)
+
+        # Scale image 0->1
+        im_scale = (im_scale - im_min)/(im_max-im_min)
+        
+        # Scale to between min->max
+        im_scale = im_scale*(max_frac-min_frac) + min_frac
+
+        return im_scale
+
+    @staticmethod
+    def digitise(image: np.ndarray,
+                 bits: int = 16,
+                 min_frac: float = 0.0,
+                 max_frac: float = 1.0,
+                 background_frac: float = 0.5) -> np.ndarray:
+        im_dig = ImageTools.scale(image,min_frac,max_frac)
+        mask_nan = np.isnan(image)
+        im_dig[mask_nan] = background_frac
+        im_dig = _image_to_uint(np.round(2**bits*im_dig),bits)
+        return im_dig
+
+    @staticmethod
+    def add_noise(image: np.ndarray) -> np.ndarray:
+        pass
+
+    @staticmethod
+    def get_num_str(im_num: int, width: int , cam_num: int = -1) -> str:
+        num_str = str(im_num)
+        num_str = num_str.zfill(width)
+
+        if cam_num >= 0:
+            num_str = num_str+'_'+str(cam_num)
+
+        return num_str
+
+    @staticmethod
+    def get_save_name(cam_num: int,
+                      frame_num: int,
+                      field_num: int | None,
+                      cam_width: int = 2,
+                      frame_width: int = 4,
+                      field_width: int = 2) -> str:
+        cam_str = str(cam_num).zfill(cam_width)
+        frame_str = str(frame_num).zfill(frame_width)
+
+        if field_num is None:
+            return f"cam{cam_str}_frame{frame_str}"
+
+        field_str = str(field_num).zfill(field_width)
+        return f"cam{cam_str}_frame{frame_str}_field{field_str}"
+
+
+def _image_to_uint(image: np.ndarray, bits: int) -> np.ndarray:
+    if (bits > 16) and (bits <= 32):
+        return image.astype(np.uint32)
+
+    if (bits > 8) and (bits <= 16):
+        return image.astype(np.uint16)
+
+    if (bits > 0) and (bits <= 8):
+        return image.astype(np.uint8)
+
+    warnings.warn(f"Number of bits={bits} should be between 0 and 32, defaulting to 16 bits.")
+    return image.astype(np.uint16)
+
+

pyvale/sensorsim/integratorfactory.py

@@ -0,0 +1,240 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import numpy as np
+from pyvale.sensorsim.field import IField
+from pyvale.sensorsim.sensordata import SensorData
+from pyvale.sensorsim.integratorspatial import IIntegratorSpatial
+from pyvale.sensorsim.integratortype import EIntSpatialType
+from pyvale.sensorsim.integratorrectangle import Rectangle2D
+from pyvale.sensorsim.integratorquadrature import (Quadrature2D,
+                                              create_gauss_weights_2d_4pts,
+                                              create_gauss_weights_2d_9pts)
+
+class IntegratorSpatialFactory:
+    """Namespace for static methods used to build 2D spatial integrators. These
+    integrators are used to simulate spatial averaging for sensors.
+    """
+
+    @staticmethod
+    def rect_2d_1pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Rectangle2D:
+        """Builds and returns a 2D rectangular spatial integrator with a single
+        integration point.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Rectangle2D
+            Rectangular spatial integrator that can sample the specified
+            physical field at specified locations
+        """
+
+        int_pt_offsets = np.array([[0,0,0],])
+
+        return Rectangle2D(field,
+                           sensor_data,
+                           int_pt_offsets)
+
+
+    @staticmethod
+    def rect_2d_4pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Rectangle2D:
+        """Builds and returns a 2D rectangular spatial integrator with four
+        equally spaced integration points in a grid pattern.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Rectangle2D
+            Rectangular spatial integrator that can sample the specified
+            physical field at specified locations
+        """
+        int_pt_offsets = sensor_data.spatial_dims * np.array([[-0.5,-0.5,0],
+                                                              [-0.5,0.5,0],
+                                                              [0.5,-0.5,0],
+                                                              [0.5,0.5,0],])
+
+        return Rectangle2D(field,
+                           sensor_data,
+                           int_pt_offsets)
+
+
+
+    @staticmethod
+    def rect_2d_9pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Rectangle2D:
+        """Builds and returns a 2D rectangular spatial integrator with nine
+        equally spaced integration points in a grid pattern.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Rectangle2D
+            Rectangular spatial integrator that can sample the specified
+            physical field at specified locations
+        """
+        int_pt_offsets = sensor_data.spatial_dims * np.array([[-1/3,-1/3,0],
+                                                              [-1/3,0,0],
+                                                              [-1/3,1/3,0],
+                                                              [0,-1/3,0],
+                                                              [0,0,0],
+                                                              [0,1/3,0],
+                                                              [1/3,-1/3,0],
+                                                              [1/3,0,0],
+                                                              [1/3,1/3,0]])
+
+        return Rectangle2D(field,
+                           sensor_data,
+                           int_pt_offsets)
+
+
+    @staticmethod
+    def quad_2d_4pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Quadrature2D:
+        """Builds and returns a Gaussian quadrature spatal integrator based on
+        a rectangular area with four integration points.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Quadrature2D
+            Quadrature integrator that can be used to sample the physical field
+            at specified locations.
+        """
+        gauss_pt_offsets = (sensor_data.spatial_dims * 1/np.sqrt(3)
+                                            * np.array([[-1,-1,0],
+                                                        [-1,1,0],
+                                                        [1,-1,0],
+                                                        [1,1,0]]))
+
+        gauss_weight_func = create_gauss_weights_2d_4pts
+
+        return Quadrature2D(field,
+                            sensor_data,
+                            gauss_pt_offsets,
+                            gauss_weight_func)
+
+
+    @staticmethod
+    def quad_2d_9pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Quadrature2D:
+        """Builds and returns a Gaussian quadrature spatal integrator based on
+        a rectangular area with nine integration points.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Quadrature2D
+            Quadrature integrator that can be used to sample the physical field
+            at specified locations.
+        """
+        gauss_pt_offsets = (sensor_data.spatial_dims
+                            * np.array([[-np.sqrt(0.6),-np.sqrt(0.6),0],
+                                        [-np.sqrt(0.6),np.sqrt(0.6),0],
+                                        [np.sqrt(0.6),-np.sqrt(0.6),0],
+                                        [np.sqrt(0.6),np.sqrt(0.6),0],
+                                        [-np.sqrt(0.6),0,0],
+                                        [0,-np.sqrt(0.6),0],
+                                        [0,np.sqrt(0.6),0],
+                                        [np.sqrt(0.6),0,0],
+                                        [0,0,0]]))
+
+        gauss_weight_func = create_gauss_weights_2d_9pts
+
+        return Quadrature2D(field,
+                            sensor_data,
+                            gauss_pt_offsets,
+                            gauss_weight_func)
+
+
+def build_spatial_averager(field: IField, sensor_data: SensorData,
+                          ) -> IIntegratorSpatial | None:
+    """Helper function to build a spatial integrator based on the
+    "EIntSpatialType" enumeration in the SensorData object. Separates the
+    spatial integration object from the SensorData object.
+
+    Parameters
+    ----------
+    field : IField
+        Physical field that will be sampled by the spatial averager.
+    sensor_data : SensorData
+        Sensor data containing the type of spatial integrator to build in the
+        `sensor_data.spatial_averager` as an `EIntSpatialType` enumeration.
+
+    Returns
+    -------
+    IIntegratorSpatial | None
+        The spatial averager that will sample the physical field at the
+        specified sensor locations. If `sensor_data.spatial_averager` or
+        `sensor_data.spatial_dims` are None then it is not possible to build a
+        spatial integrator and None is returned.
+    """
+    if sensor_data.spatial_averager is None or sensor_data.spatial_dims is None:
+        return None
+
+    if sensor_data.spatial_averager == EIntSpatialType.RECT1PT:
+        return IntegratorSpatialFactory.rect_2d_1pt(field,
+                                                    sensor_data)
+    elif sensor_data.spatial_averager == EIntSpatialType.RECT4PT:
+        return IntegratorSpatialFactory.rect_2d_4pt(field,
+                                                    sensor_data)
+    elif sensor_data.spatial_averager == EIntSpatialType.RECT9PT:
+        return IntegratorSpatialFactory.rect_2d_9pt(field,
+                                                    sensor_data)
+    elif sensor_data.spatial_averager == EIntSpatialType.QUAD4PT:
+        return IntegratorSpatialFactory.quad_2d_4pt(field,
+                                                    sensor_data)
+    elif sensor_data.spatial_averager == EIntSpatialType.QUAD9PT:
+        return IntegratorSpatialFactory.quad_2d_9pt(field,
+                                                    sensor_data)
+    else:
+        return None

pyvale/sensorsim/integratorquadrature.py

@@ -0,0 +1,217 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+from typing import Callable
+import numpy as np
+from pyvale.sensorsim.field import IField
+from pyvale.sensorsim.integratorspatial import (IIntegratorSpatial,
+                                      create_int_pt_array)
+from pyvale.sensorsim.sensordata import SensorData
+
+
+class Quadrature2D(IIntegratorSpatial):
+    """Gaussian quadrature numerical integrator for spatial averaging in 2D.
+    Used to model spatial averaging of sensors over a rectangular area which is
+    specified in the SensorData object. Handles sampling of the physical field
+    at the integration points and averages them back to a single value per
+    sensor location as specified in the SensorData object.
+
+    Implements the `IIntegratorSpatial` interface allowing for interoperability
+    of different spatial integration algorithms for modelling sensor averaging.
+    """
+    __slots__ = ("_field","_area","_gauss_pts_num","_gauss_pt_offsets"
+                 ,"_gauss_weight_func","_gauss_pts","_averages","_sens_data")
+
+    def __init__(self,
+                 field: IField,
+                 sens_data: SensorData,
+                 gauss_pt_offsets: np.ndarray,
+                 gauss_weight_func: Callable) -> None:
+        """
+        Parameters
+        ----------
+        field : IField
+            A physical field interface that will be sampled at the integration
+            points and averaged back to single value per sensor.
+        sens_data : SensorData
+            Parameters of the sensor array including the sensor locations,
+            sampling times, type of spatial integrator and its dimensions. See
+            the `SensorData` dataclass for more details.
+        gauss_pt_offsets : np.ndarray
+            Offsets from the central location of the integration area with
+            shape=(n_gauss_pts,coord[X,Y,Z])
+        gauss_weight_func : Callable
+            A function that takes the shape of the measurement array as a tuple
+            and returns a numpy array of weights for the gaussian integration
+            points. The function must return an array with shape=(n_gauss_pts,)
+            +meas_shape where meas_shape=(num_sensors,num_field_components,
+            num_time_steps)
+        """
+        self._field = field
+        self._sens_data = sens_data
+        self._area = self._sens_data.spatial_dims[0] * \
+            self._sens_data.spatial_dims[1]
+
+        self._gauss_pts_num = gauss_pt_offsets.shape[0]
+        self._gauss_pt_offsets = gauss_pt_offsets
+        self._gauss_weight_func = gauss_weight_func
+
+        self._gauss_pts = create_int_pt_array(self._sens_data,
+                                              self._gauss_pt_offsets)
+        self._averages = None
+
+    def calc_integrals(self, sens_data: SensorData | None = None) -> np.ndarray:
+        """Calculates the numerical integrals for each sensor based on the
+        specified sensor data and numerical integration options (i.e. geometry
+        and integration points).
+
+        Parameters
+        ----------
+        sens_data : SensorData | None, optional
+            Specifies the sensor parameters used to calculate the averages, by
+            default None. Is a sensor data object is passed a reference to that
+            object is stored by this class and used in later calculations. If
+            None then it uses the SensorData object stored by this class.
+            Defaults to None.
+
+        Returns
+        -------
+        np.ndarray
+            Array of virtual sensor integrals with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
+        """
+        self._averages = self.calc_averages(sens_data)
+        return self._area*self.get_averages()
+
+    def get_integrals(self) -> np.ndarray:
+        """Gets the most recent calculation of the spatial averages for all
+        sensors in the sensor array without performing any new interpolation. If
+        the averages have not been calculated they are first calculated and then
+        returned.
+
+        Returns
+        -------
+        np.ndarray
+            Array of virtual sensor averages with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
+        """
+        return self._area*self.get_averages()
+
+    def calc_averages(self, sens_data: SensorData | None = None) -> np.ndarray:
+        """Calculates the spatial averages for each sensor based on the
+        specified sensor data and numerical integration options (i.e. geometry
+        and integration points).
+
+        Parameters
+        ----------
+        sens_data : SensorData | None, optional
+            Specifies the sensor parameters used to calculate the averages, by
+            default None. Is a sensor data object is passed a reference to that
+            object is stored by this class and used in later calculations. If
+            None then it uses the SensorData object stored by this class.
+            Defaults to None.
+
+        Returns
+        -------
+        np.ndarray
+            Array of virtual sensor averages with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
+        """
+        if sens_data is not None:
+            self._sens_data = sens_data
+
+        # shape=(n_sens*n_gauss_pts,n_dims)
+        self._gauss_pts = create_int_pt_array(self._sens_data,
+                                              self._gauss_pt_offsets)
+
+        # shape=(n_gauss_pts*n_sens,n_comps,n_timesteps)
+        gauss_vals = self._field.sample_field(self._gauss_pts,
+                                              self._sens_data.sample_times,
+                                              self._sens_data.angles)
+
+        meas_shape = (self._sens_data.positions.shape[0],
+                      gauss_vals.shape[1],
+                      gauss_vals.shape[2])
+
+        # shape=(n_gauss_pts,n_sens,n_comps,n_timesteps)
+        gauss_vals = gauss_vals.reshape((self._gauss_pts_num,)+meas_shape,
+                                         order='F')
+
+        # shape=(n_gauss_pts,n_sens,n_comps,n_timesteps)
+        gauss_weights = self._gauss_weight_func(meas_shape)
+
+        # NOTE: coeff comes from changing gauss interval from [-1,1] to [a,b] -
+        # so (a-b)/2 * (a-b)/2 = sensor_area / 4, then need to divide by the
+        # integration area to convert to an average:
+        # integrals = self._area/4 * np.sum(gauss_weights*gauss_vals,axis=0)
+        # self._averages = (1/self._area)*integrals
+
+        # shape=(n_sensors,n_comps,n_timsteps)=meas_shape
+        self._averages = 1/4 * np.sum(gauss_weights*gauss_vals,axis=0)
+        return self._averages
+
+    def get_averages(self) -> np.ndarray:
+        """Gets the most recent calculation of the spatial averages for all
+        sensors in the sensor array without performing any new interpolation. If
+        the averages have not been calculated they are first calculated and then
+        returned.
+
+        Returns
+        -------
+        np.ndarray
+            Array of virtual sensor averages with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
+        """
+        if self._averages is None:
+            self._averages = self.calc_averages()
+
+        return self._averages
+
+
+def create_gauss_weights_2d_4pts(meas_shape: tuple[int,int,int]) -> np.ndarray:
+    """Helper function that creates an array of weights for gaussian quadrature
+    integration. This function provides the weights for 2D integrator with 4
+    integration points.
+
+    Parameters
+    ----------
+    meas_shape : tuple[int,int,int]
+        Shape of the measurement array, shape=(n_sensors,n_field_comps,
+        n_time_steps).
+
+    Returns
+    -------
+    np.ndarray
+        Array of gaussian quadrature weights with shape = (n_gauss_pts,n_sensors
+        ,n_field_comps,n_time_steps).
+    """
+    #shape=(4,)+meas_shape
+    return np.ones((4,)+meas_shape)
+
+
+def create_gauss_weights_2d_9pts(meas_shape: tuple[int,int,int]) -> np.ndarray:
+    """Helper function that creates an array of weights for gaussian quadrature
+    integration. This function provides the weights for 2D integrator with 9
+    integration points.
+
+    Parameters
+    ----------
+    meas_shape : tuple[int,int,int]
+        Shape of the measurement array, shape=(n_sensors,n_field_comps,
+        n_time_steps).
+
+    Returns
+    -------
+    np.ndarray
+        Array of gaussian quadrature weights with shape = (n_gauss_pts,n_sensors
+        ,n_field_comps,n_time_steps).
+    """
+    # shape=(9,)+meas_shape
+    gauss_weights = np.vstack((25/81 * np.ones((4,)+meas_shape),
+                               40/81 * np.ones((4,)+meas_shape),
+                               64/81 * np.ones((1,)+meas_shape)))
+    return gauss_weights
+