Video processors

Batch process

class simba.video_processors.batch_process_create_ffmpeg_commands.FFMPEGCommandCreator(json_path, codec='libx264')[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

Videos to frames

simba.video_processors.videos_to_frames.video_to_frames(video_path, save_dir=None, quality=95, img_format='png', verbose=True, clahe=False, greyscale=False, core_cnt=- 1, black_and_white=False, include_video_name_in_filename=True)[source]

Extract all frames from a video file and save them as individual image files.

EXPECTED RUNTIMES
OBSERVATIONS (MILLIONS)	TIME (S)	STDEV (S)
3600	31.95222333	1.035132203
7200	45.07845	1.315006481
18000	139.1806667	2.15158503
18 cors
REPEATS = 3

Note

Uses multiprocessing for faster frame extraction. Frames are saved with sequential numbering (0, 1, 2, …).

Parameters

video_path (Union[str, os.PathLike]) – Path to the video file to extract frames from.
save_dir (Union[str, os.PathLike]) – Directory where extracted frames will be saved.
quality (Optional[int]) – Image quality for JPEG format (1-100). Higher values = better quality + larger file size. Default: 95.
img_format (Literal['png', 'webp']) – Format of the output images. One of: ‘png’, ‘webp’. Default: ‘png’.
verbose (bool) – If True, prints progress messages during extraction. Default: True.
clahe (bool) – If True, applies Contrast Limited Adaptive Histogram Equalization to each frame. Default: False.
greyscale (bool) – If True, converts frames to greyscale. Default: False.
core_cnt (Optional[int]) – Number of CPU cores to use for multiprocessing. -1 uses all available cores. Default: -1.
black_and_white (bool) – If True, converts frames to black and white. Default: False.
include_video_name_in_filename (bool) – If True, includes video name in frame filenames. Default: True.

Returns

None. Frames are saved to disk in the specified directory.

Example

>>> video_to_frames(video_path=r"C:/troubleshooting/SDS_pre_post/project_folder/videos/SDI100 x ALR2 post_d7.mp4",
...                save_dir=r'C:/troubleshooting/SDS_pre_post/project_folder/videos/test',
...                black_and_white=False,
...                verbose=True,
...                img_format='webp',
...                clahe=True)

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, input_folder, output_folder, crop_cnt, gpu=False, quality=60)[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.

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.

Example

>>> cropper = MultiCropper(file_type='mp4', input_folder=r'C:/troubleshooting/mitra/test', output_folder=r'C:/troubleshooting/mitra/test/cropped', crop_cnt=2, gpu=True)
>>> cropper.run()

Get pixels per millimeter - old

Video processing tools

class simba.video_processors.video_processing.VideoRotator(input_path, output_dir, gpu=False, ffmpeg=False)[source]

Bases: simba.mixins.config_reader.ConfigReader

GUI Tool for rotating video.

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.

Returns

None. Rotated video is saved with the _rotated_DATETIME.mp4 suffix.

Example

>>> VideoRotator(input_path='project_folder/videos/Video_1.mp4', output_dir='project_folder/videos')

simba.video_processors.video_processing.append_audio(video_path, audio_path, audio_src_type='video')[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, input_format, output_format, gpu=False)[source]

Batch convert all videos in a folder of specific format into a different video format.

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.

Returns

None. The results are stored in the same directory as the input files.

Note

Codec is automatically selected: libx264 for CPU encoding (ignored if gpu=True).

Example

>>> _ = batch_convert_video_format(directory='project_folder/videos', input_format='avi', output_format='mp4')

simba.video_processors.video_processing.batch_create_frames(directory)[source]

Extract all frames for all videos in a directory.

Parameters: directory (str) – Path to directory containing video files.
Returns: None. Results are stored within sub-directories in the input directory named according to the video files.
Example

>>> _ = batch_create_frames(directory='project_folder/videos')

simba.video_processors.video_processing.batch_video_to_greyscale(path, save_dir=None, quality=None, gpu=False)[source]

Convert a directory of video file to greyscale mp4 format.

See also

For GPU CuPY acceleration, see img_stack_to_grayscale_cupy() For GPU numbaCUDA acceleration, see img_stack_to_grayscale_cuda(), For multicore CPU solutions, see img_stack_to_greyscale() or batch_video_to_greyscale() For single-core single video solution, see video_to_greyscale()

Parameters

path (Union[str, os.PathLike]) – Path to directory holding video files in color, or a list of file paths to videos in color.
save_dir (Optional[bool]) – If not None, then the directory where to store converted videos. If None, then stores the new videos in the same directory as the input video with the _grayscale suffix.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. If None, defaults to 23. Default None.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Raises

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

Returns

None.

Note

Codec is automatically selected: libx264 for CPU encoding (ignored if gpu=True).

Example

>>> _ = batch_video_to_greyscale(path='/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/videos/test_2')
>>> batch_video_to_greyscale(path='/Users/simon/Desktop/imgs_4', save_dir='/Users/simon/Desktop/imgs_4/test')

simba.video_processors.video_processing.change_fps_of_multiple_videos(path, fps, quality=23, save_dir=None, gpu=False, verbose=True)[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

path (Union[str, os.PathLike, List[Union[str, os.PathLike]]]) – Path to video file directory, or a list of video file paths.
fps (int) – FPS of the new video files.
quality (int) – Video quality (CRF value). Lower values = higher quality. Range 0-52. Default 23.
save_dir (Optional[Union[str, os.PathLike]]) – If not None, then the directory where to store converted videos. If None, then stores the new videos in the same directory as the input video with the _fps_{fps}.file_extension suffix.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.
verbose (bool) – If True, prints conversion progress. Default True.

Returns

None.

Note

Codec is automatically selected based on file extension: libvpx-vp9 for .webm, mpeg4 for .avi, libx264 for others. GPU accelerates only decode and encode; the fps filter runs on CPU, so GPU may give little or no speedup for FPS conversion compared to CPU.

Example

>>> _ = change_fps_of_multiple_videos(path='project_folder/videos/Video_1.mp4', fps=15)
>>> change_fps_of_multiple_videos(path='/Users/simon/Desktop/imgs', save_dir='/Users/simon/Desktop/imgs_4', fps=15)

simba.video_processors.video_processing.change_img_format(directory, file_type_in, file_type_out, verbose=False)[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_playback_speed(video_path, speed, save_path=None, quality=60, gpu=False, verbose=True, codec=None)[source]

Change the playback speed of a video file. Speed > 1.0 makes the video faster, speed < 1.0 makes it slower.

Note

The output video will have no audio track. The function uses FFmpeg’s setpts filter to adjust playback speed. The video duration will change proportionally to the speed factor (e.g., speed=2.0 halves the duration).

Parameters

video_path (Union[str, os.PathLike]) – Path to the input video file.
speed (float) – Playback speed multiplier. Must be between 0.001 and 100. Values > 1.0 increase speed, values < 1.0 decrease speed.
save_path (Optional[Union[str, os.PathLike]]) – Path where the output video will be saved. If None, saves in the same directory as input with _playback_speed suffix.
quality (int) – Video quality as percentage (1-100). Higher values indicate better quality. Default: 60. Converted to CRF internally.
codec (str) – Video codec to use. Default: ‘libx264’.

Returns

None

Example

>>> change_playback_speed(video_path=r"project_folder/videos/Video_1.mp4", speed=1.5)
>>> change_playback_speed(video_path=r"project_folder/videos/Video_1.mp4", speed=0.5, quality=80)
>>> change_playback_speed(video_path=r"C:/troubleshooting/RAT_NOR/project_folder/videos/03152021_NOB_IOT_8.mp4", speed=2.0, gpu=False)

simba.video_processors.video_processing.change_playback_speed_dir(data_dir, speed, save_dir=None, quality=60, gpu=False, verbose=True, codec=None)[source]

Change the playback speed of all video files in a directory. Speed > 1.0 makes videos faster, speed < 1.0 makes them slower.

Note

The output videos will have no audio track. The function uses FFmpeg’s setpts filter to adjust playback speed. The video duration will change proportionally to the speed factor (e.g., speed=2.0 halves the duration). If save_dir is None, creates a new directory named playback_speed_{speed}x in the input directory.

See also

For processing a single video file, see change_playback_speed().

Parameters

data_dir (Union[str, os.PathLike]) – Path to the directory containing video files to process.
speed (float) – Playback speed multiplier. Must be between 0.000001 and 100. Values > 1.0 increase speed, values < 1.0 decrease speed.
save_dir (Optional[Union[str, os.PathLike]]) – Path where the output videos will be saved. If None, creates a new directory named playback_speed_{speed}x in the input directory.
quality (int) – Video quality as percentage (1-100). Higher values indicate better quality. Default: 60. Converted to CRF internally.
gpu (bool) – If True, use NVIDIA GPU codecs for encoding. Requires NVIDIA GPU and appropriate drivers. Default: False.
verbose (bool) – If True, prints progress messages. Default: True.
codec (str) – Video codec to use. Default: ‘libx264’.

Returns

None

Example

>>> change_playback_speed_dir(data_dir=r'E:/open_video/barnes_maze/test', speed=5)
>>> change_playback_speed_dir(data_dir=r'project_folder/videos', speed=2.0, quality=80, gpu=True)

simba.video_processors.video_processing.change_single_video_fps(file_path, fps, gpu=False, codec=None, save_path=None, quality=23, verbose=True)[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 if save_path is not passed.

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 (Union[int, float]) – FPS of the new video file.
gpu (bool) – If True, use NVIDEA GPU codecs. Default False. GPU accelerates only decode and encode; the fps filter runs on CPU, so GPU may give little or no speedup for FPS conversion.
codec (Optional[str]) – Video codec to use. If None, automatically selects based on file extension (libvpx-vp9 for .webm, mpeg4 for .avi, libx264 for others). Default None.
save_path (Optional[Union[str, os.PathLike]]) – Path where to save the converted video. If None, saves in the same directory as input file with _fps_{fps} suffix. Default None.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. Default 23.
verbose (bool) – If True, prints conversion progress. Default True.

Returns

None

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, clip_limit=2, tile_grid_size=(16, 16), out_path=None, verbose=True)[source]

Convert a single video file to clahe-enhanced greyscale .avi file.

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.
out_path (Optional[Union[str, os.PathLike]]) – 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.

Returns

None.

Example

>>> _ = clahe_enhance_video(file_path: 'project_folder/videos/Video_1.mp4')

simba.video_processors.video_processing.clahe_enhance_video_mp(file_path, clip_limit=2, tile_grid_size=(16, 16), out_path=None, gpu=False, verbose=True, pool=None, core_cnt=- 1)[source]

Convert a single video file to clahe-enhanced greyscale file using multiprocessing.

See also

For single core method, see simba.video_processors.video_processing.clahe_enhance_video().

EXPECTED RUNTIMES
VIDEO FRAME COUNT	TIME (S)	STDEV (S)
1800	16.39103333	0.412235252
3200	18.14536667	0.257643365
7200	21.5071	0.19340044
18000	32.63486667	0.608378783
36000	50.46666667	1.750495454
REPEATS = 3
RESOLUTION: 670 x 530
CORE COUNT: 24

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.
out_path (Optional[Union[str, os.PathLike]]) – 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.
gpu (Union[str, os.PathLike]) – If True, try using GPU for segment concatenation.
core_cnt (int) – Number of cores to use. Pass -1 for all available cores.

Returns

None.

Example

>>> _ = clahe_enhance_video_mp(file_path= 'project_folder/videos/Video_1.mp4')

simba.video_processors.video_processing.clip_video_in_range(file_path, start_time, end_time, out_dir=None, save_path=None, codec=None, quality=60, verbose=True, overwrite=False, include_clip_time_in_filename=False, gpu=False)[source]

Clip video within a specific range.

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.
save_path (Optional[Union[str, os.PathLike]]) – Optional save path for the clipped video. If provided, overrides out_dir and filename generation. Default None.
codec (Optional[str]) – Video codec to use for CPU encoding. If None, automatically selects based on file extension (libvpx-vp9 for .webm, mpeg4 for .avi, libx264 for others). Default None. Ignored if gpu=True.
quality (int) – Video quality percentage (0-100). Higher values = higher quality. Default 60.
verbose (bool) – If True, prints conversion progress. Default True.
overwrite (Optional[bool]) – If True, overwrite output file if path already exists. If False, then raise FileExistError. Default False.
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 _clipped suffix. Default False.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Returns

None. The clip is stored in the same directory as the input video with the _clipped.mp4 suffix if save_path and out_dir are None.

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, frm_ids, save_dir=None, gpu=False, codec=None, quality=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.
gpu (Optional[bool]) – If True, uses FFMpeg GPU acceleration.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. If None, defaults to 23. Default None.

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, codec='divx', save_dir=None, quality=60)[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.

Example

>>> convert_to_avi(path='/Users/simon/Desktop/video_test/Screen Recording 2024-05-06 at 5.34.34 PM_converted.mp4', quality=100, codec='xvid')

simba.video_processors.video_processing.convert_to_bmp(path, save_dir=None, verbose=False)[source]

Convert images in a directory to BMP format.

See also

For JEPG, see convert_to_jpeg(). For PNG, see convert_to_png(). For TIFF, see convert_to_tiff(). For WEBP, see convert_to_webp().

Parameters

path (Union[str, os.PathLike]) – path to directory containing images, or path to a single image file, or a list of paths to image files.
save_dir (Optional[bool]) – If not None, then the directory where to store converted images. If None, then stores the images in a subdirectory within the first passed image directory.
verbose (Optional[bool]) – If True, print conversion progress. Default is False.

Returns

None. New images are saved in save_dir.

Example

>>> convert_to_bmp(path='/Users/simon/Desktop/test_jpg_/landing_40.jpeg', save_dir='/Users/simon/Desktop/test_jpg_/test__')

simba.video_processors.video_processing.convert_to_jpeg(path, quality=95, save_dir=None, verbose=False)[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

See also

For BMP images, see convert_to_bmp(). For PNG, see convert_to_png(). For TIFF, see convert_to_tiff(). For WEBP, see convert_to_webp().

Parameters

directory (Union[str, os.PathLike]) – Path to directory holding image files, a single image file, or a list of paths to image files.
quality (Optional[int]) – The quality of the output images (0-100).
save_dir (Optional[bool]) – If not None, then the directory where to store converted images. If None, then stores the images in a subdirectory within the first passed image directory.
verbose (Optional[bool]) – If True, prints progress. Default False.

Returns

None. New images are saved in save_dir.

Example

>>> convert_to_jpeg(path='/Users/simon/Desktop/imgs', verbose=False, quality=15)
>>> convert_to_jpeg(path='/Users/simon/Desktop/my_image.png', verbose=False, quality=15)
>>> convert_to_jpeg(path=['/Users/simon/Desktop/my_image_1.png', '/Users/simon/Desktop/my_image_2.png'], verbose=True, quality=40)
>>> convert_to_jpeg(path='/Users/simon/Desktop/imgs', save_dir='/Users/simon/Desktop/test_jpg_/test__/HELLO', verbose=False, quality=15)

simba.video_processors.video_processing.convert_to_mov(path, codec='prores', save_dir=None, quality=60)[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, codec='libx265', save_dir=None, quality=60, keep_audio=False)[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]) – If CPU codec, then integer representing the quality: 10, 20, 30.. 100. If GPU codec, then string: ‘Low’, ‘Medium’, ‘High’
keep_audio (Optional[bool]) – If True, keep audio track with AAC codec. If False, remove audio. Default: False.

Returns

None.

Example

>>> convert_to_mp4(path='/Users/simon/Desktop/video_test', quality="60", codec='vp9')

simba.video_processors.video_processing.convert_to_png(path, save_dir=None, verbose=False)[source]

Convert images to PNG format.

See also

For BMP images, see convert_to_bmp(). For JEPG, see convert_to_jpeg(). For TIFF, see convert_to_tiff(). For WEBP, see convert_to_webp().

Parameters

path (Union[str, os.PathLike]) – path to directory containing images, or path to a single image file, or a list of paths to image files.
save_dir (Optional[bool]) – If not None, then the directory where to store converted images. If None, then stores the images in a subdirectory within the first passed image directory.
verbose (Optional[bool]) – If True, print conversion progress. Default is False.

Returns

None. New images are saved in save_dir.

Example

>>> convert_to_png(path=['/Users/simon/Desktop/test_jpg_/test__/landing_40.bmp', '/Users/simon/Desktop/test_jpg_/landing_30.jpeg'], save_dir='/Users/simon/Desktop/test_jpg_/test__/HELLO_3')

simba.video_processors.video_processing.convert_to_tiff(directory, stack=False, compression='raw', verbose=False)[source]

Convert images in a directory to TIFF format.

See also

For BMP images, see convert_to_bmp(). For JEPG, see convert_to_jpeg(). For PNG, see convert_to_png(). For WEBP, see convert_to_webp().

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. New images are saved in save_dir.

Example

>>> convert_to_tiff('/Users/simon/Desktop/imgs', stack=True, compression='tiff_lzw')

simba.video_processors.video_processing.convert_to_webm(path, codec='vp9', save_dir=None, quality=60)[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.

Example

>>> convert_to_webm(path='/Users/simon/Desktop/video_test/Screen Recording 2024-05-06 at 5.34.34 PM_converted.mp4', quality=100, codec='vp8')

simba.video_processors.video_processing.convert_to_webp(path, quality=95, save_dir=None, verbose=True)[source]

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

See also

For BMP images, see convert_to_bmp(). For JEPG, see convert_to_jpeg(). For PNG, see convert_to_png(). For TIFF, see convert_to_tiff().

Parameters

path (Union[str, os.PathLike]) – Path to directory holding image files
quality (Optional[int]) – The quality of the output images (0-100).
save_dir (Optional[bool]) – If not None, then the directory where to store converted images. If None, then stores the images in a subdirectory within the first passed image directory.
verbose (Optional[bool]) – If True, prints progress. Default False.

Returns

None. New images are saved in save_dir.

Example

>>> convert_to_webp('/Users/simon/Desktop/imgs', quality=80)
>>> convert_to_webp(path=['/Users/simon/Desktop/test_jpg_/test__/landing_40.bmp', '/Users/simon/Desktop/test_jpg_/landing_30.jpeg'], save_dir='/Users/simon/Desktop/test_jpg_/test__/HELLO_4')

simba.video_processors.video_processing.convert_video_powerpoint_compatible_format(file_path, gpu=False)[source]

Create MS PowerPoint compatible copy of a video file.

Parameters

file_path (Union[str, os.PathLike]) – Path to video file.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Returns

None. The result is stored in the same directory as the input file with the _powerpointready suffix.

Note

Codec is automatically selected: libx264 for CPU encoding (ignored if gpu=True).

Example

>>> _ = convert_video_powerpoint_compatible_format(file_path='project_folder/videos/Video_1.mp4')

simba.video_processors.video_processing.copy_img_folder(config_path, source)[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_average_frm(video_path, start_frm=None, end_frm=None, start_time=None, end_time=None, save_path=None, verbose=False)[source]

Create an image representing the average frame of a segment in a video or an entire video.

See also

See simba.data_processors.cuda.image.create_average_frm_cupy(), simba.data_processors.cuda.image.create_average_frm_cuda() for GPU acceleration. This one appears quicker than the GPU implementations…

EXPECTED RUNTIMES
OBSERVATIONS (THOUSANDS)	TIME (S)	STDEV (S)
1.8	1.205733333	0.041036732
3.6	2.376	0.12985592
5.4	3.556166667	0.131753267
7.2	4.624466667	0.116711196
9	6.3948	0.798469906
18	12.24	0.781892576
27	19.2576	0.257472387
36	23.74796667	0.237322151
REPEATS = 3
RESOLUTION: 670 x 530

Note

Useful helper for e.g., video background subtraction simba.video_processors.video_processing.video_bg_substraction() Either pass start_frm and end_frm OR start_time and end_time OR pass all four arguments as None. If all are None, then the entire video will be used to create the average frame.

Parameters

video_path (Union[str, os.PathLike]) – The path to the video to create the average frame from. Default: None.
start_frm (Optional[int]) – The first frame in the segment to create the average frame from. Default: None.
end_frm (Optional[int]) – The last frame in the segment to create the average frame from. Default: None.
start_time (Optional[str]) – The start timestamp in HH:MM:SS format in the segment to create the average frame from. Default: None.
end_time (Optional[str]) – The end timestamp in HH:MM:SS format in the segment to create the average frame from. Default: None.
save_path (Optional[Union[str, os.PathLike]]) – The path to where to save the average image. If None, then returns the average image in np,ndarray format. Default: None.

Return Union[None, np.ndarray]

The average image (if save_path is not None) or None if save_path is passed.

simba.video_processors.video_processing.create_blank_video(path, length, width, height, color='black', gpu=False, verbose=False)[source]

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

Note

Useful for when creating image mosaics with un-even number of videos and need a “fill” video in e.g. black color.

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, output_path, gpu=False, codec=None, quality=60)[source]

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

Note

Calls the ROISelector() interface.

Parameters

directory_path (Union[str, os.PathLike]) – Directory containing input videos.
output_path (Union[str, os.PathLike]) – Directory where to save the cropped videos.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.
codec (Optional[str]) – Video codec to use for CPU encoding. If None, automatically selects based on file extension (libvpx-vp9 for .webm, mpeg4 for .avi, libx264 for others). Default None. Ignored if gpu=True.
quality (int) – Video quality percentage (1-100). Higher values = higher quality. Default 60.

Returns

None. Results are stored in passed output_path.

Example

>>> _ = crop_multiple_videos(directory_path='project_folder/videos', output_path='project_folder/videos/my_new_folder')
>>> _ = crop_multiple_videos(directory_path=r'C:/troubleshooting/mitra/test', output_path=r'C:/troubleshooting/mitra/test/cropped', gpu=True)

simba.video_processors.video_processing.crop_multiple_videos_circles(in_dir, out_dir)[source]

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

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, out_dir)[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, gpu=False, quality=60)[source]

Crop a single video using ROISelector() interface.

Results is saved in the same directory as input video with the _cropped.mp4 suffix.

See also

To crop multiple videos, see crop_multiple_videos()

Parameters

file_path (Union[str, os.PathLike]) – Path to video file.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.
quality (int) – Video quality percentage (1-100). Higher values = higher quality. Default 60.

Returns

None. Results is saved in the same directory as input video with the _cropped.mp4 suffix.

Example

>>> _ = crop_single_video(file_path='project_folder/videos/Video_1.mp4')

simba.video_processors.video_processing.crop_single_video_circle(file_path)[source]

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

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)[source]

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

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.

Parameters: file_path (Union[str, os.PathLike]) – The path to 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.crop_video(video_path, save_path, size, top_left, gpu=False, codec='libx264', verbose=True, quality=60)[source]

Crops a video from the given file at video_path and saves the result to save_path. Optionally uses GPU acceleration for faster processing, falling back to CPU if GPU fails.

Parameters

video_path (Union[str, os.PathLike]) – The path to the input video file to crop. Can be a string or path-like object.
save_path (Union[str, os.PathLike]) – The path to save the cropped video file. Can be a string or path-like object.
size (Tuple[int, int]) – A tuple (width, height) specifying the size of the output cropped video.
top_left (Tuple[int, int]) – A tuple (x, y) specifying the top-left corner of the cropping area.
gpu (bool) – If True, attempts to use GPU acceleration for the video cropping. Defaults to False.
codec (str) – The codec used for encoding the output video. Defaults to the SimBA batch codec.
verbose (bool) – If True, prints progress messages and the elapsed time. Defaults to True.
quality (int) – The quality of the output video, on a scale from 1 to 100. Defaults to 60 (balances encoding time vs file size).

Returns

None. The result is saved at save_path. If verbose is True, prints the elapsed time and success message.

simba.video_processors.video_processing.crossfade_two_videos(video_path_1, video_path_2, crossfade_duration=2, crossfade_method='fade', crossfade_offset=2, quality=60, out_format='mp4', save_path=None, gpu=False)[source]

Cross-fade two videos.

Note

See simba.utils.lookups.get_ffmpeg_crossfade_methods for named crossfade methods. See https://trac.ffmpeg.org/wiki/Xfade. for visualizations of named crossfade methods,

Parameters

video_path_1 (Union[str, os.PathLike]) – Path to the first video on disk.
video_path_2 (Union[str, os.PathLike]) – Path to the second video on disk.
crossfade_duration (Optional[int]) – The duration of the crossfade.
crossfade_method (Optional[str]) – The crossfade method. For accepted methods, see simba.utils.lookups.get_ffmpeg_crossfade_methods.
crossfade_offset (Optional[int]) – The time in seconds into the first video before the crossfade duration begins.
save_path (Optional[Union[str, os.PathLike]]) – The location where to save the crossfaded video. If None, then saves the video in the same directory as video_path_1 with _crossfade suffix.
gpu (Optional[bool]) – If True, uses GPU codecs with potentially faster runtimes. Default: False.

Returns

None.

Example

>>> crossfade_two_videos(video_path_1='/Users/simon/Desktop/envs/simba/troubleshooting/reptile/1.mp4', video_path_2='/Users/simon/Desktop/envs/simba/troubleshooting/reptile/1.mp4', crossfade_duration=5, crossfade_method='zoomin', save_path='/Users/simon/Desktop/cross_test.mp4')

simba.video_processors.video_processing.downsample_video(file_path, video_height, video_width, gpu=False, codec=None, quality=23, save_path=None, verbose=True)[source]

Down-sample a video file.

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 (bool) – If True, use NVIDEA GPU codecs. Default False.
codec (str) – Video codec to use for CPU encoding. Default ‘libx264’. Ignored if gpu=True.
quality (int) – Video quality (CRF value). Lower values = higher quality. Range 0-52. Default 23.
save_path (Optional[Union[str, os.PathLike]]) – Optional save path for the downsampled video. If None, saves in the same directory as input file with _downsampled.mp4 suffix. Default None.
verbose (bool) – If True, prints conversion progress. Default True.

Returns

None. The result is stored in the same directory as the input file with the _downsampled.mp4 suffix if save_path is None.

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, start_frame, end_frame, save_dir=None, img_format='png', verbose=True, greyscale=False, clahe=False, include_fn=False)[source]

Extract a user-defined range of frames from a video file and save them as individual image files.

Note

Frames are saved with sequential numbering matching the original frame numbers. If no save directory is specified, frames are saved in a subdirectory with the suffix _frames within the same directory as the video file.

Parameters

file_path (Union[str, os.PathLike]) – Path to the video file to extract frames from.
start_frame (int) – First frame in range to extract (0-indexed).
end_frame (int) – Last frame in range to extract (inclusive).
save_dir (Optional[Union[str, os.PathLike]]) – Optional directory where extracted frames will be saved. If None, saves in a subdirectory with suffix _frames in the same directory as the video file.
img_format (Literal['png', 'webp', 'jpeg']) – Format of the output images. One of: ‘png’, ‘webp’, ‘jpeg’. Default: ‘png’.
verbose (Optional[bool]) – If True, prints progress messages during extraction. Default: True.
greyscale (Optional[bool]) – If True, converts frames to greyscale. Default: False.
clahe (Optional[bool]) – If True, applies Contrast Limited Adaptive Histogram Equalization to each frame. Default: False.
include_fn (Optional[bool]) – If True, includes video name in frame filenames. Default: False.

Returns

None. Frames are saved to disk in the specified directory.

Example

>>> _ = extract_frame_range(file_path='project_folder/videos/Video_1.mp4',
...                        start_frame=100,
...                        end_frame=500,
...                        img_format='webp',
...                        verbose=True)

simba.video_processors.video_processing.extract_frames_from_all_videos_in_directory(config_path, directory, confirm_popup=False)[source]

Extract all frames from all videos in a directory.

Parameters

config_path (Union[str, os.PathLike]) – Path to SimBA project config file in Configparser format.
directory (Union[str, os.PathLike]) – Path to file or folder containing videos (e.g. mp4, avi).
confirm_popup (bool) – If True, show a confirmation dialog before extracting. If the user chooses NO, no frames are extracted. Default: False.

Returns

None. Frames are saved in project_folder/frames/input of the SimBA project.

Example

>>> extract_frames_from_all_videos_in_directory(config_path='project_folder/project_config.ini', directory='/tests/test_data/video_tests')
>>> extract_frames_from_all_videos_in_directory(config_path=config_path, directory=video_dir, confirm_popup=True)

simba.video_processors.video_processing.extract_frames_single_video(file_path, save_dir)[source]

Extract all frames for a single video.

Note

Image frames are saved as PNG files named with integers in order of appearance, i.e., 0.png, 1.png ...

Parameters

file_path (Union[str, os.PathLike]) – Path to video file.
save_dir (Optional[Union[str, os.PathLike]]) – Optional directory where to save the frames. If save_dir is not passed, results are stored within a subdirectory in the same directory as the input file.

Returns

None

Example

>>> _ = extract_frames_single_video(file_path='project_folder/videos/Video_1.mp4')
>>> extract_frames_single_video(file_path='/Users/simon/Desktop/imgs_4/test.mp4', save_dir='/Users/simon/Desktop/imgs_4/frames')

simba.video_processors.video_processing.flip_videos(video_path, horizontal_flip=False, vertical_flip=False, quality=60, save_dir=None, gpu=False)[source]

Flip a video or directory of videos horizontally, vertically, or both, and save them to the specified directory.

Parameters

video_path (Union[str, os.PathLike]) – Path to the input video file or directory containing video files.
horizontal_flip (Optional[bool]) – If True, flip the video(s) horizontally (default is False).
vertical_flip (Optional[bool]) – If True, flip the video(s) vertically (default is False).
quality (Optional[int]) – Quality of the output video, an integer between 1 and 100 (default is 60).
save_dir (Optional[Union[str, os.PathLike]]) – Directory to save the flipped video(s). If None, the directory of the input video(s) will be used.
gpu (Optional[bool]) – If True, attempt to use GPU acceleration for rotation (default is False).

Returns

None.

simba.video_processors.video_processing.frames_to_movie(directory, fps, quality=60, out_format='mp4', gpu=False)[source]

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

Image files must be numerically named (e.g., 1.png, 2.png, …).

Parameters

directory – Directory containing the images.
fps – Frame rate of the output video.
quality – Integer (1–100) representing output video quality. Higher = better quality + bigger size.
out_format – Format of the output video. One of: ‘mp4’, ‘avi’, ‘webm’. Default is ‘mp4’.
gpu – If True, use NVIDIA GPU codecs (if available). Default is False.

Returns

None. Video is saved to disk.

Note

Codec is automatically selected based on out_format: libvpx-vp9 for ‘webm’, mpeg4 for ‘avi’, libx264 for ‘mp4’ (ignored if gpu=True).

simba.video_processors.video_processing.get_img_slic(img, n_segments=50, compactness=50, sigma=1)[source]

Simplify an image into superpixels using SLIC (Simple Linear Iterative Clustering).

Parameters

img (np.ndarray) – Image to segment.
n_segments – Number of segments to produce.
compactness – How compact (“square”) the output segments are.
sigma (np.ndarray) – Amount of Gaussian smoothing.

Returns

Smoothened version of the input image.

Return type

np.ndarray

Example

>>> img = read_frm_of_video(video_path=r"C:/troubleshooting/mitra/project_folder/videos/FRR_gq_Saline_0626.mp4", frame_index=0)
>>> sliced_img = get_img_slic(img=img)

simba.video_processors.video_processing.get_video_slic(video_path, save_path, n_segments=50, compactness=50, sigma=1, core_cnt=- 1)[source]

Apply SLIC superpixel segmentation to all frames of a video and save the output as a new video.

See also

To convert single image, see simba.video_processors.video_processing.get_img_slic()

param Union[str, os.PathLike] video_path

Path to the input video file.

param Union[str, os.PathLike] save_path

Path to save the processed video with SLIC superpixel segmentation.

param Optional[int] n_segments

Approximate number of superpixels for each frame. Defaults to 50.

param Optional[int] compactness

Balance of color and spatial proximity. Higher values result in more uniformly shaped superpixels. Defaults to 50.

param Optional[int] sigma

Standard deviation for Gaussian smoothing applied to each frame before segmentation. Defaults to 1.

param Optional[int] core_cnt

Number of CPU cores to use for parallel processing. Set to -1 to use all available cores. Defaults to -1.

return

None. The segmented video is saved to save_path.

example
>>> #video_path = r"C:      roubleshooting\mitra\project_folder

ideosFRR_gq_Saline_0626.mp4”

simba.video_processors.video_processing.gif_creator(file_path, start_time, duration, width=None, quality=100, save_path=None, fps=15, gpu=False)[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 extension if save_path is passed as None.

Note

The height is auto-computed to retain aspect ratio.

See also

GIFs are typically for online use but can be costly in terms of time to create and file size. For smaller files, consider webm format which are for online publication and simba.video_processors.video_processing.convert_to_webm.

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. If None, then retains the width and height of the input video.
save_path (Optional[Union[str, os.PathLike]]) – Optional save location for the gif. If None, then the new video is saved in the same directory.
fps (int) – FPS of the gif. Defaults to 15.
quality (int) – Quality of the GIF on scale 1-100. Smaller values gives smaller GIFs by filesize with worse quality. Default: 100.
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)
>>> gif_creator(file_path=r'/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/videos/SI_DAY3_308_CD1_PRESENT.mp4', start_time=5, duration=15, width=600, gpu=False, save_path='/Users/simon/Desktop/imgs_4/Test.gif')

simba.video_processors.video_processing.horizontal_video_concatenator(video_paths, save_path, height_px=None, height_idx=None, gpu=False, quality=23, verbose=True)[source]

Concatenates multiple videos horizontally.

Note

Set the height of each video in the moseic by passing EITHER height_px or height_idx.

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.
quality (int) – Video quality (CRF value). Lower values = higher quality. Range 0-52. Default 23.
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.is_video_seekable(data_path, gpu=False, batch_size=None, verbose=False, raise_error=True, save_path=None)[source]

Determines if the given video file(s) are seekable and can be processed frame-by-frame without issues.

This function checks if all frames in the specified video(s) can be read sequentially. It can process videos using either CPU or GPU, with optional batch processing to handle memory limitations. If unreadable frames are detected, the function can either raise an error or return a result indicating the issue.

Parameters

data_path (Union[str, os.PathLike]) – Path to the video file or a path to a directory containing video files.
gpu (bool) – If True, then use GPU. Else, CPU.
batch_size (Optional[int]) – Optional int representing the number of frames in each video to process sequentially. If None, all frames in a video is processed at once. Use a smaller value to avoid MemoryErrors. Default None.
verbose (bool) – If True, prints progress. Default None.
raise_error (bool) – If True, raises error if not all passed videos are seeakable.

Example

>>> _ = is_video_seekable(data_path='/Users/simon/Desktop/unseekable/20200730_AB_7dpf_850nm_0003_fps_5.mp4', batch_size=400)

simba.video_processors.video_processing.mixed_mosaic_concatenator(video_paths, save_path, gpu=False, quality=23, verbose=True, uneven_fill_color='black')[source]

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

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).
quality (int) – Video quality (CRF value). Lower values = higher quality. Range 0-52. Default 23.
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, save_path, width_idx=None, width_px=None, height_idx=None, height_px=None, gpu=False, quality=23, verbose=True, uneven_fill_color='black')[source]

Concatenates multiple videos into a mosaic layout.

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).
quality (int) – Video quality (CRF value). Lower values = higher quality. Range 0-52. Default 23.
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, start_times, end_times, out_dir=None, quality=None, codec=None, include_clip_time_in_filename=False, gpu=False)[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.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. If None, defaults to 23. Default None.
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.
codec (Optional[str]) – Video codec to use for CPU encoding. If None, automatically selects based on file extension (libvpx-vp9 for .webm, mpeg4 for .avi, libx264 for others). Default None. Ignored if gpu=True.

Returns

None.

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.reencode_mp4_video(file_path, codec, quality)[source]

Re-encode an MP4 video file in-place with a new codec and quality setting.

This function re-encodes the video track of an MP4 file using FFmpeg while preserving the audio track unchanged. The original file is replaced with the re-encoded version. A temporary file is used during encoding to ensure the original is only replaced if encoding succeeds.

Note

The function modifies the file in-place. The original file will be replaced with the re-encoded version upon successful completion. The audio track is copied as-is without re-encoding (-c:a copy). FFmpeg must be installed and available in the system PATH.

Parameters

file_path (Union[str, os.PathLike]) – Path to the MP4 video file to re-encode.
codec (str) – Video codec to use for encoding (e.g., ‘libx264’, ‘libx265’, ‘h264_nvenc’).
quality (int) – CRF (Constant Rate Factor) value for quality control. Lower values indicate higher quality. Typical range: 18-28 (18 = high quality, 28 = lower quality/file size).

Returns

None. The original file is replaced with the re-encoded version.

Example

>>> reencode_mp4_video(file_path=r'project_folder/videos/Video_1.mp4', codec='libx264', quality=23)
>>> reencode_mp4_video(file_path=r'C:/videos/my_video.mp4', codec='libx265', quality=20)

simba.video_processors.video_processing.remove_beginning_of_video(file_path, time, quality=60, save_path=None, gpu=False)[source]

Remove N seconds from the beginning of a video file.

See also

To remove N seconds from the end of the video, see simba.video_processors.video_processing.remove_end_of_video().

Parameters

file_path (Union[str, os.PathLike]) – Path to video file
time (int) – Number of seconds to remove from the beginning of the video.
quality (int) – Video quality percentage (1-100). Higher values = higher quality. Default 60.
save_path (Optional[Union[str, os.PathLike]]) – Optional save location for the shortened video. If None, then the new video is saved in the same directory as the input video with the _shortened suffix.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Returns

None. If save_path is not passed, the result is stored in the same directory as the input file with the _shorten.mp4 suffix.

Note

Codec is automatically selected: libx264 for CPU encoding (ignored if gpu=True).

Example

>>> _ = remove_beginning_of_video(file_path='project_folder/videos/Video_1.avi', time=10)
>>> remove_beginning_of_video(file_path=f'/Users/simon/Desktop/imgs_4/test/blahhhh.mp4', save_path='/Users/simon/Desktop/imgs_4/test/CUT.mp4', time=3)

simba.video_processors.video_processing.remove_end_of_video(file_path, time, quality=60, save_path=None, gpu=False)[source]

Remove N seconds from the end of a video file.

See also

To remove N seconds from the beginning of the video, see simba.video_processors.video_processing.remove_beginning_of_video()

Parameters

file_path (Union[str, os.PathLike]) – Path to video file
time (int) – Number of seconds to remove from the end of the video.
quality (int) – Video quality percentage (1-100). Higher values = higher quality. Default 60.
save_path (Optional[Union[str, os.PathLike]]) – Optional save location for the shortened video. If None, then the new video is saved in the same directory as the input video with the _shortened suffix.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Returns

None. If save_path is not passed, the result is stored in the same directory as the input file with the _shorten.mp4 suffix.

Note

Codec is automatically selected: libx264 for CPU encoding (ignored if gpu=True).

Example

>>> _ = remove_end_of_video(file_path='project_folder/videos/Video_1.avi', time=10)
>>> remove_end_of_video(file_path=f'/Users/simon/Desktop/imgs_4/test/blahhhh.mp4', save_path='/Users/simon/Desktop/imgs_4/test/CUT.mp4', time=3)

simba.video_processors.video_processing.resize_videos_by_height(video_paths, height, overwrite=False, save_dir=None, gpu=False, quality=None, suffix=None, codec=None, verbose=True)[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.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. If None, defaults to 23. Default None.
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, width, overwrite=False, save_dir=None, gpu=False, codec=None, quality=None, suffix=None, verbose=True)[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.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. If None, defaults to 23. Default None.
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')
>>> video_paths= [r"D:/videos/4A_Mouse_5-choice_MustTouchTrainingNEWFINAL_a8_grayscale.mp4"]
>>> resize_videos_by_width(video_paths=video_paths, width=301, overwrite=False, save_dir=r"D:/videos/test", gpu=True)

simba.video_processors.video_processing.reverse_videos(path, save_dir=None, codec=None, quality=60, gpu=False)[source]

Reverses one or more video files located at the specified path and saves the reversed videos in the specified directory.

Parameters

path (Union[str, os.PathLike]) – Path to the video file or directory containing video files to be reversed.
save_dir (Optional[Union[str, os.PathLike]]) – Directory to save the reversed videos. If not provided, reversed videos will be saved in a subdirectory named ‘reversed_<timestamp>’ in the same directory as the input file(s).
quality (Optional[int]) – Output video quality expressed as a percentage. Default is 60. Values range from 1 (low quality, high compression) to 100 (high quality, low compression).
gpu (Optional[bool]) – If True, uses GPU codecs with potentially faster runtimes. Default: False.

Returns

None

Example

>>> reverse_videos(path='/Users/simon/Desktop/envs/simba/troubleshooting/open_field_below/project_folder/videos/reverse/TheVideoName_video_name_2_frame_no.mp4')

simba.video_processors.video_processing.roi_blurbox(video_path, blur_level=0.02, invert=False, save_path=None)[source]

Blurs either the selected or unselected portion of a user-specified region-of-interest according to the passed blur level. Higher blur levels produces more opaque regions.

Parameters

video_path (Union[str, os.PathLike]) – The path to the video on disk
blur_level (Optional[float]) – The level of the blur as a ratio 0-1.0.
invert (Optional[bool]) – If True, blurs the unselected region. If False, blurs the selected region.
save_path (Optional[Union[str, os.PathLike]]) – The location where to save the blurred video. If None, then saves the blurred video in the same directory as the input video with the _blurred suffix.

Returns

None

Example

>>> roi_blurbox(video_path='/Users/simon/Downloads/1_LH_clipped_downsampled.mp4', blur_level=0.2, invert=True)

simba.video_processors.video_processing.rotate_video(video_path, degrees, gpu=False, quality=60, fill_color='black', save_dir=None)[source]

Rotate a video or a directory of videos by a specified number of degrees.

Parameters

video_path (Union[str, os.PathLike]) – Path to the input video file or directory containing video files.
degrees (int) – Number of degrees (between 1 and 359, inclusive) to rotate the video clockwise.
gpu (Optional[bool]) – If True, attempt to use GPU acceleration for rotation (default is False).
quality (Optional[int]) – Quality of the output video, an integer between 1 and 100 (default is 60).
save_dir (Optional[Union[str, os.PathLike]]) – Directory to save the rotated video(s). If None, the directory of the input video(s) will be used with the rotated suiffix.

Returns

None.

Example

>>> rotate_video(video_path='/Users/simon/Desktop/envs/simba/troubleshooting/reptile/rot_test.mp4', degrees=180)
>>> rotate_video(video_path=r"C:/troubleshooting/mitra/project_folder/videos/clipped/501_MA142_Gi_CNO_0514_clipped.mp4", degrees=65)
>>> rotate_video(video_path=r"C:/troubleshooting/mitra/project_folder/videos/clipped/501_MA142_Gi_CNO_0514_clipped.mp4", degrees=10, fill_color='deeppink', gpu=True)

simba.video_processors.video_processing.split_mosaic(video_path, tile_size, save_dir, verbose=True)[source]

Helper to split a mosaic video into its constituent parts.

Parameters

video_path (Union[str, os.PathLike]) – The path to the input video file to crop. Can be a string or path-like object.
tile_size (Tuple[int, int]) – A tuple (tile_width, tile_height) indicating the size of each tile in pixels. The width and height must evenly divide the dimensions of the video.
save_dir (Union[str, os.PathLike]) – Directory to save the output tile videos. Will be created if it does not exist.
verbose (bool) – If True, prints progress information and status messages during processing.

Example

>>> split_mosaic(video_path=r"3.mp4", tile_size=(1280, 720), save_dir=r"3_cropped")

simba.video_processors.video_processing.superimpose_elapsed_time(video_path, font='Arial', font_size=30, font_color='white', font_border_color='black', time_format='HH:MM:SS.MMMM', font_border_width=2, quality=None, position='top_left', save_dir=None, gpu=False)[source]

Superimposes elapsed time on the given video file(s) and saves the modified video(s).

Parameters

video_path (Union[str, os.PathLike]) – Path to the input video file or directory containing video files.
font_size (Optional[int]) – Font size for the elapsed time text. Default 30.
font_color (Optional[str]) – Font color for the elapsed time text. Default white
font_border_color (Optional[str]) – Font border color for the elapsed time text. Default black.
font_border_width (Optional[int]) – Font border width for the elapsed time text in pixels. Default 2.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. If None, defaults to 23. Default None.
position (Optional[Literal['top_left', 'top_right', 'bottom_left', 'bottom_right', 'middle_top', 'middle_bottom']]) – Position where the elapsed time text will be superimposed. Default top_left.
save_dir (Optional[Union[str, os.PathLike]]) – Directory where the modified video(s) will be saved. If not provided, the directory of the input video(s) will be used.
gpu (Optional[bool]) – If True, uses GPU codecs with potentially faster runtimes. Default: False.

Returns

None

Example

>>> superimpose_elapsed_time(video_path='/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/videos/test_4/1.mp4', position='middle_top', font_color='black', font_border_color='pink', font_border_width=5, font_size=30)

simba.video_processors.video_processing.superimpose_frame_count(file_path, gpu=False, recursive=False, font='Arial', font_color='black', bg_color='white', codec=None, quality=None, verbose=True, save_path=None, loc='bottom_middle', fontsize=20)[source]

Superimpose frame count on a video file.

Parameters

file_path (Union[str, os.PathLike]) – Path to video file or directory containing video files.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.
recursive (Optional[bool]) – If True, processes all video files in file_path directory found recursively. If False, then grabs just the video in the parent.
font (Optional[str]) – The font to use for the frame number. Default ‘Arial’.
font_color (Optional[str]) – The color of frame number text. Default ‘black’.
bg_color (Optional[str]) – The color of the box which the frame number is printed in. Default ‘white’.
codec (Optional[str]) – Video codec to use for CPU encoding. Default ‘libx264’. Ignored if gpu=True.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. If None, defaults to 23. Default None.
verbose (bool) – If True, prints conversion progress. Default True.
save_path (Optional[Union[str, os.PathLike]]) – Optional save path or save directory for the video with frame numbers. If None, then the new video is saved in the same directory as the input video with the _frame_no suffix.
loc (Optional[Literal['top_left', 'top_middle', 'top_right', 'bottom_left', 'bottom_middle', 'bottom_right']]) – The location of the font number text. Options: ‘top_left’, ‘top_middle’, ‘top_right’, ‘bottom_left’, ‘bottom_middle’, ‘bottom_right’. Default ‘bottom_middle’.
fontsize (Optional[int]) – The size of the font representing the current frame. Default 20.

Returns

None. The result is stored in the same directory as the input file with the _frame_no.mp4 suffix if save_path is None.

Example

>>> _ = superimpose_frame_count(file_path='/Users/simon/Downloads/1_LH_0_3.mp4', fontsize=90)
>>> superimpose_frame_count(file_path='/Users/simon/Desktop/imgs_4/test/Screen Recording 2024-02-26 at 4.43.26 PM_frame_no.mp4', save_path='/Users/simon/Desktop/imgs_4/test/blahhhh.mp4', fontsize=90)

simba.video_processors.video_processing.superimpose_freetext(video_path, text, font='Arial', font_size=30, font_color='white', font_border_color='black', font_border_width=2, quality=None, position='top_left', save_dir=None, gpu=False)[source]

Superimposes passed text on the given video file(s) and saves the modified video(s).

Parameters

video_path (Union[str, os.PathLike]) – Path to the input video file or directory containing video files.
text (str) – The text to overlay on the video. Characters that break the ffmpeg drawtext filter (: ' " \ % , ; =) are stripped or replaced before rendering. Raises if no legal characters remain.
font_size (Optional[int]) – Font size for the text. Default 30.
font_color (Optional[str]) – Font color for text. Default white
font_border_color (Optional[str]) – Font border color for the text. Default black.
font_border_width (Optional[int]) – Font border width for the text in pixels. Default 2.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. If None, defaults to 23. Default None.
position (Optional[Literal['top_left', 'top_right', 'bottom_left', 'bottom_right', 'top_middle', 'bottom_middle']]) – Position where the text will be superimposed. Default top_left.
save_dir (Optional[Union[str, os.PathLike]]) – Directory where the modified video(s) will be saved. If not provided, the directory of the input video(s) will be used.
gpu (Optional[bool]) – If True, uses GPU codecs with potentially faster runtimes. Default: False.

Returns

None

simba.video_processors.video_processing.superimpose_overlay_video(video_path, overlay_video_path, position='top_left', opacity=0.5, scale=0.05, save_dir=None, gpu=False)[source]

Inset a video overlay on a second video with specified size, opacity, and location.

Parameters

video_path (Union[str, os.PathLike]) – The path to the video file.
overlay_video_path (Union[str, os.PathLike]) – The path to video to be inserted into the video_path video.
position (Optional[str]) – The position of the inset overlay video. Options: ‘top_left’, ‘bottom_right’, ‘top_right’, ‘bottom_left’, ‘center’
opacity (Optional[float]) – The opacity of the inset overlay video as a value between 0-1.0. 1.0 meaning the same as input image. Default: 0.5.
scale (Optional[float]) – The scale of the inset overlay video as a ratio os the image size. Default: 0.05.
save_dir (Optional[Union[str, os.PathLike]]) – The location where to save the output video. If None, then saves the video in the same directory as the first video.
gpu (Optional[bool]) – If True, uses GPU codecs with potentially faster runtimes. Default: False.

Returns

None

Example

>>> superimpose_overlay_video(video_path='/Users/simon/Desktop/envs/simba/troubleshooting/multi_animal_dlc_two_c57/project_folder/videos/watermark/Together_1_powerpointready.mp4', overlay_video_path='/Users/simon/Desktop/splash.png', position='top_left', opacity=1.0, scale=0.2)

simba.video_processors.video_processing.superimpose_video_names(video_path, font='Arial', font_size=30, font_color='white', font_border_color='black', font_border_width=2, quality=None, position='top_left', save_dir=None, gpu=False)[source]

Superimposes the video name on the given video file(s) and saves the modified video(s).

Parameters

video_path (Union[str, os.PathLike]) – Path to the input video file or directory containing video files.
font_size (Optional[int]) – Font size for the video name text. Default 30.
font_color (Optional[str]) – Font color for the video name text. Default white
font_border_color (Optional[str]) – Font border color for the video name text. Default black.
font_border_width (Optional[int]) – Font border width for the video name text in pixels. Default 2.
quality (Optional[int]) – Video quality (CRF value). Lower values = higher quality. Range 0-52. If None, defaults to 23. Default None.
position (Optional[Literal['top_left', 'top_right', 'bottom_left', 'bottom_right', 'top_middle', 'bottom_middle']]) – Position where the video name will be superimposed. Default top_left.
save_dir (Optional[Union[str, os.PathLike]]) – Directory where the modified video(s) will be saved. If not provided, the directory of the input video(s) will be used.
gpu (Optional[bool]) – If True, uses GPU codecs with potentially faster runtimes. Default: False.

Returns

None

Example

>>> superimpose_video_names(video_path='/Users/simon/Desktop/envs/simba/troubleshooting/mouse_open_field/project_folder/videos/test_4/1.mp4', position='middle_top', font_color='black', font_border_color='pink', font_border_width=5, font_size=30)

simba.video_processors.video_processing.superimpose_video_progressbar(video_path, bar_height=10, color='red', codec=None, position='bottom', save_dir=None, gpu=False)[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.
position (Optional[str]) – The position of the progressbar. Options: ‘top’, ‘bottom’.
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.
gpu (Optional[bool]) – If True, uses GPU codecs with potentially faster runtimes. Default: False.

Returns

None.

Example

>>> superimpose_video_progressbar(video_path='/home/plateabiosciences/Downloads/031723/3A_Mouse_5-choice_MouseTouchBasic_s9_a6.mp4', gpu=False)

simba.video_processors.video_processing.temporal_concatenation(video_paths, save_path=None, save_format='mp4', quality=60, gpu=False)[source]

Concatenates multiple video files temporally into a single video.

Parameters

video_paths (List[Union[str, os.PathLike]]) – List of paths to video files to be temporally joined. The videos will be joined in the order appearance in the list.
save_path (Optional[Union[str, os.PathLike]]) – The location where to save the temporally concatenated videos. If None, then the video is saved in the same directory as the first video in video_paths with the name temporal_concat_video.
save_format (Optional[Literal['mp4', 'mov', 'avi', 'webm']]) – The video format of the concatenated video. Default: mp4.
quality (Optional[int]) – Integer representing the quality: 10, 20, 30.. 100.
gpu (Optional[bool]) – If True, attempt to use GPU acceleration for rotation (default is False).

Returns

None

simba.video_processors.video_processing.upsample_fps(video_path, fps, quality=60, save_dir=None)[source]

Upsample the frame rate of a video or all videos in a directory to a specified fps with a given quality.

Note

Uses ffmpeg minterpolate

Warning

Long run-times for higher resolution videos.

Parameters

video_path (Union[str, os.PathLike]) – The path to the input video file or directory containing video files.
fps (int) – The target frame rate to upsample the video(s) to.
quality (Optional[int]) – The quality level of the output video(s), represented as a percentage (1-100). Lower values indicate higher quality. Default is 60.
save_dir (Optional[Union[str, os.PathLike]]) – The directory to save the upsampled video(s). If None, the videos will be saved in the same directory as the input video(s).

Returns

None. The function saves the upsampled video(s) to the specified directory.

Example

>>> upsample_fps(video_path='/Users/simon/Desktop/Box2_IF19_7_20211109T173625_4_851_873_1_cropped.mp4', fps=100, quality=100)

simba.video_processors.video_processing.vertical_video_concatenator(video_paths, save_path, width_px=None, width_idx=None, gpu=False, quality=23, verbose=True)[source]

Concatenates multiple videos vertically.

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

FFMPEGCodecGPUError – If GPU is requested but not available.
InvalidInputError – If both or neither width_px and width_idx are provided.

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_bg_subtraction(video_path, avg_frm=None, bg_video_path=None, bg_start_frm=None, bg_end_frm=None, bg_start_time=None, bg_end_time=None, threshold=50, bg_color=(0, 0, 0), fg_color=None, save_path=None, verbose=True, method='absolute', closing_kernel_size=None, closing_iterations=3, opening_kernel_size=None, opening_iterations=3)[source]

Subtract the background from a video.

Note

If bg_video_path is passed, that video will be used to parse the background. If None, video_path will be use dto parse background. Either pass start_frm and end_frm OR start_time and end_time OR pass all four arguments as None. Those two arguments will be used to slice the background video, and the sliced part is used to parse the background.

For example, in the scenario where there is no animal in the video_path video for the first 20s, then the first 20s can be used to parse the background. In this scenario, bg_video_path can be passed as None and bg_start_time and bg_end_time can be 00:00:00 and 00:00:20, repectively.

In the scenario where there is animal(s) in the entire video_path video, pass bg_video_path as a path to a video recording the arena without the animals.

See also

For multicore CPU alternative, see bg_subtraction_cuda() or simba.data_processors.cuda.image.bg_subtraction_cupy().

Parameters

video_path (Union[str, os.PathLike]) – The path to the video to remove the background from.
avg_frm (Optional[np.ndarray]) – The average frame to use to compute the background. If None is passed, then the average frame will be computed.
bg_video_path (Optional[Union[str, os.PathLike]]) – Only used if avg_frm is None. Path to the video which contains a segment with the background only. If None, then video_path will be used.
bg_start_frm (Optional[int]) – The first frame in the background video to use when creating a representative background image. Default: None.
bg_end_frm (Optional[int]) – The last frame in the background video to use when creating a representative background image. Default: None.
bg_start_time (Optional[str]) – The start timestamp in HH:MM:SS format in the background video to use to create a representative background image. Default: None.
bg_end_time (Optional[str]) – The end timestamp in HH:MM:SS format in the background video to use to create a representative background image. Default: None.
threshold (Optional[int]) – Value between 0-255 representing the difference threshold between the average frame subtracted from each frame. Higher values and more pixels will be considered background. Default: 50.
bg_color (Optional[Tuple[int, int, int]]) – The RGB color of the moving objects in the output video. Defaults to None, which represents the original colors of the moving objects.
fg_color (Optional[Tuple[int, int, int]]) – The RGB color of the background output video. Defaults to black (0, 0, 0).
save_path (Optional[Union[str, os.PathLike]]) – The patch to where to save the output video where the background is removed. If None, saves the output video in the same directory as the input video with the _bg_subtracted suffix. Default: None.

Returns

None.

Example

>>> video_bg_subtraction(video_path='/Users/simon/Downloads/1_LH_cropped.mp4', bg_start_time='00:00:00', bg_end_time='00:00:10', bg_color=(0, 106, 167), fg_color=(254, 204, 2))

simba.video_processors.video_processing.video_bg_subtraction_mp(video_path, pool=None, bg_video_path=None, bg_start_frm=None, bg_end_frm=None, bg_start_time=None, bg_end_time=None, avg_frm=None, bg_color=(0, 0, 0), fg_color=None, save_path=None, core_cnt=- 1, verbose=True, gpu=False, threshold=50, method='absolute', closing_kernel_size=None, closing_iterations=3, opening_kernel_size=None, opening_iterations=3)[source]

Subtract the background from a video using multiprocessing.

Note

If avg_frm is passed, that img will be used to parse the background.

If avg_frm is NOT passed and bg_video_path IS passed, the bg_video_path will be used to parse the background.

If avg_frm is NOT passed and bg_video_path is NOT passed, the video_path will be used to parse the background.

If avg_frm is NOT passed, pass consider passing start_frm and end_frm OR start_time and end_time. Those arguments will be used to slice the background video, and the sliced part is used to parse the background.

For example, in the scenario where there is no animal in the video_path video for the first 20s, then the first 20s can be used to parse the background. In this scenario, bg_video_path can be passed as None and bg_start_time and bg_end_time can be 00:00:00 and 00:00:20, repectively.

In the scenario where there is animal(s) in the entire video_path video, pass bg_video_path as a path to a video recording the arena without the animals.

See also

For single core alternative, see video_bg_subtraction(). For GPU based alternative, see bg_subtraction_cuda() or bg_subtraction_cupy().

EXPECTED RUNTIMES
FRAME COUNT	TIME (SECONDS)	STDEV (SECONDS)
1800	18.53	0.84
5400	22.8	0.34
10800	25.89	1.85
21600	40.07	1.23
43200	65.67	1.91
i9-1499KF 14 cores
RESOLUTON: 620x402
3 RUNS

Parameters

video_path (Union[str, os.PathLike]) – The path to the video to remove the background from.
pool (Optional[multiprocessing.Pool]) – Optional multiprocessing pool for parallel processing. If None, a new pool is created and terminated after processing. Default: None.
bg_video_path (Optional[Union[str, os.PathLike]]) – Path to the video which contains a segment with the background only. If None, then video_path will be used. Default: None.
bg_start_frm (Optional[int]) – The first frame in the background video to use when creating a representative background image. Default: None.
bg_end_frm (Optional[int]) – The last frame in the background video to use when creating a representative background image. Default: None.
bg_start_time (Optional[str]) – The start timestamp in HH:MM:SS format in the background video to use to create a representative background image. Default: None.
bg_end_time (Optional[str]) – The end timestamp in HH:MM:SS format in the background video to use to create a representative background image. Default: None.
avg_frm (Optional[Union[np.ndarray, str, os.PathLike]]) – The average frame to use to compute the background. Can be a NumPy array, or a path to an image file. If None is passed, then the average frame will be computed from the background video. Default: None.
bg_color (Tuple[int, int, int]) – The RGB color to use for background pixels in the output video. Default: (0, 0, 0).
fg_color (Optional[Tuple[int, int, int]]) – The RGB color to use for foreground (moving object) pixels in the output video. If None, original colors are preserved. Default: None.
save_path (Optional[Union[str, os.PathLike]]) – The path to where to save the output video where the background is removed. If None, saves the output video in the same directory as the input video with the _bg_subtracted suffix. Default: None.
core_cnt (int) – The number of cores to use. Defaults to -1 representing all available cores.
verbose (bool) – Whether to print progress messages. Default: True.
gpu (bool) – Whether to use GPU acceleration for video concatenation. Default: False.
threshold (Optional[int]) – Value between 1-255 representing the difference threshold between the average frame subtracted from each frame. Higher values mean more pixels will be considered background. Default: 50.
method (str) – Method for background subtraction. Options: ‘absolute’, ‘light’, ‘dark’. Default: ‘absolute’.
closing_kernel_size (Optional[Tuple[int, int]]) – Size of the morphological closing kernel (width, height). If None, closing is not applied. Default: None.
closing_iterations (int) – Number of iterations for morphological closing operation. Default: 3.
opening_kernel_size (Optional[Tuple[int, int]]) – Size of the morphological opening kernel (width, height). If None, opening is not applied. Default: None.
opening_iterations (int) – Number of iterations for morphological opening operation. Default: 3.

Returns

None.

Example

>>> video_bg_subtraction_mp(video_path='/Users/simon/Downloads/1_LH.mp4', bg_start_time='00:00:00', bg_end_time='00:00:10', bg_color=(0, 0, 0), fg_color=(255, 255, 255))

simba.video_processors.video_processing.video_concatenator(video_one_path, video_two_path, resolution='video 1', horizontal=True, quality=None, gpu=False)[source]

Concatenate two videos to a single video either horizontally or vertically

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.
quality (Optional[int]) – Integer (1-100) representing output video quality. Higher = better quality + bigger size. If None, defaults to 60. Default None.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.

Returns

None. The video is stored in the same directory as the video_one_path using the video names concatenated as filename.

Note

Codec is automatically selected: libx264 for CPU encoding (ignored if gpu=True).

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_bw(video_path, threshold=0.5, save_dir=None, gpu=False)[source]

Convert video to black and white using passed threshold.

Parameters

video_path (Union[str, os.PathLike]) – Path to the video
threshold (Optional[float]) – Value between 0 and 1. Lower values gives more white and vice versa.
gpu (Optional[bool]) – If True, uses GPU codecs with potentially faster runtimes. Default: False.

Returns

None.

Example

>>> video_to_bw(video_path='/Users/simon/Downloads/1_LH_clipped_cropped_eq_20240515135926.mp4', threshold=0.02)

simba.video_processors.video_processing.video_to_greyscale(file_path, gpu=False, codec=None, verbose=True, quality=23, save_path=None)[source]

Convert a video file to greyscale mp4 format.

See also

For GPU CuPY acceleration, see img_stack_to_grayscale_cupy() For GPU numba CUDA acceleration, see img_stack_to_grayscale_cuda(), For multicore CPU solutions, see img_stack_to_greyscale() or batch_video_to_greyscale() For single-core multivideo solution, see batch_video_to_greyscale()

Parameters

file_path (Union[str, os.PathLike]) – Path to video file.
gpu (Optional[bool]) – If True, use NVIDEA GPU codecs. Default False.
codec (str) – Video codec to use for CPU encoding. Default ‘libx264’. Ignored if gpu=True.
verbose (bool) – If True, prints conversion progress. Default True.
quality (int) – Video quality (CRF value). Lower values = higher quality. Range 0-52. Default 23.
save_path (Optional[Union[str, os.PathLike]]) – Path where to save the converted video. If None, saves in the same directory as input file with _grayscale.mp4 suffix. Default None.

Returns

None. The result is stored in the same directory as the input file with the _grayscale.mp4 suffix if save_path is not provided.

Raises

FFMPEGCodecGPUError – If no GPU is found and gpu == True.
FileExistError – If video name with _grayscale suffix already exist and save_path is None.

Example

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

simba.video_processors.video_processing.watermark_video(video_path, watermark_path, position='top_left', opacity=0.5, scale=0.05, save_dir=None, gpu=False)[source]

Watermark a video file or a directory of video files with specified watermark size, opacity, and location.

Parameters

video_path (Union[str, os.PathLike]) – The path to the video file or path to directory with video files.
watermark_path (Union[str, os.PathLike]) – The path to the watermark .png file.
position (Optional[str]) – The position of the watermark. Options: ‘top_left’, ‘bottom_right’, ‘top_right’, ‘bottom_left’, ‘center’
opacity (Optional[float]) – The opacity of the watermark as a value between 0-1.0. 1.0 meaning the same as input image. Default: 0.5.
scale (Optional[float]) – The scale of the watermark as a ratio os the image size. Default: 0.05.
save_dir (Optional[Union[str, os.PathLike]]) – The location where to save the watermarked video. If None, then saves the video in the same directory as the first video.
gpu (Optional[bool]) – If True, uses GPU codecs with potentially faster runtimes. Default: False.

Returns

None

Example

>>> watermark_video(video_path='/Users/simon/Desktop/envs/simba/troubleshooting/multi_animal_dlc_two_c57/project_folder/videos/watermark/Together_1_powerpointready.mp4', watermark_path='/Users/simon/Desktop/splash.png', position='top_left', opacity=1.0, scale=0.2)

Crop ROI selector (rectangles)

class simba.video_processors.roi_selector.ROISelector(path, thickness=10, clr=(147, 20, 255), title=None, destroy=True, greyscale=False, clahe=False)[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 etc.

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.
destroy (bool) – If True, destroy drawing window when completed. Default: True.

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, thickness=10, clr=(147, 20, 255), title=None, destroy=True)[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.

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()
>>> circle_selector = ROISelectorCircle(path=r"C:   roubleshooting\mitra    estŃ_MA109_Gi_CNO_0521.mp4")
>>> circle_selector.run()

Crop ROI selector (polygons)

class simba.video_processors.roi_selector_polygon.ROISelectorPolygon(path, thickness=2, vertice_size=3, clr=(147, 20, 255), title=None, destroy=True)[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.

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)[source]

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

Parameters: data (Union[str, os.PathLike, np.ndarray]) – Path to a video file.
Return Tuple[float, int]: Tuple containing the chosen clip limit and tile size.
Example

>>> video = cv2.imread(r"D:/EPM/sample_2/video_1.mp4")
>>> interactive_clahe_ui(data=video)

Interactive brightness / contrast interface

class simba.video_processors.brightness_contrast_ui.BrightnessContrastUI(data)[source]

Bases: object

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

Note

Adapted from geeksforgeeks.

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)

Video processors

Batch process

Get pixels per millimeter

Extract frames

Videos to frames

Extract .SEQ frames

Multi-cropper

Get pixels per millimeter - old

Video processing tools

Crop ROI selector (rectangles)

Crop ROI selector (circles)

Crop ROI selector (polygons)

Interactive CLAHE interface

Interactive brightness / contrast interface

Asynchronous frame reader (GPU)