spacr.flowview.thumbs

Qt-free thumbnail preparation and bounded on-disk caching.

Classes

ThumbnailCache

A configurable oldest-first disk cache of PNG thumbnails.

Functions

make_thumbnail(→ PIL.Image.Image)

Return a contrast-stretched thumbnail within the requested edge limit.

thumbnail_png(→ bytes)

Encode make_thumbnail() as deterministic PNG bytes.

Module Contents

class spacr.flowview.thumbs.ThumbnailCache(directory: str | os.PathLike[str], *, max_bytes: int = DEFAULT_CACHE_BYTES, max_size: int = MAX_THUMBNAIL_AXIS)[source]

A configurable oldest-first disk cache of PNG thumbnails.

Parameters:

  • directory – where the thumbnails are written. Created if missing.

  • max_bytes – the cache’s size budget. When writing would exceed it, the oldest entries are evicted until it fits – oldest-first rather than least-recently-used, because a thumbnail is cheap to regenerate and tracking access times costs a write on every read.

  • max_size – the longest edge, in pixels, of a generated thumbnail. Capped at MAX_THUMBNAIL_AXIS.

Raises:

ValueError – when max_bytes is not positive, or max_size is outside 1..MAX_THUMBNAIL_AXIS.

File publication is atomic across cache instances, so concurrent readers see either the old or new complete PNG. Budgeting and deletion are guarded only within one instance; use one mutating instance per directory.

Create a cache directory with byte and pixel limits.

Parameters:

  • directory – directory reserved for generated thumbnail entries.

  • max_bytes – positive total byte budget for cache-owned PNG files.

  • max_size – generated thumbnail’s maximum width or height.

Raises:

ValueError – when a normalized limit falls outside its range.

clear() → int[source]

Delete generated PNG entries and return the number removed.

Foreign files, including PNGs outside the SHA-256 namespace, remain.

discard() → int[source]

Clear the cache and remove its directory when empty.

Returns:

number of generated PNG entries removed.

A successful directory removal makes this instance terminal; create a new cache before storing another thumbnail.

get(key: object) → pathlib.Path | None[source]

Return an existing thumbnail path without changing its age.

Parameters:

key – cache identity accepted by path_for().

Returns:

cache-owned path when it exists, otherwise None.

path_for(key: object) → pathlib.Path[source]

Return the traversal-safe cache path assigned to key.

Parameters:

key – cache identity, normalized with str before hashing.

Returns:

path whose filename is a lowercase SHA-256 digest plus .png.

Keys with identical string representations intentionally share a path.

store(key: object, image: str | os.PathLike[str] | PIL.Image.Image | Any, *, outline_mask: Any | None = None) → pathlib.Path[source]

Prepare and atomically cache a thumbnail.

Parameters:

  • key – cache identity accepted by path_for().

  • image – image path, Pillow image, or array-like pixel data.

  • outline_mask – optional two-dimensional mask matching the source.

Returns:

path of the published PNG after oldest-first eviction.

Raises:

ValueError – when the encoded PNG exceeds the byte budget.

property total_bytes: int[source]

Return the byte size of this cache’s generated PNG entries.

spacr.flowview.thumbs.make_thumbnail(image: str | os.PathLike[str] | PIL.Image.Image | Any, *, outline_mask: Any | None = None, max_size: int = MAX_THUMBNAIL_AXIS) → PIL.Image.Image[source]

Return a contrast-stretched thumbnail within the requested edge limit.

outline_mask may contain binary or labelled segmentation data. Its boundaries are overlaid as one-pixel neutral-white lines after nearest- neighbour downsampling; filled regions are never painted.

Parameters:

  • image – image path, Pillow image, or array-like pixel data.

  • outline_mask – optional two-dimensional mask matching the source size.

  • max_size – maximum width or height, capped by MAX_THUMBNAIL_AXIS.

Returns:

detached Pillow image containing the rendered thumbnail.

Raises:

ValueError – when the size, image shape, or mask shape is invalid.

spacr.flowview.thumbs.thumbnail_png(image: str | os.PathLike[str] | PIL.Image.Image | Any, *, outline_mask: Any | None = None, max_size: int = MAX_THUMBNAIL_AXIS) → bytes[source]

Encode make_thumbnail() as deterministic PNG bytes.

Parameters:

  • image – image path, Pillow image, or array-like pixel data.

  • outline_mask – optional two-dimensional mask matching the source size.

  • max_size – maximum width or height of the encoded thumbnail.

Returns:

complete PNG file contents suitable for atomic publication.