motion_correction.pyimof package

Submodules

motion_correction.pyimof.display module

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

motion_correction.pyimof.display.color_wheel(u=None, v=None, nr=50, ntheta=1025)

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~numpy.ndarray (optional)

The horizontal component of the vector field (default: None).

v~numpy.ndarray (optional)

The vertical component of the vector field (default: None).

nrint (optional)

The number of steps used to discretise the wheel radius.

nthetaint (optional)

The number of steps used to discretise the wheel sectors.

Returns

angle, radius: tuple[~numpy.ndarray]

The grid discretisation of the wheel sectors and radius.

motion_correction.pyimof.display.flow_to_color(u, v, cmap=None, scale=True)

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~numpy.ndarray

The horizontal component of the vector field.

v~numpy.ndarray

The vertical component of the vector field.

cmapstr (optional)

The colormap used to color code the input vector field.

scalebool (optional)

whether to scale output saturation according to magnitude.

Returns

img~numpy.ndarray

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

motion_correction.pyimof.display.get_tight_figsize(I)

Computes the matplotlib figure tight size respecting image proportions.

Parameters

I~numpy.ndarray

The image to be displayed.

Returns

w, htuple[float]

The width and height in inch of the desired figure.

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

Plots the color coded vector field.

Parameters

u~numpy.ndarray

The horizontal component of the vector field.

v~numpy.ndarray

The vertical component of the vector field.

ax~matplotlib.pyplot.Axes (optional)

Optional matplotlib axes used to plot the image. If None, the image is displayed in a tight figure.

cmapstr (optional)

The colormap used to color code the input vector field.

scalebool (optional)

whether to scale output saturation according to magnitude.

colorwheelbool (optional)

whether to display the color wheel describing the images colors or not.

Returns

ax~matplotlib.pyplot.Axes

The matplotlib axes where the image is displayed.

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

Draws a quiver plot representing a dense vector field.

Parameters

u~numpy.ndarray (with shape m×n)

The horizontal component of the vector field.

v~numpy.ndarray (with shape m×n)

The vertical component of the vector field.

c~numpy.ndarray (optional (with shape m×n))

Values used to color the arrows.

bg~numpy.ndarray (2D or 3D optional)

Background image.

ax~matplotlib.pyplot.Axes (optional)

Axes used to plot the image. If None, the image is displayed in a tight figure.

stepint (optional)

The grid step used to display the vector field. If None, it is computed using the nvec parameter.

nvecint

The maximum number of vector over all the grid dimentions. It is ignored if the step parameter is not None.

bg_cmapstr (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~matplotlib.pyplot.Axes

The matplotlib axes where the vector field is displayed.

motion_correction.pyimof.io module

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

motion_correction.pyimof.io.floread(fname)

Read a Middleburry .flo file.

Parameters

fname: str

The file name.

Returns

u, vtuple[~numpy.ndarray]

The horizontal and vertical components of the estimated optical flow.

motion_correction.pyimof.io.flowrite(u, v, fname)

Write a given flow to the Middleburry file format .flo

Parameters

u~numpy.ndarray

The horizontal component of the estimated optical flow.

v~numpy.ndarray

The vertical component of the estimated optical flow.

fname: str

The target file name. The ‘.flo’ extension is appended if necessary.

motion_correction.pyimof.solvers module

Collection of optical flow algorithms.

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

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~numpy.ndarray

The first gray scale image of the sequence.

I1~numpy.ndarray

The second gray scale image of the sequence.

radint

Radius of the window considered around each pixel.

nwarpint

Number of times I1 is warped.

gaussianbool

if True, gaussian kernel is used otherwise uniform kernel is used.

prefilterbool

whether to prefilter the estimated optical flow before each image warp.

Returns

u, vtuple[~numpy.ndarray]

The horizontal and vertical components of the estimated optical flow.

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()

motion_correction.pyimof.solvers.tvl1(I0, I1, dt=0.2, lambda_=15, tau=0.3, nwarp=5, niter=10, tol=0.0001, prefilter=False)

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~numpy.ndarray

The first gray scale image of the sequence.

I1~numpy.ndarray

The second gray scale image of the sequence.

dtfloat

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.

taufloat

Tightness parameter. It should have a small value in order to maintain attachement and regularization parts in correspondence.

nwarpint

Number of times I1 is warped.

niterint

Number of fixed point iteration.

tolfloat

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

prefilterbool

whether to prefilter the estimated optical flow before each image warp.

Returns

u, vtuple[~numpy.ndarray]

The horizontal and vertical components of the estimated optical flow.

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()

motion_correction.pyimof.util module

Common tools to optical flow algorithms.

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

Generic coarse to fine solver.

Parameters

I0~numpy.ndarray

The first gray scale image of the sequence.

I1~numpy.ndarray

The second gray scale image of the sequence.

solvercallable

The solver applyed at each pyramid level.

downscalefloat

The pyramid downscale factor.

nlevelint

The maximum number of pyramid levels.

min_sizeint

The minimum size for any dimension of the pyramid levels.

Returns

u, vtuple[~numpy.ndarray]

The horizontal and vertical components of the estimated optical flow.

motion_correction.pyimof.util.get_pyramid(I, downscale=2.0, nlevel=10, min_size=16)

Construct image pyramid.

Parameters

I~numpy.ndarray

The image to be preprocessed (Gray scale or RGB).

downscalefloat

The pyramid downscale factor.

nlevelint

The maximum number of pyramid levels.

min_sizeint

The minimum size for any dimension of the pyramid levels.

Returns

pyramidlist[~numpy.ndarray]

The coarse to fine images pyramid.

motion_correction.pyimof.util.resize_flow(u, v, shape)

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~numpy.ndarray

The horizontal component of the motion field.

v~numpy.ndarray

The vertical component of the motion field.

shapeiterable

Couple of integers representing the output shape.

Returns

ru, rvtuple[~numpy.ndarray]

The resized and rescaled horizontal and vertical components of the motion field.

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

Toltal variation regularization using Chambolle algorithm [1]_.

Parameters

x~numpy.ndarray

The target array.

taufloat

Tightness parameter. It should have a small value in order to maintain attachement and regularization parts in correspondence.

dtfloat

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

max_iterint

Maximum number of iteration.

p~numpy.ndarray

Optional buffer array of shape (x.ndim, ) + x.shape.

g~numpy.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. From https://github.com/rfezzani/pyimof