Tutorial

Tutorial#

pyidi is a python package for displacement identification from raw video.

Currently the pyIDI method works with Photron .cih and .cihx files, however, numpy.ndarray can also be passed as cih_file argument. If an array is passed, it must have a shape of: (n time points, image height, image width).

Loading the video#

First create the VideoReader object:

from pyidi import VideoReader

video = VideoReader('filename.cih')

Setting the method#

The video object must be passed to the IDIMethod class. Available methods are:

To use the Simplified Optical Flow method, the object must be instantiated:

from pyidi import SimplifiedOpticalFlow

sof = SimplifiedOpticalFlow(video)

After the method object is instantiated, the points can be set and the arguments can be configured.

For more details on the available methods, see the currently implemented Displacement identification methods.

Setting the points#

Displacements are computed for certain points or certain regions of interest that are represented by a point.

Points must be of shape n_points x 2:

points = [[1, 2],
          [1, 5],
          [2, 10]]

where the first column indicates indices along axis 0, and the second column indices along axis 1.

The points must be passed to method object:

sof.set_points(points=points)

If the points are not known, a Point selection UI or newer Napari image viewer can be used to select the points.

Configuring the method#

The method can be configured using:

sof.configure(...)

Note

Some of the methods enable the multiprocessing option. By setting the number of processes, the points are divided into groups and each group is processed in a separate process.

A caveat is that when using the multiprocessing option in a shell (not jupyter notebook), the code must be run in a if __name__ == '__main__': block.

Get displacement#

Finally, displacements can be identified:

displacements = sof.get_displacements()

Saved analysis#

The settings of the analysis and the identified displacements are saved in a directory next to the loaded cih_file.

Directory content before the analysis:

  • video_to_analyze.cih

Directory content after the analysis:

  • video_to_analyze.cih

  • video_to_analyze_pyidi_analysis

    • analysis_001

      • points.pkl

      • results.pkl

      • settings.txt

Loading saved analysis#

The saved analysis can be loaded using the load_analysis function:

analysis_path = 'video_to_analyze_pyidi_analysis/analysis_001'

video_loaded, info_dict = pyidi.load_analysis(analysis_path)

Now we can access the video_loaded attributes, e.g.:

video_loaded.displacements