pysteps.motion.lucaskanade.dense_lucaskanade

pysteps.motion.lucaskanade.dense_lucaskanade(input_images, lk_kwargs=None, fd_method='shitomasi', fd_kwargs=None, interp_method='idwinterp2d', interp_kwargs=None, dense=True, nr_std_outlier=3, k_outlier=30, size_opening=3, decl_scale=20, verbose=False)

Run the Lucas-Kanade optical flow routine and interpolate the motion vectors.

Interface to the OpenCV implementation of the local Lucas-Kanade optical flow method applied in combination to a feature detection routine.

The sparse motion vectors are finally interpolated to return the whole motion field.

Parameters:

• input_images (ndarray or MaskedArray) –

  Array of shape (T, m, n) containing a sequence of T two-dimensional input images of shape (m, n). The indexing order in input_images is assumed to be (time, latitude, longitude).

  T = 2 is the minimum required number of images. With T > 2, all the resulting sparse vectors are pooled together for the final interpolation on a regular grid.

  In case of ndarray, invalid values (Nans or infs) are masked, otherwise the mask of the MaskedArray is used. Such mask defines a region where features are not detected for the tracking algorithm.

• lk_kwargs (dict, optional) – Optional dictionary containing keyword arguments for the Lucas-Kanade features tracking algorithm. See the documentation of pysteps.tracking.lucaskanade.track_features().

• fd_method ({"shitomasi", "blob", "tstorm"}, optional) – Name of the feature detection routine. See feature detection methods in pysteps.feature.

• fd_kwargs (dict, optional) – Optional dictionary containing keyword arguments for the features detection algorithm. See the documentation of pysteps.feature.

• interp_method ({"idwinterp2d", "rbfinterp2d"}, optional) – Name of the interpolation method to use. See interpolation methods in pysteps.utils.interpolate.

• interp_kwargs (dict, optional) – Optional dictionary containing keyword arguments for the interpolation algorithm. See the documentation of pysteps.utils.interpolate.

• dense (bool, optional) –

  If True, return the three-dimensional array (2, m, n) containing the dense x- and y-components of the motion field.

  If False, return the sparse motion vectors as 2-D xy and uv arrays, where xy defines the vector positions, uv defines the x and y direction components of the vectors.

• nr_std_outlier (int, optional) – Maximum acceptable deviation from the mean in terms of number of standard deviations. Any sparse vector with a deviation larger than this threshold is flagged as outlier and excluded from the interpolation. See the documentation of pysteps.utils.cleansing.detect_outliers().

• k_outlier (int or None, optional) – The number of nearest neighbors used to localize the outlier detection. If set to None, it employs all the data points (global detection). See the documentation of pysteps.utils.cleansing.detect_outliers().

• 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. If set to zero, the filtering is not performed. See the documentation of pysteps.utils.images.morph_opening().

• decl_scale (int, optional) – The scale declustering parameter in pixels used to reduce the number of redundant sparse vectors before the interpolation. Sparse vectors within this declustering scale are averaged together. If set to less than 2 pixels, the declustering is not performed. See the documentation of pysteps.utils.cleansing.decluster().

• verbose (bool, optional) – If set to True, print some information about the program.

Returns:

out – If dense=True (the default), return the advection field having shape (2, m, n), where out[0, :, :] contains the x-components of the motion vectors and out[1, :, :] contains the y-components. The velocities are in units of pixels / timestep, where timestep is the time difference between the two input images. Return a zero motion field of shape (2, m, n) when no motion is detected.

If dense=False, it returns a tuple containing the 2-dimensional arrays xy and uv, where x, y define the vector locations, u, v define the x and y direction components of the vectors. Return two empty arrays when no motion is detected.

Return type:

ndarray or tuple

See also

pysteps.motion.lucaskanade.track_features

References

Bouguet, J.-Y.: Pyramidal implementation of the affine Lucas Kanade feature tracker description of the algorithm, Intel Corp., 5, 4, 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.