cddm.video

Video processing tools.

You can use this helper functions to perform normalization, background subtraction and windowing on multi-frame data.

There are also function for real-time display of videos for real-time analysis.

Module Contents

cddm.video.fromarrays(arrays)

Creates a multi-frame iterator from given list of arrays.

Parameters

arrays (tuple of array-like) – A tuple of array-like objects that represent a single-camera videos

Returns

video – A multi-frame iterator

Return type

iterator

cddm.video.asarrays(video, count=None)

Loads multi-frame video into numpy arrays.

Parameters

  • video (iterable) – A multi-frame iterator object.

  • count (int, optional) – Defines how many frames are in the video. If not provided it will calculate length of the video based on the length of the iterable. If that is not possible ValueError is raised

Returns

out – A tuple of array(s) representing video(s)

Return type

tuple of arrays

cddm.video.asmemmaps(basename, video, count=None)

Loads multi-frame video into numpy memmaps.

Actual data is written to numpy files with the provide basename and subscripted by source identifier (index), e.g. “basename_0.npy” and “basename_1.npy” in case of dual-frame video source.

Parameters

  • basename (str) – Base name for the filenames of the videos.

  • video (iterable) – A multi-frame iterator object.

  • count (int, optional) – Defines how many multi-frames are in the video. If not provided it is determined by len().

Returns

out – A tuple of memmapped array(s) representing video(s)

Return type

tuple of arrays

cddm.video.load(video, count=None)

Loads video into memory.

Parameters

  • video (iterable) – A multi-frame iterator object.

  • count (int, optional) – Defines how many frames are in the video. If not provided it will calculate length of the video based on the length of the iterable. If that is not possible ValueError is raised

Returns

out – A video iterable. A tuple of multi-frame data (arrays)

Return type

tuple

cddm.video.crop(video, roi=(slice(None), slice(None)))

Crops each frame in the video.

Parameters

  • video (iterable) – Input multi-frame iterable object. Each element of the iterable is a tuple of ndarrays (frames)

  • roi (tuple) – A tuple of two slice objects for slicing in first axis (height) and the second axis (width). You can also provide a tuple arguments tuple that are past to the slice builtin function.

Returns

video – A multi-frame iterator

Return type

iterator

Examples

One option is to provide roi with indices. To crop frames like frame[10:100,20:120]

>>> video = random_video(count = 100)
>>> video = crop(video, roi = ((10,100),(20,120)))

Or you can use slice objects to perform crop

>>> video = crop(video, roi = (slice(10,100),slice(20,120)))
cddm.video.mask(video, mask=None)

Masks each frame in the video.

Parameters

  • video (iterable) – Input multi-frame iterable object. Each element of the iterable is a tuple of ndarrays (frames)

  • mask (ndarrray) – A boolean index array for masking (boolean indexing).

Returns

video – A multi-frame iterator

Return type

iterator

cddm.video.subtract(x, y, inplace=False, dtype=None)

Subtracts two videos.

Parameters

  • x (iterable) – Input multi-frame iterable object. Each element of the iterable is a tuple of ndarrays (frames)

  • y (iterable) – Input multi-frame iterable object. Each element of the iterable is a tuple of ndarrays (frames)

  • inplace (bool, optional) – Whether tranformation is performed inplace or not.

  • dtype (numpy dtype) – If specifed, determines output dtype. Only valid if inplace == False.

Returns

video – A multi-frame iterator

Return type

iterator

cddm.video.add(x, y, inplace=False, dtype=None)

Adds two videos.

Parameters

  • x (iterable) – Input multi-frame iterable object. Each element of the iterable is a tuple of ndarrays (frames)

  • y (iterable) – Input multi-frame iterable object. Each element of the iterable is a tuple of ndarrays (frames)

  • inplace (bool, optional) – Whether tranformation is performed inplace or not.

  • dtype (numpy dtype) – If specifed, determines output dtype. Only valid if inplace == False.

Returns

video – A multi-frame iterator

Return type

iterator

cddm.video.normalize_video(video, inplace=False, dtype=None)

Normalizes each frame in the video to the mean value (intensity).

Parameters

  • video (iterable) – Input multi-frame iterable object. Each element of the iterable is a tuple of ndarrays (frames)

  • inplace (bool, optional) – Whether tranformation is performed inplace or not.

  • dtype (numpy dtype) – If specifed, determines output dtype. Only valid if inplace == False.

Returns

video – A multi-frame iterator

Return type

iterator

cddm.video.multiply(x, y, inplace=False, dtype=None)

Multiplies two videos.

Parameters

  • x (iterable) – Input multi-frame iterable object. Each element of the iterable is a tuple of ndarrays (frames)

  • y (iterable) – Input multi-frame iterable object. Each element of the iterable is a tuple of ndarrays (frames)

  • inplace (bool, optional) – Whether tranformation is performed inplace or not.

  • dtype (numpy dtype) – If specifed, determines output dtype. Only valid if inplace == False.

Returns

video – A multi-frame iterator

Return type

iterator

class cddm.video.ImageShow(title='video', norm_func=lambda x: ...)

A simple interface for video visualization using matplotlib, opencv, or pyqtgraph.

Parameters

  • title (str) – Title of the video

  • norm_func (callable) – Normalization function that takes a single argument (array) and returns a single element (array). Can be used to apply custom normalization function to the image before it is shown.

show(self, im)

Shows image

Parameters

im (ndarray) – A 2D array

cddm.video.pause(i=1)

Pause in milliseconds needed to update matplotlib or opencv figures For pyqtgraph, it performs app.processEvents()

cddm.video.play(video, fps=100.0, max_delay=0.1)

Plays video for real-time visualization.

You must first call show functions (e.g. show_video()) to specify what needs to be played. This function performs the actual display when in a for loop.

Parameters

  • video (iterable) – A multi-frame iterable object.

  • fps (float) – Expected FPS of the input video. If rendering of video is too slow for the expected frame rate, frames will be skipped to assure the expected acquisition. Therefore, you must match exactly the acquisition frame rate with this parameter.

  • max_delay (float) – Max delay that visualization can produce before it starts skipping frames.

Returns

video – A multi-frame iterator

Return type

iterator

Examples

First create some test data of a dual video

>>> video = random_video(count = 256, dual = True)
>>> video = show_video(video)

Now we can load video to memory, and play it as we load frame by frame…

>>> v1,v2 = asarrays(play(video, fps = 30),count = 256)

See also

video.play_threaded()

cddm.video.play_threaded(video, fps=None)

Plays video for real-time visualization.

You must first call show functions (e.g. show_video()) to specify what needs to be played. This function performs the actual display when in a for loop. It works similar to play(), but it first creates a thread and starts the video iterator in the background.

Parameters

  • video (iterable) – A multi-frame iterable object.

  • fps (float, optional) – Desired video fps for display. This may be different from the actual video fps. If not set, it will display video as fast as possible.

Returns

video – A multi-frame iterator

Return type

iterator

Examples

First create some test data of a dual video

>>> video = random_video(count = 256, dual = True)
>>> video = show_video(video)

Now we can load video to memory, and play it as we load frame by frame…

>>> v1,v2 = asarrays(play_threaded(video, fps = 30),count = 256)

See also

video.play()

cddm.video.figure_title(name)

Generate a unique figure title

cddm.video.norm_rfft2(clip=None, mode='real')

Returns a frame normalizing function for show_video()

cddm.video.show_fft(video, id=0, title=None, clip=None, mode='abs')

Show fft of the video.

Parameters

  • video (iterator) – A multi-frame iterator

  • id (int) – Frame index

  • title (str, optional) – Unique title of the video. You can use video.figure_title() to create a unique name.

  • clip (float, optional) – Clipping value. If not given, it is determined automatically.

  • mode (str, optional) – What to display, “real”, “imag” or “abs”

Returns

video – A multi-frame iterator

Return type

iterator

cddm.video.show_video(video, id=0, title=None, norm_func=lambda x: ...)

Returns a video and performs image live video show. This works in connection with play() that does the actual display.

Parameters

  • video (iterator) – A multi-frame iterator

  • id (int) – Frame index

  • title (str) – Unique title of the video. You can use figure_title() a to produce unique name.

  • norm_func (callable) – Normalization function that takes a single argument (array) and returns a single element (array). Can be used to apply custom normalization function to the image before it is shown.

Returns

video – A multi-frame iterator

Return type

iterator

cddm.video.show_diff(video, title=None, normalize=False, dt=None, t1=None, t2=None)

Returns a video and performs image difference live video show. This works in connection with play() that does the actual display.

Parameters

  • video (iterator) – A multi-frame iterator

  • title (str) – Unique title of the video. You can use figure_title() a to produce unique name.

  • normalize (bool) – Whether to normalize frames to its mean value before subtracting. Note that this does not normalize the output video, only the displayed video is normalized.

Returns

video – A multi-frame iterator

Return type

iterator

cddm.video.random_video(shape=(512, 512), count=256, dtype=FDTYPE, max_value=1.0, dual=False)

Random multi-frame video generator, useful for testing.