pysteps.motion.lucaskanade.dense_lucaskanade

pysteps.motion.lucaskanade.dense_lucaskanade(R, **kwargs)

OpenCV implementation of the local Lucas-Kanade method with interpolation of the sparse motion vectors to fill the whole grid.

Parameters:

R : ndarray or MaskedArray

Array of shape (T,m,n) containing a sequence of T two-dimensional input images of shape (m,n).

In case of an ndarray, invalid values (Nans or infs) are masked. The mask in the MaskedArray defines a region where velocity vectors are not computed.

Returns:

out : ndarray

Three-dimensional array (2,m,n) containing the dense x- and y-components of the motion field. Return an empty array when no motion vectors are found.

Other Parameters:  

buffer_mask : int, optional

A mask buffer width in pixels. This extends the input mask (if any) to help avoiding the erroneous interpretation of velocities near the maximum range of the radars (0 by default).

max_corners_ST : int, optional

The maxCorners parameter in the Shi-Tomasi corner detection method. It represents the maximum number of points to be tracked (corners), by default this is 500. If set to zero, all detected corners are used.

quality_level_ST : float, optional

The qualityLevel parameter in the Shi-Tomasi corner detection method. It represents the minimal accepted quality for the points to be tracked (corners), by default this is set to 0.1. Higher quality thresholds can lead to no detection at all.

min_distance_ST : int, optional

The minDistance parameter in the Shi-Tomasi corner detection method. It represents minimum possible Euclidean distance in pixels between corners, by default this is set to 3 pixels.

block_size_ST : int, optional

The blockSize parameter in the Shi-Tomasi corner detection method. It represents the window size in pixels used for computing a derivative covariation matrix over each pixel neighborhood, by default this is set to 15 pixels.

winsize_LK : tuple of int, optional

The winSize parameter in the Lucas-Kanade optical flow method. It represents the size of the search window that it is used at each pyramid level, by default this is set to (50, 50) pixels.

nr_levels_LK : int, optional

The maxLevel parameter in the Lucas-Kanade optical flow method. It represents the 0-based maximal pyramid level number, by default this is set to 3.

nr_IQR_outlier : int, optional

Maximum acceptable deviation from the median velocity value in terms of number of inter quantile ranges (IQR). Any velocity that is larger than this value is flagged as outlier and excldued from the interpolation. By default this is set to 3.

size_opening : int, optional

The size of the structuring element kernel in pixels. This is used to perform a binary morphological opening on the input fields in order to filter isolated echoes due to clutter. By default this is set to 3. If set to zero, the fitlering is not perfomed.

decl_grid : int, optional

The cell size in pixels of the declustering grid that is used to filter out outliers in a sparse motion field and get more representative data points before the interpolation. This simply computes new sparse vectors over a coarser grid by taking the median of all vectors within one cell. By default this is set to 20 pixels. If set to less than 2 pixels, the declustering is not perfomed.

min_nr_samples : int, optional

The minimum number of samples necessary for computing the median vector within given declustering cell, otherwise all sparse vectors in that cell are discarded. By default this is set to 2.

rbfunction : string, optional

The name of the radial basis function used for the interpolation of the sparse vectors. This is based on the Euclidian norm d. By default this is set to “inverse” and the available names are “nearest”, “inverse”, “gaussian”.

k : int, optional

The number of nearest neighbors used for fast interpolation, by default this is set to 20. If set equal to zero, it employs all the neighbors.

epsilon : float, optional

The adjustable constant used in the gaussian and inverse radial basis functions. by default this is computed as the median distance between the sparse vectors.

nchunks : int, optional

Split the grid points in n chunks to limit the memory usage during the interpolation. By default this is set to 5, if set to 1 the interpolation is computed with the whole grid.

extra_vectors : ndarray, optional

Additional sparse motion vectors as 2d array (columns: x,y,u,v; rows: nbr. of vectors) to be integrated with the sparse vectors from the Lucas-Kanade local tracking. x and y must be in pixel coordinates, with (0,0) being the upper-left corner of the field R. u and v must be in pixel units. By default this is set to None.

verbose : bool, optional

If set to True, it prints information about the program (True by default).

References

Bouguet, J.-Y.: Pyramidal implementation of the affine Lucas Kanade feature tracker description of the algorithm, Intel Corp., 5, 4, https://doi.org/10.1109/HPDC.2004.1323531, 2001

Lucas, B. D. and Kanade, T.: An iterative image registration technique with an application to stereo vision, in: Proceedings of the 1981 DARPA Imaging Understanding Workshop, pp. 121–130, 1981.