pyvale 2025.4.1__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/cameratools.py

@@ -1,23 +1,28 @@
-# ================================================================================
+# ==============================================================================
 # 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.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:
 
@@ -55,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)
@@ -71,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]:
@@ -91,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]:
@@ -115,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,
@@ -148,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,
@@ -210,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,
@@ -324,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/cython/rastercyth.py

@@ -1,8 +1,12 @@
-# ================================================================================
+# ==============================================================================
 # 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

pyvale/dataset.py

@@ -4,39 +4,63 @@
 # Copyright (C) 2025 The Computer Aided Validation Team
 #===============================================================================
 
+"""
+Accesors for data that comes pre-packaged with pyvale for demonstrating its
+functionality. This includes moose simulation outputs as exodus files, input
+files for moose and gmsh for additional simulation cases, and images required
+for testing the image deformation and digital image correlation modules.
+"""
+
 from enum import Enum
 from pathlib import Path
 from importlib.resources import files
 
 
+SIM_CASE_COUNT = 26
+"""Constant describing the number of simulation test case input files for moose
+and gmsh that come packaged with pyvale.
+"""
+
 class EElemTest(Enum):
+    """Enumeration used to specify different 3D element types for extracting
+    specific test simulation datasets.
+    """
+
     TET4 = "TET4"
+    """Tetrahedral element, linear with 4 nodes.
+    """
+
     TET10 = "TET10"
+    """Tetrahedral element, quadratic with 10 nodes.
+    """
+
     TET14 = "TET14"
+    """Tetrahedral element, quadratic with 14 nodes.
+    """
+
     HEX8 = "HEX8"
+    """Hexahedral element, linear with 8 nodes.
+    """
+
     HEX20 = "HEX20"
+    """Hexahedral element, quadratic with 20 nodes.
+    """
+
     HEX27 = "HEX27"
+    """Hexahedral element, quadratic with 27 nodes.
+    """
 
     def __str__(self):
         return self.value
 
 
-SIM_CASE_COUNT = 26
-
-
 class DataSetError(Exception):
     """Custom error class for file io errors associated with retrieving datasets
     and files packaged with pyvale.
     """
-    pass
 
 
 class DataSet:
-    """A static namespace class for handling datasets packaged with pyvale.
-    Contains a series of static methods returning a Path object to each data
-    file that is packaged with pyvale.
-    """
-
     @staticmethod
     def sim_case_input_file_path(case_num: int) -> Path:
         """Gets the path to MOOSE input file (*.i) for a particular simulation
@@ -62,7 +86,7 @@ class DataSet:
             raise DataSetError("Simulation case number must be greater than 0")
         elif case_num > SIM_CASE_COUNT:
             raise DataSetError("Simulation case number must be less than " \
-                               + f"{SIM_CASE_COUNT}")
+                                + f"{SIM_CASE_COUNT}")
 
         case_num_str = str(case_num).zfill(2)
         case_file = f"case{case_num_str}.i"
@@ -97,7 +121,7 @@ class DataSet:
             raise DataSetError("Simulation case number must be greater than 0")
         elif case_num > SIM_CASE_COUNT:
             raise DataSetError("Simulation case number must be less than " \
-                               + f"{SIM_CASE_COUNT}")
+                                + f"{SIM_CASE_COUNT}")
 
         case_num_str = str(case_num).zfill(2)
         case_file = f"case{case_num_str}.geo"
@@ -248,19 +272,54 @@ class DataSet:
 
     @staticmethod
     def render_mechanical_3d_path() -> Path:
-        """_summary_
+        """Path to a MOOSE simulation output in exodus format. This case is a
+        purely mechanical test case in 3D meant for testing image rendering
+        algorithms for digital image correlation simulation. The simulation
+        consists of a linear elastic thin plate with a hole loaded in tension.
+        The simulation uses linear tetrahedral elements for rendering tests.
 
         Returns
         -------
         Path
-            _description_
+            Path to the exodus (*.e) output file for this simulation case.
         """
         return Path(files("pyvale.data").joinpath("case26_out.e"))
 
     @staticmethod
     def render_simple_block_path() -> Path:
+        """Path to a MOOSE simulation output in exodus format. This case is a
+        a simple rectangular block in 3D loaded in tension. It uses a minimum
+        number of elements and is intended purely for testing image rendering
+        algorithms. This simulation uses linear tetrahedral elements.
+
+        Returns
+        -------
+        Path
+            Path to the exodus (*.e) output file for this simulation case.
+        """
         return Path(files("pyvale.data").joinpath("case25_out.e"))
 
     @staticmethod
     def element_case_path(elem_type: EElemTest) -> Path:
-        return Path(files("pyvale.data").joinpath(f"case00_{elem_type.value}_out.e"))
+        """Path to a MOOSE simulation output in exodus format. This case is a
+        10mm cube undergoing thermo-mechanical loading solved for the
+        temperature displacement and strain fields. This case is solved using a
+        variety of tetrahedral and hexahedral elements with linear or quadratic
+        shapes functions. These simulation cases are intended for testing
+        purposes and contain a minimal number of elements.
+
+        Parameters
+        ----------
+        elem_type : EElemTest
+            Enumeration specifying the element type for this test case.
+
+        Returns
+        -------
+        Path
+            Path to the exodus (*.e) output file for this simulation case.
+        """
+        return Path(files("pyvale.data")
+                    .joinpath(f"case00_{elem_type.value}_out.e"))
+
+
+