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

pyvale/examples/renderblender/ex3_1_blendercalibration.py

@@ -4,117 +4,172 @@
 # Copyright (C) 2025 The Computer Aided Validation Team
 # ==============================================================================
 
+"""
+Blender example: Rendering calibration images
+---------------------------------------------
+
+This example takes you through how to render calibration images for a given DIC
+setup.
+"""
 import numpy as np
 from scipy.spatial.transform import Rotation
 from pathlib import Path
 import pyvale
 
-def main() -> None:
-    #NOTE: All lengths are to be specified in mm
-
-    # Set the save path
-    # --------------------------------------------------------------------------
-    # All the files saved will be saved to a subfolder within this specified
-    # base directory.
-    # This base directory can be specified by:
-    base_dir = Path("./")
-    # If no base directory is specified, it will be set as your home directory
-
-    # Creating the scene
-    # --------------------------------------------------------------------------
-    scene = pyvale.BlenderScene()
-
-    # Add the calibration target
-    # A rectangular calibration target of the specified size is added to the scene
-    target = scene.add_cal_target(target_size=np.array([150, 100, 10]))
-
-    # Add the camera
-    cam_data_0 = pyvale.CameraData(pixels_num=np.array([1540, 1040]),
-                                 pixels_size=np.array([0.00345, 0.00345]),
-                                 pos_world=np.array([0, 0, 400]),
-                                 rot_world=Rotation.from_euler("xyz", [0, 0, 0]),
-                                 roi_cent_world=(0, 0, 0),
-                                 focal_length=15.0)
-    # Set this to "symmetric" to get a symmetric stereo system or set this to
-    # "faceon" to get a face-on stereo system
-    stereo_setup = "faceon"
-    if stereo_setup == "symmetric":
-        stereo_system = pyvale.CameraTools.symmetric_stereo_cameras(
-            cam_data_0=cam_data_0,
-            stereo_angle=15.0)
-    if stereo_setup == "faceon":
-        stereo_system = pyvale.CameraTools.faceon_stereo_cameras(
-            cam_data_0=cam_data_0,
-            stereo_angle=15.0)
-
-    scene.add_stereo_system(stereo_system)
-
-    # Generate calibration file
-    stereo_system.save_calibration(base_dir)
-
-    # Add the light
-    light_data = pyvale.BlenderLightData(type=pyvale.BlenderLightType.POINT,
-                                         pos_world=(0, 0, 200),
-                                         rot_world=Rotation.from_euler("xyz",
-                                                                       [0, 0, 0]),
-                                         energy=1)
-    light = scene.add_light(light_data)
-    # The light can be moved and rotated:
-    light.location = (0, 0, 210)
-    light.rotation_euler = (0, 0, 0) # NOTE: The default is an XYZ Euler angle
-
-    # Apply the calibration target pattern
-    material_data = pyvale.BlenderMaterialData()
-    speckle_path = Path.cwd() / "src/pyvale/data/cal_target.tiff"
-    mm_px_resolution = pyvale.CameraTools.calculate_mm_px_resolution(cam_data_0)
-    scene.add_speckle(part=target,
-                                    speckle_path=speckle_path,
-                                    mat_data=material_data,
-                                    mm_px_resolution=mm_px_resolution,
-                                    cal=True)
-    # NOTE: The `cal` flag has to be set to True in order to scale the
-    # calibration target pattern correctly
-
-    # Rendering calibration images
-    # --------------------------------------------------------------------------
-    save_dir = Path.cwd() / "blenderimages"
-    save_name = "cal"
-    render_data = pyvale.RenderData(cam_data=(stereo_system.cam_data_0,
-                                              stereo_system.cam_data_1),
-                                    base_dir=base_dir)
-    # NOTE: The number of threads used to render the images is set within
-    # RenderData, it is defaulted to 4 threads
-
-    # The desired limits for the calibration target movement are to be set within
-    # the CalibrationData dataclass
-    calibration_data = pyvale.CalibrationData(angle_lims=(-10, 10),
-                                              angle_step=5,
-                                              plunge_lims=(-5, 5),
-                                              plunge_step=5)
-
-    # The number of calibration images that will be rendered can be calculated
-    number_calibration_images = pyvale.BlenderTools.number_calibration_images(calibration_data)
-    print()
-    print(80*"-")
-    print("Number of calibration images to be rendered:", number_calibration_images)
-    print(80*"-")
-
-    # The calibration images can then be rendered
-    pyvale.BlenderTools.render_calibration_images(render_data,
-                                                  calibration_data,
-                                                  target)
-
-    print()
-    print(80*"-")
-    print("Save directory of the images:", (render_data.base_dir / "calimages"))
-    print(80*"-")
-    print()
-
-    # Save Blender file
-    # --------------------------------------------------------------------------
-    # The file that will be saved is a Blender project file. This can be opened
-    # with the Blender GUI to view the scene.
-    pyvale.BlenderTools.save_blender_file(base_dir)
-
-if __name__ == "__main__":
-    main()
+# %%
+# Firstly, a save path must be set.
+# In order to do this a base path must be set. Then all the generated files will
+# be saved to a subfolder within this specified base directory
+# (e.g. blenderimages).
+# If no base directory is specified, it will be set as your home directory.
+
+base_dir = Path.cwd()
+
+# %%
+# Creating the scene
+# ^^^^^^^^^^^^^^^^^^
+# In order to create a DIC setup in Blender, first a scene must be created.
+# A scene is initialised using the `BlenderScene` class. All the subsequent
+# objects and actions necessary are then methods of this class.
+scene = pyvale.BlenderScene()
+
+# %%
+# The next thing to add to the scene is the calibration target.
+# This is done by specifing the size of calibration target to add to the scene
+# by passing in an array of (width, height, depth).
+# The calibration target being simulated here is 12 x 9 with 10 mm spacing.
+
+target = scene.add_cal_target(target_size=np.array([150, 100, 10]))
+
+# %%
+# The cameras can then be initialised. A stereo camera system is defined by a
+# `CameraStereo` object, which contains the intrinsic parameters of both cameras
+# as well as the extrinsic parameters between them.
+# There are two ways to initialise a `CameraStereo` object.
+# One way is to specify the camera parameters separately for each camera, create
+# a `CameraStereo` object, and then add the stereo system using the
+# `add_stereo_system` method.
+# The other method is to use a convenience function, as shown below.
+# This requires you to first initialise one camera. Then you can choose between
+# either a face-on or symmetric stereo system. Then, either of the
+# `symmetric_stereo_cameras` or `faceon_stereo_cameras` functions can be used to
+# initialise a `CameraStereo` object. The only input required to these functions
+# are the camera parameters for the first camera, and the desired stereo angle
+# between the two. The cameras can then be added to the Blender scene using the
+# `add_stereo_system` method.
+cam_data_0 = pyvale.CameraData(pixels_num=np.array([1540, 1040]),
+                               pixels_size=np.array([0.00345, 0.00345]),
+                               pos_world=np.array([0, 0, 400]),
+                               rot_world=Rotation.from_euler("xyz", [0, 0, 0]),
+                               roi_cent_world=(0, 0, 0),
+                               focal_length=15.0)
+# Set this to "symmetric" to get a symmetric stereo system or set this to
+# "faceon" to get a face-on stereo system
+stereo_setup = "faceon"
+if stereo_setup == "symmetric":
+    stereo_system = pyvale.CameraTools.symmetric_stereo_cameras(
+        cam_data_0=cam_data_0,
+        stereo_angle=15.0)
+if stereo_setup == "faceon":
+    stereo_system = pyvale.CameraTools.faceon_stereo_cameras(
+        cam_data_0=cam_data_0,
+        stereo_angle=15.0)
+scene.add_stereo_system(stereo_system)
+
+# %%
+# Since this scene contains a stereo DIC system, a calibration file will be
+# required to run the images through a DIC engine.
+# A calibration file can be generated directly from the `CameraStereo` object.
+# The calibration file will be saved in `YAML` format. However, if you wish to
+# use MatchID to process the images, `save_calibration_mid` can be used instead
+# to save the calibration in a format readable by MatchID.
+# The calibration file will be saved to a sub-directory of the base directory
+# called "calibration".
+# This calibration file with "perfect" parameters can be used as a comparitive
+# benchmark to the calibration gained from running the calibration files through
+# a DIC engine.
+stereo_system.save_calibration(base_dir)
+
+# %%
+# A light can the be added to the scene.
+# Blender offers different light types: Point, Sun, Spot and Area.
+# The light can also be moved and rotated like the camera.
+
+light_data = pyvale.BlenderLightData(type=pyvale.BlenderLightType.POINT,
+                                     pos_world=(0, 0, 200),
+                                     rot_world=Rotation.from_euler("xyz",
+                                                                  [0, 0, 0]),
+                                     energy=1)
+light = scene.add_light(light_data)
+light.location = (0, 0, 210)
+light.rotation_euler = (0, 0, 0) # NOTE: The default is an XYZ Euler angle
+
+# %%
+# The calibration target pattern can then be added to the calibration target
+# object.
+# This is added in the same way that a speckle pattern is added to a sample.
+# However, it is important to set the `cal` flag to True, as this means that the
+# calibration target pattern will not be scaled in the same way as a speckle
+# pattern.
+
+material_data = pyvale.BlenderMaterialData()
+speckle_path = Path.cwd() / "src/pyvale/data/cal_target.tiff"
+mm_px_resolution = pyvale.CameraTools.calculate_mm_px_resolution(cam_data_0)
+scene.add_speckle(part=target,
+                  speckle_path=speckle_path,
+                  mat_data=material_data,
+                  mm_px_resolution=mm_px_resolution,
+                  cal=True)
+
+# %%
+# Rendering a set of images
+# ^^^^^^^^^^^^^^^^^^^^^^^^^
+# Once all the objects have been added to the scene, a set of images can be
+# rendered.Firstly, all the rendering parameters must be set, including
+# parameters such as the number of threads to use.
+
+render_data = pyvale.RenderData(cam_data=(stereo_system.cam_data_0,
+                                            stereo_system.cam_data_1),
+                                base_dir=base_dir)
+
+# %%
+# The parameters for the calibration target's movement can then be set. This is
+# done by setting the minimum and maximum angle and plunge limits, as well as
+# the step value that they should be increased by. The x and y limit of the
+# calibration target's movement (from the origin) can also be set if you wish to
+# perform a calibration for a constrained optical setup. If these limits are not
+# passed in they will be initialised from the FOV to cover the whole FOV of the
+# cameras.
+
+calibration_data = pyvale.CalibrationData(angle_lims=(-10, 10),
+                                          angle_step=5,
+                                          plunge_lims=(-5, 5),
+                                          plunge_step=5)
+
+# %%
+# It is then possible to check the number of calibration images that will be
+# rendered before rendering them. The only input that is needed is the
+# `calibration_data` specified above.
+
+number_calibration_images = pyvale.BlenderTools.number_calibration_images(calibration_data)
+print("Number of calibration images to be rendered:", number_calibration_images)
+
+# %%
+# The calibration images can then be rendered. This function will move the
+# calibration target according to movement limits set above, and will also move
+# the target rigidly across the FOV of the camera, in order to characterise the
+# entire FOV of the cameras.
+pyvale.BlenderTools.render_calibration_images(render_data,
+                                              calibration_data,
+                                              target)
+
+# %%
+# The rendered images will be saved to this filepath:
+
+print("Save directory of the images:", (render_data.base_dir / "calimages"))
+
+# %%
+# There is also the option to save the scene as a Blender project file.
+# This file can be opened with the Blender GUI to view the scene.
+
+pyvale.BlenderTools.save_blender_file(base_dir)

pyvale/examples/renderrasterisation/ex_rastenp.py

@@ -5,6 +5,7 @@
 # ==============================================================================
 
 from pathlib import Path
+import copy
 import time
 import numpy as np
 from scipy.spatial.transform import Rotation
@@ -27,21 +28,20 @@ import pyvale as pyv
 
 
 def main() -> None:
-    """pyvale example: rasterisation field renderer
+    """Basics rasterisation field renderer
     ----------------------------------------------------------------------------
-    - TODO
     """
     # This a path to an exodus *.e output file from MOOSE, this can be
     # replaced with a path to your own simulation file
-    #sim_path = Path.home()/"pyvale"/"src"/"pyvale"/"simcases"/"case21_out.e"
-    sim_path = pyv.DataSet.render_mechanical_3d_path()
+    sim_path = Path.home()/"pyvale"/"src"/"pyvale"/"simcases"/"case21_out.e"
+    #sim_path = pyv.DataSet.render_mechanical_3d_path()
 
     disp_comps = ("disp_x","disp_y","disp_z")
 
     sim_data = mh.ExodusReader(sim_path).read_all_sim_data()
 
     # Scale m -> mm
-    sim_data = pyv.scale_length_units(sim_data,disp_comps,1000.0)
+    sim_data = pyv.scale_length_units(1000.0,sim_data,disp_comps)
 
     # Extracts the surface mesh from a full 3d simulation for rendering
     render_mesh = pyv.create_render_mesh(sim_data,
@@ -49,6 +49,18 @@ def main() -> None:
                                         sim_spat_dim=3,
                                         field_disp_keys=disp_comps)
 
+    #===========================================================================
+    # render_mesh.fields_render = render_mesh.fields_render[:,-2:-1,:]
+    # render_mesh.fields_disp = render_mesh.fields_disp[:,-2:-1,:]
+    # render_mesh.fields_disp = None
+    #===========================================================================
+
+    meshes = [render_mesh,copy.deepcopy(render_mesh)]
+    meshes[1].set_pos(np.array((0.0,12.5,0.0)))
+    meshes[1].set_rot(Rotation.from_euler("zyx",(0.0, 0.0, 0.0),degrees=True))
+    meshes[1].fields_disp = None
+    coords_all = pyv.get_all_coords_world(meshes)
+
     print()
     print(80*"-")
     print("MESH DATA:")
@@ -66,16 +78,15 @@ def main() -> None:
     print(80*"-")
     print()
 
-
     pixel_num = np.array((960,1280))
     pixel_size = np.array((5.3e-3,5.3e-3))
     focal_leng: float = 50
-    cam_rot = Rotation.from_euler("zyx",(0.0,-30.0,-10.0),degrees=True)
-    fov_scale_factor: float = 1.1
+    cam_rot = Rotation.from_euler("zyx",(0.0, 0.0, -30.0),degrees=True)
+    fov_scale_factor: float = 1.0
 
     (roi_pos_world,
-     cam_pos_world) = pyv.CameraTools.pos_fill_frame_from_rotation(
-         coords_world=render_mesh.coords,
+     cam_pos_world) = pyv.CameraTools.pos_fill_frame(
+         coords_world=coords_all,
          pixel_num=pixel_num,
          pixel_size=pixel_size,
          focal_leng=focal_leng,
@@ -103,51 +114,79 @@ def main() -> None:
     print("World to camera matrix:")
     print(cam_data.world_to_cam_mat)
     print(80*"-")
-    print()
+
+    scene = pyv.RenderScene([cam_data,cam_data],meshes)
+
+    frames_per_camera = (scene.meshes[0].fields_render.shape[1]
+                        *scene.meshes[0].fields_render.shape[2])
+    frames_total = frames_per_camera*len(scene.cameras)
 
     print(80*"-")
-    total_frames = render_mesh.fields_render.shape[1]*render_mesh.fields_render.shape[2]
-    print(f"Time steps to render: {render_mesh.fields_render.shape[1]}")
-    print(f"Fields to render: {render_mesh.fields_render.shape[2]}")
-    print(f"Total frames to render: {total_frames}")
+    print("RENDER SCENE:")
+    print(f"Cameras #: {len(scene.cameras)}")
+    print(f"Meshes #:  {len(scene.meshes)}")
+    print()
+    print(f"Time steps: {scene.meshes[0].fields_render.shape[1]}")
+    print(f"Field #:    {scene.meshes[0].fields_render.shape[2]}")
+    print()
+    print(f"Frames per camera: {frames_per_camera}")
+    print(f"Frames total:      {frames_total}")
     print(80*"-")
 
+
+    #===========================================================================
     print()
     print(80*"=")
-    print("RASTER LOOP START")
+    print("IN MEM: Raster Loop start")
 
-    #save_path = Path.cwd()/"example_output"
-    save_path = None
-    static_mesh = False
+    raster_opts = pyv.RasterOpts(parallel=8)
+    renderer = pyv.RasterNumpy(raster_opts)
 
     time_start_loop = time.perf_counter()
-    if static_mesh:
-        images = pyv.RasterNP.raster_static_mesh(
-            cam_data,render_mesh,save_path,threads_num=8
-        )
-    else:
-        time_start_loop = time.perf_counter()
-        images = pyv.RasterNP.raster_deformed_mesh(
-            cam_data,render_mesh,save_path,parallel=8
-        )
+
+    images = renderer.render_all(scene)
 
     time_end_loop = time.perf_counter()
-    render_time = time_end_loop - time_start_loop
+    time_inmem = time_end_loop - time_start_loop
+
+    print(f"{images[0].shape=}")
+    print(f"{images[1].shape=}")
+    print("IN MEM: Raster Loop End")
+    print(80*"=")
 
 
-    print("RASTER LOOP END")
     print(80*"=")
+    print("TO DISK: Raster Loop start")
+    save_path = Path.cwd()/"pyvale-output"
+    if not save_path.is_dir():
+        save_path.mkdir(parents=True, exist_ok=True)
+
+    time_start_loop = time.perf_counter()
+
+    renderer.render_all_to_disk(scene,save_path)
+
+    time_end_loop = time.perf_counter()
+    time_to_disk = time_end_loop - time_start_loop
+
+    print("TO DISK: Raster Loop End")
+    print(80*"=")
+
+
     print("PERFORMANCE")
-    print(f"Total frames = {total_frames}")
-    print(f"Total render time = {render_time:.4f} seconds")
-    print(f"Time per frame = {(render_time/total_frames):.4f} seconds")
+    print(f"Total frames = {frames_total}")
+    print(f"IN MEM: Total render time = {time_inmem:.4f} s")
+    print(f"IN MEM: Time per frame = {(time_inmem/frames_total):.4f} s")
+    print(f"TO DISK: Total render time = {time_to_disk:.4f} s")
+    print(f"TO DISK: Time per frame = {(time_to_disk/frames_total):.4f} s")
     print(80*"=")
 
+
     plot_on = True
     if plot_on:
-        (fig,ax) = pyv.plot_field_image(images[:,:,-1,0],
+        (fig,ax) = pyv.plot_field_image(images[1][:,:,-1,0],
                                         title_str="Disp. y, [mm]")
-        plt.show()
+
+    plt.show()
 
 if __name__ == "__main__":
     main()

pyvale/examples/renderrasterisation/ex_rastercyth_oneframe.py

@@ -13,10 +13,6 @@ import pyvale as pyv
 import imagebenchmarks as ib
 
 def main() -> None:
-    """pyvale example: rasterisation field renderer
-    ----------------------------------------------------------------------------
-    - TODO
-    """
     print()
     print(80*"=")
     print("RASTER CYTHON FILE (should be *.so on Linux):")
@@ -24,23 +20,20 @@ def main() -> None:
     print(80*"=")
     print()
 
-    return
-
-    benchmark = True
+    benchmark = False
     if not benchmark:
-
         # This a path to an exodus *.e output file from MOOSE, this can be
         # replaced with a path to your own simulation file
         #sim_path = Path.home()/"pyvale"/"src"/"pyvale"/"simcases"/"case26_out.e"
 
         sim_path = pyv.DataSet.render_simple_block_path()
-        sim_path = pyv.DataSet.render_mechanical_3d_path()
+        #sim_path = pyv.DataSet.render_mechanical_3d_path()
         sim_data = mh.ExodusReader(sim_path).read_all_sim_data()
 
         disp_comps = ("disp_x","disp_y","disp_z")
 
         # Scale m -> mm
-        sim_data = pyv.scale_length_units(sim_data,disp_comps,1000.0)
+        sim_data = pyv.scale_length_units(1000.0,sim_data,disp_comps)
 
         print()
         print(f"{np.max(np.abs(sim_data.node_vars['disp_x']))=}")
@@ -65,7 +58,7 @@ def main() -> None:
         fov_scale_factor: float = 1.1
 
         (roi_pos_world,
-        cam_pos_world) = pyv.CameraTools.pos_fill_frame_from_rotation(
+        cam_pos_world) = pyv.CameraTools.pos_fill_frame(
             coords_world=render_mesh.coords,
             pixel_num=pixel_num,
             pixel_size=pixel_size,
@@ -151,7 +144,7 @@ def main() -> None:
 
         (image_buffer,
          depth_buffer,
-         elems_in_image) = pyv.rastercyth.raster_frame(
+         elems_in_image) = pyv.rastercyth.raster_static_frame(
                                                 render_mesh.coords,
                                                 render_mesh.connectivity,
                                                 fields_render,
@@ -171,7 +164,7 @@ def main() -> None:
 
     #===========================================================================
     # PLOTTING
-    plot_on = True
+    plot_on = False
     plot_field = 0
 
     # depth_to_plot = np.copy(np.asarray(depth_buffer[:,:,plot_frame]))

pyvale/examples/renderrasterisation/ex_rastercyth_static_cypara.py

@@ -28,7 +28,7 @@ def main() -> None:
     disp_comps = ("disp_x","disp_y","disp_z")
 
     # Scale m -> mm
-    sim_data = pyv.scale_length_units(sim_data,disp_comps,1000.0)
+    sim_data = pyv.scale_length_units(1000.0,sim_data,disp_comps)
 
     print()
     print(f"{np.max(np.abs(sim_data.node_vars['disp_x']))=}")
@@ -66,7 +66,7 @@ def main() -> None:
     fov_scale_factor: float = 1.1
 
     (roi_pos_world,
-     cam_pos_world) = pyv.CameraTools.pos_fill_frame_from_rotation(
+     cam_pos_world) = pyv.CameraTools.pos_fill_frame(
          coords_world=render_mesh.coords,
          pixel_num=pixel_num,
          pixel_size=pixel_size,

pyvale/examples/renderrasterisation/ex_rastercyth_static_pypara.py

@@ -4,8 +4,6 @@
 # Copyright (C) 2025 The Computer Aided Validation Team
 # ==============================================================================
 
-
-
 import time
 import numpy as np
 from scipy.spatial.transform import Rotation
@@ -32,7 +30,7 @@ def main() -> None:
     disp_comps = ("disp_x","disp_y","disp_z")
 
     # Scale m -> mm
-    sim_data = pyv.scale_length_units(sim_data,disp_comps,1000.0)
+    sim_data = pyv.scale_length_units(1000.0,sim_data,disp_comps)
 
     print()
     print(f"{np.max(np.abs(sim_data.node_vars['disp_x']))=}")
@@ -70,7 +68,7 @@ def main() -> None:
     fov_scale_factor: float = 1.1
 
     (roi_pos_world,
-     cam_pos_world) = pyv.CameraTools.pos_fill_frame_from_rotation(
+     cam_pos_world) = pyv.CameraTools.pos_fill_frame(
          coords_world=render_mesh.coords,
          pixel_num=pixel_num,
          pixel_size=pixel_size,

pyvale/imagedef2d.py

@@ -20,6 +20,7 @@ from scipy import ndimage
 from pyvale.rasternp import edge_function, RasterNP
 from pyvale.cameradata2d import CameraData2D
 from pyvale.cameratools import CameraTools
+from pyvale.imagetools import ImageTools
 
 
 @dataclass(slots=True)
@@ -436,9 +437,9 @@ class ImageDef2D:
                                             print_on=print_on)
 
             save_file = id_opts.save_path / str(f'{id_opts.save_tag}_'+
-                    f'{CameraTools.image_num_str(im_num=ff,width=4)}'+
+                    f'{ImageTools.get_num_str(im_num=ff,width=4)}'+
                     '.tiff')
-            CameraTools.save_image(save_file,def_image,cam_data.bits)
+            ImageTools.save_tiff(save_file,def_image,cam_data.bits)
 
             if print_on:
                 tocf = time.perf_counter()