pyimof package

Submodules

pyimof.display module

Collection of utils and functions for the visualization of vector fields.

pyimof.display.color_wheel(u=None, v=None, nr=50, ntheta=1025)[source]

Compute the discretization of a wheel used to describe the color code used to display a vector field (u, v).

If the vector field (u, v) is provided, the radius of the wheel is equal to its maximum magnitude. Otherwise (i.e. if any of u and v is None), the radius is set to 1.

Parameters

  • u (ndarray (optional)) – The horizontal component of the vector field (default: None).

  • v (ndarray (optional)) – The vertical component of the vector field (default: None).

  • nr (int (optional)) – The number of steps used to discretise the wheel radius.

  • ntheta (int (optional)) – The number of steps used to discretise the wheel sectors.

Returns

angle, radius – The grid discretisation of the wheel sectors and radius.

Return type

tuple[ndarray]

pyimof.display.flow_to_color(u, v, cmap=None, scale=True)[source]

Apply color code to a vector field according to its orientation and magnitude.

Any colormap compatible with matplotlib can be applyed but circular colormaps are recommanded ( for example ‘huv’, ‘twilight’, ‘twilight_shifted’ and the builtin ‘middlebury’ colormaps).

If cmap is None, the HSV image defined using optical flow orientation (hue) and magnitude (saturation) is returned.

Parameters

  • u (ndarray) – The horizontal component of the vector field.

  • v (ndarray) – The vertical component of the vector field.

  • cmap (str (optional)) – The colormap used to color code the input vector field.

  • scale (bool (optional)) – whether to scale output saturation according to magnitude.

Returns

img – RGBA image representing the desired color code applyed to the vector field.

Return type

ndarray

pyimof.display.get_tight_figsize(I)[source]

Computes the matplotlib figure tight size respecting image proportions.

Parameters

I (ndarray) – The image to be displayed.

Returns

w, h – The width and height in inch of the desired figure.

Return type

tuple[float]

pyimof.display.plot(u, v, ax=None, cmap='middlebury', scale=True, colorwheel=True)[source]

Plots the color coded vector field.

Parameters

  • u (ndarray) – The horizontal component of the vector field.

  • v (ndarray) – The vertical component of the vector field.

  • ax (Axes (optional)) – Optional matplotlib axes used to plot the image. If None, the image is displayed in a tight figure.

  • cmap (str (optional)) – The colormap used to color code the input vector field.

  • scale (bool (optional)) – whether to scale output saturation according to magnitude.

  • colorwheel (bool (optional)) – whether to display the color wheel describing the images colors or not.

Returns

ax – The matplotlib axes where the image is displayed.

Return type

Axes

pyimof.display.quiver(u, v, c=None, bg=None, ax=None, step=None, nvec=50, bg_cmap=None, **kwargs)[source]

Draws a quiver plot representing a dense vector field.

Parameters

  • u (ndarray (with shape m×n)) – The horizontal component of the vector field.

  • v (ndarray (with shape m×n)) – The vertical component of the vector field.

  • c (ndarray (optional (with shape m×n))) – Values used to color the arrows.

  • bg (ndarray (2D or 3D optional)) – Background image.

  • ax (Axes (optional)) – Axes used to plot the image. If None, the image is displayed in a tight figure.

  • step (int (optional)) – The grid step used to display the vector field. If None, it is computed using the nvec parameter.

  • nvec (int) – The maximum number of vector over all the grid dimentions. It is ignored if the step parameter is not None.

  • bg_cmap (str (optional)) – The colormap used to color the background image.

Notes

Any other matplotlib.pyplot.quiver() valid keyword can be used, knowing that some are fixed

  • units = ‘dots’

  • angles = ‘xy’

  • scale = ‘xy’

Returns

ax – The matplotlib axes where the vector field is displayed.

Return type

Axes

pyimof.io module

Functions to read and write ‘.flo’ Middleburry file format.

pyimof.io.floread(fname)[source]

Read a Middleburry .flo file.

Parameters

fname (str) – The file name.

Returns

u, v – The horizontal and vertical components of the estimated optical flow.

Return type

tuple[ndarray]

pyimof.io.flowrite(u, v, fname)[source]

Write a given flow to the Middleburry file format .flo

Parameters

  • u (ndarray) – The horizontal component of the estimated optical flow.

  • v (ndarray) – The vertical component of the estimated optical flow.

  • fname (str) – The target file name. The ‘.flo’ extension is appended if necessary.

pyimof.solvers module

Collection of optical flow algorithms.

pyimof.solvers.ilk(I0, I1, rad=7, nwarp=10, gaussian=True, prefilter=False)[source]

Coarse to fine iterative Lucas-Kanade (iLK) optical flow estimator. A fast and robust algorithm developped by Le Besnerais and Champagnat 4 and improved in 5..

Parameters

  • I0 (ndarray) – The first gray scale image of the sequence.

  • I1 (ndarray) – The second gray scale image of the sequence.

  • rad (int) – Radius of the window considered around each pixel.

  • nwarp (int) – Number of times I1 is warped.

  • gaussian (bool) – if True, gaussian kernel is used otherwise uniform kernel is used.

  • prefilter (bool) – whether to prefilter the estimated optical flow before each image warp.

Returns

u, v – The horizontal and vertical components of the estimated optical flow.

Return type

tuple[ndarray]

References

4

Le Besnerais, G., & Champagnat, F. (2005, September). Dense optical flow by iterative local window registration. In IEEE International Conference on Image Processing 2005 (Vol. 1, pp. I-137). IEEE.

5

Plyer, A., Le Besnerais, G., & Champagnat, F. (2016). Massively parallel Lucas Kanade optical flow for real-time video processing applications. Journal of Real-Time Image Processing, 11(4), 713-730.

Examples

>>> from matplotlib import pyplot as plt
>>> import pyimof
>>> I0, I1 = pyimof.data.yosemite()
>>> u, v = pyimof.solvers.ilk(I0, I1)
>>> pyimof.display.plot(u, v)
>>> plt.show()
pyimof.solvers.tvl1(I0, I1, dt=0.2, lambda_=15, tau=0.3, nwarp=5, niter=10, tol=0.0001, prefilter=False)[source]

Coarse to fine TV-L1 optical flow estimator. A popular algorithm intrudced by Zack et al. [1]_, improved in 2 and detailed in 3.

Parameters

  • I0 (ndarray) – The first gray scale image of the sequence.

  • I1 (ndarray) – The second gray scale image of the sequence.

  • dt (float) – Time step of the numerical scheme. Convergence is proved for values dt < 0.125, but it can be larger for faster convergence.

  • lambda_ (float) – Attachement parameter. The smaller this parameter is, the smoother is the solutions.

  • tau (float) – Tightness parameter. It should have a small value in order to maintain attachement and regularization parts in correspondence.

  • nwarp (int) – Number of times I1 is warped.

  • niter (int) – Number of fixed point iteration.

  • tol (float) – Tolerance used as stopping criterion based on the L² distance between two consecutive values of (u, v).

  • prefilter (bool) – whether to prefilter the estimated optical flow before each image warp.

Returns

u, v – The horizontal and vertical components of the estimated optical flow.

Return type

tuple[ndarray]

References

1

Zach, C., Pock, T., & Bischof, H. (2007, September). A duality based approach for realtime TV-L 1 optical flow. In Joint pattern recognition symposium (pp. 214-223). Springer, Berlin, Heidelberg.

2

Wedel, A., Pock, T., Zach, C., Bischof, H., & Cremers, D. (2009). An improved algorithm for TV-L 1 optical flow. In Statistical and geometrical approaches to visual motion analysis (pp. 23-45). Springer, Berlin, Heidelberg.

3

Pérez, J. S., Meinhardt-Llopis, E., & Facciolo, G. (2013). TV-L1 optical flow estimation. Image Processing On Line, 2013, 137-150.

Examples

>>> from matplotlib import pyplot as plt
>>> import pyimof
>>> I0, I1 = pyimof.data.yosemite()
>>> u, v = pyimof.solvers.tvl1(I0, I1)
>>> pyimof.display.plot(u, v)
>>> plt.show()

pyimof.util module

Common tools to optical flow algorithms.

pyimof.util.coarse_to_fine(I0, I1, solver, downscale=2, nlevel=10, min_size=16)[source]

Generic coarse to fine solver.

Parameters

  • I0 (ndarray) – The first gray scale image of the sequence.

  • I1 (ndarray) – The second gray scale image of the sequence.

  • solver (callable) – The solver applyed at each pyramid level.

  • downscale (float) – The pyramid downscale factor.

  • nlevel (int) – The maximum number of pyramid levels.

  • min_size (int) – The minimum size for any dimension of the pyramid levels.

Returns

u, v – The horizontal and vertical components of the estimated optical flow.

Return type

tuple[ndarray]

pyimof.util.get_pyramid(I, downscale=2.0, nlevel=10, min_size=16)[source]

Construct image pyramid.

Parameters

  • I (ndarray) – The image to be preprocessed (Gray scale or RGB).

  • downscale (float) – The pyramid downscale factor.

  • nlevel (int) – The maximum number of pyramid levels.

  • min_size (int) – The minimum size for any dimension of the pyramid levels.

Returns

pyramid – The coarse to fine images pyramid.

Return type

list[ndarray]

pyimof.util.resize_flow(u, v, shape)[source]

Rescale the values of the vector field (u, v) to the desired shape.

The values of the output vector field are scaled to the new resolution.

Parameters

  • u (ndarray) – The horizontal component of the motion field.

  • v (ndarray) – The vertical component of the motion field.

  • shape (iterable) – Couple of integers representing the output shape.

Returns

ru, rv – The resized and rescaled horizontal and vertical components of the motion field.

Return type

tuple[ndarray]

pyimof.util.tv_regularize(x, tau=0.3, dt=0.2, max_iter=100, p=None, g=None)[source]

Toltal variation regularization using Chambolle algorithm [1]_.

Parameters

  • x (ndarray) – The target array.

  • tau (float) – Tightness parameter. It should have a small value in order to maintain attachement and regularization parts in correspondence.

  • dt (float) – Time step of the numerical scheme. Convergence is proved for values dt < 0.125, but it can be larger for faster convergence.

  • max_iter (int) – Maximum number of iteration.

  • p (ndarray) – Optional buffer array of shape (x.ndim, ) + x.shape.

  • g (ndarray) – Optional buffer array of shape (x.ndim, ) + x.shape.

References

1

A. Chambolle, An algorithm for total variation minimization and applications, Journal of Mathematical Imaging and Vision, Springer, 2004, 20, 89-97.

Module contents

A python package for optical flow estimation and visualization.