pyvale 2025.4.0__py3-none-any.whl → 2025.5.1__py3-none-any.whl

pyvale/camerastereo.py

@@ -0,0 +1,217 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+NOTE: This module is a feature under developement.
+"""
+
+from typing import Self
+from pathlib import Path
+import numpy as np
+import yaml
+from scipy.spatial.transform import Rotation
+from pyvale.cameradata import CameraData
+from pyvale.pyvaleexceptions import BlenderError
+
+
+class CameraStereo:
+    __slots__ = ("cam_data_0","cam_data_1","stereo_dist","stereo_rotation")
+
+    def __init__(self, cam_data_0: CameraData, cam_data_1: CameraData) -> None:
+        self.cam_data_0 = cam_data_0
+        self.cam_data_1 = cam_data_1
+
+        cam0_rot_matrix = Rotation.as_matrix(self.cam_data_0.rot_world)
+        cam1_rot_matrix = Rotation.as_matrix(self.cam_data_1.rot_world)
+        (self.stereo_rotation, _) = Rotation.align_vectors(cam0_rot_matrix,
+                                                           cam1_rot_matrix)
+        dist = self.cam_data_0.pos_world - self.cam_data_1.pos_world
+        dist_rot = self.cam_data_0.rot_world.apply(dist)
+        inverse = self.stereo_rotation.inv().as_quat()
+        inverse[3] *= -1
+        inverse = Rotation.from_quat(inverse)
+        self.stereo_dist = inverse.apply(dist_rot)
+
+    @classmethod
+    def from_calibration(cls,
+                         calib_path: Path,
+                         pos_world_0: np.ndarray,
+                         rot_world_0: Rotation,
+                         focal_length: float) -> Self:
+        """A method to initialise the CameraStereo using a calibration file and
+        some additional parameters. This creates an instance of the CameraStereo
+        class from the calibration parameters.
+
+        Parameters
+        ----------
+        calib_path : Path
+            The path to the calibration file (in yaml format).
+        pos_world_0 : np.ndarray
+            The position of camera 0 in world coordinates.
+        rot_world_0 : Rotation
+            The rotation of camera 0 in world coordinates.
+        focal_length : float
+            The focal length of camera 0.
+
+        Returns
+        -------
+        Self
+            An instance of the CameraStereo class, given the specified parameters.
+        """
+        calib_params = yaml.safe_load(calib_path.read_text())
+        pixels_num_cam0 = np.array([calib_params['Cam0_Cx [pixels]']*2,
+                           calib_params['Cam0_Cy [pixels]']*2])
+        pixels_num_cam1 = np.array([calib_params['Cam1_Cx [pixels]']*2,
+                           calib_params['Cam1_Cy [pixels]']*2])
+        pixels_size = focal_length / calib_params["Cam0_Fx [pixels]"]
+        stereo_rotation = Rotation.from_euler("xyz", ([calib_params['Theta [deg]'],
+                                    calib_params['Phi [deg]'],
+                                    calib_params['Psi [deg]']]), degrees=True)
+        stereo_dist = np.array([calib_params["Tx [mm]"],
+                                calib_params["Ty [mm]"],
+                                calib_params["Tz [mm]"]])
+
+        rot_world_1 = stereo_rotation * rot_world_0
+
+        inverse = stereo_rotation.inv().as_quat()
+        inverse[3] *= -1
+        inverse = Rotation.from_quat(inverse)
+
+        dist_rot = inverse.inv().apply(stereo_dist)
+        dist = rot_world_0.inv().apply(dist_rot)
+        pos_world_1 = pos_world_0 - dist
+
+        cam_data_0 = CameraData(pixels_num=pixels_num_cam0,
+                                pixels_size=np.array([pixels_size, pixels_size]),
+                                pos_world=pos_world_0,
+                                rot_world=rot_world_0,
+                                roi_cent_world=np.array([0, 0, 0]),
+                                focal_length=focal_length)
+        cam_data_1 = CameraData(pixels_num=pixels_num_cam1,
+                                pixels_size=np.array([pixels_size, pixels_size]),
+                                pos_world=pos_world_1,
+                                rot_world=rot_world_1,
+                                roi_cent_world=np.array([0, 0, 0]),
+                                focal_length=focal_length)
+        camera_stereo = cls(cam_data_0, cam_data_1)
+
+        return camera_stereo
+
+    def save_calibration(self, base_dir: Path) -> None:
+        """A method to save a calibration file of the stereo system as a yaml.
+        This is so that the file can easily be read into python, but is also
+        user-readable.
+
+        Parameters
+        ----------
+        base_dir : Path
+            The base directory to which all files should be saved. The
+            calibration file will be saved in a sub-directory named "calibration"
+            within this directory.
+
+        Raises
+        ------
+        BlenderError
+            "The specified save directory does not exist"
+        """
+        stereo_rotation = self.stereo_rotation.as_euler("xyz", degrees=True)
+        calib_params = {
+            "Cam0_Fx [pixels]": float(self.cam_data_0.focal_length /
+                                 self.cam_data_0.pixels_size[0]),
+            "Cam0_Fy [pixels]": float(self.cam_data_0.focal_length /
+                                 self.cam_data_0.pixels_size[1]),
+            "Cam0_Fs [pixels]": 0,
+            "Cam0_Kappa 1": self.cam_data_0.k1,
+            "Cam0_Kappa 2": self.cam_data_0.k2,
+            "Cam0_Kappa 3": self.cam_data_0.k3,
+            "Cam0_P1": self.cam_data_0.p1,
+            "Cam0_P2": self.cam_data_0.p2,
+            "Cam0_Cx [pixels]": float(self.cam_data_0.c0),
+            "Cam0_Cy [pixels]": float(self.cam_data_0.c1),
+            "Cam1_Fx [pixels]": float(self.cam_data_1.focal_length /
+                                 self.cam_data_1.pixels_size[0]),
+            "Cam1_Fy [pixels]": float(self.cam_data_1.focal_length /
+                                 self.cam_data_1.pixels_size[1]),
+            "Cam1_Fs [pixels]": 0,
+            "Cam1_Kappa 1": self.cam_data_1.k1,
+            "Cam1_Kappa 2": self.cam_data_1.k2,
+            "Cam1_Kappa 3": self.cam_data_1.k3,
+            "Cam1_P1": self.cam_data_1.p1,
+            "Cam1_P2": self.cam_data_1.p2,
+            "Cam1_Cx [pixels]": float(self.cam_data_1.c0),
+            "Cam1_Cy [pixels]": float(self.cam_data_1.c1),
+            "Tx [mm]": float(self.stereo_dist[0]),
+            "Ty [mm]": float(self.stereo_dist[1]),
+            "Tz [mm]": float(self.stereo_dist[2]),
+            "Theta [deg]": float(stereo_rotation[0]),
+            "Phi [deg]": float(stereo_rotation[1]),
+            "Psi [deg]": float(stereo_rotation[2])
+        }
+        if not base_dir.is_dir():
+            raise BlenderError("The specified save directory does not exist")
+
+        save_dir = base_dir / "calibration"
+        if not save_dir.is_dir():
+            save_dir.mkdir(parents=True, exist_ok=True)
+
+        filepath = str(save_dir / "calibration.yaml")
+        calib_file = open(filepath, "w")
+        yaml.safe_dump(calib_params, calib_file)
+        calib_file.close()
+        print("Calibration file saved to:", (save_dir / "calibration.yaml"))
+
+    def save_calibration_mid(self, base_dir: Path) -> None:
+        """A method to save a calibration file of the stereo system in a MatchID
+        accepted format.
+
+        Parameters
+        ----------
+        base_dir : Path
+            The base directory to which all files should be saved. The
+            calibration file will be saved in a sub-directory named "calibration"
+            within this directory.
+
+        Raises
+        ------
+        BlenderError
+            "The specified save directory does not exist"
+        """
+        if not base_dir.is_dir():
+            raise BlenderError("The specified save directory does not exist")
+
+        save_dir = base_dir / "calibration"
+        if not save_dir.is_dir():
+            save_dir.mkdir(parents=True, exist_ok=True)
+
+        filepath = str(save_dir / "calibration.caldat")
+        with open(filepath, "w") as file:
+            file.write(f'Cam0_Fx [pixels]; {self.cam_data_0.focal_length/ self.cam_data_0.pixels_size[0]}\n')
+            file.write(f'Cam0_Fy [pixels]; {self.cam_data_0.focal_length/ self.cam_data_0.pixels_size[1]}\n')
+            file.write("Cam0_Fs [pixels];0\n")
+            file.write(f'Cam0_Kappa 1;{self.cam_data_0.k1}\n')
+            file.write(f'Cam0_Kappa 2;{self.cam_data_0.k2}\n')
+            file.write(f'Cam0_Kappa 3;{self.cam_data_0.k3}\n')
+            file.write(f'Cam0_P1;{self.cam_data_0.p1}\n')
+            file.write(f'Cam0_P2;{self.cam_data_0.p2}\n')
+            file.write(f'Cam0_Cx [pixels];{self.cam_data_0.c0}\n')
+            file.write(f'Cam0_Cy [pixels];{self.cam_data_0.c1}\n')
+            file.write(f'Cam1_Fx [pixels]; {self.cam_data_1.focal_length/ self.cam_data_1.pixels_size[0]}\n')
+            file.write(f'Cam1_Fy [pixels]; {self.cam_data_1.focal_length/ self.cam_data_1.pixels_size[1]}\n')
+            file.write("Cam1_Fs [pixels];0\n")
+            file.write(f'Cam1_Kappa 1;{self.cam_data_1.k1}\n')
+            file.write(f'Cam1_Kappa 2;{self.cam_data_1.k2}\n')
+            file.write(f'Cam1_Kappa 3;{self.cam_data_1.k3}\n')
+            file.write(f'Cam1_P1;{self.cam_data_1.p1}\n')
+            file.write(f'Cam1_P2;{self.cam_data_1.p2}\n')
+            file.write(f'Cam1_Cx [pixels];{self.cam_data_1.c0}\n')
+            file.write(f'Cam1_Cy [pixels];{self.cam_data_1.c1}\n')
+            file.write(f"Tx [mm];{self.stereo_dist[0]}\n")
+            file.write(f"Ty [mm];{self.stereo_dist[1]}\n")
+            file.write(f"Tz [mm];{self.stereo_dist[2]}\n")
+            stereo_rotation = self.stereo_rotation.as_euler("xyz", degrees=True)
+            file.write(f"Theta [deg];{stereo_rotation[0]}\n")
+            file.write(f"Phi [deg];{stereo_rotation[1]}\n")
+            file.write(f"Psi [deg];{stereo_rotation[2]}")

pyvale/{core/cameratools.py → cameratools.py}

@@ -1,24 +1,28 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
 """
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
+NOTE: This module is a feature under developement.
 """
+
 import warnings
 from pathlib import Path
 import numpy as np
 from scipy.signal import convolve2d
+import copy
 from scipy.spatial.transform import Rotation
 import matplotlib.image as mplim
 from PIL import Image
-from pyvale.core.cameradata2d import CameraData2D
-from pyvale.core.sensordata import SensorData
+from pyvale.cameradata2d import CameraData2D
+from pyvale.sensordata import SensorData
+from pyvale.cameradata import CameraData
+from pyvale.camerastereo import CameraStereo
 
-# NOTE: This module is a feature under developement.
 
 class CameraTools:
-    #-------------------------------------------------------------------------------
     @staticmethod
     def load_image(im_path: Path) -> np.ndarray:
 
@@ -56,7 +60,6 @@ class CameraTools:
 
         return num_str
 
-    #-------------------------------------------------------------------------------
     @staticmethod
     def pixel_vec_px(pixels_count: np.ndarray) -> tuple[np.ndarray,np.ndarray]:
         px_vec_x = np.arange(0,pixels_count[0],1)
@@ -72,7 +75,6 @@ class CameraTools:
         (px_grid_x,px_grid_y) = CameraTools.pixel_grid_px(pixels_count)
         return (px_grid_x.flatten(),px_grid_y.flatten())
 
-    #-------------------------------------------------------------------------------
     @staticmethod
     def subpixel_vec_px(pixels_count: np.ndarray,
                             subsample: int = 2) -> tuple[np.ndarray,np.ndarray]:
@@ -92,7 +94,6 @@ class CameraTools:
         (px_grid_x,px_grid_y) = CameraTools.subpixel_grid_px(pixels_count,subsample)
         return (px_grid_x.flatten(),px_grid_y.flatten())
 
-    #-------------------------------------------------------------------------------
     @staticmethod
     def pixel_vec_leng(field_of_view: np.ndarray,
                             leng_per_px: float) -> tuple[np.ndarray,np.ndarray]:
@@ -116,7 +117,7 @@ class CameraTools:
         (px_grid_x,px_grid_y) = CameraTools.pixel_grid_leng(field_of_view,leng_per_px)
         return (px_grid_x.flatten(),px_grid_y.flatten())
 
-    #-------------------------------------------------------------------------------
+
     @staticmethod
     def subpixel_vec_leng(field_of_view: np.ndarray,
                           leng_per_px: float,
@@ -149,7 +150,6 @@ class CameraTools:
                                                         subsample)
         return (px_grid_x.flatten(),px_grid_y.flatten())
 
-    #-------------------------------------------------------------------------------
     @staticmethod
     def calc_resolution_from_sim_2d(pixels_count: np.ndarray,
                                     coords: np.ndarray,
@@ -211,7 +211,6 @@ class CameraTools:
                                     round(subsample/2)-1::subsample]
         return avg_image
 
-    #---------------------------------------------------------------------------
     @staticmethod
     def build_sensor_data_from_camera_2d(cam_data: CameraData2D) -> SensorData:
         pixels_vectorised = CameraTools.vectorise_pixel_grid_leng(cam_data.field_of_view,
@@ -263,16 +262,16 @@ class CameraTools:
         boundbox_cam_leng = (np.max(bound_box_cam_vecs,axis=1)
                             - np.min(bound_box_cam_vecs,axis=1))
 
-        print(80*"-")
-        print(f"{bb_min=}")
-        print(f"{bb_max=}")
-        print()
-        print("Cam to world mat:")
-        print(cam_to_world_mat)
-        print()
-        print("World to cam mat:")
-        print(world_to_cam_mat)
-        print(80*"-")
+        # print(80*"-")
+        # print(f"{bb_min=}")
+        # print(f"{bb_max=}")
+        # print()
+        # print("Cam to world mat:")
+        # print(cam_to_world_mat)
+        # print()
+        # print("World to cam mat:")
+        # print(world_to_cam_mat)
+        # print(80*"-")
 
         return np.array((boundbox_cam_leng[xx],boundbox_cam_leng[yy]))
 
@@ -325,4 +324,199 @@ class CameraTools:
         return (roi_pos_world,cam_pos_world)
 
 
-    #-------------------------------------------------------------------------------
+    #---------------------------------------------------------------------------
+    # Blender camera tools
+
+    @staticmethod
+    def calculate_FOV(cam_data: CameraData) -> tuple[float, float]:
+        """A method to calulate the camera's field of view in mm
+
+        Parameters
+        ----------
+        cam_data : CameraData
+            A dataclass containing the camera parameters
+
+        Returns
+        -------
+        tuple[float, float]
+            A tuple containing the field of view in mm in both x and y directions
+        """
+        FOV_x = (((cam_data.image_dist - cam_data.focal_length)
+                    / cam_data.focal_length) *
+                    (cam_data.pixels_size) *
+                    cam_data.pixels_num[0])[0]
+        FOV_y = (cam_data.pixels_num[1] / cam_data.pixels_num[0]) * FOV_x
+        FOV_mm = (FOV_x, FOV_y)
+        return FOV_mm
+
+    @staticmethod
+    def blender_FOV(cam_data: CameraData) -> tuple[float, float]:
+        """A method to calculate the camera's field of view in mm using Blender's
+        method. This method differs due to one simplification.
+
+        Parameters
+        ----------
+        cam_data : CameraData
+            A dataclass containing the camera parameters
+
+        Returns
+        -------
+        tuple[float, float]
+            A tuple containing the FOV in x and y directions
+        """
+        FOV_x = (cam_data.pixels_num[0] * cam_data.pixels_size[0] * cam_data.image_dist) / cam_data.focal_length
+        FOV_y = (cam_data.pixels_num[1] / cam_data.pixels_num[0]) * FOV_x
+        FOV_blender = (FOV_x, FOV_y)
+        return FOV_blender
+
+    @staticmethod
+    def calculate_mm_px_resolution(cam_data: CameraData) -> float:
+        """Function to calculate the mm/px resolution of a camera
+
+        Parameters
+        ----------
+        cam_data : CameraData
+            A dataclass containing the camera parameters
+
+        Returns
+        -------
+        float
+            The mm/px resolution
+        """
+        FOV_mm = CameraTools.blender_FOV(cam_data)
+        resolution = FOV_mm[0] / cam_data.pixels_num[0]
+        return resolution
+
+    @staticmethod
+    def focal_length_from_resolution(pixels_size: np.ndarray,
+                                    working_dist: float,
+                                    resolution: float) -> float:
+        """A method to calculate the required focal length to achieve a certain
+        resolution. This is calculated given the pixel size and working distance.
+        This method can be used for a 2D setup or for camera 0 for a stereo setup.
+
+        Parameters
+        ----------
+        pixels_size : np.ndarray
+            The camera pixel size in the x and y directions (in mm).
+        working_dist : float
+            The working distance of the camera to the sample.
+        resolution : float
+            The desired resolution in mm/px.
+
+        Returns
+        -------
+        float
+            The focal length required to obtain the desired image resolution.
+        """
+        focal_length = working_dist / ((resolution / pixels_size[0]))
+        return focal_length
+
+    @staticmethod
+    def blender_camera_from_resolution(pixels_num: np.ndarray,
+                                    pixels_size: np.ndarray,
+                                    working_dist: float,
+                                    resolution: float) -> CameraData:
+        """A convenience function to create a camera object in Blender from its pixels,
+        the pixel size, the working distance and desired resolution.
+
+        Parameters
+        ----------
+        pixels_num : np.ndarray
+            The number of pixels in the camera, in the x and y directions.
+        pixels_size : np.ndarray
+            The camera pixels size in mm, in the x and y directions.
+        working_dist : float
+            The working distance of the camera.
+        resolution : float
+            The desired mm/px resolution
+
+        Returns
+        -------
+        CameraData
+            A dataclass containing the created camera's parameters.
+        """
+        focal_length = CameraTools.focal_length_from_resolution(pixels_size, working_dist, resolution)
+
+        cam_data = CameraData(pixels_num=pixels_num,
+                            pixels_size=pixels_size,
+                            pos_world=(0, 0, working_dist),
+                            rot_world=Rotation.from_euler("xyz", [0, 0, 0]),
+                            roi_cent_world=(0, 0, 0),
+                            focal_length=focal_length)
+        return cam_data
+
+    @staticmethod
+    def symmetric_stereo_cameras(cam_data_0: CameraData,
+                                stereo_angle:float) -> CameraStereo:
+        """A convenience function to set up a symmetric stereo camera system, given
+        an initial CameraData dataclass and a stereo angle. This assumes the basic
+        camera parameters are the same.
+
+        Parameters
+        ----------
+        cam_data_0 : CameraData
+            A dataclass containing the camera parameters for a single camera, which
+            will be camera 0.
+        stereo_angle : float
+            The stereo angle between the two cameras.
+
+        Returns
+        -------
+        CameraStereo
+            An instance of the CameraStereo class. This class contains
+            information about each of the cameras, as well as the extrinsic
+            parameters between them.
+        """
+        cam_data_1 = copy.deepcopy(cam_data_0)
+        base = 2 * cam_data_0.pos_world[2] * np.tan(np.radians(stereo_angle) / 2)
+
+        cam_data_0.pos_world[0] -= base / 2
+        cam_data_1.pos_world[0] += base / 2
+
+        cam_0_rot = (0, -np.radians(stereo_angle / 2), 0)
+        cam_0_rot = Rotation.from_euler("xyz", cam_0_rot, degrees=False)
+        cam_data_0.rot_world = cam_0_rot
+
+        cam_1_rot = (0, np.radians(stereo_angle / 2), 0)
+        cam_1_rot = Rotation.from_euler("xyz", cam_1_rot, degrees=False)
+        cam_data_1.rot_world = cam_1_rot
+
+        stereo_system = CameraStereo(cam_data_0, cam_data_1)
+
+        return stereo_system
+
+    @staticmethod
+    def faceon_stereo_cameras(cam_data_0: CameraData,
+                            stereo_angle: float) -> CameraStereo:
+        # TODO: Correct docstring
+        """A convenience function to set up a face-on stereo camera system, given
+        an initial CameraData dataclass and a stereo angle. This assumes the basic
+        camera parameters are the same.
+
+        Parameters
+        ----------
+        cam_data_0 : CameraData
+            A dataclass containing the camera parameters for a single camera, which
+            will be camera 0.
+        stereo_angle : float
+            The stereo angle between the two cameras.
+
+        Returns
+        -------
+        CameraStereo
+            An instance of the CameraStereo class. This class contains
+            information about each of the cameras, as well as the extrinsic
+            parameters between them.
+        """
+        cam_data_1 = copy.deepcopy(cam_data_0)
+        base = cam_data_0.pos_world[2] * np.tan(np.radians(stereo_angle))
+        cam_data_1.pos_world[0] += base
+
+        rotation_angle = (0, np.radians(stereo_angle), 0)
+        rotation_angle = Rotation.from_euler("xyz", rotation_angle, degrees=False)
+        cam_data_1.rot_world = rotation_angle
+
+        stereo_system = CameraStereo(cam_data_0, cam_data_1)
+
+        return stereo_system

pyvale/{core/cython → cython}/rastercyth.py

@@ -1,18 +1,22 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
 """
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
+NOTE: this module is a feature under developement.
 """
+
 import numpy as np
 import cython
 from cython.parallel import prange, parallel, threadid
 from cython.cimports.libc.math import floor, ceil
 
-from pyvale.core.rendermesh import RenderMeshData
-from pyvale.core.cameradata import CameraData
+from pyvale.rendermesh import RenderMeshData
+from pyvale.cameradata import CameraData
 
+# NOTE: This module is a feature under developement.
 
 @cython.nogil
 @cython.cfunc # python+C or cython.cfunc for C only

pyvale/data/__init__.py

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