pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/dic/cpp/dicinterpolator.hpp

@@ -0,0 +1,162 @@
+// ================================================================================
+// pyvale: the python validation engine
+// License: MIT
+// Copyright (C) 2025 The Computer Aided Validation Team
+// ================================================================================
+
+
+
+
+#ifndef DICINTERPOLATOR_H
+#define DICINTERPOLATOR_H
+
+
+
+// STD library Header files
+#include <vector>
+
+// Program Header files
+/**
+ * @brief namespace for bicubic spline interpolation. 
+ * 
+ * Based on the implementation by GNU Scientific Library (GSL).
+ * Main difference is the removal of the binary search for index lookup.
+ * For use in DIC, we only ever need integer locations and therefore its
+ * sufficient to get the floor value of the subpixel location.
+ * 
+ */
+struct InterpVals {
+    double f;
+    double dfdx;
+    double dfdy;
+};
+
+class Interpolator {
+
+private: 
+
+    /**
+     * @brief Calculates the coefficients for cubic spline interpolation.
+     * 
+     * Computes the coefficients b, c, and d for the cubic spline polynomial.
+     * 
+     * @param tridiag_solution The solution vector from the tridiagonal system
+     * @param dy Difference in function values
+     * @param dx Difference in x values
+     * @param index Current index in the data array
+     * @param b Pointer to store the computed b coefficient
+     * @param c Pointer to store the computed c coefficient
+     * @param d Pointer to store the computed d coefficient
+     */
+    inline void coeff_calc(std::vector<double> &tridiag_solution, double dy, double dx, size_t index, double * b, double * c, double * d);
+    
+    inline void index_lookup_xy(const int ss_x, const int ss_y, size_t &xi, size_t &yi, const double subpx_x, const double subpx_y) const;
+
+    /**
+     * @brief Finds the index of the pixel that contains the given coordinate.
+     * 
+     * Determines the lower index of the interval containing the specified value.
+     * 
+     * @param px Vector of pixel coordinates
+     * @param x The coordinate to look up
+     * @return The index of the pixel containing the coordinate
+     */
+    inline int index_lookup(const std::vector<double> &px, double x) const;
+
+    /**
+     * @brief Initializes the cubic spline coefficients.
+     * 
+     * Sets up the tridiagonal system and solves it to obtain the cubic spline coefficients.
+     * 
+     * @param px Vector of x coordinates
+     * @param data Vector of function values at the x coordinates
+     */
+    void cspline_init(const std::vector<double> &px, const std::vector<double> &data,
+                      std::vector<double> &local_tridiag_sol);
+
+    /**
+     * @brief Evaluates the derivative of a cubic spline at a specified point.
+     * 
+     * Computes the first derivative of the cubic spline function at the given value.
+     * 
+     * @param px Vector of x coordinates
+     * @param data Vector of function values at the x coordinates
+     * @param value The point at which to evaluate the derivative
+     * @param length The length of the px and data arrays
+     * @return The derivative value at the specified point
+     */
+    double cspline_eval_deriv(std::vector<double> &px, std::vector<double> &data, 
+                              std::vector<double> &local_tridiag_sol, double value, int length);
+
+
+public:
+    std::vector<double> dx;
+    std::vector<double> dy;
+    std::vector<double> dxy;
+    std::vector<double> px_y;
+    std::vector<double> px_x;
+    double *image;
+    int px_vert;
+    int px_hori;
+
+    /**
+     * @brief Initializes the bicubic interpolator with deformed image data.
+     * 
+     * Sets up the necessary data structures and computes derivatives required for bicubic interpolation.
+     * 
+     * @param img Pointer to the image data array
+     * @param px_hori Width of the image in pixels
+     * @param px_vert Height of the image in pixels
+     */
+    Interpolator(double * img, int px_hori, int px_vert);
+
+    /**
+     * @brief Evaluates the bicubic interpolation at a specified point.
+     * 
+     * Computes the interpolated value at (x,y) using bicubic interpolation from the surrounding pixel values.
+     * 
+     * @param x The x-coordinate of the interpolation point
+     * @param y The y-coordinate of the interpolation point
+     * @return The interpolated value at (x,y)
+     */
+    double eval_bicubic(const int ss_x, const int ss_y, const double subpx_x, const double subpx_y) const;
+
+    /**
+     * @brief Evaluates the x-derivative of bicubic interpolation at a specified point.
+     * 
+     * Computes the partial derivative with respect to x at point (x,y).
+     * 
+     * @param x The x-coordinate of the point
+     * @param y The y-coordinate of the point
+     * @return The x-derivative of the interpolated function at (x,y)
+     */
+    double eval_bicubic_dx(const int ss_x, const int ss_y, const double subpx_x, const double subpx_y) const;
+
+    /**
+     * @brief Evaluates the y-derivative of bicubic interpolation at a specified point.
+     * 
+     * Computes the partial derivative with respect to y at point (x,y).
+     * 
+     * @param x The x-coordinate of the point
+     * @param y The y-coordinate of the point
+     * @return The y-derivative of the interpolated function at (x,y)
+     */
+    double eval_bicubic_dy(const int ss_x, const int ss_y, const double subpx_x, const double subpx_y) const;
+
+    /**
+     * @brief Evaluates the bicubic interpolation and its derivatives at a specified point.
+     * 
+     * Computes the interpolated value and its partial derivatives at (x,y) in a single call.
+     * 
+     * @param x The x-coordinate of the point
+     * @param y The y-coordinate of the point
+     * @return Data struct containing the interpolated value and its x and y derivatives
+     */
+    InterpVals eval_bicubic_and_derivs(const int ss_x, const int ss_y, const double subpx_x, const double subpx_y) const;
+};
+
+#endif //DICINTERPOLATOR_H
+
+
+
+

pyvale/dic/cpp/dicmain.cpp

@@ -0,0 +1,214 @@
+// ================================================================================
+// pyvale: the python validation engine
+// License: MIT
+// Copyright (C) 2025 The Computer Aided Validation Team
+// ================================================================================
+
+
+// STD library Header files
+#include <atomic>
+#include <iostream>
+#include <cstring>
+#include <omp.h>
+#include <vector>
+#include <signal.h>
+
+// pybind header files
+#include <pybind11/pybind11.h>
+#include <pybind11/numpy.h>
+#include <pybind11/stl.h>
+#include <pybind11/iostream.h>
+
+// common_cpp header files
+#include "../../common_cpp/dicsignalhandler.hpp"
+#include "../../common_cpp/defines.hpp"
+#include "../../common_cpp/util.hpp"
+
+// DIC Header files
+#include "./dicinterpolator.hpp"
+#include "./dicoptimizer.hpp"
+#include "./dicscanmethod.hpp"
+#include "./dicutil.hpp"
+#include "./dicfourier.hpp"
+#include "./dicshapefunc.hpp"
+#include "./dicresults.hpp"
+#include "dicsubset.hpp"
+
+// cuda Header files
+//#include "../cuda/malloc.hpp"
+
+namespace py = pybind11;
+
+
+void DICengine(const py::array_t<double>& img_stack_arr,
+               const py::array_t<bool>&   img_roi_arr, 
+               util::Config &conf,
+               common_util::SaveConfig &saveconf){
+
+    // Register signal handler for Ctrl+C and set debug_level
+    signal(SIGINT, signalHandler);
+    g_debug_level = conf.debug_level;
+
+    // ------------------------------------------------------------------------
+    // Initialisation
+    // ------------------------------------------------------------------------
+    if (g_debug_level>0){
+    TITLE("Config");
+    INFO_OUT("Width of Images: ", conf.px_hori << " [px]");
+    INFO_OUT("Height of Images: ", conf.px_vert << " [px]");
+    INFO_OUT("Number of Deformed Images: ", conf.num_def_img);
+    INFO_OUT("Max number of solver iterations: ", conf.max_iter);
+    INFO_OUT("Correlation Criterion: ", conf.corr_crit);
+    INFO_OUT("Shape Function: ", conf.shape_func);
+    INFO_OUT("Interpolation Routine: ", conf.interp_routine);
+    INFO_OUT("FFT MAD outlier removal enabled: ", conf.fft_mad);
+    INFO_OUT("FFT MAD scale: ", conf.fft_mad_scale);
+    INFO_OUT("Image Scan Method: ", conf.scan_method);
+    INFO_OUT("Optimization Precision:", conf.precision);
+    INFO_OUT("Correlation Cutoff Threshold:", conf.threshold);
+    INFO_OUT("Estimate for Max Displacement:", conf.max_disp << " [px]");
+    INFO_OUT("Subset Size:", conf.ss_size << " [px]");
+    INFO_OUT("Subset Step:", conf.ss_step << " [px]" );
+    INFO_OUT("Number of OMP threads:", omp_get_max_threads());
+    INFO_OUT("Debug level: ", conf.debug_level);
+    if (conf.scan_method.find("RG") != std::string::npos)INFO_OUT("Reliability Guided Seed central px location: ", "(" 
+                                         << conf.rg_seed.first+conf.ss_size/2 << ", " << conf.rg_seed.second+conf.ss_size/2 << ") [px] " )
+    }
+
+    // get raw pointers
+    bool* img_roi = static_cast<bool*>(img_roi_arr.request().ptr);
+    double* img_stack = static_cast<double*>(img_stack_arr.request().ptr);
+
+    // ------------------------------------------------------------------------
+    // get a list of ss coordinates within RIO;
+    // ------------------------------------------------------------------------
+    std::vector<subset::Grid> ss_grids;
+    std::vector<int> ss_sizes, ss_steps;
+    util::gen_size_and_step_vector(ss_sizes, ss_steps, conf.ss_size, conf.ss_step, conf.max_disp);
+    fourier::init(ss_grids, ss_sizes, ss_steps, img_roi, conf);
+
+
+    // resize the results based on subset information
+    OptResultArrays result_arrays(conf.num_def_img, ss_grids.back().num,
+                               conf.num_params, saveconf.at_end);
+
+
+    // set relevent shape function
+    shapefunc::set(conf.shape_func);
+
+    // set cost function to use in optimization
+    optimizer::set_cost_function(conf.corr_crit);
+
+
+
+    // -----------------------------------------------------------------------
+    // loop over deformed images and perform DIC
+    // -----------------------------------------------------------------------
+    if (g_debug_level>0){
+        std::cout << std::endl;
+        TITLE("Starting Correlation")
+    }
+    common_util::Timer timer("DIC Engine:");
+
+    // pointer to reference image at start of stack
+    double *img_ref = img_stack;
+    
+    // pointer to hold the reference interpolator (will be created once)
+    Interpolator* interp_ref = nullptr;
+
+    // loop over deformed images. They start at index 1 in the stack
+    for (int img_num = 1; img_num < conf.num_def_img+1; img_num++){
+
+        // pointer to starting location of deformed image in memory
+        int num_px_in_image = conf.px_hori * conf.px_vert;
+        double *img_def = img_stack + img_num*num_px_in_image;
+
+        // define our interpolator for the reference image
+        Interpolator interp_def(img_def, conf.px_hori, conf.px_vert);
+
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        // raster scan
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        if (conf.scan_method=="IMAGE_SCAN") 
+            scanmethod::image(img_ref, interp_def, ss_grids[0], conf, img_num, result_arrays);
+
+
+
+
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        // multiwindow FFTCC + reliability Guided
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        else if (conf.scan_method=="MULTIWINDOW_RG")
+            scanmethod::multiwindow_reliability_guided(img_ref, img_def, interp_def, ss_grids, conf, img_num, result_arrays);
+
+
+
+
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        // singlewindow FFTCC + reliability Guided
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        else if (conf.scan_method=="SINGLEWINDOW_RG"){
+            if (!interp_ref) interp_ref = new Interpolator(img_ref, conf.px_hori, conf.px_vert);
+            scanmethod::singlewindow_incremental_reliability_guided(img_ref, img_def, *interp_ref, interp_def, ss_grids, conf, 0, img_num, result_arrays);
+        }
+
+
+
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        // multi window FFTCC ONLY
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        else if (conf.scan_method=="MULTIWINDOW")
+            scanmethod::multiwindow(img_ref, img_def, interp_def, ss_grids, conf, img_num, result_arrays);
+
+
+
+
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        // singlewindow FFTCC + reliability Guided + Incremental Updating
+        // -------------------------------------------------------------------------------------------------------------------------------------------
+        else if (conf.scan_method=="SINGLEWINDOW_RG_INCREMENTAL"){
+            double *img_prev = nullptr;
+            int img_num_prev = img_num-1;
+            img_prev = img_stack + img_num_prev*num_px_in_image;
+            Interpolator interp_ref_inc(img_prev, conf.px_hori, conf.px_vert);
+            scanmethod::singlewindow_incremental_reliability_guided(img_prev, img_def, interp_ref_inc, interp_def, ss_grids, conf, img_num_prev, img_num, result_arrays);
+        }
+
+
+
+
+
+        if (!saveconf.at_end)
+            result_arrays.write_to_disk(img_num, saveconf, ss_grids.back(), conf.num_def_img, conf.filenames);
+
+        if (stop_request) break;
+    }
+
+    if (saveconf.at_end)
+        for (int img_num = 1; img_num < conf.num_def_img+1; img_num++)
+            result_arrays.write_to_disk(img_num, saveconf, ss_grids.back(), conf.num_def_img, conf.filenames);
+
+
+    if (interp_ref) delete interp_ref;
+
+    // TODO: don't have shifts as a global var. Should probably make fourier
+    // stuff a class at some point in the future
+    fourier::shifts.clear();
+    fourier::shifts.shrink_to_fit();
+}
+
+
+void build_info(){
+        //std::cout << "Buld Information:" << std::endl;
+        //INFO_OUT("- g++ version:", CPUCOMP);
+        //INFO_OUT("- Co
+        //INFO_OUT("- Git SHA:", GITINFO);
+        //INFO_OUT("- Number of dirty files:", GITDIRTY);
+        //INFO_OUT("- Compiled on Machine:", HOSTNAME);
+        //INFO_OUT("- Compiled on OS:", OSNAME);
+        //INFO_OUT("- Compiled at:", BUILDTIME);
+        //std::cout << std::endl;
+}
+
+
+

pyvale/dic/cpp/dicmain.hpp

@@ -0,0 +1,61 @@
+// ================================================================================
+// pyvale: the python validation engine
+// License: MIT
+// Copyright (C) 2025 The Computer Aided Validation Team
+// ================================================================================
+#ifndef DICMAIN_H
+#define DICMAIN_H
+
+// Pybind11 Header Files
+#include <pybind11/numpy.h>
+#include <pybind11/pybind11.h>
+
+// common_cpp header files
+#include "../../common_cpp/util.hpp"
+
+// DIC Header Files
+#include "./dicutil.hpp"
+
+namespace py = pybind11;
+
+/**
+ * @brief Runs the 2D Digital Image Correlation (DIC) engine on input image data.
+ *
+ * This function performs 2D DIC using a specified correlation criterion,
+ * shape function, interpolation scheme, and scan method.
+ * It computes displacement fields by comparing a reference image with a stack of
+ * deformed images over a defined region of interest (ROI).
+ *
+ * @param img_ref_arr A 2D NumPy array (pybind11) representing the reference image.
+ * @param img_def_stack_arr A 3D NumPy array containing a stack of deformed images.
+ *                          Each image must have the same dimensions as the reference image.
+ * @param img_roi_arr A 2D boolean NumPy array specifying the region of interest (ROI).
+ *                    True values indicate active ROI pixels.
+ * @param conf Configuration parameters for the DIC engine (subset size, correlation method, etc.).
+ *             This is an instance of `util::Config`.
+ * @param saveconf Output configuration for saving DIC results to disk.
+ *                 This is an instance of `SaveConfig`.
+ *
+ * @details
+ * The function supports multiple scan methods including raster scan, brute force,
+ * reliability-guided, and Fourier-based approaches. It computes correlation
+ * between the reference and deformed images over subsets defined by the ROI.
+ * 
+ * Subset data is initialized and processed in parallel using OpenMP.
+ * Results are optionally saved after each image or at the end of processing,
+ * depending on `saveconf.at_end`.
+ *
+ * @note This function is intended to be called via the Python interface using pybind11.
+ *       Image arrays are expected to be contiguous and C-style (row-major) in memory.
+ */
+void DICengine(const py::array_t<double>& img_stack_arr,
+               const py::array_t<bool>& img_roi_arr,
+               util::Config& conf,
+               common_util::SaveConfig& saveconf);
+
+void build_info();
+
+
+
+#endif // DICMAIN_H
+