Loading Video Frames

mr provides three classes for loading video.

ImageSequence reads images from a directory.
Video reads standard video files (AVI, MOV, etc.).
TiffStack reads multi-frame TIF / TIFF files.

Once loaded, these objects can be handled alike. In programming terms, each is a subclass of a generic Frames object. The differences between the formats are all handled by mr "under the hood."

Load sequential images from a directory.

Take ImageSequence as an example. We have a folder of images here:



In [4]:

    
ls /home/dallan/mr/mr/tests/video/image_sequence/









    



T76S3F00001.png  T76S3F00003.png  T76S3F00005.png
T76S3F00002.png  T76S3F00004.png

We can load them into an ImageSequence object.



In [2]:

    
import mr



In [5]:

    
v = mr.ImageSequence('/home/dallan/mr/mr/tests/video/image_sequence/')

We can see basic properties.



In [6]:

    
v









    Out[6]:





<Frames>
Source File: /home/dallan/mr/mr/tests/video/image_sequence/
Frame Dimensions: 424 x 640
Cursor at Frame 0 of 5

We can print the first frame (it's an array of brightness values) or view those values as an image.



In [7]:

    
v[0]









    Out[7]:





array([[134, 133, 133, ..., 135, 136, 134],
       [137, 136, 137, ..., 135, 134, 133],
       [135, 133, 137, ..., 134, 132, 130],
       ..., 
       [130, 129, 130, ..., 133, 133, 133],
       [129, 128, 129, ..., 131, 130, 130],
       [129, 128, 129, ..., 129, 130, 131]], dtype=uint8)



In [9]:

    
imshow(v[0], cmap=cm.gray)









    Out[9]:





<matplotlib.image.AxesImage at 0xb2c3a2c>

Because the developer does most of his work in brightfield, all of the contructors (Video, ImageSequence, TiffStack) invert black and white when they load the video. To suppress this, set invert=False.



In [21]:

    
uninverted = mr.ImageSequence('/home/dallan/mr/mr/tests/video/image_sequence/', invert=False)
imshow(uninverted[0], cmap=cm.gray)









    Out[21]:





<matplotlib.image.AxesImage at 0xb802e2c>

Use subsections of the loaded frames.

We can select a subset of the frames for viewing or processing. Examples:

v[3] frame three (an array)
v[:10] first 10 frames (a list of arrays)
v[2:5] frames 2-5 including 2 and 5 (a list of arrays)
v[100:] frames 100 to the end (a list of arrays)

Load video files or multi-frame TIFFs.

ImageSequence relies only on numpy and scipy, which are required dependencies of mr, so it works out of the box. Video needs OpenCV, which includes the Python module cv2. TiffStack needs libtiff.

Once these dependencies are in place, Video and TiffStack work in the same way as ImageSequence.



In [16]:

    
v = mr.Video('/home/dallan/mr/mr/tests/water/bulk-water.mov')



In [19]:

    
v









    Out[19]:





<Frames>
Source File: /home/dallan/mr/mr/tests/video/stuck.tif
Frame Dimensions: 512 x 512
Cursor at Frame 0 of 5



In [18]:

    
v = mr.TiffStack('/home/dallan/mr/mr/tests/video/stuck.tif')



In [20]:

    
v









    Out[20]:





<Frames>
Source File: /home/dallan/mr/mr/tests/video/stuck.tif
Frame Dimensions: 512 x 512
Cursor at Frame 0 of 5

Extra tools

If OpenCV is installed, some convenient video tools are available. These work for any Frames.

mr.play(v) plays back the frames. You can slow playback by specifying a delay in miliseconds, like mr.play(v, wait=100).
mr.circle(f, v) takes a DataFrame of features or trajectories and circles them over the video.
You can save the annotated videos displayed by mr.circle using mr.circle(f, v, write_file='some_file.avi').

If OpenCV is not installed, you can still view individual frames using imshow(v[frame_number]) and annotated frames using annotate(f[f.frame == frame_number], v[frame_number]).