Various ad hoc image related utility functions and classes. If you're using the SIXEL support (images in the terminal) I recommand also installing libsixel.

Short summary:

• as_sixel_bytes: A generator yielding img as SIXEL format bytes chunks.

• sixel: Return the filesystem path of a cached SIXEL version of the image at imagepath.

• sixel_from_image_bytes: Return the filesystem path of a cached SIXEL version of the image data in image_bs.

• SixelImageString: A str subclass for printing a Pillow Image.

• sized_sixel_bytes: Wrapper for as_sixel_bytes() which returns a 4 tuple of (list[bytes],char_width,char_height,tty_size_info) being: - a list of the bytes chunks yielded from as_sixel_bytes() - the width of the SIXEL image in characters - the height of the SIXEL image in characters - the tty information used to calculate the result as a WinSizePX.

• ThumbnailCache: A class to manage a collection of thumbnail images.

Functions

as_sixel_bytes(img: PIL.Image.Image) -> Generator[bytes, NoneType, NoneType]

A generator yielding img as SIXEL format bytes chunks.

This tries to use libsixel but falls back to the external executable img2sixel if that is not available.

sixel(imagepath: str) -> str

Return the filesystem path of a cached SIXEL version of the image at imagepath.

sixel_from_image_bytes(image_bs: bytes) -> str

Return the filesystem path of a cached SIXEL version of the image data in image_bs.

sized_sixel_bytes(img: PIL.Image.Image, tty=1) -> tuple[list[bytes], int, int, cs.tty.WinSizePX]

Wrapper for as_sixel_bytes() which returns a 4 tuple of (list[bytes],char_width,char_height,tty_size_info) being:

• a list of the bytes chunks yielded from as_sixel_bytes()
• the width of the SIXEL image in characters
• the height of the SIXEL image in characters
• the tty information used to calculate the result as a WinSizePX

Parameters:

• img: a Pillow Image
• tty: an optional file or file descriptor for the tty whose size will be measured; the default is 1 for the standard output

Writing the SIXEL data will occupy a rectangle char_width wide by char_high high and move the cursor down char_high-1 rows in the original column.

Classes

class SixelImageString(builtins.str)

A str subclass for printing a Pillow Image.

SixelImageString.copy(self, image=None, **updates)

Return a copy of this mage string, with modifications.

SixelImageString.resized_within(self, new_width: int, new_height: int, *, size_up=False, tty=None, warp_aspect=False)

Resize the image to fit within new_width x new_height characters.

SixelImageString.split(self, *a, **kw)

Splitting an image string returns an image string for the final component.

This is a bit of a bodge, but should work with stuff like printt().

class ThumbnailCache(cs.cache.ConvCache)

A class to manage a collection of thumbnail images.

ThumbnailCache.DEFAULT_CACHE_BASEPATH

'~/var/cache/im/thumbnails'

ThumbnailCache.DEFAULT_MIN_SIZE

16

ThumbnailCache.DEFAULT_SCALE_STEP

2.0

ThumbnailCache.create_thumbnail(self, imagepath: str, thumbpath: str, max_edge: int)

Write a thumbnail image no larger than max_edgexmax_edge of imagepath to thumbpath.

ThumbnailCache.thumb_for_path(self, dx, dy, imagepath)

Return the path to the thumbnail of at least (dx,dy) size for imagepath. Creates the thumbnail if necessary.

Parameters:

• dx, dy: the target display size for the thumbnail.
• image: the source image, an image file pathname or a PIL Image instance.

The generated thumbnail will have at least these dimensions unless either exceeds the size of the source image. In that case the original source image will be returned; this result can be recognised with an identity check.

Thumbnail paths are named after the SHA1 digest of their file content.

ThumbnailCache.thumb_scale(self, dx, dy)

Compute thumbnail size from target dimensions.