SingleFrameLoader

class lib.image.SingleFrameLoader(path: str, video_meta_data: dict[Literal['pts_time', 'keyframes'], list[int]] | None = None)

Bases: ImagesLoader

Allows direct access to a frame by filename or frame index.

As we are interested in instant access to frames, there is no requirement to process in a background thread, as either way we need to wait for the frame to load.

Parameters:

• path (str) – Full path to the input media

• video_meta_data (dict[T.Literal['pts_time', 'keyframes'], list[int]] | None) – Existing video meta information containing the pts_time and is_key flags for the given video. Used in conjunction with single_frame_reader for faster seeks. Providing this means that the video does not need to be scanned again. Set to None if the video is to be scanned. Default: None

Attributes Summary

count	The number of images or video frames in the source location.
file_list	A full list of files in the source location.
is_video	True if the input is a video, False if it is not
location	The folder or video that was passed in as the path parameter.
process_count	The number of images or video frames to be processed (IE the total count less items that are to be skipped from the skip_list)
processed_file_list	A list of files in the source location with any files that will be skipped removed
video_meta_data	For videos contains the keys frame_pts holding a list of time stamps for each frame and keyframes holding the frame index of each key frame.

Methods Summary

add_skip_list(skip_list)	Add a skip list to this ImagesLoader
close()	Shut down the video reader
image_from_index(index)	Return a single image from file_list for the given index.
load()	Generator for loading images from the given location

Attributes Documentation

count

The number of images or video frames in the source location. This count includes any files that will ultimately be skipped if a skip_list has been provided. See also process_count

file_list

A full list of files in the source location. This includes any files that will ultimately be skipped if a skip_list has been provided. If the input is a video then this is a list of dummy filenames as corresponding to an alignments file

is_video

True if the input is a video, False if it is not

location

The folder or video that was passed in as the path parameter.

Type:

str

process_count

The number of images or video frames to be processed (IE the total count less items that are to be skipped from the skip_list)

processed_file_list

A list of files in the source location with any files that will be skipped removed

video_meta_data

For videos contains the keys frame_pts holding a list of time stamps for each frame and keyframes holding the frame index of each key frame.

Notes

Only populated if the input is a video and single frame reader is being used, otherwise returns None.

Methods Documentation

add_skip_list(skip_list: list[int]) → None

Add a skip list to this ImagesLoader

Parameters:

skip_list (list[int]) – A list of indices corresponding to the frame indices that should be skipped by the load() function.

Return type:

None

close() → None

Shut down the video reader

Return type:

None

image_from_index(index: int) → tuple[str, npt.NDArray[np.uint8]]

Return a single image from file_list for the given index. We do not use a background thread for this task, as it is assumed that requesting an image by index will be done when required.

Parameters:

index (int) – The index number (frame number) of the frame to retrieve. NB: The first frame is index 0

Returns:

• filename (str) – The filename of the returned image

• image (numpy.ndarray) – The image for the given index

Return type:

tuple[str, npt.NDArray[np.uint8]]

load() → T.Generator[tuple[str, npt.NDArray[np.uint8]] | tuple[str, npt.NDArray[np.uint8], PNGHeader], None, None]

Generator for loading images from the given location

If FacesLoader is in use then the Faceswap metadata of the image stored in the image exif file is added as the final item in the output tuple.

Yields:

• filename – The filename of the loaded image.

• image – The loaded image.

• metadata – The Faceswap metadata associated with the loaded image. (FacesLoader only)

Return type:

T.Generator[tuple[str, npt.NDArray[np.uint8]] | tuple[str, npt.NDArray[np.uint8], PNGHeader], None, None]

close() → None

Shut down the video reader

Return type:

None

image_from_index(index: int) → tuple[str, npt.NDArray[np.uint8]]

Return a single image from file_list for the given index. We do not use a background thread for this task, as it is assumed that requesting an image by index will be done when required.

Parameters:

index (int) – The index number (frame number) of the frame to retrieve. NB: The first frame is index 0

Returns:

• filename (str) – The filename of the returned image

• image (numpy.ndarray) – The image for the given index

Return type:

tuple[str, npt.NDArray[np.uint8]]

property video_meta_data: dict[Literal['pts_time', 'keyframes'], list[int]] | None

For videos contains the keys frame_pts holding a list of time stamps for each frame and keyframes holding the frame index of each key frame.

Notes

Only populated if the input is a video and single frame reader is being used, otherwise returns None.