tlc.helpers.image_helper¶

Helpers for working with image data.

Module Contents¶

Classes¶

Class

Description

ImageHelper

Helper class for image operations.

API¶

class ImageHelper¶

Helper class for image operations.

static get_exif_image_dimensions(
image_url: str | Path | Url,
) → tuple[int, int]¶

Get the dimensions of an image, accounting for Exif orientation.

Parameters:

image_url – The URL of the image.

Returns:

The image dimensions (height, width).

static get_exif_image_dimensions_from_bytes(
image_bytes: bytes,
source: str | None = None,
) → tuple[int, int]¶

Get the dimensions of an image from bytes, accounting for Exif orientation.

Parameters:

  • image_bytes – The bytes of the image.

  • source – Optional identifier (e.g. a URL) naming the image in the warning emitted when its body is truncated or corrupt but the header dimensions are still readable.

Returns:

The image dimensions (height, width).

static open(
source: str | Path | Url | bytes | bytearray | Image,
*,
mode: str | None = None,
) → Image¶

Open an image from a path, URL, raw bytes, or an existing PIL image.

This is the canonical way to turn an image-column sample value into a PIL.Image.Image regardless of how the column is stored. A table’s image sample can surface either as a path/URL string (file-backed columns) or as an already-loaded PIL.Image.Image (inline columns); passing either — or raw encoded bytes — to this method always yields a usable image. Passing a PIL.Image.Image returns it unchanged (apart from an optional mode conversion), so it is safe to call defensively in a transform or preprocessing function:

from tlc.helpers import ImageHelper

def map_fn(sample):
    image = ImageHelper.open(sample["image"], mode="RGB")
    return my_transform(image)

String/Path/tlc.Url inputs are resolved through the 3LC URL-adapter system, so remote (s3://, gs://) and aliased URLs work, not just local files.

Parameters:

  • source – A path or URL string, a Path, a tlc.Url, raw encoded image bytes, or an existing PIL.Image.Image.

  • mode – If given, convert the image to this PIL mode (e.g. "RGB") when it differs from the current mode.

Returns:

The loaded image as a PIL image.