Image Utils

Utility functions for image-to-text operations in Gen AI applications.

This module provides a comprehensive set of utility functions for handling image data in various formats and sources. It includes functionality for: 1. Image validation and format checking 2. Image loading from various sources (file, URL, base64, S3) 3. Image format conversion and encoding

`box_2d_to_xyxy(box_2d, box_2d_range=DEFAULT_BOX_2D_RANGE)`

Converts a box_2d bounding box into normalized (x_min, y_min, x_max, y_max) coordinates.

box_2d is the bounding box format returned by Gemini models for detection tasks: [ymin, xmin, ymax, xmax] with values in box_2d_range, which is 0-1000 by default. Each value is clamped into that range and scaled to 0-1, with the origin at the top-left corner.

Parameters:

Name	Type	Description	Default
`box_2d`	`Any`	The bounding box returned by the model.	required
`box_2d_range`	`tuple[int, int]`	The `(min_coordinate, max_coordinate)` range the model was asked to use. Defaults to (0, 1000).	`DEFAULT_BOX_2D_RANGE`

Returns:

Type	Description
`tuple[float, float, float, float] \| None`	tuple[float, float, float, float] \| None: The normalized `(x_min, y_min, x_max, y_max)` coordinates, or None if `box_2d` is not a list of four finite numbers or has a minimum edge greater than its maximum edge.

Raises:

Type	Description
`ValueError`	If `box_2d_range` is not a pair of integers or its minimum is not lower than its maximum.

`convert_into_structured_caption(text)`

Convert a structured caption string (YAML or JSON) into a dictionary.

Parameters:

Name	Type	Description	Default
`text`	`str`	The structured caption string to parse.	required

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: The parsed dictionary, or an empty dictionary if parsing fails.

`get_image_size(attachment)`

Gets the pixel size of an image attachment without decoding its pixel data.

Only the image header is read, so this stays cheap for large images.

Parameters:

Name	Type	Description	Default
`attachment`	`Attachment`	The attachment to inspect.	required

Returns:

Type	Description
`tuple[int, int] \| None`	tuple[int, int] \| None: The `(width, height)` in pixels, or None if the attachment is not an image or its size cannot be read.

`resize_attachment(attachment, target_width, target_height, preserve_aspect_ratio=True)`

Resize an attachment's image if it is smaller than the target dimensions.

Parameters:

Name	Type	Description	Default
`attachment`	`Attachment`	The input attachment containing image binary data.	required
`target_width`	`int`	The minimum target width.	required
`target_height`	`int`	The minimum target height.	required
`preserve_aspect_ratio`	`bool`	Whether to preserve the aspect ratio while resizing. Defaults to True.	`True`

Returns:

Name	Type	Description
`Attachment`	`Attachment`	The original attachment if already at or above target dimensions, otherwise a new attachment with the resized image.

`resize_image(image_bytes, target_width, target_height, preserve_aspect_ratio=True)`

Resize image to meet target dimension requirements.

Parameters:

Name	Type	Description	Default
`image_bytes`	`bytes`	The input image binary data.	required
`target_width`	`int`	The target width.	required
`target_height`	`int`	The target height.	required
`preserve_aspect_ratio`	`bool`	Whether to preserve the aspect ratio while resizing. If True, the image is scaled to cover the target dimensions while maintaining aspect ratio. If False, the image is resized exactly to the target dimensions. Defaults to True.	`True`

Returns:

Name	Type	Description
`bytes`	`bytes`	The resized image binary data.

Examples:

Resize with aspect ratio preservation (default)

If input is 64x128 and target is 128x128, output will be 128x256

resized_bytes = resize_image(original_bytes, target_width=128, target_height=128)

Resize to exact dimensions without preserving aspect ratio

Output will be exactly 128x128 regardless of input aspect ratio

exact_bytes = resize_image( original_bytes, target_width=128, target_height=128, preserve_aspect_ratio=False )

`validate_box_2d_range(box_2d_range)`

Validates a box_2d coordinate range and returns it as a (min_coordinate, max_coordinate) tuple.

Parameters:

Name	Type	Description	Default
`box_2d_range`	`Any`	The coordinate range, expected to be a pair of integers where the first is lower than the second.	required

Returns:

Type	Description
`tuple[int, int]`	tuple[int, int]: The validated `(min_coordinate, max_coordinate)` range.

Raises:

Type	Description
`ValueError`	If `box_2d_range` is not a pair of integers or its minimum is not lower than its maximum.