pyIDI source code

pyIDI base class

class pyidi.pyidi.pyIDI(cih_file)[source]

The pyIDI base class represents the video to be analysed.


Close the .mraw video memmap.

get_displacements(autosave=True, **kwargs)[source]

Calculate the displacements based on chosen method.

Method docstring: — Method is not set. Please use the set_method method. —

set_method(method, **kwargs)[source]

Set displacement identification method on video. To configure the method, use method.configure()

Available methods: — [Available method names and descriptions go here.] —

Parameters:method (IDIMethod or str) – the method to be used for displacement identification.
set_points(points=None, method=None, **kwargs)[source]

Set points that will be used to calculate displacements. If points is None and a method has aready been set on this pyIDI instance, the method object’s get_point is used to get method-appropriate points.

show_field(field, scale=1.0, width=0.5)[source]

Show displacement field on image.

  • field (ndarray) – Field of displacements (number_of_points, 2)
  • scale – scale the field, defaults to 1.
  • scale – float, optional
  • width – width of the arrow, defaults to 0.5
  • width – float, optional

Show selected points on image.

Displacement identification methods

IDIMetod base class

class pyidi.methods.idi_method.IDIMethod(video, *args, **kwargs)[source]

Common functions for all methods.

calculate_displacements(video, *args, **kwargs)[source]

Calculate the displacements of set points here. The result should be saved into the self.displacements attribute.

configure(*args, **kwargs)[source]

Configure the displacement identification method here.

Simplified optical flow

class pyidi.methods._simplified_optical_flow.PickPoints(video, subset, axis, min_grad)[source]

Pick the area of interest.

Select the points with highest gradient in vertical direction.

inside_polygon(x, y, points)[source]

Return True if a coordinate (x, y) is inside a polygon defined by a list of verticies [(x1, y1), (x2, x2), … , (xN, yN)].


class pyidi.methods._simplified_optical_flow.SimplifiedOpticalFlow(video, *args, **kwargs)[source]

Displacmenet computation based on Simplified Optical Flow method [1].

[1] Javh, J., Slavič, J., & Boltežar, M. (2017). The subpixel resolution
of optical-flow-based modal analysis. Mechanical Systems and Signal Processing, 88, 89–99.
[2] Lucas, B. D., & Kanade, T. (1981). An Iterative Image Registration
Technique with an Application to Stereo Vision. In Proceedings of the 7th International Joint Conference on Artificial Intelligence - Volume 2 (pp. 674–679). San Francisco, CA, USA: Morgan Kaufmann Publishers Inc.

Calculate the displacements of set points here. The result should be saved into the self.displacements attribute.

configure(subset_size=3, pixel_shift=False, convert_from_px=1.0, mraw_range='all', mean_n_neighbours=0, zero_shift=False, progress_bar=True, reference_range=(0, 100))[source]

Set the attributes, compute reference image and gradients.

  • video (object) – ‘parent’ object
  • subset_size – size of the averaging subset, defaults to 3
  • subset_size – int, optional
  • pixel_shift – use pixel shift or not?, defaults to False
  • pixel_shift – bool, optional
  • convert_from_px – distance unit per pixel, defaults to 1.
  • convert_from_px – float or int, optional
  • mraw_range – what range of images to calculate into displacements, defaults to ‘all’
  • mraw_range – str or tuple, optional
  • mean_n_neighbours – average the displacements of neighbouring points (how many points), defaults to 0
  • mean_n_neighbours – int, optional
  • zero_shift – shift the mean of the signal to zero?, defaults to False
  • zero_shift – bool, optional
  • progress_bar – show progress bar while calculating the displacements, defaults to True
  • progress_bar – bool, optional
  • reference_range – what range of images is averaged into reference image, defaults to (0, 100)
  • reference_range – tuple, optional

Calculate the average of displacements.

static get_points(video, **kwargs)[source]

Determine the points.


Pixel shifting implementation.

reference(images, subset_size)[source]

Calculation of the reference image, image gradients and gradient amplitudes.

  • images – Images to average. Usually the first 100 images.
  • subset_size – Size of the subset to average.

Reference image, image gradient in 0 direction, image gradient in 1 direction, gradient magnitude

subset(data, subset_size)[source]

Calculating a filtered image.

Calculates a filtered image with subset of d. It sums the area of d x d.

  • data – Image that is to be filtered.
  • subset_size – Size of the subset.

Filtered image.

The Lucas-Kanade algorithm for translations

class pyidi.methods._lucas_kanade.LucasKanade(video, *args, **kwargs)[source]

Translation identification based on the Lucas-Kanade method using least-squares iterative optimization with the Zero Normalized Cross Correlation optimization criterium.

calculate_displacements(video, **kwargs)[source]

Calculate displacements for set points and roi size.

kwargs are passed to configure method. Pre-set arguments (using configure) are NOT changed!


Clearing the temporary files.

configure(roi_size=(9, 9), pad=2, max_nfev=20, tol=1e-08, int_order=3, verbose=1, show_pbar=True, processes=1, pbar_type='atpbar', multi_type='mantichora', resume_analysis=True, process_number=0, reference_image=0, mraw_range='full', use_numba=False)[source]

Displacement identification based on Lucas-Kanade method, using iterative least squares optimization of translatory transformation parameters to determine image ROI translations.

  • video (object) – parent object
  • roi_size (tuple, list, optional) – (h, w) height and width of the region of interest. ROI dimensions should be odd numbers. Defaults to (9, 9)
  • pad (int, optional) – size of padding around the region of interest in px, defaults to 2
  • max_nfev (int, optional) – maximum number of iterations in least-squares optimization, defaults to 20
  • tol (float, optional) – tolerance for termination of the iterative optimization loop. The minimum value of the optimization parameter vector norm.
  • int_order (int, optional) – interpolation spline order
  • verbose (int, optional) – show text while running, defaults to 1
  • show_pbar (bool, optional) – show progress bar, defaults to True
  • processes (int, optional, defaults to 1.) – number of processes to run
  • pbar_type (str, optional) – type of the progress bar (‘tqdm’ or ‘atpbar’), defaults to ‘atpbar’
  • multi_type (str, optional) – type of multiprocessing used (‘multiprocessing’ or ‘mantichora’), defaults to ‘mantichora’
  • resume_analysis – if True, the last analysis results are loaded and computation continues from last computed time point.
  • process_number (int, optional) – User should not change this (for multiprocessing purposes - to indicate the process number)
  • reference_image (int or tuple or ndarray) – The reference image for computation. Can be index of a frame, tuple (slice) or numpy.ndarray that is taken as a reference.
  • mraw_range (tuple or "full") – Part of the video to process. If “full”, a full video is processed. If first element of tuple is not 0, a appropriate reference image should be chosen.
  • use_numba (bool) – Use numba.njit for computation speedup. Currently not implemented.

Make a dictionary of the chosen settings.


Temporary files to track the solving process.

This is done in case some error occures. In this eventuality the calculation can be resumed from the last computed time point.

Parameters:init_multi (bool, optional) – when initialization multiprocessing, defaults to False
optimize_translations(G, F_spline, maxiter, tol, d_subpixel_init=(0, 0))[source]

Determine the optimal translation parameters to align the current image subset G with the interpolated reference image subset F.

  • G (array of shape roi_size) – the current image subset.
  • F_spline (scipy.interpolate.RectBivariateSpline) – interpolated referencee image subset
  • maxiter (int) – maximum number of iterations
  • tol (float) – convergence criterium
  • d_subpixel_init – initial subpixel displacement guess, relative to the integrer position of the image subset G

the obtimal subpixel translation parameters of the current image, relative to the position of input subset G.

Return type:

array of size 2


Reload the settings written in the temporary files.

When resuming the computation of displacement, the settings are loaded from the previously created temporary files.


roi_size attribute getter

show_points(video, figsize=(15, 5), cmap='gray', color='r')[source]

Shoe points to be analyzed, together with ROI borders.

  • figsize – matplotlib figure size, defaults to (15, 5)
  • cmap – matplotlib colormap, defaults to ‘gray’
  • color – marker and border color, defaults to ‘r’

Checking the settings of computation.

The computation can only be resumed if all the settings and data are the same as with the original analysis. This function checks that (writing all the setting to dict and comparing the json dump of the dicts).

If the settings are the same but the points are not, a new analysis is also started. To set the same points, check the temp_pyidi folder.

Returns:Whether to resume analysis or not
Return type:bool

Updating the log file.

A new last time is written in the log file in order to track the solution process.

Parameters:last_time (int) – Last computed time point (index)
pyidi.methods._lucas_kanade.multi(video, processes)[source]

Splitting the points to multiple processes and creating a pool of workers.

  • video (object) – the video object with defined attributes
  • processes (int) – number of processes. If negative, the number of processes is set to psutil.cpu_count + processes.


Return type:


pyidi.methods._lucas_kanade.worker(points, idi_kwargs, method_kwargs, i)[source]

A function that is called when for each job in multiprocessing.