DIC doc improvements.

.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

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

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)

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<int, int> rg_seed;
         std::string corr_crit;

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,58 +64,52 @@ 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
         Precision threshold for iterative optimization convergence (default: 0.001).
     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)