dpivsoft.DPIV

dpivsoft.DPIV.processing(Img1, Img2)

Run the complete two-pass PIV algorithm on an image pair (CPU implementation). Processing options are taken from the global Parameters class.

Parameters:

• Img1 (2d np.ndarray) – First and second frames of the PIV pair.

• Img2 (2d np.ndarray) – First and second frames of the PIV pair.

Returns:

• x_2, y_2 (2d np.ndarray) – Coordinates of the final (second-pass) grid in pixels.

• u_2, v_2 (2d np.ndarray) – Displacement field on the final grid in pixels.

dpivsoft.DPIV.corrFFT1(Img1, Img2)

First PIV pass: FFT-based cross-correlation on the coarse grid, without window deformation.

Parameters:

• Img1 (2d np.ndarray) – Image pair.

• Img2 (2d np.ndarray) – Image pair.

Returns:

• x_1, y_1 (2d np.ndarray) – First-pass grid coordinates in pixels.

• u_1, v_1 (2d np.ndarray) – Displacement field on the first-pass grid in pixels.

dpivsoft.DPIV.corrFFT1bis(Img1, Img2, x_1, y_1, u_1, v_1)

Optional extra iterations of the first pass (Parameters.no_iter_1 > 1): median filtering plus window deformation, refining the corrFFT1 result on the same grid.

Parameters:

• Img1 (2d np.ndarray) – Image pair.

• Img2 (2d np.ndarray) – Image pair.

• x_1 (2d np.ndarray) – Grid and displacement field from corrFFT1.

• y_1 (2d np.ndarray) – Grid and displacement field from corrFFT1.

• u_1 (2d np.ndarray) – Grid and displacement field from corrFFT1.

• v_1 (2d np.ndarray) – Grid and displacement field from corrFFT1.

Returns:

x_1, y_1, u_1, v_1 – Refined displacement field on the same first-pass grid.

Return type:

2d np.ndarray

dpivsoft.DPIV.corrFFT2(Img1, Img2, x_1, y_1, u_1, v_1)

Second PIV pass: interpolate the first-pass result onto the finer second grid, then iterate FFT cross-correlation with window deformation until sub-pixel convergence (at most Parameters.no_iter_2 iterations per point).

Parameters:

• Img1 (2d np.ndarray) – Image pair.

• Img2 (2d np.ndarray) – Image pair.

• x_1 (2d np.ndarray) – Grid and displacement field from the first pass.

• y_1 (2d np.ndarray) – Grid and displacement field from the first pass.

• u_1 (2d np.ndarray) – Grid and displacement field from the first pass.

• v_1 (2d np.ndarray) – Grid and displacement field from the first pass.

Returns:

• x_2, y_2 (2d np.ndarray) – Second-pass grid coordinates in pixels.

• u_2, v_2 (2d np.ndarray) – Displacement field on the second-pass grid in pixels.

dpivsoft.DPIV.corrDirect1(Img1, Img2)

First PIV pass using direct (spatial) cross-correlation instead of FFT: the correlation is evaluated only inside the search window.

Parameters:

• Img1 (2d np.ndarray) – Image pair.

• Img2 (2d np.ndarray) – Image pair.

Returns:

• x_1, y_1 (2d np.ndarray) – First-pass grid coordinates in pixels.

• u_1, v_1 (2d np.ndarray) – Displacement field on the first-pass grid in pixels.

• box_origin_x_1 (2d np.ndarray) – x origin of each correlation box in pixels.

dpivsoft.DPIV.gauss_subpixel(a, b, c)

Three-point Gaussian sub-pixel peak estimator.

Given the peak sample b and its two neighbours a (left/below) and c (right/above), return the sub-pixel offset of the peak relative to b. Returns 0.0 when any sample is non-positive or the curvature is degenerate (estimator undefined).

dpivsoft.DPIV.find_peaks(correlation, window_x, window_y, westerweel=1, peak_ratio=None, return_valid=False)

Locate the correlation peak with sub-pixel accuracy.

The two highest peaks are found; the one with the larger surrounding correlation sum is kept and refined with a three-point Gaussian estimator (see gauss_subpixel).

Parameters:

• correlation (2d np.ndarray) – Cross-correlation map of one interrogation window.

• window_x (int) – Size in pixels of the search window around the map center.

• window_y (int) – Size in pixels of the search window around the map center.

• westerweel (int, optional) – If nonzero (default), apply the Westerweel bias correction to the peak neighbourhood before the sub-pixel fit.

• peak_ratio (float, optional) – Maximum allowed second/first peak-height ratio; defaults to Parameters.peak_ratio.

• return_valid (bool, optional) – If True, also return whether the peak passed the peak-ratio test. Used by the stereo disparity correction, which NaNs ambiguous windows; the main pipeline leaves it False and relies on median_filter instead.

Returns:

• epsilon_x, epsilon_y (float) – Sub-pixel offsets of the peak.

• max_col, max_row (int) – Integer peak position (column, row).

• valid (bool) – Only returned if return_valid is True.

dpivsoft.DPIV.median_filter(u, v, limit)

Remove spurious vectors by comparison with the local median (median test). Interior points use the 8 surrounding neighbours; edge and corner points use reduced neighbourhoods.

Parameters:

• u (2d np.ndarray) – Velocity/displacement components.

• v (2d np.ndarray) – Velocity/displacement components.

• limit (float) – Rejection threshold: a vector is replaced by the local median when it deviates from it by more than limit times the median magnitude.

Returns:

• uf, vf (2d np.ndarray) – Filtered velocity field.

• err_vect (float) – Number of vectors replaced.

dpivsoft.DPIV.gaussian_filter(Image_1, Image_2, gaussian_size)

Smooth both images with the Gaussian kernel built by gaussian_kernel. Used only on the first pass.

dpivsoft.DPIV.gaussian_kernel(gaussian_size)

Build the normalized 2d Gaussian convolution kernel of width gaussian_size (pixels) used to pre-filter the images.

dpivsoft.DPIV.jacobian_matrix(u, v, x, y, no_box_x, no_box_y)

Compute the velocity gradients (du/dx, du/dy, dv/dx, dv/dy) on the PIV grid: centered differences in the interior, one-sided at the boundaries, smoothed with a 3x3 box filter.

Returns:

du_dx, du_dy, dv_dx, dv_dy – Velocity gradients on the same grid.

Return type:

2d np.ndarray

dpivsoft.DPIV.interpolations(du_dx, du_dy, dv_dx, dv_dy, u_1, v_1, x_1, y_1, x_2, y_2, no_box)

Interpolate the first-pass velocity field and its gradients onto the second-pass grid (linear scattered-data interpolation).

Returns:

• du_dx, du_dy, dv_dx, dv_dy, u_2, v_2 (2d np.ndarray) – Fields interpolated onto the second grid.

• x_2, y_2 (2d np.ndarray) – Second grid as meshgrid arrays.

dpivsoft.DPIV.translated_pixels(i_index, j_index, u_index, v_index, Width, Height, box_size_x, box_size_y)

Compute the symmetrically shifted (+-displacement/2) pixel positions used to deform both sub-images. If a shift would fall outside the image, the displacement is discarded (no shift) in that direction.

Returns:

• i_frac_1, j_frac_1, i_frac_2, j_frac_2 (2d np.ndarray) – Fractional pixel offsets for the bilinear interpolation.

• j_index_1, i_index_1, j_index_2, i_index_2 (2d np.ndarray) – Shifted pixel positions for sub-images 1 and 2.

dpivsoft.DPIV.deform_image(Img1, Img2, Width, Height, box_origin_x, box_origin_y, i_matrix, j_matrix, box_size_x, box_size_y, u, v, du_dx, du_dy, dv_dx, dv_dy, i, j)

Build the two interrogation sub-windows of box (j, i), each deformed by half the local velocity field (bilinear interpolation) and mean-subtracted.

Returns:

• SubImg1, SubImg2 (2d np.ndarray) – Deformed, mean-subtracted sub-images.

• u_index, v_index (2d np.ndarray) – Per-pixel displacement predicted from the velocity and its gradients (added back to the correlation result).

dpivsoft.DPIV.weight_function(i_matrix, j_matrix, box_size_x, box_size_y)

Separable quadratic weighting function that de-emphasizes pixels near the edges of the interrogation window.

dpivsoft.DPIV.masking(Img1, Img2)

Apply the binary mask (Parameters.Data.mask) to both images.

dpivsoft.DPIV.change_mask(SubImg1, SubImg2)

Replace masked (zero) pixels of each sub-image by the mean intensity of the unmasked pixels, so the mask does not bias the correlation.

dpivsoft.DPIV.check_mask(u, v, mask)

Set the velocity to 0 where the center of the correlation box lies inside the mask. Enforces the no-slip condition and prevents the median filter from bleeding values across the mask edge.

dpivsoft.DPIV.load_images(name_img_1, name_img_2)

Load an image pair for PIV processing as grayscale float32 arrays. A value of 1 is added so that no pixel outside the mask is exactly 0.

dpivsoft.DPIV.save(x, y, u, v, filename, option='dpivsoft', Matlab=False, param=False)

Save the flow field to disk, scaled with Parameters.calibration and Parameters.delta_t.

Parameters:

• x (2d np.ndarray) – Grid and velocity field to save.

• y (2d np.ndarray) – Grid and velocity field to save.

• u (2d np.ndarray) – Grid and velocity field to save.

• v (2d np.ndarray) – Grid and velocity field to save.

• filename (str) – Output file name (extension added by NumPy/SciPy where needed).

• option ({'dpivsoft', 'openpiv'}) – ‘dpivsoft’: save a python .npz file using the original DPIVSoft (MATLAB) variable naming. ‘openpiv’: save the field in an ASCII file compatible with OpenPIV.

• Matlab (bool) – If True, additionally save a MATLAB .mat file with all processing parameters.

• param (bool) – If True, include the processing parameters in the .npz file.