Topology for PIV computation (fluidimage.topologies.piv)

class fluidimage.topologies.piv.TopologyPIV(params, logging_level='info', nb_max_workers=None)[source]

Bases: fluidimage.topologies.base.TopologyBase

Topology for PIV computation.

The most useful methods for the user (in particular compute()) are defined in the base class fluidimage.topologies.base.TopologyBase.


A ParamContainer (created with the class method create_default_params()) containing the parameters for the computation.

logging_levelstr, {‘warning’, ‘info’, ‘debug’, …}

Logging level.

nb_max_workersNone, int

Maximum numbers of “workers”. If None, a number is estimated from the number of cores detected. If there are memory errors, you can try to decrease the number of workers.


alias of fluidimage.works.piv.multipass.WorkPIV

classmethod create_default_params()[source]

Class method returning the default parameters.

Typical usage:

params = TopologyPIV.create_default_params()
# modify parameters here

topo = TopologyPIV(params)

Save a PIV object

fill_couples_of_names_and_paths(input_queue, output_queues)[source]

Fill the two first queues

make_couples(input_queues, output_queue)[source]

Make the couples of arrays


Make a text printed at exit

Documentation for params

Documentation for params.series

Parameters indicating the input series of images.

path : str, {‘’}

String indicating the input images (can be a full path towards an image file or a string given to glob).

strcouple : ‘i:i+2’

String indicating as a Python slicing how couples of images are formed. There is one couple per value of i. The values of i are set with the other parameters ind_start, ind_step and ind_stop approximately with the function range (range(ind_start, ind_stop, ind_step)).

Python slicing is a very powerful notation to define subset from a (possibly multidimensional) set of images. For a user, an alternative is to understand how Python slicing works. See for example this page: http://stackoverflow.com/questions/509211/explain-pythons-slice-notation.

Another possibility is to follow simple examples:

For single-frame images (im0, im1, im2, im3, …), we keep the default value ‘i:i+2’ to form the couples (im0, im1), (im1, im2), …

To see what it gives, one can use IPython and range:

>>> i = 0
>>> list(range(10))[i:i+2]
[0, 1]
>>> list(range(10))[i:i+4:2]
[0, 2]

We see that we can also use the value ‘i:i+4:2’ to form the couples (im0, im2), (im1, im3), …

For double-frame images (im1a, im1b, im2a, im2b, …) you can write

>>> params.series.strcouple = 'i, 0:2'

In this case, the first couple will be (im1a, im1b).

To get the first couple (im1a, im1a), we would have to write

>>> params.series.strcouple = 'i:i+2, 0'

ind_start : int, {0}

ind_step : int, {1}

int_stop : None

Documentation for params.saving

Saving of the results.

path : None or str

Path of the directory where the data will be saved. If None, the path is obtained from the input path and the parameter postfix.

how : str {‘ask’}

‘ask’, ‘new_dir’, ‘complete’ or ‘recompute’.

postfix : str

Postfix from which the output file is computed.

Documentation for params.piv0

Parameters describing one PIV step.

shape_crop_im0int (48)

Shape of the cropped images 0 from which are computed the correlation.

shape_crop_im1int or None

Shape of the cropped images 0 (has to be None for correl based on fft).


Displacement maximum used in correlation classes. The exact effect depends on the correlation method. For fft based correlation, it can also be of the form ‘50%’ and then the maximum displacement is computed for each pass as a pourcentage of max(shape_crop_im0).


Displacement averaged over space (NotImplemented).

method_correl : str, default ‘fftw’

Can be in [‘pythran’, ‘pycuda’, ‘scipy.signal’, ‘scipy.ndimage’, ‘theano’, ‘np.fft’, ‘fftw’, ‘cufft’, ‘skcufft’]

method_subpix : str, default ‘2d_gaussian2’

Can be in [‘2d_gaussian’, ‘2d_gaussian2’, ‘centroid’, ‘no_subpix’]


Integer used in the subpix finder. It is related to the typical size of the particles. It has to be increased in case of peak locking (plot the histograms of the displacements).

coef_correl_no_displNone, number

If this coefficient is not None, the correlation of the point corresponding to no displacement is multiplied by this coefficient (for the first pass).

nb_peaks_to_search1, int

Number of peaks to search. Secondary peaks can be used during the fix step.

particle_radius3, int

Typical radius of a particle (or more preciselly of a correlation peak). Used only if nb_peaks_to_search is larger than one.

Documentation for params.piv0.grid

Parameters describing the grid.

overlapfloat (0.5)

Number smaller than 1 defining the overlap between interrogation windows.

fromstr {‘overlap’}

Keyword for the method from which is computed the grid.

Documentation for params.mask

Parameters describing how images are masked.

strcrop : None, str

Two-dimensional slice (for example ‘100:600, :’). If None, the whole image is used.

Documentation for params.fix

Parameters indicating how are detected and processed false vectors.

correl_min : 0.2

Vectors associated with correlation smaller than correl_min are considered as false vectors.

threshold_diff_neighbour : 10

Vectors for which the difference with the average vectors is larger than threshold_diff_neighbour are considered as false vectors.

displacement_max : None

Vectors larger than displacement_max are considered as false vectors.

Documentation for params.multipass

Multipass PIV parameters:

numberint (default 1)

Number of PIV passes.

coeff_zoom : integer or iterable of size number - 1.

Reduction coefficient defining the size of the interrogation windows for the passes 1 (second pass) to number - 1 (last pass) (always defined comparing the passes i-1).

use_tps : bool or ‘last’

If it is True, the interpolation is done using the Thin Plate Spline method (computationnally heavy but sometimes interesting). If it is ‘last’, the TPS method is used only for the last pass.

subdom_size : int

Number of vectors in the subdomains used for the TPS method.

smoothing_coef : float

Coefficient used for the TPS method. The result is smoother for larger smoothing_coef.

threshold_tps : float

Allowed difference of displacement (in pixels) between smoothed and input field for TPS filter.

Documentation for params.preproc

im2im : str {None}

Function or class to be used to process the images.

args_init : object {None}

An argument given to the init function of the class used to process the images.


is_name_in_queue(image_name, queue)

Check if a name is in a queue of series



alias of fluidimage.topologies.piv.TopologyPIV

TopologyPIV(params[, logging_level, …])

Topology for PIV computation.