read_image

lib.image.read_image(filename: str, raise_error: Literal[False] = False, with_metadata: Literal[False] = False) → npt.NDArray[np.uint8] | None
lib.image.read_image(filename: str, raise_error: Literal[True], with_metadata: Literal[False] = False) → npt.NDArray[np.uint8]
lib.image.read_image(filename: str, raise_error: Literal[False] = False, *, with_metadata: Literal[True]) → tuple[npt.NDArray[np.uint8], PNGHeader]
lib.image.read_image(filename: str, raise_error: Literal[True], with_metadata: Literal[True]) → npt.NDArray[np.uint8]

Read an image file from a file location.

Extends the functionality of cv2.imread() by ensuring that an image was actually loaded. Errors can be logged and ignored so that the process can continue on an image load failure.

Parameters:

  • filename (str) – Full path to the image to be loaded.

  • raise_error (bool) – If True then any failures (including the returned image being None) will be raised. If False then an error message will be logged, but the error will not be raised. Default: False

  • with_metadata (bool) – Only returns a value if the images loaded are extracted Faceswap faces. If True then returns the Faceswap metadata stored with in a Face images .png EXIF header. Default: False

Returns:

  • image – The image in BGR channel order as UINT8 for the corresponding filename

  • metadata – The faceswap metadata corresponding to the image. Only returned if with_metadata is True

Return type:

np.ndarray | None | tuple[npt.NDArray[np.uint8], PNGHeader]

Example

>>> image_file = "/path/to/image.png"
>>> try:
>>>    image = read_image(image_file, raise_error=True, with_metadata=False)
>>> except:
>>>     raise ValueError("There was an error")