[WIP] #220 calibration

.gitignore

@@ -31,3 +31,11 @@ crates/**/target/
 dist/
 *.whl
 /piv_explainer
+/.agents
+/.claude
+skills-lock.json
+
+# artifacts written by the tests into the working directory
+/minimized
+/saved_params
+/dummy

CLAUDE.md

@@ -10,12 +10,18 @@ OpenPIV is a Python library for Particle Image Velocimetry (PIV) analysis of flu
 
 ### Bootstrap and Install Dependencies
 - Use Poetry: `pip install poetry` then `poetry install` (~10 seconds). All development commands should use `poetry run <command>`.
+- The Rust acceleration is optional: `maturin develop --release -m crates/openpiv_rust/Cargo.toml` builds it in place. Without it the SciPy backend is used.
 
 ### Build and Test
-- Run tests: `poetry run pytest openpiv -v` — ~10 seconds, 216 tests pass.
+- **Always run the tests and ruff before committing.** Both are required, a green
+  test suite alone is not enough.
+- Run tests: `poetry run pytest openpiv -v` — ~10 seconds, ~350 tests pass.
 - Run a single test file: `poetry run pytest openpiv/test/test_process.py -v`
+- Lint: `poetry run ruff check .` (config in `pyproject.toml`, `[tool.ruff]`).
+  `poetry run ruff check . --fix` applies the safe fixes; the unsafe ones
+  (`--unsafe-fixes`) can change runtime behaviour and need a test run afterwards.
 - Import test: `poetry run python -c "import openpiv; print('OpenPIV imported successfully')"`
-- No linting tools are configured (no black, flake8, etc.).
+- No formatting tool is configured; ruff's linter is the style gate.
 - `python setup.py build_ext --inplace` is a legacy no-op: all Cython (`.pyx`) files have been removed and converted to pure Python, despite the package description still mentioning "Cython modules".
 
 ### Run Example Workflows
@@ -38,6 +44,8 @@ OpenPIV is a Python library for Particle Image Velocimetry (PIV) analysis of flu
 - `preprocess.py` — image preprocessing (background subtraction, masking).
 - `smoothn.py` — robust spline smoothing; a Python port of `smoothn.m` (D. Garcia / Prof. Lewis) bundled for convenience — it is not covered by the OpenPIV license, see README for attribution.
 - `phase_separation.py` — solid-phase / liquid-tracer separation utilities.
+- `calibration/` — camera calibration: `dlt_model/`, `pinhole_model/`, `poly_model/` (Soloff) and `stereo.py` (common world grid, dewarp, disparity self-calibration, 3C reconstruction). The sub-package uses duck typing: a camera needs `project_points`, `project_to_z`, `resolution` and `dtype`.
+- `examples/stereo/` — runnable stereo-PIV example on DaVis data: `config.py` (`StereoConfig`), `davis.py` (DaVis XML exports), `frames.py` (`.ims`/`.im7` via the optional `readim7` dependency), `pipeline.py` (the steps), `__main__.py` (CLI: `info`, `calibrate`, `dewarp`, `disparity`, `piv`, `all`).
 
 ### Typical call chains
 - Quick path: `piv.simple_piv(frame_a, frame_b, plot=False)` → `(x, y, u, v, s2n)`.
@@ -46,7 +54,7 @@ OpenPIV is a Python library for Particle Image Velocimetry (PIV) analysis of flu
 - Batch/multi-pass: build a `PIVSettings`, then `windef.piv(settings)`.
 
 ### Tests
-- `openpiv/test/` (~216 tests). `conftest.py` forces the `Agg` matplotlib backend and patches `plt.show` so tests run headless — keep that in mind if adding plotting code.
+- `openpiv/test/` (~350 tests). `conftest.py` forces the `Agg` matplotlib backend and patches `plt.show` so tests run headless — keep that in mind if adding plotting code.
 
 ### Packaging notes
 - Package name on PyPI is `OpenPIV`; import name is lowercase `openpiv`.

benchmarks/fft_backends/bench_repeated_calls.py

@@ -4,6 +4,7 @@
 its upfront planning cost. Throwaway script for explore/fft-backends.
 """
 import time
+
 import numpy as np
 
 N_CALLS = 40  # ~ processing 40 image pairs at one pass/window size

benchmarks/fft_backends/bench_single_call.py

@@ -4,6 +4,7 @@
 branch. Run with: uv run python scripts_bench_fft.py
 """
 import time
+
 import numpy as np
 
 
@@ -95,7 +96,7 @@ def main():
                 dt, out = bench(a, b, run)
                 results[backend_name] = (dt, out)
                 print(f"  {backend_name:20s} {dt*1000:8.2f} ms")
-            except Exception as e:  # noqa: BLE001 - benchmark script, report and continue
+            except Exception as e:
                 print(f"  {backend_name:20s} FAILED: {e}")
 
         if "scipy.fft" in results:

benchmarks/fft_backends/benchmark_windef.py

@@ -1,12 +1,15 @@
-import time
-import tempfile
 import pathlib
+import tempfile
+import time
+
 import numpy as np
 from imageio.v3 import imwrite
+
 from openpiv import windef
 from openpiv.settings import PIVSettings
 from openpiv.test import test_process
 
+
 def run_multigrid(frame_a, frame_b, backend, n_runs=3):
     settings = PIVSettings()
     settings.windowsizes = (64, 32, 16)
@@ -16,10 +19,10 @@ def run_multigrid(frame_a, frame_b, backend, n_runs=3):
     settings.sig2noise_validate = False
     settings.show_all_plots = False
     settings.show_plot = False
-    
+
     # Warmup
     windef.multigrid_windef(frame_a, frame_b, settings)
-    
+
     times = []
     for _ in range(n_runs):
         t0 = time.perf_counter()
@@ -52,14 +55,14 @@ def run_mp(frame_a, frame_b, backend):
         settings.save_plot = False
         settings.show_all_plots = False
         settings.sig2noise_validate = False
-        
+
         t0 = time.perf_counter()
         windef.piv(settings)
         return (time.perf_counter() - t0) * 1000.0
 
 def main():
     frame_a, frame_b = test_process.create_pair(image_size=256)
-    
+
     print("=" * 60)
     print("  BENCHMARK: Multigrid Window Deformation (256x256, 3 passes)")
     print("=" * 60)

benchmarks/fft_backends/run_piv_quiver_demo.py

@@ -1,12 +1,14 @@
 import os
 import time
-import numpy as np
-import matplotlib.pyplot as plt
-from pathlib import Path
 from importlib.resources import files
-from openpiv import pyprocess, tools, validation, filters
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
 import openpiv_rust
 
+from openpiv import filters, pyprocess, tools, validation
+
 ARTIFACT_DIR = Path(r"C:\Users\alex\.gemini\antigravity-cli\brain\371a4578-c887-4c4a-bba3-7bbfb7f1997c")
 ARTIFACT_DIR.mkdir(parents=True, exist_ok=True)
 
@@ -27,7 +29,7 @@ def run_real_piv_demo():
 
     # 1. Scipy correlation
     t0 = time.perf_counter()
-    scipy_corr = pyprocess.fft_correlate_images(aa, bb, correlation_method="circular", normalized_correlation=False)
+    pyprocess.fft_correlate_images(aa, bb, correlation_method="circular", normalized_correlation=False)
     t_scipy_corr = time.perf_counter() - t0
 
     # 2. Rust correlation
@@ -71,7 +73,7 @@ def run_real_piv_demo():
 
     # Plot Quiver Comparison
     fig, axes = plt.subplots(1, 3, figsize=(18, 5.5), facecolor="white")
-    
+
     # Panel 1: Scipy
     ax = axes[0]
     ax.imshow(frame_a, cmap="gray", alpha=0.5, origin="upper")
@@ -111,7 +113,7 @@ def run_synthetic_vortex_demo():
     print("\n=== Running Synthetic Vortex Quiver Demo ===")
     np.random.seed(42)
     img_h, img_w = 256, 256
-    
+
     n_particles = 4000
     px = np.random.uniform(0, img_w, n_particles)
     py = np.random.uniform(0, img_h, n_particles)
@@ -124,31 +126,30 @@ def run_synthetic_vortex_demo():
     ry = py - cy
     r = np.sqrt(rx**2 + ry**2) + 1e-6
     v_theta = gamma * r / (r0**2 + r**2)
-    
+
     dx_particles = -v_theta * (ry / r)
     dy_particles = v_theta * (rx / r)
 
     frame_a = np.zeros((img_h, img_w), dtype=np.float32)
     frame_b = np.zeros((img_h, img_w), dtype=np.float32)
 
     for i in range(n_particles):
-        x0, y0 = int(round(px[i])), int(round(py[i]))
+        x0, y0 = round(px[i]), round(py[i])
         if 1 <= x0 < img_w - 1 and 1 <= y0 < img_h - 1:
             frame_a[y0, x0] += 200.0
             frame_a[y0+1, x0] += 100.0
             frame_a[y0-1, x0] += 100.0
             frame_a[y0, x0+1] += 100.0
             frame_a[y0, x0-1] += 100.0
 
-        x1, y1 = int(round(px[i] + dx_particles[i])), int(round(py[i] + dy_particles[i]))
+        x1, y1 = round(px[i] + dx_particles[i]), round(py[i] + dy_particles[i])
         if 1 <= x1 < img_w - 1 and 1 <= y1 < img_h - 1:
             frame_b[y1, x1] += 200.0
             frame_b[y1+1, x1] += 100.0
             frame_b[y1-1, x1] += 100.0
             frame_b[y1, x1+1] += 100.0
             frame_b[y1, x1-1] += 100.0
 
-    window_size = 32
     overlap = 16
     search_area_size = 32
 
@@ -158,7 +159,7 @@ def run_synthetic_vortex_demo():
 
     # Scipy correlation
     t0 = time.perf_counter()
-    scipy_corr = pyprocess.fft_correlate_images(aa, bb, correlation_method="circular", normalized_correlation=False)
+    pyprocess.fft_correlate_images(aa, bb, correlation_method="circular", normalized_correlation=False)
     t_scipy_corr = time.perf_counter() - t0
 
     # Rust correlation
@@ -173,7 +174,7 @@ def run_synthetic_vortex_demo():
     x, y = pyprocess.get_coordinates(image_size=frame_a.shape, search_area_size=search_area_size, overlap=overlap)
 
     fig, axes = plt.subplots(1, 2, figsize=(14, 6), facecolor="white")
-    
+
     # Panel 1: Rust Quiver Field
     ax = axes[0]
     ax.imshow(frame_a, cmap="gray", alpha=0.5, origin="upper")

benchmarks/fft_backends/test_rust_fft.py

@@ -1,9 +1,11 @@
 import sys
 import time
+
 import numpy as np
-from openpiv import pyprocess
 import openpiv_rust
 
+from openpiv import pyprocess
+
 print('=== OpenPIV Rust vs scipy.fft Benchmark & Validation ===', flush=True)
 
 # Shapes representing real PIV interrogation window batches

benchmarks/run_benchmarks.py

@@ -7,7 +7,9 @@
     python benchmarks/run_benchmarks.py
 """
 import time
+
 import numpy as np
+
 from openpiv import pyprocess, validation, windef
 from openpiv.settings import PIVSettings
 

dummy

@@ -0,0 +1,42 @@
+dummy
+512 512 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+1.0 1.0 
+0.0 1.0 
+2.0 3.0 
+4.0 5.0 
+6.0 7.0 
+8.0 9.0 
+10.0 11.0 
+12.0 13.0 
+14.0 15.0 
+16.0 17.0 
+18.0 19.0 
+20.0 21.0 
+22.0 23.0 
+24.0 25.0 
+26.0 27.0 
+28.0 29.0 
+30.0 31.0 
+32.0 33.0 
+34.0 35.0 
+36.0 37.0 
+38.0 39.0 
+float64

openpiv/PIV_3D_plotting.py

@@ -3,11 +3,11 @@
 """
 
 
+from itertools import chain
+
 import matplotlib
 import matplotlib.pyplot as plt
 import numpy as np
-from itertools import chain
-from mpl_toolkits.mplot3d import Axes3D
 
 
 def set_axes_equal(ax):
@@ -21,8 +21,8 @@ def set_axes_equal(ax):
       Parameters
     ----------
      ax: matplotlib.axes object
-       
-     
+
+
     """
 
     x_limits = ax.get_xlim3d()
@@ -202,7 +202,7 @@ def quiver_3D(
     arrow_scale=0.15,
     equal_ax=True,
 ):
-    """ 
+    """
     Displaying 3D deformation fields vector arrows
 
     Parameters
@@ -217,33 +217,33 @@ def quiver_3D(
 
      mask_filtered, boolean 3d ndarray or 1d ndarray
           Array, or list with same dimensions as the deformations. Defines the area where deformations are drawn
-          
+
      filter_def: float
           Filter that prevents the display of deformations arrows with length < filter_def
-          
+
      filter_reg: tuple,list or int
           Filter that prevents the display of every i-th deformations arrows separatly alon each axis.
           filter_reg=(2,2,2) means that only every second arrow along x,y z axis is displayed leading to
           a total reduction of displayed arrows by a factor of 8. filter_reg=3 is interpreted
           as (3,3,3).
-          
+
      cmap: string
           matplotlib colorbar that defines the coloring of the arrow
-          
+
      quiv_args: dict
          Dictionary with kwargs passed on to the matplotlib quiver function.
 
      vmin,vmax: float
          Upper and lower bounds for the colormap. Works like vmin and vmax in plt.imshow().
-         
+
     arrow_scale: float
-        Automatic scaling of the quiver arrows so that the longest arrow has the 
+        Automatic scaling of the quiver arrows so that the longest arrow has the
         length axis length * arrow_scale. Arrow length can alternatively be set by
-        passing a "lenght" argument in quiv_args. 
-    
+        passing a "lenght" argument in quiv_args.
+
     equal_axes: bool
         resize the figure axis so that they are have equal scaling.
-    
+
 
     Returns
     -------
@@ -283,8 +283,7 @@ def quiver_3D(
             x, y, z = np.indices(u.shape)
         else:
             raise ValueError(
-                "displacement data has wrong number of dimensions (%s). Use 1d array, list, or 3d array."
-                % str(len(u.shape))
+                f"displacement data has wrong number of dimensions ({len(u.shape)!s}). Use 1d array, list, or 3d array."
             )
 
     # conversion to array

openpiv/__init__.py

@@ -1,6 +1,5 @@
 from importlib.metadata import version
 
-
 __version__ = version("OpenPIV")