Extract Frames Function References

Functions documentation for extract_frames.py

Function Reference

`scripts.preprocessing.extract_frames`

Functions for extracting frames from cross-sucking videos

`extract_frames(video_paths, videos_root, working_dir, split, skip, force=False)`

Orchestrate asynchronous frame extraction for a collection of video files.

Validates relative video path targets against a root directory, configures an isolated node-local staging environment for the specified dataset split, and handles multi-threaded background disk-writing workers.

Parameters:

Name	Type	Description	Default
`video_paths`	`list of str`	Relative file paths to individual target video files inside `videos_root`.	required
`videos_root`	`Path`	The absolute root path directory containing the unlabelled source videos.	required
`working_dir`	`Path`	The core active staging directory workspace (typically a local compute NVMe partition).	required
`split`	`str`	The specific machine learning dataset subset split; must be `'train'` or `'val'`.	required
`skip`	`int`	The integer stride sequence interval used for frame downsampling. Must be greater than 0.	required
`force`	`bool`	If True, ignores existing matching output data targets and forces re-extraction.	`False`

Returns:

Name	Type	Description
`saved_frames_registry`	`dict of {tuple(int, str or None) : set of int}`	A multi-video frame tracking map. Keys are unique video identifying tuples, and values are sets of integers containing successfully processed frame indices.

Raises:

Type	Description
`TypeError`	If input arguments fail structural type matching validations.
`ValueError`	If `split` is an unsupported keyword string or `skip` is non-positive.

`generate_video_metadata(video_name)`

Extract lookup keys and file prefixes from an unlabelled video clip name.

Parameters:

Name	Type	Description	Default
`video_name`	`str`	The raw base name of the video file (e.g., 'CS_0042_clip.mp4').	required

Returns:

Name	Type	Description
`video_key`	`tuple of (int, str or None)`	A tracking tuple pair composed of (numeric_id, part_id) used to index and align extracted video frames with corresponding labels.
`file_prefix`	`str`	The standardized prefix format used for outputting dataset frame files, structured as `"{numeric_id:04}_{part_str}_frame_"`.

Raises:

Type	Description
`TypeError`	If `video_name` is not a string.
`ValueError`	If `video_name` is empty or composed entirely of whitespace.

`process_single_video(video_path, file_prefix, final_output_dir, skip, executor, semaphore, safe_write_func)`

Extract and process downsampled frames from a single video stream.

Decodes a video file sequentially using OpenCV. Frames matching the downsampling interval stride are pushed to an asynchronous multi-threaded writer pool for high-speed disk writing. Non-matching frames are rapidly bypassed directly via native decoder buffer grabbing.

Parameters:

Name	Type	Description	Default
`video_path`	`Path`	The absolute or relative filesystem path to the source video file clip.	required
`file_prefix`	`str`	The standardized filename prefix used to identify individual dataset frame assets.	required
`final_output_dir`	`Path`	The destination directory path where output image frames will be written.	required
`skip`	`int`	The frame downsampling stride interval (e.g., `5` processes every 5th frame).	required
`executor`	`ThreadPoolExecutor`	An active thread pool workspace utilized to handle unblocked background file writes.	required
`semaphore`	`BoundedSemaphore`	A resource lock counter limiting the maximum length of the thread queue pool to protect memory buffers.	required
`safe_write_func`	`callable`	The specialized thread target worker function executing image writes and resource releases.	required

Returns:

Name	Type	Description
`saved_frames`	`set of int`	A set containing the absolute sequential integers of all frames successfully decoded and dispatched to the background file writer.

Raises:

Type	Description
`TypeError`	If parameter input arguments fail baseline structural type boundaries.
`ValueError`	If `skip` is not a positive integer greater than zero.
`FileNotFoundError`	If the file located at `video_path` does not exist on disk.