Speckle pattern generation module

docs/apidoc.sh

@@ -27,7 +27,7 @@ echo "Updating generated RST files..."
 # sed -i '0,/dataset.dataset/s/dataset.dataset/pyvale.dataset/' source/pyvale.dataset.dataset.rst || error_exit "Failed to update dataset title"
 
 # Modules to process
-modules=("dic" "blender" "mooseherder" "sensorsim" "verif" "dataset")
+modules=("dic" "blender" "mooseherder" "sensorsim" "verif" "dataset" "specklegen")
 
 for mod in "${modules[@]}"; do
     rst="source/pyvale.${mod}.rst"

docs/source/api_py.rst

@@ -13,4 +13,6 @@ Detailed Python API
    pyvale.mooseherder
    pyvale.verif
    pyvale.dataset
+   pyvale.specklegen
+
 

docs/source/conf.py

@@ -117,6 +117,7 @@
         '../../src/pyvale/examples/dic',
         '../../src/pyvale/examples/blenderimagedef',
         '../../src/pyvale/examples/mooseherder',
+        '../../src/pyvale/examples/specklegen',
     ],
     # Path to where to save gallery generated output
     'gallery_dirs': [
@@ -125,6 +126,7 @@
         'examples/dic',
         'examples/blenderimagedef',
         'examples/mooseherder',
+        'examples/specklegen',
     ],
     # Pattern to identify example files
     'filename_pattern': '/plot_',

docs/source/examples/examples.rst

@@ -37,3 +37,10 @@ Mooseherder
    :maxdepth: 2
 
    examples_mooseherder
+
+Specklegen
+-------------------------------------
+.. toctree::
+   :maxdepth: 2
+
+   examples_specklegen

docs/source/examples/examples_specklegen.rst

@@ -0,0 +1,16 @@
+.. _examples_specklegen:
+
+Specklegen
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   specklegen/ex1a_random_disks_overlap.rst
+   specklegen/ex1b_random_disks_reduce_overlap.rst
+   specklegen/ex1c_random_disks_grid.rst
+   specklegen/ex2a_perlin_noise.rst
+   specklegen/ex3a_fractal_noise.rst
+   specklegen/ex4a_simplex_noise.rst
+
+

pyproject.toml

@@ -33,9 +33,13 @@ dependencies = [
   "pybind11>=2.13.6",
   "pyqtgraph>=0.13.7",
   "opencv-python<=4.9.0.80",
+  "seaborn>=0.13.2",
+  "scikit-image>=0.0",
+  "perlin_numpy>=0.0.0",
+  "opensimplex>=0.4.5.1",
   "pandas>=2.3.1",
   "scikit-build-core>=0.11.6",
-  "ninja>=1.13.0"
+  "ninja>=1.13.0",
 ]
 
 [tool.pytest.ini_options]

scripts/gengold_specklegen.py

@@ -0,0 +1,42 @@
+#===============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+#===============================================================================
+
+import pyvale.verif.specklegold as specklegold
+import pyvale.verif.specklegenconst as specklegenconst
+
+def main() -> None:
+
+    tags = ["random_disks", "random_disks_grid", "perlin", "fractal", "simplex"]
+
+    for tag in tags:
+
+        param_dict = {
+            "speckle_size": 20,
+            "screen_size_width": 1000,
+            "screen_size_height": 800,
+            "bit_depth": 8,
+            "theme": 'white_on_black',
+            "seed": 123,
+            "type_gen": tag,
+            "octaves": 3,
+            "lacunarity": 2,
+            "sigma": 4.0,
+            "reduce_overlap": True,
+            "attempts_tot": 300,
+            "perturbation_max": 12,
+            "case_tot": 3
+        }
+
+        print(80*"=")
+        print(f"Gold Output Generator for pyvale {tag} speckle pattern generation")
+        print(80*"=")
+        print(f"Saving gold output to: {specklegenconst.GOLD_PATH}\n")
+
+        print(f"Generating gold output for {tag} field point sensors...")
+        specklegold.gen_gold_measurements(param_dict)
+
+if __name__ == "__main__":
+    main()

src/pyvale/__init__.py

@@ -21,3 +21,4 @@
 from . import mooseherder
 from . import dataset
 from . import calib
+from . import specklegen

src/pyvale/examples/specklegen/README.md

@@ -0,0 +1,2 @@
+Specklegen Examples
+==================

src/pyvale/examples/specklegen/ex1a_random_disks_overlap.py

@@ -0,0 +1,142 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Specklegen: Speckle pattern generation using random disk placement without checking for overlap
+================================================================================
+Script to generate a synthetic speckle pattern made from randomly placed circular
+speckles (disks), run diagnostics on the generated image, and save both the image
+and diagnostics to the selected folder.
+"""
+
+import numpy as np
+import time
+import json
+import os
+import pyvale.specklegen as specklegen
+
+#%%
+# Here we parse command line arguments to set the speckle pattern parameters.
+# For ease of use in this example script we set parameter values directly in the
+# code rather than via bash script.
+# The parameter responsible for reducing overlap is set to 'False' in this example.
+
+speckle_size = 20
+screen_size_width = 1000
+screen_size_height = 800
+bit_depth = 8
+theme = 'white_on_black'
+seed = 10
+sigma = 4.0
+reduce_overlap = False
+type_gen = "random_disks"
+output_path = "src/pyvale/examples/specklegen/output/ex1a"
+
+print('Start')
+
+assert theme in ['black_on_white', 'white_on_black'], "Theme should be either 'black_on_white' or 'white_on_black'."
+
+if reduce_overlap:
+    print("Reducing overlap between speckles")
+else:
+    print("Not reducing overlap between speckles")
+
+subfolder = f"/{type_gen}_{speckle_size}_{screen_size_width}_{screen_size_height}_{bit_depth}_{theme}_{seed}_{sigma}_{reduce_overlap}"
+print(subfolder)
+save_path = output_path + subfolder
+if not os.path.exists(save_path):
+    os.makedirs(save_path)
+
+#%%
+# We calculate parameteres aiming for approximately 50/50 black-to-white ratio.
+# We now generate the speckle pattern using the specified parameters.
+# The background and foreground colours are set based on the chosen theme and bit depth.
+
+speckle_area = np.pi * (speckle_size / 2) ** 2
+total_area = screen_size_width * screen_size_height
+total_speckles = int((0.5 * total_area) / speckle_area)
+print(f"Total number of speckles = {total_speckles}")
+dynamic_range: int = 2**bit_depth - 1
+background_colour = 0 if theme == 'white_on_black' else dynamic_range
+foreground_colour = dynamic_range if theme == 'white_on_black' else 0
+
+feature_size_width = speckle_size
+feature_size_height = speckle_size
+
+time_start = time.time()
+image, results = specklegen.generate_speckles(screen_size_width, screen_size_height,
+                                   feature_size_width, feature_size_height,
+                                   foreground_colour, background_colour,
+                                   bit_depth, type_gen, seed,
+                                   total_speckles=total_speckles,
+                                   reduce_overlap=reduce_overlap,
+                                   sigma=sigma)
+time_end = time.time()
+time_taken = time_end - time_start
+print(f"Time taken for speckle generation: {np.round(time_taken, 3)} seconds")
+
+np.savetxt(f"{save_path}/speckle_placement_results.csv", results, delimiter=",", 
+           header="speckle_number, attempts, overlap(1/0/2), cent_x, cent_y", comments='', fmt=['%d', '%d', '%d', '%.3f', '%.3f'])
+
+#%%
+# Now we run diagnostics on the generated speckle pattern and save the results. 
+# Finally, we print out the key statistics to the console. 
+# The plots are saved in the provided output folder. However, the diagnostic function outputs the matplotlib figures and axes,  
+# so the plot formatting could be changed from the default one used by the function. 
+# We aim to achieve black-to-white ratio as close to unity as possible. Unity ratio means 50/50 distribution of black and white colours. 
+# However, in this example, black-to-white ratio considerably deviates from unity. 
+# It is also visible in the irradiance value histogram. 
+# The proportion of 0 irradiance values, corresponding to black colour, overweighs the 255 values, corresponding to white colour. 
+# This is a result of speckle overlap.
+
+print("")
+print('Starting speckle pattern diagnostics...')
+results = specklegen.speckle_pattern_statistics(image, dynamic_range)
+plots = specklegen.speckle_pattern_plots(image, dynamic_range, save_path)
+
+with open(f"{save_path}/speckle_pattern_diagnostics.json", 'w') as f:
+    json.dump(results, f, indent=4)
+
+ratio = results.get("black_white_ratio", None)
+mean_gradient = results.get("mean_intensity_gradient", None)
+std_dev = results.get("std_dev_irradiance", None)
+avg = results.get("avg_irradiance", None)
+contrast = results.get("contrast", None)
+entropy = results.get("shannon_entropy", None)
+peak_to_mean = results.get("peak_to_mean_ratio", None)
+skew = results.get("skewness", None)
+kurt = results.get("kurtosis", None)
+avg_speckle_size_fwhm = results.get("avg_speckle_size_fwhm", None)
+avg_speckle_size_e2 = results.get("avg_speckle_size_e2", None)
+H_fit_stats = results.get("H_fit_stats", None)
+V_fit_stats = results.get("V_fit_stats", None)
+
+print("")
+print("Speckle statistics:")
+
+print(f"Black/White ratio: {np.round(ratio, 3)}")
+print(f"Mean intensity gradient: {np.round(mean_gradient, 3)}")
+print(f"Standard deviation of irradiance values: {np.round(std_dev, 3)}")
+print(f"Average irradiance value: {np.round(avg, 3)}")
+print(f"Contrast (std/mean): {np.round(contrast, 3)}")
+print(f"Skewness: {np.round(skew, 3)}")
+print(f"Kurtosis: {np.round(kurt, 3)}")
+print(f"Shannon entropy: {np.round(entropy, 3)}")
+print(f"Peak to mean ratio: {np.round(peak_to_mean, 3)}")
+print(f"Average speckle size (full width at half maximum): {np.round(avg_speckle_size_fwhm, 3)} pixels")
+print(f"Average speckle size (1/e^2): {np.round(avg_speckle_size_e2, 3)} pixels")
+print(f"R_squared: Horisontal fit: {np.round(H_fit_stats['R_squared'], 3)}, Vertical fit: {np.round(V_fit_stats['R_squared'], 3)}")
+
+#%%
+# Finally, the relative errors beetween the specified speckle size and the speckle size approximated using cautocovariance are calculated. 
+error = np.abs(avg_speckle_size_fwhm - speckle_size) * 100 / speckle_size
+print(f"Percentage error between requested speckle size and measured speckle size from FWHM: {np.round(error, 3)} %")
+error = np.abs(avg_speckle_size_e2 - speckle_size) * 100 / speckle_size
+print(f"Percentage error between requested speckle size and measured speckle size from 1/e^2: {np.round(error, 3)} %")
+np.save(f"{save_path}/image.npy", image)
+print("")
+print('End :)')
+print("")