dgs.utils.image.load_image

dgs.utils.image.load_image(filepath: str | tuple[str, ...], force_reshape: bool = False, dtype: torch.dtype = torch.float32, device: torch.device = 'cpu', read_mode: torchvision.io.ImageReadMode = torchvision.io.ImageReadMode.RGB, **kwargs) → torchvision.tv_tensors.Image | torch.Tensor[source]

Load an image or multiple images given a single or multiple filepaths.

This function does return a single tensor containing all the images. If you are simply trying to load multiple images and do not need a single tensor, check out load_image_list(). To be able to do so, make sure that either the images have the same shape, or force_reshape is set to True. Additional parameters for the forced reshaped variant can be specified.

Notes

To be able to compute gradients, the dtype of the images has to be a float (e.g., torch.float32).

Parameters:

  • filepath – Single string or list of absolute or local filepaths to the image.

  • force_reshape – Whether to reshape the image(s) to a target shape. The mode and size can be specified in the kwargs. Default False.

  • dtype – The dtype of the image, most likely one of uint8, byte, or float32. Default torch.float32.

  • device – Device the image should be on. Default “cpu”

  • read_mode – Which ImageReadMode to use while loading the images. Default ‘ImageReadMode.RGB’.

Keyword Arguments:

  • mode – If force_reshape is true, defines the resize mode, has to be in the modes of CustomToAspect. Default “zero-pad”.

  • output_size – If force_reshape is true, defines the height and width of the returned images. Default (256, 256).

Examples

>>> img = load_image("./tests/test_data/866-200x300.jpg")
>>> print(img.shape)
torch.Size([1, 3, 300, 200])

>>> multiple_images = ["./tests/test_data/866-200x300.jpg", "./tests/test_data/866-1000x1000.jpg"]
>>> imgs = load_image(multiple_images)
Traceback (most recent call last):
    ...
RuntimeError: All images should have the same shape.

>>> imgs = load_image(multiple_images, force_reshape=True, output_size=(300, 300))
>>> print(imgs.shape)
torch.Size([2, 3, 300, 300])
Raises:

RuntimeError – If images have different shapes but force_reshape is False.

Returns:

Torch tensor with its original shape of [B x C x H x W] if force_reshape is false, otherwise the returned shape depends on the output_size. The returned image will always have four dimensions. The returned image will have the dtype and respective scale as provided.