Skip to content

Image

Platform image service for loading and caching PhotoImage objects.

This class provides a centralized service for working with images in bootstack applications. It handles:

  • Loading images from files, bytes, or PIL Image objects
  • Automatic caching to avoid repeated decoding
  • Keeping strong references to prevent Tk garbage collection issues
  • Support for many image formats via Pillow (PNG, JPEG, GIF, BMP, etc.)

All methods are class methods, so no instantiation is required.

Examples:

    # From a file path
    icon = Image.open("path/to/icon.png")

    # From raw bytes
    icon = Image.from_bytes(embedded_data)

    # From a PIL Image object
    pil_img = PILImage.open("photo.jpg").resize((100, 100))
    icon = Image.from_pil(pil_img)

    # Create a transparent spacer
    spacer = Image.transparent(32, 32)
Note

Images are cached by default using automatically generated keys based on the source (file path, content hash, or object id). You can provide a custom key parameter to control caching behavior.

get_cached classmethod 

get_cached(key: Hashable) -> PILPhotoImage | None

Retrieve a cached PhotoImage by its key.

Parameters:

Name Type Description Default
key Hashable

The cache key to look up.

 required

Returns:

Type Description
PhotoImage | None

The cached PhotoImage if found, or None if not in cache.

set_cached classmethod 

set_cached(key: Hashable, img: PhotoImage) -> PILPhotoImage

Store a PhotoImage in the cache.

Parameters:

Name Type Description Default
key Hashable

The cache key to store the image under.

 required
img PhotoImage

The PhotoImage to cache.

 required

Returns:

Type Description
PhotoImage

The same PhotoImage that was passed in (for chaining).

clear_cache classmethod 

clear_cache() -> None

Clear all cached images.

This removes all images from the cache. Use with caution, as any widgets still referencing these images may display incorrectly.

cache_info classmethod 

cache_info() -> ImageCacheInfo

Get information about the current cache state.

Returns:

Type Description
ImageCacheInfo

An ImageCacheInfo object containing cache statistics.

Examples:

>>> info = Image.cache_info()
>>> print(f"Cached images: {info.items}")

open classmethod 

open(
    path: str | Path, *, key: Hashable | None = None
) -> PILPhotoImage

Load an image from a file path.

Opens an image file using Pillow and converts it to a Tk-compatible PhotoImage. The result is cached to avoid repeated disk reads and decoding for the same file.

Parameters:

Name Type Description Default
path str | Path

Path to the image file. Supports ~ expansion and relative paths.

 required
key Hashable | None

Optional custom cache key. If not provided, the absolute file path is used as the cache key.

 None

Returns:

Type Description
PhotoImage

A Tk-compatible PhotoImage that can be used with widgets.

Examples:

>>> photo = Image.open("assets/logo.png")
>>> label = Label(app, image=photo)

>>> # With custom cache key for versioning
>>> photo = Image.open("icon.png", key=("icon", "v2"))

from_pil classmethod 

from_pil(
    image: Image, *, key: Hashable | None = None
) -> PILPhotoImage

Convert a PIL Image to a Tk PhotoImage.

Wraps an existing PIL Image object in a Tk-compatible PhotoImage. This is useful when you need to perform image manipulation (resizing, filtering, etc.) before displaying the image.

Parameters:

Name Type Description Default
image Image

A PIL Image object to convert.

 required
key Hashable | None

Optional custom cache key. If not provided, the object id of the PIL Image is used (note: this means the same PIL Image object will be cached, but copies won't hit the cache).

 None

Returns:

Type Description
PhotoImage

A Tk-compatible PhotoImage that can be used with widgets.

Examples:

>>> from PIL import Image as PILImage
>>> pil_img = PILImage.open("photo.jpg")
>>> pil_img = pil_img.resize((100, 100))
>>> photo = Image.from_pil(pil_img)

from_bytes classmethod 

from_bytes(
    data: bytes, *, key: Hashable | None = None
) -> PILPhotoImage

Create a PhotoImage from raw image bytes.

Decodes image data from bytes using Pillow and converts it to a Tk-compatible PhotoImage. This is useful for embedded resources, downloaded images, or any other source of raw image data.

Parameters:

Name Type Description Default
data bytes

Raw image bytes in any format supported by Pillow (PNG, JPEG, GIF, BMP, etc.).

 required
key Hashable | None

Optional custom cache key. If not provided, an MD5 hash of the bytes is used as the cache key.

 None

Returns:

Type Description
PhotoImage

A Tk-compatible PhotoImage that can be used with widgets.

Examples:

>>> # Load from embedded resource
>>> with open("icon.png", "rb") as f:
...     icon_data = f.read()
>>> photo = Image.from_bytes(icon_data)

>>> # With custom cache key
>>> photo = Image.from_bytes(data, key="my-icon")

transparent classmethod 

transparent(
    width: int, height: int, *, key: Hashable | None = None
) -> PILPhotoImage

Create a transparent spacer image.

Creates a fully transparent RGBA image of the specified dimensions. This is useful for creating spacing in layouts or as a placeholder image.

Parameters:

Name Type Description Default
width int

Width of the image in pixels.

 required
height int

Height of the image in pixels.

 required
key Hashable | None

Optional custom cache key. If not provided, a tuple of ("transparent", width, height) is used.

 None

Returns:

Type Description
PhotoImage

A transparent Tk-compatible PhotoImage.

Examples:

>>> # Create a 16x16 transparent spacer
>>> spacer = Image.transparent(16, 16)
>>> label = Label(app, image=spacer)

>>> # Use as compound image padding
>>> button = Button(app, image=spacer, compound="left")