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

pyvale/examples/dic/ex2_plate_with_hole.py

@@ -0,0 +1,149 @@
+#================================================================================
+#Example: thermocouples on a 2d plate
+#
+#pyvale: the python validation engine
+#License: MIT
+#Copyright (C) 2024 The Computer Aided Validation Team
+#================================================================================
+"""
+2D Plate with a Hole
+---------------------
+
+This example walks through setting up a DIC and strain calculation for the
+classic "plate with a hole" problem. The images used are synthetically generated,
+allowing for comparison to analytically known values.
+"""
+
+import matplotlib.pyplot as plt
+from pathlib import Path
+import pyvale
+
+# %%
+# We'll start by defining some variables that will be reused throughout the example:
+# the reference image, deformed image(s), and the subset size.
+# 
+# If you're working with a series of deformed images, it's a good idea to place
+# them in a separate folder or ensure they follow a consistent naming convention.
+# In such cases, the wildcard operator `*` can be used to select multiple files.
+#
+# The images used here are included in the `data <https://github.com/Computer-Aided-Validation-Laboratory/pyvale/tree/main/src/pyvale/data>`_ folder.
+# We've provided helper functions to load them regardless of your installation path.
+subset_size = 31
+ref_img = pyvale.DataSet.dic_plate_with_hole_ref()
+def_img = pyvale.DataSet.dic_plate_with_hole_def()
+
+# create a directory for the the different outputs
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+# %%
+# Next, we’ll select our Region of Interest (ROI) using the interactive tool.
+# Create an instance of the ROI class and pass the reference image
+# as input. This image will be shown as the underlay during any ROI selection or
+# visualization.
+roi = pyvale.DICRegionOfInterest(ref_img)
+roi.interactive_selection(subset_size)
+
+# %%
+# Once you've closed the ROI interactive window, a mask and seed location coordinates
+# will be generated. These are needed for the DIC engine.
+#
+# If you intend to reuse this ROI, it's a good idea to save it. For large images,
+# setting `binary=True` is recommended to reduce file size and write time.
+roi_file = output_path / "roi.dat"
+roi.save_array(filename=roi_file, binary=False)
+
+# %%
+# To load a previously saved ROI for future use, use the `read_array` method.
+# Make sure the filename and format (binary or human-readable) match what was saved.
+roi.read_array(filename=roi_file, binary=False)
+
+# %%
+# Now we can run the 2D DIC engine using :func:`pyvale.dic_2d`.
+#
+# This function accepts many optional arguments — consult the documentation for full details.
+# At a minimum, you’ll need to specify:
+#
+# - Reference image
+# - Deformed image(s)
+# - ROI mask
+# - Seed coordinates (If using a Reliability Guided approach)
+# - Subset size
+#
+# By default, the engine uses an affine shape function with the Zero Normalised
+# Sum of Squared Differences (ZNSSD) correlation criterion.
+#
+# At present, the DIC engine doesn't return any results to the user, instead the results are saved to disk.
+# You can customize the filename, location, format, and delimiter using 
+# the options options `output_basepath`, `output_prefix`, `output_delimiter`, and `output_binary`.
+# More info on these options can be found in the documentation for :func:`pyvale.dic_2d`.
+# By default, the results will be saved with the prefix `dic_results_` followed
+# by the original filename. The file extension will be replaced will either ".csv" or "dic2d"
+# depending on whether the results are being saved in human-readable or binary format.
+pyvale.dic_2d(reference=ref_img,
+              deformed=def_img,
+              roi_mask=roi.mask,
+              seed=roi.seed,
+              subset_size=subset_size,
+              subset_step=10,
+              shape_function="AFFINE",
+              max_displacement=10,
+              correlation_criteria="ZNSSD",
+              output_basepath=output_path,
+              output_delimiter=",",
+              output_prefix="dic_results_")
+
+# %%
+# If you saved the results in a human-readable format, you can use any tool
+# (e.g., Excel, Python, MATLAB) for post-processing.
+#
+# For convenience, we provide a utility function to import results back into Python
+# for analysis and visualization: :func:`pyvale.dic_data_import`.
+#
+# The returned object is an instance of :class:`pyvale.DICResults`. If the results
+# were saved in binary format or with a custom delimiter, be sure to specify those parameters.
+dic_files = output_path / "dic_results_*.csv"
+dicdata = pyvale.dic_data_import(data=dic_files, delimiter=",", binary=False)
+
+# %%
+# As an example, here's a simple visualization of the displacement (u, v) and
+# correlation cost for the two deformed images using matplotlib. You'll need to 
+# ensure you have `matplotlib.pyplot` installed and imported.
+fig, axes = plt.subplots(2, 3, figsize=(15, 5))
+axes = axes.flatten()
+
+# First deformation image
+im1 = axes[0].pcolor(dicdata.ss_x, dicdata.ss_y, dicdata.u[0])
+im2 = axes[1].pcolor(dicdata.ss_x, dicdata.ss_y, dicdata.v[0])
+im3 = axes[2].pcolor(dicdata.ss_x, dicdata.ss_y, dicdata.cost[0])
+
+# Second deformation image
+im4 = axes[3].pcolor(dicdata.ss_x, dicdata.ss_y, dicdata.u[1])
+im5 = axes[4].pcolor(dicdata.ss_x, dicdata.ss_y, dicdata.v[1])
+im6 = axes[5].pcolor(dicdata.ss_x, dicdata.ss_y, dicdata.cost[1])
+
+# Titles
+axes[0].set_title('u component (def0000.tiff)')
+axes[1].set_title('v component (def0000.tiff)')
+axes[2].set_title('cost (def0000.tiff)')
+axes[3].set_title('u component (def0001.tiff)')
+axes[4].set_title('v component (def0001.tiff)')
+axes[5].set_title('cost (def0001.tiff)')
+
+# Colorbars
+fig.colorbar(im1, ax=axes[0])
+fig.colorbar(im2, ax=axes[1])
+fig.colorbar(im3, ax=axes[2])
+fig.colorbar(im4, ax=axes[3])
+fig.colorbar(im5, ax=axes[4])
+fig.colorbar(im6, ax=axes[5])
+
+plt.tight_layout()
+plt.show()
+
+# %%
+# .. image:: ../../../../_static/plate_with_hole.png
+#    :alt: Displacement and cost values
+#    :width: 800px
+#    :align: center

pyvale/examples/dic/ex3_plate_with_hole_strain.py

@@ -0,0 +1,93 @@
+# ================================================================================
+# Example: DIC Challenge 2.0 Comparison
+# 
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2024 The Computer Aided Validation Team
+# ================================================================================
+
+"""
+Strain and Deformation Gradient Calculations
+---------------------------------------------
+
+This example follows on from the previous one. It assumes that the DIC results
+have already been generated in the current working directory and are ready to
+be used for strain calculations.
+"""
+
+import matplotlib.pyplot as plt
+from pathlib import Path
+import pyvale
+
+# %%
+# We'll start by importing the DIC data from the previous example.
+
+# create a directory for the the different outputs
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+# specify where our input data is
+input_data = output_path / "dic_results_*.csv"
+
+# %%
+# You can calculate strain directly from the DIC results.
+# It's not necessary to load the data beforehand — you can simply pass the
+# filename (or pattern) to the `data` argument. If you used a custom delimiter
+# or saved in binary format, make sure to specify those as well.
+
+# %%
+# At a minimum, you need to specify the strain window size and the element type
+# used within the window. The valid options for `window_element` are:
+#
+# - `4` for bilinear
+# - `9` for biquadratic
+#
+# The output will always include the window coordinates and the full deformation
+# gradient tensor. If you also specify a `strain_formulation`, the corresponding
+# 2D strain tensor will be included in the output.
+pyvale.strain_2d(data=input_data, window_size=5, window_element=4,
+                 output_basepath=output_path)
+
+# %%
+# Once the strain calculation is complete, you can import the results using
+# :func:`pyvale.strain_data_import`.
+#
+# Be sure to specify the delimiter, format (binary or not), and layout.
+strain_output = output_path / "strain_dic_results_*.csv"
+straindata = pyvale.strain_data_import(data=strain_output,
+                                       binary=False, delimiter=",",
+                                       layout="matrix")
+
+# %%
+# Here's a simple example of how to visualize the deformation gradient components
+# for the first deformation step using matplotlib.
+fig, axes = plt.subplots(2, 2, figsize=(15, 5))
+axes = axes.flatten()
+fig.suptitle('Deformation Gradient for ' + straindata.filenames[0])
+
+im1 = axes[0].pcolor(straindata.window_x, straindata.window_y, straindata.def_grad[0, :, :, 0, 0])
+im2 = axes[1].pcolor(straindata.window_x, straindata.window_y, straindata.def_grad[0, :, :, 0, 1])
+im3 = axes[2].pcolor(straindata.window_x, straindata.window_y, straindata.def_grad[0, :, :, 1, 0])
+im4 = axes[3].pcolor(straindata.window_x, straindata.window_y, straindata.def_grad[0, :, :, 1, 1])
+
+# titles
+axes[0].set_title('deformation gradient xx')
+axes[1].set_title('deformation gradient xy')
+axes[2].set_title('deformation gradient yx')
+axes[3].set_title('deformation gradient yy')
+
+# Colorbars
+fig.colorbar(im1, ax=axes[0])
+fig.colorbar(im2, ax=axes[1])
+fig.colorbar(im3, ax=axes[2])
+fig.colorbar(im4, ax=axes[3])
+
+plt.tight_layout()
+plt.show()
+
+# %%
+# .. image:: ../../../../_static/plate_with_hole_def_grad.png
+#    :alt: Displacement and cost values
+#    :width: 800px
+#    :align: center

pyvale/examples/dic/ex4_dic_blender.py

@@ -0,0 +1,95 @@
+#================================================================================
+#Example: DIC with images generated by blender
+#
+#pyvale: the python validation engine
+#License: MIT
+#Copyright (C) 2024 The Computer Aided Validation Team
+#================================================================================
+
+"""
+DIC with images generated from a virtual blender experiment 
+---------------------------------------------
+
+This example looks at taking the virtual experiments conducted using the blender
+module and taking it one step further and performing a DIC calculation on the
+simulated data. For this to work, you'll need to complete the `2D image
+deformation example <https://computer-aided-validation-laboratory.github.io/pyvale/examples/renderblender/ex1_2_blenderdeformed.html>`_ using the blender module first. 
+
+**We'd recommend downloading both examples (links can be
+found at the bottom of each example) and placing them within the same folder on 
+your device. That way the relative file paths below will not need to be
+changed.**
+"""
+
+import matplotlib.pyplot as plt
+from pathlib import Path
+import numpy as np
+import pyvale
+import os
+
+#subset size
+subset_size = 21
+
+# rename the reference image so that that we can distinguish between reference
+# and deformed images
+if os.path.exists("./blenderimages/blenderimage_0.tiff"):
+    os.rename("./blenderimages/blenderimage_0.tiff", 
+              "./blenderimages/reference.tiff")
+
+ref_img = "./blenderimages/reference.tiff"
+def_img = "./blenderimages/blenderimage_*.tiff"
+
+# Interactive ROI selection
+roi = pyvale.DICRegionOfInterest(ref_img)
+roi.interactive_selection(subset_size)
+
+#output_path
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+# DIC Calculation
+pyvale.dic_2d(reference=ref_img,
+              deformed=def_img,
+              roi_mask=roi.mask,
+              seed=roi.seed,
+              subset_size=subset_size,
+              subset_step=10,
+              shape_function="AFFINE",
+              max_displacement=20,
+              correlation_criteria="ZNSSD",
+              output_basepath=output_path,
+              output_prefix="blender_dic_")
+
+# Import the Results
+data_path = output_path / "blender_dic_*.csv"
+dicdata = pyvale.dic_data_import(data=data_path, delimiter=",",
+                                 layout='matrix', binary=False)
+
+# %%
+# As an example we can plot the v-component of displacement for each of the
+# eight deformation images
+
+# Setup plot
+fig, axes = plt.subplots(2, 4, figsize=(15, 5))
+axes = axes.flatten()
+
+# Compute global min and max for consistent color scaling
+vmin = np.nanmin(dicdata.v)
+vmax = np.nanmax(dicdata.v)
+print(vmin,vmax)
+
+# loop over images and add to subplots
+for i in range(len(dicdata.filenames)):
+    im = axes[i].pcolor(dicdata.ss_x, dicdata.ss_y, dicdata.v[i], vmin=vmin, vmax=vmax)
+    axes[i].set_title(dicdata.filenames[i])
+    fig.colorbar(im, ax=axes[i])
+
+plt.tight_layout()
+plt.show()
+
+# %%
+# .. image:: ../../../../_static/dic_blender_plot.png
+#    :alt: DIC Comparison with ground truth
+#    :width: 800px
+#    :align: center

pyvale/examples/dic/ex5_dic_challenge.py

@@ -0,0 +1,102 @@
+# ================================================================================
+# Example: DIC Challenge 2.0 Comparison
+# 
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2024 The Computer Aided Validation Team
+# ================================================================================
+
+"""
+Comparison to the 2.0 2D DIC Challenge
+---------------------------------------------
+
+The DIC challenge provides a framework for comparison and validation of existing
+DIC Codes. More information can be found at `https://idics.org/challenge/
+<https://idics.org/challenge/>`_. In this example we look at a comparison to a
+image generated with ±0.5 pixel sinusoidal vertical displacement amplitude “star” 
+pattern with varying spatial frequency. More information on the image creation
+can be found in the `original paper
+<https://link.springer.com/article/10.1007/s11340-021-00806-6>`_. In this
+example we'll look at the convergence to the peak vertical discplacement value
+of 0.5 pixels along a particular correlation direction. 
+
+As always, we'll start with importing the required libraries:
+"""
+
+import matplotlib.pyplot as plt
+from pathlib import Path
+import pyvale
+
+
+# %%
+# There's a pair of DIC challenge images that come as part of the Pyvale install. We can preload them with:
+ref_pattern = pyvale.DataSet.dic_challenge_ref()
+def_pattern = pyvale.DataSet.dic_challenge_def()
+subset_size = 17
+
+
+# %%
+# we need to select our region of interest. For this example, we are only
+# interested in the subsets along the mid horizontal line.
+# We can use :func:`roi.rect_boundary` to exclude a large border region so we
+# only correlate along the horizontal at the midpoint for our selected subset
+# size
+roi = pyvale.DICRegionOfInterest(ref_image=ref_pattern)
+subset_radius = subset_size // 2
+roi.rect_boundary(left=50,right=50,top=250-subset_radius,bottom=250-subset_radius)
+roi.show_image()
+
+# create a directory for the the different outputs
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+# %%
+# .. image:: ../../../../_static/dic_challenge_roi.png
+#    :alt: Selected roi
+#    :width: 800px
+#    :align: center 
+
+
+# %% 
+# To perform the correlation we need to select a seed point. Ideally, this is
+# somewhere in the region where the displacements are small with low noise. 
+# Here we'll select it to be [3500,250], which is close to the right hand
+# boundary where the spatial frequency is lower. The results will be saved in
+# the current working directory with a filename prefix of subset_size_19_*.txt
+# If you are feeling adventorous you could investigate the effect of varying the
+# subset size by placing the above and below sections in a loop.
+pyvale.dic_2d(reference=ref_pattern,
+              deformed=def_pattern,
+              roi_mask=roi.mask,
+              subset_size=subset_size,
+              subset_step=1,
+              seed=[3500,250],
+              max_displacement=10,
+              output_basepath=output_path)
+
+# %% 
+# We can import the results in the standard way
+data_path = output_path / "dic_results_DIC_Challenge*.csv"
+dicdata = pyvale.dic_data_import(data=data_path, layout='column', 
+                                 binary=False, delimiter=",")
+
+# &&
+# Finally a simple plot of the calculated displacements at y=2500. This could be
+# extended and compared to other DIC engines used in the 2.0 DIC challenge. A
+# link to the dataset can be found under '2D-DIC Challenge 2.0' can be found
+# at `https://idics.org/challenge/ <https://idics.org/challenge/>`_
+plt.figure()
+plt.xlabel("subset x location [px]")
+plt.ylabel("Displacement [px]")
+plt.grid(True)
+plt.axhline(y=0.5, color='red', linestyle='--', linewidth=4)
+plt.plot(dicdata.ss_x, dicdata.v[0,:])
+plt.tight_layout()
+plt.show()
+
+# %%
+# .. image:: ../../../../_static/dic_challenge_plot.png
+#    :alt: DIC Comparison with ground truth
+#    :width: 600px
+#    :align: center

pyvale/examples/imagedef2d/ex_imagedef2d_todisk.py

@@ -16,9 +16,11 @@ def main() -> None:
     sim_data = mh.ExodusReader(sim_path).read_all_sim_data()
 
     image_path = pyv.DataSet.dic_pattern_5mpx_path()
-    image_speckle = pyv.CameraTools.load_image(image_path)
+    image_speckle = pyv.ImageTools.load_image_greyscale(image_path)
 
-    save_path = Path.cwd()/"exampleoutput"
+    save_path = Path.cwd()/"pyvale-output"
+    if not save_path.is_dir():
+        save_path.mkdir(parents=True, exist_ok=True)
 
     coords = sim_data.coords
     connectivity = (sim_data.connect["connect1"]-1).T # Beware 0 indexing here