haybale-image 0.3.2__py3-none-any.whl

haybale_image/OVERVIEW.md

@@ -0,0 +1,30 @@
+# Image
+
+Image types, IO and viewers shared by vision and ML libraries
+
+## Nodes
+### Image
+- **Image Info** — Reports the width, height, channel layout and bit depth of an image
+- **Load Image** — Reads an image file from a volume
+- **Save Image** — Writes an image to a file in a volume, in the format its extension names
+- **View Image** — Shows an image on the node, as a live stream or as a still picture
+
+## Types
+- **Gray image** — A one-channel picture.
+- **Image** — A picture of any channel layout. Pixels are kept as made and converted on demand.
+- **RGB image** — A three-channel picture.
+- **RGBA image** — A picture with three colour channels and transparency.
+
+## Adapters
+- **ImageToGrayAdapter** — Convert an image to gray
+- **ImageToRgbAdapter** — Convert an image to RGB
+- **ImageToRgbaAdapter** — Convert an image to RGBA
+
+## Widgets
+- **ImageViewerWidget** — Shows an image, as a live stream or as a still picture
+
+## Settings
+- **Image** — Defaults for saving images
+
+## Panels
+- **Image** — Defaults for saving images.

haybale_image/QUICKREF.md

@@ -0,0 +1,27 @@
+# haybale-image — component index (v0.3.2)
+
+## node
+- `haybale-image:node:ImageInfoNode` — Image Info — Reports the width, height, channel layout and bit depth of an image  _tags: image, info, size, width, height, layout, depth, channels_
+- `haybale-image:node:LoadImageNode` — Load Image — Reads an image file from a volume  _tags: image, load, open, read, file, png, jpg, tiff, import_
+- `haybale-image:node:SaveImageNode` — Save Image — Writes an image to a file in a volume, in the format its extension names  _tags: image, save, write, export, file, png, jpg, tiff, webp_
+- `haybale-image:node:ViewImageNode` — View Image — Shows an image on the node, as a live stream or as a still picture  _tags: image, view, show, preview, display, viewer, stream_
+
+## type
+- `haybale-image:type:IMAGE` — Image — A picture of any channel layout. Pixels are kept as made and converted on demand.
+- `haybale-image:type:IMAGE_GRAY` — Gray image — A one-channel picture.
+- `haybale-image:type:IMAGE_RGB` — RGB image — A three-channel picture.
+- `haybale-image:type:IMAGE_RGBA` — RGBA image — A picture with three colour channels and transparency.
+
+## adapter
+- `haybale-image:adapter:ImageToGrayAdapter` — ImageToGrayAdapter — Convert an image to gray
+- `haybale-image:adapter:ImageToRgbAdapter` — ImageToRgbAdapter — Convert an image to RGB
+- `haybale-image:adapter:ImageToRgbaAdapter` — ImageToRgbaAdapter — Convert an image to RGBA
+
+## widget
+- `haybale-image:widget:ImageViewerWidget` — ImageViewerWidget — Shows an image, as a live stream or as a still picture
+
+## setting
+- `haybale-image:setting:ImageSettings` — Image — Defaults for saving images
+
+## panel
+- `haybale-image:panel:ImageSettingsPanel` — Image — Defaults for saving images.

haybale_image/__init__.py

@@ -0,0 +1,43 @@
+"""Haybale-Image: image values shared by vision and ML libraries.
+
+Provides:
+  - ImageValue (``haybale_image.value``): an image with fixed semantics (RGB order,
+    values in [0, 1], layout, source depth) and free storage (dtype, channel order,
+    numpy array or torch tensor on any device), reached only through accessors.
+
+Component folders (registered in ``register_components``):
+  - ``settings``, ``types``, ``adapters``, ``widgets``, ``nodes``, ``panels``: the IMAGE types,
+    adapters, widgets, IO nodes and the library settings panel.
+"""
+
+from pathlib import Path
+
+from haywire.core.library.base import BaseLibrary
+from haywire.core.library.decorator import library
+from haywire.core.settings.registry import SettingsRegistry
+from haywire.core.adapter.registry import AdapterRegistry
+from haywire.core.node.registry import NodeRegistry
+from haywire.core.types.registry import TypeRegistry
+from haywire.ui.panel.registry import PanelRegistry
+from haywire.ui.widget.registry import WidgetRegistry
+
+
+@library(
+    file_watcher=True,
+)
+class Library(BaseLibrary):
+    """Image library — image values, types and IO."""
+
+    def register_components(self):
+        """Register the component folders with their registries."""
+        base_path = Path(__file__).parent
+
+        self.add_folder_to_registry(folder_path=str(base_path / "settings"), registry_cls=SettingsRegistry)
+        self.add_folder_to_registry(folder_path=str(base_path / "types"), registry_cls=TypeRegistry)
+        self.add_folder_to_registry(folder_path=str(base_path / "adapters"), registry_cls=AdapterRegistry)
+        self.add_folder_to_registry(folder_path=str(base_path / "widgets"), registry_cls=WidgetRegistry)
+        self.add_folder_to_registry(folder_path=str(base_path / "nodes"), registry_cls=NodeRegistry)
+        self.add_folder_to_registry(folder_path=str(base_path / "panels"), registry_cls=PanelRegistry)
+
+    def validate(self) -> bool:
+        return True

haybale_image/adapters/image_adapters.py

@@ -0,0 +1,51 @@
+"""Layout adapters: any image to a gray, RGB or RGBA image."""
+
+from typing_extensions import override
+
+from haywire.core.adapter.base import BaseAdapter, adapter
+
+from haybale_image.types.image import IMAGE, IMAGE_GRAY, IMAGE_RGB, IMAGE_RGBA
+from haybale_image.value import ImageValue, Layout, convert_layout
+
+
+def _sample(layout: Layout) -> ImageValue:
+    import numpy as np
+
+    channels = {Layout.GRAY: (), Layout.RGB: (3,), Layout.RGBA: (4,)}[layout]
+    return ImageValue.from_array(np.zeros((2, 2, *channels), dtype=np.uint8))
+
+
+@adapter(description="Convert an image to gray", converts_from=IMAGE, converts_to=IMAGE_GRAY)
+class ImageToGrayAdapter(BaseAdapter):
+    """Convert an image to one gray channel (luma of the colour channels)."""
+
+    @override
+    def convert(self, value: ImageValue) -> ImageValue:
+        return convert_layout(value, Layout.GRAY)
+
+    def get_test_value(self) -> ImageValue:
+        return _sample(Layout.RGB)
+
+
+@adapter(description="Convert an image to RGB", converts_from=IMAGE, converts_to=IMAGE_RGB)
+class ImageToRgbAdapter(BaseAdapter):
+    """Convert an image to three colour channels, dropping transparency or repeating gray."""
+
+    @override
+    def convert(self, value: ImageValue) -> ImageValue:
+        return convert_layout(value, Layout.RGB)
+
+    def get_test_value(self) -> ImageValue:
+        return _sample(Layout.GRAY)
+
+
+@adapter(description="Convert an image to RGBA", converts_from=IMAGE, converts_to=IMAGE_RGBA)
+class ImageToRgbaAdapter(BaseAdapter):
+    """Convert an image to colour plus transparency, fully opaque when it had none."""
+
+    @override
+    def convert(self, value: ImageValue) -> ImageValue:
+        return convert_layout(value, Layout.RGBA)
+
+    def get_test_value(self) -> ImageValue:
+        return _sample(Layout.RGB)

haybale_image/docs/haybale-image.adapter.ImageToGrayAdapter.md

@@ -0,0 +1,15 @@
+# ImageToGrayAdapter
+
+`haybale-image:adapter:ImageToGrayAdapter` · kind: adapter
+
+Convert an image to gray
+
+## Details
+
+- **converts_from**: `haybale-image:type:IMAGE`
+- **converts_to**: `haybale-image:type:IMAGE_GRAY`
+- **priority**: `0`
+
+## Notes
+
+Convert an image to one gray channel (luma of the colour channels).

haybale_image/docs/haybale-image.adapter.ImageToRgbAdapter.md

@@ -0,0 +1,15 @@
+# ImageToRgbAdapter
+
+`haybale-image:adapter:ImageToRgbAdapter` · kind: adapter
+
+Convert an image to RGB
+
+## Details
+
+- **converts_from**: `haybale-image:type:IMAGE`
+- **converts_to**: `haybale-image:type:IMAGE_RGB`
+- **priority**: `0`
+
+## Notes
+
+Convert an image to three colour channels, dropping transparency or repeating gray.

haybale_image/docs/haybale-image.adapter.ImageToRgbaAdapter.md

@@ -0,0 +1,15 @@
+# ImageToRgbaAdapter
+
+`haybale-image:adapter:ImageToRgbaAdapter` · kind: adapter
+
+Convert an image to RGBA
+
+## Details
+
+- **converts_from**: `haybale-image:type:IMAGE`
+- **converts_to**: `haybale-image:type:IMAGE_RGBA`
+- **priority**: `0`
+
+## Notes
+
+Convert an image to colour plus transparency, fully opaque when it had none.

haybale_image/docs/haybale-image.node.ImageInfoNode.md

@@ -0,0 +1,23 @@
+# Image Info
+
+`haybale-image:node:ImageInfoNode` · kind: node
+
+Reports the width, height, channel layout and bit depth of an image
+
+## Ports
+
+| id | direction | type | description |
+|---|---|---|---|
+| `image` | inlet | `haybale-image:type:IMAGE` | Image to describe |
+| `width` | outlet | `haywire-core:type:INT` | Width in pixels |
+| `height` | outlet | `haywire-core:type:INT` | Height in pixels |
+| `layout` | outlet | `haywire-core:type:STRING` | Channels: gray, rgb or rgba |
+| `depth` | outlet | `haywire-core:type:INT` | Bits per channel of the source file, such as 8 or 16 |
+
+## Notes
+
+Reports the width, height, channel layout and bit depth of an `Image`.
+
+- `Width`, `Height`: size in pixels.
+- `Layout`: `gray`, `rgb` or `rgba`.
+- `Depth`: bits per channel of the file the image was read from (8, 16 or 32).

haybale_image/docs/haybale-image.node.LoadImageNode.md

@@ -0,0 +1,37 @@
+# Load Image
+
+`haybale-image:node:LoadImageNode` · kind: node
+
+Reads an image file from a volume
+
+## Ports
+
+| id | direction | type | description |
+|---|---|---|---|
+| `path` | inlet | `haywire-core:type:FILE_PATH` | Image file to read |
+| `progress.main` | config | `haywire-core:type:PROGRESS` |  |
+| `image` | outlet | `haybale-image:type:IMAGE` | The decoded image |
+
+## Settings
+
+| name | bag | default | description |
+|---|---|---|---|
+| `main` | progress | `PROGRESS(active=False, fraction=None, label='')` |  |
+
+## Notes
+
+Reads an image file from a volume into an `Image`.
+
+Gray files stay gray, files with transparency become RGBA and everything else
+is RGB. The camera's rotation (EXIF orientation) is applied to the pixels on
+load, because OpenCV's reader ignores it.
+16-bit and float files are read at full precision; see Image Info's `Depth`.
+
+The Loading bar shows while the file is read and decoded.
+
+The node reports an error naming the file when it is missing or is not an
+image, and when `Path` leads to a volume that is not defined on this machine.
+
+```
+For Each File → Load Image → Image Info
+```

haybale_image/docs/haybale-image.node.SaveImageNode.md

@@ -0,0 +1,63 @@
+# Save Image
+
+`haybale-image:node:SaveImageNode` · kind: node
+
+Writes an image to a file in a volume, in the format its extension names
+
+## Ports
+
+| id | direction | type | description |
+|---|---|---|---|
+| `exec` | inlet | `haywire-core:type:EXEC` | Saves the image |
+| `image` | inlet | `haybale-image:type:IMAGE` | Image to save |
+| `path` | inlet | `haywire-core:type:FILE_PATH` | File to write; its extension picks the format |
+| `if_exists` | config | `haywire-core:type:STRING` | When the file exists: overwrite, skip, or unique-suffix (adds a number) |
+| `depth` | config | `haywire-core:type:STRING` | Bits per channel: source keeps the image's own, or 8, 16, 32 |
+| `progress.main` | config | `haywire-core:type:PROGRESS` |  |
+| `next` | outlet | `haywire-core:type:EXEC` | Runs after saving |
+| `saved` | outlet | `haywire-core:type:FILE_PATH` | The file written, or the one skipped |
+
+## Settings
+
+| name | bag | default | description |
+|---|---|---|---|
+| `compression` | png | `None` | Compression of saved PNG files, from 0 (fastest) to 9 (smallest); never loses detail |
+| `quality` | jpeg | `None` | Quality of saved JPEG files, from 0 (smallest) to 100 (best) |
+| `quality` | webp | `None` | Quality of saved WebP files, from 0 (smallest) to 100 (best) |
+| `lossless` | webp | `None` | Save WebP files without losing detail; WebP quality is then ignored |
+| `compression` | tiff | `None` | Compression of saved TIFF files; none of them loses detail |
+| `quality` | avif | `None` | Quality of saved AVIF files, from 0 (smallest) to 100 (best) |
+| `main` | progress | `PROGRESS(active=False, fraction=None, label='')` |  |
+
+## Notes
+
+Writes `Image` to the file at `Path`, in the format its extension names.
+
+Known extensions: `.png`, `.jpg`/`.jpeg`, `.webp`, `.tif`/`.tiff`, `.bmp`, `.gif`,
+`.tga`, `.avif`. The file appears complete or not at all; a half-written file is
+never left behind.
+
+- `If Exists`: what to do when the file is already there. `overwrite` replaces
+  it, `skip` keeps it and writes nothing, `unique-suffix` saves beside it as
+  `name_1.png`, `name_2.png`, and so on.
+- `Depth`: `source` keeps the image's own bit depth; `8`, `16` and `32` (float)
+  ask for that depth. A format that cannot store it gets the deepest it can
+  (JPEG is always 8-bit, PNG at most 16-bit). 16-bit and float saves drop the
+  image's ICC profile and EXIF block.
+
+`Saved` is the file that now holds the image: the suffixed name for
+`unique-suffix`, and the existing file for `skip`.
+
+The quality and compression settings default to the library's *Image* settings;
+change them here for this node only. Only the settings of the format `Path` names
+are shown.
+
+The Saving bar shows while the file is encoded and written.
+
+The folder must already exist; add Create Folder before Save Image to make it.
+An empty image, an unknown extension and a volume that is not defined on this
+machine are reported as errors.
+
+```text
+For Each File → Load Image → … → Save Image (Path = Output Path)
+```

haybale_image/docs/haybale-image.node.ViewImageNode.md

@@ -0,0 +1,40 @@
+# View Image
+
+`haybale-image:node:ViewImageNode` · kind: node
+
+Shows an image on the node, as a live stream or as a still picture
+
+## Ports
+
+| id | direction | type | description |
+|---|---|---|---|
+| `exec` | inlet | `haywire-core:type:EXEC` | Shows the image |
+| `image` | inlet | `haybale-image:type:IMAGE` | Image to show |
+| `next` | outlet | `haywire-core:type:EXEC` | Runs after showing |
+| `image_out` | outlet | `haybale-image:type:IMAGE` | The same image, passed on |
+
+## Settings
+
+| name | bag | default | description |
+|---|---|---|---|
+| `mode` | viewer | `'still'` | stream for images that change often (a camera); still for large, rarely changing ones |
+| `enlarge` | viewer | `3.0` | How many times wider the view gets when a still image is clicked |
+| `zoom` | viewer | `1.0` | How many times the enlarged view's width the image shows; 1 fits it |
+
+## Notes
+
+Shows `Image` on the node and passes it on to `Image Out`.
+
+- `Mode`: `stream` for images that change many times a second, such as a camera;
+  `still` for large images that change rarely, such as a loaded file. A still
+  image keeps its transparency.
+
+Click a still image to enlarge the view: it gets `Enlarge view` times wider and
+takes the image's shape, and the image shows `Zoom image` times the view's width
+(1 fits it). Drag inside it to move around the image; click again to go back.
+
+The view appears once `Image` is connected.
+
+```text
+Load Image → View Image (Mode = still)
+```

haybale_image/docs/haybale-image.panel.ImageSettingsPanel.md

@@ -0,0 +1,14 @@
+# Image
+
+`haybale-image:panel:ImageSettingsPanel` · kind: panel
+
+Defaults for saving images.
+
+## Details
+
+- **surface**: `barns`
+- **order**: `10`
+
+## Notes
+
+Defaults for saving images; each Save Image node can override them.

haybale_image/docs/haybale-image.setting.ImageSettings.md

@@ -0,0 +1,9 @@
+# Image
+
+`haybale-image:setting:ImageSettings` · kind: setting
+
+Defaults for saving images
+
+## Notes
+
+Defaults for saving images; each Save Image node can override them.

haybale_image/docs/haybale-image.type.IMAGE.md

@@ -0,0 +1,15 @@
+# Image
+
+`haybale-image:type:IMAGE` · kind: type
+
+A picture of any channel layout. Pixels are kept as made and converted on demand.
+
+## Details
+
+- **wire_type**: `haywire-core:wire:DataWire`
+- **default**: `{'value': {'width': 0, 'height': 0, 'layout': 'gray'}}`
+- **color**: `#3f8fd2`
+
+## Notes
+
+A picture of any channel layout; the value is never saved with the graph.

haybale_image/docs/haybale-image.type.IMAGE_GRAY.md

@@ -0,0 +1,15 @@
+# Gray image
+
+`haybale-image:type:IMAGE_GRAY` · kind: type
+
+A one-channel picture.
+
+## Details
+
+- **wire_type**: `haywire-core:wire:DataWire`
+- **default**: `{'value': {'width': 0, 'height': 0, 'layout': 'gray'}}`
+- **color**: `#3f8fd2`
+
+## Notes
+
+A one-channel picture.

haybale_image/docs/haybale-image.type.IMAGE_RGB.md

@@ -0,0 +1,15 @@
+# RGB image
+
+`haybale-image:type:IMAGE_RGB` · kind: type
+
+A three-channel picture.
+
+## Details
+
+- **wire_type**: `haywire-core:wire:DataWire`
+- **default**: `{'value': {'width': 0, 'height': 0, 'layout': 'rgb'}}`
+- **color**: `#3f8fd2`
+
+## Notes
+
+A three-channel picture.

haybale_image/docs/haybale-image.type.IMAGE_RGBA.md

@@ -0,0 +1,15 @@
+# RGBA image
+
+`haybale-image:type:IMAGE_RGBA` · kind: type
+
+A picture with three colour channels and transparency.
+
+## Details
+
+- **wire_type**: `haywire-core:wire:DataWire`
+- **default**: `{'value': {'width': 0, 'height': 0, 'layout': 'rgba'}}`
+- **color**: `#3f8fd2`
+
+## Notes
+
+A picture with three colour channels and transparency.

haybale_image/docs/haybale-image.widget.ImageViewerWidget.md

@@ -0,0 +1,37 @@
+# ImageViewerWidget
+
+`haybale-image:widget:ImageViewerWidget` · kind: widget
+
+Shows an image, as a live stream or as a still picture
+
+## Details
+
+- **min_width**: `160`
+
+## Notes
+
+Shows the port's image.
+
+Properties (`ImageViewerWidget.config(properties={...})`):
+
+- `mode`: `stream` (default) sends every image as JPEG, for images that change
+  many times a second; `still` sends the image as PNG only when the view asks for
+  it, for large images that change rarely. Click a still image to enlarge the
+  view; click again to fit it.
+- `quality`: JPEG quality in `stream` mode, 0 to 100 (default `80`).
+- `enlarge`: in `still` mode, how many times wider the view gets on a click; its
+  height follows the image's shape (default `2`).
+- `zoom`: how many times the enlarged view's width the image shows (default `2`;
+  `1` fits it); drag inside it to move around the image.
+- `frame_width`: CSS width of a border around the view (default `0`, none).
+- `frame_color`: CSS color of that border (default `var(--hw-border)`).
+
+`stream` shows nothing until the view is open, and RGBA images lose their
+transparency. `still` keeps transparency and shows 8 bits per channel.
+
+```python
+self.add(IMAGE.as_inlet(
+    "image",
+    widget=ImageViewerWidget.config(properties={"mode": "still"}),
+))
+```

haybale_image/haybale.toml

@@ -0,0 +1,13 @@
+# Library metadata. Canon for everything descriptive about this haybale;
+# ships in the wheel beside __init__.py and is read from disk at runtime.
+# Edited in the studio's library overview — no reinstall, no reload.
+
+name = "haybale-image"
+version = "0.3.2"
+label = "Image"
+description = "Image types, IO and viewers shared by vision and ML libraries"
+tags = ["image"]
+
+# Sibling haybales this library subscribes to, as MODULE names.
+# Required for hot-reload scope tracking.
+linked_libraries = []

haybale_image/helpers.py

@@ -0,0 +1,110 @@
+"""Conversions between ``ImageValue`` and PIL / OpenCV BGR arrays, and alpha premultiplication."""
+
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image
+
+from haybale_image.value import NO_METADATA, ChannelOrder, ImageMetadata, ImageValue, Layout
+
+
+def from_pil(im: Image.Image, metadata: ImageMetadata = NO_METADATA) -> ImageValue:
+    """Wrap a PIL image as an ``ImageValue``.
+
+    Args:
+        im: Any PIL image. Gray modes stay gray, ``LA`` and transparent ``P`` become
+            RGBA, ``CMYK``/``YCbCr`` and unknown modes are converted to RGB(A).
+        metadata: ICC and EXIF blocks to carry with the image.
+
+    Returns:
+        The image; 16-bit and float sources record ``source_depth`` 16 / 32.
+    """
+    mode = im.mode
+    if mode == "1":
+        return ImageValue.from_array(np.asarray(im.convert("L")), metadata=metadata)
+    if mode == "L":
+        return ImageValue.from_array(np.asarray(im), metadata=metadata)
+    if mode == "LA":
+        la = np.asarray(im)
+        rgba = np.concatenate([np.repeat(la[..., :1], 3, axis=2), la[..., 1:]], axis=2)
+        return ImageValue.from_array(rgba, metadata=metadata)
+    if mode == "P":
+        target = "RGBA" if "transparency" in im.info else "RGB"
+        return ImageValue.from_array(np.asarray(im.convert(target)), metadata=metadata)
+    if mode in ("RGB", "RGBA"):
+        return ImageValue.from_array(np.asarray(im), metadata=metadata)
+    if mode in ("CMYK", "YCbCr"):
+        return ImageValue.from_array(np.asarray(im.convert("RGB")), metadata=metadata)
+    if mode in ("I;16", "I;16L", "I;16B", "I;16N"):
+        # Native byte order explicitly: I;16B arrives as a big-endian view.
+        data = np.asarray(im).astype(np.uint16)
+        return ImageValue.from_array(data, source_depth=16, metadata=metadata)
+    if mode == "I":
+        data = np.clip(np.asarray(im), 0, 65535).astype(np.uint16)
+        return ImageValue.from_array(data, source_depth=16, metadata=metadata)
+    if mode == "F":
+        data = np.asarray(im).astype(np.float32)
+        return ImageValue.from_array(data, source_depth=32, metadata=metadata)
+    target = "RGBA" if "A" in im.getbands() else "RGB"
+    return ImageValue.from_array(np.asarray(im.convert(target)), metadata=metadata)
+
+
+def to_pil(img: ImageValue, depth: int = 8) -> Image.Image:
+    """Convert an ``ImageValue`` to a PIL image.
+
+    Args:
+        img: The image.
+        depth: Bit depth for gray images: 8 (``L``), 16 (``I;16``) or 32 (``F``).
+            Ignored for RGB and RGBA, which are always 8-bit (Pillow has no
+            16-bit RGB; use OpenCV for that).
+
+    Raises:
+        ValueError: ``depth`` is not 8, 16 or 32.
+    """
+    if depth not in (8, 16, 32):
+        raise ValueError(f"depth must be 8, 16 or 32, got {depth}")
+    if img.layout is Layout.GRAY:
+        dtype = {8: np.uint8, 16: np.uint16, 32: np.float32}[depth]
+        return Image.fromarray(np.ascontiguousarray(img.array(dtype)))
+    return Image.fromarray(np.ascontiguousarray(img.array(np.uint8)))
+
+
+def from_cv_bgr(
+    a: np.ndarray, metadata: ImageMetadata = NO_METADATA, source_depth: int | None = None
+) -> ImageValue:
+    """Wrap an OpenCV ``H×W×3``/``H×W×4`` BGR(A) (or gray) array without copying."""
+    return ImageValue.from_array(a, order=ChannelOrder.BGR, source_depth=source_depth, metadata=metadata)
+
+
+def to_cv_bgr(img: ImageValue, dtype: type[np.generic] = np.uint8) -> np.ndarray:
+    """Return the pixels as a BGR(A) array of ``dtype`` (a view when storage allows)."""
+    return img.array(dtype, ChannelOrder.BGR)
+
+
+def premultiply(img: ImageValue) -> np.ndarray:
+    """Return float32 ``H×W×4`` RGB-order pixels with colour multiplied by alpha.
+
+    Raises:
+        ValueError: ``img`` is not RGBA.
+    """
+    if img.layout is not Layout.RGBA:
+        raise ValueError(f"premultiply needs an RGBA image, got {img.layout.name}")
+    out = np.array(img.array(np.float32), dtype=np.float32, copy=True)
+    out[..., :3] *= out[..., 3:4]
+    return out
+
+
+def unpremultiply(rgba: np.ndarray) -> np.ndarray:
+    """Divide colour by alpha (float32 ``H×W×4``); alpha-0 pixels become 0.
+
+    Raises:
+        ValueError: ``rgba`` is not ``H×W×4``.
+    """
+    if rgba.ndim != 3 or rgba.shape[2] != 4:
+        raise ValueError(f"unpremultiply needs an H×W×4 array, got shape {rgba.shape}")
+    out = np.array(rgba, dtype=np.float32, copy=True)
+    alpha = out[..., 3:4]
+    nz = alpha > 0
+    np.divide(out[..., :3], alpha, out=out[..., :3], where=nz)
+    out[..., :3] = np.where(nz, out[..., :3], 0.0)
+    return out

haybale_image/io/__init__.py

@@ -0,0 +1,23 @@
+"""Image file IO: formats by extension and the codecs that read and write them."""
+
+from haybale_image.io.codecs import EncodeOptions, encode_image, read_image
+from haybale_image.io.formats import (
+    DEPTHS,
+    FORMAT_BY_EXTENSION,
+    HOLDS_METADATA,
+    Format,
+    best_depth,
+    format_for,
+)
+
+__all__ = [
+    "DEPTHS",
+    "FORMAT_BY_EXTENSION",
+    "HOLDS_METADATA",
+    "EncodeOptions",
+    "Format",
+    "best_depth",
+    "encode_image",
+    "format_for",
+    "read_image",
+]