Video¶

PIMS provides reading of video through PyAV (fastest), ImageIO or MoviePy.

PyAV (fastest)¶

PyAV can be installed via Anaconda, as follows:

conda install av -c conda-forge

Non-anaconda users will have to compile PyAV themselves, which is complicated, especially on Windows. For this we refer the users to the PyAV documentation.

There are two ways PIMS provides random access to video files, which is not something that video formats natively support:

PyAVReaderTimed bases the indices of the video frames on the frame_rate that is reported by the video file, along with the timestamps that are imprinted on the separate video frames. The readers PyAVVideoReader and Video are different names for this reader.
PyAVReaderIndexed scans through the entire video to build a table of contents. This means that opening the file can take some time, but once it is open, random access is fast. In the case timestamps or frame_rate` are not available, this reader is the preferred option.

class pims.PyAVReaderTimed(file, cache_size=16, fast_forward_thresh=32, stream_index=0, format=None)[source]¶

Read images from a video file via a direct FFmpeg/AVbin interface.

The frames are indexed according to their ‘timestamp’, starting at 0 at the timestamp of the first non-empty frame. Missing frames are filled in with empty frames. The number of frames in the video is estimated from the movie duration and the average frame rate.

Parameters

filenamestring
cache_sizeinteger, optional: the number of frames that are kept in memory. Default 16.
fast_forward_threshinteger, optional: the reader will proceed through the frames if forwarding below this number. If forwarding above this number, it will use seek(). Default 32.
stream_indexinteger, optional: the index of the video stream inside the file. rarely other than 0.

Examples

>>> video = PyAVVideoReader('video.avi')  # or .mov, etc.
>>> video[0] # Show the first frame.
>>> video[-1] # Show the last frame.
>>> video[1][0:10, 0:10] # Show one corner of the second frame.

>>> for frame in video[:]:
...    # Do something with every frame.

>>> for frame in video[10:20]:
...    # Do something with frames 10-20.

>>> for frame in video[[5, 7, 13]]:
...    # Do something with frames 5, 7, and 13.

>>> frame_count = len(video) # Number of frames in video
>>> frame_shape = video.frame_shape # Pixel dimensions of video

Attributes

duration: The video duration in seconds.
exts: Property to get the extensions of a FramesStream class.
frame_rate
frame_shape: Returns the shape of a single frame as a tuple ex (10, 12)
pixel_type: Returns a numpy.dtype for the data type of the pixel values

Methods

`class_exts`()	Return a set of the file extensions that this reader can deal with.
`close`(self)	A method to clean up anything that need to be cleaned up.
`get_frame`(self, i)	Sub classes must over-ride this function for how to get a given frame out of the file.
`seek`(self, i)	Seek to a frame before i and return the first frame.

classmethod class_exts()[source]¶

Return a set of the file extensions that this reader can deal with.

Sub-classes should over-ride this function to list what extensions they deal with.

The default interpretation of the returned set is ‘file extensions including but not exclusively’.

property duration¶: The video duration in seconds.

property frame_shape¶: Returns the shape of a single frame as a tuple ex (10, 12)

get_frame(self, i)[source]¶: Sub classes must over-ride this function for how to get a given frame out of the file. Any data-type specific internal-state nonsense should be dealt with in this function.

property pixel_type¶: Returns a numpy.dtype for the data type of the pixel values

seek(self, i)[source]¶: Seek to a frame before i and return the first frame.

class pims.PyAVReaderIndexed(file, toc=None, format=None)[source]¶

Read images from the frames of a standard video file into an iterable object that returns images as numpy arrays.

Parameters

filenamestring

Examples

>>> video = Video('video.avi')  # or .mov, etc.
>>> imshow(video[0]) # Show the first frame.
>>> imshow(video[-1]) # Show the last frame.
>>> imshow(video[1][0:10, 0:10]) # Show one corner of the second frame.

>>> for frame in video[:]:
...    # Do something with every frame.

>>> for frame in video[10:20]:
...    # Do something with frames 10-20.

>>> for frame in video[[5, 7, 13]]:
...    # Do something with frames 5, 7, and 13.

>>> frame_count = len(video) # Number of frames in video
>>> frame_shape = video.frame_shape # Pixel dimensions of video

Attributes

exts: Property to get the extensions of a FramesStream class.
frame_shape: Returns the shape of a single frame as a tuple ex (10, 12)
pixel_type: Returns a numpy.dtype for the data type of the pixel values
toc

Methods

`class_exts`()	Return a set of the file extensions that this reader can deal with.
`close`(self)	A method to clean up anything that need to be cleaned up.
`get_frame`(self, j)	Sub classes must over-ride this function for how to get a given frame out of the file.

classmethod class_exts()[source]¶

Return a set of the file extensions that this reader can deal with.

Sub-classes should over-ride this function to list what extensions they deal with.

The default interpretation of the returned set is ‘file extensions including but not exclusively’.

property frame_shape¶: Returns the shape of a single frame as a tuple ex (10, 12)

get_frame(self, j)[source]¶: Sub classes must over-ride this function for how to get a given frame out of the file. Any data-type specific internal-state nonsense should be dealt with in this function.

property pixel_type¶: Returns a numpy.dtype for the data type of the pixel values

ImageIO and MoviePy¶

Both ImageIO and MoviePy implement interfaces with ffmpeg through a Pipe. These are implemented through ImageIOReader and MoviePyReader, respectively.

class pims.ImageIOReader(filename, **kwargs)[source]¶

Attributes

axes: Returns a list of all axes.
bundle_axes: This determines which axes will be bundled into one Frame.
default_coords: When a axis is not present in both iter_axes and bundle_axes, the coordinate contained in this dictionary will be used.
exts: Property to get the extensions of a FramesStream class.
frame_rate
frame_shape: Returns the shape of the frame as returned by get_frame.
iter_axes: This determines which axes will be iterated over by the FramesSequence.
ndim: Returns the number of axes.
pixel_type: Returns a numpy.dtype for the data type of the pixel values
sizes: Returns a dict of all axis sizes.

Methods

`class_exts`()	Return a set of the file extensions that this reader can deal with.
`close`(self)	A method to clean up anything that need to be cleaned up.
`get_frame`(self, i)	Returns a Frame of shape determined by bundle_axes.

get_frame_2D
get_metadata

classmethod class_exts()[source]¶

Return a set of the file extensions that this reader can deal with.

Sub-classes should over-ride this function to list what extensions they deal with.

The default interpretation of the returned set is ‘file extensions including but not exclusively’.

close(self)[source]¶

A method to clean up anything that need to be cleaned up.

Sub-classes should use super to call up the MRO stack and then do any class-specific clean up

property frame_shape¶: Returns the shape of the frame as returned by get_frame.

property pixel_type¶: Returns a numpy.dtype for the data type of the pixel values