walsh 0.1.1__py3-none-any.whl

walsh/__init__.py

@@ -0,0 +1,43 @@
+"""Image compression with the Walsh-Hadamard transform.
+
+Typical use::
+
+    from walsh import Task
+
+    Task().with_action("compress").with_input("image.bmp").with_output("out.cim").run()
+    Task().with_action("extract").with_input("out.cim").with_output("back.bmp").run()
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from walsh.colors import ColorModel, RgbColorModel, YCbCrColorModel
+from walsh.image import (
+    BlockDescription,
+    BMPImage,
+    CustomizableImage,
+    UnsupportedFileFormatError,
+)
+from walsh.task import Action, Task
+from walsh.transforms import Transform, WalshHadamardTransform
+
+try:
+    __version__ = version("walsh")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "Action",
+    "BMPImage",
+    "BlockDescription",
+    "ColorModel",
+    "CustomizableImage",
+    "RgbColorModel",
+    "Task",
+    "Transform",
+    "UnsupportedFileFormatError",
+    "WalshHadamardTransform",
+    "YCbCrColorModel",
+    "__version__",
+]

walsh/cli.py

@@ -0,0 +1,104 @@
+"""Command line interface: ``walsh compress`` / ``walsh extract``."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from collections.abc import Sequence
+
+from walsh import __version__
+from walsh.image import UnsupportedFileFormatError
+from walsh.task import (
+    DEFAULT_CHROMA_BLOCK_SIZE,
+    DEFAULT_PACKED_BLOCK_SIZE,
+    DEFAULT_Y_BLOCK_SIZE,
+    Action,
+    Task,
+)
+
+__all__ = ["build_parser", "main"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="walsh",
+        description="Compress and restore images with the Walsh-Hadamard transform.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="increase log verbosity (repeat for debug output)",
+    )
+
+    subparsers = parser.add_subparsers(dest="action", required=True)
+
+    compress = subparsers.add_parser(
+        Action.COMPRESS.value, help="transform a 24-bit BMP into a .cim file"
+    )
+    compress.add_argument("input", help="path to a 24-bit uncompressed BMP")
+    compress.add_argument("output", help="path of the .cim file to write")
+    compress.add_argument(
+        "--y-block-size",
+        type=int,
+        default=DEFAULT_Y_BLOCK_SIZE,
+        help="luma block edge (default: %(default)s)",
+    )
+    compress.add_argument(
+        "--chroma-block-size",
+        type=int,
+        default=DEFAULT_CHROMA_BLOCK_SIZE,
+        help="Cb/Cr block edge (default: %(default)s)",
+    )
+    compress.add_argument(
+        "--packed-block-size",
+        type=int,
+        default=DEFAULT_PACKED_BLOCK_SIZE,
+        help="coefficients kept per axis; lower means smaller and lossier (default: %(default)s)",
+    )
+    compress.add_argument(
+        "--coeff-removal",
+        type=float,
+        default=None,
+        help="zero Hadamard matrix entries at or below this threshold",
+    )
+
+    extract = subparsers.add_parser(Action.EXTRACT.value, help="restore a BMP from a .cim file")
+    extract.add_argument("input", help="path to a .cim file")
+    extract.add_argument("output", help="path of the BMP to write")
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    level = logging.WARNING - min(args.verbose, 2) * 10
+    logging.basicConfig(level=level, format="%(levelname)s %(name)s: %(message)s")
+
+    action = Action(args.action)
+    if action is Action.COMPRESS:
+        task = Task(
+            y_block_size=args.y_block_size,
+            cb_block_size=args.chroma_block_size,
+            cr_block_size=args.chroma_block_size,
+            packed_block_size=args.packed_block_size,
+        ).with_coeff_removal(args.coeff_removal)
+    else:
+        task = Task()
+
+    task.with_action(action).with_input(args.input).with_output(args.output)
+
+    try:
+        task.run()
+    except (OSError, UnsupportedFileFormatError, ValueError) as error:
+        print(f"walsh: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

walsh/colors.py

@@ -0,0 +1,63 @@
+"""Colour model conversions between RGB and YCbCr."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+__all__ = ["ColorModel", "Rgb", "RgbColorModel", "Triple", "YCbCrColorModel"]
+
+#: A pixel as three numbers, in whatever model the class in question uses.
+Triple = tuple[float, float, float]
+
+#: A pixel as three 0-255 integers.
+Rgb = tuple[int, int, int]
+
+
+class ColorModel(ABC):
+    """Converts a single pixel between its native model and RGB/YCbCr."""
+
+    @abstractmethod
+    def get_rgb(self, color: Triple) -> Rgb:
+        """Return ``color`` as an ``(r, g, b)`` triple of 0-255 ints."""
+
+    @abstractmethod
+    def get_y_cb_cr(self, color: Triple) -> Triple:
+        """Return ``color`` as a ``(y, cb, cr)`` triple."""
+
+
+class RgbColorModel(ColorModel):
+    """Pixels stored as RGB."""
+
+    def get_rgb(self, color: Triple) -> Rgb:
+        return _as_rgb(*color)
+
+    def get_y_cb_cr(self, color: Triple) -> Triple:
+        r, g, b = color
+        y = 0.299 * r + 0.587 * g + 0.114 * b
+        cb = 128 - 0.168736 * r - 0.331264 * g + 0.5 * b
+        cr = 128 + 0.5 * r - 0.418688 * g - 0.081312 * b
+        return y, cb, cr
+
+
+class YCbCrColorModel(ColorModel):
+    """Pixels stored as YCbCr."""
+
+    def get_rgb(self, color: Triple) -> Rgb:
+        y, cb, cr = color
+        return _as_rgb(
+            y + 1.402 * (cr - 128),
+            y - 0.34414 * (cb - 128) - 0.71414 * (cr - 128),
+            y + 1.772 * (cb - 128),
+        )
+
+    def get_y_cb_cr(self, color: Triple) -> Triple:
+        return color
+
+
+def _as_rgb(r: float, g: float, b: float) -> Rgb:
+    """Truncate towards zero and clamp each channel into the 0-255 range."""
+    return _clamp(int(r)), _clamp(int(g)), _clamp(int(b))
+
+
+def _clamp(value: int, low: int = 0, high: int = 255) -> int:
+    return max(low, min(high, value))

walsh/decorators.py

@@ -0,0 +1,57 @@
+"""Small caching helper used to memoise expensive matrix construction."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable, Hashable
+from typing import Any, ParamSpec, TypeVar
+
+__all__ = ["cached"]
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+#: Separates positional from keyword arguments in a cache key. Must be a module
+#: level constant: a fresh marker per call would make every lookup miss.
+_KWARGS_MARKER = object()
+
+
+def _hashable(value: Any) -> Hashable:
+    """Return ``value`` if it can be used as a dict key, else its ``repr``."""
+    if isinstance(value, Hashable):
+        return value
+    return repr(value)
+
+
+def _make_key(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Hashable:
+    key: tuple[Hashable, ...] = tuple(_hashable(a) for a in args)
+    if kwargs:
+        key = (
+            *key,
+            _KWARGS_MARKER,
+            *((name, _hashable(value)) for name, value in sorted(kwargs.items())),
+        )
+    return key
+
+
+def cached(function: Callable[P, R]) -> Callable[P, R]:
+    """Memoise ``function`` on its arguments, tolerating unhashable ones.
+
+    Unlike :func:`functools.lru_cache` this accepts unhashable arguments by
+    falling back to their ``repr``, which is what the numpy-heavy call sites
+    here need. The cache is unbounded and lives for the life of the process.
+    """
+    cache: dict[Hashable, R] = {}
+
+    @functools.wraps(function)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        key = _make_key(args, kwargs)
+        try:
+            return cache[key]
+        except KeyError:
+            result = cache[key] = function(*args, **kwargs)
+            return result
+
+    wrapper.cache_clear = cache.clear  # type: ignore[attr-defined]
+    wrapper.cache_size = lambda: len(cache)  # type: ignore[attr-defined]
+    return wrapper

walsh/image.py

@@ -0,0 +1,312 @@
+"""Container formats: 24-bit BMP in, custom ``.cim`` spectral format out."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import struct
+import sys
+from collections.abc import Generator, Sequence
+from os import PathLike
+from typing import BinaryIO, NamedTuple
+
+import numpy as np
+import numpy.typing as npt
+
+__all__ = [
+    "BMPImage",
+    "BlockDescription",
+    "CustomizableImage",
+    "UnsupportedFileFormatError",
+    "align",
+]
+
+log = logging.getLogger(__name__)
+
+FileSource = str | PathLike[str] | None
+
+Block = npt.NDArray[np.float64]
+Pixel = tuple[int, int, int]
+
+BMP_HEADER_FORMAT = "<2sIHHIIIIHHIIIIII"
+BMP_SIGNATURE = b"BM"
+BMP_HEADER_SIZE = 40
+BMP_PIXEL_OFFSET = 54
+
+#: Spectral coefficients are stored as little-endian signed 16-bit integers.
+COEFF_DTYPE = np.dtype("<i2")
+COEFF_MIN = np.iinfo(COEFF_DTYPE).min
+COEFF_MAX = np.iinfo(COEFF_DTYPE).max
+
+
+class UnsupportedFileFormatError(Exception):
+    """Raised for BMP files that are not 24-bit, single-plane, uncompressed."""
+
+
+def align(x: int, a: int) -> int:
+    """Round ``x`` up to the next multiple of ``a``."""
+    return (((x - 1) // a) + 1) * a
+
+
+@contextlib.contextmanager
+def _open_binary(source: FileSource, mode: str) -> Generator[BinaryIO, None, None]:
+    """Open ``source``, or fall back to std streams when it is ``None``.
+
+    The std streams are deliberately not closed on exit.
+    """
+    if source is None:
+        yield sys.stdin.buffer if "r" in mode else sys.stdout.buffer
+        return
+    with open(source, mode) as handle:
+        yield handle  # type: ignore[misc]
+
+
+class BMPImage:
+    """A 24-bit uncompressed Windows bitmap.
+
+    .. note::
+       Pixel triples are kept in the order they appear in the file, which for
+       BMP is blue-green-red. Reading and writing use the same order, so a
+       round trip is lossless, but callers that interpret a triple as
+       ``(r, g, b)`` are working with the channels swapped.
+    """
+
+    def __init__(self) -> None:
+        self._signature = BMP_SIGNATURE
+        self._size = 0
+        self._offset = BMP_PIXEL_OFFSET
+        self._header_size = BMP_HEADER_SIZE
+        self._width = 0
+        self._height = 0
+        self._planes = 1
+        self._bpp = 24
+        self._compression = 0
+        self._size_of_data = 0
+        self._horizontal_res = 2835
+        self._vertical_res = 2835
+        self._raw_data: list[Pixel] = []
+
+    def _read_header(self, file: BinaryIO) -> None:
+        header = file.read(struct.calcsize(BMP_HEADER_FORMAT))
+        (
+            self._signature,
+            self._size,
+            _,
+            _,
+            self._offset,
+            self._header_size,
+            self._width,
+            self._height,
+            self._planes,
+            self._bpp,
+            self._compression,
+            self._size_of_data,
+            self._horizontal_res,
+            self._vertical_res,
+            _,
+            _,
+        ) = struct.unpack(BMP_HEADER_FORMAT, header)
+
+        actual = (self._signature, self._planes, self._bpp, self._compression)
+        if actual != (BMP_SIGNATURE, 1, 24, 0):
+            raise UnsupportedFileFormatError(
+                "expected a 24-bit single-plane uncompressed BMP, got "
+                f"signature={self._signature!r} planes={self._planes} "
+                f"bpp={self._bpp} compression={self._compression}"
+            )
+
+    def _read_data(self, file: BinaryIO) -> None:
+        file.seek(self._offset)
+        stride = align(self._width * 3, 4)
+        self._raw_data = []
+        for _ in range(self._height):
+            line = file.read(stride)
+            for i in range(0, self._width * 3, 3):
+                self._raw_data.append(struct.unpack_from("<BBB", line, i))
+
+    def load(self, filename: FileSource) -> None:
+        """Read a BMP from ``filename``, or from stdin when it is ``None``."""
+        with _open_binary(filename, "rb") as file:
+            self._read_header(file)
+            self._read_data(file)
+        log.debug("loaded BMP %dx%d from %s", self._width, self._height, filename)
+
+    def _write_header(self, file: BinaryIO) -> None:
+        ignored = 0
+        file.write(
+            struct.pack(
+                BMP_HEADER_FORMAT,
+                self._signature,
+                self._size,
+                ignored,
+                ignored,
+                self._offset,
+                self._header_size,
+                self._width,
+                self._height,
+                self._planes,
+                self._bpp,
+                self._compression,
+                self._size_of_data,
+                self._horizontal_res,
+                self._vertical_res,
+                ignored,
+                ignored,
+            )
+        )
+
+    def _write_data(self, file: BinaryIO) -> None:
+        padding = align(self._width * 3, 4) - self._width * 3
+        log.debug("row padding: %d byte(s)", padding)
+        pad = b"\x00" * padding
+        for start in range(0, len(self._raw_data), self._width):
+            for pixel in self._raw_data[start : start + self._width]:
+                file.write(struct.pack("<BBB", *pixel))
+            file.write(pad)
+
+    def save(self, filename: FileSource) -> None:
+        """Write this bitmap to ``filename``, or to stdout when it is ``None``."""
+        with _open_binary(filename, "wb") as file:
+            self._write_header(file)
+            self._write_data(file)
+
+    def get_dimensions(self) -> tuple[int, int]:
+        return self._width, self._height
+
+    def set_dimensions(self, width: int, height: int) -> None:
+        self._width = width
+        self._height = height
+        self._size_of_data = width * height * 3
+        self._size = BMP_PIXEL_OFFSET + align(width * 3, 4) * height
+
+    def get_raw_data(self) -> list[Pixel]:
+        return self._raw_data
+
+    def set_raw_data(self, new_data: Sequence[Pixel]) -> None:
+        self._raw_data = list(new_data)
+
+
+class BlockDescription(NamedTuple):
+    """How one channel's blocks are laid out in a ``.cim`` file."""
+
+    original_block_size: int
+    packed_block_size: int
+    number_of_blocks: int
+
+
+class CustomizableImage:
+    """The custom ``.cim`` container holding truncated spectral blocks.
+
+    Layout: ``<II`` width/height, then three ``<HHH`` :class:`BlockDescription`
+    records (Y, Cb, Cr), then each channel's blocks as row-major ``int16``.
+    """
+
+    HEADER_FORMAT = "<II"
+    DESCRIPTION_FORMAT = "<HHH"
+
+    def __init__(self) -> None:
+        self._width = 0
+        self._height = 0
+        self._descriptions: dict[str, BlockDescription | None] = {
+            "y": None,
+            "cb": None,
+            "cr": None,
+        }
+        self._data: dict[str, list[Block]] = {"y": [], "cb": [], "cr": []}
+
+    def _read_header(self, file: BinaryIO) -> None:
+        size = struct.calcsize(self.HEADER_FORMAT)
+        self._width, self._height = struct.unpack(self.HEADER_FORMAT, file.read(size))
+        size = struct.calcsize(self.DESCRIPTION_FORMAT)
+        for channel in self._descriptions:
+            fields = struct.unpack(self.DESCRIPTION_FORMAT, file.read(size))
+            self._descriptions[channel] = BlockDescription(*fields)
+
+    @staticmethod
+    def _read_blocks(file: BinaryIO, description: BlockDescription) -> list[Block]:
+        original, packed, count = description
+        pattern = "<" + "h" * (packed * packed)
+        size = struct.calcsize(pattern)
+
+        blocks = []
+        for _ in range(count):
+            data = struct.unpack(pattern, file.read(size))
+            block = np.zeros((original, original), dtype=np.float64)
+            block[:packed, :packed] = np.asarray(data, dtype=np.float64).reshape(packed, packed)
+            blocks.append(block)
+        return blocks
+
+    @classmethod
+    def load(cls, filename: FileSource) -> CustomizableImage:
+        """Read a ``.cim`` from ``filename``, or from stdin when it is ``None``."""
+        image = cls()
+        with _open_binary(filename, "rb") as file:
+            image._read_header(file)
+            for channel, description in image._descriptions.items():
+                if description is not None and description.number_of_blocks > 0:
+                    image._data[channel] = cls._read_blocks(file, description)
+        return image
+
+    def get_y_data(self) -> list[Block]:
+        return self._data["y"]
+
+    def get_cb_data(self) -> list[Block]:
+        return self._data["cb"]
+
+    def get_cr_data(self) -> list[Block]:
+        return self._data["cr"]
+
+    def get_dimensions(self) -> tuple[int, int]:
+        return self._width, self._height
+
+    def set_dimensions(self, width: int, height: int) -> None:
+        self._width = width
+        self._height = height
+
+    def set_descriptions(
+        self,
+        y_description: BlockDescription,
+        cb_description: BlockDescription,
+        cr_description: BlockDescription,
+    ) -> None:
+        self._descriptions["y"] = BlockDescription(*y_description)
+        self._descriptions["cb"] = BlockDescription(*cb_description)
+        self._descriptions["cr"] = BlockDescription(*cr_description)
+
+    def set_data(
+        self,
+        y_data: Sequence[Block],
+        cb_data: Sequence[Block],
+        cr_data: Sequence[Block],
+    ) -> None:
+        """Store blocks, keeping only the low-frequency corner of each.
+
+        This is where the codec actually loses information: each block is
+        cropped to ``packed_block_size`` x ``packed_block_size``.
+        """
+        for channel, blocks in (("y", y_data), ("cb", cb_data), ("cr", cr_data)):
+            description = self._descriptions[channel]
+            if description is None:
+                raise ValueError("set_descriptions() must be called before set_data()")
+            packed = description.packed_block_size
+            self._data[channel] = [block[:packed, :packed] for block in blocks]
+
+    def _write_header(self, file: BinaryIO) -> None:
+        file.write(struct.pack(self.HEADER_FORMAT, self._width, self._height))
+        for channel, description in self._descriptions.items():
+            if description is None:
+                raise ValueError(f"no block description set for channel {channel!r}")
+            file.write(struct.pack(self.DESCRIPTION_FORMAT, *description))
+
+    @staticmethod
+    def _write_blocks(file: BinaryIO, blocks: Sequence[Block]) -> None:
+        for block in blocks:
+            data = np.clip(np.rint(block), COEFF_MIN, COEFF_MAX).astype(COEFF_DTYPE)
+            file.write(data.reshape(-1).tobytes())
+
+    def save(self, filename: FileSource) -> None:
+        """Write this image to ``filename``, or to stdout when it is ``None``."""
+        with _open_binary(filename, "wb") as file:
+            self._write_header(file)
+            for blocks in self._data.values():
+                self._write_blocks(file, blocks)

walsh/task.py

@@ -0,0 +1,226 @@
+"""Orchestration: the compress and extract pipelines."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Sequence
+from enum import Enum
+from typing import ClassVar
+
+import numpy as np
+import numpy.typing as npt
+
+from walsh.colors import RgbColorModel, YCbCrColorModel
+from walsh.image import BlockDescription, BMPImage, CustomizableImage, FileSource
+from walsh.transforms import WalshHadamardTransform
+
+__all__ = ["Action", "Task"]
+
+log = logging.getLogger(__name__)
+
+Block = npt.NDArray[np.float64]
+
+#: Defaults carried over from the original implementation.
+DEFAULT_Y_BLOCK_SIZE = 8
+DEFAULT_CHROMA_BLOCK_SIZE = 16
+DEFAULT_PACKED_BLOCK_SIZE = 4
+
+#: Neutral fill values used when a channel carries no blocks.
+NEUTRAL_LUMA = 0
+NEUTRAL_CHROMA = 128
+
+
+class Action(str, Enum):
+    """What a :class:`Task` should do when run."""
+
+    COMPRESS = "compress"
+    EXTRACT = "extract"
+
+
+class Task:
+    """A single compress or extract run, configured fluently.
+
+    >>> Task().with_action("compress").with_input("in.bmp").with_output("out.cim").run()
+    ...                                                        # doctest: +SKIP
+
+    :param y_block_size: block edge used for the luma channel.
+    :param cb_block_size: block edge used for the Cb channel.
+    :param cr_block_size: block edge used for the Cr channel.
+    :param packed_block_size: how many low-frequency coefficients per axis are
+        kept when writing. This is the codec's lossy knob.
+    """
+
+    def __init__(
+        self,
+        *,
+        y_block_size: int = DEFAULT_Y_BLOCK_SIZE,
+        cb_block_size: int = DEFAULT_CHROMA_BLOCK_SIZE,
+        cr_block_size: int = DEFAULT_CHROMA_BLOCK_SIZE,
+        packed_block_size: int = DEFAULT_PACKED_BLOCK_SIZE,
+    ) -> None:
+        self._input: FileSource = None
+        self._output: FileSource = None
+        self._action: Action | None = None
+        self._coeff_removal: float | None = None
+        self._y_block_size = y_block_size
+        self._cb_block_size = cb_block_size
+        self._cr_block_size = cr_block_size
+        self._packed_block_size = packed_block_size
+
+    # -- configuration ---------------------------------------------------
+
+    def with_input(self, source: FileSource) -> Task:
+        self._input = source
+        return self
+
+    def with_output(self, destination: FileSource) -> Task:
+        self._output = destination
+        return self
+
+    def with_action(self, action: Action | str) -> Task:
+        """Select the pipeline to run. Raises :class:`ValueError` if unknown."""
+        try:
+            self._action = Action(action)
+        except ValueError:
+            valid = ", ".join(repr(a.value) for a in Action)
+            raise ValueError(f"unknown action {action!r}; expected one of {valid}") from None
+        return self
+
+    def with_coeff_removal(self, coeff: float | None) -> Task:
+        """Zero Hadamard matrix entries at or below ``coeff`` (see transforms)."""
+        self._coeff_removal = coeff
+        return self
+
+    # -- helpers ---------------------------------------------------------
+
+    @staticmethod
+    def _get_padding_size(x: int, a: int) -> int:
+        """How much to add to ``x`` to reach the next multiple of ``a``."""
+        return ((x - 1) // a + 1) * a - x
+
+    def _slice(
+        self, values: Sequence[float], width: int, height: int, block_size: int
+    ) -> list[Block]:
+        """Reshape a flat channel into zero-padded ``block_size`` square blocks."""
+        plane = np.asarray(values, dtype=np.float64).reshape(height, width)
+
+        height_padding = self._get_padding_size(height, block_size)
+        width_padding = self._get_padding_size(width, block_size)
+        log.debug(
+            "slicing %dx%d into %d-blocks (pad h=%d w=%d)",
+            width,
+            height,
+            block_size,
+            height_padding,
+            width_padding,
+        )
+        plane = np.pad(plane, ((0, height_padding), (0, width_padding)))
+
+        blocks: list[Block] = []
+        for row in np.vsplit(plane, plane.shape[0] // block_size):
+            blocks.extend(np.hsplit(row, row.shape[1] // block_size))
+
+        log.debug("produced %d block(s) of %s", len(blocks), blocks[0].shape)
+        return blocks
+
+    @staticmethod
+    def _merge(blocks: Sequence[Block], width: int, height: int) -> Block:
+        """Reassemble blocks into a plane and crop the padding back off."""
+        _, block_width = blocks[0].shape
+        blocks_per_row = (width - 1) // block_width + 1
+        blocks_per_column = len(blocks) // blocks_per_row
+        rows = [
+            np.hstack(blocks[i * blocks_per_row : (i + 1) * blocks_per_row])
+            for i in range(blocks_per_column)
+        ]
+        return np.vstack(rows)[0:height, 0:width]
+
+    # -- pipelines -------------------------------------------------------
+
+    def compress(self) -> None:
+        """BMP in, spectral ``.cim`` out."""
+        log.info("compressing %s -> %s", self._input, self._output)
+
+        bmp_image = BMPImage()
+        bmp_image.load(self._input)
+
+        width, height = bmp_image.get_dimensions()
+        data = bmp_image.get_raw_data()
+
+        color = RgbColorModel()
+        y, cb, cr = zip(*(color.get_y_cb_cr(pixel) for pixel in data), strict=True)
+
+        blocks = {
+            "y": self._slice(y, width, height, self._y_block_size),
+            "cb": self._slice(cb, width, height, self._cb_block_size),
+            "cr": self._slice(cr, width, height, self._cr_block_size),
+        }
+
+        transform = WalshHadamardTransform(self._coeff_removal)
+        spectral = {
+            channel: transform.transform_sequence(channel_blocks)
+            for channel, channel_blocks in blocks.items()
+        }
+
+        packed = self._packed_block_size
+        customizable_image = CustomizableImage()
+        customizable_image.set_dimensions(width, height)
+        customizable_image.set_descriptions(
+            BlockDescription(self._y_block_size, packed, len(spectral["y"])),
+            BlockDescription(self._cb_block_size, packed, len(spectral["cb"])),
+            BlockDescription(self._cr_block_size, packed, len(spectral["cr"])),
+        )
+        customizable_image.set_data(spectral["y"], spectral["cb"], spectral["cr"])
+        customizable_image.save(self._output)
+
+    def extract(self) -> None:
+        """Spectral ``.cim`` in, BMP out."""
+        log.info("extracting %s -> %s", self._input, self._output)
+
+        customizable_image = CustomizableImage.load(self._input)
+        width, height = customizable_image.get_dimensions()
+        transform = WalshHadamardTransform()
+
+        channels = {
+            "y": (customizable_image.get_y_data(), NEUTRAL_LUMA),
+            "cb": (customizable_image.get_cb_data(), NEUTRAL_CHROMA),
+            "cr": (customizable_image.get_cr_data(), NEUTRAL_CHROMA),
+        }
+
+        planes: dict[str, list[float]] = {}
+        for channel, (spectral, neutral) in channels.items():
+            if not spectral:
+                log.debug("channel %s is empty, filling with %d", channel, neutral)
+                planes[channel] = [float(neutral)] * (width * height)
+                continue
+            merged = self._merge(transform.inverse_transform_sequence(spectral), width, height)
+            planes[channel] = np.asarray(merged).reshape(-1).tolist()
+
+        color = YCbCrColorModel()
+        pixels = [
+            color.get_rgb(triple)
+            for triple in zip(planes["y"], planes["cb"], planes["cr"], strict=True)
+        ]
+
+        bmp_image = BMPImage()
+        bmp_image.set_dimensions(width, height)
+        bmp_image.set_raw_data(pixels)
+        bmp_image.save(self._output)
+
+    _ACTIONS: ClassVar[dict[Action, Callable[[Task], None]]] = {
+        Action.COMPRESS: compress,
+        Action.EXTRACT: extract,
+    }
+
+    def run(self) -> None:
+        """Execute the configured action. Raises if none was selected."""
+        if self._action is None:
+            raise ValueError("no action selected; call with_action() first")
+        log.debug(
+            "run action=%s input=%s output=%s coeff_removal=%s",
+            self._action.value,
+            self._input,
+            self._output,
+            self._coeff_removal,
+        )
+        Task._ACTIONS[self._action](self)

walsh/transforms.py

@@ -0,0 +1,96 @@
+"""The Walsh-Hadamard transform itself."""
+
+from __future__ import annotations
+
+import math
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+import numpy as np
+import numpy.typing as npt
+
+from walsh.decorators import cached
+
+__all__ = ["Transform", "WalshHadamardTransform"]
+
+Block = npt.NDArray[np.float64]
+
+#: Tolerance used when comparing a matrix entry against the removal coefficient.
+COEFF_TOLERANCE = 0.000001
+
+
+class Transform(ABC):
+    """A block transform and its inverse."""
+
+    @abstractmethod
+    def transform(self, src: Block) -> Block:
+        """Transform a single square block."""
+
+    @abstractmethod
+    def inverse_transform(self, src: Block) -> Block:
+        """Invert :meth:`transform` for a single square block."""
+
+    def transform_sequence(self, src_seq: Iterable[Block]) -> list[Block]:
+        return [self.transform(block) for block in src_seq]
+
+    def inverse_transform_sequence(self, src_seq: Iterable[Block]) -> list[Block]:
+        return [self.inverse_transform(block) for block in src_seq]
+
+
+class WalshHadamardTransform(Transform):
+    """Orthonormal Walsh-Hadamard transform in sequency (Walsh) order.
+
+    The transform is symmetric and involutive, so :meth:`inverse_transform`
+    is simply :meth:`transform` applied again.
+
+    :param coeff: optional coefficient-removal threshold. When set, matrix
+        entries that fall at or below it during construction are zeroed,
+        which discards part of the spectrum. See :meth:`_build_matrix`.
+    """
+
+    def __init__(self, coeff: float | None = None) -> None:
+        self._coeff = coeff
+
+    @cached
+    def _build_matrix(self, size: int) -> Block:
+        """Build the ``size`` x ``size`` Walsh-Hadamard matrix.
+
+        Starts from a uniform matrix of ``1 / sqrt(2) ** n`` and negates the
+        entries whose row and column indices share a set bit, which yields the
+        natural (Hadamard) ordering. Rows are then sorted by the number of
+        sign changes to reach sequency (Walsh) ordering.
+        """
+        n = int(math.log(size, 2))
+        matrix = np.full((size, size), 1 / (np.sqrt(2) ** n), dtype=np.float64)
+
+        for i in range(n):
+            for j in range(size):
+                for k in range(size):
+                    if (j // 2**i) % 2 == 1 and (k // 2**i) % 2 == 1:
+                        matrix[j, k] = -matrix[j, k]
+                        # NOTE: preserved verbatim from the original Python 2
+                        # implementation. The comparison is one-sided rather
+                        # than on the magnitude, so in practice any non-None
+                        # coeff above -1/sqrt(2)**n zeroes every entry that
+                        # ever gets negated. Changing it changes output.
+                        if self._coeff is not None and matrix[j, k] - self._coeff < COEFF_TOLERANCE:
+                            matrix[j, k] = 0
+
+        return matrix[np.argsort(_sign_changes(matrix), kind="stable")]
+
+    def transform(self, src: Block) -> Block:
+        src = np.asarray(src, dtype=np.float64)
+        if src.ndim != 2 or src.shape[0] != src.shape[1]:
+            raise ValueError(f"expected a square block, got shape {src.shape}")
+
+        h = self._build_matrix(src.shape[0])
+        return h @ src @ h
+
+    def inverse_transform(self, src: Block) -> Block:
+        return self.transform(src)
+
+
+def _sign_changes(matrix: Block) -> npt.NDArray[np.int64]:
+    """Count sign changes along each row -- the sequency of that Walsh function."""
+    counts: npt.NDArray[np.int64] = np.count_nonzero(matrix[:, 1:] * matrix[:, :-1] < 0, axis=1)
+    return counts

walsh-0.1.1.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: walsh
+Version: 0.1.1
+Summary: Image compression with the Walsh-Hadamard transform
+Author-email: Oskar Jarczyk <oskar.jarczyk@gmail.com>
+Maintainer-email: Oskar Jarczyk <oskar.jarczyk@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/oskar-j/walsh-hadamard-transform
+Project-URL: Repository, https://github.com/oskar-j/walsh-hadamard-transform
+Project-URL: Issues, https://github.com/oskar-j/walsh-hadamard-transform/issues
+Project-URL: Changelog, https://github.com/oskar-j/walsh-hadamard-transform/blob/master/CHANGELOG.md
+Keywords: walsh,hadamard,transform,image,compression,dsp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.24
+Provides-Extra: demo
+Requires-Dist: matplotlib<4,>=3.7; extra == "demo"
+Requires-Dist: Pillow<13,>=10.0; extra == "demo"
+Dynamic: license-file
+
+# Walsh-hadamard transform
+
+[![PyPI](https://img.shields.io/pypi/v/walsh.svg)](https://pypi.org/project/walsh/)
+[![Python versions](https://img.shields.io/pypi/pyversions/walsh.svg)](https://pypi.org/project/walsh/)
+[![CI](https://github.com/oskar-j/walsh-hadamard-transform/actions/workflows/ci.yml/badge.svg)](https://github.com/oskar-j/walsh-hadamard-transform/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Compressing images with a Hadamard transform
+
+## Description
+
+**From Wikipedia:** The Hadamard transform (also known as the *Walsh–Hadamard transform*, 
+*Hadamard–Rademacher–Walsh transform*, *Walsh transform*, or *Walsh–Fourier transform*) is an example 
+of a generalized class of Fourier transforms. It performs an orthogonal, symmetric, 
+involutive, linear operation on 2m real numbers (or complex numbers, although the 
+Hadamard matrices themselves are purely real).
+
+The Hadamard transform can be regarded as being built out of *size-2 
+discrete Fourier transforms* (DFTs), and is in fact equivalent to a 
+multidimensional DFT of size `2 × 2 × ⋯ × 2 × 2`. It decomposes an 
+arbitrary input vector into a superposition of *Walsh functions*.
+
+The transform is named for the French mathematician Jacques Hadamard, 
+the German-American mathematician Hans Rademacher, and the 
+American mathematician Joseph L. Walsh. 
+
+The Hadamard transform is also used in data encryption, as well as many signal processing 
+and data compression algorithms, such as `JPEG XR` and `MPEG-4 AVC`. In video compression 
+applications, it is usually used in the form of the sum of absolute transformed differences. 
+It is also a crucial part of *Grover's algorithm* and *Shor's algorithm* in quantum computing. 
+
+## Acknowledgement
+
+This code is partially based on the solution from [ktisha/python2012](https://github.com/ktisha/python2012/tree/dee4beda8e22f3a66a3e31384d4b72ab66102e88/avereshchagin)
+
+## Installation
+
+Requires Python 3.10 or newer.
+
+```
+pip install walsh
+```
+
+or, with [uv](https://docs.astral.sh/uv/):
+
+```
+uv add walsh          # into a project
+uv tool install walsh # just the command line tool
+```
+
+The example script additionally needs matplotlib and Pillow, which are the
+`demo` extra: `pip install "walsh[demo]"`.
+
+### Development
+
+`uv.lock` is committed, so a checkout reproduces exactly the environment CI
+uses:
+
+```
+uv sync --group dev --all-extras
+```
+
+`--group dev` brings in pytest, ruff and mypy; `--all-extras` adds the `demo`
+extra so `examples/roundtrip.py` runs too. Without uv:
+
+```
+pip install -e ".[demo]" -r requirements-dev.txt
+```
+
+## How to run
+
+### Command line
+
+```
+walsh compress data/image.bmp data/transformed.cim
+walsh extract  data/transformed.cim data/recreated.bmp
+```
+
+`compress` accepts `--packed-block-size` (how many low-frequency coefficients
+per axis to keep -- lower is smaller and lossier), `--y-block-size`,
+`--chroma-block-size` and `--coeff-removal`. Add `-v`/`-vv` for progress
+logging, and see `walsh --help` for the full list.
+
+### As a library
+
+```python
+from walsh import Task
+
+Task().with_action("compress").with_input("data/image.bmp").with_output("out.cim").run()
+Task().with_action("extract").with_input("out.cim").with_output("back.bmp").run()
+```
+
+### Example
+
+`examples/roundtrip.py` compresses the sample image, restores it, and plots
+both images with their histograms side by side (needs the `demo` extra):
+
+```
+python examples/roundtrip.py
+```
+
+## Requirements
+
+The package itself needs only `numpy` -- BMP parsing is done by hand with
+`struct`. `matplotlib` and `Pillow` are needed only by the example script, and
+are declared as the `demo` extra. Versions are pinned in `pyproject.toml`;
+`requirements.txt`, `requirements-demo.txt` and `requirements-dev.txt` mirror
+them for plain `pip install -r` workflows.
+
+## Development commands
+
+```
+uv run pytest              # test suite
+uv run ruff check .        # lint
+uv run ruff format .       # format
+uv run mypy                # strict type check
+uv build                   # sdist + wheel into dist/
+```
+
+CI runs exactly these on every pull request, plus the test suite against
+Python 3.10 through 3.14.
+
+## Releasing
+
+The version in `pyproject.toml` is the single source of truth. To cut a
+release, bump it, add the matching `## [x.y.z]` section to `CHANGELOG.md`, and
+merge to `master`. The release workflow then tags `v<version>`, creates a
+GitHub Release with those notes, and publishes the sdist and wheel to
+[PyPI](https://pypi.org/project/walsh/) using Trusted Publishing — no API token
+is stored in this repository.
+
+Merges that do not change the version are a no-op, since PyPI permanently
+refuses to accept the same version twice.
+
+## File format
+
+`compress` writes a `.cim` file: an atypical, project-specific container, so
+most commercial tools will not be able to read it. It stores the image
+dimensions, three block-layout descriptions (Y, Cb, Cr), and the retained
+Walsh-Hadamard coefficients as little-endian `int16`.
+
+## Effects
+
+![https://raw.githubusercontent.com/oskar-j/walsh-hadamard-transform/master/doc/sample_usage.jpg](https://raw.githubusercontent.com/oskar-j/walsh-hadamard-transform/master/doc/sample_usage.jpg)

walsh-0.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+walsh/__init__.py,sha256=z4qmhYWDtt8jTDpLKZjeDvPFAexrYMcmfIhnZMOLOBQ,1086
+walsh/cli.py,sha256=yW8D1JRuRBi8fTvytjxkknc63qkcZXdTPR2wcsYjSzw,3188
+walsh/colors.py,sha256=MCndT-6a2gsQ1ogVJfc-cyw6tNkxBM_JmN6seb-n2CQ,1832
+walsh/decorators.py,sha256=yROYvcJnA7KxIEIiH94G8CeopeglKJ6uD9ul1pd2jhc,1832
+walsh/image.py,sha256=05ts2ik5rCY328QfSTrwc5JJJP65lxqCkW2tgnAeoM8,10815
+walsh/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+walsh/task.py,sha256=eYa60rD-cP9OmoFZMUWRA3xWJvEs3mJ8FFyfPOUwjMs,8286
+walsh/transforms.py,sha256=ztW7a414lDJvWDsrKNxAd0aIE5Ki4AXjKIsiBHHhJLw,3631
+walsh-0.1.1.dist-info/licenses/LICENSE,sha256=RBQ-xJOWhbkaAnMhPY22613A552wbnzo9YDyyzkgi3s,1070
+walsh-0.1.1.dist-info/METADATA,sha256=91YJQcfNz1QO1waWotalK3BLar62fxwikkEXqwqD4Oo,6685
+walsh-0.1.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+walsh-0.1.1.dist-info/entry_points.txt,sha256=79C5XI5316tKYSbcQK0PExCg1i36aIl5nl_yLd7zLwQ,41
+walsh-0.1.1.dist-info/top_level.txt,sha256=LHrQEOKEm3Lp4RmLHTFxM25Up6nPIke45PfQCedudLw,6
+walsh-0.1.1.dist-info/RECORD,,

walsh-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

walsh-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+walsh = walsh.cli:main

walsh-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Oskar Jarczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

walsh-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+walsh