diff --git a/.gitignore b/.gitignore index f05185b9..1181d256 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,7 @@ pyvale.*.rst docs/source/examples/*/ # keep the gallery layouts !docs/source/examples/examples_*.rst +docs/source/sg_execution_times.rst # doxygen folder generated when compiling docs docs/source/doxygen diff --git a/docs/source/guide_user/guide_dic.rst b/docs/source/guide_user/guide_dic.rst index a29904fb..5c608333 100644 --- a/docs/source/guide_user/guide_dic.rst +++ b/docs/source/guide_user/guide_dic.rst @@ -405,7 +405,7 @@ incorrect initial rigid estimate for the displacements. Pyvale has a Median Absolute Deviation (MAD) outlier removal flag that, when enabled, will kill likely incorrect spikes in the rigid -estimates or each FFTCC window size. This can be enabled with the following +estimates for each FFTCC window size. This can be enabled with the following arguments when calling the DIC engine: .. code-block:: Python diff --git a/docs/source/sg_execution_times.rst b/docs/source/sg_execution_times.rst deleted file mode 100644 index 59bf07c4..00000000 --- a/docs/source/sg_execution_times.rst +++ /dev/null @@ -1,166 +0,0 @@ - -:orphan: - -.. _sphx_glr_sg_execution_times: - - -Computation times -================= -**00:00.000** total execution time for 44 files **from all galleries**: - -.. container:: - - .. raw:: html - - - - - - - - .. list-table:: - :header-rows: 1 - :class: table table-striped sg-datatable - - * - Example - - Time - - Mem (MB) - * - :ref:`sphx_glr_examples_basics_ex1a_basicscalars_therm2d.py` (``../../src/pyvale/examples/basics/ex1a_basicscalars_therm2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex1b_sensormodel_therm2d.py` (``../../src/pyvale/examples/basics/ex1b_sensormodel_therm2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex1c_customsens_therm3d.py` (``../../src/pyvale/examples/basics/ex1c_customsens_therm3d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex1d_basicerrors_therm3d.py` (``../../src/pyvale/examples/basics/ex1d_basicerrors_therm3d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex1e_fielderrs_therm3d.py` (``../../src/pyvale/examples/basics/ex1e_fielderrs_therm3d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex1f_caliberrs_therm2d.py` (``../../src/pyvale/examples/basics/ex1f_caliberrs_therm2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex1g_spatavg_therm2d.py` (``../../src/pyvale/examples/basics/ex1g_spatavg_therm2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex2a_basicvectors_disp2d.py` (``../../src/pyvale/examples/basics/ex2a_basicvectors_disp2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex2b_vectorsens_disp2d.py` (``../../src/pyvale/examples/basics/ex2b_vectorsens_disp2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex2c_sensangle_disp2d.py` (``../../src/pyvale/examples/basics/ex2c_sensangle_disp2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex2d_chainfielderrs_disp2d.py` (``../../src/pyvale/examples/basics/ex2d_chainfielderrs_disp2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex2e_vectorfields3d_disp3d.py` (``../../src/pyvale/examples/basics/ex2e_vectorfields3d_disp3d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex3a_basictensors_strain2d.py` (``../../src/pyvale/examples/basics/ex3a_basictensors_strain2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex3b_tensorsens2d_strain2d.py` (``../../src/pyvale/examples/basics/ex3b_tensorsens2d_strain2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex3c_tensorsens3d_strain3d.py` (``../../src/pyvale/examples/basics/ex3c_tensorsens3d_strain3d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex4a_expsim2d_thermmech2d.py` (``../../src/pyvale/examples/basics/ex4a_expsim2d_thermmech2d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex4b_expsim3d_thermmech3d.py` (``../../src/pyvale/examples/basics/ex4b_expsim3d_thermmech3d.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_basics_ex5_nomesh.py` (``../../src/pyvale/examples/basics/ex5_nomesh.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_dic_ex1_2_blenderdeformed.py` (``../../src/pyvale/examples/dic/ex1_2_blenderdeformed.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_dic_ex1_region_of_interest.py` (``../../src/pyvale/examples/dic/ex1_region_of_interest.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_dic_ex2_plate_with_hole.py` (``../../src/pyvale/examples/dic/ex2_plate_with_hole.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_dic_ex3_plate_with_hole_strain.py` (``../../src/pyvale/examples/dic/ex3_plate_with_hole_strain.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_dic_ex4_dic_blender.py` (``../../src/pyvale/examples/dic/ex4_dic_blender.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_dic_ex5_dic_challenge.py` (``../../src/pyvale/examples/dic/ex5_dic_challenge.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex0_create_moose_config.py` (``../../src/pyvale/examples/mooseherder/ex0_create_moose_config.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex1a_modify_moose_input.py` (``../../src/pyvale/examples/mooseherder/ex1a_modify_moose_input.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex1b_modify_gmsh_input.py` (``../../src/pyvale/examples/mooseherder/ex1b_modify_gmsh_input.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex2a_run_moose_once.py` (``../../src/pyvale/examples/mooseherder/ex2a_run_moose_once.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex2b_run_gmsh_once.py` (``../../src/pyvale/examples/mooseherder/ex2b_run_gmsh_once.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex2c_run_both_once.py` (``../../src/pyvale/examples/mooseherder/ex2c_run_both_once.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex3_run_moose_seq_para.py` (``../../src/pyvale/examples/mooseherder/ex3_run_moose_seq_para.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex4_run_gmsh-moose_seq_para.py` (``../../src/pyvale/examples/mooseherder/ex4_run_gmsh-moose_seq_para.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex5_run_moose_paramulti.py` (``../../src/pyvale/examples/mooseherder/ex5_run_moose_paramulti.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex6_read_moose_exodus.py` (``../../src/pyvale/examples/mooseherder/ex6_read_moose_exodus.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex7a_read_moose_herd_results.py` (``../../src/pyvale/examples/mooseherder/ex7a_read_moose_herd_results.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex7b_read_multi_herd_results.py` (``../../src/pyvale/examples/mooseherder/ex7b_read_multi_herd_results.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex7c_read_multi_gmshmoose_results.py` (``../../src/pyvale/examples/mooseherder/ex7c_read_multi_gmshmoose_results.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex7d_readconfig_multi_gmshmoose_results.py` (``../../src/pyvale/examples/mooseherder/ex7d_readconfig_multi_gmshmoose_results.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_mooseherder_ex8_read_existing_sweep_output.py` (``../../src/pyvale/examples/mooseherder/ex8_read_existing_sweep_output.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_renderblender_ex1_1_blenderscene.py` (``../../src/pyvale/examples/renderblender/ex1_1_blenderscene.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_renderblender_ex1_2_blenderdeformed.py` (``../../src/pyvale/examples/renderblender/ex1_2_blenderdeformed.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_renderblender_ex2_1_stereoscene.py` (``../../src/pyvale/examples/renderblender/ex2_1_stereoscene.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_renderblender_ex2_2_stereodeformed.py` (``../../src/pyvale/examples/renderblender/ex2_2_stereodeformed.py``) - - 00:00.000 - - 0.0 - * - :ref:`sphx_glr_examples_renderblender_ex3_1_blendercalibration.py` (``../../src/pyvale/examples/renderblender/ex3_1_blendercalibration.py``) - - 00:00.000 - - 0.0 diff --git a/src/pyvale/dic/cpp/bindings.cpp b/src/pyvale/dic/cpp/bindings.cpp index 1efafd3d..39999e76 100644 --- a/src/pyvale/dic/cpp/bindings.cpp +++ b/src/pyvale/dic/cpp/bindings.cpp @@ -30,7 +30,6 @@ PYBIND11_MODULE(dic2dcpp, m) { .def_readwrite("max_iter", &util::Config::max_iter) .def_readwrite("precision", &util::Config::precision) .def_readwrite("threshold", &util::Config::threshold) - .def_readwrite("bf_threshold", &util::Config::bf_threshold) .def_readwrite("max_disp", &util::Config::max_disp) .def_readwrite("corr_crit", &util::Config::corr_crit) .def_readwrite("shape_func", &util::Config::shape_func) diff --git a/src/pyvale/dic/cpp/dicutil.hpp b/src/pyvale/dic/cpp/dicutil.hpp index e0ca2ac9..927c1d78 100644 --- a/src/pyvale/dic/cpp/dicutil.hpp +++ b/src/pyvale/dic/cpp/dicutil.hpp @@ -39,7 +39,6 @@ namespace util { int num_params; double precision; double threshold; - double bf_threshold; int max_disp; std::pair rg_seed; std::string corr_crit; diff --git a/src/pyvale/dic/dic2d.py b/src/pyvale/dic/dic2d.py index 02de61c3..9ef5836c 100644 --- a/src/pyvale/dic/dic2d.py +++ b/src/pyvale/dic/dic2d.py @@ -28,7 +28,6 @@ def calculate_2d(reference: np.ndarray | str | Path, max_iterations: int=40, precision: float=0.001, threshold: float=0.9, - bf_threshold: float=0.6, num_threads: int | None = None, max_displacement: int=128, method: str="MULTIWINDOW_RG", @@ -65,12 +64,13 @@ def calculate_2d(reference: np.ndarray | str | Path, subset_step : int, optional Step size between subset centers in pixels (default: 10). correlation_criteria : str, optional - Metric for matching subsets: "ZNSSD", "NSSD" or "SSD" (default: "ZNSSD"). + Metric for matching subsets: ``"ZNSSD"``, ``"NSSD"`` or ``"SSD"`` (default: ``"ZNSSD"``). shape_function : str, optional - Deformation model: e.g., "AFFINE", "RIGID" (default: "AFFINE"). + Deformation model: e.g., ``"AFFINE"``, ``"QUAD"``, ``"RIGID"`` (default: ``"AFFINE"``). interpolation_routine : str, optional - Interpolation method used on image intensity. "BICUBIC" is currently the - only supported option. + Interpolation method used on image intensity. Options are ``"BSPLINE"`` and + ``"HERMITE"``. Implementation details can be found in our DIC theory + documentation. (default: `"BSPLINE"``). max_iterations : int, optional Maximum number of iterations allowed for subset optimization (default: 40). precision : float, optional @@ -78,45 +78,38 @@ def calculate_2d(reference: np.ndarray | str | Path, threshold : float, optional Minimum correlation/cost coefficient value to be considered a matching subset (default: 0.9). num_threads : int, optional - Number of threads to use for parallel computation (default: None, uses all available). - bf_threshold : float, optional - Correlation threshold used in rigid bruteforce check for a subset to be considered a - good match(default: 0.6). + Number of threads to use for parallel computation (default: ``None``, uses all available). max_displacement : int, optional Estimate for the Maximum displacement in any direction (in pixels) (default: 128). method : str, optional - Subset scanning method: "RG" for Reliability-Guided (best overall approach), - "IMAGE_SCAN" for a standard scan across the image with no seeding - (best performance with for subpixel displacements with high quality images), - "FFT" for a multi-window FFT based approach (Good for large displacements) + Subset scanning method: ``"MULTIWINDOW_RG"`` for multi-window Reliability-Guided DIC (best overall approach), + ``"MULTIWINDOW"`` for a multi-window FFT based approach (Good for large rigid displacements) fft_mad : bool, optional - The option to smooth FFT windowing data by identifying and replacing outliers using - a robust statistical method. For each subset, the function collects values from its - neighboring subsets (within a 5x5 window, i.e., radius = 2), computes the median and - Median Absolute Deviation (MAD), and determines whether the value at the current - subset is an outlier. If it is, the value is replaced with the median of - its neighbors. (default: False) + Median Absolute Deviation (MAD) outlier removal flag that + will kill likely incorrect spikes in the rigid estimates + for each FFTCC window size. (default: ``False``) fft_mad_scale : bool, optional An outlier is defined as a value whose deviation from the local median exceeds - `fft_mad_scale` times the MAD. This value choses the scaling factor that determines - the threshold for detecting outliers relative to the MAD. + ``fft_mad_scale`` times the MAD. This value choses the scaling factor that determines + the threshold for detecting outliers relative to the MAD. A larger ``fft_mad_scale`` + is more tolerant, while a smaller value kills larger deviations. output_at_end : bool, optional - If True, results will only be written at the end of processing (default: False). + If True, results will only be written at the end of processing (default: ``False``). output_basepath : str or pathlib.Path, optional - Directory path where output files will be written (default: "./"). + Directory path where output files will be written (default: ``"./"``). output_binary : bool, optional - Whether to write output in binary format (default: False). + Whether to write output in binary format (default: ``False``). output_prefix : str, optional - Prefix for all output files (default: :code:`dic_results_`). results will be + Prefix for all output files (default: ``dic_results_``). results will be named with output_prefix + original filename. THe extension will be - changed to ".csv" or ".dic2d" depending on whether outputting as a binary. + changed to ``".csv"`` or ``".dic2d"`` depending on whether outputting as a binary. output_delimiter : str, optional - Delimiter used in text output files (default: ","). + Delimiter used in text output files (default: ``","``). output_below_threshold : bool, optional If True, subset results with cost values that did not exceed the cost threshold - will still be present in output (default: False). + will still be present in output (default: ``False``). output_shape_params : bool, optional - If True, all shape parameters will be saved in the output files (default: False). + If True, all shape parameters will be saved in the output files (default: ``False``). debug_level: Returns @@ -140,7 +133,7 @@ def calculate_2d(reference: np.ndarray | str | Path, dicchecks.check_correlation_criteria(correlation_criteria) dicchecks.check_interpolation(interpolation_routine) dicchecks.check_method(method) - dicchecks.check_thresholds(threshold, bf_threshold, precision) + dicchecks.check_thresholds(threshold, precision) common_py_util.check_output_directory(str(output_basepath), output_prefix, debug_level) dicchecks.check_subsets(subset_size, subset_step) updated_seed = dicchecks.check_and_update_rg_seed(seed, roi_mask, method, image_stack.shape[2], image_stack.shape[1], subset_size, subset_step) @@ -154,7 +147,6 @@ def calculate_2d(reference: np.ndarray | str | Path, config.max_iter = max_iterations config.precision = precision config.threshold = threshold - config.bf_threshold = bf_threshold config.max_disp = max_displacement config.corr_crit = correlation_criteria config.shape_func = shape_function @@ -187,4 +179,4 @@ def calculate_2d(reference: np.ndarray | str | Path, # calling the c++ dic engine with dic2dcpp.ostream_redirect(stdout=True, stderr=True): - dic2dcpp.dic_engine(image_stack, roi_c, config, saveconf) + dic2dcpp.engine_2d(image_stack, roi_c, config, saveconf) diff --git a/src/pyvale/dic/dicchecks.py b/src/pyvale/dic/dicchecks.py index 0b402a12..6b57896c 100644 --- a/src/pyvale/dic/dicchecks.py +++ b/src/pyvale/dic/dicchecks.py @@ -21,18 +21,19 @@ def check_correlation_criteria(correlation_criteria: str) -> None: """ Validate that the correlation criteria is one of the allowed values. - Checks whether input `correlation_criteria` is among the - accepted options: "SSD", "NSSD", or "ZNSSD". If not, raises a `ValueError`. + Checks whether input ``correlation_criteria`` is among the + accepted options: ``"SSD"``, ``"NSSD"``, or ``"ZNSSD"``. If not, raises a + ``ValueError``. Parameters ---------- correlation_criteria : str - The correlation type. Must be one of: "SSD", "NSSD", or "ZNSSD". + The correlation type. Must be one of: ``"SSD"``, ``"NSSD"``, or ``"ZNSSD"``. Raises ------ ValueError - If `correlation_criteria` is not one of the allowed values. + If ``correlation_criteria`` is not one of the allowed values. """ allowed_values = {"SSD", "NSSD", "ZNSSD"} @@ -47,26 +48,26 @@ def check_correlation_criteria(correlation_criteria: str) -> None: def check_shape_function(shape_function: str) -> int: """ Checks whether input `shape_function` is one of the allowed - values ("RIGID", "AFFINE" or "QUAD"). If valid, it returns the number of transformation + values (``"RIGID"``, ``"AFFINE"`` or ``"QUAD"``). If valid, it returns the number of transformation parameters associated with that shape function. Parameters ---------- shape_function : str - The shape function type. Must be either "RIGID", "AFFINE" or "QUAD". + The shape function type. Must be either ``"RIGID"``, ``"AFFINE"`` or ``"QUAD"``. Returns ------- int The number of parameters for the specified shape function: - - 2 for "RIGID" - - 6 for "AFFINE" - - 12 for "QUAD" + - 2 for ``"RIGID"`` + - 6 for ``"AFFINE"`` + - 12 for ``"QUAD"`` Raises ------ ValueError - If `shape_function` is not one of the allowed values. + If ``shape_function`` is not one of the allowed values. """ if (shape_function=="RIGID"): @@ -88,18 +89,18 @@ def check_interpolation(interpolation_routine: str) -> None: Validate that the interpolation routine is one of the allowed methods. Checks whether interpolation_routine is a supported - interpolation method. Allowed values are "BSPLINE" and "HERMITE". If the input - is not one of these, a `ValueError` is raised. + interpolation method. Allowed values are ``"BSPLINE"`` and ``"HERMITE"``. If the input + is not one of these, a ``ValueError`` is raised. Parameters ---------- interpolation_routine : str - The interpolation method to validate. Must be either "BSPLINE" or "HERMITE". + The interpolation method to validate. Must be either ``"BSPLINE"`` or ``"HERMITE"``. Raises ------ ValueError - If `interpolation_routine` is not a supported value. + If ``interpolation_routine`` is not a supported value. """ @@ -115,17 +116,16 @@ def check_interpolation(interpolation_routine: str) -> None: def check_method(method: str) -> None: """ Validate that the scan type one of the allowed methods. - Allowed values are "MULTIWINDOW_RG", "MULTIWINDOW", "SINGLEWINDOW_RG", "SINGLEWINDOW_RG_INCREMENTAL", "IMAGE_SCAN". Parameters ---------- - interpolation_routine : str - The interpolation method to validate. Must be either "BILINEAR" or "BICUBIC". + method : str + Allowed values are ``"MULTIWINDOW_RG"``, ``"MULTIWINDOW"``, ``"SINGLEWINDOW_RG"``, ``"SINGLEWINDOW_RG_INCREMENTAL"``, ``"IMAGE_SCAN"``. Raises ------ ValueError - If `interpolation_routine` is not a supported value. + If ``method`` is not a supported value. """ @@ -138,18 +138,15 @@ def check_method(method: str) -> None: def check_thresholds(threshold: float, - bf_threshold: float, precision: float) -> None: """ - Ensures that `threshold`, `bf_threshold`, and `precision` - are all floats strictly between 0 and 1. Raises a `ValueError` if any condition fails. + Ensures that ``threshold``, and ``precision`` + are all floats strictly between 0 and 1. Raises a ``ValueError`` if any condition fails. Parameters ---------- threshold : float correlation/cost coeff minumum value to be considered matching subset. - bf_threshold : float - Threshold for the brute-force optimization method. precision : float Desired precision for the optimizer. @@ -162,10 +159,6 @@ def check_thresholds(threshold: float, if not (0 < threshold < 1): raise ValueError("threshold must be a float " "strictly between 0 and 1.") - - if not (0 < bf_threshold < 1): - raise ValueError("bf_threshold must be a float " - "strictly between 0 and 1.") if not (0 < precision < 1): raise ValueError("Optimizer precision must be a float strictly " @@ -206,7 +199,7 @@ def check_and_update_rg_seed(seed: list[int] | list[np.int32] | np.ndarray, roi_ scanning method. It adjusts the seed to the nearest valid grid point based on the subset step size, clamps it to the image dimensions, and ensures it lies within the region of interest (ROI) mask. - If the scanning method is not "RG", the function returns a default seed of [0, 0]. + If the scanning method is not reliability guided, the function returns a default seed of [0, 0]. This seed is not used any other scan method methods. Parameters @@ -305,7 +298,7 @@ def check_and_get_images(reference: np.ndarray | str | Path, or a glob pattern string pointing to multiple image files. roi : np.ndarray A 2D NumPy array defining the region of interest. Must match the reference image shape - if `reference` is an array. + if ``reference`` is an array. debug_level: int Determines how much information to provide in console output. @@ -319,7 +312,7 @@ def check_and_get_images(reference: np.ndarray | str | Path, Raises ------ ValueError - If there is a type mismatch between `reference` and `deformed`, + If there is a type mismatch between ``reference`` and ``deformed``, if image files are not found or unreadable, or if image shapes do not match. FileNotFoundError diff --git a/src/pyvale/dic/dicdataimport.py b/src/pyvale/dic/dicdataimport.py index 5563fc2c..0a3dd0cd 100644 --- a/src/pyvale/dic/dicdataimport.py +++ b/src/pyvale/dic/dicdataimport.py @@ -25,39 +25,37 @@ def import_2d(data: str | Path, layout: str = "matrix", delimiter: str = ",") -> Results: """ - Import DIC result data from human readable text or binary files. + test. Import DIC result data from human readable text or binary files. Parameters ---------- - data : str or pathlib.Path - Path pattern to the data files (can include wildcards). Default is "./". + Path pattern to the data files (can include wildcards). Default is ``"./"``. layout : str, optional - Format of the output data layout: "column" (flat array per frame) or "matrix" - (reshaped grid per frame). Default is "column". + Format of the output data layout: ``"column"`` (flat array per frame) or ``"matrix"`` + (reshaped grid per frame). (Default: ``"matrix"``). binary : bool, optional If True, expects files in a specific binary format. If False, expects text data. - Default is False. + (Default: ``False``). delimiter : str, optional - Delimiter used in text data files. Ignored if binary=True. Default is a single space. + Delimiter used in text data files. Ignored if ``binary=True``. (Default: ``","``). Returns ------- - Results + Results : pyvale.dic.Results A named container with the following fields: - - ss_x, ss_y (grid arrays if layout=="matrix"; otherwise, 1D integer arrays) - - u, v, m, converged, cost, ftol, xtol, niter (arrays with shape depending on layout) - - filenames (python list) + * ss_x, ss_y (grid arrays if ``layout=="matrix"``; otherwise, 1D integer arrays) + * u, v, m, converged, cost, ftol, xtol, niter (arrays with shape depending on layout) + * filenames (python list) Raises ------ ValueError: - If `layout` is not "column" or "matrix", or text data has insufficient columns, + If `layout` is not ``"column"`` or ``"matrix"``, or text data has insufficient columns, or binary rows are malformed. - import cython module FileNotFoundError: If no matching data files are found. """ @@ -164,11 +162,11 @@ def read_binary(file: str, delimiter: str): Read a binary DIC result file and extract DIC fields. Assumes a fixed binary structure with each row containing: - - 2 × int32 (subset coordinates) - - 6 × float64 (u, v, match quality, cost, ftol, xtol) - - 1 × int32 (number of iterations) - - 1 × uint8 (convergence flag) - - 2 or 6 × float64 (shape parameters) + * 2 × ``int32`` (subset coordinates) + * 6 × ``float64`` (u, v, match quality, cost, ftol, xtol) + * 1 × ``int32`` (number of iterations) + * 1 × ``uint8`` (convergence flag) + * 2 or 6 × ``float64`` (shape parameters) Parameters ---------- @@ -364,8 +362,8 @@ def to_grid(data, shape, ss_x_ref, ss_y_ref, x_unique, y_unique): """ Reshape a 2D DIC field from flat (column) format into grid (matrix) format. - This is used when output layout is specified as "matrix". - Maps values using reference subset coordinates (ss_x_ref, ss_y_ref). + This is used when ``layout="matrix"``. + Maps values using reference subset coordinates (``ss_x_ref``, ``ss_y_ref``). Parameters ---------- diff --git a/src/pyvale/dic/dicregionofinterest.py b/src/pyvale/dic/dicregionofinterest.py index 9382945a..ad6db5e9 100644 --- a/src/pyvale/dic/dicregionofinterest.py +++ b/src/pyvale/dic/dicregionofinterest.py @@ -43,7 +43,8 @@ def __init__(self, ref_image: str | np.ndarray | Path): Raises ------ - ValueError: If the image cannot be loaded or is invalid. + ValueError + If the image cannot be loaded or is invalid. """ if isinstance(ref_image, str): self.ref_image = cv2.imread(ref_image) @@ -871,7 +872,7 @@ def _get_roi_data(self, roi_element, add: bool): def reset_mask(self): """ - Completely resets the roi mask to 0s. + Completely resets the roi mask to 0's. """ self.mask[:] = False; @@ -884,10 +885,14 @@ def rect_boundary(self, left: int, right: int, top: int, bottom: int) -> None: Parameters ---------- - left (int): Number of px to exclude from left edge. - right (int): Number of px to exclude from the right edge. - top (int): Number of px to exclude from the top edge. - bottom (int): Number of px to exclude from the bottom edge. + left : int + Number of px to exclude from left edge. + right : int + Number of px to exclude from the right edge. + top : int + Number of px to exclude from the top edge. + bottom : int + Number of px to exclude from the bottom edge. """ self.reset_mask() self.mask[bottom:(self.ref_image.shape[0]-top), left:(self.ref_image.shape[1])-right] = 255 @@ -931,7 +936,7 @@ def rect_region(self, x: int, y: int, size_x: int, size_y: int ) -> None: def save_image(self, filename: str | Path) -> None: """ - Save the ROI overlayed over the reference image in .tiff image format. + Save the ROI overlayed over the reference image in ``.tiff`` image format. Parameters ---------- @@ -963,7 +968,7 @@ def save_array(self, filename: str | Path, binary: bool=False) -> None: filename : str or pathlib.Path filename given to saved ROI mask binary : bool - If True, saves from as a .npy binary file. + If True, saves from as a ``.npy`` binary file. If False, saves to a space delimited text file. Raises @@ -982,14 +987,14 @@ def save_array(self, filename: str | Path, binary: bool=False) -> None: def read_array(self, filename: str | Path, binary: bool = False) -> None: """ - Load the ROI mask from a binary or text file and store it in `self.mask`. + Load the ROI mask from a binary or text file and store it in ``self.mask``. Parameters ---------- filename : str or pathlib.Path Path to the file to load. binary : bool - If True, loads from a .npy binary file. If False, loads from a text file. + If True, loads from a ``.npy`` binary file. If ``False``, loads from a text file. Raises ------ diff --git a/src/pyvale/examples/dic/ex4_dic_blender.py b/src/pyvale/examples/dic/ex4_dic_blender.py index 2a8cf78a..a3ceadb7 100644 --- a/src/pyvale/examples/dic/ex4_dic_blender.py +++ b/src/pyvale/examples/dic/ex4_dic_blender.py @@ -13,7 +13,7 @@ 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 `_ using the blender module first. +deformation example `_ 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