pyrit.prompt_converter.ImageCompressionConverter

pyrit.prompt_converter.ImageCompressionConverter#

class ImageCompressionConverter(*, output_format: Literal['JPEG', 'PNG', 'WEBP'] | None = None, quality: int | None = None, optimize: bool | None = None, progressive: bool | None = None, compress_level: int | None = None, lossless: bool | None = None, method: int | None = None, background_color: tuple[int, int, int] = (0, 0, 0), min_compression_threshold: int = 1024, fallback_to_original: bool = True)[source]#

Bases: PromptConverter

Compresses images to reduce file size while preserving visual quality.

This converter supports multiple compression strategies across JPEG, PNG, and WEBP formats, each with format-specific optimization settings. It can maintain the original image format or convert between formats as needed.

When converting images with transparency (alpha channel) to JPEG format, the converter automatically composites the transparent areas onto a solid background color.

Supported input types: File paths to any image that PIL can open (or URLs pointing to such images): https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#fully-supported-formats

Supported output formats and their compression options:

  • JPEG: quality, optimize, progressive

  • PNG: optimize, compress_level

  • WEBP: quality, lossless, method

References

https://pillow.readthedocs.io/en/stable/handbook/concepts.html https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#jpeg-saving https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#png-saving https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#webp-saving

__init__(*, output_format: Literal['JPEG', 'PNG', 'WEBP'] | None = None, quality: int | None = None, optimize: bool | None = None, progressive: bool | None = None, compress_level: int | None = None, lossless: bool | None = None, method: int | None = None, background_color: tuple[int, int, int] = (0, 0, 0), min_compression_threshold: int = 1024, fallback_to_original: bool = True)[source]#

Initializes the converter with specified compression settings.

Parameters:

  • output_format (str, optional) – Output image format. If None, keeps original format (if supported).

  • quality (int, optional) –

    General quality setting for JPEG and WEBP formats (0-100).

    For JPEG format, it represents the image quality, on a scale from 0 (worst) to 95 (best).

    For WEBP format, the value ranges from 0 to 100; for lossy compression: 0-smallest file size and 100-largest; for lossless: 0-fastest/less efficient, and 100 gives the best compression.

  • optimize (bool, optional) –

    Whether to optimize the image during compression.

    For JPEG: makes the encoder perform an extra pass over the image to select optimal settings.

    For PNG: instructs the PNG writer to make the output file as small as possible.

  • progressive (bool, optional) – Whether to save JPEG images as progressive.

  • compress_level (int, optional) – ZLIB compression level (0-9): 1=fastest, 9=best, 0=none. Ignored if optimize is True (then it is forced to 9).

  • lossless (bool, optional) – Whether to use lossless compression for WEBP format.

  • method (int, optional) – Quality/speed trade-off for WEBP format (0=fast, 6=slower-better).

  • background_color (tuple[int, int, int]) – RGB color tuple for background when converting transparent images to JPEG. Defaults to black.

  • min_compression_threshold (int) – Minimum file size threshold for compression. Defaults to 1024 bytes.

  • fallback_to_original (bool) – Fallback to original if compression increases file size. Defaults to True.

Raises:

ValueError – If unsupported output format is specified, or if some of the parameters are out of range.

Methods

__init__(*[, output_format, quality, ...])

Initializes the converter with specified compression settings.

convert_async(*, prompt[, input_type])

Converts the given prompt (image) by compressing it.

convert_tokens_async(*, prompt[, ...])

Converts substrings within a prompt that are enclosed by specified start and end tokens.

get_identifier()

Returns an identifier dictionary for the converter.

input_supported(input_type)

Checks if the input type is supported by the converter.

output_supported(output_type)

Checks if the output type is supported by the converter.

Attributes

supported_input_types

Returns a list of supported input types for the converter.

supported_output_types

Returns a list of supported output types for the converter.
async convert_async(*, prompt: str, input_type: Literal['text', 'image_path', 'audio_path', 'video_path', 'url', 'reasoning', 'error'] = 'image_path') → ConverterResult[source]#

Converts the given prompt (image) by compressing it.

Parameters:

  • prompt (str) – The image file path or URL pointing to the image to be compressed.

  • input_type (PromptDataType) – The type of input data.

Returns:

The result containing path to the compressed image.

Return type:

ConverterResult

Raises:

ValueError – If the input type is not supported.

input_supported(input_type: Literal['text', 'image_path', 'audio_path', 'video_path', 'url', 'reasoning', 'error']) → bool[source]#

Checks if the input type is supported by the converter.

Parameters:

input_type (PromptDataType) – The input type to check.

Returns:

True if the input type is supported, False otherwise.

Return type:

bool

output_supported(output_type: Literal['text', 'image_path', 'audio_path', 'video_path', 'url', 'reasoning', 'error']) → bool[source]#

Checks if the output type is supported by the converter.

Parameters:

output_type (PromptDataType) – The output type to check.

Returns:

True if the output type is supported, False otherwise.

Return type:

bool

Contents