imagecalculator 0.1.0__py3-none-any.whl

imagecalculator/__init__.py

@@ -0,0 +1,27 @@
+"""imagecalculator: progressive block-DCT image codec.
+
+Tier 1 -- truncation reduces your token count::
+
+    enc = ic.compress("photo.jpg", keep=8)      # 8 of 63 diagonals -> 112 px for the model
+    img = ic.decompress(enc)                    # PIL image at the reduced native size
+
+Tier 2 -- truncation + per-diagonal quantization, YCrCb, chroma subsampling and
+entropy coding reduce the bytes over the air (``enc.nbytes``).
+"""
+from ._version import __version__
+from .bands import decode_payload, diag_support_index, encode_payload
+from .codec import EncodedImage, Encoder, compress, decode, decompress, load
+from .config import IC_BLOCK_SIZES, IC_QUANTIZATION_FACTORS, SUBSAMPLING_STRATEGIES, CodecConfig, quantization_bands
+from .image import load_image, load_pil, png_b64, png_bytes, to_pil
+from .policy import DiagonalPolicy
+from .tokens import TokenEstimate, estimate as token_estimate
+
+__all__ = [
+    "__version__",
+    "CodecConfig", "quantization_bands", "IC_BLOCK_SIZES", "IC_QUANTIZATION_FACTORS", "SUBSAMPLING_STRATEGIES",
+    "DiagonalPolicy",
+    "Encoder", "EncodedImage", "compress", "decompress", "decode", "load",
+    "load_image", "load_pil", "to_pil", "png_bytes", "png_b64",
+    "token_estimate", "TokenEstimate",
+    "encode_payload", "decode_payload", "diag_support_index",
+]

imagecalculator/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

imagecalculator/bands.py

@@ -0,0 +1,94 @@
+"""Per-diagonal band payloads: support indices and the blosc record format.
+
+A payload is ``[1-byte dtype code][blosc(zstd, BITSHUFFLE) of the compact
+(3, n_d) integer array]`` -- byte-identical to one ``img_<i>/diag_<d>.col``
+file of the research dir store.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import blosc
+import numpy as np
+
+DTYPE_CODES = {
+    "int8": 0, "int16": 1, "int32": 2, "int64": 3,
+    "uint8": 4, "uint16": 5, "uint32": 6, "uint64": 7,
+}
+CODE_TO_DTYPE = {v: k for k, v in DTYPE_CODES.items()}
+
+
+@lru_cache(maxsize=64)
+def diag_support_index(image_size: int, block_size: int) -> tuple[np.ndarray, ...]:
+    """Flat (C-raster) positions of each anti-diagonal's support in an ``S x S`` plane.
+
+    Position ``(i, j)`` belongs to anti-diagonal ``(i % N) + (j % N)``. Entry
+    ``d`` of the result gathers and scatters diagonal ``d`` with the same index,
+    so a compact band round-trips to its dense positions exactly.
+    """
+    S, N = image_size, block_size
+    within = np.arange(S) % N
+    antidiag = (within[:, None] + within[None, :]).ravel()
+    return tuple(np.flatnonzero(antidiag == d) for d in range(2 * N - 1))
+
+
+def diag_support_sizes(image_size: int, block_size: int) -> tuple[int, ...]:
+    return tuple(int(ix.size) for ix in diag_support_index(image_size, block_size))
+
+
+def choose_int_dtype(min_val: int, max_val: int) -> np.dtype:
+    if min_val >= 0:
+        for t in (np.uint8, np.uint16, np.uint32):
+            if max_val <= np.iinfo(t).max:
+                return np.dtype(t)
+        return np.dtype(np.uint64)
+    for t in (np.int8, np.int16, np.int32):
+        if min_val >= np.iinfo(t).min and max_val <= np.iinfo(t).max:
+            return np.dtype(t)
+    return np.dtype(np.int64)
+
+
+def encode_blob(arr: np.ndarray, clevel: int) -> tuple[bytes, np.dtype]:
+    """Narrow an int64 array to the smallest dtype holding its range and blosc-compress it."""
+    arr = arr if arr.dtype == np.int64 else arr.astype(np.int64)
+    dtype = choose_int_dtype(int(arr.min()), int(arr.max()))
+    arr = np.ascontiguousarray(arr.astype(dtype, copy=False))
+    blob = blosc.compress(
+        arr.tobytes(),
+        typesize=arr.itemsize,
+        cname="zstd",
+        clevel=int(clevel),
+        shuffle=blosc.BITSHUFFLE,
+    )
+    return blob, dtype
+
+
+def decode_blob(blob: bytes, dtype: str | np.dtype, shape: tuple[int, ...]) -> np.ndarray:
+    raw = blosc.decompress(blob)
+    return np.frombuffer(raw, dtype=np.dtype(dtype)).reshape(shape).astype(np.int64)
+
+
+def encode_payload(compact: np.ndarray, clevel: int) -> bytes:
+    """``(3, n_d)`` int64 -> ``[dtype code][blob]`` (the dir-store file content)."""
+    blob, dtype = encode_blob(compact, clevel)
+    return bytes((DTYPE_CODES[dtype.name],)) + blob
+
+
+def decode_payload(payload: bytes, n_d: int) -> np.ndarray:
+    """``[dtype code][blob]`` -> ``(3, n_d)`` int64."""
+    if len(payload) < 2:
+        raise ValueError("payload too short")
+    code = payload[0]
+    if code not in CODE_TO_DTYPE:
+        raise ValueError(f"unknown dtype code {code}")
+    return decode_blob(payload[1:], CODE_TO_DTYPE[code], (3, n_d))
+
+
+def compact_to_dense(compact: np.ndarray, index: np.ndarray, image_size: int) -> np.ndarray:
+    dense = np.zeros((3, image_size * image_size), dtype=compact.dtype)
+    dense[:, index] = compact
+    return dense.reshape(3, image_size, image_size)
+
+
+def dense_to_compact(dense: np.ndarray, index: np.ndarray) -> np.ndarray:
+    return np.ascontiguousarray(dense.reshape(3, -1)[:, index])

imagecalculator/cli.py

@@ -0,0 +1,128 @@
+"""``imagecalculator compress | decompress | info``."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .codec import EncodedImage, compress, decompress
+
+
+def _parse_quantization(text: str | None):
+    if text is None:
+        return None
+    text = text.strip()
+    if text.startswith("["):
+        return json.loads(text)
+    return int(text)
+
+
+def _parse_keep(text: str):
+    if text == "all":
+        return "all"
+    if "." in text or text.endswith("%"):
+        v = float(text.rstrip("%"))
+        return v / 100.0 if text.endswith("%") else v
+    return int(text)
+
+
+def _fmt_bytes(n: int) -> str:
+    return f"{n / 1024:.1f} KiB" if n >= 1024 else f"{n} B"
+
+
+def cmd_compress(a: argparse.Namespace) -> int:
+    enc = compress(
+        a.image, keep=_parse_keep(a.keep), quantization=_parse_quantization(a.quantization),
+        block_size=a.block_size, image_size=a.image_size, use_ycrcb=not a.no_ycrcb,
+        subsampling=a.subsampling, clevel=a.clevel, device=a.device,
+    )
+    out = Path(a.output) if a.output else Path(a.image).with_suffix(".icf")
+    enc.save(out)
+    _print_info(enc, original=a.image, provider=a.provider, detail=a.detail)
+    print(f"wrote {out}")
+    return 0
+
+
+def cmd_decompress(a: argparse.Namespace) -> int:
+    size: str | int = a.size if a.size in ("native", "full") else int(a.size)
+    img = decompress(a.icf, size=size, device=a.device)
+    out = Path(a.output) if a.output else Path(a.icf).with_suffix(".png")
+    img.save(out)
+    print(f"wrote {out} ({img.size[0]}x{img.size[1]})")
+    return 0
+
+
+def _print_info(enc: EncodedImage, original: str | None = None, provider: str = "anthropic", detail: str | None = None) -> None:
+    c = enc.config
+    sv = enc.savings(original, provider, detail)
+    q = c.quantization if c.is_uniform else f"schedule(min={c.quantization_factor})"
+    print(f"config: block {c.block_size}, image {c.image_size}, ycrcb={c.use_ycrcb}, subsampling={c.subsampling}, q={q}, clevel={c.clevel}")
+    print(f"keep: {enc.keep_k}/{c.max_diag} diagonals  -> native decode {enc.pixels[0]}x{enc.pixels[1]} px")
+    t = sv["tokens"]
+    print(f"tokens: {t['reduced']} (full image {t['full_image']}, {t['provider']} estimate, {t['ratio']:.1f}x fewer)")
+    b = sv["bytes"]
+    if b["original_file"]:
+        print(f"bytes over the air: {_fmt_bytes(b['over_the_air'])} (original file {_fmt_bytes(b['original_file'])}, {b['ratio']:.1f}x smaller)")
+    else:
+        print(f"bytes over the air: {_fmt_bytes(b['over_the_air'])}")
+    if enc.transform_label:
+        print(f"transform: {enc.transform_label} (not research-store compatible)")
+
+
+def cmd_info(a: argparse.Namespace) -> int:
+    enc = EncodedImage.load(a.icf)
+    _print_info(enc, original=a.original, provider=a.provider, detail=a.detail)
+    if a.json:
+        print(json.dumps(enc.savings(a.original, a.provider, a.detail), indent=2))
+    return 0
+
+
+def _add_token_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--provider", default="anthropic", help="token estimate: anthropic | openai[:model] | google[:model]")
+    p.add_argument("--detail", default=None, help="OpenAI detail or Gemini media_resolution (default: the API default)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="imagecalculator", description="Progressive block-DCT image codec")
+    p.add_argument("--version", action="version", version=f"imagecalculator {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("compress", help="truncate + quantize an image into an .icf blob")
+    c.add_argument("image")
+    c.add_argument("--keep", default="all", help="diagonals to keep: int, fraction (0.25) or percent (25%%), or 'all'")
+    c.add_argument("--quantization", "-q", default=None, help="scalar step, or JSON bands [[from,to,q],...]")
+    c.add_argument("--block-size", type=int, default=32)
+    c.add_argument("--image-size", type=int, default=448)
+    c.add_argument("--no-ycrcb", action="store_true")
+    c.add_argument("--subsampling", default="1x1", choices=["1x1", "2x2-r", "2x2-c", "4x4"])
+    c.add_argument("--clevel", type=int, default=9)
+    c.add_argument("--device", default="cpu")
+    c.add_argument("-o", "--output")
+    _add_token_args(c)
+    c.set_defaults(fn=cmd_compress)
+
+    d = sub.add_parser("decompress", help="decode an .icf blob to PNG")
+    d.add_argument("icf")
+    d.add_argument("--size", default="native", help="native | full | <side px>")
+    d.add_argument("--device", default="cpu")
+    d.add_argument("-o", "--output")
+    d.set_defaults(fn=cmd_decompress)
+
+    i = sub.add_parser("info", help="print config, keep, tokens and bytes")
+    i.add_argument("icf")
+    i.add_argument("--original", help="original image file for the byte baseline")
+    i.add_argument("--json", action="store_true")
+    _add_token_args(i)
+    i.set_defaults(fn=cmd_info)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    a = build_parser().parse_args(argv)
+    return a.fn(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

imagecalculator/codec.py

@@ -0,0 +1,331 @@
+"""Encoder / EncodedImage / decode: the compress-for-the-model path.
+
+Pipeline (bit-exact with the research dir-store builder when no ``transform``
+is used): load -> resize -> [YCrCb -> chroma subsample] -> block DCT ->
+``round(coeff / q[d])`` -> keep the first ``k`` anti-diagonals -> one compact
+blosc payload per diagonal. Decoding runs an ``m``-point inverse DCT on each
+block's low corner, so ``k`` diagonals come back as an ``S*k/N`` px image.
+"""
+from __future__ import annotations
+
+import json
+import os
+import struct
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Sequence
+
+import numpy as np
+import torch
+from PIL import Image
+from torch import Tensor
+
+from . import tokens as _tokens
+from .bands import decode_payload, diag_support_index, encode_payload
+from .config import CodecConfig, quantization_bands
+from .image import ImageLike, load_image, to_pil
+from .policy import DiagonalPolicy, ResolvedPolicy
+from .transform import deblockify, forward_plane, inverse_plane
+
+MAGIC = b"ICF1"
+FORMAT_VERSION = 1
+
+
+# ---------------------------------------------------------------------------
+# EncodedImage
+# ---------------------------------------------------------------------------
+
+@dataclass
+class EncodedImage:
+    """One image's kept diagonals as compressed payloads.
+
+    ``payloads[d]`` is byte-identical to ``img_<i>/diag_<d>.col`` of a research
+    dir store built with the same config (``transform=None``).
+    """
+
+    config: CodecConfig
+    payloads: list[bytes]
+    transform_label: str | None = None
+    _support: tuple[int, ...] = field(default_factory=tuple, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if not self.payloads:
+            raise ValueError("an EncodedImage needs at least one diagonal")
+        if len(self.payloads) > self.config.max_diag:
+            raise ValueError(f"{len(self.payloads)} payloads but max_diag is {self.config.max_diag}")
+        if not self._support:
+            self._support = tuple(int(ix.size) for ix in diag_support_index(self.config.image_size, self.config.block_size))
+
+    # -- geometry ------------------------------------------------------------
+    @property
+    def keep_k(self) -> int:
+        return len(self.payloads)
+
+    @property
+    def is_truncated(self) -> bool:
+        return self.keep_k < self.config.max_diag
+
+    @property
+    def native_m(self) -> int:
+        """Output block size of the native decode: the smallest corner holding the kept triangle."""
+        return min(self.keep_k, self.config.block_size)
+
+    @property
+    def native_side(self) -> int:
+        return self.config.image_size * self.native_m // self.config.block_size
+
+    @property
+    def pixels(self) -> tuple[int, int]:
+        """``(width, height)`` of the native-size decode (tier 1: what the model sees)."""
+        return (self.native_side, self.native_side)
+
+    def valid_sizes(self) -> list[int]:
+        S, N = self.config.image_size, self.config.block_size
+        return [S * m // N for m in range(self.native_m, N + 1)]
+
+    # -- bytes ---------------------------------------------------------------
+    @property
+    def payload_bytes(self) -> int:
+        return sum(len(p) for p in self.payloads)
+
+    @property
+    def nbytes(self) -> int:
+        """Bytes over the air: the ``.icf`` container (header + kept payloads) (tier 2)."""
+        return len(self.to_bytes())
+
+    def cumulative_bytes(self) -> np.ndarray:
+        """int64 ``(keep_k,)``: payload bytes through each kept diagonal."""
+        return np.cumsum([len(p) for p in self.payloads], dtype=np.int64)
+
+    # -- tokens --------------------------------------------------------------
+    def token_estimate(self, provider: str = "anthropic", detail: str | None = None) -> _tokens.TokenEstimate:
+        """``provider`` is ``"anthropic"``, ``"openai[:model]"`` or ``"google[:model]"``."""
+        w, h = self.pixels
+        return _tokens.estimate(w, h, provider, detail)
+
+    def savings(self, original: str | Path | int | None = None, provider: str = "anthropic",
+                detail: str | None = None) -> dict:
+        """Tier 1 and tier 2 numbers next to their full-image baselines."""
+        S = self.config.image_size
+        full = _tokens.estimate(S, S, provider, detail)
+        red = self.token_estimate(provider, detail)
+        if isinstance(original, (str, Path)):
+            orig_bytes: int | None = os.path.getsize(original)
+        elif isinstance(original, int):
+            orig_bytes = original
+        else:
+            orig_bytes = None
+        out = {
+            "tokens": {"reduced": red.tokens, "full_image": full.tokens, "provider": provider},
+            "pixels": {"reduced": self.pixels, "full_image": (S, S)},
+            "bytes": {"over_the_air": self.nbytes, "original_file": orig_bytes},
+            "keep": self.keep_k,
+            "max_diag": self.config.max_diag,
+        }
+        if orig_bytes:
+            out["bytes"]["ratio"] = orig_bytes / self.nbytes
+        out["tokens"]["ratio"] = full.tokens / red.tokens
+        return out
+
+    # -- coefficients --------------------------------------------------------
+    def coefficients(self, d: int) -> np.ndarray:
+        """Quantized integer coefficients of diagonal ``d`` as ``(3, n_d)`` int64."""
+        if not (0 <= d < self.keep_k):
+            raise IndexError(f"diagonal {d} not kept (keep_k={self.keep_k})")
+        return decode_payload(self.payloads[d], self._support[d])
+
+    def dense_plane(self) -> np.ndarray:
+        """Dequantized coefficients scattered into a dense ``(3, S, S)`` float32 plane (research reader arithmetic)."""
+        S = self.config.image_size
+        idx = diag_support_index(S, self.config.block_size)
+        q = self.config.q_vector
+        acc = np.zeros((3, S * S), dtype=np.float32)
+        for d in range(self.keep_k):
+            vals = self.coefficients(d)
+            acc[:, idx[d]] += vals.astype(np.float32) * float(q[d])
+        return acc.reshape(3, S, S)
+
+    def truncate(self, k: int) -> "EncodedImage":
+        if not (1 <= k <= self.keep_k):
+            raise ValueError(f"k must be in 1..{self.keep_k}; got {k}")
+        return EncodedImage(self.config, list(self.payloads[:k]), self.transform_label, self._support)
+
+    # -- container -----------------------------------------------------------
+    def header(self) -> dict:
+        h = self.config.to_dict()
+        h.update({
+            "format_version": FORMAT_VERSION,
+            "keep": self.keep_k,
+            "lengths": [len(p) for p in self.payloads],
+        })
+        if self.transform_label is not None:
+            h["transform"] = self.transform_label
+        return h
+
+    def to_bytes(self) -> bytes:
+        hdr = json.dumps(self.header(), separators=(",", ":")).encode("utf-8")
+        return b"".join([MAGIC, struct.pack("<I", len(hdr)), hdr, *self.payloads])
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "EncodedImage":
+        if data[:4] != MAGIC:
+            raise ValueError("not an .icf blob (bad magic)")
+        (hlen,) = struct.unpack("<I", data[4:8])
+        hdr = json.loads(data[8:8 + hlen].decode("utf-8"))
+        config = CodecConfig.from_dict(hdr)
+        lengths = [int(v) for v in hdr["lengths"]]
+        if len(lengths) != int(hdr["keep"]):
+            raise ValueError("corrupt header: keep != len(lengths)")
+        pos = 8 + hlen
+        payloads = []
+        for n in lengths:
+            payloads.append(data[pos:pos + n])
+            pos += n
+        if pos != len(data):
+            raise ValueError(f"container length mismatch: expected {pos} bytes, got {len(data)}")
+        return cls(config, payloads, hdr.get("transform"))
+
+    def save(self, path: str | Path) -> None:
+        Path(path).write_bytes(self.to_bytes())
+
+    @classmethod
+    def load(cls, path: str | Path) -> "EncodedImage":
+        return cls.from_bytes(Path(path).read_bytes())
+
+
+# ---------------------------------------------------------------------------
+# Encoder
+# ---------------------------------------------------------------------------
+
+class Encoder:
+    """Encode images under one :class:`CodecConfig` on one device."""
+
+    def __init__(self, config: CodecConfig, device: torch.device | str = "cpu"):
+        self.config = config
+        self.device = torch.device(device)
+        S, N = config.image_size, config.block_size
+        self._support = diag_support_index(S, N)
+        # per-position diagonal index of the dense S x S plane
+        within = np.arange(S) % N
+        self._diag_of_pos = torch.from_numpy((within[:, None] + within[None, :]).ravel()).to(self.device)
+
+    def _plane(self, image: ImageLike) -> Tensor:
+        """Un-quantized dense coefficient plane ``(3, S*S)`` float32 on the device."""
+        cfg = self.config
+        img = load_image(image, cfg.image_size, self.device)
+        blocks = forward_plane(img, cfg.block_size, cfg.use_ycrcb, cfg.subsampling)
+        return deblockify(blocks, (cfg.image_size, cfg.image_size)).reshape(3, -1)
+
+    def _quantize(self, plane: Tensor, policy: ResolvedPolicy) -> np.ndarray:
+        q_pos = torch.from_numpy(policy.q_vector).to(self.device)[self._diag_of_pos]
+        if policy.transform is not None:
+            plane = plane.clone()
+            for d in range(policy.keep_k):
+                ix = torch.from_numpy(self._support[d]).to(self.device)
+                plane[:, ix] = policy.transform(d, plane[:, ix])
+        return torch.round(plane / q_pos).to(torch.int64).cpu().numpy()
+
+    def encode(self, image: ImageLike, policy: DiagonalPolicy | None = None, transform_label: str | None = None) -> EncodedImage:
+        cfg = self.config
+        pol = (policy or DiagonalPolicy()).resolve(cfg.max_diag, cfg.q_vector, cfg.clevel)
+        plane_q = self._quantize(self._plane(image), pol)
+        payloads = [
+            encode_payload(np.ascontiguousarray(plane_q[:, self._support[d]]), pol.clevels[d])
+            for d in range(pol.keep_k)
+        ]
+        eff_cfg = cfg
+        if not np.array_equal(pol.q_vector, cfg.q_vector):
+            qv = [int(v) for v in pol.q_vector]
+            quant = qv[0] if len(set(qv)) == 1 else tuple(qv)
+            eff_cfg = CodecConfig(cfg.block_size, cfg.image_size, cfg.use_ycrcb, cfg.subsampling, quant, cfg.clevel)
+        label = transform_label if transform_label is not None else ("custom" if pol.transform is not None else None)
+        return EncodedImage(eff_cfg, payloads, label, tuple(int(ix.size) for ix in self._support))
+
+    def coefficient_plane(self, image: ImageLike) -> Tensor:
+        """Quantized integer coefficient plane ``(1, 3, S, S)`` (config quantization, nothing truncated)."""
+        cfg = self.config
+        pol = DiagonalPolicy().resolve(cfg.max_diag, cfg.q_vector, cfg.clevel)
+        plane_q = self._quantize(self._plane(image), pol)
+        return torch.from_numpy(plane_q.reshape(3, cfg.image_size, cfg.image_size)).unsqueeze(0)
+
+
+# ---------------------------------------------------------------------------
+# Decoding
+# ---------------------------------------------------------------------------
+
+def _resolve_m(enc: EncodedImage, size: str | int) -> int:
+    S, N = enc.config.image_size, enc.config.block_size
+    if size == "native":
+        return enc.native_m
+    if size == "full":
+        return N
+    side = int(size)
+    if side * N % S != 0:
+        raise ValueError(f"size {side} is not S*m/N for an integer m; valid sizes: {enc.valid_sizes()}")
+    m = side * N // S
+    if not (enc.native_m <= m <= N):
+        raise ValueError(f"size {side} is outside the valid range; valid sizes: {enc.valid_sizes()}")
+    return m
+
+
+def decode(encoded: EncodedImage, size: str | int = "native", device: torch.device | str = "cpu") -> Tensor:
+    """RGB float32 ``(1, 3, h, w)`` in [0, 255] at ``size`` = ``"native"`` (``S*k/N``), ``"full"`` or an int side."""
+    m = _resolve_m(encoded, size)
+    plane = torch.from_numpy(encoded.dense_plane()).unsqueeze(0).to(device)
+    return inverse_plane(plane, encoded.config.block_size, encoded.config.use_ycrcb, m)
+
+
+def decompress(encoded: EncodedImage | bytes | str | Path, size: str | int = "native", device: torch.device | str = "cpu") -> Image.Image:
+    """Decode to a PIL image (uint8 truncation, as the research reader)."""
+    if isinstance(encoded, (bytes, bytearray)):
+        encoded = EncodedImage.from_bytes(bytes(encoded))
+    elif isinstance(encoded, (str, Path)):
+        encoded = EncodedImage.load(encoded)
+    return to_pil(decode(encoded, size, device))
+
+
+# ---------------------------------------------------------------------------
+# One-call API
+# ---------------------------------------------------------------------------
+
+def _as_quantization(quantization, block_size: int):
+    if quantization is None:
+        return 1
+    if isinstance(quantization, (int, np.integer)):
+        return int(quantization)
+    seq = list(quantization)
+    if seq and isinstance(seq[0], (list, tuple)):
+        return quantization_bands(seq, block_size)
+    return tuple(int(v) for v in seq)
+
+
+def compress(
+    image: ImageLike,
+    *,
+    keep: int | float | str = "all",
+    quantization: int | Sequence[int] | Sequence[Sequence[int]] | None = None,
+    block_size: int = 32,
+    image_size: int = 448,
+    use_ycrcb: bool = True,
+    subsampling: str = "1x1",
+    clevel: int = 9,
+    policy: DiagonalPolicy | None = None,
+    device: torch.device | str = "cpu",
+) -> EncodedImage:
+    """Truncate to ``keep`` diagonals, quantize per diagonal, and pack the compact payloads.
+
+    ``keep`` sets the pixel/token budget (tier 1). ``quantization``, ``use_ycrcb``,
+    ``subsampling`` and ``clevel`` set bytes per pixel (tier 2). ``policy`` is
+    the general form; when given, its ``keep``/``quantization``/``clevel`` win
+    over the keyword arguments they override (``None`` fields fall back).
+    """
+    cfg = CodecConfig(block_size, image_size, use_ycrcb, subsampling, _as_quantization(quantization, block_size), clevel)
+    if policy is None:
+        policy = DiagonalPolicy(keep=keep)
+    elif policy.keep == "all" and keep != "all":
+        policy = DiagonalPolicy(keep, policy.quantization, policy.transform, policy.clevel)
+    return Encoder(cfg, device).encode(image, policy)
+
+
+def load(path: str | Path) -> EncodedImage:
+    return EncodedImage.load(path)