moseq2_extract.io package

IO - Image Module

Image reading/writing functionality.

moseq2_extract.io.image.read_image(filename, scale=True, scale_key='scale_factor')

Load image data

Args: filename (str): path to output file scale (bool): flag that indicates whether to scale image scale_key (str): indicates scale factor.

Returns: image (numpy.ndarray): loaded image

moseq2_extract.io.image.read_tiff_files(input_dir)

Read ROI output results (Tiff files) located in the given input_directory.

Args: input_dir (str): path to directory containing ROI files.

Returns: images (list): list of 2d arrays of the ROIs. filenames (list): list of corresponding filenames to each read image.

moseq2_extract.io.image.write_image(filename, image, scale=True, scale_factor=None, frame_dtype='uint16', compress=0)

Save image data.

Args: filename (str): path to output file image (numpy.ndarray): the (unscaled) 2-D image to save scale (bool): flag to scale the image between the bounds of dtype scale_factor (int): factor by which to scale image frame_dtype (str): array data type compress (int): image compression level

IO - Video Module

Video and video-metadata read/write functions.

moseq2_extract.io.video.get_movie_info(filename, frame_size=(512, 424), bit_depth=16, mapping='DEPTH', threads=8, **kwargs)

Return dict of movie metadata.

Args: filename (str): path to video file frame_dims (tuple): video dimensions bit_depth (int): integer indicating data type encoding mapping (str): the stream to read from mkv files threads (int): number of threads to simultaneously read timestamps stored within the raw data file.

Returns: metadata (dict): dictionary containing video file metadata

moseq2_extract.io.video.get_raw_info(filename, bit_depth=16, frame_size=(512, 424))

Get info from a raw data file with specified frame dimensions and bit depth.

Args: filename (str): name of raw data file bit_depth (int): bits per pixel (default: 16) frame_dims (tuple): wxh or hxw of each frame

Returns: file_info (dict): dictionary containing depth file metadata

moseq2_extract.io.video.get_stream_names(filename, stream_tag='title')

Run an FFProbe command to determine whether an input video file contains multiple streams, and returns a stream_name to paired int values to extract the desired stream.

Args: filename (str): path to video file to get streams from. stream_tag (str): value of the stream tags for ffprobe command to return

Returns: out (dict): Dictionary of string to int pairs for the included streams in the mkv file. Dict will be used to choose the correct mapping number to choose which stream to read in read_frames().

moseq2_extract.io.video.get_video_info(filename, mapping='DEPTH', threads=8, count_frames=False, **kwargs)

Get file metadata from videos.

Args: filename (str): name of file to read video metadata from. mapping (str): chooses the stream to read from files. threads (int): number of threads to simultanoues run the ffprobe command count_frames (bool): indicates whether to count the frames individually.

Returns: out_dict (dict): dictionary containing video file metadata

moseq2_extract.io.video.load_movie_data(filename, frames=None, frame_size=(512, 424), bit_depth=16, **kwargs)

Parse file extension and load the movie data into numpy array.

Args: filename (str): Path to video. frames (int or list): Frame indices to read in to output array. frame_size (tuple): Video dimensions (nrows, ncols) bit_depth (int): Number of bits per pixel, corresponds to image resolution. kwargs (dict): Any additional parameters that could be required in read_frames_raw().

Returns: frame_data (numpy.ndarray): Read video as numpy array. (nframes, nrows, ncols)

moseq2_extract.io.video.load_timestamps_from_movie(input_file, threads=8, mapping='DEPTH')

Run a ffprobe command to extract the timestamps from the .mkv file, and pipes the output data to a csv file.

Args: filename (str): path to input file to extract timestamps from. threads (int): number of threads to simultaneously read timestamps mapping (str): chooses the stream to read from mkv files. (Will default to if video is not an mkv format)

Returns: timestamps (list): list of float values representing timestamps for each frame.

moseq2_extract.io.video.read_frames(filename, frames=range(0, 0), threads=6, fps=30, frames_is_timestamp=False, pixel_format='gray16le', movie_dtype='uint16', frame_size=None, slices=24, slicecrc=1, mapping='DEPTH', get_cmd=False, finfo=None, **kwargs)

Read in frames from the .mp4/.avi file using a pipe from ffmpeg.

Args: filename (str): filename to get frames from frames (list or numpy.ndarray): list of frames to grab threads (int): number of threads to use for decode fps (int): frame rate of camera frames_is_timestamp (bool): if False, indicates timestamps represent kinect v2 absolute machine timestamps, pixel_format (str): ffmpeg pixel format of data movie_dtype (str): An indicator for numpy to store the piped ffmpeg-read video in memory for processing. frame_size (str): wxh frame size in pixels slices (int): number of slices to use for decode slicecrc (int): check integrity of slices mapping (str): the stream to read from mkv files. get_cmd (bool): indicates whether function should return ffmpeg command (instead of executing). finfo (dict): dictionary containing video file metadata

Returns: video (numpy.ndarray): frames x rows x columns

moseq2_extract.io.video.read_frames_raw(filename, frames=None, frame_size=(512, 424), bit_depth=16, movie_dtype='<u2', **kwargs)

Reads in data from raw binary file.

Args: filename (string): name of raw data file frames (list or range): frames to extract frame_dims (tuple): wxh of frames in pixels bit_depth (int): bits per pixel (default: 16) movie_dtype (str): An indicator for numpy to store the piped ffmpeg-read video in memory for processing.

Returns: chunk (numpy ndarray): nframes x h x w

moseq2_extract.io.video.read_mkv(filename, frames=range(0, 0), pixel_format='gray16be', movie_dtype='uint16', frames_is_timestamp=True, timestamps=None, **kwargs)

Read in frames from a .mkv file using a pipe from ffmpeg.

Args: filename (str): filename to get frames from frames (list or numpy.ndarray): list of frame indices to read pixel_format (str): ffmpeg pixel format of data movie_dtype (str): An indicator for numpy to store the piped ffmpeg-read video in memory for processing. frames_is_timestamp (bool): if False, use machine timestamp if True, use frame as timestamp timestamps (list): array of timestamps to slice into using the frame indices threads (int): number of threads to use for decode fps (int): frame rate of camera in Hz frame_size (str): wxh frame size in pixels frame_dtype (str): indicates the data type to use when reading the videos slices (int): number of slices to use for decode slicecrc (int): check integrity of slices mapping (int): ffmpeg channel mapping; “o:mapping”; chooses the stream to read from mkv files. get_cmd (bool): indicates whether function should return ffmpeg command (instead of executing).

Returns: video (numpy.ndarray): frames x rows x columns

moseq2_extract.io.video.write_frames(filename, frames, threads=6, fps=30, pixel_format='gray16le', codec='ffv1', close_pipe=True, pipe=None, frame_dtype='uint16', slices=24, slicecrc=1, frame_size=None, get_cmd=False)

Write frames to avi file using the ffv1 lossless encoder

Args: filename (str): path to file to write to. frames (np.ndarray): frames to write threads (int): number of threads to write video fps (int): frames per second pixel_format (str): format video color scheme codec (str): ffmpeg encoding-writer method to use close_pipe (bool): indicates to close the open pipe to video when done writing. pipe (subProcess.Pipe): pipe to currently open video file. frame_dtype (str): indicates the data type to use when writing the videos slices (int): number of frame slices to write at a time. slicecrc (int): check integrity of slices frame_size (tuple): shape/dimensions of image. get_cmd (bool): indicates whether function should return ffmpeg command (instead of executing)

Returns: pipe (subProcess.Pipe): indicates whether video writing is complete.

moseq2_extract.io.video.write_frames_preview(filename, frames=array([], dtype=float64), threads=6, fps=30, pixel_format='rgb24', codec='h264', slices=24, slicecrc=1, frame_size=None, depth_min=0, depth_max=80, get_cmd=False, cmap='jet', pipe=None, close_pipe=True, frame_range=None, progress_bar=False)

Simple command to pipe frames to an ffv1 file. Writes out a false-colored mp4 video.

Args: filename (str): path to file to write to. frames (np.ndarray): frames to write threads (int): number of threads to write video fps (int): frames per second pixel_format (str): format video color scheme codec (str): ffmpeg encoding-writer method to use slices (int): number of frame slices to write at a time. slicecrc (int): check integrity of slices frame_size (tuple): shape/dimensions of image. depth_min (int): minimum mouse depth from floor in (mm) depth_max (int): maximum mouse depth from floor in (mm) get_cmd (bool): indicates whether function should return ffmpeg command (instead of executing) cmap (str): color map to use. pipe (subProcess.Pipe): pipe to currently open video file. close_pipe (bool): indicates to close the open pipe to video when done writing. frame_range (range()): frame indices to write on video progress_bar (bool): If True, displays a TQDM progress bar for the video writing progress.

Returns: pipe (subProcess.Pipe): indicates whether video writing is complete.