Video processors

Batch process

class simba.video_processors.batch_process_create_ffmpeg_commands.FFMPEGCommandCreator(json_path: str)[source]

Bases: object

Execute FFmpeg commands from instructions stored in json format.

Parameters

json_path (str) – path to json file storing FFmpeg instructions as created by simba.batch_process_vides.BatchProcessFrame.

Notes

Batch pre-process tutorials. Example expected JSON file.

Examples

>>> ffmpeg_executor = FFMPEGCommandCreator(json_path='MyJsonFilePath')
>>> ffmpeg_executor.crop_videos()
>>> ffmpeg_executor.clip_videos()
>>> ffmpeg_executor.downsample_videos()
>>> ffmpeg_executor.apply_fps()
>>> ffmpeg_executor.apply_grayscale()
>>> ffmpeg_executor.apply_frame_count()
>>> ffmpeg_executor.apply_clahe()
>>> ffmpeg_executor.move_all_processed_files_to_output_folder()

Get pixels per millimeter

Extract frames

Extract .SEQ frames

Created on Fri Oct 4 14:39:50 2019

@authors: Xiaoyu Tong, Jia Jie Choong, Simon Nilsson

Multi-cropper

class simba.video_processors.multi_cropper.MultiCropper(file_type: typing_extensions.Literal['avi', 'mp4', 'mov', 'flv', 'm4v'], input_folder: Union[str, PathLike], output_folder: Union[str, PathLike], crop_cnt: int, gpu: Optional[bool] = False)[source]

Bases: object

Crop each video of a specific file format (e.g., mp4) in a directory into N smaller cropped videos.

Note

Multi-crop tutorial.

Expected GPU timesavings.

_static/img/multicrop.png
Parameters

  • input_folder (Union[str, os.PathLike]) – Folder path holding videos to be cropped.

  • file_type (Literal['avi', 'mp4', 'mov', 'flv', 'm4v']) – File type of input video files inside the input_folder directory.

  • output_folder (Union[str, os.PathLike]) – Directory where to store the cropped videos.

  • crop_cnt (int) – The number of cropped videos to create from each input video. Minimum: 2.

  • gpu (bool) – If True, use GPU codecs, else CPU. Default CPU.

Get pixels per millimeter - old

Video processing tools

class simba.video_processors.video_processing.VideoRotator(input_path: Union[str, PathLike], output_dir: Union[str, PathLike], gpu: Optional[bool] = False, ffmpeg: Optional[bool] = False)[source]

Bases: ConfigReader

GUI Tool for rotating video. Rotated video is saved with the _rotated_DATETIME.mp4 suffix.

_images/VideoRotator.gif
Parameters

  • input_path (str) – Path to video to rotate.

  • output_dir (str) – Directory where to save the rotated video.

  • gpu (Optional[bool]) – If True, use FFMPEG NVIDEA GPU codecs. Else CPU codecs.

  • gpu – If True, use FFPMPEG. Else, OpenCV.

Example

>>> VideoRotator(input_path='project_folder/videos/Video_1.mp4', output_dir='project_folder/videos')
simba.video_processors.video_processing.append_audio(video_path: Union[str, PathLike], audio_path: Union[str, PathLike], audio_src_type: typing_extensions.Literal['video', 'audio'] = 'video') → None[source]

Append audio track from one video to another video without an audio track.

Parameters

  • video_one_path (Union[str, os.PathLike]) – Path to video file without audio track.

  • audio_path (Union[str, os.PathLike]) – Path to file (e.g., video) with audio track.

  • audio_src_type (Literal['video', 'audio']) – Type of audio source of “video_two_path” (e.g., video or audio file).

Example

>>> append_audio(video_path='/Users/simon/Desktop/envs/troubleshooting/two_black_animals_14bp/project_folder/videos/merged_video_20230425201637.mp4',
>>> audio_path="/Users/simon/Documents/Zoom/ddd/video1180732233.mp4")
simba.video_processors.video_processing.batch_convert_video_format(directory: Union[str, PathLike], input_format: str, output_format: str, gpu: Optional[bool] = False) → None[source]

Batch convert all videos in a folder of specific format into a different video format. The results are stored in the same directory as the input files.

Parameters

  • directory (Union[str, os.PathLike]) – Path to video file directory.

  • input_format (str) – Format of the input files (e.g., avi).

  • output_format (str) – Format of the output files (e.g., mp4).

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = batch_convert_video_format(directory='project_folder/videos', input_format='avi', output_format='mp4')
simba.video_processors.video_processing.batch_create_frames(directory: Union[str, PathLike]) → None[source]

Extract all frames for all videos in a directory. Results are stored within sub-directories in the input directory named according to the video files.

Parameters

directory (str) – Path to directory containing video files.

Example

>>> _ = batch_create_frames(directory='project_folder/videos')
simba.video_processors.video_processing.batch_video_to_greyscale(directory: Union[str, PathLike], gpu: Optional[bool] = False) → None[source]

Convert a directory of video file to greyscale mp4 format. The results are stored in the same directory as the input files with the _grayscale.mp4 suffix.

_images/to_greyscale.gif
Parameters

  • directory (Union[str, os.PathLike]) – Path to directory holding video files in color.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Raises

FFMPEGCodecGPUError – If no GPU is found and gpu == True.

Example

>>> _ = batch_video_to_greyscale(directory='/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/videos/test_2')
simba.video_processors.video_processing.change_fps_of_multiple_videos(directory: Union[str, PathLike], fps: int, gpu: Optional[bool] = False) → None[source]

Change the fps of all video files in a folder. Results are stored in the same directory as in the input files with the suffix _fps_new_fps.

Parameters

  • directory (Union[str, os.PathLike]) – Path to video file directory

  • fps (int) – Fps of the new video files.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = change_fps_of_multiple_videos(directory='project_folder/videos/Video_1.mp4', fps=15)
simba.video_processors.video_processing.change_img_format(directory: Union[str, PathLike], file_type_in: str, file_type_out: str, verbose: Optional[bool] = False) → None[source]

Convert the file type of all image files within a directory.

Parameters

  • directory (Union[str, os.PathLike]) – Path to directory holding image files

  • file_type_in (str) – Input file type, e.g., ‘bmp’ or ‘png.

  • file_type_out (str) – Output file type, e.g., ‘bmp’ or ‘png.

  • verbose (Optional[bool]) – If True, prints progress. Default False.

Example

>>> _ = change_img_format(directory='/Users/simon/Desktop/envs/simba/troubleshooting/two_black_animals_14bp/test_img', file_type_in='png', file_type_out='bmp', verbose=True)
simba.video_processors.video_processing.change_single_video_fps(file_path: Union[str, PathLike], fps: int, gpu: Optional[bool] = False) → None[source]

Change the fps of a single video file. Results are stored in the same directory as in the input file with the suffix _fps_new_fps.

Note

To change the FPS of all videos in a directory, use simba.video_processors.video_processing.change_fps_of_multiple_videos.

Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file

  • fps (int) – Fps of the new video file.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = change_single_video_fps(file_path='project_folder/videos/Video_1.mp4', fps=15)
simba.video_processors.video_processing.clahe_enhance_video(file_path: Union[str, PathLike], clip_limit: Optional[int] = 2, tile_grid_size: Optional[Tuple[int]] = (16, 16), out_path: Optional[Union[str, PathLike]] = None) → None[source]

Convert a single video file to clahe-enhanced greyscale .avi file. The result is saved with prefix CLAHE_ in the same directory as in the input file if out_path is not passed. Else saved at the out_path.

_images/clahe_enhance_video.gif
Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file.

  • clip_limit (Optional[int]) – CLAHE amplification limit. Inccreased clip limit reduce noise in output. Default: 2.

  • tile_grid_size (Optional[Tuple[int]]) – The histogram kernel size.

Example

>>> _ = clahe_enhance_video(file_path: 'project_folder/videos/Video_1.mp4')
simba.video_processors.video_processing.clip_video_in_range(file_path: Union[str, PathLike], start_time: str, end_time: str, out_dir: Optional[Union[str, PathLike]] = None, overwrite: Optional[bool] = False, include_clip_time_in_filename: Optional[bool] = False, gpu: Optional[bool] = False) → None[source]

Clip video within a specific range. The result is stored in the same directory as the input file with the _clipped.mp4 suffix.

Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file

  • start_time (str) – Start time in HH:MM:SS format.

  • end_time (str) – End time in HH:MM:SS format.

  • out_dir (Optional[Union[str, os.PathLike]]) – If None, then the clip will be stored in the same dir as the input video. If directory, then the location of the output files.

  • include_clip_time_in_filename (Optional[bool]) – If True, include the clip start and end in HH-MM-SS format as suffix in the filename. If False, then use integer suffic representing the count.

  • overwrite (Optional[bool]) – If True, the overwrite output file if path already exist. If False, then raise FileExistError.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = clip_video_in_range(file_path='project_folder/videos/Video_1.avi', start_time='00:00:05', end_time='00:00:10')
simba.video_processors.video_processing.clip_videos_by_frame_ids(file_paths: List[Union[str, PathLike]], frm_ids: List[List[int]], save_dir: Optional[Union[str, PathLike]] = None)[source]

Clip videos specified by frame IDs (numbers).

Parameters

  • file_paths (List[Union[str, os.PathLike]]) – List of paths to input video files.

  • frm_ids (List[List[int]]) – List of lists containing start and end frame IDs for each video.

  • save_dir (Optional[Union[str, os.PathLike]]) – Directory to save the clipped videos. If None, videos will be saved in the same directory as the input videos with frame numbers as suffix.

Returns

None.

Example

>>> file_paths = ['/Users/simon/Desktop/envs/simba/troubleshooting/beepboop174/project_folder/frames/output/path_plots/Trial    10.mp4', '/Users/simon/Desktop/envs/simba/troubleshooting/beepboop174/project_folder/frames/output/path_plots/Trial    10_1.mp4']
>>> frm_ids = [[0, 20], [20, 40]]
>>> clip_videos_by_frame_ids(file_paths=file_paths, frm_ids=frm_ids, save_dir='/Users/simon/Desktop/envs/simba/troubleshooting/beepboop174/project_folder/frames/output/path_plots/trial_cnt')
simba.video_processors.video_processing.convert_to_avi(path: Union[str, PathLike], codec: typing_extensions.Literal['xvid', 'divx', 'mjpeg'] = 'divx', save_dir: Optional[Union[str, PathLike]] = None, quality: Optional[int] = 60) → None[source]

Convert a directory containing videos, or a single video, to AVI format using passed quality and codec.

Parameters

  • path (Union[str, os.PathLike]) – Path to directory or file.

  • codec (Literal['xvid', 'divx', 'mjpeg']) – Method to encode the AVI format. Default: xvid.

  • save_dir (Optional[Optional[Union[str, os.PathLike]]]) – Directory where to save the converted videos. If None, then creates a directory in the same directory as the input.

  • quality (Optional[int]) – Integer representing the quality: 10, 20, 30.. 100.

Returns

None.

simba.video_processors.video_processing.convert_to_bmp(directory: Union[str, PathLike], verbose: Optional[bool] = False) → None[source]

Convert images in a directory to BMP format.

Parameters

  • directory (Union[str, os.PathLike]) – Directory containing the images.

  • verbose (Optional[bool]) – If True, print conversion progress. Default is False.

Returns

None.

simba.video_processors.video_processing.convert_to_jpeg(directory: Union[str, PathLike], quality: Optional[int] = 95, verbose: Optional[bool] = False) → None[source]

Convert the file type of all image files within a directory to jpeg format of passed quality.

Note

Quality above 95 should be avoided; 100 disables portions of the JPEG compression algorithm, and results in large files with hardly any gain in image quality

Parameters

  • directory (Union[str, os.PathLike]) – Path to directory holding image files

  • quality (Optional[int]) – The quality of the output images (0-100).

  • verbose (Optional[bool]) – If True, prints progress. Default False.

Example

>>> convert_to_jpeg(directory='/Users/simon/Desktop/imgs', file_type_in='.png', quality=15)
simba.video_processors.video_processing.convert_to_mov(path: Union[str, PathLike], codec: typing_extensions.Literal['prores', 'animation', 'dnxhd', 'cineform'] = 'prores', save_dir: Optional[Union[str, PathLike]] = None, quality: Optional[int] = 60) → None[source]

Convert a directory containing videos, or a single video, to MOV format using passed quality and codec.

Parameters

  • path (Union[str, os.PathLike]) – Path to directory or file.

  • codec (Literal['prores', 'animation']) – Method to encode the MOV format. Default: prores.

  • save_dir (Optional[Optional[Union[str, os.PathLike]]]) – Directory where to save the converted videos. If None, then creates a directory in the same directory as the input.

  • quality (Optional[int]) – Integer representing the quality: 10, 20, 30.. 100.

Returns

None.

simba.video_processors.video_processing.convert_to_mp4(path: Union[str, PathLike], codec: typing_extensions.Literal['libx265', 'libx264', 'vp9', 'powerpoint'] = 'libx265', save_dir: Optional[Union[str, PathLike]] = None, quality: Optional[int] = 60) → None[source]

Convert a directory containing videos, or a single video, to MP4 format using passed quality and codec.

Parameters

  • path (Union[str, os.PathLike]) – Path to directory or file.

  • codec (Literal['libx265', 'libx264', 'vp9', 'powerpoint']) –

  • save_dir (Optional[Optional[Union[str, os.PathLike]]]) – Directory where to save the converted videos. If None, then creates a directory in the same directory as the input.

  • quality (Optional[int]) – Integer representing the quality: 10, 20, 30.. 100.

Returns

None.

Example

>>> convert_to_mp4(path='/Users/simon/Desktop/video_test', quality="60", codec='vp9')
simba.video_processors.video_processing.convert_to_png(directory: Union[str, PathLike], verbose: Optional[bool] = False) → None[source]

Convert images in a directory to PNG format.

Parameters

  • directory (Union[str, os.PathLike]) – Directory containing the images.

  • verbose (Optional[bool]) – If True, print conversion progress. Default is False.

Returns

None.

simba.video_processors.video_processing.convert_to_tiff(directory: Union[str, PathLike], stack: Optional[bool] = False, compression: typing_extensions.Literal['raw', 'tiff_deflate', 'tiff_lzw'] = 'raw', verbose: Optional[bool] = False) → None[source]

Convert images in a directory to TIFF format.

Parameters

  • directory (Union[str, os.PathLike]) – The directory containing the images.

  • stack (Optional[bool]) – If True, create a TIFF stack from the images. Default is False.

  • compression (Literal['raw', 'tiff_deflate', 'tiff_lzw']) – Compression method for the TIFF file. Options are ‘raw’ (no compression), ‘tiff_deflate’, and ‘tiff_lzw’. Default is ‘raw’.

  • verbose (Optional[bool]) – If True, print conversion progress. Default is False.

Returns

None.

Example

>>> convert_to_tiff('/Users/simon/Desktop/imgs', stack=True, compression='tiff_lzw')
simba.video_processors.video_processing.convert_to_webm(path: Union[str, PathLike], codec: typing_extensions.Literal['vp8', 'vp9'] = 'vp9', save_dir: Optional[Union[str, PathLike]] = None, quality: Optional[int] = 60) → None[source]

Convert a directory containing videos, or a single video, to WEBM format using passed quality and codec.

Parameters

  • path (Union[str, os.PathLike]) – Path to directory or file.

  • codec (Literal['vp8', 'vp9', 'av1']) – Method to encode the WEBM format. Default: vp9.

  • save_dir (Optional[Optional[Union[str, os.PathLike]]]) – Directory where to save the converted videos. If None, then creates a directory in the same directory as the input.

  • quality (Optional[int]) – Integer representing the quality: 10, 20, 30.. 100.

Returns

None.

simba.video_processors.video_processing.convert_to_webp(directory: Union[str, PathLike], quality: Optional[int] = 95, verbose: Optional[bool] = True)[source]

Convert the file type of all image files within a directory to WEBP format of passed quality.

Parameters

  • directory (Union[str, os.PathLike]) – Path to directory holding image files

  • quality (Optional[int]) – The quality of the output images (0-100).

  • verbose (Optional[bool]) – If True, prints progress. Default False.

Example

>>> convert_to_webp('/Users/simon/Desktop/imgs', quality=80)
simba.video_processors.video_processing.convert_video_powerpoint_compatible_format(file_path: Union[str, PathLike], gpu: Optional[bool] = False) → None[source]

Create MS PowerPoint compatible copy of a video file. The result is stored in the same directory as the input file with the _powerpointready suffix.

Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = convert_video_powerpoint_compatible_format(file_path='project_folder/videos/Video_1.mp4')
simba.video_processors.video_processing.copy_img_folder(config_path: Union[str, PathLike], source: Union[str, PathLike]) → None[source]

Copy directory of png files to the SimBA project. The directory is stored in the project_folder/frames/input folder of the SimBA project

Parameters

  • config_path (str) – path to SimBA project config file in Configparser format.

  • source (str) – path to image folder outside SimBA project.

Example

>>> copy_img_folder(config_path='MySimBAprojectConfig', source='/DirectoryWithVideos/')
simba.video_processors.video_processing.create_blank_video(path: Union[str, PathLike], length: int, width: int, height: int, color: Optional[str] = 'black', gpu: Optional[bool] = False, verbose: Optional[bool] = False) → None[source]

Create a “blank” uni-colored video of specified size and length.

Parameters

  • path (Union[str, os.PathLike]) – Location where to store the blank video.

  • length (int) – Length of the blank video in seconds.

  • width (int) – Width of the blank video in pixels.

  • height (int) – Height of the blank video in pixels.

  • color (Optional[str]) – Color of the blank video. Default black.

  • gpu (Optional[bool]) – If True, then use FFmpeg GPU codecs. Default False.

  • verbose (Optional[bool]) – If True, prints progress. Default True.

Returns

None.

Example

>>> _ = create_blank_video(path='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/new/blank_test.mp4', length=5, width=300, height=400, gpu=False, verbose=True, color='orange')
simba.video_processors.video_processing.crop_multiple_videos(directory_path: Union[str, PathLike], output_path: Union[str, PathLike], gpu: Optional[bool] = False) → None[source]

Crop multiple videos in a folder according to crop-coordinates defined in the first video.

Parameters

  • directory_path (str) – Directory containing input videos.

  • output_path (str) – Directory where to save the cropped videos.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = crop_multiple_videos(directory_path='project_folder/videos', output_path='project_folder/videos/my_new_folder')
simba.video_processors.video_processing.crop_multiple_videos_circles(in_dir: Union[str, PathLike], out_dir: Union[str, PathLike]) → None[source]

Crop multiple videos based on circular regions of interest (ROIs) selected by the user.

_images/crop_single_video_circle.gif

Note

This function crops multiple videos based on circular ROIs selected by the user. The user is asked to define a circle manually in one video within the input directory. The function then crops all the video in the input directory according to the shape defined using the first video and saves the videos in the out_dir with the same filenames as the original videos..

Parameters

  • in_dir (Union[str, os.PathLike]) – The directory containing input video files.

  • out_dir (Union[str, os.PathLike]) – The directory to save the cropped video files.

Example

>>> crop_multiple_videos_circles(in_dir='/Users/simon/Desktop/edited/tests', out_dir='/Users/simon/Desktop')
simba.video_processors.video_processing.crop_multiple_videos_polygons(in_dir: Union[str, PathLike], out_dir: Union[str, PathLike]) → None[source]

Crop multiple videos based on polygonal regions of interest (ROIs) selected by the user.

Parameters

  • in_dir (Union[str, os.PathLike]) – The directory containing input video files.

  • out_dir (Union[str, os.PathLike]) – The directory to save the cropped video files.

Note

This function crops multiple videos based on polygonal ROIs selected by the user. The user is asked to define a polygon manually in one video within the input directory. The function then crops all the video in the input directory according to the shape defined using the first video and saves the videos in the out_dir with the same filenames as the original videos..

Example

>>> crop_multiple_videos_polygons(in_dir='/Users/simon/Desktop/edited/tests', out_dir='/Users/simon/Desktop')
simba.video_processors.video_processing.crop_single_video(file_path: Union[str, PathLike], gpu: Optional[bool] = False) → None[source]

Crop a single video using simba.video_processors.roi_selector.ROISelector interface. Results is saved in the same directory as input video with the _cropped.mp4 suffix`.

_images/crop_single_video.gif
Parameters

  • file_path (str) – Path to video file.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = crop_single_video(file_path='project_folder/videos/Video_1.mp4')
simba.video_processors.video_processing.crop_single_video_circle(file_path: Union[str, PathLike]) → None[source]

Crop a video based on circular regions of interest (ROIs) selected by the user.

_images/crop_single_video_circle.gif

Note

This function crops the input video based on circular regions of interest (ROIs) selected by the user. The user is prompted to select a circular ROI on the video frame, and the function then crops the video based on the selected ROI. The cropped video is saved with “_circle_cropped” suffix in the same directory as the input video file.

Parameters

file_path (Union[str, os.PathLike]) – The path to the input video file.

Example

>>> crop_single_video_circle(file_path='/Users/simon/Desktop/AGGRESSIVITY_4_11_21_Trial_2_camera1_rotated_20240211143355.mp4')
simba.video_processors.video_processing.crop_single_video_polygon(file_path: Union[str, PathLike]) → None[source]

Crop a video based on polygonal regions of interest (ROIs) selected by the user.

_images/roi_selector_polygon.gif
Parameters

file_path (Union[str, os.PathLike]) – The path to the input video file.

Note

This function crops the input video based on polygonal regions of interest (ROIs) selected by the user. The user is prompted to select a polygonal ROI on the video frame, and the function then crops the video based on the selected ROI. The cropped video is saved with “_polygon_cropped” suffix in the same directory as the input video file.

Example

>>> crop_single_video_polygon(file_path='/Users/simon/Desktop/AGGRESSIVITY_4_11_21_Trial_2_camera1_rotated_20240211143355.mp4')
simba.video_processors.video_processing.downsample_video(file_path: Union[str, PathLike], video_height: int, video_width: int, gpu: Optional[bool] = False) → None[source]

Down-sample a video file. The result is stored in the same directory as the input file with the _downsampled.mp4 suffix.

Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file.

  • video_height (int) – height of new video.

  • video_width (int) – width of new video.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = downsample_video(file_path='project_folder/videos/Video_1.avi', video_height=600, video_width=400)
simba.video_processors.video_processing.extract_frame_range(file_path: Union[str, PathLike], start_frame: int, end_frame: int, save_dir: Optional[Union[str, PathLike]] = None, verbose: Optional[bool] = True) → None[source]

Extract a user-defined range of frames from a video file to png format. Images are saved in a folder with the suffix _frames within the same directory as the video file.

Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file

  • start_frame (int) – First frame in range to extract

  • end_frame (int) – Last frame in range to extract.

Example

>>> _ = extract_frame_range(file_path='project_folder/videos/Video_1.mp4', start_frame=100, end_frame=500)
simba.video_processors.video_processing.extract_frames_from_all_videos_in_directory(config_path: Union[str, PathLike], directory: Union[str, PathLike]) → None[source]

Extract all frames from all videos in a directory. The results are saved in the project_folder/frames/input directory of the SimBA project

Parameters

  • config_path (str) – path to SimBA project config file in Configparser format.

  • directory (str) – path to file or folder containing videos in mp4 and/or avi format.

Example

>>> extract_frames_from_all_videos_in_directory(config_path='project_folder/project_config.ini', source='/tests/test_data/video_tests')
simba.video_processors.video_processing.extract_frames_single_video(file_path: Union[str, PathLike]) → None[source]

Extract all frames for a single. Results are stored within a subdirectory in the same directory as the input file.

Parameters

file_path (str) – Path to video file.

Example

>>> _ = extract_frames_single_video(file_path='project_folder/videos/Video_1.mp4')
simba.video_processors.video_processing.frames_to_movie(directory: Union[str, PathLike], fps: int, quality: int, out_format: Optional[typing_extensions.Literal['mp4', 'avi', 'mov']] = 'mp4', gpu: Optional[bool] = False) → None[source]

Merge all image files in a folder to a mp4 video file. Video file is stored in the same directory as the input directory sub-folder.

Note

The Image files have to have ordered numerical names e.g., 1.png, 2.png etc…

Parameters

  • directory (str) – Directory containing the images.

  • fps (int) – The frame rate of the output video.

  • quality (int) – Integer representing quatlity of the output video: 10, 20, 30.. 100. Higher values gives larger videos at higher quality. Higher values may negatively affect runtime.

  • out_format (Optional[Literal['mp4', 'avi', 'webm', 'mov']]) – The format of the output video: ‘mp4’, ‘avi’, ‘webm’, or ‘mov’. Default: mp4.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> frames_to_movie(directory='/Users/simon/Desktop/blah', fps=60, quality=60, out_format='mp4')
simba.video_processors.video_processing.gif_creator(file_path: Union[str, PathLike], start_time: int, duration: int, width: int, gpu: Optional[bool] = False) → None[source]

Create a sample gif from a video file. The result is stored in the same directory as the input file with the .gif file-ending.

Note

The height is auto-computed to retain aspect ratio

Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file.

  • start_time (int) – Start time of the gif in relation to the video in seconds.

  • duration (int) – Duration of the gif.

  • width (int) – Width of the gif.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = gif_creator(file_path='project_folder/videos/Video_1.avi', start_time=5, duration=10, width=600)
simba.video_processors.video_processing.horizontal_video_concatenator(video_paths: List[Union[str, PathLike]], save_path: Union[str, PathLike], height_px: Optional[Union[int, str]] = None, height_idx: Optional[Union[int, str]] = None, gpu: Optional[bool] = False, verbose: Optional[bool] = True) → None[source]

Concatenates multiple videos horizontally.

_images/horizontal_video_concatenator.gif
Parameters

  • video_paths (List[Union[str, os.PathLike]]) – List of input video file paths.

  • save_path (Union[str, os.PathLike]) – File path to save the concatenated video.

  • height_px (Optional[int]) – Height of the output video in pixels.

  • height_idx (Optional[int]) – Index of the video to use for determining Height.

  • gpu (Optional[bool]) – Whether to use GPU-accelerated codec (default: False).

  • (default (Optional[bool] verbose:Whether to print progress messages) – True).

Example

>>> video_paths = ['video1.mp4', 'video2.mp4']
>>> x = horizontal_video_concatenator(video_paths=video_paths, height_px=50, save_path='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/new/08102021_DOT_Rat7_8(2)_.mp4', gpu=False)
simba.video_processors.video_processing.mixed_mosaic_concatenator(video_paths: List[Union[str, PathLike]], save_path: Union[str, PathLike], gpu: Optional[bool] = False, verbose: Optional[bool] = True, uneven_fill_color: Optional[str] = 'black') → None[source]

Create a mixed mosaic video by concatenating multiple input videos in a mosaic layout of various sizes.

_images/mixed_mosaic_concatenator.png

Note

The resolution of the output video is determined by the resolution of the video path at the first index.

If an uneven number of right-panel videos ( if not (len(video_paths)-1) % 2) == 0), then the last index will be filled by uneven_fill_color.

Parameters

  • video_paths (List[Union[str, os.PathLike]]) – List of input video file paths.

  • save_path (Union[str, os.PathLike]) – File path to save the concatenated video.

  • gpu (Optional[bool]) – Whether to use GPU-accelerated codec (default: False).

  • verbose (Optional[bool]) – Whether to print progress messages (default: True).

Example

>>> video_paths = ['video1.mp4', 'video2.mp4', 'video3.mp4']
>>> save_path = '/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/new/blank_test.mp4'
>>> mixed_mosaic_concatenator(video_paths=video_paths, save_path=save_path, gpu=False, verbose=True)
simba.video_processors.video_processing.mosaic_concatenator(video_paths: List[Union[str, PathLike]], save_path: Union[str, PathLike], width_idx: Optional[Union[int, str]] = None, width_px: Optional[Union[int, str]] = None, height_idx: Optional[Union[int, str]] = None, height_px: Optional[Union[int, str]] = None, gpu: Optional[bool] = False, verbose: Optional[bool] = True, uneven_fill_color: Optional[str] = 'black') → None[source]

Concatenates multiple videos into a mosaic layout.

_images/mosaic_concatenator.png

Note

if an uneven number of videos, the last index will be filled by uneven_fill_color.

Parameters

  • video_paths (List[Union[str, os.PathLike]]) – List of input video file paths.

  • save_path (Union[str, os.PathLike]) – File path to save the concatenated video.

  • width_px (Optional[int]) – Width of the output video in pixels.

  • width_idx (Optional[int]) – Index of the video to use for determining width.

  • height_px (Optional[int]) – Height of the output video panels in pixels.

  • height_idx (Optional[int]) – Height of the video to use for determining width.

  • gpu (Optional[bool]) – Whether to use GPU-accelerated codec (default: False).

  • verbose (Optional[bool]) – Whether to print progress messages (default: True).

Example

>>> video_paths = ['/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/08102021_DOT_Rat7_8(2).mp4', '/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/08102021_DOT_Rat11_12.mp4', '/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/new/2022-06-21_NOB_IOT_23.mp4']
>>> save_path = '/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/new/blank_test.mp4'
>>> mosaic_concatenator(video_paths=video_paths, save_path=save_path, width_idx=1, height_idx=1, gpu=False)
simba.video_processors.video_processing.multi_split_video(file_path: Union[str, PathLike], start_times: List[str], end_times: List[str], out_dir: Optional[Union[str, PathLike]] = None, include_clip_time_in_filename: Optional[bool] = False, gpu: Optional[bool] = False) → None[source]

Divide a video file into multiple video files from specified start and stop times.

Parameters

  • file_path (str) – Path to input video file.

  • start_times (List[str]) – Start times in HH:MM:SS format.

  • end_times (List[str]) – End times in HH:MM:SS format.

  • out_dir (Optional[Union[str, os.PathLike]]) – If None, then the clips will be stored in the same dir as the input video. If directory, then the location of the output files.

  • include_clip_time_in_filename (Optional[bool]) – If True, include the clip start and end in HH-MM-SS format as suffix in the filename. If False, then use integer suffic representing the count.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = multi_split_video(file_path='project_folder/videos/Video_1.mp4', start_times=['00:00:05', '00:00:20'], end_times=['00:00:10', '00:00:25'])
simba.video_processors.video_processing.overlay_video_progressbar(video_path: Union[str, PathLike], bar_height: Optional[int] = 10, color: Optional[str] = 'red', save_dir: Optional[Union[str, PathLike]] = None) → None[source]

Overlay a progress bar on a directory of videos or a single video.

Parameters

  • video_path (Union[str, os.PathLike]) – Directory containing video files or a single video file

  • bar_height (Optional[int]) – The height of the progressbar in percent of the video height.

  • color (Optional[str]) – The color of the progress bar. See simba.utils.lookups.get_color_dict keys for accepted names.

  • save_dir (Optional[Union[str, os.PathLike]]) – If not None, then saves the videos in the passed directory. Else, in the same directry with the _progress_bar suffix.

Returns

None.

simba.video_processors.video_processing.remove_beginning_of_video(file_path: Union[str, PathLike], time: int, gpu: Optional[bool] = False) → None[source]

Remove N seconds from the beginning of a video file. The result is stored in the same directory as the input file with the _shorten.mp4 suffix.

Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file

  • time (int) – Number of seconds to remove from the beginning of the video.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> _ = remove_beginning_of_video(file_path='project_folder/videos/Video_1.avi', time=10)
simba.video_processors.video_processing.resize_videos_by_height(video_paths: List[Union[str, PathLike]], height: Union[int, str], overwrite: Optional[bool] = False, save_dir: Optional[Union[str, PathLike]] = None, gpu: Optional[bool] = False, suffix: Optional[str] = None, verbose: Optional[bool] = True) → Union[None, List[Union[None, str, PathLike]]][source]

Re-size a list of videos to a specified height while retaining their aspect ratios.

Parameters

  • video_paths (List[Union[str, os.PathLike]]) – List of path to videos.

  • height (Union[int, str]) – The height of the output videos. If int, then the height in pixels. If str, then the index in video_paths from which to grab the height.

  • overwrite (Optional[bool]) – If True, then overwrites the original videos. Default False.

  • save_dir (Optional[Union[str, os.PathLike]]) – If not None, then the directory where to store the re-sized videos.

  • gpu (Optional[bool]) – If True, then use FFmpeg GPU codecs. Default False.

  • suffix (Optional[bool]) – If not None, then stores the resized videos in the same directory as the input videos with the provided suffix.

  • verbose (Optional[bool]) – If True, prints progress. Default True.

Return Union[None, List[Union[str, os.PathLike]]]

If save_dir is not None, returns the paths of the re-sized videos. Else returns empty list.

Example

>>> video_paths= ['/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/08102021_DOT_Rat7_8(2).mp4', '/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/08102021_DOT_Rat11_12.mp4']
>>> _ = resize_videos_by_height(video_paths=video_paths, height=300, overwrite=False, save_dir='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/new')
simba.video_processors.video_processing.resize_videos_by_width(video_paths: List[Union[str, PathLike]], width: Union[int, str], overwrite: Optional[bool] = False, save_dir: Optional[Union[str, PathLike]] = None, gpu: Optional[bool] = False, suffix: Optional[str] = None, verbose: Optional[bool] = True) → Union[None, List[Union[None, str, PathLike]]][source]

Re-size a list of videos to a specified width while retaining their aspect ratios.

Parameters

  • video_paths (List[Union[str, os.PathLike]]) – List of path to videos.

  • width (Union[int, str]) – The width of the output videos. If int, then the width in pixels. If str, then the index in video_paths from which to grab the width.

  • overwrite (Optional[bool]) – If True, then overwrites the original videos. Default False.

  • save_dir (Optional[Union[str, os.PathLike]]) – If not None, then the directory where to store the re-sized videos.

  • gpu (Optional[bool]) – If True, then use FFmpeg GPU codecs. Default False.

  • suffix (Optional[bool]) – If not None, then stores the resized videos in the same directory as the input videos with the provided suffix.

  • verbose (Optional[bool]) – If True, prints progress. Default True.

Return Union[None, List[Union[str, os.PathLike]]]

If save_dir is not None, returns the paths of the re-sized videos. Else returns empty list.

Example

>>> video_paths= ['/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/08102021_DOT_Rat7_8(2).mp4', '/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/08102021_DOT_Rat11_12.mp4']
>>> _ = resize_videos_by_width(video_paths=video_paths, width=300, overwrite=False, save_dir='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/new')
simba.video_processors.video_processing.superimpose_frame_count(file_path: Union[str, PathLike], gpu: Optional[bool] = False, fontsize: Optional[int] = 20) → None[source]

Superimpose frame count on a video file. The result is stored in the same directory as the input file with the _frame_no.mp4 suffix.

_images/superimpose_frame_count.png _images/superimpose_frame_count.gif
Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

  • fontsize (Optional[int]) – The size of the font represetnting the current frame. Default: 20.

Example

>>> _ = superimpose_frame_count(file_path='project_folder/videos/Video_1.avi')
simba.video_processors.video_processing.vertical_video_concatenator(video_paths: List[Union[str, PathLike]], save_path: Union[str, PathLike], width_px: Optional[int] = None, width_idx: Optional[int] = None, gpu: Optional[bool] = False, verbose: Optional[bool] = True) → None[source]

Concatenates multiple videos vertically.

_images/vertical_video_concatenator.png
Parameters

  • video_paths (List[Union[str, os.PathLike]]) – List of input video file paths.

  • save_path (Union[str, os.PathLike]) – File path to save the concatenated video.

  • width_px (Optional[int]) – Width of the output video in pixels.

  • width_idx (Optional[int]) – Index of the video to use for determining width.

  • gpu (Optional[bool]) – Whether to use GPU-accelerated codec (default: False).

  • (default (Optional[bool] verbose:Whether to print progress messages) – True).

Raises
Example

>>> video_paths = ['/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/08102021_DOT_Rat7_8(2).mp4',
>>>                '/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/08102021_DOT_Rat11_12.mp4',
>>>                '/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/08102021_DOT_Rat11_12_1.mp4']
>>> _ = vertical_video_concatenator(video_paths=video_paths, width_idx=1, save_path='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/videos/test/new/08102021_DOT_Rat7_8(2)_.mp4', gpu=False)
simba.video_processors.video_processing.video_concatenator(video_one_path: Union[str, PathLike], video_two_path: Union[str, PathLike], resolution: Union[int, str], horizontal: bool, gpu: Optional[bool] = False) → None[source]

Concatenate two videos to a single video

Parameters

  • video_one_path (str) – Path to the first video in the concatenated video

  • video_two_path (str) – Path to the second video in the concatenated video

  • resolution (int or str) – If str, then the name of the video which resolution you want to retain. E.g., Video_1. Else int, representing the video width (if vertical concat) or height (if horizontal concat). Aspect raio will be retained.

  • horizontal – If true, then horizontal concatenation. Else vertical concatenation.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Example

>>> video_concatenator(video_one_path='project_folder/videos/Video_1.mp4', video_two_path='project_folder/videos/Video_2.mp4', resolution=800, horizontal=True)
simba.video_processors.video_processing.video_to_greyscale(file_path: Union[str, PathLike], gpu: Optional[bool] = False) → None[source]

Convert a video file to greyscale mp4 format. The result is stored in the same directory as the input file with the _grayscale.mp4 suffix.

_images/to_greyscale.gif
Parameters

  • file_path (Union[str, os.PathLike]) – Path to video file.

  • gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Raises
Example

>>> _ = video_to_greyscale(file_path='project_folder/videos/Video_1.avi')

Crop ROI selector (rectangles)

class simba.video_processors.roi_selector.ROISelector(path: Union[str, PathLike], thickness: int = 10, clr: Tuple[int, int, int] = (147, 20, 255), title: Optional[str] = None)[source]

Bases: object

A class for selecting and reflecting Regions of Interest (ROI) in an image. The selected region variables are stored in self: top_left, bottom_right, width, height.

_images/roi_selector.gif
Parameters

  • path (Union[str, os.PathLike]) – Path to the image or video file. Can also be an image represented as a numpy array.

  • thickness (int) – Thickness of the rectangle border for visualizing the ROI.

  • clr (Tuple[int, int, int]) – BGR color tuple for visualizing the ROI. Default: deep pink.

  • title (Optional[str]) – Title of the drawing window. If None, then Draw ROI - Press ESC when drawn.

Example

>>> img_selector = ROISelector(path='/Users/simon/Desktop/compute_overlap.png', clr=(0, 255, 0), thickness=2)
>>> img_selector.run()

Crop ROI selector (circles)

class simba.video_processors.roi_selector_circle.ROISelectorCircle(path: Union[str, PathLike], thickness: int = 10, clr: Tuple[int, int, int] = (147, 20, 255), title: Optional[str] = None)[source]

Bases: object

Class for selecting a circular region of interest (ROI) within an image or video frame. The selected region variables are stored in self: circle_center, circle_radius.

Parameters

  • path (Union[str, os.PathLike]) – Path to the image or video file. Can also be an image represented as a numpy array.

  • thickness (int) – Thickness of the circle border when visualizing the ROI.

  • clr (Tuple[int, int, int]) – BGR color tuple for visualizing the ROI. Default: deep pink.

  • title (Optional[str]) – Title of the drawing window. If None, then Draw ROI - Press ESC when drawn.

Raises

  • InvalidFileTypeError – If the file type is not supported.

  • CropWarning – If the selected ROI extends beyond the image boundaries or if the ROI radius equals zero.

_images/circle_crop_2.gif

Note

Circle crop tutorial.

Example

>>> circle_selector = ROISelectorCircle(path='/Users/simon/Desktop/amber.png')
>>> circle_selector.run()
>>> circle_selector = ROISelectorCircle(path='/Users/simon/Desktop/Box2_IF19_7_20211109T173625_4_851_873_1_cropped.mp4')
>>> circle_selector.run()

Crop ROI selector (polygons)

class simba.video_processors.roi_selector_polygon.ROISelectorPolygon(path: Union[str, PathLike], thickness: int = 2, clr: Tuple[int, int, int] = (147, 20, 255), title: Optional[str] = None)[source]

Bases: object

Class for selecting a polygonal region of interest (ROI) within an image or video frame. The selected region vertices are stored in self: polygon_vertices.

_images/roi_selector_polygon.gif
Parameters

  • path (Union[str, os.PathLike]) – Path to the image or video file. Can also be an image represented as a numpy array.

  • thickness (int) – Thickness of the polygon border when visualizing the ROI.

  • clr (Tuple[int, int, int]) – BGR color tuple for visualizing the ROI. Default: deep pink.

  • title (Optional[str]) – Title of the drawing window. If None, then Draw ROI - Press ESC when drawn.

Raises

  • InvalidFileTypeError – If the file type is not supported.

  • CropWarning – If the selected ROI extends beyond the image boundaries or if the number of vertices is less than 3.

Example

>>> polygon_selector = ROISelectorPolygon(path='/Users/simon/Desktop/amber.png')
>>> polygon_selector.run()
>>> polygon_selector = ROISelectorPolygon(path='/Users/simon/Desktop/Box2_IF19_7_20211109T173625_4_851_873_1_cropped.mp4')
>>> polygon_selector.run()

Interactive CLAHE interface

simba.video_processors.clahe_ui.interactive_clahe_ui(data: Union[str, PathLike, ndarray]) → Tuple[float, int][source]

Create a user interface using OpenCV to explore and set appropriate CLAHE settings tile size and clip limit.

_images/interactive_clahe_ui.gif
Parameters

data (Union[str, os.PathLike, np.ndarray]) – Path to a video file or a NumPy array representing an image.

Return Tuple[float, int]

Tuple containing the chosen clip limit and tile size.

Example

>>> img = cv2.imread('/Users/simon/Downloads/PXL_20240429_222923838.jpg',)
>>> interactive_clahe_ui(data=img)

Interactive brightness / contrast interface

simba.video_processors.brightness_contrast_ui.brightness_contrast_ui(data: Union[str, PathLike, ndarray]) → Tuple[float, float][source]

Create a user interface using OpenCV to explore and change the brightness and contrast of a video.

Note

Adapted from geeksforgeeks.

_images/brightness_contrast_ui.gif
Parameters

video_path (Union[str, os.PathLike]) – Path to the video file or an image in numpy array format.

Return Tuple

The scaled brightness and scaled contrast values on scale -1 to +1 and 0-2 respectively, suitable for FFmpeg conversion

Example I

>>> brightness_contrast_ui(video_path='/Users/simon/Desktop/envs/simba/troubleshooting/RAT_NOR/project_folder/frames/output/ROI_features/2022-06-20_NOB_DOT_4.mp4')
Example II

>>> img = cv2.imread('/Users/simon/Downloads/PXL_20240429_222923838.jpg')
>>> brightness_contrast_ui(data=img)