imagecalculator 0.1.0__tar.gz

imagecalculator-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.icf
+/stores/
+/scratch/
+.venv/
+*.whl

imagecalculator-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (2026-11-08)
+
+Initial release.
+
+- Progressive block-DCT codec: `compress`, `decompress`, `Encoder`, `EncodedImage`, `.icf` container.
+- `keep` truncation to the first `k` anti-diagonals with reduced-native-size decode (`S*k/N` px).
+- Per-diagonal quantization (scalar, vector or bands), YCrCb + chroma subsampling, support-only storage, blosc/zstd payloads.
+- Token estimators for Anthropic, OpenAI and Google image pricing (`token_estimate`, `EncodedImage.savings`).
+- `imagecalculator compress | decompress | info` CLI.
+- Byte-exact compatibility with the research Frequency-Store dir stores when no `transform` is set.

imagecalculator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Can Gokmen
+
+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.

imagecalculator-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: imagecalculator
+Version: 0.1.0
+Summary: Progressive block-DCT image codec: truncate to the first k anti-diagonals, quantize per diagonal, decode at the reduced native size (Image Calculator / Frequency-Store)
+Project-URL: Homepage, https://github.com/cangokmen/imagecalculator
+Project-URL: Repository, https://github.com/cangokmen/imagecalculator
+Project-URL: Issues, https://github.com/cangokmen/imagecalculator/issues
+Author: Can Gokmen
+License: MIT
+License-File: LICENSE
+Keywords: dct,image-compression,progressive-codec,tokens,vision-language-models
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: blosc<2,>=1.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=9.0
+Requires-Dist: torch>=2.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# imagecalculator
+
+A progressive block-DCT image codec for sending images to vision models.
+
+**Truncation reduces your token count.** Keep only the first `k` anti-diagonals
+of each DCT block and decode them at the *reduced native size*: the model sees
+fewer pixels, and pixel-priced APIs (Claude, GPT, Gemini) charge fewer image
+tokens. Tokens scale with `(k/N)^2`.
+
+**Truncation + the other optimizations reduce your wifi cost.** Per-diagonal
+quantization, YCrCb with chroma subsampling, support-only (zero-free) storage
+and blosc/zstd entropy coding shrink the bytes that leave the device for the
+same pixels.
+
+The two levers are independent: `keep` sets the pixel/token budget, the rest
+sets bytes per pixel.
+
+```python
+import imagecalculator as ic
+
+enc = ic.compress("photo.jpg", keep=8, quantization=20)   # 8 of 63 diagonals (block 32, 448 px)
+enc.pixels            # (112, 112)  -> what the model will see
+enc.token_estimate()  # ~17 tokens on Anthropic (vs ~268 for the full 448 px image)
+enc.nbytes            # bytes over the air (.icf container)
+enc.save("photo.icf")
+
+img = ic.decompress(enc)                 # PIL image, 112 x 112, k-point inverse DCT per block
+img = ic.decompress(enc, size=224)       # any S*m/N with m >= k
+img = ic.decompress(enc, size="full")    # blurry full-size reconstruction (legacy behaviour)
+```
+
+### Sending it to Claude
+
+```python
+import os, anthropic, imagecalculator as ic
+
+enc = ic.compress("photo.jpg", keep=8, quantization=20)
+img = ic.decompress(enc)                                   # receiver side
+client = anthropic.Anthropic()
+r = client.messages.create(
+    model="claude-opus-5-5", max_tokens=1024,
+    messages=[{"role": "user", "content": [
+        {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ic.png_b64(img)}},
+        {"type": "text", "text": "What color is the bus?"},
+    ]}],
+)
+print("tokens:", r.usage.input_tokens, "(full image: ~268)")                      # tier 1: truncation
+print("bytes over wifi:", enc.nbytes, "(original JPEG:", os.path.getsize("photo.jpg"), ")")  # tier 2
+```
+
+`examples/compress_for_claude.py` runs the same question at `keep = 4, 8, 16, 32`
+and prints measured `usage.input_tokens` and bytes next to a Lanczos resize of
+the original to the same pixel size.
+
+### Honest framing
+
+A `k`-point inverse DCT of the low corner is a near-ideal low-pass filter
+followed by decimation. It carries the **same information as a good resize**
+(Lanczos / area) to that size, not more. What the format adds: one encoding
+serves every size, and bytes are competitive with a JPEG of the resized image.
+
+## Per-diagonal control (the adaptivity knobs)
+
+```python
+# scalar step, a per-diagonal vector, or [[from, to, q], ...] bands tiling [0, max_diag)
+enc = ic.compress("photo.jpg", keep=16, quantization=[[0, 8, 1], [8, 20, 10], [20, 63, 50]])
+
+# anything else per diagonal: a hook on the un-rounded (3, n_d) coefficients
+import torch
+def dead_zone(d, coeffs):            # drop tiny high-frequency coefficients
+    return coeffs if d < 8 else torch.where(coeffs.abs() < 30, torch.zeros_like(coeffs), coeffs)
+pol = ic.DiagonalPolicy(keep=16, quantization=20, transform=dead_zone, clevel=9)
+enc = ic.compress("photo.jpg", policy=pol)
+```
+
+## CLI
+
+```
+imagecalculator compress photo.jpg --keep 8 --quantization 20 [--block-size 32 --image-size 448] -o photo.icf
+imagecalculator decompress photo.icf [--size native|full|224] -o photo.png
+imagecalculator info photo.icf [--original photo.jpg]
+```
+
+`info` prints the config, then two lines: `tokens: 17 (full image 268, ...)` and
+`bytes over the air: 6.1 KiB (original file 182 KiB, ...)`.
+
+`compress` and `info` take `--provider anthropic | openai[:model] | google[:model]`
+and `--detail` (OpenAI `detail`, Gemini `media_resolution`); the same arguments
+go to `token_estimate()` / `EncodedImage.savings()`. Truncation only saves tokens
+where cost scales with pixels: Anthropic, OpenAI patch models (gpt-5.2 and
+later, gpt-4.1-mini; default `openai` = gpt-5.5) and Gemini 2.5 and earlier. Tile-priced OpenAI
+models (gpt-4o, gpt-4.1, gpt-5.1) bill a 448 px image as one 512 px tile, and
+Gemini 3/4 bill a fixed count per image (1120 by default), so `keep` doesn't
+change their token count, only bytes.
+
+## Install
+
+```
+pip install imagecalculator
+```
+
+`pip` pulls in a default torch build; to pick the CPU wheel (much smaller),
+install torch from the PyTorch index first:
+
+```
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+pip install imagecalculator
+```
+
+From a checkout: `pip install -e ".[dev]"` and `OMP_NUM_THREADS=4 pytest -q`.
+
+Dependencies: numpy, torch, blosc (1.x), Pillow.
+
+On a shared machine with many cores, set `OMP_NUM_THREADS` (or
+`torch.set_num_threads`) to a small number: the codec's tensors are small, and
+32 contending OpenMP threads turn a 2 ms encode into seconds.
+
+`quantization=1` stores the DCT coefficients as rounded integers (the
+research "q1" stores); a full decode is within 2 levels of the input (one from
+coefficient rounding, one from uint8 truncation), not bit-exact in pixel space.
+
+## Compatibility with the research Frequency-Store
+
+With no `transform`, `enc.payloads[d]` is byte-identical to the file
+`img_<i>/diag_<d>.col` of a research dir store built with the same config, and
+`decompress(enc, size="full")` reproduces the research reader's reconstruction
+exactly.

imagecalculator-0.1.0/README.md

@@ -0,0 +1,127 @@
+# imagecalculator
+
+A progressive block-DCT image codec for sending images to vision models.
+
+**Truncation reduces your token count.** Keep only the first `k` anti-diagonals
+of each DCT block and decode them at the *reduced native size*: the model sees
+fewer pixels, and pixel-priced APIs (Claude, GPT, Gemini) charge fewer image
+tokens. Tokens scale with `(k/N)^2`.
+
+**Truncation + the other optimizations reduce your wifi cost.** Per-diagonal
+quantization, YCrCb with chroma subsampling, support-only (zero-free) storage
+and blosc/zstd entropy coding shrink the bytes that leave the device for the
+same pixels.
+
+The two levers are independent: `keep` sets the pixel/token budget, the rest
+sets bytes per pixel.
+
+```python
+import imagecalculator as ic
+
+enc = ic.compress("photo.jpg", keep=8, quantization=20)   # 8 of 63 diagonals (block 32, 448 px)
+enc.pixels            # (112, 112)  -> what the model will see
+enc.token_estimate()  # ~17 tokens on Anthropic (vs ~268 for the full 448 px image)
+enc.nbytes            # bytes over the air (.icf container)
+enc.save("photo.icf")
+
+img = ic.decompress(enc)                 # PIL image, 112 x 112, k-point inverse DCT per block
+img = ic.decompress(enc, size=224)       # any S*m/N with m >= k
+img = ic.decompress(enc, size="full")    # blurry full-size reconstruction (legacy behaviour)
+```
+
+### Sending it to Claude
+
+```python
+import os, anthropic, imagecalculator as ic
+
+enc = ic.compress("photo.jpg", keep=8, quantization=20)
+img = ic.decompress(enc)                                   # receiver side
+client = anthropic.Anthropic()
+r = client.messages.create(
+    model="claude-opus-5-5", max_tokens=1024,
+    messages=[{"role": "user", "content": [
+        {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ic.png_b64(img)}},
+        {"type": "text", "text": "What color is the bus?"},
+    ]}],
+)
+print("tokens:", r.usage.input_tokens, "(full image: ~268)")                      # tier 1: truncation
+print("bytes over wifi:", enc.nbytes, "(original JPEG:", os.path.getsize("photo.jpg"), ")")  # tier 2
+```
+
+`examples/compress_for_claude.py` runs the same question at `keep = 4, 8, 16, 32`
+and prints measured `usage.input_tokens` and bytes next to a Lanczos resize of
+the original to the same pixel size.
+
+### Honest framing
+
+A `k`-point inverse DCT of the low corner is a near-ideal low-pass filter
+followed by decimation. It carries the **same information as a good resize**
+(Lanczos / area) to that size, not more. What the format adds: one encoding
+serves every size, and bytes are competitive with a JPEG of the resized image.
+
+## Per-diagonal control (the adaptivity knobs)
+
+```python
+# scalar step, a per-diagonal vector, or [[from, to, q], ...] bands tiling [0, max_diag)
+enc = ic.compress("photo.jpg", keep=16, quantization=[[0, 8, 1], [8, 20, 10], [20, 63, 50]])
+
+# anything else per diagonal: a hook on the un-rounded (3, n_d) coefficients
+import torch
+def dead_zone(d, coeffs):            # drop tiny high-frequency coefficients
+    return coeffs if d < 8 else torch.where(coeffs.abs() < 30, torch.zeros_like(coeffs), coeffs)
+pol = ic.DiagonalPolicy(keep=16, quantization=20, transform=dead_zone, clevel=9)
+enc = ic.compress("photo.jpg", policy=pol)
+```
+
+## CLI
+
+```
+imagecalculator compress photo.jpg --keep 8 --quantization 20 [--block-size 32 --image-size 448] -o photo.icf
+imagecalculator decompress photo.icf [--size native|full|224] -o photo.png
+imagecalculator info photo.icf [--original photo.jpg]
+```
+
+`info` prints the config, then two lines: `tokens: 17 (full image 268, ...)` and
+`bytes over the air: 6.1 KiB (original file 182 KiB, ...)`.
+
+`compress` and `info` take `--provider anthropic | openai[:model] | google[:model]`
+and `--detail` (OpenAI `detail`, Gemini `media_resolution`); the same arguments
+go to `token_estimate()` / `EncodedImage.savings()`. Truncation only saves tokens
+where cost scales with pixels: Anthropic, OpenAI patch models (gpt-5.2 and
+later, gpt-4.1-mini; default `openai` = gpt-5.5) and Gemini 2.5 and earlier. Tile-priced OpenAI
+models (gpt-4o, gpt-4.1, gpt-5.1) bill a 448 px image as one 512 px tile, and
+Gemini 3/4 bill a fixed count per image (1120 by default), so `keep` doesn't
+change their token count, only bytes.
+
+## Install
+
+```
+pip install imagecalculator
+```
+
+`pip` pulls in a default torch build; to pick the CPU wheel (much smaller),
+install torch from the PyTorch index first:
+
+```
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+pip install imagecalculator
+```
+
+From a checkout: `pip install -e ".[dev]"` and `OMP_NUM_THREADS=4 pytest -q`.
+
+Dependencies: numpy, torch, blosc (1.x), Pillow.
+
+On a shared machine with many cores, set `OMP_NUM_THREADS` (or
+`torch.set_num_threads`) to a small number: the codec's tensors are small, and
+32 contending OpenMP threads turn a 2 ms encode into seconds.
+
+`quantization=1` stores the DCT coefficients as rounded integers (the
+research "q1" stores); a full decode is within 2 levels of the input (one from
+coefficient rounding, one from uint8 truncation), not bit-exact in pixel space.
+
+## Compatibility with the research Frequency-Store
+
+With no `transform`, `enc.payloads[d]` is byte-identical to the file
+`img_<i>/diag_<d>.col` of a research dir store built with the same config, and
+`decompress(enc, size="full")` reproduces the research reader's reconstruction
+exactly.

imagecalculator-0.1.0/examples/compress_for_claude.py

@@ -0,0 +1,81 @@
+"""Tier 1 / tier 2 demo: ask Claude the same question at several `keep` values.
+
+    export ANTHROPIC_API_KEY=...   (or `ant auth login`)
+    python examples/compress_for_claude.py photo.jpg "What color is the bus?" --keep 4 8 16 32
+
+Prints, per `keep`: pixels, measured input tokens, bytes over the air, and the
+same for a Lanczos resize of the original to the same pixel size encoded as
+JPEG at the quality closest in bytes -- so the token claim (tier 1) and the
+byte claim (tier 2) are measured, not asserted.
+"""
+from __future__ import annotations
+
+import argparse
+import io
+import os
+
+import anthropic
+from PIL import Image
+
+import imagecalculator as ic
+
+MODEL = "claude-opus-5-5"
+
+
+def ask(client: anthropic.Anthropic, img: Image.Image, question: str) -> tuple[str, int]:
+    r = client.messages.create(
+        model=MODEL, max_tokens=512, output_config={"effort": "low"},
+        messages=[{"role": "user", "content": [
+            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ic.png_b64(img)}},
+            {"type": "text", "text": question},
+        ]}],
+    )
+    if r.stop_reason == "refusal":
+        raise RuntimeError(f"refused: {r.stop_details}")
+    text = next((b.text for b in r.content if b.type == "text"), "")
+    return text.strip(), r.usage.input_tokens
+
+
+def jpeg_at_bytes(img: Image.Image, target: int) -> tuple[bytes, int]:
+    """Smallest-quality JPEG whose size is >= target (the fair byte competitor)."""
+    best = None
+    for q in range(5, 96, 5):
+        buf = io.BytesIO()
+        img.save(buf, format="JPEG", quality=q)
+        b = buf.getvalue()
+        best = (b, q)
+        if len(b) >= target:
+            break
+    return best  # type: ignore[return-value]
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("image")
+    ap.add_argument("question")
+    ap.add_argument("--keep", type=int, nargs="+", default=[4, 8, 16, 32])
+    ap.add_argument("--quantization", type=int, default=20)
+    ap.add_argument("--block-size", type=int, default=32)
+    ap.add_argument("--image-size", type=int, default=448)
+    a = ap.parse_args()
+
+    client = anthropic.Anthropic()
+    original = Image.open(a.image).convert("RGB")
+    orig_bytes = os.path.getsize(a.image)
+    full = original.resize((a.image_size, a.image_size), Image.BILINEAR)
+    ans, toks = ask(client, full, a.question)
+    print(f"full {a.image_size}px: tokens={toks:4d} bytes={orig_bytes:7d}  -> {ans!r}")
+    print()
+    print(f"{'keep':>4} {'px':>4} | {'IC tokens':>9} {'IC bytes':>8} | {'resize tokens':>13} {'JPEG bytes':>10} q | answers")
+    for k in a.keep:
+        enc = ic.compress(a.image, keep=k, quantization=a.quantization, block_size=a.block_size, image_size=a.image_size)
+        img = ic.decompress(enc)
+        ans_ic, tok_ic = ask(client, img, a.question)
+        small = original.resize(enc.pixels, Image.LANCZOS)
+        jpg, q = jpeg_at_bytes(small, enc.nbytes)
+        ans_rs, tok_rs = ask(client, Image.open(io.BytesIO(jpg)), a.question)
+        print(f"{k:>4} {enc.pixels[0]:>4} | {tok_ic:>9} {enc.nbytes:>8} | {tok_rs:>13} {len(jpg):>10} {q:>2} | {ans_ic!r} / {ans_rs!r}")
+
+
+if __name__ == "__main__":
+    main()

imagecalculator-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "imagecalculator"
+dynamic = ["version"]
+description = "Progressive block-DCT image codec: truncate to the first k anti-diagonals, quantize per diagonal, decode at the reduced native size (Image Calculator / Frequency-Store)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Can Gokmen" }]
+keywords = ["image-compression", "dct", "vision-language-models", "tokens", "progressive-codec"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=1.24",
+    "torch>=2.1",
+    "blosc>=1.10,<2",
+    "pillow>=9.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/cangokmen/imagecalculator"
+Repository = "https://github.com/cangokmen/imagecalculator"
+Issues = "https://github.com/cangokmen/imagecalculator/issues"
+
+[project.scripts]
+imagecalculator = "imagecalculator.cli:main"
+
+[tool.hatch.version]
+path = "src/imagecalculator/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/imagecalculator"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/imagecalculator",
+    "tests",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "pyproject.toml",
+]
+exclude = ["**/__pycache__"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

imagecalculator-0.1.0/src/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-0.1.0/src/imagecalculator/_version.py

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

imagecalculator-0.1.0/src/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])