Openpiv

frame_a = tools.imread( "image_a.bmp" ) frame_b = tools.imread( "image_b.bmp" )

Run PIV analysis

u, v, sig2noise = pyprocess.extended_search_area_piv( frame_a.astype(np.int32), frame_b.astype(np.int32), window_size= 32 , overlap= 12 , dt= 0.02 , search_area_size= 38 , )

Get coordinates

x, y = pyprocess.get_coordinates( image_size=frame_a.shape, search_area_size= 38 , overlap= 12 , )

Validate and filter

flags = validation.sig2noise_val(sig2noise, threshold= 1.05 ) u, v = filters.replace_outliers(u, v, flags, method= "localmean" , max_iter= 3 , kernel_size= 2 )

Scale to physical units

x, y, u, v = scaling.uniform(x, y, u, v, scaling_factor= 96.52 )

Save results

tools.save( "vectors.txt" , x, y, u, v, flags) Core Concepts PIV Fundamentals Particle Image Velocimetry (PIV) is an optical method for measuring fluid flow velocities. It works by tracking illuminated particles in a flow between two consecutive images. Key principles: Seed the flow with tracer particles Capture two frames with known time separation Use cross-correlation to find displacement Convert pixel displacement to physical velocity Process flow: Capture image pair (frame_a, frame_b) with time delta dt Divide images into interrogation windows Cross-correlate windows to find peak displacement Validate vectors using signal-to-noise ratio Replace erroneous vectors with interpolated values Scale to physical units (pixels → meters) Interrogation Window Parameters Window Size: Size of the correlation window in pixels (typically 16-128 px). Larger windows give better accuracy but lower spatial resolution. Overlap: Number of pixels shared between adjacent windows (typically 50-75% of window_size). Higher overlap increases resolution but computational cost. Search Area: Size of the area in second frame to search for matching (typically window_size + 4-8 pixels for subpixel accuracy). Relationship: Higher window_size → better accuracy, lower resolution Higher overlap → higher resolution, more computation Search area > window_size allows for larger displacements Signal-to-Noise Ratio The sig2noise ratio measures the reliability of cross-correlation peaks: Higher values indicate more confident vector matches Typical threshold: 1.05 to 1.3 (lower = more strict) Vectors below threshold are flagged as invalid

Validate using sig2noise

flags = validation.sig2noise_val(sig2noise, threshold= 1.05 )

flags = 0 means valid, flags != 0 means invalid

Common Operations Basic PIV Processing from openpiv import tools, pyprocess, validation, filters, scaling import numpy as np

Load and process

frame_a = tools.imread( "frame_a.tif" ) frame_b = tools.imread( "frame_b.tif" )

Run cross-correlation

u, v, sig2noise = pyprocess.extended_search_area_piv( frame_a, frame_b, window_size= 32 , overlap= 16 , dt= 0.02 , search_area_size= 38 , )

Get grid coordinates

x, y = pyprocess.get_coordinates( image_size=frame_a.shape, search_area_size= 38 , overlap= 16 , )

Validate

flags = validation.sig2noise_val(sig2noise, threshold= 1.2 )

Replace outliers

u, v = filters.replace_outliers(u, v, flags, method= "localmean" )

Scale to physical units

x, y, u, v = scaling.uniform(x, y, u, v, scaling_factor= 96.52 )

Transform coordinates

x, y, u, v = tools.transform_coordinates(x, y, u, v)

Mask invalid vectors

u = np.where(flags == 0 , u, np.nan) v = np.where(flags == 0 , v, np.nan) Dynamic Masking Apply masking to exclude regions with high luminosity or reflections: from openpiv import masking

Apply dynamic mask (Shirai method)

mask_a = masking.dynamic_masking(frame_a, method= "shirai" ) mask_b = masking.dynamic_masking(frame_b, method= "shirai" )

frame_a_masked = frame_a * mask_a frame_b_masked = frame_b * mask_b Multi-Pass Processing For better accuracy with large displacements, use multiple passes with decreasing window sizes:

First pass - larger windows

u1, v1, sig2noise1 = pyprocess.extended_search_area_piv( frame_a, frame_b, window_size= 64 , overlap= 32 , search_area_size= 64 , )

Second pass - smaller windows with initial guess

u2, v2, sig2noise2 = pyprocess.iterative_warping_piv( frame_a, frame_b, window_size= 32 , overlap= 16 , u0=u1, v0=v1,

Use first pass as initial guess

) Validation and Post-Processing Validation Methods Signal-to-Noise Ratio Validation: flags = validation.sig2noise_val(sig2noise, threshold= 1.05 ) Global Range Validation: flags = validation.global_val(u, v, u_threshold= 10 , v_threshold= 10 ) Local Median Validation: flags = validation.local_median_val(u, v, u_threshold= 2.5 , v_threshold= 2.5 ) Combined Validation: flags = validation.sig2noise_val(sig2noise, threshold= 1.05 ) flags = np.maximum(flags, validation.local_median_val(u, v)) Outlier Replacement Replace invalid vectors with interpolated values:

Local mean replacement

u, v = filters.replace_outliers( u, v, flags, method= "localmean" , max_iter= 3 , kernel_size= 2 , )

Disc replacement (neighboring vectors)

u, v = filters.replace_outliers( u, v, flags, method= "disc" , max_iter= 3 , kernel_size= 2 , ) Smoothing Apply smoothing to reduce noise in velocity fields: from openpiv import smooth

u_smooth = smooth.smooth(u, kernel_size= 3 , order= 2 ) v_smooth = smooth.smooth(v, kernel_size= 3 , order= 2 ) Visualization Vector Field Plotting import matplotlib.pyplot as plt from openpiv import tools

Plot on image

fig, ax = plt.subplots(figsize=( 8 , 8 )) tools.display_vector_field( "vectors.txt" , ax=ax, scaling_factor= 96.52 , scale= 50 , width= 0.0035 , on_img= True , image_name= "frame_a.bmp" , ) plt.savefig( "vector_field.png" , dpi= 150 ) plt.close() Custom Visualization import matplotlib.pyplot as plt import numpy as np

valid_mask = ~np.isnan(u)

fig, axes = plt.subplots( 1 , 3 , figsize=( 15 , 5 ))

Velocity magnitude

mag = np.sqrt(u** 2

• v** 2 ) im0 = axes[ 0 ].imshow(mag, cmap= 'viridis' ) axes[ 0 ].set_title( 'Velocity Magnitude' ) plt.colorbar(im0, ax=axes[ 0 ])

U component

im1 = axes[ 1 ].imshow(u, cmap= 'RdBu_r' ) axes[ 1 ].set_title( 'U Velocity' ) plt.colorbar(im1, ax=axes[ 1 ])

V component

im2 = axes[ 2 ].imshow(v, cmap= 'RdBu_r' ) axes[ 2 ].set_title( 'V Velocity' ) plt.colorbar(im2, ax=axes[ 2 ])

plt.tight_layout() plt.savefig( "velocity_components.png" ) plt.close() Analysis Functions Vorticity Calculation def compute_vorticity ( u, v, dx= 1.0 ): """Compute vorticity from velocity field.""" dv_dx = np.gradient(v, dx, axis= 1 ) du_dy = np.gradient(u, dx, axis= 0 ) return dv_dx - du_dy

vorticity = compute_vorticity(u, v, dx= 1.0 ) Strain Rate Computation def compute_strain ( u, v, dx= 1.0 ): """Compute strain rate tensor components.""" du_dx = np.gradient(u, dx, axis= 1 ) du_dy = np.gradient(u, dx, axis= 0 ) dv_dx = np.gradient(v, dx, axis= 1 ) dv_dy = np.gradient(v, dx, axis= 0 )

Strain rate tensor

exx = du_dx eyy = dv_dy exy = 0.5

• (du_dy + dv_dx) return exx, eyy, exy Turbulence Statistics def compute_statistics ( u, v ): """Compute turbulence statistics.""" u_mean = np.nanmean(u) v_mean = np.nanmean(v)

  u_prime = u - u_mean v_prime = v - v_mean

  rms_u = np.nanstd(u_prime) rms_v = np.nanstd(v_prime)

  turbulent_kinetic_energy = 0.5

• (rms_u** 2

• rms_v** 2 ) return { 'u_mean' : u_mean, 'v_mean' : v_mean, 'rms_u' : rms_u, 'rms_v' : rms_v, 'tke' : turbulent_kinetic_energy, } CLI Usage Command Line Interface

Process image pair

python -m openpiv_skills.runner --image img1.bmp --image img2.bmp --output_dir results --verbose

With custom parameters

python -m openpiv_skills.runner
--image frame_a.bmp
--image frame_b.bmp
--output_dir results
--window_size 32
--overlap 16
--dt 0.02
--scaling 96.52
--verbose CLI Options Option Default Description --image required Image file (specify twice for pair) --output_dir results Output directory --algorithm openpiv_piv PIV algorithm choice --mask none Mask type: none, dynamic, static --window_size 32 Interrogation window size (px) --overlap 12 Window overlap (px) --search_area 38 Search area size (px) --dt 0.02 Time between frames (s) --scaling 96.52 Scaling factor (pixels/meter) --verbose False Print progress messages Output Files Generated Files vectors.txt

• Text file with x, y, u, v, flags columns params.npz
• NumPy archive with x, y, u, v, flags arrays vector_field.png
• Vector field visualization on image vectors.txt Format x y u v flags 0.0 0.0 0.125 -0.034 0 4.0 0.0 0.132 -0.041 0 ... Best Practices Parameter Selection Window Size: Use 32x32 for typical applications Larger (64, 128) for high accuracy, lower resolution Smaller (16, 24) for higher resolution, more noise Overlap: 50-75% of window size is typical Higher overlap → smoother results, more computation Threshold: 1.05 for strict validation (more vectors rejected) 1.2 for relaxed validation (more vectors kept) Scaling Factor: Calibrate using known reference (e.g., calibration grid) Common values: 96.52 px/mm for certain setups Image Quality Ensure particles are visible and well-distributed Avoid saturated regions (overexposure) Use adequate particle density (5-10 particles per window) Minimize background noise Processing Tips Start with default parameters , then tune based on results Check sig2noise ratio
• low values indicate poor correlation Visualize early
• inspect vector field for obvious issues Use multi-pass for flows with large velocity gradients Apply masking to exclude regions of interest Resources This skill includes comprehensive reference documentation: references/ advanced_algorithms.md
• Advanced PIV algorithms, synthetic aperture, tomographic PIV Load these references as needed when users require detailed information about specific topics.