pysteps.motion.vet.vet

Contents

pysteps.motion.vet.vet#

pysteps.motion.vet.vet(input_images, sectors=((32, 16, 4, 2), (32, 16, 4, 2)), smooth_gain=1000000.0, first_guess=None, intermediate_steps=False, verbose=True, indexing='yx', padding=0, options=None)#

Variational Echo Tracking Algorithm presented in Laroche and Zawadzki (1995) and used in the McGill Algorithm for Prediction by Lagrangian Extrapolation (MAPLE) described in Germann and Zawadzki (2002).

This algorithm computes the displacement field between two images ( the input_image with respect to the template image). The displacement is sought by minimizing the sum of the residuals of the squared differences of the images pixels and the contribution of a smoothness constraint. In the case that a MaskedArray is used as input, the residuals term in the cost function is only computed over areas with non-masked values. Otherwise, it is computed over the entire domain.

To find the minimum, a scaling guess procedure is applied, from larger to smaller scales. This reduces the chances that the minimization procedure converges to a local minimum. The first scaling guess is defined by the scaling sectors keyword.

The smoothness of the returned displacement field is controlled by the smoothness constraint gain (smooth_gain keyword).

If a first guess is not given, zero displacements are used as the first guess.

The cost function is minimized using the scipy minimization function, with the ‘CG’ method by default. This method proved to give the best results under many different conditions and is the most similar one to the original VET implementation in Laroche and Zawadzki (1995).

The method CG uses a nonlinear conjugate gradient algorithm by Polak and Ribiere, a variant of the Fletcher-Reeves method described in Nocedal and Wright (2006), pp. 120-122.

Parameters:
  • input_images (ndarray or MaskedArray) –

    Input images, sequence of 2D arrays, or 3D arrays. The first dimension represents the images time dimension.

    The template_image (first element in first dimensions) denotes the reference image used to obtain the displacement (2D array). The second is the target image.

    The expected dimensions are (2,ni,nj).

  • sectors (list or array, optional) – Number of sectors on each dimension used in the scaling procedure. If dimension is 1, the same sectors will be used both image dimensions (x and y). If sectors is a 1D array, the same number of sectors is used in both dimensions.

  • smooth_gain (float, optional) – Smooth gain factor

  • first_guess (ndarray, optional) –

    The shape of the first guess should have the same shape as the initial sectors shapes used in the scaling procedure. If first_guess is not present zeros are used as first guess.

    E.g.:

    If the first sector shape in the scaling procedure is (ni,nj), then the first_guess should have (2, ni, nj ) shape.

  • intermediate_steps (bool, optional) – If True, also return a list with the first guesses obtained during the scaling procedure. False, by default.

  • verbose (bool, optional) – Verbosity enabled if True (default).

  • indexing (str, optional) – Input indexing order.’ij’ and ‘xy’ indicates that the dimensions of the input are (time, longitude, latitude), while ‘yx’ indicates (time, latitude, longitude). The displacement field dimensions are ordered accordingly in a way that the first dimension indicates the displacement along x (0) or y (1). That is, UV displacements are always returned.

  • padding (int) – Padding width in grid points. A border is added to the input array to reduce the effects of the minimization at the border.

  • options (dict, optional) – A dictionary of solver options. See scipy minimization function for more details.

Returns:

  • displacement_field (ndarray_) – Displacement Field (2D array representing the transformation) that warps the template image into the input image. The dimensions are (2,ni,nj), where the first dimension indicates the displacement along x (0) or y (1) in units of pixels / timestep as given by the input_images array.

  • intermediate_steps (list of ndarray_) – List with the first guesses obtained during the scaling procedure.

References

Laroche, S., and I. Zawadzki, 1995: Retrievals of horizontal winds from single-Doppler clear-air data by methods of cross-correlation and variational analysis. J. Atmos. Oceanic Technol., 12, 721–738. doi: http://dx.doi.org/10.1175/1520-0426(1995)012<0721:ROHWFS>2.0.CO;2

Germann, U. and I. Zawadzki, 2002: Scale-Dependence of the Predictability of Precipitation from Continental Radar Images. Part I: Description of the Methodology. Mon. Wea. Rev., 130, 2859–2873, doi: 10.1175/1520-0493(2002)130<2859:SDOTPO>2.0.CO;2.

Nocedal, J, and S J Wright. 2006. Numerical Optimization. Springer New York.