Saving images and adversarial examples

New in 1.5.0

save_image_batch was first introduced in v1.5.0.

To avoid degrading the effectiveness of adversarial perturbation through image saving to and opening from disk, use save_image_batch.

As a rule of thumb, we recommend saving images as PNGs, as they better keep the image quality than JPEGs. To compare, in the unit tests of torchattack, we use:

• a tolerance of 4e-3 for PNGs, which approx. to \(\varepsilon = 1 / 255\) in the \(\ell_\infty\) norm, and
• a tolerance of 8e-3 for JPEGs, which approx. to \(\varepsilon = 2 / 255\).

A commonly used perturbation magnitude is \(\varepsilon = 8 / 255\), for reference.

save_image_batch(imgs, save_dir, filenames=None, extension='png', kwargs=None)

Losslessly (as lossless as possible) save a batch of images to disk.

Parameters:

Name	Type	Description	Default
imgs	Tensor	The batch of images to save.	required
save_dir	str	The directory to save the images (parent folder).	required
filenames	list[str] | None	The names of the images without their extensions. Defaults to None.	None
extension	str	The extension of the images to save as. One of 'png', 'jpeg'. Defaults to "png".	'png'
kwargs	dict | None	Additional keyword arguments to pass to the image save function. Defaults to None.	None

Source code in torchattack/evaluate/save_image.py

def save_image_batch(
    imgs: torch.Tensor,
    save_dir: str,
    filenames: list[str] | None = None,
    extension: str = 'png',
    kwargs: dict | None = None,
) -> None:
    """Losslessly (as lossless as possible) save a batch of images to disk.

    Args:
        imgs: The batch of images to save.
        save_dir: The directory to save the images (parent folder).
        filenames: The names of the images without their extensions. Defaults to None.
        extension: The extension of the images to save as. One of 'png', 'jpeg'. Defaults to "png".
        kwargs: Additional keyword arguments to pass to the image save function. Defaults to None.
    """

    if kwargs is None:
        kwargs = (
            {}
            # To best preserve perturbation effectiveness, we recommend saving as PNGs
            # See: https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#png-saving
            if extension == 'png'
            # If saving as JPEGs, add additional arguments to ensure perturbation quality
            # See: https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#jpeg-saving
            else {'quality': 100, 'subsampling': 0, 'keep_rgb': True}
        )

    assert extension in ['png', 'jpeg'], 'Extension must be either `png` or `jpeg`.'

    # Create the parent directory if it does not exist
    if not os.path.exists(save_dir):
        os.makedirs(save_dir)

    # Generate random filenames if none are provided
    if filenames is None:
        filenames = _generate_filenames(len(imgs))

    assert imgs.dim() == 4, 'Input tensor must be 4D (BCHW)'
    assert imgs.size(0) == len(filenames), 'Batch size must match number of filenames'

    for x, name in zip(imgs, filenames):
        img = x.detach().cpu().numpy().transpose(1, 2, 0)
        img = Image.fromarray((img * 255).astype('uint8'))
        img.save(os.path.join(save_dir, f'{name}.{extension}'), **kwargs)