Metadata-Version: 2.4
Name: cs-imageutils
Version: 20261016.1
Summary: 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`.
Keywords: python3
Author-email: Cameron Simpson <cs@cskk.id.au>
Description-Content-Type: text/markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Dist: Pillow
Requires-Dist: cs.ascii_art>=20260912
Requires-Dist: cs.cache>=20260531
Requires-Dist: cs.deco>=20261016
Requires-Dist: cs.gimmicks>=20260311
Requires-Dist: cs.pfx>=20260912
Requires-Dist: cs.psutils>=20260531
Requires-Dist: cs.tty>=20261016
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/imageutils.py

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_edge`x`max_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.
