ImagesLoader

Bases: ImageIO

Perform image loading from a folder of images or a video.

Images will be loaded and returned in the order that they appear in the folder, or in the video to ensure deterministic ordering. Loading occurs in a background thread, caching 8 images at a time so that other processes do not need to wait on disk reads.

See also ImageIO for additional attributes.

Parameters:

path (str | list[str]) – The path to load images from. This can be a folder which contains images a video file or a list of image files.
queue_size (int) – The amount of images to hold in the internal buffer. Default: 8.
fast_count (bool) – When loading from video, the video needs to be parsed frame by frame to get an accurate count. This can be done quite quickly without guaranteed accuracy, or slower with guaranteed accuracy. Set to True to count quickly, or False to count slower but accurately. Default: True.
skip_list (list[int] | None) – Optional list of frame/image indices to not load. Any indices provided here will be skipped when executing the load() function from the given location. Default: None
count (int | None) – If the number of images that the loader will encounter is already known, it can be passed in here to skip the image counting step, which can save time at launch. Set to None if the count is not already known. Default: None
pts (list[int] | None) – The Presentation Timestamps if the source is a video and they are available. Default: None
keyframes (list[int] | None) – The Keyframes if the source is a video and they are available. Default: None

Examples

Loading from a video file:

>>> loader = ImagesLoader('/path/to/video.mp4')
>>> for filename, image in loader.load():
>>>     <do processing>

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

Methods Summary

`add_skip_list`(skip_list)	Add a skip list to this `ImagesLoader`
`close`()	Closes down and joins the internal threads
`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

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(): Closes down and joins the internal threads

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]