OpenPIV 0.25.3__tar.gz → 0.26.0__tar.gz

{openpiv-0.25.3 → openpiv-0.26.0}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: OpenPIV
-Version: 0.25.3
+Version: 0.26.0
 Summary: OpenPIV consists in a Python and Cython modules for scripting and executing the analysis of a set of PIV image pairs. In addition, a Qt and Tk graphical user interfaces are in development, to ease the use for those users who don't have python skills.
 License: GPLv3
+License-File: LICENSE.txt
 Author: Alex Liberzon
 Requires-Python: >=3.10
 Classifier: Development Status :: 4 - Beta
@@ -18,27 +19,26 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
-Requires-Dist: imageio (>=2.22.4,<3.0.0)
-Requires-Dist: importlib_resources (==5.12.0)
-Requires-Dist: matplotlib (>=3,<4)
-Requires-Dist: natsort (>=8.4.0,<9.0.0)
-Requires-Dist: numpy (>=1.21.6,<2.0.0)
-Requires-Dist: scikit-image (>=0.23)
-Requires-Dist: scipy (>=1.7.3,<2.0.0)
-Requires-Dist: tqdm (>=4.66.1,<5.0.0)
+Provides-Extra: rust
+Requires-Dist: imageio (>=2.35.0)
+Requires-Dist: matplotlib (>=3.8.0)
+Requires-Dist: natsort (>=8.4.0)
+Requires-Dist: numpy (>=2.0.0)
+Requires-Dist: openpiv-rust (>=0.1.0) ; extra == "rust"
+Requires-Dist: scikit-image (>=0.23.0)
+Requires-Dist: scipy (>=1.11.0)
+Requires-Dist: tqdm (>=4.66.0)
 Project-URL: Documentation, http://openpiv.readthedocs.org
 Project-URL: Repository, https://pypi.python.org/pypi/OpenPIV
 Description-Content-Type: text/markdown
 
 # OpenPIV
-![Build and upload to PyPI](https://github.com/OpenPIV/openpiv-python/workflows/Build%20and%20upload%20to%20PyPI/badge.svg)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4409178.svg)](https://doi.org/10.5281/zenodo.4409178)
+[![Python package](https://github.com/OpenPIV/openpiv-python/actions/workflows/testing.yml/badge.svg)](https://github.com/OpenPIV/openpiv-python/actions/workflows/testing.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18304582.svg)](https://doi.org/10.5281/zenodo.18304582)
 ![PyPI](https://img.shields.io/pypi/v/openpiv)
-![Anaconda](https://anaconda.org/openpiv/openpiv/badges/version.svg)
 
 
 OpenPIV consists in a Python and Cython modules for scripting and executing the analysis of 
@@ -61,18 +61,36 @@ Click the link - thanks to BinderHub, Jupyter and Conda you can now get it in yo
 
 ## Installing
 
+### Recommended: Using uv (fastest)
+
+[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver written in Rust:
+
+    pip install uv
+    uv pip install openpiv
+
+### Using pip (standard)
+
 Use PyPI: <https://pypi.python.org/pypi/OpenPIV>:
 
     pip install openpiv
 
+### Or [Poetry](https://python-poetry.org/)
 
-## Or `conda` 
+    poetry add openpiv
 
-    conda install -c alexlib openpiv
+### Note on Conda/Anaconda
 
-## Or [Poetry](https://python-poetry.org/)
+⚠️ **Conda packages are no longer actively maintained.** The conda-forge package may be outdated.
 
-    poetry add openpiv
+If you previously installed OpenPIV via conda, you can migrate to pip or uv:
+
+    # Remove the conda package
+    conda remove openpiv
+    
+    # Install with pip or uv
+    pip install openpiv
+    # or
+    uv pip install openpiv
     
     
 ### To build from source

{openpiv-0.25.3 → openpiv-0.26.0}/README.md

@@ -1,8 +1,7 @@
 # OpenPIV
-![Build and upload to PyPI](https://github.com/OpenPIV/openpiv-python/workflows/Build%20and%20upload%20to%20PyPI/badge.svg)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4409178.svg)](https://doi.org/10.5281/zenodo.4409178)
+[![Python package](https://github.com/OpenPIV/openpiv-python/actions/workflows/testing.yml/badge.svg)](https://github.com/OpenPIV/openpiv-python/actions/workflows/testing.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18304582.svg)](https://doi.org/10.5281/zenodo.18304582)
 ![PyPI](https://img.shields.io/pypi/v/openpiv)
-![Anaconda](https://anaconda.org/openpiv/openpiv/badges/version.svg)
 
 
 OpenPIV consists in a Python and Cython modules for scripting and executing the analysis of 
@@ -25,18 +24,36 @@ Click the link - thanks to BinderHub, Jupyter and Conda you can now get it in yo
 
 ## Installing
 
+### Recommended: Using uv (fastest)
+
+[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver written in Rust:
+
+    pip install uv
+    uv pip install openpiv
+
+### Using pip (standard)
+
 Use PyPI: <https://pypi.python.org/pypi/OpenPIV>:
 
     pip install openpiv
 
+### Or [Poetry](https://python-poetry.org/)
 
-## Or `conda` 
+    poetry add openpiv
 
-    conda install -c alexlib openpiv
+### Note on Conda/Anaconda
 
-## Or [Poetry](https://python-poetry.org/)
+⚠️ **Conda packages are no longer actively maintained.** The conda-forge package may be outdated.
 
-    poetry add openpiv
+If you previously installed OpenPIV via conda, you can migrate to pip or uv:
+
+    # Remove the conda package
+    conda remove openpiv
+    
+    # Install with pip or uv
+    pip install openpiv
+    # or
+    uv pip install openpiv
     
     
 ### To build from source

{openpiv-0.25.3 → openpiv-0.26.0}/openpiv/PIV_3D_plotting.py

@@ -71,7 +71,7 @@ def scatter_3D(a, cmap="jet", sca_args=None, control="color", size=60):
         sm = matplotlib.cm.ScalarMappable(cmap=cmap, norm=norm)
         sm.set_array([])
         # different option
-        cm = matplotlib.cm.get_cmap(cmap)
+        cm = matplotlib.colormaps.get_cmap(cmap)
         colors = cm(norm(a)).reshape(a.shape[0] * a.shape[1] * a.shape[2], 4)  #
         # plotting
         nan_filter = ~np.isnan(a.flatten())
@@ -83,7 +83,7 @@ def scatter_3D(a, cmap="jet", sca_args=None, control="color", size=60):
             s=size,
             **scatter_args
         )
-        plt.colorbar(sm)
+        fig.colorbar(sm, ax=ax)
 
     if control == "alpha":
         # untested #
@@ -92,8 +92,12 @@ def scatter_3D(a, cmap="jet", sca_args=None, control="color", size=60):
         plt.show()
 
     if control == "size":
-        sizes = (a - a.min()) * size / a.ptp()
-        ax.scatter(x, y, z, a, s=sizes, **scatter_args)
+        value_range = np.ptp(a)
+        if value_range == 0:
+            sizes = np.full(a.shape, size, dtype=float)
+        else:
+            sizes = (a - a.min()) * size / value_range
+        ax.scatter(x, y, z, c=a.flatten(), s=sizes.flatten(), **scatter_args)
         ax_scale = plt.axes([0.88, 0.1, 0.05, 0.7])
         # ax_scale.set_ylim((0.1,1.2))
         nm = 5
@@ -172,12 +176,13 @@ def plot_3D_alpha(data):
     z[:, :, 1::2] += 0.95
 
     fig = plt.figure()
-    ax = fig.gca(projection="3d")
+    ax = fig.add_subplot(projection="3d")
     ax.voxels(x, y, z, fill, facecolors=col_exp, edgecolors=col_exp)
     ax.set_xlabel("x")
     ax.set_ylabel("y")
     ax.set_zlabel("z")
     plt.show()
+    return fig
 
 
 def quiver_3D(
@@ -332,11 +337,11 @@ def quiver_3D(
 
     # plotting
     fig = plt.figure()
-    ax = fig.gca(projection="3d", rasterized=True)
+    ax = fig.add_subplot(projection="3d", rasterized=True)
     ax.quiver(
         xf, yf, zf, vf * scale, uf * scale, wf * scale, colors=colors, **quiver_args
     )
-    plt.colorbar(sm)
+    fig.colorbar(sm, ax=ax)
 
     ax.set_xlim(ax_dims[0])
     ax.set_ylim(ax_dims[1])
@@ -348,8 +353,9 @@ def quiver_3D(
     ax.set_xlabel("x")
     ax.set_ylabel("y")
     ax.set_zlabel("z")
-    ax.w_xaxis.set_pane_color((0.2, 0.2, 0.2, 1.0))
-    ax.w_yaxis.set_pane_color((0.2, 0.2, 0.2, 1.0))
-    ax.w_zaxis.set_pane_color((0.2, 0.2, 0.2, 1.0))
+    for axis in (ax.xaxis, ax.yaxis, ax.zaxis):
+        pane = getattr(axis, "pane", None)
+        if pane is not None:
+            pane.set_facecolor((0.2, 0.2, 0.2, 1.0))
 
     return fig

openpiv-0.26.0/openpiv/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import version
+
+
+__version__ = version("OpenPIV")
+
+
+def test():
+    import pytest
+
+    pytest.main()

openpiv-0.26.0/openpiv/data/test1/test_data.vec

@@ -0,0 +1,71 @@
+# x	y	u	v	flags	mask
+4.0406e-01	3.3983e+00	-5.2592e-03	-5.9910e-02	0.0000e+00	0.0000e+00
+9.0137e-01	3.3983e+00	-9.6075e-04	-6.4036e-02	0.0000e+00	0.0000e+00
+1.3987e+00	3.3983e+00	-3.4784e-06	-5.9356e-02	1.0000e+00	0.0000e+00
+1.8960e+00	3.3983e+00	4.9192e-03	-6.1691e-02	0.0000e+00	0.0000e+00
+2.3933e+00	3.3983e+00	-9.2873e-04	-5.6505e-02	1.0000e+00	0.0000e+00
+2.8906e+00	3.3983e+00	-5.9565e-03	-5.0575e-02	0.0000e+00	0.0000e+00
+3.3879e+00	3.3983e+00	2.1094e-04	-5.7925e-02	0.0000e+00	0.0000e+00
+3.8852e+00	3.3983e+00	-2.7240e-03	-6.0472e-02	0.0000e+00	0.0000e+00
+4.3825e+00	3.3983e+00	-3.7283e-03	-5.8267e-02	1.0000e+00	0.0000e+00
+4.8798e+00	3.3983e+00	2.4173e-03	-6.4150e-02	0.0000e+00	0.0000e+00
+4.0406e-01	2.9010e+00	-1.8216e-03	-5.4789e-02	0.0000e+00	0.0000e+00
+9.0137e-01	2.9010e+00	-1.8865e-04	-5.9088e-02	1.0000e+00	0.0000e+00
+1.3987e+00	2.9010e+00	5.2738e-03	-5.5928e-02	0.0000e+00	0.0000e+00
+1.8960e+00	2.9010e+00	8.0944e-03	-5.4726e-02	0.0000e+00	0.0000e+00
+2.3933e+00	2.9010e+00	-2.6124e-03	-5.5983e-02	0.0000e+00	0.0000e+00
+2.8906e+00	2.9010e+00	-4.3661e-03	-5.1347e-02	0.0000e+00	0.0000e+00
+3.3879e+00	2.9010e+00	-3.3565e-03	-5.6682e-02	0.0000e+00	0.0000e+00
+3.8852e+00	2.9010e+00	-3.5475e-03	-6.1713e-02	0.0000e+00	0.0000e+00
+4.3825e+00	2.9010e+00	-3.8556e-03	-5.6242e-02	1.0000e+00	0.0000e+00
+4.8798e+00	2.9010e+00	-6.4612e-03	-6.4347e-02	0.0000e+00	0.0000e+00
+4.0406e-01	2.4036e+00	8.3705e-04	-5.9559e-02	0.0000e+00	0.0000e+00
+9.0137e-01	2.4036e+00	1.4459e-03	-6.0987e-02	0.0000e+00	0.0000e+00
+1.3987e+00	2.4036e+00	-3.0819e-04	-5.8402e-02	1.0000e+00	0.0000e+00
+1.8960e+00	2.4036e+00	-7.8548e-03	-6.5643e-02	0.0000e+00	0.0000e+00
+2.3933e+00	2.4036e+00	-6.7928e-04	-6.3742e-02	0.0000e+00	0.0000e+00
+2.8906e+00	2.4036e+00	1.2726e-04	-4.9550e-02	0.0000e+00	0.0000e+00
+3.3879e+00	2.4036e+00	-6.4997e-03	-4.9535e-02	0.0000e+00	0.0000e+00
+3.8852e+00	2.4036e+00	-5.7793e-03	-5.4359e-02	0.0000e+00	0.0000e+00
+4.3825e+00	2.4036e+00	-7.7358e-03	-5.8984e-02	0.0000e+00	0.0000e+00
+4.8798e+00	2.4036e+00	-3.6829e-03	-5.6436e-02	1.0000e+00	0.0000e+00
+4.0406e-01	1.9063e+00	-8.4074e-03	-5.9327e-02	0.0000e+00	0.0000e+00
+9.0137e-01	1.9063e+00	2.5401e-03	-5.4095e-02	0.0000e+00	0.0000e+00
+1.3987e+00	1.9063e+00	-3.3883e-03	-5.7585e-02	0.0000e+00	0.0000e+00
+1.8960e+00	1.9063e+00	1.9393e-03	-5.9907e-02	0.0000e+00	0.0000e+00
+2.3933e+00	1.9063e+00	1.4774e-03	-6.0280e-02	0.0000e+00	0.0000e+00
+2.8906e+00	1.9063e+00	-1.7161e-03	-5.2136e-02	0.0000e+00	0.0000e+00
+3.3879e+00	1.9063e+00	-9.2400e-03	-4.8946e-02	0.0000e+00	0.0000e+00
+3.8852e+00	1.9063e+00	-7.1067e-03	-4.8031e-02	0.0000e+00	0.0000e+00
+4.3825e+00	1.9063e+00	-1.2505e-03	-5.2882e-02	0.0000e+00	0.0000e+00
+4.8798e+00	1.9063e+00	6.4614e-04	-5.0812e-02	0.0000e+00	0.0000e+00
+4.0406e-01	1.4090e+00	2.2486e-03	-5.0550e-02	0.0000e+00	0.0000e+00
+9.0137e-01	1.4090e+00	-6.7877e-03	-5.4202e-02	0.0000e+00	0.0000e+00
+1.3987e+00	1.4090e+00	-2.5288e-03	-6.3126e-02	0.0000e+00	0.0000e+00
+1.8960e+00	1.4090e+00	-5.9178e-04	-5.8457e-02	0.0000e+00	0.0000e+00
+2.3933e+00	1.4090e+00	5.8459e-03	-5.2184e-02	0.0000e+00	0.0000e+00
+2.8906e+00	1.4090e+00	5.4790e-03	-4.3826e-02	0.0000e+00	0.0000e+00
+3.3879e+00	1.4090e+00	-7.8645e-04	-5.1268e-02	0.0000e+00	0.0000e+00
+3.8852e+00	1.4090e+00	-5.9201e-03	-5.2166e-02	0.0000e+00	0.0000e+00
+4.3825e+00	1.4090e+00	-4.3095e-03	-5.2602e-02	0.0000e+00	0.0000e+00
+4.8798e+00	1.4090e+00	-2.2094e-03	-5.4975e-02	0.0000e+00	0.0000e+00
+4.0406e-01	9.1173e-01	9.7924e-03	-5.5734e-02	0.0000e+00	0.0000e+00
+9.0137e-01	9.1173e-01	7.5636e-03	-5.2847e-02	0.0000e+00	0.0000e+00
+1.3987e+00	9.1173e-01	9.0445e-03	-4.9824e-02	0.0000e+00	0.0000e+00
+1.8960e+00	9.1173e-01	1.4482e-03	-5.3496e-02	0.0000e+00	0.0000e+00
+2.3933e+00	9.1173e-01	-3.3418e-03	-5.3215e-02	0.0000e+00	0.0000e+00
+2.8906e+00	9.1173e-01	-5.2835e-03	-4.9696e-02	0.0000e+00	0.0000e+00
+3.3879e+00	9.1173e-01	-5.0878e-03	-5.0559e-02	0.0000e+00	0.0000e+00
+3.8852e+00	9.1173e-01	-5.8373e-03	-5.1331e-02	0.0000e+00	0.0000e+00
+4.3825e+00	9.1173e-01	-9.5435e-04	-5.1071e-02	0.0000e+00	0.0000e+00
+4.8798e+00	9.1173e-01	-1.7836e-03	-5.0735e-02	0.0000e+00	0.0000e+00
+4.0406e-01	4.1442e-01	7.7151e-03	-5.9321e-02	0.0000e+00	0.0000e+00
+9.0137e-01	4.1442e-01	1.0424e-02	-5.2889e-02	0.0000e+00	0.0000e+00
+1.3987e+00	4.1442e-01	-1.2132e-03	-5.1367e-02	0.0000e+00	0.0000e+00
+1.8960e+00	4.1442e-01	1.8418e-03	-5.2428e-02	1.0000e+00	0.0000e+00
+2.3933e+00	4.1442e-01	3.0095e-03	-4.7837e-02	0.0000e+00	0.0000e+00
+2.8906e+00	4.1442e-01	2.7171e-03	-5.1027e-02	0.0000e+00	0.0000e+00
+3.3879e+00	4.1442e-01	-5.2003e-03	-5.0522e-02	0.0000e+00	0.0000e+00
+3.8852e+00	4.1442e-01	-4.6899e-03	-5.3185e-02	0.0000e+00	0.0000e+00
+4.3825e+00	4.1442e-01	-2.9401e-03	-5.4006e-02	0.0000e+00	0.0000e+00
+4.8798e+00	4.1442e-01	2.9101e-03	-5.1380e-02	0.0000e+00	0.0000e+00

{openpiv-0.25.3 → openpiv-0.26.0}/openpiv/docs/conf.py

@@ -64,7 +64,7 @@ copyright = '2014, OpenPIV team'
 # built documents.
 #
 # The short X.Y version.
-version = '0.24.4a'
+version = '0.26.0'
 # The full version, including alpha/beta/rc tags.
 # release = '0.0.1a'
 

{openpiv-0.25.3 → openpiv-0.26.0}/openpiv/docs/index.rst

@@ -31,6 +31,7 @@ Contents:
    src/windef
    src/masking
    src/developers
+   src/fft_correlation_backends
    src/api_reference
    src/faq
 

{openpiv-0.25.3 → openpiv-0.26.0}/openpiv/docs/requirements.txt

@@ -1,4 +1,3 @@
-numpy>=1.9
 openpiv
 sphinx
 recommonmark

{openpiv-0.25.3 → openpiv-0.26.0}/openpiv/docs/src/developers.rst

@@ -63,3 +63,64 @@ If you need to install cv2::
     conda install -c conda-forge opencv
 
 
+Developing with or without Rust
+--------------------------------
+
+OpenPIV supports dual computational backends: **pure Python / SciPy** (default) and **compiled Rust** (via ``openpiv_rust``).
+
+Option A: Developing in Pure Python (without Rust)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You do not need a Rust compiler installed. Simply install OpenPIV in editable mode:
+
+.. code-block:: bash
+
+    poetry install
+    # or: pip install -e .
+
+All core functionality, single-pass, and multi-pass deformation will use the optimized
+``scipy.fft`` backend automatically.
+
+To run the test suite:
+
+.. code-block:: bash
+
+    pytest openpiv/test
+
+Option B: Developing with the Rust Extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have the Rust toolchain (``cargo``) installed:
+
+1. Install ``maturin``:
+
+   .. code-block:: bash
+
+       pip install maturin
+
+2. Compile and link ``openpiv_rust`` directly into your Python environment:
+
+   .. code-block:: bash
+
+       cd crates/openpiv_rust
+       maturin develop --release
+       cd ../..
+
+3. Verify that the Rust backend is active:
+
+   .. code-block:: bash
+
+       python -c "import openpiv_rust; print('Rust backend ready!')"
+
+Running the Performance Benchmarks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+OpenPIV includes a dedicated benchmark suite comparing cross-correlation, subpixel
+peak finding, and end-to-end multi-pass Windef across backends:
+
+.. code-block:: bash
+
+    python benchmarks/run_benchmarks.py
+
+
+

openpiv-0.26.0/openpiv/docs/src/fft_correlation_backends.rst

@@ -0,0 +1,162 @@
+FFT Correlation Backends & Performance Study
+============================================
+
+This document details the comparative study of 2D cross-correlation algorithms,
+backends, and performance characteristics in OpenPIV, focusing on both **Circular**
+and **Linear** correlation, `scipy.fft` (PocketFFT), and the `openpiv_rust` compiled backend.
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+Overview
+--------
+
+In Particle Image Velocimetry (PIV), cross-correlation between interrogation windows
+is the core computational step. For an image pair split into :math:`N` interrogation
+windows of size :math:`(H \times W)`, the correlation maps are computed using the
+Wiener-Khinchin theorem via Fast Fourier Transforms:
+
+.. math::
+
+   C = \mathcal{F}^{-1} \left( \mathcal{F}(I_B) \cdot \mathcal{F}^*(I_A) \right)
+
+OpenPIV supports two primary correlation paradigms:
+
+1. **Circular Correlation (Standard OpenPIV)**:
+   Assumes periodic boundary conditions (toroidal wraparound).
+   Inputs of size :math:`(N \times N)` yield correlation maps of size :math:`(N \times N)`.
+   No zero-padding is required.
+
+2. **Linear Correlation (Full / Extended)**:
+   Evaluates true spatial shift without periodic wraparound.
+   For windows of size :math:`s_1` and :math:`s_2`, the full linear correlation has size
+   :math:`(s_1 + s_2 - 1)`. To prevent time-domain aliasing, inputs must be zero-padded
+   to at least this size before applying the FFT.
+
+
+The 63x63 vs 64x64 Power-of-2 Finding
+-------------------------------------
+
+In previous versions of OpenPIV, linear correlation in ``openpiv.pyprocess.fft_correlate_images``
+computed the padded transform size as:
+
+.. code-block:: python
+
+   size = s1 + s2 - 1                                   # e.g., 32 + 32 - 1 = 63
+   fsize = 2 ** np.ceil(np.log2(size)).astype(int) - 1  # 64 - 1 = 63 (BUG!)
+
+Why 63 Disabled PocketFFT Optimization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SciPy delegates FFT operations to **PocketFFT** (written in C++ by Martin Reinecke),
+which includes hand-tuned AVX2/FMA vector kernels. However, these SIMD routines rely on
+smooth radix factors (powers of 2: 2, 4, 8, 16, 32, 64).
+
+1. Subtracting 1 produced an **odd composite size** :math:`63 = 3 \times 3 \times 7`.
+2. This forced PocketFFT into slow Bluestein/composite transforms, disabling SIMD vectorization.
+3. Furthermore, padding to 63 left an off-by-one boundary alignment when slicing the central window.
+
+The Power-of-2 Solution
+^^^^^^^^^^^^^^^^^^^^^^^
+
+By keeping the clean power-of-2 transform size :math:`fsize = 2^{\lceil \log_2(size) \rceil}`
+(e.g., :math:`64 \times 64` for :math:`32 \times 32` windows), PocketFFT achieves optimal
+SIMD execution speed.
+
+To recover the exact central correlation window matching ``scipy.signal.correlate``
+to machine precision (:math:`\le 10^{-13}`), the centered slice is:
+
+.. code-block:: python
+
+   # Exact power of 2 transform size
+   fsize = 2 ** np.ceil(np.log2(size)).astype(int)
+
+   # Centered slice extracting (s1) around the zero-displacement lag
+   fslice = (
+       slice(0, image_a.shape[0]),
+       slice(fsize[0] // 2 - s1[0] // 2, fsize[0] // 2 - s1[0] // 2 + s1[0]),
+       slice(fsize[1] // 2 - s1[1] // 2, fsize[1] // 2 - s1[1] // 2 + s1[1]),
+   )
+   f2a = conj(rfft2(image_a, fsize, axes=(-2, -1), workers=workers))
+   f2b = rfft2(image_b, fsize, axes=(-2, -1), workers=workers)
+   corr = fftshift(irfft2(f2a * f2b, axes=(-2, -1)).real, axes=(-2, -1))[fslice]
+
+
+Batched Multi-Threading in scipy.fft
+------------------------------------
+
+``scipy.fft`` supports a ``workers`` parameter (e.g., ``workers=-1`` for all logical cores).
+However, profiling reveals:
+
+* On large 2D or 3D volumes, PocketFFT multi-threading scales well.
+* On **batches of tiny 2D windows** (:math:`16 \times 16` or :math:`32 \times 32`),
+  thread synchronization overhead inside PocketFFT often negates multi-core gains
+  (scaling from :math:`1.0\times` to :math:`1.1\times`), because thread splitting occurs
+  per-transform rather than distributing independent windows across workers.
+
+
+The Rust Acceleration Engine (openpiv_rust)
+-------------------------------------------
+
+To overcome Python GIL overhead and achieve linear CPU scaling across window batches,
+OpenPIV provides an optional compiled Rust extension (``openpiv_rust``) built with
+PyO3, Rayon, and RealFFT.
+
+Key Architectural Optimizations in Rust
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. **Zero-Allocation Rayon Scratch Pool**:
+   Window transforms use ``par_chunks_exact_mut().for_each_init(...)``, pre-allocating
+   frequency buffers once per worker thread. For 961 windows, this eliminates over
+   8,600 heap allocations per pass.
+
+2. **Native Power-of-2 Real FFT**:
+   Uses ``realfft`` (Real-to-Complex forward and Complex-to-Real inverse), cutting
+   arithmetic and memory bandwidth by 50% compared to full complex transforms.
+
+3. **Batched Subpixel Peak Finding**:
+   In addition to cross-correlation, `openpiv_rust` provides
+   ``batch_correlation_to_displacement``, executing Gaussian/Centroid/Parabolic subpixel
+   peak fitting directly across all windows in parallel, yielding a **28x to 65x speedup**
+   over the nested Python loop.
+
+
+Benchmark Results
+-----------------
+
+Linear Correlation (225 windows of 32x32)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+============================================  ====================  ==================
+Implementation                                Runtime               Relative Speed
+============================================  ====================  ==================
+``scipy.signal.correlate`` (Python loop)      70.63 ms              1.0x (baseline)
+OpenPIV SciPy (legacy ``fsize=63``)           49.28 ms              1.4x
+OpenPIV SciPy (power-of-2 ``fsize=64``)       39.10 ms              1.8x
+**openpiv_rust** (Rayon + realfft)            **8.26 ms**           **8.5x**
+============================================  ====================  ==================
+
+Displacement Calculation (Peak Finding)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+============================================  ====================  ==================
+Grid / Windows                                Python Loop           openpiv_rust
+============================================  ====================  ==================
+225 windows (32x32)                           5.19 ms               **0.18 ms (28x)**
+961 windows (16x16)                           19.84 ms              **0.30 ms (65x)**
+============================================  ====================  ==================
+
+End-to-End Multi-Pass Windef (3 passes on 256x256 image)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* **SciPy backend**: 110.59 ms
+* **Rust backend (with subpixel Rust engine)**: **81.66 ms** (:math:`1.35\times` speedup)
+
+Conclusion & Usage Guidelines
+-----------------------------
+
+* For systems with compiled binary extensions available, set ``settings.backend = 'rust'``
+  to maximize throughput in both single-pass and multi-pass deformation workflows.
+* On pure Python / NumPy / SciPy environments, using the exact power-of-2 padding rule
+  ensures optimal PocketFFT vectorization while maintaining exact numerical consistency.

{openpiv-0.25.3 → openpiv-0.26.0}/openpiv/docs/src/installation_instruction.rst

@@ -19,23 +19,42 @@ The dependencies are:
 * `Python <http://python.org/>`_
 * `Scipy <http://numpy.scipy.org/>`_
 * `Numpy <http://www.scipy.org/>`_
-* `scikit-image <http://scikit-image.org/>`_
-
-On all platforms, the following Python distribution is recommended:
-
-* Anaconda <https://store.continuum.io/cshop/anaconda/>   
+* `scikit-image <http://scikit-image.org/>`_   
 
 
 Installation
 ============
 
-Use `conda` :: 
+Recommended: Use `uv` (fastest)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`uv <https://github.com/astral-sh/uv>`_ is a fast Python package installer and resolver written in Rust.
+It provides faster and more reliable package installation compared to traditional tools.
+
+To install OpenPIV with uv::
 
-    conda install -c alexlib openpiv
+    pip install uv
+    uv pip install openpiv
 
-Or use `pip` :: 
+Or use `pip` (standard)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
 
     pip install openpiv
+
+.. warning::
+    **Conda packages are no longer actively maintained.** The conda-forge package may be outdated.
+    
+    If you previously installed OpenPIV via conda, you can migrate to pip or uv::
+    
+        # Remove the conda package
+        conda remove openpiv
+        
+        # Install with pip or uv
+        pip install openpiv
+        # or
+        uv pip install openpiv
     
 Get OpenPIV source code!
 ========================

{openpiv-0.25.3 → openpiv-0.26.0}/openpiv/filters.py

@@ -44,8 +44,13 @@ def _gaussian_kernel(half_width: int=1)-> np.ndarray:
 
     """
     # size = int(half_width)
-    x, y = np.mgrid[-half_width:half_width + 1, -half_width:half_width + 1]
-    g = np.exp(-(x ** 2 / float(half_width) + y ** 2 / float(half_width)))
+
+    if half_width == 0:
+        return 1
+    else: 
+        x, y = np.mgrid[-half_width:half_width + 1, -half_width:half_width + 1]
+        g = np.exp(-(x ** 2 / float(half_width) + y ** 2 / float(half_width)))
+    
     return g / g.sum()
 
 
@@ -169,21 +174,21 @@ def replace_outliers(
     # regardless the grid_mask (which is a user-provided masked region)
 
     
-    if not isinstance(u, np.ma.MaskedArray):
-        u = np.ma.masked_array(u, mask=np.ma.nomask)
-        
-    # store grid_mask for reinforcement
-    grid_mask = u.mask.copy()
-
-    u[flags] = np.nan
-    v[flags] = np.nan
+    has_mask = isinstance(u, np.ma.MaskedArray)
+    grid_mask = np.ma.getmaskarray(u).copy() if has_mask else np.ma.nomask
+
+    u_data = np.array(np.ma.getdata(u), copy=True)
+    v_data = np.array(np.ma.getdata(v), copy=True)
+
+    u_data[flags] = np.nan
+    v_data[flags] = np.nan
     
     uf = replace_nans(
-        u, method=method, max_iter=max_iter, tol=tol,
+        u_data, method=method, max_iter=max_iter, tol=tol,
         kernel_size=kernel_size
     )
     vf = replace_nans(
-        v, method=method, max_iter=max_iter, tol=tol,
+        v_data, method=method, max_iter=max_iter, tol=tol,
         kernel_size=kernel_size
     )
 
@@ -192,9 +197,10 @@ def replace_outliers(
     vf = np.ma.masked_array(vf, mask=grid_mask)
 
     if isinstance(w, np.ndarray):
-        w[flags] = np.nan
+        w_data = np.array(np.ma.getdata(w), copy=True)
+        w_data[flags] = np.nan
         wf = replace_nans(
-            w, method=method, max_iter=max_iter, tol=tol,
+            w_data, method=method, max_iter=max_iter, tol=tol,
             kernel_size=kernel_size
         )
         wf = np.ma.masked_array(wf, mask=grid_mask)