optimap.video¶

Functions for loading, viewing, filtering, saving and exporting videos.

optimap.video.load_video(path, start_frame=0, frames=None, step=1, use_mmap=False, **kwargs)[source]¶

Loads a video from a file or folder, automatically detecting the file type.

If path is a folder, it will load a video from a series of images in the folder.

Supported file types:

.tif, .tiff (TIFF stack)
.mat (MATLAB), loads the first field in the file
.dat (MultiRecorder)
.gsd, .gsh (SciMedia MiCAM 05)
.rsh, .rsm, .rsd (SciMedia MiCAM ULTIMA)
.npy (numpy array)

Supported file types when loading a folder:

.tif, .tiff images
.png images

For some file types read-only memory mapping is used when use_mmap=True. This is useful for large videos, as it does not load the entire video into memory, only loading the frames when they are accessed. However, it is not supported for all file types, and it is not possible to write to the video array. Supported file types for memory mapping:

.tif, .tiff (TIFF stack)
.dat (MultiRecorder)
.npy (numpy array)

Parameters:

path (str or pathlib.Path) – Path to video file, or folder containing images
start_frame (int, optional) – Index of the starting frame (0-indexed). Defaults to 0.
frames (int or None, optional) – Number of frames to load. If None, loads all frames till the end.
step (int, optional) – Steps between frames. If greater than 1, it will skip frames. Defaults to 1.
use_mmap (bool, optional) – If True, uses memory mapping to load the video in read-only mode, defaults to False. Only supported for some file types.
**kwargs (dict) – Additional arguments to pass to the video loader function

Returns:

video – Video array

Return type:

{t, x, y} ndarray

optimap.video.load_metadata(filename)[source]¶

Loads metadata information from a recording, automatically detecting the file type.

Supported file types:

.gsd, .gsh (SciMedia MiCAM 05)
.rsh, .rsm, .rsd (SciMedia MiCAM ULTIMA)
.dat (MultiRecorder)

Parameters:: filename (str or pathlib.Path) – Path to video file
Returns:: Dictionary containing the metadata
Return type:: dict

optimap.video.load_image_folder(path, prefix='', start_frame=0, end_frame=None, step=1)[source]¶

Loads a sequences of images from a folder as a video.

The filenames are sorted in natural order (i.e ‘frame_2.png’ comes before ‘frame_10.png’) and loaded in that order. The prefix parameter can be used to filter the files to load.

The start_frame, end_frame and step parameters can be used to load only a subset of the images. Note that they refer to the index of the images in the sorted list of files.

Supported image extensions (case-insensitive):

.tif and .tiff
.png

Parameters:

path (str or pathlib.Path) – Path to folder containing the images
prefix (str, optional) – Prefix of the image files to load, by default “”.
start_frame (int, optional) – Index of the starting frame (0-indexed). Defaults to 0.
end_frame (int or None, optional) – Index of the ending frame (non-inclusive). If None, loads all frames till the end.
step (int, optional) – Steps between frames. If greater than 1, it will skip frames. Defaults to 1.

Returns:

3D numpy array containing the loaded images

Return type:

np.ndarray

optimap.video.save_video(filename, video, **kwargs)[source]¶

Save a video to a file. Supported file formats are .npy, .tif/.tiff, and .mat.

See save_tiff_folder() for saving a video as a folder of .tiff images.

See export_video() for exporting a video to a movie file (e.g. .mp4).

Parameters:

filename (str or pathlib.Path) – Filename to save to
video (np.ndarray) – Video to save
**kwargs (dict) – Additional arguments to pass to the respective save function

optimap.video.save_image_sequence(directory: str | Path, video: ndarray, filepattern: str = 'frame_{:03d}', format='.png', **kwargs)[source]¶

Save a video as a sequence of images.

This function will create a directory if it does not exist, and save each frame of the video as an image. The images are named according to the provided file pattern and format.

Example

import numpy as np
import optimap as om

video = np.random.rand(100, 100, 100)
om.save_image_sequence("my_folder", video, filepattern="frame_{:03d}", format=".png")

Will create a folder my_folder and save the images as my_folder/frame_000.png, my_folder/frame_001.png, etc.

Parameters:

directory (str or pathlib.Path) – Directory to save to
video (np.ndarray or list of np.ndarray) – The video to save as a sequence of images
filepattern (str) – The pattern to use for the filenames. The pattern should include a placeholder for the frame number, e.g., ‘frame_{:03d}’. Default is ‘frame_{:03d}’.
format (str) – Image format to save as, e.g., ‘.png’, ‘.jpg’, .tiff etc. Default is ‘.png’.
**kwargs (dict) – Additional arguments to pass to skimage.io.imsave() or tifffile.imwrite() (for .tiff files)

optimap.video.save_matlab(array, filename, fieldname='video', appendmat=True)[source]¶

Save an array to a MATLAB .mat file.

Parameters:

array (np.ndarray) – Array to save
filename (str or pathlib.Path) – Filename to save to
fieldname (str, optional) – Name of the field to save the array to, by default 'video'
appendmat (bool, optional) – Whether to append to an existing file, by default True

optimap.video.save_tiff(filename, video, photometric='minisblack', **kwargs)[source]¶

Save a video as a monochromatic TIFF stack.

Parameters:

video (np.ndarray) – Video to save
filename (str or pathlib.Path) – Filename to save to
photometric (str, optional) – Photometric interpretation, by default 'minisblack'
**kwargs (dict) – Additional arguments to pass to tifffile.imwrite()

optimap.video.save_tiff_folder(directory, video, filepattern='frame_{:03d}')[source]¶

Save a video as a folder of TIFF images. See save_image_sequence() for details.

Parameters:

directory (str or pathlib.Path) – Directory to save to
video (np.ndarray) – Video to save
filepattern (str) – File pattern of the images, by default 'frame_{:03d}'

optimap.video.export_video(filename: str | Path, video: ndarray | Iterable[ndarray], fps: int = 60, skip_frames: int = 1, cmap='gray', vmin: float = None, vmax: float = None, progress_bar: bool = True, ffmpeg_encoder: str = None, pad_mode: str = 'edge')[source]¶

Export a video numpy array to a video file (e.g. .mp4) using ffmpeg.

Downloads pre-built ffmpeg automatically if ffmpeg is not installed.

Example

import optimap as om
import numpy as np

video = np.random.rand(100, 100, 100)
om.export_video("video.mp4", video, fps=30, cmap="viridis")

Parameters:

filename (str or Path) – Video file path for writing.
video (np.ndarray or Iterable[np.ndarray]) – The video to export. Should be of shape (frames, height, width, channels) or (frames, height, width). If the video is grayscale, the colormap will be applied. If it’s an RGB video, its values should range [0, 1] or [0, 255] (np.uint8).
fps (int, optional) – The framerate of the output video, by default 60
skip_frames (int, optional) – Only export every skip_frames frames, by default 1
cmap (str, optional) – The matplotlib colormap to use, by default “gray”
vmin (float, optional) – The minimum value for the colormap, by default None
vmax (float, optional) – The maximum value for the colormap, by default None
progress_bar (bool, optional) – Whether to show a progress bar, by default True
ffmpeg_encoder (str, optional) – The ffmpeg encoder to use, by default 'libx264'. See set_default_ffmpeg_encoder() and set_ffmpeg_defaults() for more information.
pad_mode (str, optional) – Odd-sized videos need to be padded to even dimensions, otherwise ffmpeg will error. The padding mode to use, by default “edge”. See numpy.pad() for more information.

optimap.video.export_videos(filename: str | Path, videos: ndarray | List[ndarray], ncols: int = 6, padding: int = 0, padding_color='black', fps: int = 60, skip_frames: int = 1, cmaps: str | List[str] = 'gray', vmins: float | List[float] = None, vmaxs: float | List[float] = None, ffmpeg_encoder: str = None, progress_bar: bool = True)[source]¶

Export a list of videos to a video file (e.g. .mp4) by arranging them side by side in a grid.

Uses optimap.image.collage() to arrange the video frames in a grid.

Example

import optimap as om
import numpy as np

videos = [
    np.random.rand(100, 100, 100),
    np.random.rand(100, 100, 100),
    np.random.rand(100, 100, 100),
    np.random.rand(100, 100, 100),
]

cmaps = ["gray", "viridis", "plasma", "inferno"]
om.export_videos("collage.mp4", videos, ncols=2, padding=10,
                        padding_color="white", cmaps=cmaps)

Parameters:

filename (str or Path) – Video file path for writing.
videos (np.ndarray or List[np.ndarray]) – The videos to export. Should be of shape (frames, height, width, channels) or (frames, height, width). If the video is grayscale, the colormap will be applied. If it’s an RGB video, its values should range [0, 1] or [0, 255] (np.uint8).
ncols (int, optional) – The number of columns in the collage, by default 6
padding (int, optional) – The padding between the videos in pixels, by default 0
padding_color (str or np.ndarray (np.uint8), optional) – The color of the padding, by default ‘black’
fps (int, optional) – The framerate of the output video, by default 60
skip_frames (int, optional) – Only export every skip_frames frame, by default 1
cmaps (str or List[str], optional) – The matplotlib colormap to use, by default “gray”
vmins (float or List[float], optional) – The minimum value for the colormap, by default None
vmaxs (float or List[float], optional) – The maximum value for the colormap, by default None
ffmpeg_encoder (str, optional) – The ffmpeg encoder to use, by default 'libx264'. See set_default_ffmpeg_encoder() and set_ffmpeg_defaults() for more information.
progress_bar (bool, optional) – Whether to show a progress bar, by default True

optimap.video.export_video_with_overlay(filename: str | Path, base: ndarray, overlay: ndarray, alpha: ndarray = None, fps: int = 60, skip_frames: int = 1, cmap_base='gray', cmap_overlay='Purples', vmin_base=None, vmax_base=None, vmin_overlay=None, vmax_overlay=None, ffmpeg_encoder=None, progress_bar: bool = True)[source]¶

Blends two videos together using alpha blending and exports it to a video file (e.g. .mp4).

The base video is blended with the overlay video using an alpha channel. If no alpha channel is provided, the overlay array is used as alpha channel (if it is grayscale) or the alpha channel of the overlay video is used (if it is RGBA). The alpha channel is expected to be in the range [0, 1], a value of 0 means that the base video is used, a value of 1 means that the overlay video is used.

Parameters:

filename (str or Path) – Video file path for writing.
base (np.ndarray) – The base video. Should be of shape (frames, height, width) or (frames, height, width, channels). Either uint8 or float32 (expected to be in the range [0, 1]).
overlay (np.ndarray) – The overlay video. Should be of shape (frames, height, width) or(frames, height, width, channels). Either uint8 or float32 (expected to be in the range [0, 1]).
alpha (np.ndarray, optional) – The alpha channel to use for blending, by default None. Expected to be in range [0, 1], and of shape (T, X, Y) or (X, Y). If None, the overlay array is used (if grayscale) or the alpha channel of the overlay video is used (if RGBA).
fps (int, optional) – The framerate of the output video, by default 60
skip_frames (int, optional) – Only export every skip_frames frames, by default 1
cmap_base (str or matplotlib.colors.Colormap, optional) – The colormap to use for the base video, by default 'gray'
cmap_overlay (str or matplotlib.colors.Colormap, optional) – The colormap to use for the overlay video, by default 'Purples'
vmin_base (float, optional) – The minimum value for the base video, by default None
vmax_base (float, optional) – The maximum value for the base video, by default None
vmin_overlay (float, optional) – The minimum value for the overlay video, by default None
vmax_overlay (float, optional) – The maximum value for the overlay video, by default None
ffmpeg_encoder (str, optional) – The ffmpeg encoder to use, by default 'libx264'. See set_default_ffmpeg_encoder() and set_ffmpeg_defaults() for more information.
progress_bar (bool, optional) – Whether to show a progress bar, by default True

optimap.video.play(video, skip_frame=1, title='', vmin=None, vmax=None, cmap='gray', interval=10, **kwargs)[source]¶: Deprecated alias for optimap.video.show_video().

optimap.video.play2(video1, video2, skip_frame=1, title1='', title2='', vmin1=None, vmax1=None, vmin2=None, vmax2=None, cmap1='gray', cmap2='gray', interval=10, **kwargs)[source]¶: Deprecated alias for optimap.video.show_video_pair().

optimap.video.playn(videos, skip_frame=1, titles=None, cmaps='gray', vmins=None, vmaxs=None, interval=10, **kwargs)[source]¶: Deprecated alias for optimap.video.show_videos().

optimap.video.play_with_overlay(*args, **kwargs)[source]¶: Deprecated alias for optimap.video.show_video_overlay().

optimap.video.show_videos(videos, skip_frame=1, titles=None, cmaps='gray', vmins=None, vmaxs=None, interval=10, **kwargs)[source]¶

Video player for n side-by-side videos based on matplotlib’s animate function.

Parameters:

videos (list of {t, x, y} np.ndarray) – Videos to play.
skip_frame (int, optional) – Skip every n-th frame, by default 1
titles (list of str, optional) – Titles of the videos, by default None
cmaps (str or list of str, optional) – Colormaps to use for the videos, by default “gray”
vmins (float or list of floats, optional) – Minimum values for the colorbars, by default None
vmaxs (float or list of floats, optional) – Maximum values for the colorbars, by default None
interval (int, optional) – Delay between frames in ms, by default 10. This is not the actual framerate, but the delay between frames.
**kwargs – Additional keyword arguments passed to matplotlib.pyplot.subplots()

Return type:

InteractivePlayer

optimap.video.show_video(video, skip_frame=1, title='', vmin=None, vmax=None, cmap='gray', interval=10, **kwargs)[source]¶

Simple video player based on matplotlib’s animate function.

See optimap.video.show_video_pair() for a player for two videos side-by-side, and optimap.video.show_videos() for a player for n videos side-by-side.

Note

Using Monochrome is an alternative to this function, which allows for more control over the video player.

See monochrome.show_array() for more information.

>>> import monochrome as mc
>>> mc.show_array(video)

Parameters:

video ({t, x, y} np.ndarray) – Video to play.
skip_frame (int, optional) – Skip every n-th frame, by default 1
title (str, optional) – Title of the video, by default “”
vmin (float, optional) – Minimum value for the colorbar, by default None
vmax (float, optional) – Maximum value for the colorbar, by default None
cmap (str, optional) – Colormap to use, by default “gray”
interval (int, optional) – Delay between frames in ms, by default 10. This is not the actual framerate, but the delay between frames.
**kwargs – Additional keyword arguments passed to matplotlib.pyplot.subplots()

Return type:

InteractivePlayer

optimap.video.show_video_pair(video1, video2, skip_frame=1, title1='video1', title2='video2', cmap1='gray', cmap2='gray', interval=10, vmin1=None, vmax1=None, vmin2=None, vmax2=None, **kwargs)[source]¶

Video player for two videos side-by-side based on matplotlib’s animate function.

Parameters:

video1 ({t, x, y} np.ndarray) – First video to play.
video2 ({t, x, y} np.ndarray) – Second video to play.
skip_frame (int, optional) – Skip every n-th frame, by default 1
title1 (str, optional) – Title of the first video, by default “video1”
title2 (str, optional) – Title of the second video, by default “video2”
cmap1 (str, optional) – Colormap to use for the first video, by default “gray”
cmap2 (str, optional) – Colormap to use for the second video, by default “gray”
vmin1 (float, optional) – Minimum value for the colorbar of the first video, by default None
vmax1 (float, optional) – Maximum value for the colorbar of the first video, by default None
vmin2 (float, optional) – Minimum value for the colorbar of the second video, by default None
vmax2 (float, optional) – Maximum value for the colorbar of the second video, by default None
interval (int, optional) – Delay between frames in ms, by default 10. This is not the actual framerate, but the delay between frames.
**kwargs – Additional keyword arguments passed to matplotlib.pyplot.subplots()

Return type:

InteractivePlayer

optimap.video.show_video_overlay(base: ndarray, overlay: ndarray, alpha: ndarray = None, skip_frames: int = 1, cmap_base='gray', cmap_overlay='Purples', vmin_base=None, vmax_base=None, vmin_overlay=None, vmax_overlay=None, interval=10, **kwargs)[source]¶

Play a video with an overlay. See export_video_with_overlay() and iter_alpha_blend_videos() for more information.

Parameters:

base (np.ndarray) – Base video to play.
overlay (np.ndarray) – Video to overlay on the base video.
alpha (np.ndarray, optional) – Alpha channel for the overlay, by default None
skip_frames (int, optional) – Show every n-th frame, by default 1
cmap_base (str or matplotlib.colors.Colormap, optional) – Colormap to use for the base video, by default “gray”
cmap_overlay (str or matplotlib.colors.Colormap, optional) – Colormap to use for the overlay video, by default “Purples”
vmin_base (float, optional) – Minimum value for the colorbar of the base video, by default None
vmax_base (float, optional) – Maximum value for the colorbar of the base video, by default None
vmin_overlay (float, optional) – Minimum value for the colorbar of the overlay video, by default None
vmax_overlay (float, optional) – Maximum value for the colorbar of the overlay video, by default None
interval (int, optional) – Delay between frames in ms, by default 10. This is not the actual framerate, but the delay between frames.
**kwargs – Additional keyword arguments passed to matplotlib.pyplot.subplots()

Return type:

matplotlib.animation.FuncAnimation

optimap.video.rotate_left(video, k=1)[source]¶

Rotate video by 90° counter-clockwise (left).

Parameters:

video ({t, x, y} ndarray) – Video to rotate.
k (int, optional) – Number of times to rotate by 90°, by default 1

Returns:

Rotated video.

Return type:

{t, y, x} ndarray

optimap.video.rotate_right(video, k=1)[source]¶

Rotate video by 90° clockwise (right).

Parameters:

video ({t, x, y} ndarray) – Video to rotate.
k (int, optional) – Number of times to rotate by 90°, by default 1

Returns:

Rotated video.

Return type:

{t, y, x} ndarray

optimap.video.flip_up_down(video)[source]¶

Flip Video up-down.

Parameters:: video ({t, x, y} ndarray) – Video to flip.
Returns:: Flipped video.
Return type:: {t, x, y} ndarray

optimap.video.flip_left_right(video)[source]¶

Flip Video left-right.

Parameters:: video ({t, x, y} ndarray) – Video to flip.
Returns:: Flipped video.
Return type:: {t, x, y} ndarray

optimap.video.resize(video, shape=None, scale=None, interpolation='cubic')[source]¶

Resize video.

Either shape or scale must be specified.

Interpolation method is applied to each frame individually. See optimap.image.resize() for interpolation methods, “area” is recommended for downsampling as it gives moire-free results.

Parameters:

video ({t, x, y} np.ndarray) – Video to resize.
shape ((new_x, new_y) tuple) – Spatial shape of resized video. Either this or scale must be specified.
scale (float) – Scale factor to apply to video, e.g. 0.5 for half the size. Either this or shape must be specified.
interpolation (str, optional) – Interpolation method to use, by default “cubic”. See optimap.image.resize() for interpolation methods.

Returns:

Resized video.

Return type:

3D np.ndarray

optimap.video.crop(video, width)[source]¶

Crop Video by width pixels on each side.

Parameters:

video ({t, x, y} ndarray) – Video to crop.
width (int) – Width of crop.

Return type:

{t, x-2*width, y-2*width} ndarray

optimap.video.pad(video, width, mode='constant', **kwargs)[source]¶

Pad Video by width pixels on each side.

Parameters:

video ({t, x, y} ndarray) – Video to pad.
width (int) – Width of padding.
mode (str, optional) – Padding mode, by default ‘constant’. See numpy.pad() for details and additional keyword arguments.
**kwargs (dict, optional) – Additional keyword arguments passed to numpy.pad().

Return type:

{t, x+2*width, y+2*width} ndarray

optimap.video.normalize(array: ~numpy.ndarray, ymin=0, ymax=None, vmin=None, vmax=None, dtype=<class 'numpy.float32'>, clip=True)[source]¶

Normalize an array (video, image, …) to a specified range and data type.

By default, the input will be normalized to the interval [0, 1] with type np.float32 based on the minumum and maximum value of the input array.

If parameters vmin or vmax are specified, the normalization is performed using these values and the resulting array will be clipped.

The parameters ymin and ymax specify the minimum and maximum values of the resulting array, by default 0 and 1 if dtype is a floating point type, or the maximum value of the data type if dtype is an integer type.

Examples

import optimap as om
import numpy as np

filepath = om.download_example_data("Sinus_Rabbit_1.npy")
video = om.load_video(filepath)

# normalize video to interval [0, 1] using the minimum and maximum values of the video
video_normalized = om.video.normalize(video)

# normalize video to interval [0, 255] by converting the video to uint8
video_normalized_uint8 = om.video.normalize(video, ymin=0, ymax=255, dtype=np.uint8)

Parameters:

array (ndarray) – The input array to be normalized.
ymin (float, optional) – Minimum value of the resulting video, by default 0
ymax (float, optional) – Maximum value of the resulting video, by default 1 for floating point arrays, or the maximum value of the data type for integer arrays.
vmin (float, optional) – Minimum value of the input video, by default None If None, the minimum value of the input video is calculated.
vmax (float, optional) – Maximum value of the input video, by default None If None, the maximum value of the input video is calculated.
dtype (type, optional) – Data type of the resulting array, by default np.float32
clip (bool, optional) – If True, the resulting video will be clipped to [ymin, ymax], by default True Only applies if vmin or vmax are specified.

Returns:

Normalized array/video/image.

Return type:

ndarray

optimap.video.normalize_pixelwise(video: ndarray, ymin=0, ymax=1)[source]¶

Normalizes video pixel-wise to interval [ymin, ymax].

Parameters:

video ({t, x, y} ndarray) – The input video to be normalized.
ymin (float, optional) – Minimum value, by default 0
ymax (float, optional) – Maximum value, by default 1

Returns:

Normalized video.

Return type:

{t, x, y} ndarray

optimap.video.normalize_pixelwise_slidingwindow(video: ndarray, window_size: int, ymin=0, ymax=1)[source]¶

Normalizes video pixel-wise using a temporal sliding window.

For each frame t in the video, this function normalizes its pixels based on the pixel values within a window spanning from [t - window_size//2, t + window_size//2]. The normalization maps pixel values to the interval [ymin, ymax].

Note

If window_size if even, the window size will be increased by 1 to make it odd. This is to ensure that the window is symmetric around the current frame t.

The window shrinks at the beginning and end of the video, where there are not enough frames to fill the window.

Parameters:

video ({t, x, y} ndarray) – The input video to be normalized.
window_size (int) – The size of the sliding window.
ymin (float, optional) – The minimum value of the normalization interval. Default is 0.
ymax (float, optional) – The maximum value of the normalization interval. Default is 1.

Returns:

Normalized video.

Return type:

{t, x, y} ndarray

optimap.video.smooth_spatiotemporal(video: ndarray, sigma_temporal, sigma_spatial)[source]¶

Smooth video using a Gaussian filter in space and time.

Parameters:

video ({t, x, y} ndarray) – video to smooth
sigma_temporal (float) – Standard deviation for Gaussian kernel in time.
sigma_spatial (float) – Standard deviation for Gaussian kernel in space.

Returns:

Filtered video.

Return type:

{t, x, y} ndarray

optimap.video.temporal_difference(array: ndarray, n: int, fill_value: float = 0, center: bool = False)[source]¶

Temporal difference filter using an offset of n frames.

Computes temporal intensity changes in the videos or traces between frames at time \(t\) and \(t - \Delta t\):

\[\text{signal}_{\text{diff}}(t) = \text{signal}(t) - \text{signal}(t - \Delta t)\]

where \(\Delta t\) is the time difference between frames (usually set to \(\Delta t = 1-5\) frames).

The resulting signal is padded with fill_value to keep the original shape. If center is set to True, the padding is centered around the signal, otherwise it is added to the beginning.

Parameters:

array (ndarray) – Video or signal to filter. First axis is assumed to be time.
n (int) – Offset in frames.
fill_value (float, optional) – Value to fill the padded frames with, by default 0
center (bool, optional) – If True, the padding is centered around the signal, by default False

Returns:

Filtered video/signal.

Return type:

ndarray

optimap.video.evolve_jitter_filter(video, framerate=500.0, threshold=0.004)[source]¶

Jitter removal filter for Photometrics Evolve 128 camera.

Parameters:

video ({t, x, y} ndarray) – Video to filter.
framerate (float) – Framerate in Hz.
threshold (float) – Threshold.

Returns:

Filtered video.

Return type:

{t, x, y} ndarray

optimap.video.alpha_blend_videos(*args, **kwargs)[source]¶

Blends two videos together using alpha blending.

Wrapper around iter_alpha_blend_videos() that returns the blended video as a numpy array.

Returns:: The blended video as with rgba channels.
Return type:: np.ndarray {frames, height, width, 4}

optimap.video.iter_alpha_blend_videos(base: ndarray, overlay: ndarray, alpha: ndarray = None, skip_frames: int = 1, cmap_base='gray', cmap_overlay='Purples', vmin_base=None, vmax_base=None, vmin_overlay=None, vmax_overlay=None)[source]¶

Blends two videos together using alpha blending. Yields the blended video frame by frame.

Parameters:

base (np.ndarray) – The base video. Should be of shape (frames, height, width) or (frames, height, width, channels). Either uint8 or float32 (expected to be in the range [0, 1]).
overlay (np.ndarray) – The overlay video. Should be of shape (frames, height, width) or(frames, height, width, channels). Either uint8 or float32 (expected to be in the range [0, 1]).
alpha (np.ndarray, optional) – The alpha channel to use for blending, by default None. Expected to be in range [0, 1], and of shape (T, X, Y) or (X, Y). If None, the overlay array is used (if grayscale) or the alpha channel of the overlay video is used (if RGBA).
skip_frames (int, optional) – Only export every skip_frames frames, by default 1
cmap_base (str or matplotlib.colors.Colormap, optional) – The colormap to use for the base video, by default 'gray'
cmap_overlay (str or matplotlib.colors.Colormap, optional) – The colormap to use for the overlay video, by default 'Purples'
vmin_base (float, optional) – The minimum value for the base video, by default None
vmax_base (float, optional) – The maximum value for the base video, by default None
vmin_overlay (float, optional) – The minimum value for the overlay video, by default None
vmax_overlay (float, optional) – The maximum value for the overlay video, by default None
ffmpeg_encoder (str, optional) – The ffmpeg encoder to use, by default 'libx264'. See set_default_ffmpeg_encoder() and set_ffmpeg_defaults() for more information.

Yields:

np.ndarray {height, width, 4} – The blended video frame.

optimap.video.smoothstep(x, vmin=0, vmax=1, N=2)[source]¶

Smoothly clamps the input array to the range [0, 1] using the smoothstep function. Useful for e.g. creating alpha channels.

Parameters:

x (np.ndarray) – The input array.
vmin (float, optional) – The minimum value of the input array, by default 0
vmax (float, optional) – The maximum value of the input array, by default 1
N (int, optional) – The order of the polynomial, by default 2

Returns:

The smoothly clamped array, with values in the range [0, 1].

Return type:

np.ndarray

optimap.video.set_ffmpeg_defaults(encoder: str, params: dict)[source]¶

Set the default ffmpeg parameters to use for exporting videos.

Parameters:

encoder (str) – The ffmpeg encoder for which the parameters apply. E.g. ‘libx264’ or ‘h264_nvenc’.
params (dict) – The ffmpeg parameters to use. E.g. {‘-c:v’: ‘libx264’, ‘-crf’: ‘15’, ‘-preset’: ‘slower’}.

optimap.video.set_default_ffmpeg_encoder(encoder: str)[source]¶

Set the default ffmpeg encoder to use for exporting videos.

Parameters:: encoder (str) – The ffmpeg encoder to use. E.g. ‘libx264’ or ‘h264_nvenc’.

optimap.video.get_default_ffmpeg_encoder()[source]¶

Get the default ffmpeg encoder to use for exporting videos.

Returns:: The ffmpeg encoder to use. E.g. ‘libx264’ or ‘h264_nvenc’.
Return type:: str

class optimap.video.InteractivePlayer(fig, func, start=0, end=100, step=1, interval=25, gui_pos=(0.125, 0.92), **kwargs)[source]¶

Bases: FuncAnimation

Generic interactive looping player with play, pause, forward, backward, and slider controls based on matplotlib.animation.FuncAnimation.

Calls a function at each frame to update the figure content with the current frame index. Can be used to create custom video players or other interactive animations, see optimap.show_video() as an example of how to use this class.

**Keyboard Shortcuts**¶
Key	Action
`Space`	Play/Pause
`Left`	Last frame
`Right`	Next frame
`Up`	Increase step size
`Down`	Decrease step size
`q`	Quit

Example

import numpy as np
import matplotlib.pyplot as plt
from optimap.video import InteractivePlayer
fig, ax = plt.subplots()
x = np.linspace(0, 2*np.pi, 100)
line, = ax.plot(x, np.sin(x))
def update(i):
    line.set_ydata(np.sin(x + i / 10))
player = InteractivePlayer(fig, update, end=len(x))
plt.show()

Parameters:

fig (matplotlib.figure.Figure) – Figure to plot on.
func (callable) – Function to call at each frame. Must accept a single integer argument (frame index).
start (int, optional) – Start frame, by default 0
end (int, optional) – End frame (exclusive), by default 100
step (int, optional) – Step size for forward and backward buttons, by default 1
interval (int, optional) – Delay between frames in milliseconds, by default 25
gui_pos (tuple, optional) – Position of the GUI elements (play, slider, etc.), by default (0.125, 0.92)
**kwargs – Additional keyword arguments passed to matplotlib.animation.FuncAnimation

save(*args, hide_slider=True, hide_buttons=True, hide_framecounter=False, **kwargs)[source]¶

Save the animation as a movie file, but hide the GUI buttons and slider.

Parameters:

*args – See FuncAnimation’s save() for arguments.
hide_slider (bool, optional) – Hide the slider, by default True
hide_buttons (bool, optional) – Hide the play/pause button, by default True
hide_framecounter (bool, optional) – Hide the frame counter, by default False
**kwargs – See FuncAnimation’s save() for arguments.

class optimap.video.MultiRecorderImporter(filepath, is_8bit=False)[source]¶

Bases: object

Importer for MultiRecorder (MPI-DS) recordings (.dat files).

get_metadata()[source]¶: Returns the metadata dictionary.

load_video(start_frame=0, frames=None, step=1, use_mmap=False)[source]¶: Returns a 3D numpy array containing the loaded video.

get_frametimes()[source]¶

MultiRecoder can encode the time at which each frame was recorded as a unsigned 64-bit integer.

The exact meaning of value depends on the camera plugin.

Returns:: frametimes – Array of frame times for each frame in the file
Return type:: np.ndarray

class optimap.video.MiCAM05_Importer(filepath)[source]¶

Bases: object

Importer for SciMedia MiCAM05 CMOS camera recordings (.gsh / .gsd files).

Warning

Tested only on sample MiCAM05-N256 camera files with 256x256 pixels resolution.

load_video(start_frame=0, frames=None, step=1)[source]¶: Returns a 3D numpy array containing the loaded video.

get_metadata()[source]¶: Returns the metadata dictionary.

class optimap.video.MiCAM_ULTIMA_Importer(filepath)[source]¶

Bases: object

Importer for SciMedia MiCAM ULTIMA recordings (.rsh / .rsm / .rsd files).

load_video(start_frame=0, frames=None, step=1)[source]¶: Returns a 3D numpy array containing the loaded video.

get_metadata()[source]¶: Returns the metadata dictionary.