Skip to content

web_image

web_image #

Browser-ready pictures: any still image as a JPEG a page can show.

  1. Fit. A JPEG already within the size a viewer asks for is shown as it is.
  2. Transcode. Anything else — HEIC, DNG, a panorama, a larger JPEG — is decoded, shrunk and re-encoded once by a memoized function, so a rebuilt page reuses the result.

thumbnail and mosaic are the same transcode for a value that leaves the page, such as an interceptor's _metadata._thumbnail.

THUMBNAIL_AXIS = 320 module-attribute #

The longest side of a thumbnail, in pixels, and the side of a mosaic.

mosaic(images, side=2) #

side × side of images, spread evenly through them, tiled into one thumbnail.

Each tile is cropped square; fewer images than tiles leave the last tiles blank.

Parameters:

Name Type Description Default
images Array[Picture]

The pictures to choose from, in order; Missing ones are skipped.

required
side int

How many tiles across and down.

2

Raises:

Type Description
ValueError

If images holds no picture.

Source code in capturegraph-ui/capturegraph_ui/viewers/web_image.py
@cg.pure_function("cgui.mosaic/1")
def mosaic[Picture: cg.StillImageFile](
    images: cg.Array[Picture],
    side: int = 2,
) -> cg.Thumbnail:
    """``side`` × ``side`` of ``images``, spread evenly through them, tiled into one thumbnail.

    Each tile is cropped square; fewer images than tiles leave the last tiles blank.

    Args:
        images: The pictures to choose from, in order; ``Missing`` ones are skipped.
        side: How many tiles across and down.

    Raises:
        ValueError: If ``images`` holds no picture.
    """
    present = [image for image in images if not cg.is_missing(image)]
    if not present:
        raise ValueError("a mosaic needs at least one picture")
    count = min(side * side, len(present))
    picks = [round(slot * (len(present) - 1) / max(count - 1, 1)) for slot in range(count)]
    cell = THUMBNAIL_AXIS // side
    canvas = Image.new("RGB", (cell * side, cell * side), "white")
    for slot, index in enumerate(picks):
        with thumbnail(present[index]).pil() as picture:
            tile = ImageOps.fit(picture.convert("RGB"), (cell, cell))
        canvas.paste(tile, (slot % side * cell, slot // side * cell))
    small = cg.Thumbnail.new()
    canvas.save(small, quality=80)
    return small

thumbnail(image) #

A JPEG preview of image, its longest side THUMBNAIL_AXIS pixels.

@cgserver.intercept(Survey, lambda s: s.sessions.for_each()._metadata._thumbnail)
def session_thumbnail(node: Session) -> cg.Thumbnail:
    return cgui.thumbnail(node.photo)
Source code in capturegraph-ui/capturegraph_ui/viewers/web_image.py
@cg.pure_function("cgui.thumbnail/1")
def thumbnail(image: cg.StillImageFile) -> cg.Thumbnail:
    """A JPEG preview of ``image``, its longest side ``THUMBNAIL_AXIS`` pixels.

    ```python
    @cgserver.intercept(Survey, lambda s: s.sessions.for_each()._metadata._thumbnail)
    def session_thumbnail(node: Session) -> cg.Thumbnail:
        return cgui.thumbnail(node.photo)
    ```
    """
    small = cg.Thumbnail.new()
    _shrunk(image, THUMBNAIL_AXIS).save(small, quality=80)
    return small

web_image(image, max_axis) #

image as a JPEG whose longest side is at most max_axis pixels.

Parameters:

Name Type Description Default
image StillImageFile

Any still image.

required
max_axis int

The longest side to show, in pixels.

required

Returns:

Type Description
StillImageFile

image itself when it is a JPEG within max_axis, else its transcode.

Source code in capturegraph-ui/capturegraph_ui/viewers/web_image.py
def web_image(
    image: cg.StillImageFile,
    max_axis: int,
) -> cg.StillImageFile:
    """``image`` as a JPEG whose longest side is at most ``max_axis`` pixels.

    Args:
        image: Any still image.
        max_axis: The longest side to show, in pixels.

    Returns:
        ``image`` itself when it is a JPEG within ``max_axis``, else its transcode.
    """
    if image.kind() == "jpeg":
        with Image.open(image) as opened:
            if max(opened.size) <= max_axis:
                return image
    if max_axis == THUMBNAIL_AXIS:
        return thumbnail(image)
    return web_jpeg(image, max_axis)

web_images(images, max_axis) #

Each of images as web_image makes it, transcoded in parallel.

An image that cannot be decoded comes back Missing.

Source code in capturegraph-ui/capturegraph_ui/viewers/web_image.py
def web_images(
    images: list[cg.StillImageFile],
    max_axis: int,
) -> list[cg.StillImageFile]:
    """Each of ``images`` as ``web_image`` makes it, transcoded in parallel.

    An image that cannot be decoded comes back ``Missing``.
    """
    return list(
        cg.Array(images).pmap(
            lambda image: web_image(image, max_axis),
            label="Pictures",
            on_error="missing",
        )
    )

web_jpeg(image, max_axis) #

image re-encoded as a JPEG, its longest side shrunk to max_axis pixels.

Source code in capturegraph-ui/capturegraph_ui/viewers/web_image.py
@cg.pure_function("cgui.web_jpeg/1")
def web_jpeg(
    image: cg.StillImageFile,
    max_axis: int,
) -> cg.Image:
    """``image`` re-encoded as a JPEG, its longest side shrunk to ``max_axis`` pixels."""
    jpeg = cg.Image.new("jpeg")
    _shrunk(image, max_axis).save(jpeg, quality=88)
    return jpeg