pbc3.0 first update

.gitignore

@@ -0,0 +1,2 @@
+# macos
+.DS_Store

PBC3.py

@@ -0,0 +1,1003 @@
+
+# ====================================================================================================
+#
+#           PBC v3.0 - Probabilistic Brush Compression
+#           Lossy Image Compression Algorithm by EgeEken (github.com/EgeEken)
+#           3.0 Update - 2026-06 - Whole algorithm overhaul
+#
+# ====================================================================================================
+
+import time
+import math
+import lzma
+import numpy as np
+from PIL import Image
+
+from pbc3_types import BitWriter, BitReader, PBC3Config, PBC3Result  # noqa: F401 (re-exported)
+from pbc3_kernels import (
+    NUMBA_AVAILABLE as _NUMBA,
+    box_cell_bound as _nb_box_cell_bound,
+    base_cell_size as _nb_base_cell_size,
+    anchor_block_scores as _nb_anchor_block_scores,
+)
+
+
+class PBC3:
+    MAGIC = b"PBC3"
+    VERSION = 0
+    PALETTE_GENERATED = 0
+    PALETTE_EXPLICIT = 1
+    ENTROPY_STORE = 0
+    ENTROPY_LZMA = 2
+    _LZMA_FILTERS = [{"id": lzma.FILTER_LZMA2, "preset": lzma.PRESET_EXTREME}]
+    COLOR_SPACES = {"RGB": 0, "YCbCr": 1}
+    COLOR_SPACE_NAMES = {0: "RGB", 1: "YCbCr"}
+    RESAMPLE_FILTER = Image.Resampling.BICUBIC
+    RESAMPLE_REDUCING_GAP = None
+    USE_NUMBA_RESAMPLE = False  # opt-in numba bicubic (pbc3_resample.py); PIL by default
+
+    @staticmethod
+    def _to_image(image):
+        if isinstance(image, Image.Image):
+            return image
+        if isinstance(image, str):
+            return Image.open(image)
+        arr = np.asarray(image)
+        if arr.dtype != np.uint8:
+            arr = np.clip(arr, 0, 255).astype(np.uint8)
+        mode = "RGBA" if arr.ndim == 3 and arr.shape[-1] == 4 else "RGB"
+        return Image.fromarray(arr, mode)
+
+    @staticmethod
+    def _has_alpha(img):
+        return img.mode in ("RGBA", "LA", "PA") or (img.mode == "P" and "transparency" in img.info)
+
+    @staticmethod
+    def _ceil_div(a, b):
+        return (a + b - 1) // b
+
+    @staticmethod
+    def _add_time(timings, key, seconds):
+        timings[key] = timings.get(key, 0.0) + seconds
+
+    @staticmethod
+    def _norm(values):
+        arr = np.asarray(values, dtype=np.float64)
+        rng = arr.max() - arr.min()
+        if rng <= 0:
+            return np.ones_like(arr)
+        return (arr - arr.min()) / rng
+
+    @staticmethod
+    def _interp(start, end, step, count):
+        if count <= 1:
+            return float(end)
+        p = (step - 1) / max(1, count - 1)
+        return float(start) * (1 - p) + float(end) * p
+
+    @classmethod
+    def _entropy_pack(cls, body, use_lzma=True):
+        if not use_lzma:
+            return cls.ENTROPY_STORE, body
+        x = lzma.compress(body, format=lzma.FORMAT_RAW, filters=cls._LZMA_FILTERS)
+        if len(x) < len(body):
+            return cls.ENTROPY_LZMA, x
+        return cls.ENTROPY_STORE, body
+
+    @classmethod
+    def _entropy_unpack(cls, method, body):
+        if method == cls.ENTROPY_STORE:
+            return body
+        if method == cls.ENTROPY_LZMA:
+            return lzma.decompress(body, format=lzma.FORMAT_RAW, filters=cls._LZMA_FILTERS)
+        raise ValueError(f"unknown entropy method {method}")
+
+    @classmethod
+    def _open_body(cls, data):
+        if data[:4] != cls.MAGIC:
+            raise ValueError("not a PBC3 file")
+        version = data[4]
+        if version != cls.VERSION:
+            raise ValueError(f"unsupported PBC3 version {version}")
+        return version, cls._entropy_unpack(data[5], data[6:])
+
+    @classmethod
+    def _auto_downsample_rate(cls, image_size, downsample_rate, max_pixels):
+        if downsample_rate != -1:
+            return float(downsample_rate)
+        w, h = image_size
+        pixels = w * h
+        max_pixels = max(1, int(max_pixels))
+        if pixels <= max_pixels:
+            return 1.0
+        return math.sqrt(pixels / max_pixels)
+
+    @classmethod
+    def _downsample_image(cls, img, rate):
+        if rate <= 1:
+            return img.copy()
+        w = max(1, int(round(img.size[0] / rate)))
+        h = max(1, int(round(img.size[1] / rate)))
+        return img.resize((w, h), cls.RESAMPLE_FILTER, reducing_gap=cls.RESAMPLE_REDUCING_GAP)
+
+    @staticmethod
+    def _palette_bounds(values):
+        min_value = int(np.min(values))
+        max_value = int(np.max(values))
+        return min(255, max(0, -min_value)), min(255, max(0, max_value))
+
+    @classmethod
+    def _range_counts(cls, mask_size, negative_max=255, positive_max=255, positive_bias=True):
+        side_bits = max(0, mask_size - 1)
+        negative_max = max(0, int(negative_max))
+        positive_max = max(0, int(positive_max))
+        if side_bits == 0 or (negative_max == 0 and positive_max == 0):
+            return 0, 0
+        if negative_max == 0:
+            return min(side_bits, positive_max), 0
+        if positive_max == 0:
+            return 0, min(side_bits, negative_max)
+        raw_pos = side_bits * positive_max / (positive_max + negative_max)
+        pos_count = math.ceil(raw_pos) if positive_bias else math.floor(raw_pos)
+        pos_count = min(side_bits - 1, max(1, pos_count), positive_max)
+        neg_count = min(side_bits - pos_count, negative_max)
+        if neg_count == 0 and negative_max > 0 and side_bits > pos_count:
+            neg_count = 1
+            pos_count = max(1, pos_count - 1)
+        return pos_count, neg_count
+
+    @classmethod
+    def _mask_index_for_value(cls, value, mask_size, negative_max=255, positive_max=255, positive_bias=True):
+        if value == 0:
+            return 0
+        pos_count, neg_count = cls._range_counts(mask_size, negative_max, positive_max, positive_bias)
+        if value > 0:
+            if pos_count == 0 or positive_max <= 0:
+                return None
+            mag = min(int(value), positive_max)
+            bin_i = min((mag - 1) * pos_count // positive_max, pos_count - 1)
+            return 1 + bin_i
+        if neg_count == 0 or negative_max <= 0:
+            return None
+        mag = min(int(-value), negative_max)
+        bin_i = min((mag - 1) * neg_count // negative_max, neg_count - 1)
+        return 1 + pos_count + bin_i
+
+    @classmethod
+    def _range_for_mask_index(cls, index, mask_size, negative_max=255, positive_max=255, positive_bias=True):
+        pos_count, neg_count = cls._range_counts(mask_size, negative_max, positive_max, positive_bias)
+        if index == 0:
+            return 0, 0
+        if 1 <= index <= pos_count:
+            bin_i = index - 1
+            start = 1 + (bin_i * positive_max) // pos_count
+            end = ((bin_i + 1) * positive_max) // pos_count
+            return (start, end) if start <= end else None
+        bin_i = index - 1 - pos_count
+        if 0 <= bin_i < neg_count:
+            low_mag = 1 + (bin_i * negative_max) // neg_count
+            high_mag = ((bin_i + 1) * negative_max) // neg_count
+            return (-high_mag, -low_mag) if high_mag >= low_mag else None
+        return None
+
+    @classmethod
+    def _mask_from_values(cls, values, mask_size, negative_max=255, positive_max=255, positive_bias=True):
+        mask = [0] * mask_size
+        mask[0] = 1
+        pos_count, neg_count = cls._range_counts(mask_size, negative_max, positive_max, positive_bias)
+        flat = np.clip(np.rint(np.asarray(values)).astype(np.int32).ravel(), -negative_max, positive_max)
+        if pos_count > 0 and positive_max > 0:
+            pos = flat[flat > 0]
+            if pos.size:
+                bins = 1 + np.minimum((np.minimum(pos, positive_max) - 1) * pos_count // positive_max, pos_count - 1)
+                for b in np.unique(bins):
+                    if b < mask_size:
+                        mask[int(b)] = 1
+        if neg_count > 0 and negative_max > 0:
+            neg = flat[flat < 0]
+            if neg.size:
+                mag = np.minimum(-neg, negative_max)
+                bins = 1 + pos_count + np.minimum((mag - 1) * neg_count // negative_max, neg_count - 1)
+                for b in np.unique(bins):
+                    if b < mask_size:
+                        mask[int(b)] = 1
+        return mask
+
+    @classmethod
+    def _active_value_count(cls, mask, negative_max=255, positive_max=255, positive_bias=True):
+        count = 0
+        for i, bit in enumerate(mask):
+            if bit:
+                r = cls._range_for_mask_index(i, len(mask), negative_max, positive_max, positive_bias)
+                if r is not None:
+                    start, end = r
+                    count += end - start + 1
+        return max(1, count)
+
+    @classmethod
+    def resolve_palette_bitcount(cls, mask, max_bitcount, negative_max=255, positive_max=255, positive_bias=True):
+        value_count = cls._active_value_count(mask, negative_max, positive_max, positive_bias)
+        needed = max(1, math.ceil(math.log2(value_count)))
+        return min(int(max_bitcount), needed)
+
+    @classmethod
+    def palette_generator(cls, mask, max_bitcount, negative_max=255, positive_max=255, positive_bias=True):
+        bitcount = cls.resolve_palette_bitcount(mask, max_bitcount, negative_max, positive_max, positive_bias)
+        size = 1 << bitcount
+        active_ranges = []
+        for i, bit in enumerate(mask):
+            if bit:
+                r = cls._range_for_mask_index(i, len(mask), negative_max, positive_max, positive_bias)
+                if r is not None:
+                    active_ranges.append(r)
+        palette = []
+        if mask and mask[0]:
+            palette.append(0)
+            active_ranges = [r for r in active_ranges if r != (0, 0)]
+        value_count = cls._active_value_count(mask, negative_max, positive_max, positive_bias)
+        if size >= value_count:
+            for start, end in active_ranges:
+                palette.extend(range(start, end + 1))
+            if len(palette) < size:
+                palette.extend([palette[-1] if palette else 0] * (size - len(palette)))
+            return np.array(palette[:size], dtype=np.int16)
+        if not active_ranges:
+            return np.zeros(size, dtype=np.int16)
+        remaining = size - len(palette)
+        counts = [0] * len(active_ranges)
+        for i in range(remaining):
+            counts[i % len(active_ranges)] += 1
+        for (start, end), count in zip(active_ranges, counts):
+            if count == 1:
+                palette.append(int(round((start + end) / 2)))
+            elif count > 1:
+                for j in range(count):
+                    t = (j + 1) / (count + 1)
+                    palette.append(int(round(start + (end - start) * t)))
+        if len(palette) < size:
+            palette.extend([palette[-1] if palette else 0] * (size - len(palette)))
+        return np.array(palette[:size], dtype=np.int16)
+
+    @classmethod
+    def _top_values_palette(cls, small, bitcount, threshold):
+        size = 1 << bitcount
+        flat = np.clip(np.rint(np.asarray(small)).astype(np.int32).ravel(), -255, 255)
+        vals, counts = np.unique(flat, return_counts=True)
+        centroids = [0.0]
+        binw = max(1, int(threshold))
+        agg = {}
+        for v, ct in zip(np.round(vals / binw) * binw, counts):
+            agg[float(v)] = agg.get(float(v), 0) + int(ct)
+        for v in sorted((k for k in agg if k != 0.0), key=lambda k: agg[k], reverse=True):
+            centroids.append(v)
+            if len(centroids) >= size:
+                break
+        centroids = np.array(centroids, dtype=np.float64)
+        if centroids.size > 1 and vals.size:
+            w = counts.astype(np.float64)
+            for _ in range(8):
+                assign = np.argmin(np.abs(vals[:, None] - centroids[None, :]), axis=1)
+                new = centroids.copy()
+                for k in range(centroids.size):
+                    sel = assign == k
+                    wk = w[sel].sum()
+                    if wk > 0:
+                        new[k] = float((vals[sel] * w[sel]).sum() / wk)
+                new[0] = 0.0
+                if np.array_equal(np.rint(new), np.rint(centroids)):
+                    centroids = new
+                    break
+                centroids = new
+        pal = np.rint(centroids).astype(np.int16)
+        if pal.size < size:
+            pal = np.concatenate([pal, np.zeros(size - pal.size, dtype=np.int16)])
+        return pal[:size]
+
+    @staticmethod
+    def quantize_signed(values, palette):
+        vals = np.asarray(values, dtype=np.int16)
+        pal = np.asarray(palette, dtype=np.int16)
+        dist = np.abs(vals[..., None].astype(np.int32) - pal[None, None, :].astype(np.int32))
+        return np.argmin(dist, axis=-1).astype(np.uint16)
+
+    @classmethod
+    def signed_resample(cls, values, out_h, out_w):
+        values = np.asarray(values, dtype=np.float32)
+        out_h, out_w = int(out_h), int(out_w)
+        if values.shape == (out_h, out_w):
+            return np.rint(values).astype(np.int16)
+        if cls.USE_NUMBA_RESAMPLE:
+            from pbc3_resample import resample_bicubic
+            out = resample_bicubic(values, out_h, out_w)
+        else:
+            resized = Image.fromarray(values).resize((out_w, out_h), cls.RESAMPLE_FILTER, reducing_gap=cls.RESAMPLE_REDUCING_GAP)
+            out = np.asarray(resized, dtype=np.float32)
+        return np.rint(out).astype(np.int16)
+
+    @classmethod
+    def signed_resample_cells(cls, values, cell_size):
+        h, w = values.shape
+        return cls.signed_resample(values, cls._ceil_div(h, cell_size), cls._ceil_div(w, cell_size))
+
+    @classmethod
+    def apply_grid(cls, canvas_layer, x, y, w, h, cell_size, values):
+        patch = cls.signed_resample(values, h, w).astype(np.int32)
+        canvas_layer[y:y + h, x:x + w] += patch
+
+    @staticmethod
+    def _integral(a):
+        return np.pad(a.astype(np.int64).cumsum(0).cumsum(1), ((1, 0), (1, 0)))
+
+    @classmethod
+    def _cell_edges(cls, start, length, cell_size):
+        n = cls._ceil_div(length, cell_size)
+        edges = start + np.arange(n + 1) * cell_size
+        edges[n] = start + length
+        return edges
+
+    @classmethod
+    def _box_cell_bound(cls, integral, x, y, bw, bh, cell_size):
+        if _NUMBA:
+            return _nb_box_cell_bound(np.ascontiguousarray(integral, dtype=np.int64),
+                                      int(x), int(y), int(bw), int(bh), int(cell_size))
+        xe = cls._cell_edges(x, bw, cell_size)
+        ye = cls._cell_edges(y, bh, cell_size)
+        corners = integral[np.ix_(ye, xe)].astype(np.float64)
+        cell_sum = corners[1:, 1:] - corners[:-1, 1:] - corners[1:, :-1] + corners[:-1, :-1]
+        counts = (np.diff(ye)[:, None] * np.diff(xe)[None, :]).astype(np.float64)
+        return float(np.sum(cell_sum * cell_sum / counts))
+
+    @classmethod
+    def _write_grid(cls, bw, flat, bitcount):
+        for value in flat:
+            bw.write(int(value), bitcount)
+
+    @classmethod
+    def _read_grid(cls, br, n, bitcount):
+        flat = np.zeros(n, dtype=np.uint16)
+        for k in range(n):
+            flat[k] = br.read(bitcount)
+        return flat
+
+    @classmethod
+    def _patch_bits_for(cls, patch, channel_bits):
+        w, h, cell = patch["w"], patch["h"], patch["cell_size"]
+        bitcount = patch["bitcount"]
+        grid_bits = cls._ceil_div(w, cell) * cls._ceil_div(h, cell) * bitcount
+        base = channel_bits + 64 + 16 + 1
+        if patch["palette_mode"] == cls.PALETTE_EXPLICIT:
+            header = base + 4 + (1 << bitcount) * 9
+        else:
+            header = base + 10 + len(patch["mask"]) + 8 + 8 + 4
+        return header + grid_bits
+
+    @classmethod
+    def _patch_header_bits(cls, channel_bits, mask_size):
+        return channel_bits + 64 + 10 + mask_size + 8 + 8 + 4 + 16 + 1
+
+    @classmethod
+    def _palette_threshold(cls, config, step):
+        base = int(config.palette_difference_threshold)
+        if base <= 0:
+            return 0
+        if str(config.palette_difference_threshold_mode).lower() != "linear" or config.patch_count <= 1:
+            return base
+        progress = (step - 1) / max(1, config.patch_count - 1)
+        if progress >= 0.9:
+            return 0
+        return int(round(base * (1 - progress / 0.9)))
+
+    @classmethod
+    def _palette_mode_options(cls, config, bitcount):
+        mode = str(config.palette_mode).lower()
+        if mode == "generated":
+            return [cls.PALETTE_GENERATED]
+        if mode == "explicit":
+            return [cls.PALETTE_EXPLICIT]
+        opts = [cls.PALETTE_GENERATED]
+        if bitcount <= int(config.explicit_palette_max_bitcount):
+            opts.append(cls.PALETTE_EXPLICIT)
+        return opts
+
+    @classmethod
+    def _channel_error_score(cls, target, canvas, channel, mode):
+        err = np.abs(target[:, :, channel] - np.clip(canvas[:, :, channel], 0, 255))
+        if str(mode).lower() == "max":
+            return float(np.max(err))
+        return float(np.sum(err))
+
+    @classmethod
+    def _choose_channel(cls, scores, step, channels, mode):
+        mode = str(mode).lower()
+        if mode in {"sum", "max"}:
+            return int(max(range(channels), key=lambda c: scores[c]))
+        return (step - 1) % channels
+
+    @classmethod
+    def _write_patch(cls, bw, patch, channel_bits):
+        bw.write(patch["channel"], channel_bits)
+        bw.write(patch["x"], 16)
+        bw.write(patch["y"], 16)
+        bw.write(patch["w"], 16)
+        bw.write(patch["h"], 16)
+        pm = patch["palette_mode"]
+        bw.write(pm, 1)
+        bitcount = patch["bitcount"]
+        if pm == cls.PALETTE_EXPLICIT:
+            bw.write(bitcount, 4)
+            for v in patch["palette"]:
+                bw.write(int(v) & 0x1FF, 9)
+        else:
+            mask = patch["mask"]
+            bw.write(len(mask), 10)
+            for bit in mask:
+                bw.write(bit, 1)
+            bw.write(patch["neg"], 8)
+            bw.write(patch["pos"], 8)
+            bw.write(patch["max_bitcount"], 4)
+        flat = patch["indices"].ravel().astype(np.int64)
+        bw.write(patch["cell_size"], 16)
+        cls._write_grid(bw, flat, bitcount)
+
+    @classmethod
+    def _read_patch(cls, br, channel_bits, positive_bias=True):
+        channel = br.read(channel_bits)
+        x = br.read(16)
+        y = br.read(16)
+        w = br.read(16)
+        h = br.read(16)
+        pm = br.read(1)
+        if pm == cls.PALETTE_EXPLICIT:
+            bitcount = br.read(4)
+            size = 1 << bitcount
+            palette = np.empty(size, dtype=np.int16)
+            for i in range(size):
+                raw = br.read(9)
+                palette[i] = raw - 512 if raw >= 256 else raw
+        else:
+            mask_size = br.read(10)
+            mask = [br.read(1) for _ in range(mask_size)]
+            negative_max = br.read(8)
+            positive_max = br.read(8)
+            max_bitcount = br.read(4)
+            bitcount = cls.resolve_palette_bitcount(mask, max_bitcount, negative_max, positive_max, positive_bias)
+            palette = cls.palette_generator(mask, max_bitcount, negative_max, positive_max, positive_bias)
+        cell_size = br.read(16)
+        gw = cls._ceil_div(w, cell_size)
+        gh = cls._ceil_div(h, cell_size)
+        flat = cls._read_grid(br, gh * gw, bitcount)
+        indices = flat.reshape(gh, gw)
+        values = palette[indices]
+        return channel, x, y, w, h, cell_size, values
+
+    @classmethod
+    def _make_patch(cls, channel, x, y, w, h, cell_size, residual, config, max_bitcount, palette_mode, threshold):
+        small = cls.signed_resample_cells(residual, cell_size)
+        if palette_mode == cls.PALETTE_EXPLICIT:
+            bitcount = int(max_bitcount)
+            palette = cls._top_values_palette(small, bitcount, threshold)
+            indices = cls.quantize_signed(np.clip(small, -255, 255), palette)
+            values = palette[indices]
+            return {
+                "channel": channel, "x": x, "y": y, "w": w, "h": h, "cell_size": cell_size,
+                "indices": indices, "palette_mode": cls.PALETTE_EXPLICIT,
+                "palette": palette, "bitcount": bitcount,
+                "mask": None, "neg": 0, "pos": 0, "max_bitcount": bitcount,
+            }, values
+        negative_max, positive_max = cls._palette_bounds(small)
+        mask = cls._mask_from_values(small, config.mask_size, negative_max, positive_max, config.positive_bias)
+        palette = cls.palette_generator(mask, max_bitcount, negative_max, positive_max, config.positive_bias)
+        indices = cls.quantize_signed(np.clip(small, -negative_max, positive_max), palette)
+        values = palette[indices]
+        bitcount = cls.resolve_palette_bitcount(mask, max_bitcount, negative_max, positive_max, config.positive_bias)
+        return {
+            "channel": channel, "x": x, "y": y, "w": w, "h": h, "cell_size": cell_size,
+            "indices": indices, "palette_mode": cls.PALETTE_GENERATED,
+            "palette": None, "bitcount": bitcount,
+            "mask": mask, "neg": negative_max, "pos": positive_max, "max_bitcount": max_bitcount,
+        }, values
+
+    @classmethod
+    def _top_anchors(cls, visible_error_channel, top_k, block_size, channel):
+        h, w = visible_error_channel.shape
+        block_size = max(1, int(block_size))
+        if block_size == 1:
+            flat = visible_error_channel.reshape(-1)
+            k = min(int(top_k), flat.size)
+            idx = np.argpartition(flat, -k)[-k:]
+            idx = idx[np.argsort(flat[idx])[::-1]]
+            return [(channel, int(i) // w, int(i) % w) for i in idx]
+        if _NUMBA:
+            scores, ys, xs = _nb_anchor_block_scores(np.ascontiguousarray(visible_error_channel, dtype=np.float64), block_size)
+            if scores.size == 0:
+                return []
+            k = min(int(top_k), scores.size)
+            idx = np.argpartition(scores, -k)[-k:]
+            order = idx[np.argsort(scores[idx])[::-1]]
+            return [(channel, int(ys[i]), int(xs[i])) for i in order]
+        anchors = []
+        ii = np.pad(visible_error_channel.cumsum(axis=0).cumsum(axis=1), ((1, 0), (1, 0)))
+        for y0 in range(0, h, block_size):
+            y1 = min(h, y0 + block_size)
+            for x0 in range(0, w, block_size):
+                x1 = min(w, x0 + block_size)
+                s = ii[y1, x1] - ii[y0, x1] - ii[y1, x0] + ii[y0, x0]
+                anchors.append((float(s / ((y1 - y0) * (x1 - x0))), channel, (y0 + y1 - 1) // 2, (x0 + x1 - 1) // 2))
+        if not anchors:
+            return []
+        k = min(int(top_k), len(anchors))
+        idx = np.argpartition(np.array([a[0] for a in anchors]), -k)[-k:]
+        selected = [anchors[i] for i in idx]
+        selected.sort(key=lambda a: a[0], reverse=True)
+        return [(c, y, x) for _, c, y, x in selected]
+
+    @classmethod
+    def _sample_box(cls, rng, anchor, image_w, image_h, config):
+        c, ay, ax = anchor
+        min_size = max(1, int(config.min_patch_size))
+        max_w = max(min_size, min(int(config.max_patch_size), image_w))
+        max_h = max(min_size, min(int(config.max_patch_size), image_h))
+        w = int(round(2 ** rng.uniform(math.log2(min_size), math.log2(max_w))))
+        h = int(round(2 ** rng.uniform(math.log2(min_size), math.log2(max_h))))
+        w = min(max(1, w), image_w)
+        h = min(max(1, h), image_h)
+        x_min = max(0, ax - w + 1)
+        x_max = min(ax, image_w - w)
+        y_min = max(0, ay - h + 1)
+        y_max = min(ay, image_h - h)
+        x = int(rng.integers(x_min, x_max + 1)) if x_min <= x_max else max(0, min(ax, image_w - w))
+        y = int(rng.integers(y_min, y_max + 1)) if y_min <= y_max else max(0, min(ay, image_h - h))
+        return c, x, y, w, h, ax, ay
+
+    @classmethod
+    def _base_cell_size(cls, residual_patch, config):
+        if _NUMBA and residual_patch.size:
+            return int(_nb_base_cell_size(np.ascontiguousarray(residual_patch, dtype=np.float64), int(config.max_cell_size)))
+        mean_abs = float(np.mean(np.abs(residual_patch))) if residual_patch.size else 0.0
+        if mean_abs <= 0:
+            return int(config.max_cell_size)
+        gx = float(np.mean(np.abs(np.diff(residual_patch, axis=1)))) if residual_patch.shape[1] > 1 else 0.0
+        gy = float(np.mean(np.abs(np.diff(residual_patch, axis=0)))) if residual_patch.shape[0] > 1 else 0.0
+        ratio = (gx + gy) / (mean_abs + 1.0)
+        if ratio < 0.25:
+            return 32
+        if ratio < 0.5:
+            return 16
+        if ratio < 1.0:
+            return 8
+        return 4
+
+    @classmethod
+    def _candidate_cell_sizes(cls, base, config):
+        offsets = [0, 1, -1, 2, -2, 3, -3]
+        cells = []
+        for off in offsets:
+            if len(cells) >= max(1, int(config.cell_sizes_per_candidate)):
+                break
+            cell = int(round(base * (2 ** off)))
+            cell = max(int(config.min_cell_size), min(int(config.max_cell_size), cell))
+            if cell not in cells:
+                cells.append(cell)
+        return cells
+
+    @classmethod
+    def _patch_bitcounts(cls, config):
+        if str(config.patch_bitcount_mode).lower() != "dynamic":
+            return [int(config.patch_palette_bitcount)]
+        lo = max(1, min(9, int(config.dynamic_patch_bitcount_min)))
+        hi = max(lo, min(9, int(config.dynamic_patch_bitcount_max)))
+        return list(range(lo, hi + 1))
+
+    @classmethod
+    def _auto_init_candidates(cls, residual, w, h, config):
+        mean_abs = float(np.mean(np.abs(residual))) + 1.0
+        gx = float(np.mean(np.abs(np.diff(residual, axis=1)))) if residual.shape[1] > 1 else 0.0
+        gy = float(np.mean(np.abs(np.diff(residual, axis=0)))) if residual.shape[0] > 1 else 0.0
+        freq = (gx + gy) / mean_abs
+        std = float(np.std(residual))
+        if freq >= 1.0:
+            cell0 = 4
+        elif freq >= 0.5:
+            cell0 = 8
+        elif freq >= 0.25:
+            cell0 = 12
+        elif freq >= 0.12:
+            cell0 = 16
+        else:
+            cell0 = 24
+        if std < 6:
+            bits0 = 3
+        elif std < 12:
+            bits0 = 4
+        elif std < 24:
+            bits0 = 5
+        else:
+            bits0 = 6
+        lo_c, hi_c = max(1, int(config.min_cell_size)), min(int(config.max_cell_size), max(w, h))
+        max_b = int(config.downsample_palette_bitcount)
+        clampc = lambda v: max(lo_c, min(hi_c, int(v)))
+        clampb = lambda v: max(1, min(max_b, int(v)))
+        raw = [(cell0, bits0), (cell0, bits0 - 1), (cell0, bits0 + 1),
+               (cell0 // 2, bits0), (cell0 * 2, bits0), (cell0 // 2, bits0 - 1),
+               (cell0 * 2, bits0 + 1), (cell0 // 4, bits0), (cell0 * 4, bits0),
+               (cell0 // 2, bits0 + 1), (cell0 * 2, bits0 - 1), (cell0, bits0 + 2),
+               (cell0, bits0 - 2), (cell0 // 4, bits0 + 1), (cell0 * 4, bits0 - 1)]
+        out = []
+        for cell, bits in raw:
+            pair = (clampc(cell), clampb(bits))
+            if pair not in out:
+                out.append(pair)
+        return out
+
+    @classmethod
+    def _select_init(cls, c, target, canvas, w, h, config, channel_bits):
+        base_layer = canvas[:, :, c]
+        residual = target[:, :, c] - base_layer
+        before = target[:, :, c] - np.clip(base_layer, 0, 255)
+        before_sse = float(np.sum(before.astype(np.int64) ** 2))
+        cands = cls._auto_init_candidates(residual, w, h, config)[:max(1, int(config.init_search_depth))]
+        reductions, bit_costs, built = [], [], []
+        for cell, bits in cands:
+            patch, values = cls._make_patch(c, 0, 0, w, h, cell, residual, config, bits, cls.PALETTE_GENERATED, 0)
+            delta = cls.signed_resample(values, h, w).astype(np.int32)
+            after = target[:, :, c] - np.clip(base_layer + delta, 0, 255)
+            reductions.append(before_sse - float(np.sum(after.astype(np.int64) ** 2)))
+            bit_costs.append(cls._patch_bits_for(patch, channel_bits))
+            built.append((patch, values, cell, bits))
+        q = float(config.q_init)
+        scores = q * cls._norm(reductions) - (1.0 - q) * cls._norm(bit_costs)
+        return built[int(np.argmax(scores))]
+
+    @classmethod
+    def _debug_line(cls, kind, **items):
+        return kind + " " + " ".join(f"{k}={v}" for k, v in items.items())
+
+    @classmethod
+    def _select_patch(cls, target, canvas, config, rng, channel_bits, step, canvas_patches, debug_lines, timings, current_channel):
+        t = time.perf_counter()
+        visible_canvas_channel = np.clip(canvas[:, :, current_channel], 0, 255).astype(np.int32)
+        visible_error = (target[:, :, current_channel] - visible_canvas_channel).astype(np.int64)
+        abs_error = np.abs(visible_error)
+        integral_signed = cls._integral(visible_error)
+        integral_abs = cls._integral(abs_error)
+        cls._add_time(timings, "visible_error", time.perf_counter() - t)
+
+        q = cls._interp(config.q_start, config.q_end, step, config.patch_count)
+        search_q = cls._interp(config.search_q_start, config.search_q_end, step, config.patch_count)
+        threshold = cls._palette_threshold(config, step)
+
+        t = time.perf_counter()
+        anchors = cls._top_anchors(abs_error.astype(np.float32), config.top_k, config.anchor_block_size, current_channel)
+        cls._add_time(timings, "anchors", time.perf_counter() - t)
+        if not anchors:
+            return None, None
+
+        h, w, _ = target.shape
+        box_sums, box_areas, box_specs = [], [], []
+        t = time.perf_counter()
+        for i in range(max(1, int(config.search_depth))):
+            c, x, y, bw, bh, ax, ay = cls._sample_box(rng, anchors[i % len(anchors)], w, h, config)
+            box_sum = integral_abs[y + bh, x + bw] - integral_abs[y, x + bw] - integral_abs[y + bh, x] + integral_abs[y, x]
+            if box_sum <= 0:
+                continue
+            box_sums.append(float(box_sum))
+            box_areas.append(float(bw * bh))
+            box_specs.append((c, x, y, bw, bh))
+        cls._add_time(timings, "search_prescore", time.perf_counter() - t)
+        if not box_specs:
+            return None, None
+        pre_scores = search_q * cls._norm(box_sums) - (1.0 - search_q) * cls._norm(box_areas)
+        keep = np.argsort(pre_scores)[::-1][:max(1, int(config.proposal_depth))]
+        boxes = [box_specs[i] for i in keep]
+
+        header_bits = cls._patch_header_bits(channel_bits, config.mask_size)
+        mid_bitcount = int(config.patch_palette_bitcount)
+
+        t = time.perf_counter()
+        mid_bounds, mid_bits, mid_specs = [], [], []
+        for (c, x, y, bw, bh) in boxes:
+            hidden_residual = target[y:y + bh, x:x + bw, c] - canvas[y:y + bh, x:x + bw, c]
+            base_cell = cls._base_cell_size(hidden_residual, config)
+            for cell_size in cls._candidate_cell_sizes(base_cell, config):
+                cell_size = max(1, min(cell_size, bw, bh))
+                bound = cls._box_cell_bound(integral_signed, x, y, bw, bh, cell_size)
+                if bound <= 0:
+                    continue
+                grid_cells = cls._ceil_div(bw, cell_size) * cls._ceil_div(bh, cell_size)
+                mid_bounds.append(bound)
+                mid_bits.append(header_bits + grid_cells * mid_bitcount)
+                mid_specs.append((c, x, y, bw, bh, cell_size))
+        cls._add_time(timings, "mid_score", time.perf_counter() - t)
+        if not mid_specs:
+            return None, None
+        mid_scores = q * cls._norm(mid_bounds) - (1.0 - q) * cls._norm(mid_bits)
+        keep = np.argsort(mid_scores)[::-1][:max(1, int(config.exact_depth))]
+        mid_specs = [mid_specs[i] for i in keep]
+
+        bitcounts = cls._patch_bitcounts(config)
+        reductions, bit_costs, built = [], [], []
+        t = time.perf_counter()
+        for proposal_i, (c, x, y, bw, bh, cell_size) in enumerate(mid_specs):
+            hidden_residual = target[y:y + bh, x:x + bw, c] - canvas[y:y + bh, x:x + bw, c]
+            before = target[y:y + bh, x:x + bw, c] - np.clip(canvas[y:y + bh, x:x + bw, c], 0, 255)
+            before_sse = float(np.sum(before.astype(np.int64) ** 2))
+            for bitcount in bitcounts:
+                for palette_mode in cls._palette_mode_options(config, bitcount):
+                    patch, values = cls._make_patch(c, x, y, bw, bh, cell_size, hidden_residual, config, bitcount, palette_mode, threshold)
+                    delta = cls.signed_resample(values, bh, bw).astype(np.int32)
+                    after = target[y:y + bh, x:x + bw, c] - np.clip(canvas[y:y + bh, x:x + bw, c] + delta, 0, 255)
+                    reduction = before_sse - float(np.sum(after.astype(np.int64) ** 2))
+                    if reduction <= 0:
+                        continue
+                    reductions.append(reduction)
+                    bit_costs.append(cls._patch_bits_for(patch, channel_bits))
+                    built.append((patch, values))
+                    if config.debug_mode:
+                        debug_lines.append(cls._debug_line(
+                            "CANDIDATE", patch_step=step, canvas_patches=canvas_patches, proposal=proposal_i,
+                            channel=c, x=x, y=y, w=bw, h=bh, cell_size=cell_size, bitcount=bitcount,
+                            palette_mode=palette_mode, reduction=f"{reduction:.4f}"))
+        cls._add_time(timings, "fill_score", time.perf_counter() - t)
+        if not built:
+            return None, None
+
+        scores = q * cls._norm(reductions) - (1.0 - q) * cls._norm(bit_costs)
+        best_i = int(np.argmax(scores))
+        best_patch, best_values = built[best_i]
+        if config.debug_mode:
+            debug_lines.append(cls._debug_line(
+                "SELECTED", patch_step=step, canvas_patches=canvas_patches, channel=best_patch["channel"],
+                x=best_patch["x"], y=best_patch["y"], w=best_patch["w"], h=best_patch["h"],
+                cell_size=best_patch["cell_size"], bitcount=best_patch["bitcount"],
+                palette_mode=best_patch["palette_mode"], score=f"{float(scores[best_i]):.6f}"))
+        return best_patch, best_values
+
+    @classmethod
+    def _write_header(cls, bw, w, h, original_w, original_h, downsampled, color_id, channels, channel_bits, positive_bias, has_alpha, patch_count, base_values):
+        bw.write(int(downsampled), 1)
+        if downsampled:
+            bw.write(original_w, 16)
+            bw.write(original_h, 16)
+        bw.write(w, 16)
+        bw.write(h, 16)
+        bw.write(color_id, 2)
+        bw.write(channels, 8)
+        bw.write(channel_bits, 4)
+        bw.write(int(positive_bias), 1)
+        bw.write(int(has_alpha), 1)
+        bw.write(patch_count, 32)
+        for base in base_values:
+            bw.write(base, 8)
+
+    @classmethod
+    def _read_header(cls, br):
+        downsampled = bool(br.read(1))
+        original_w = br.read(16) if downsampled else None
+        original_h = br.read(16) if downsampled else None
+        w = br.read(16)
+        h = br.read(16)
+        color_id = br.read(2)
+        channels = br.read(8)
+        channel_bits = br.read(4)
+        positive_bias = bool(br.read(1))
+        has_alpha = bool(br.read(1))
+        patch_count = br.read(32)
+        color_space = cls.COLOR_SPACE_NAMES[color_id]
+        base_values = [br.read(8) for _ in range(channels)]
+        return downsampled, original_w, original_h, w, h, color_space, channels, channel_bits, positive_bias, has_alpha, patch_count, base_values
+
+    @classmethod
+    def prepare(cls, image, config=None, **kwargs):
+        """Build the working-resolution target once so it can be reused across many
+        compress() runs on the same image via compress(..., reuse=prep) (skips the
+        setup_downsample step per run). Reuse is valid only while color_space /
+        downsample settings stay the same."""
+        if config is None:
+            config = PBC3Config(**kwargs)
+        elif kwargs:
+            config = PBC3Config(**{**config.__dict__, **kwargs})
+        src = cls._to_image(image)
+        has_alpha = cls._has_alpha(src)
+        if has_alpha:
+            rgba = src.convert("RGBA")
+            color_img = rgba.convert("RGB").convert(config.color_space)
+            alpha_img = rgba.getchannel("A")
+            orig_compare = rgba
+        else:
+            color_img = src.convert(config.color_space)
+            alpha_img = None
+            orig_compare = src.convert("RGB")
+        original_w, original_h = color_img.size
+        rate = cls._auto_downsample_rate(color_img.size, config.downsample_rate, config.auto_downsample_max_pixels)
+        color_ds = cls._downsample_image(color_img, rate)
+        downsampled = color_ds.size != color_img.size
+        arr = np.asarray(color_ds, dtype=np.uint8)
+        if has_alpha:
+            alpha_ds = alpha_img.resize(color_ds.size, cls.RESAMPLE_FILTER, reducing_gap=cls.RESAMPLE_REDUCING_GAP) if downsampled else alpha_img
+            arr = np.dstack([arr, np.asarray(alpha_ds, dtype=np.uint8)])
+        h, w, channels = arr.shape
+        return {
+            "arr": arr, "target": arr.astype(np.int32), "h": h, "w": w, "channels": channels,
+            "original_w": original_w, "original_h": original_h, "downsampled": downsampled,
+            "has_alpha": has_alpha, "orig_compare": orig_compare, "rate": rate,
+            "color_id": cls.COLOR_SPACES[config.color_space], "color_space": config.color_space,
+        }
+
+    @classmethod
+    def compress(cls, image, config=None, *, reuse=None, **kwargs):
+        if config is None:
+            config = PBC3Config(**kwargs)
+        elif kwargs:
+            config = PBC3Config(**{**config.__dict__, **kwargs})
+
+        t0 = time.perf_counter()
+        timings = {}
+        debug_lines = []
+
+        t = time.perf_counter()
+        prep = reuse if reuse is not None else cls.prepare(image, config)
+        arr, target = prep["arr"], prep["target"]
+        h, w, channels = prep["h"], prep["w"], prep["channels"]
+        original_w, original_h = prep["original_w"], prep["original_h"]
+        downsampled, has_alpha = prep["downsampled"], prep["has_alpha"]
+        orig_compare, color_id, rate = prep["orig_compare"], prep["color_id"], prep["rate"]
+        cls._add_time(timings, "setup_downsample", time.perf_counter() - t)
+
+        if w > 65535 or h > 65535 or original_w > 65535 or original_h > 65535:
+            raise ValueError("this prototype stores dimensions as uint16")
+        if config.mask_size < 1 or config.mask_size > 1023:
+            raise ValueError("mask_size must be in 1..1023")
+        if config.auto_downsample_max_pixels < 1:
+            raise ValueError("auto_downsample_max_pixels must be >= 1")
+        if not (1 <= config.downsample_palette_bitcount <= 9 and 1 <= config.patch_palette_bitcount <= 9):
+            raise ValueError("palette bitcounts must be in 1..9")
+        if str(config.channel_cycle).lower() not in {"off", "sum", "max"}:
+            raise ValueError('channel_cycle must be "Off", "Sum", or "Max"')
+        if str(config.patch_bitcount_mode).lower() not in {"constant", "dynamic"}:
+            raise ValueError('patch_bitcount_mode must be "constant" or "dynamic"')
+        if str(config.palette_mode).lower() not in {"generated", "explicit", "auto"}:
+            raise ValueError('palette_mode must be "generated", "explicit", or "auto"')
+
+        channel_bits = max(1, math.ceil(math.log2(channels)))
+        base_values = [int(round(float(np.mean(arr[:, :, c])))) for c in range(channels)]
+        canvas = np.zeros((h, w, channels), dtype=np.int32)
+        for c, base in enumerate(base_values):
+            canvas[:, :, c] = base
+
+        patches = []
+        t = time.perf_counter()
+        for c in range(channels):
+            if config.auto_downsample_init:
+                patch, values, init_cell, init_bits = cls._select_init(c, target, canvas, w, h, config, channel_bits)
+                if config.debug_print:
+                    print(f"[auto-init] channel {c}: cell={init_cell}, bitcount={init_bits}")
+            else:
+                init_cell, init_bits = config.downsample_init_cell_size, config.downsample_palette_bitcount
+                residual = target[:, :, c] - canvas[:, :, c]
+                patch, values = cls._make_patch(c, 0, 0, w, h, init_cell, residual, config, init_bits, cls.PALETTE_GENERATED, 0)
+            cls.apply_grid(canvas[:, :, c], 0, 0, w, h, init_cell, values)
+            patches.append(patch)
+            if config.debug_mode:
+                debug_lines.append(cls._debug_line("INIT", stream_patch=len(patches), channel=c, x=0, y=0, w=w, h=h, cell_size=init_cell, bitcount=init_bits))
+        cls._add_time(timings, "init_layer", time.perf_counter() - t)
+
+        channel_scores = [cls._channel_error_score(target, canvas, c, config.channel_cycle) for c in range(channels)]
+        quality_target = float(config.quality_target_mae)
+        rng = np.random.default_rng(config.random_seed)
+        t_patch_total = time.perf_counter()
+        for step in range(1, max(0, int(config.patch_count)) + 1):
+            current_channel = cls._choose_channel(channel_scores, step, channels, config.channel_cycle)
+            patch, values = cls._select_patch(target, canvas, config, rng, channel_bits, step, len(patches), debug_lines, timings, current_channel)
+            if patch is None:
+                break
+            t = time.perf_counter()
+            c = patch["channel"]
+            cls.apply_grid(canvas[:, :, c], patch["x"], patch["y"], patch["w"], patch["h"], patch["cell_size"], values)
+            patches.append(patch)
+            channel_scores[c] = cls._channel_error_score(target, canvas, c, config.channel_cycle)
+            cls._add_time(timings, "apply_selected", time.perf_counter() - t)
+            if config.debug_mode:
+                debug_lines.append(cls._debug_line("APPLIED", patch_step=step, stream_patch=len(patches), channel=c, channel_score=f"{channel_scores[c]:.4f}", x=patch["x"], y=patch["y"], w=patch["w"], h=patch["h"], cell_size=patch["cell_size"]))
+            if config.debug_print:
+                print("|", end="", flush=True)
+            if quality_target > 0 and float(np.mean(np.abs(target - np.clip(canvas, 0, 255)))) <= quality_target:
+                break
+        if config.debug_print:
+            print()
+        cls._add_time(timings, "patch_loop_total", time.perf_counter() - t_patch_total)
+
+        t = time.perf_counter()
+        bw = BitWriter()
+        cls._write_header(bw, w, h, original_w, original_h, downsampled, color_id, channels, channel_bits, config.positive_bias, has_alpha, len(patches), base_values)
+        for patch in patches:
+            cls._write_patch(bw, patch, channel_bits)
+        method, body = cls._entropy_pack(bw.finish(), config.use_lzma)
+        data = cls.MAGIC + bytes([cls.VERSION, method]) + body
+        cls._add_time(timings, "serialize", time.perf_counter() - t)
+
+        t = time.perf_counter()
+        out_img = cls._canvas_to_image(canvas, config.color_space, has_alpha)
+        if downsampled:
+            out_img = out_img.resize((original_w, original_h), cls.RESAMPLE_FILTER, reducing_gap=cls.RESAMPLE_REDUCING_GAP)
+        mse = float(np.mean((np.asarray(orig_compare, dtype=np.float32) - np.asarray(out_img, dtype=np.float32)) ** 2))
+        cls._add_time(timings, "finalize_mse", time.perf_counter() - t)
+
+        debug_path = None
+        total_seconds = time.perf_counter() - t0
+        timings["total"] = total_seconds
+        if config.debug_mode:
+            ts = time.strftime("%Y%m%d_%H%M%S")
+            debug_path = config.debug_path or f"debug_{ts}.txt"
+            with open(debug_path, "w", encoding="utf-8") as f:
+                f.write(cls._debug_line("CONFIG", **{k: v for k, v in config.__dict__.items() if k not in {"debug_path"}}) + "\n")
+                f.write(cls._debug_line("IMAGE", original_w=original_w, original_h=original_h, working_w=w, working_h=h,
+                                        original_pixels=original_w * original_h, working_pixels=w * h,
+                                        downsample_rate=f"{rate:.6f}", downsampled=int(downsampled), has_alpha=int(has_alpha)) + "\n")
+                for k, v in timings.items():
+                    f.write(cls._debug_line("TIMER", phase=k, seconds=f"{v:.6f}") + "\n")
+                for line in debug_lines:
+                    f.write(line + "\n")
+
+        return PBC3Result(out_img, data, config, mse, total_seconds, len(data) * 8, original_w, original_h, w, h, timings, debug_path, channels=channels)
+
+    @classmethod
+    def _canvas_to_image(cls, canvas, color_space, has_alpha):
+        arr = np.clip(canvas, 0, 255).astype(np.uint8)
+        if has_alpha:
+            color = Image.fromarray(arr[:, :, :3], color_space).convert("RGB").convert("RGBA")
+            color.putalpha(Image.fromarray(arr[:, :, 3], "L"))
+            return color
+        return Image.fromarray(arr, color_space).convert("RGB")
+
+    @classmethod
+    def _decode_to_canvas(cls, data, max_patches=None):
+        if isinstance(data, str):
+            with open(data, "rb") as f:
+                data = f.read()
+        version, body = cls._open_body(data)
+        br = BitReader(body)
+        downsampled, original_w, original_h, w, h, color_space, channels, channel_bits, positive_bias, has_alpha, patch_count, base_values = cls._read_header(br)
+        canvas = np.zeros((h, w, channels), dtype=np.int32)
+        for c, base in enumerate(base_values):
+            canvas[:, :, c] = base
+        patches_to_read = patch_count if max_patches is None else min(int(max_patches), patch_count)
+        for _ in range(patches_to_read):
+            channel, x, y, pw, ph, cell_size, values = cls._read_patch(br, channel_bits, positive_bias)
+            cls.apply_grid(canvas[:, :, channel], x, y, pw, ph, cell_size, values)
+        return canvas, color_space, downsampled, original_w, original_h, w, h, has_alpha, channels, patch_count
+
+    @classmethod
+    def decompress(cls, data, max_patches=None):
+        t0 = time.perf_counter()
+        if isinstance(data, str):
+            with open(data, "rb") as f:
+                data = f.read()
+        canvas, color_space, downsampled, original_w, original_h, w, h, has_alpha, channels, patch_count = cls._decode_to_canvas(data, max_patches=max_patches)
+        img = cls._canvas_to_image(canvas, color_space, has_alpha)
+        if downsampled:
+            img = img.resize((original_w, original_h), cls.RESAMPLE_FILTER, reducing_gap=cls.RESAMPLE_REDUCING_GAP)
+        cfg = PBC3Config(color_space=color_space)
+        return PBC3Result(img, data, cfg, None, time.perf_counter() - t0, len(data) * 8, original_w or w, original_h or h, w, h, channels=channels)
+
+    @classmethod
+    def encode_file(cls, input_path, output_path, config=None, **kwargs):
+        result = cls.compress(Image.open(input_path), config=config, **kwargs)
+        with open(output_path, "wb") as f:
+            f.write(result.data)
+        return result
+
+    @classmethod
+    def decode_file(cls, input_path, output_path=None):
+        image = cls.decompress(input_path).image
+        if output_path is not None:
+            image.save(output_path)
+        return image
+
+
+if __name__ == "__main__":
+    import sys
+    if len(sys.argv) < 3:
+        print("usage: python PBC3.py input_image output.pbc3")
+    else:
+        res = PBC3.encode_file(sys.argv[1], sys.argv[2])
+        print(f"MSE: {res.mse:.2f} | Size: {len(res.data) / 1024:.2f} KB | Rate: {res.compression_rate:.2f}x | Time: {res.encode_seconds:.3f}s")

PBC3_animation.py

@@ -0,0 +1,298 @@
+import os
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+from PBC3 import PBC3, BitReader
+
+
+def _font(size):
+    for name in ("DejaVuSans.ttf", "Arial.ttf"):
+        try:
+            return ImageFont.truetype(name, size)
+        except Exception:
+            pass
+    return ImageFont.load_default()
+
+
+def _colorize_rgb_channel(channel, c):
+    arr = np.clip(channel, 0, 255).astype(np.uint8)
+    out = np.zeros((arr.shape[0], arr.shape[1], 3), dtype=np.uint8)
+    out[:, :, c % 3] = arr
+    return Image.fromarray(out, "RGB")
+
+
+def _colorize_ycbcr_channel(channel, c):
+    arr = np.clip(channel, 0, 255).astype(np.uint8)
+    if c == 0:
+        return Image.fromarray(np.stack([arr, arr, arr], axis=2), "RGB")
+
+    d = arr.astype(np.int16) - 128
+    mag = np.clip(np.abs(d) * 2, 0, 255).astype(np.uint8)
+    out = np.zeros((*arr.shape, 3), dtype=np.uint8)
+    if c == 1:
+        pos = d >= 0
+        out[pos, 2] = mag[pos]
+        out[~pos, 0] = mag[~pos]
+        out[~pos, 1] = mag[~pos]
+    else:
+        pos = d >= 0
+        out[pos, 0] = mag[pos]
+        out[~pos, 1] = mag[~pos]
+        out[~pos, 2] = mag[~pos]
+    return Image.fromarray(out, "RGB")
+
+
+def _colorize_channel(channel, c, color_space):
+    if str(color_space).lower() == "ycbcr":
+        return _colorize_ycbcr_channel(channel, c)
+    return _colorize_rgb_channel(channel, c)
+
+
+def _error_image(error, color_space, channel=None):
+    err = np.asarray(error, dtype=np.float32)
+    if err.ndim == 3:
+        err = np.mean(np.abs(err), axis=2)
+        m = float(np.max(err))
+        arr = np.clip(err * (255.0 / m), 0, 255).astype(np.uint8) if m > 0 else np.zeros(err.shape, dtype=np.uint8)
+        return Image.fromarray(np.stack([arr, arr, arr], axis=2), "RGB")
+
+    signed = err
+    mag = np.abs(signed)
+    m = float(np.max(mag))
+    arr = np.clip(mag * (255.0 / m), 0, 255).astype(np.uint8) if m > 0 else np.zeros(mag.shape, dtype=np.uint8)
+    if str(color_space).lower() != "ycbcr" or channel == 0:
+        return _colorize_channel(arr, 0 if channel is None else channel, color_space)
+
+    d = np.sign(signed).astype(np.int16) * arr.astype(np.int16)
+    if channel == 1:
+        out = np.zeros((*arr.shape, 3), dtype=np.uint8)
+        pos = d >= 0
+        out[pos, 2] = arr[pos]
+        out[~pos, 0] = arr[~pos]
+        out[~pos, 1] = arr[~pos]
+        return Image.fromarray(out, "RGB")
+
+    out = np.zeros((*arr.shape, 3), dtype=np.uint8)
+    pos = d >= 0
+    out[pos, 0] = arr[pos]
+    out[~pos, 1] = arr[~pos]
+    out[~pos, 2] = arr[~pos]
+    return Image.fromarray(out, "RGB")
+
+
+def _draw_patch(draw, box, scale, offset, color="red", width=4):
+    if box is None:
+        return
+    x, y, w, h = box
+    ox, oy = offset
+    rect = [ox + x * scale, oy + y * scale, ox + (x + w) * scale, oy + (y + h) * scale]
+    for i in range(width):
+        draw.rectangle([rect[0] - i, rect[1] - i, rect[2] + i, rect[3] + i], outline=color)
+
+
+def _fit(img, max_w, max_h):
+    scale = min(max_w / img.width, max_h / img.height)
+    out_w = max(1, int(img.width * scale))
+    out_h = max(1, int(img.height * scale))
+    return img.resize((out_w, out_h), Image.Resampling.NEAREST), scale
+
+
+def _make_frame(canvas, color_space, patch_info, separated_channels, title, target=None, show_errors=False, output_size=(3840, 2160)):
+    arr = np.clip(canvas, 0, 255).astype(np.uint8)
+    rgb = Image.fromarray(arr, color_space).convert("RGB")
+    error = None if target is None else target.astype(np.int32) - arr.astype(np.int32)
+
+    if not separated_channels:
+        panels = [(rgb, False)]
+        if show_errors:
+            if error is None:
+                raise ValueError("show_errors=True requires original_image")
+            panels.append((_error_image(error, color_space), True))
+        cols, rows = 1, len(panels)
+    else:
+        panels = [
+            (_colorize_channel(arr[:, :, 0], 0, color_space), False),
+            (_colorize_channel(arr[:, :, 1], 1, color_space), False),
+            (_colorize_channel(arr[:, :, 2], 2, color_space), False),
+            (rgb, False),
+        ]
+        if show_errors:
+            if error is None:
+                raise ValueError("show_errors=True requires original_image")
+            panels.extend([
+                (_error_image(error[:, :, 0], color_space, 0), True),
+                (_error_image(error[:, :, 1], color_space, 1), True),
+                (_error_image(error[:, :, 2], color_space, 2), True),
+                (_error_image(error, color_space), True),
+            ])
+        cols, rows = 4, 2 if show_errors else 1
+
+    frame_w, frame_h = output_size
+    frame = Image.new("RGB", output_size, "black")
+    draw = ImageDraw.Draw(frame)
+    title_h = 120
+    gap = 18
+    margin = 36
+    draw.text((margin, 34), title, fill="white", font=_font(46))
+
+    area_w = frame_w - margin * 2
+    area_h = frame_h - title_h - margin
+    cell_w = (area_w - gap * (cols - 1)) // cols
+    cell_h = (area_h - gap * (rows - 1)) // rows
+    active_channel = patch_info[0] if patch_info is not None else None
+    patch_box = patch_info[1:5] if patch_info is not None else None
+
+    for i, (panel, is_error) in enumerate(panels):
+        col = i % cols
+        row = i // cols
+        x0 = margin + col * (cell_w + gap)
+        y0 = title_h + row * (cell_h + gap)
+        fitted, scale = _fit(panel, cell_w, cell_h)
+        px = x0 + (cell_w - fitted.width) // 2
+        py = y0 + (cell_h - fitted.height) // 2
+        frame.paste(fitted, (px, py))
+
+        is_rgb_panel = (separated_channels and col == 3) or (not separated_channels and i == 0)
+        is_active_channel_panel = separated_channels and col == active_channel
+        if patch_box is not None and not is_error and (is_rgb_panel or is_active_channel_panel):
+            _draw_patch(draw, patch_box, scale, (px, py))
+
+    return frame
+
+
+def _even_rgb_array(frame):
+    arr = np.asarray(frame.convert("RGB"), dtype=np.uint8)
+    h, w = arr.shape[:2]
+    pad_h = h % 2
+    pad_w = w % 2
+    if pad_h or pad_w:
+        arr = np.pad(arr, ((0, pad_h), (0, pad_w), (0, 0)), mode="constant", constant_values=0)
+    return arr
+
+
+def _write_mp4(frames, output_path, fps):
+    try:
+        import imageio.v2 as imageio
+    except Exception as e:
+        raise RuntimeError("imageio is not importable. Try: pip install imageio imageio-ffmpeg") from e
+    try:
+        import imageio_ffmpeg  # noqa: F401
+    except Exception as e:
+        raise RuntimeError("MP4 writing needs ffmpeg. Try: pip install imageio-ffmpeg") from e
+
+    writer = imageio.get_writer(
+        output_path,
+        fps=fps,
+        codec="libx264",
+        quality=8,
+        macro_block_size=16,
+        ffmpeg_params=["-pix_fmt", "yuv420p", "-movflags", "+faststart"],
+    )
+    try:
+        for frame in frames:
+            writer.append_data(_even_rgb_array(frame))
+    finally:
+        writer.close()
+    return output_path
+
+
+def _write_gif(frames, output_path, fps):
+    duration = int(1000 / fps)
+    frames[0].save(output_path, save_all=True, append_images=frames[1:], duration=duration, loop=0)
+    return output_path
+
+
+def _write_frames(frames, output_path, fps, fallback_to_gif=True):
+    ext = os.path.splitext(output_path)[1].lower()
+    if ext == ".gif":
+        return _write_gif(frames, output_path, fps)
+    if ext not in {".mp4", ".m4v", ".mov"}:
+        output_path = os.path.splitext(output_path)[0] + ".mp4"
+    try:
+        return _write_mp4(frames, output_path, fps)
+    except Exception as e:
+        if not fallback_to_gif:
+            raise
+        fallback = os.path.splitext(output_path)[0] + ".gif"
+        print(f"MP4 export failed: {e}")
+        print(f"Falling back to GIF: {fallback}")
+        return _write_gif(frames, fallback, fps)
+
+
+def _working_target(original_image, color_space, working_w, working_h):
+    img = PBC3._to_image(original_image).convert(color_space)
+    if img.width != working_w or img.height != working_h:
+        img = img.resize((working_w, working_h), PBC3.RESAMPLE_FILTER, reducing_gap=PBC3.RESAMPLE_REDUCING_GAP)
+    return np.asarray(img, dtype=np.uint8)
+
+
+def animate_pbc3(
+    data,
+    output_path="pbc3_animation.mp4",
+    fps=3,
+    separated_channels=True,
+    max_patches=None,
+    fallback_to_gif=True,
+    show_errors=False,
+    original_image=None,
+    output_size=(3840, 2160),
+):
+    if isinstance(data, str):
+        with open(data, "rb") as f:
+            data = f.read()
+    version, body = PBC3._open_body(data)
+    br = BitReader(body)
+    downsampled, original_w, original_h, w, h, color_space, channels, channel_bits, positive_bias, patch_count, base_values = PBC3._read_header(br)
+    if channels != 3 and separated_channels:
+        separated_channels = False
+    if show_errors and original_image is None:
+        raise ValueError("show_errors=True requires original_image=...")
+
+    target = _working_target(original_image, color_space, w, h) if show_errors else None
+    canvas = np.zeros((h, w, channels), dtype=np.int32)
+    for c, base in enumerate(base_values):
+        canvas[:, :, c] = base
+
+    frames = []
+    limit = patch_count if max_patches is None else min(int(max_patches), patch_count)
+
+    # Note: entropy coding is global, so per-patch byte sizes are reported on the
+    # pre-entropy (uncompressed) stream; the final file is smaller after packing.
+    current_bytes = br.i
+    current_kb = current_bytes / 1024
+    frames.append(_make_frame(
+        canvas,
+        color_space,
+        None,
+        separated_channels,
+        f"Patch 0/{patch_count} | Stream Size: {current_kb:.2f} KB | (+0.00 KB)",
+        target,
+        show_errors,
+        output_size,
+    ))
+
+    for i in range(1, limit + 1):
+        previous_bytes = current_bytes
+
+        channel, x, y, pw, ph, cell_size, values, mode = PBC3._read_patch(br, channel_bits, positive_bias)
+
+        current_bytes = br.i
+        current_kb = current_bytes / 1024
+        delta_kb = (current_bytes - previous_bytes) / 1024
+
+        PBC3.apply_grid(canvas[:, :, channel], x, y, pw, ph, cell_size, values)
+        title = (
+            f"Patch {i}/{patch_count} | Stream Size: {current_kb:.2f} KB "
+            f"| (+{delta_kb:.2f} KB) | ch={channel} box=({x},{y},{pw},{ph}) cell={cell_size}"
+        )
+        frames.append(_make_frame(
+            canvas,
+            color_space,
+            (channel, x, y, pw, ph, cell_size),
+            separated_channels,
+            title,
+            target,
+            show_errors,
+            output_size,
+        ))
+
+    return _write_frames(frames, output_path, fps, fallback_to_gif=fallback_to_gif)

pbc3_kernels.py

@@ -0,0 +1,172 @@
+# Numba-accelerated search kernels for PBC3.
+#
+# These are imported and used directly by PBC3 when numba is available; otherwise
+# PBC3 falls back to equivalent numpy implementations. They are quality-equivalent
+# but NOT bit-identical to the pure-numpy path (numba sums floats in a different
+# order than numpy's pairwise summation, so argsort/argpartition ties may
+# occasionally flip and select a different but equivalent patch).
+#
+# verify() checks the kernels against reference numpy formulas to tight tolerance.
+
+import numpy as np
+
+try:
+    from numba import njit
+    NUMBA_AVAILABLE = True
+except Exception:
+    NUMBA_AVAILABLE = False
+
+    def njit(*args, **kwargs):
+        def wrap(f):
+            return f
+        return wrap(args[0]) if args and callable(args[0]) else wrap
+
+
+@njit(cache=True)
+def box_cell_bound(integral, x, y, bw, bh, cell_size):
+    nx = (bw + cell_size - 1) // cell_size
+    ny = (bh + cell_size - 1) // cell_size
+    total = 0.0
+    for iy in range(ny):
+        y0 = y + iy * cell_size
+        y1 = y + bh if iy == ny - 1 else y + (iy + 1) * cell_size
+        for ix in range(nx):
+            x0 = x + ix * cell_size
+            x1 = x + bw if ix == nx - 1 else x + (ix + 1) * cell_size
+            s = float(integral[y1, x1] - integral[y0, x1] - integral[y1, x0] + integral[y0, x0])
+            total += s * s / ((y1 - y0) * (x1 - x0))
+    return total
+
+
+@njit(cache=True)
+def base_cell_size(res, max_cell):
+    h, w = res.shape
+    s = 0.0
+    for i in range(h):
+        for j in range(w):
+            v = res[i, j]
+            s += v if v >= 0 else -v
+    mean_abs = s / (h * w)
+    if mean_abs <= 0.0:
+        return max_cell
+    gx = 0.0
+    if w > 1:
+        for i in range(h):
+            for j in range(w - 1):
+                d = res[i, j + 1] - res[i, j]
+                gx += d if d >= 0 else -d
+        gx /= h * (w - 1)
+    gy = 0.0
+    if h > 1:
+        for i in range(h - 1):
+            for j in range(w):
+                d = res[i + 1, j] - res[i, j]
+                gy += d if d >= 0 else -d
+        gy /= (h - 1) * w
+    ratio = (gx + gy) / (mean_abs + 1.0)
+    if ratio < 0.25:
+        return 32
+    if ratio < 0.5:
+        return 16
+    if ratio < 1.0:
+        return 8
+    return 4
+
+
+@njit(cache=True)
+def anchor_block_scores(err, block_size):
+    h, w = err.shape
+    ny = (h + block_size - 1) // block_size
+    nx = (w + block_size - 1) // block_size
+    n = ny * nx
+    scores = np.empty(n, dtype=np.float64)
+    ys = np.empty(n, dtype=np.int64)
+    xs = np.empty(n, dtype=np.int64)
+    k = 0
+    for by in range(ny):
+        y0 = by * block_size
+        y1 = min(h, y0 + block_size)
+        for bx in range(nx):
+            x0 = bx * block_size
+            x1 = min(w, x0 + block_size)
+            s = 0.0
+            for i in range(y0, y1):
+                for j in range(x0, x1):
+                    s += err[i, j]
+            scores[k] = s / ((y1 - y0) * (x1 - x0))
+            ys[k] = (y0 + y1 - 1) // 2
+            xs[k] = (x0 + x1 - 1) // 2
+            k += 1
+    return scores, ys, xs
+
+
+# Reference numpy formulas for tolerance-checking the kernels.
+def _ref_box_cell_bound(integral, x, y, bw, bh, cell_size):
+    cd = lambda a, b: (a + b - 1) // b
+    def edges(start, length):
+        n = cd(length, cell_size)
+        e = start + np.arange(n + 1) * cell_size
+        e[n] = start + length
+        return e
+    xe, ye = edges(x, bw), edges(y, bh)
+    corners = integral[np.ix_(ye, xe)].astype(np.float64)
+    cell_sum = corners[1:, 1:] - corners[:-1, 1:] - corners[1:, :-1] + corners[:-1, :-1]
+    counts = (np.diff(ye)[:, None] * np.diff(xe)[None, :]).astype(np.float64)
+    return float(np.sum(cell_sum * cell_sum / counts))
+
+
+def _ref_base_cell_size(res, max_cell):
+    mean_abs = float(np.mean(np.abs(res)))
+    if mean_abs <= 0:
+        return int(max_cell)
+    gx = float(np.mean(np.abs(np.diff(res, axis=1)))) if res.shape[1] > 1 else 0.0
+    gy = float(np.mean(np.abs(np.diff(res, axis=0)))) if res.shape[0] > 1 else 0.0
+    ratio = (gx + gy) / (mean_abs + 1.0)
+    return 32 if ratio < 0.25 else 16 if ratio < 0.5 else 8 if ratio < 1.0 else 4
+
+
+def _ref_block_scores(err, block_size):
+    h, w = err.shape
+    out = []
+    for y0 in range(0, h, block_size):
+        y1 = min(h, y0 + block_size)
+        for x0 in range(0, w, block_size):
+            x1 = min(w, x0 + block_size)
+            out.append(float(err[y0:y1, x0:x1].astype(np.float64).sum() / ((y1 - y0) * (x1 - x0))))
+    return np.array(out)
+
+
+def verify(trials=400, seed=0):
+    rng = np.random.default_rng(seed)
+    worst_box = 0.0
+    bcs_mismatch = 0
+    worst_anchor = 0.0
+    for _ in range(trials):
+        H, W = int(rng.integers(8, 200)), int(rng.integers(8, 200))
+        e = rng.integers(-80, 80, size=(H, W)).astype(np.int64)
+        integral = np.pad(e.cumsum(0).cumsum(1), ((1, 0), (1, 0)))
+        bw, bh = int(rng.integers(4, W + 1)), int(rng.integers(4, H + 1))
+        x, y = int(rng.integers(0, W - bw + 1)), int(rng.integers(0, H - bh + 1))
+        cell = int(rng.integers(1, max(2, min(bw, bh))))
+        ref = _ref_box_cell_bound(integral, x, y, bw, bh, cell)
+        got = box_cell_bound(integral, x, y, bw, bh, cell)
+        worst_box = max(worst_box, abs(got - ref) / (abs(ref) + 1e-9))
+
+        res = rng.integers(-60, 60, size=(bh, bw)).astype(np.float64)
+        if _ref_base_cell_size(res, 64) != int(base_cell_size(res, 64)):
+            bcs_mismatch += 1
+
+        bs = int(rng.integers(2, 16))
+        err = np.abs(e).astype(np.float64)
+        ref_s = _ref_block_scores(err, bs)
+        got_s, _, _ = anchor_block_scores(err, bs)
+        worst_anchor = max(worst_anchor, float(np.max(np.abs(ref_s - got_s) / (np.abs(ref_s) + 1e-9))))
+    print(f"numba_available={NUMBA_AVAILABLE} trials={trials}")
+    print(f"box_cell_bound worst_relative_diff={worst_box:.3e}")
+    print(f"base_cell_size mismatches={bcs_mismatch}/{trials}")
+    print(f"anchor_block_scores worst_relative_diff={worst_anchor:.3e}")
+    return worst_box, bcs_mismatch, worst_anchor
+
+
+if __name__ == "__main__":
+    verify()

pbc3_types.py

@@ -0,0 +1,201 @@
+# PBC3 supporting types: bit I/O, config, and result container.
+# Split out of PBC3.py to keep that module under size limits and improve structure.
+
+from dataclasses import dataclass, field
+import os
+import numpy as np
+from PIL import Image
+from matplotlib import pyplot as plt
+
+
+class BitWriter:
+    def __init__(self):
+        self.data = bytearray()
+        self.acc = 0
+        self.nbits = 0
+
+    def write(self, value, bitcount):
+        value = int(value)
+        if bitcount <= 0:
+            return
+        if value < 0 or value >= (1 << bitcount):
+            raise ValueError(f"value {value} does not fit in {bitcount} bits")
+        self.acc = (self.acc << bitcount) | value
+        self.nbits += bitcount
+        while self.nbits >= 8:
+            shift = self.nbits - 8
+            self.data.append((self.acc >> shift) & 255)
+            self.acc &= (1 << shift) - 1
+            self.nbits -= 8
+
+    def finish(self):
+        if self.nbits:
+            self.data.append((self.acc << (8 - self.nbits)) & 255)
+            self.acc = 0
+            self.nbits = 0
+        return bytes(self.data)
+
+
+class BitReader:
+    def __init__(self, data):
+        self.data = data
+        self.i = 0
+        self.acc = 0
+        self.nbits = 0
+
+    def read(self, bitcount):
+        while self.nbits < bitcount:
+            if self.i >= len(self.data):
+                raise EOFError("bitstream ended early")
+            self.acc = (self.acc << 8) | self.data[self.i]
+            self.i += 1
+            self.nbits += 8
+        shift = self.nbits - bitcount
+        value = (self.acc >> shift) & ((1 << bitcount) - 1)
+        self.acc &= (1 << shift) - 1
+        self.nbits -= bitcount
+        return value
+
+
+@dataclass
+class PBC3Config:
+    patch_count: int = 20
+    search_depth: int = 200
+    proposal_depth: int = 50
+    exact_depth: int = 10
+    min_patch_size: int = 16
+    max_patch_size: int = 400
+    min_cell_size: int = 1
+    max_cell_size: int = 64
+    cell_sizes_per_candidate: int = 3
+    top_k: int = 20
+    search_q_start: float = 0.4
+    search_q_end: float = 0.1
+    q_init: float = 0.7
+    q_start: float = 0.9
+    q_end: float = 0.9
+    color_space: str = "YCbCr"
+    channel_cycle: str = "Sum"
+    auto_downsample_init: bool = True
+    init_search_depth: int = 7
+    downsample_init_cell_size: int = 12
+    downsample_palette_bitcount: int = 6
+    downsample_rate: float = -1
+    auto_downsample_max_pixels: int = 250_000
+    patch_palette_bitcount: int = 2
+    patch_bitcount_mode: str = "constant"
+    palette_mode: str = "generated"
+    palette_difference_threshold: int = 0
+    palette_difference_threshold_mode: str = "constant"
+    explicit_palette_max_bitcount: int = 3
+    quality_target_mae: float = 0.0
+    mask_size: int = 4
+    anchor_block_size: int = 8
+    dynamic_patch_bitcount_min: int = 2
+    dynamic_patch_bitcount_max: int = 3
+    positive_bias: bool = True
+    use_lzma: bool = True
+    random_seed: int = 2003
+    debug_mode: bool = False
+    debug_print: bool = False
+    debug_path: str = None
+
+    def __post_init__(self):
+        self.channel_cycle = str(self.channel_cycle)
+        self.patch_bitcount_mode = str(self.patch_bitcount_mode)
+
+    @classmethod
+    def speed(cls):                     # old "balanced"
+        return cls()
+
+    @classmethod
+    def balanced(cls):
+        return cls(patch_count=20, search_q_start=0.7, search_q_end=0.2,
+                   init_search_depth=3, q_init=0.7, q_start=0.8, q_end=0.8)
+
+    @classmethod
+    def quality(cls):
+        return cls(patch_count=20, search_q_start=0.7, search_q_end=0.6,
+                   init_search_depth=3, q_init=0.9, q_start=0.9, q_end=0.8)
+
+    @classmethod
+    def compression(cls):
+        return cls(patch_count=50, search_q_start=0.5, search_q_end=0.2,
+                   init_search_depth=3, q_init=0.7, q_start=0.8, q_end=0.8)
+
+    @classmethod
+    def high_quality(cls):                # old "quality"
+        return cls(patch_count=100, search_q_start=0.6, search_q_end=0.1)
+
+
+@dataclass
+class PBC3Result:
+    image: Image.Image
+    data: bytes
+    config: PBC3Config
+    mse: float
+    encode_seconds: float
+    total_bits: int
+    original_width: int = None
+    original_height: int = None
+    working_width: int = None
+    working_height: int = None
+    timings: dict = field(default_factory=dict)
+    debug_path: str = None
+    channels: int = 3
+
+    @property
+    def original_bits(self):
+        w = self.original_width or self.image.width
+        h = self.original_height or self.image.height
+        return w * h * self.channels * 8
+
+    @property
+    def compressed_kb(self):
+        return self.total_bits / 8 / 1024
+
+    @property
+    def original_kb(self):
+        return self.original_bits / 8 / 1024
+
+    @property
+    def compression_rate(self):
+        return self.original_bits / self.total_bits if self.total_bits else float("inf")
+
+    @property
+    def compressed_percent(self):
+        return self.total_bits / self.original_bits * 100 if self.original_bits else 0
+
+    def save(self, path):
+        if self.data is None:
+            raise ValueError("result has no compressed data to save")
+        with open(path, "wb") as f:
+            f.write(self.data)
+
+    def verify(self):
+        from PBC3 import PBC3
+        if self.data is None:
+            return False
+        decoded = PBC3.decompress(self.data).image
+        return np.array_equal(np.asarray(self.image), np.asarray(decoded))
+
+    def show(self, subtitle=None):
+        fig = plt.figure(figsize=(8, 7.4), dpi=130)
+        gs = fig.add_gridspec(3, 1, height_ratios=[0.09, 0.16, 1.0], hspace=0.04)
+        title_ax = fig.add_subplot(gs[0])
+        info_ax = fig.add_subplot(gs[1])
+        image_ax = fig.add_subplot(gs[2])
+        for ax in (title_ax, info_ax, image_ax):
+            ax.axis("off")
+        title_ax.text(0.5, 0.5, "PBC3 Result" if subtitle is None else f"PBC3 Result\n{subtitle}", ha="center", va="center", fontsize=16, fontweight="bold")
+        mse = "N/A" if self.mse is None else f"{self.mse:.2f}"
+        seconds = "N/A" if self.encode_seconds is None else f"{self.encode_seconds:.3f}s"
+        debug = f"   |   Debug: {os.path.basename(self.debug_path)}" if self.debug_path else ""
+        info = (
+            f"MSE: {mse}   |   Compressed: {self.compressed_kb:.2f} KB   |   Original: {self.original_kb:.2f} KB\n"
+            f"Compression: {self.compression_rate:.2f}x ({self.compressed_percent:.2f}%)   |   Time: {seconds}{debug}"
+        )
+        info_ax.text(0.5, 0.5, info, ha="center", va="center", color="white", fontsize=10, linespacing=1.35,
+                     bbox=dict(boxstyle="round,pad=0.5", facecolor="black", alpha=0.72, edgecolor="none"))
+        image_ax.imshow(self.image)
+        plt.show()

server.py

@@ -8,7 +8,7 @@ import os
 import time
 from typing import List
 
-from fastapi import FastAPI, File, Form, UploadFile
+from fastapi import FastAPI, File, Form, Request, UploadFile
 from fastapi.responses import JSONResponse, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from PIL import Image
@@ -21,6 +21,7 @@ except Exception:
     pass
 
 from PBC2_4 import PBC, PBC2Config, PBC2Result, preload_numba
+from PBC3 import PBC3, PBC3Config
 
 app = FastAPI(title="PBC Compression Demo")
 
@@ -182,6 +183,30 @@ def _i(v, d):
 def _truthy(v):
     return str(v).lower() == "true"
 
+PBC3_PRESETS = {
+    "speed": PBC3Config.speed,
+    "balanced": PBC3Config.balanced,
+    "compression": PBC3Config.compression,
+    "quality": PBC3Config.quality,
+    "high_quality": PBC3Config.high_quality,
+}
+
+# Every PBC3Config field the UI can submit, with the caster used to parse its form value.
+PBC3_FIELDS = {
+    "patch_count": int, "search_depth": int, "proposal_depth": int, "exact_depth": int,
+    "min_patch_size": int, "max_patch_size": int, "min_cell_size": int, "max_cell_size": int,
+    "cell_sizes_per_candidate": int, "top_k": int,
+    "search_q_start": float, "search_q_end": float, "q_init": float, "q_start": float, "q_end": float,
+    "color_space": str, "channel_cycle": str,
+    "auto_downsample_init": _truthy, "init_search_depth": int, "downsample_init_cell_size": int,
+    "downsample_palette_bitcount": int, "downsample_rate": float, "auto_downsample_max_pixels": int,
+    "patch_palette_bitcount": int, "patch_bitcount_mode": str, "palette_mode": str,
+    "palette_difference_threshold": int, "palette_difference_threshold_mode": str,
+    "explicit_palette_max_bitcount": int, "quality_target_mae": float, "mask_size": int,
+    "anchor_block_size": int, "dynamic_patch_bitcount_min": int, "dynamic_patch_bitcount_max": int,
+    "positive_bias": _truthy, "use_lzma": _truthy, "random_seed": int,
+    "debug_mode": _truthy, "debug_print": _truthy,
+}
 
 @app.get("/api/multlist")
 def multlist(bit_count: int = 2, min: int = -10, max: int = 20, mode: str = "Stable_Uniform"):
@@ -189,102 +214,44 @@ def multlist(bit_count: int = 2, min: int = -10, max: int = 20, mode: str = "Sta
 
 
 @app.post("/api/compress")
-async def compress(
-    image: UploadFile = File(...),
-    mode: str = Form("Auto"),
-    stroke_count: str = Form(""),
-    downsample_initialize_rate: str = Form(""),
-    downsample_initialize_bits: str = Form("8"),
-    downsample_initialize: str = Form("true"),
-    size_range_start: str = Form(""),
-    size_range_end: str = Form(""),
-    color_space: str = Form("RGB"),
-    downsample_rate: str = Form(""),
-    downsample_alg: str = Form("Bicubic"),
-    start_mode: str = Form("Average"),
-    decay_mode: str = Form("Auto"),
-    decay_cutoff: str = Form(""),
-    decay_softness: str = Form(""),
-    decay_progress: str = Form(""),
-    mult_list: str = Form(""),
-    strokes_per_quadrant: str = Form("100"),
-    quadrant_warmup_time: str = Form("0.5"),
-    quadrant_max_bits: str = Form("8"),
-    quadrant_padding: str = Form("4"),
-    quadrant_selection_criteria: str = Form("Sum"),
-    channel_cycle: str = Form("Smart"),
-    strokes_per_channel_cycle: str = Form("100"),
-    channel_cycle_warmup_time: str = Form("0.9"),
-    cycle_selection_criteria: str = Form("Min"),
-):
+async def compress(request: Request):
+    form = await request.form()
+    upload = form.get("image")
+    if upload is None:
+        return JSONResponse({"error": "No image provided"}, status_code=400)
     try:
-        raw_bytes = await image.read()
+        raw_bytes = await upload.read()
         img = Image.open(io.BytesIO(raw_bytes)).convert("RGB")
     except Exception as exc:
         return JSONResponse({"error": f"Could not read image: {exc}"}, status_code=400)
     w, h = img.size
 
-    if channel_cycle == "Off":
-        channel_cycle = None
-    elif channel_cycle == "123":
-        channel_cycle = "Default"
-
+    mode = form.get("mode", "Auto")
     if mode == "Auto":
+        preset = form.get("auto_config", "speed")
+        config = PBC3_PRESETS.get(preset, PBC3Config.speed)()
+        applied = {"mode": "Auto", "auto_config": preset}
+    else:
         kwargs = {}
-    elif mode == "Semi":
-        kwargs = dict(
-            stroke_count=_i(stroke_count, -1),
-            downsample_initialize=_truthy(downsample_initialize),
-            downsample_initialize_rate=_f(downsample_initialize_rate, 16),
-            downsample_initialize_bits=_i(downsample_initialize_bits, 8),
-        )
-    else:  # Manual
-        if decay_mode == "Auto":
-            decay = dict(decay_cutoff=-1.0, decay_softness=-1.0, decay_progress=-1.0)
-        else:
-            decay = dict(
-                decay_cutoff=_f(decay_cutoff, 0.5),
-                decay_softness=_f(decay_softness, 0.5),
-                decay_progress=_f(decay_progress, 0.5),
-            )
-        try:
-            mlist = [int(x) for x in ast.literal_eval(mult_list)]
-            assert mlist
-        except (ValueError, SyntaxError, AssertionError, TypeError):
-            mlist = [-10, 0, 5, 20]
-        kwargs = dict(
-            stroke_count=_i(stroke_count, -1),
-            size_range=(_f(size_range_start, 0.3), _f(size_range_end, 0.01)),
-            mult_list=mlist,
-            start_mode=start_mode,
-            **decay,
-            focus_strokes=_i(strokes_per_quadrant, 100),
-            focus_warmup=_f(quadrant_warmup_time, 0.5),
-            focus_max_bits=_i(quadrant_max_bits, 8),
-            focus_padding=_i(quadrant_padding, 4),
-            focus_criteria=quadrant_selection_criteria,
-            channel_cycle=channel_cycle,
-            channel_cycle_strokes=_i(strokes_per_channel_cycle, 100),
-            channel_cycle_warmup=_f(channel_cycle_warmup_time, 0.9),
-            channel_cycle_criteria=cycle_selection_criteria,
-            color_space=color_space,
-            downsample_rate=_f(downsample_rate, -1),
-            downsample_initialize=_truthy(downsample_initialize),
-            downsample_initialize_rate=_f(downsample_initialize_rate, 16),
-            downsample_initialize_bits=_i(downsample_initialize_bits, 8),
-            resample=RESAMPLE.get(downsample_alg, "bicubic"),
-        )
+        for k, caster in PBC3_FIELDS.items():
+            v = form.get(k)
+            if v in (None, ""):
+                continue
+            try:
+                kwargs[k] = caster(v)
+            except (ValueError, TypeError):
+                pass
+        config = PBC3Config(**kwargs)
+        applied = {"mode": mode, **kwargs}
 
     try:
-        result = PBC.compress(img, **kwargs)
+        result = PBC3.compress(img, config=config)
     except Exception as exc:
         return JSONResponse({"error": f"Compression failed: {exc}"}, status_code=400)
     reconstructed = result.image.convert("RGB")
 
-    # Full-resolution MSE/CQ: original vs the reconstruction (already at original size).
     a = np.asarray(img, dtype=np.float32)
     b = np.asarray(reconstructed.resize(img.size), dtype=np.float32)
-
     mse = mse_metric(a, b)
     cq = composite_quality(a, b)
 
@@ -305,7 +272,7 @@ async def compress(
         "mse": round(mse, 2),
         "composite_quality": round(cq, 2),
         "time_seconds": round(result.encode_seconds, 2),
-        "params": {"mode": mode, **{k: (list(v) if isinstance(v, tuple) else v) for k, v in kwargs.items()}},
+        "params": {k: (list(v) if isinstance(v, tuple) else v) for k, v in applied.items()},
     })
 
 
@@ -332,9 +299,9 @@ async def decode(file: UploadFile = File(...)):
     raw = await file.read()
 
     try:
-        timer = time.time()
-        img = PBC.decompress(bytes(raw)).convert("RGB")
-        elapsed = time.time() - timer
+        dec_res = PBC3.decompress(bytes(raw)).image.convert("RGB")
+        img = dec_res.image
+        elapsed = dec_res.encode_seconds
     except Exception as exc:
         return JSONResponse({"error": f"Decode failed: {exc}"}, status_code=400)
 
@@ -391,11 +358,11 @@ def _guess_quality(fmt, target_bpp):
     return qs[-1]
 
 
-def _match_codec_gen(img, fmt, target_bpp, pixels):
+def _match_codec_gen(img, fmt, target_bpp, pixels, search_count=8):
     """Generator yielding {'q','bpp'} per attempt, then a final {'best': {...}}.
 
-    Seeds from the bpp guideline, then nudges quality up/down based on the observed
-    bpp, capping at 3 total encodes. `best['data']` holds the chosen encoded bytes.
+    Binary-searches quality toward target_bpp (within 3%), then refines ±3 around the
+    best hit. `best['data']` holds the chosen encoded bytes. bpp is in bits-per-pixel.
     """
     qmin, qmax = _q_bounds(fmt)
     tried = {}
@@ -412,26 +379,34 @@ def _match_codec_gen(img, fmt, target_bpp, pixels):
             tried[q] = None
             return None
         data = buf.getvalue()
-        bpp = len(data) * 8 / pixels
-        r = {"q": q, "bpp": bpp, "data": data}
+        r = {"q": q, "bpp": len(data) * 8 / pixels, "data": data}
         tried[q] = r
-        if best["ref"] is None or abs(bpp - target_bpp) < abs(best["ref"]["bpp"] - target_bpp):
+        if best["ref"] is None or abs(r["bpp"] - target_bpp) < abs(best["ref"]["bpp"] - target_bpp):
             best["ref"] = r
         return r
 
-    cur = enc(_guess_quality(fmt, target_bpp))
-    if cur:
-        yield {"q": cur["q"], "bpp": cur["bpp"]}
-    n = 0
-    while cur and n < 2 and (not target_bpp or abs(cur["bpp"] - target_bpp) / target_bpp >= 0.08):
-        # If the observed bpp undershoots, the image compresses smaller than the guide -> raise quality.
-        adj = target_bpp * (target_bpp / cur["bpp"]) if cur["bpp"] > 0 else target_bpp
-        nxt = enc(_guess_quality(fmt, adj))
-        n += 1
-        if not nxt or nxt["q"] == cur["q"]:
+    lo, hi = qmin, qmax
+    for _ in range(search_count):
+        q = (lo + hi) // 2
+        r = enc(q)
+        if r is None:
             break
-        yield {"q": nxt["q"], "bpp": nxt["bpp"]}
-        cur = nxt
+        yield {"q": r["q"], "bpp": r["bpp"]}
+        if target_bpp > 0 and abs(r["bpp"] - target_bpp) / target_bpp < 0.03:
+            break
+        if r["bpp"] > target_bpp:
+            hi = q - 1
+        else:
+            lo = q + 1
+        if lo > hi:
+            break
+
+    if best["ref"]:
+        center = best["ref"]["q"]
+        for q in range(max(qmin, center - 3), min(qmax, center + 3) + 1):
+            r = enc(q)
+            if r:
+                yield {"q": r["q"], "bpp": r["bpp"]}
 
     yield {"best": best["ref"]}
 
@@ -729,7 +704,14 @@ async def match_codec(image: UploadFile = File(...), codec: str = Form("jpeg"),
     if not best:
         return JSONResponse({"error": f"{fmt} encoding unavailable."}, status_code=400)
     rec = Image.open(io.BytesIO(best["data"])).convert("RGB")
-    return {"image": _png_b64(rec), "bpp": best["bpp"], "q": best["q"], "quality": composite_quality(img, rec)}
+    return {
+        "image": _png_b64(rec),
+        "bpp": best["bpp"],
+        "q": best["q"],
+        "quality": composite_quality(img, rec),
+        "mse": mse_metric(img, rec),
+        "size_kb": round(len(best["data"]) / 1024, 2),
+    }
 
 
 @app.get("/api/sweeps/artifact")

static/app.js

@@ -339,47 +339,78 @@ function gotoView(v) {
 }
 
 /* ============================================================
-   PARAMETERS
+   PARAMETERS  (PBC3.0)
+   Auto   → pick one of the PBC3Config presets.
+   Semi   → the high-impact parameters as sliders/inputs.
+   Manual → every PBC3Config field.
 ============================================================ */
+const AUTO_CONFIGS = [
+  { id: "speed", label: "Speed" },
+  { id: "balanced", label: "Balanced" },
+  { id: "compression", label: "Compression" },
+  { id: "quality", label: "Quality" },
+  { id: "high_quality", label: "High Quality" },
+];
+
 const PARAMS = [
-  { id: "stroke_count", label: "Stroke count", hint: "higher = better quality but slower and less compression", group: "Core", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 200000, step: 1000, value: 40000, full: true },
-  { id: "downsample_initialize_rate", label: "Downsample init rate", group: "Core", modes: ["Semi", "Manual"], type: "slider", min: 2, max: 32, step: 0.1, value: 16, disableToggle: true },
-  { id: "downsample_initialize_bits", label: "Downsample init bits", group: "Core", modes: ["Manual"], type: "slider", min: 1, max: 8, step: 1, value: 8 },
-
-  { id: "size_range_start", label: "Size range start", group: "Strokes", modes: ["Manual"], type: "slider", min: 0.001, max: 1, step: 0.001, value: 0.3 },
-  { id: "size_range_end", label: "Size range end", group: "Strokes", modes: ["Manual"], type: "slider", min: 0.001, max: 1, step: 0.001, value: 0.01 },
-  { id: "start_mode", label: "Canvas start color", group: "Strokes", modes: ["Manual"], type: "select", options: ["Average", "Median", "Black", "White", "Custom"], value: "Average" },
-
-  { id: "color_space", label: "Color space", group: "Color & downsampling", modes: ["Manual"], type: "select", options: ["RGB", "YCbCr"], value: "RGB" },
-  { id: "downsample_rate", label: "Downsample rate", hint: "-1 = auto", group: "Color & downsampling", modes: ["Manual"], type: "slider", min: -1, max: 16, step: 0.1, value: -1 },
-  { id: "downsample_alg", label: "Resample algorithm", group: "Color & downsampling", modes: ["Manual"], type: "select", options: ["Lanczos", "Bicubic", "Bilinear", "Nearest"], value: "Bicubic" },
-
-  { id: "decay_mode", label: "Size decay function", group: "Decay", modes: ["Manual"], type: "select", options: ["Auto", "Manual"], value: "Auto" },
-  { id: "decay_cutoff", label: "Decay cutoff", group: "Decay", modes: ["Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.5 },
-  { id: "decay_softness", label: "Decay softness", group: "Decay", modes: ["Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.5 },
-  { id: "decay_progress", label: "Decay progress", group: "Decay", modes: ["Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.5 },
-
-  { id: "multlist_mode", label: "Generator mode", group: "Multiplier list", modes: ["Manual"], type: "select", options: ["PBC Default", "Stable_Uniform", "Uniform", "Random"], value: "PBC Default" },
-  { id: "mult_bit_count", label: "Multiplier bit count", group: "Multiplier list", modes: ["Manual"], type: "slider", min: 1, max: 9, step: 1, value: 2 },
-  { id: "mult_min", label: "Multiplier minimum", group: "Multiplier list", modes: ["Manual"], type: "slider", min: -255, max: 255, step: 1, value: -10 },
-  { id: "mult_max", label: "Multiplier maximum", group: "Multiplier list", modes: ["Manual"], type: "slider", min: -255, max: 255, step: 1, value: 20 },
-  { id: "mult_list", label: "Multiplier list", hint: "editable", group: "Multiplier list", modes: ["Manual"], type: "text", value: "[-10, 0, 5, 20]", gen: true },
-
-  { id: "strokes_per_quadrant", label: "Focus strokes", group: "Focus", modes: ["Manual"], type: "slider", min: 10, max: 1000, step: 10, value: 100 },
-  { id: "quadrant_warmup_time", label: "Focus warmup", group: "Focus", modes: ["Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.5 },
-  { id: "quadrant_max_bits", label: "Focus max bits", group: "Focus", modes: ["Manual"], type: "slider", min: 0, max: 12, step: 1, value: 8 },
-  { id: "quadrant_padding", label: "Focus padding", group: "Focus", modes: ["Manual"], type: "slider", min: 0, max: 32, step: 1, value: 4 },
-  { id: "quadrant_selection_criteria", label: "Focus selection", group: "Focus", modes: ["Manual"], type: "select", options: ["Sum", "Max", "Min"], value: "Sum" },
-
-  { id: "channel_cycle", label: "Channel cycle strategy", group: "Channel cycle", modes: ["Manual"], type: "select", options: ["Smart", "Strict", "Balanced", "123"], value: "Smart" },
-  { id: "strokes_per_channel_cycle", label: "Strokes / cycle", group: "Channel cycle", modes: ["Manual"], type: "slider", min: 10, max: 1000, step: 10, value: 100 },
-  { id: "channel_cycle_warmup_time", label: "Cycle warmup", group: "Channel cycle", modes: ["Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.9 },
-  { id: "cycle_selection_criteria", label: "Cycle selection", group: "Channel cycle", modes: ["Manual"], type: "select", options: ["Min", "Max", "Sum"], value: "Min" },
+  // ---- Search (Semi + Manual) ----
+  { id: "patch_count", label: "Patch count", hint: "more patches = higher quality, larger files, slower", group: "Search", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 500, step: 1, value: 20, full: true },
+  { id: "search_depth", label: "Search depth", group: "Search", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 2000, step: 10, value: 200 },
+  { id: "proposal_depth", label: "Proposal depth", group: "Search", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 500, step: 5, value: 50 },
+  { id: "exact_depth", label: "Exact depth", group: "Search", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 200, step: 1, value: 10 },
+
+  // ---- Quality schedule (Semi + Manual) ----
+  { id: "search_q_start", label: "Search q start", group: "Quality schedule", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.4 },
+  { id: "search_q_end", label: "Search q end", group: "Quality schedule", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.1 },
+  { id: "q_init", label: "Q init", group: "Quality schedule", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.7 },
+  { id: "q_start", label: "Q start", group: "Quality schedule", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.9 },
+  { id: "q_end", label: "Q end", group: "Quality schedule", modes: ["Semi", "Manual"], type: "slider", min: 0, max: 1, step: 0.01, value: 0.9 },
+
+  // ---- Downsampling (Semi + Manual; Manual adds the init-layer knobs) ----
+  { id: "downsample_rate", label: "Downsample rate", hint: "auto = derive from max pixels", group: "Downsampling", modes: ["Semi", "Manual"], type: "slider", min: 1, max: 16, step: 0.1, value: 2, autoToggle: { value: -1 } },
+  { id: "auto_downsample_max_pixels", label: "Auto downsample max pixels", group: "Downsampling", modes: ["Semi", "Manual"], type: "slider", min: 10000, max: 4000000, step: 10000, value: 250000, full: true },
+  { id: "auto_downsample_init", label: "Auto downsample init", group: "Downsampling", modes: ["Manual"], type: "check", value: true },
+  { id: "init_search_depth", label: "Init search depth", group: "Downsampling", modes: ["Manual"], type: "slider", min: 0, max: 50, step: 1, value: 7 },
+  { id: "downsample_init_cell_size", label: "Init cell size", group: "Downsampling", modes: ["Manual"], type: "slider", min: 1, max: 64, step: 1, value: 12 },
+  { id: "downsample_palette_bitcount", label: "Init palette bitcount", group: "Downsampling", modes: ["Manual"], type: "slider", min: 1, max: 9, step: 1, value: 6 },
+
+  // ---- Patch & cell sizing (Manual) ----
+  { id: "min_patch_size", label: "Min patch size", group: "Patch & cell sizing", modes: ["Manual"], type: "slider", min: 1, max: 1024, step: 1, value: 16 },
+  { id: "max_patch_size", label: "Max patch size", group: "Patch & cell sizing", modes: ["Manual"], type: "slider", min: 1, max: 2000, step: 1, value: 400 },
+  { id: "min_cell_size", label: "Min cell size", group: "Patch & cell sizing", modes: ["Manual"], type: "slider", min: 1, max: 64, step: 1, value: 1 },
+  { id: "max_cell_size", label: "Max cell size", group: "Patch & cell sizing", modes: ["Manual"], type: "slider", min: 1, max: 256, step: 1, value: 64 },
+  { id: "cell_sizes_per_candidate", label: "Cell sizes / candidate", group: "Patch & cell sizing", modes: ["Manual"], type: "slider", min: 1, max: 16, step: 1, value: 3 },
+  { id: "top_k", label: "Top-k", group: "Patch & cell sizing", modes: ["Manual"], type: "slider", min: 1, max: 200, step: 1, value: 20 },
+
+  // ---- Color (Manual) ----
+  { id: "color_space", label: "Color space", group: "Color", modes: ["Manual"], type: "select", options: ["RGB", "YCbCr"], value: "YCbCr" },
+  { id: "channel_cycle", label: "Channel cycle", group: "Color", modes: ["Manual"], type: "select", options: ["Off", "Sum", "Max"], value: "Sum" },
+
+  // ---- Palette & bit allocation (Manual) ----
+  { id: "patch_palette_bitcount", label: "Patch palette bitcount", group: "Palette & bits", modes: ["Manual"], type: "slider", min: 1, max: 9, step: 1, value: 2 },
+  { id: "patch_bitcount_mode", label: "Patch bitcount mode", group: "Palette & bits", modes: ["Manual"], type: "select", options: ["constant", "dynamic"], value: "constant" },
+  { id: "dynamic_patch_bitcount_min", label: "Dynamic bitcount min", group: "Palette & bits", modes: ["Manual"], type: "slider", min: 1, max: 9, step: 1, value: 2 },
+  { id: "dynamic_patch_bitcount_max", label: "Dynamic bitcount max", group: "Palette & bits", modes: ["Manual"], type: "slider", min: 1, max: 9, step: 1, value: 3 },
+  { id: "palette_mode", label: "Palette mode", group: "Palette & bits", modes: ["Manual"], type: "select", options: ["generated", "explicit", "auto"], value: "generated" },
+  { id: "explicit_palette_max_bitcount", label: "Explicit palette max bitcount", group: "Palette & bits", modes: ["Manual"], type: "slider", min: 1, max: 9, step: 1, value: 3 },
+  { id: "palette_difference_threshold", label: "Palette diff threshold", group: "Palette & bits", modes: ["Manual"], type: "slider", min: 0, max: 255, step: 1, value: 0 },
+  { id: "palette_difference_threshold_mode", label: "Palette diff threshold mode", group: "Palette & bits", modes: ["Manual"], type: "select", options: ["constant", "linear"], value: "constant" },
+  { id: "mask_size", label: "Mask size", group: "Palette & bits", modes: ["Manual"], type: "slider", min: 1, max: 1023, step: 1, value: 4 },
+  { id: "anchor_block_size", label: "Anchor block size", group: "Palette & bits", modes: ["Manual"], type: "slider", min: 1, max: 64, step: 1, value: 8 },
+  { id: "positive_bias", label: "Positive bias", group: "Palette & bits", modes: ["Manual"], type: "check", value: true },
+
+  // ---- Advanced (Manual) ----
+  { id: "quality_target_mae", label: "Quality target MAE", hint: "0 = off (stop early once MAE drops below this)", group: "Advanced", modes: ["Manual"], type: "slider", min: 0, max: 50, step: 0.1, value: 0, full: true },
+  { id: "use_lzma", label: "Use LZMA", group: "Advanced", modes: ["Manual"], type: "check", value: true },
+  { id: "random_seed", label: "Random seed", group: "Advanced", modes: ["Manual"], type: "slider", min: 0, max: 1000000, step: 1, value: 2003 },
+  { id: "debug_mode", label: "Debug mode", group: "Advanced", modes: ["Manual"], type: "check", value: false },
+  { id: "debug_print", label: "Debug print", group: "Advanced", modes: ["Manual"], type: "check", value: false },
 ];
 
 const paramState = {};
 PARAMS.forEach(p => paramState[p.id] = p.value);
-paramState.downsample_initialize = true; // controlled by the inline "off" checkbox
+paramState.auto_config = "speed";
+PARAMS.filter(p => p.autoToggle).forEach(p => paramState[p.id + "__auto"] = true);
 
 let paramMode = "Auto";
 const paramsBody = document.getElementById("params-body");
@@ -393,10 +424,19 @@ document.querySelectorAll("#param-mode .seg-btn").forEach(b => b.addEventListene
 
 function renderParams() {
   if (paramMode === "Auto") {
-    paramsBody.innerHTML = `<p class="card-date">Auto mode — every parameter is derived from the image. Switch to Semi-Auto or Manual to take control.</p>`;
+    paramsBody.innerHTML = `
+      <p class="card-date">Auto mode — pick a preset configuration; every other parameter is derived from the image.</p>
+      <div class="param-grid">
+        <div class="param-group-title">Preset</div>
+        <div class="param full"><label>Configuration</label>
+          <select data-pid="auto_config">
+            ${AUTO_CONFIGS.map(c => `<option value="${c.id}" ${c.id === paramState.auto_config ? "selected" : ""}>${c.label}</option>`).join("")}
+          </select></div>
+      </div>`;
+    paramsBody.querySelector('[data-pid="auto_config"]').addEventListener("change", e => { paramState.auto_config = e.target.value; });
     return;
   }
-  if (paramMode === "Suggest") { renderSuggest(); return; }
+
   const items = PARAMS.filter(p => p.modes.includes(paramMode));
   let html = `<div class="param-grid">`, group = null;
   items.forEach(p => {
@@ -415,84 +455,40 @@ function renderParams() {
     });
   });
 
-  const off = paramsBody.querySelector("[data-dsioff]");
-  if (off) {
-    const syncDsi = () => {
-      paramState.downsample_initialize = !off.checked;
-      paramsBody.querySelectorAll('[data-pid="downsample_initialize_rate"]').forEach(el => el.disabled = off.checked);
+  // "auto" inline toggles: when checked the submitted value is the param's auto sentinel
+  // (e.g. downsample_rate = -1) and the slider/number are disabled.
+  paramsBody.querySelectorAll("[data-auto]").forEach(cb => {
+    const id = cb.dataset.auto;
+    cb.checked = !!paramState[id + "__auto"];
+    const sync = () => {
+      paramState[id + "__auto"] = cb.checked;
+      paramsBody.querySelectorAll(`[data-pid="${id}"]`).forEach(el => el.disabled = cb.checked);
     };
-    off.addEventListener("change", syncDsi);
-    syncDsi();
-  }
-
-  const gen = paramsBody.querySelector("#gen-mult_list");
-  if (gen) gen.addEventListener("click", async () => {
-    const q = new URLSearchParams({ bit_count: paramState.mult_bit_count, min: paramState.mult_min, max: paramState.mult_max, mode: paramState.multlist_mode });
-    try {
-      const { list } = await (await fetch("/api/multlist?" + q)).json();
-      const s = "[" + list.join(", ") + "]";
-      paramState.mult_list = s;
-      paramsBody.querySelector('[data-pid="mult_list"]').value = s;
-    } catch { toast("Could not generate list"); }
+    cb.addEventListener("change", sync);
+    sync();
   });
 }
 
 function control(p) {
   const v = paramState[p.id];
+  const hint = p.hint ? ` <i>${p.hint}</i>` : "";
   if (p.type === "select")
-    return `<div class="param"><label>${p.label}</label><select data-pid="${p.id}">${p.options.map(o => `<option ${o == v ? "selected" : ""}>${o}</option>`).join("")}</select></div>`;
+    return `<div class="param"><label>${p.label}${hint}</label><select data-pid="${p.id}">${p.options.map(o => `<option ${o == v ? "selected" : ""}>${o}</option>`).join("")}</select></div>`;
   if (p.type === "check")
-    return `<div class="param"><label>${p.label}</label><label class="check-row"><input type="checkbox" data-pid="${p.id}" ${v ? "checked" : ""}> enabled</label></div>`;
-  if (p.type === "text")
-    return `<div class="param full"><label>${p.label}${p.hint ? ` <i>${p.hint}</i>` : ""}</label>
-      <div class="slider-row">
-        <input type="text" class="num" data-pid="${p.id}" value="${v}" style="flex:1;text-align:left">
-        ${p.gen ? `<button type="button" class="gen-btn" id="gen-${p.id}">Generate</button>` : ""}
-      </div></div>`;
+    return `<div class="param"><label>${p.label}${hint}</label><label class="check-row"><input type="checkbox" data-pid="${p.id}" ${v ? "checked" : ""}> enabled</label></div>`;
   return `<div class="param ${p.full ? "full" : ""}">
-      <label>${p.label}${p.hint ? ` <i>${p.hint}</i>` : ""}</label>
+      <label>${p.label}${hint}</label>
       <div class="slider-row">
         <input type="range" data-pid="${p.id}" min="${p.min}" max="${p.max}" step="${p.step}" value="${v}">
         <input type="number" class="num" data-pid="${p.id}" min="${p.min}" max="${p.max}" step="${p.step}" value="${v}">
-        ${p.disableToggle ? `<label class="check-inline"><input type="checkbox" data-dsioff> off</label>` : ""}
+        ${p.autoToggle ? `<label class="check-inline"><input type="checkbox" data-auto="${p.id}"> auto</label>` : ""}
       </div></div>`;
 }
 
-/* ---- Optuna → form mapping (used by the Sweep Analyzer "Load into Demo" and the suggestor) ---- */
-const OPTUNA_MAP = {
-  stroke_count: "stroke_count",
-  size_start: "size_range_start",
-  size_end: "size_range_end",
-  decay_cutoff: "decay_cutoff",
-  decay_softness: "decay_softness",
-  decay_progress: "decay_progress",
-  focus_strokes: "strokes_per_quadrant",
-  focus_warmup: "quadrant_warmup_time",
-  focus_max_bits: "quadrant_max_bits",
-  focus_padding: "quadrant_padding",
-  focus_criteria: "quadrant_selection_criteria",
-  color_space: "color_space",
-  downsample_rate: "downsample_rate",
-  start_mode: "start_mode",
-  channel_cycle_strokes: "strokes_per_channel_cycle",
-  channel_cycle_warmup: "channel_cycle_warmup_time",
-  channel_cycle_criteria: "cycle_selection_criteria",
-  downsample_initialize_rate: "downsample_initialize_rate",
-  downsample_initialize_bits: "downsample_initialize_bits",
-  mult_bit_count: "mult_bit_count",
-  mult_min: "mult_min",
-  mult_max: "mult_max",
-  mult_mode: "multlist_mode",
-};
-
-const RESAMPLE_CAP = {
-  bicubic: "Bicubic",
-  lanczos: "Lanczos",
-  bilinear: "Bilinear",
-  nearest: "Nearest",
-  box: "Box",
-};
-
+/* ---- Sweep Analyzer "Load into Demo" hook -------------------------------
+   The analyzer still emits PBC2.4-style param dumps; PBC3 sweep integration
+   is pending. For now this parses the dump and applies any key that matches a
+   current parameter id, switching to Manual without erroring on the rest. */
 function parseOptuna(text) {
   const out = {};
   text.trim().split(/\r?\n/).forEach(line => {
@@ -501,173 +497,17 @@ function parseOptuna(text) {
   });
   return out;
 }
-
-// opts.keepMode: apply values to paramState without switching the mode, re-rendering
-// the form, or toasting (used by the live suggestor as the user drags the sliders).
-async function applyOptuna(text, opts = {}) {
-  const keepMode = !!opts.keepMode;
+async function applyOptuna(text) {
   const p = parseOptuna(text);
-  if (!Object.keys(p).length) { if (!keepMode) toast("Couldn't parse anything"); return; }
-
-  if (!keepMode) {
-    paramMode = "Manual";
-    document.querySelectorAll("#param-mode .seg-btn").forEach(b => b.classList.toggle("active", b.dataset.mode === "Manual"));
-  }
-
-  for (const [k, v] of Object.entries(p)) if (OPTUNA_MAP[k]) paramState[OPTUNA_MAP[k]] = v;
-  if (p.resample) paramState.downsample_alg = RESAMPLE_CAP[p.resample.toLowerCase()] || "Bicubic";
-  if (p.channel_cycle) paramState.channel_cycle = p.channel_cycle === "Default" ? "123" : p.channel_cycle;
-  if (p.decay_cutoff !== undefined) paramState.decay_mode = "Manual";
-  if (p.downsample_initialize !== undefined) paramState.downsample_initialize = p.downsample_initialize === "True";
-
-  if (p.mult_mode) {
-    const mode = p.mult_mode === "PBC_Default" ? "PBC Default" : p.mult_mode;
-    paramState.multlist_mode = mode;
-
-    if (mode === "PBC Default") {
-      paramState.mult_list = "[-10, 0, 5, 20]";
-    } else if (p.mult_bit_count) {
-      try {
-        const q = new URLSearchParams({
-          bit_count: p.mult_bit_count,
-          min: p.mult_min,
-          max: p.mult_max,
-          mode: p.mult_mode || "Stable_Uniform",
-        });
-        const { list } = await (await fetch("/api/multlist?" + q)).json();
-        paramState.mult_list = "[" + list.join(", ") + "]";
-      } catch {}
-    }
-  }
-  if (!keepMode) {
-    renderParams();
-    toast("Loaded Optuna config");
-  }
-}
-
-/* ============================================================
-   SEMI-AUTO SUGGESTOR  (interpolation over a tuning sweep)
-   Appears as a "Suggest" parameter mode only when the backend
-   recognizes a tuning .db. Three priority sliders pick an
-   operating point interpolated along the study's stroke-count
-   response curves; the result is loaded as a Manual config.
-============================================================ */
-let sweepDb = null;                 // { db_path, studies:[...] } once a .db is recognized
-const sweepTrialCache = {};         // study_name -> trials[]
-
-async function initSuggestor() {
-  try {
-    const d = await (await fetch("/api/sweeps/studies?db_path=")).json();
-    if (d && Array.isArray(d.studies) && d.studies.length) { sweepDb = d; addSuggestMode(); }
-  } catch {}
-}
-
-function addSuggestMode() {
-  const bar = document.getElementById("param-mode");
-  if (!bar || bar.querySelector('[data-mode="Suggest"]')) return;
-  const btn = document.createElement("button");
-  btn.className = "seg-btn";
-  btn.dataset.mode = "Suggest";
-  btn.textContent = "Suggest";
-  btn.style.marginLeft = "auto";
-  btn.addEventListener("click", () => {
-    document.querySelectorAll("#param-mode .seg-btn").forEach(x => x.classList.remove("active"));
-    btn.classList.add("active");
-    // Compress submits Manual params; the suggestor just fills them in.
-    paramMode = "Suggest";
-    renderSuggest();
-  });
-  bar.appendChild(btn);
-}
-
-function sgSlider(id, label, val) {
-  return `<div class="param full"><label>${label} <i id="${id}-v">${val}</i></label>
-    <div class="slider-row"><input type="range" id="${id}" min="0" max="100" value="${val}"></div></div>`;
-}
-
-function renderSuggest() {
-  const studies = sweepDb ? sweepDb.studies : [];
-  paramsBody.innerHTML = `
-    <p class="card-date">Interpolation-based suggestion from a tuning sweep. Set your priorities and the closest stroke-count operating point on the study's Pareto response curves is interpolated, then loaded as a Manual config you can still tweak before compressing.</p>
-    <div class="param-grid">
-      <div class="param-group-title">Sweep study</div>
-      <div class="param full"><label>Study</label>
-        <select id="sg-study">${studies.map(s => `<option value="${s.study_name}">${s.study_name} (${s.n_trials})</option>`).join("")}</select></div>
-      <div class="param-group-title">Priorities</div>
-      ${sgSlider("sg-speed", "Speed priority", 33)}
-      ${sgSlider("sg-comp", "Compression priority", 33)}
-      ${sgSlider("sg-qual", "Quality priority", 34)}
-    </div>
-    <div id="sg-out" class="card-date" style="margin-top:10px"></div>`;
-
-  document.getElementById("sg-study").addEventListener("change", recomputeSuggestion);
-  ["sg-speed", "sg-comp", "sg-qual"].forEach(id => {
-    const el = document.getElementById(id);
-    el.addEventListener("input", () => { document.getElementById(id + "-v").textContent = el.value; recomputeSuggestion(); });
-  });
-  recomputeSuggestion();
-}
-
-async function loadSweepTrials(name) {
-  if (sweepTrialCache[name]) return sweepTrialCache[name];
-  try {
-    const d = await (await fetch(`/api/sweeps/study?db_path=${encodeURIComponent(sweepDb.db_path)}&study_name=${encodeURIComponent(name)}`)).json();
-    if (d.error) return null;
-    sweepTrialCache[name] = d.trials || [];
-    return sweepTrialCache[name];
-  } catch { return null; }
-}
-
-function computeSuggestion(trials, ws, wc, wq) {
-  let set = trials.filter(t => t.pareto);
-  if (!set.length) set = trials;
-  const pts = set.map(t => ({ s: +t.params.stroke_count, q: t.quality, bpp: t.bpp, sp: t.speed, t }))
-    .filter(p => !isNaN(p.s)).sort((a, b) => a.s - b.s);
-  if (!pts.length) return null;
-
-  const sum = (ws + wc + wq) || 1; wq /= sum;
-  const xs = pts.map(p => p.s);
-  const interpKey = (s, key) => {
-    if (s <= xs[0]) return pts[0][key];
-    if (s >= xs[xs.length - 1]) return pts[xs.length - 1][key];
-    for (let i = 1; i < xs.length; i++)
-      if (s <= xs[i]) { const f = (s - xs[i - 1]) / ((xs[i] - xs[i - 1]) || 1); return pts[i - 1][key] + f * (pts[i][key] - pts[i - 1][key]); }
-    return pts[pts.length - 1][key];
-  };
-
-  // Quality favours more strokes; speed and compression both favour fewer. After
-  // normalisation the quality share sets the position along the stroke axis, so moving
-  // any slider slides the operating point gradually between trials instead of snapping
-  // to an endpoint (which a weighted-sum maximum does on near-linear Pareto fronts).
-  const lo = xs[0], hi = xs[xs.length - 1];
-  const s = lo + (hi - lo) * Math.max(0, Math.min(1, wq));
-  const nearest = pts.reduce((a, b) => Math.abs(b.s - s) < Math.abs(a.s - s) ? b : a);
-  return { stroke: Math.round(s), trial: nearest.t, q: interpKey(s, "q"), bpp: interpKey(s, "bpp"), sp: interpKey(s, "sp") };
-}
-
-function suggestionToOptuna(t, stroke) {
-  const lines = Object.entries(t.params).map(([k, v]) =>
-    k === "stroke_count" ? `stroke_count ${stroke}` : `${k} ${v === true ? "True" : v === false ? "False" : v}`);
-  return lines.join("\n");
-}
-
-async function recomputeSuggestion() {
-  const out = document.getElementById("sg-out");
-  if (!out) return;
-  const name = document.getElementById("sg-study").value;
-  const trials = await loadSweepTrials(name);
-  if (!trials) { out.textContent = "Could not load study."; return; }
-  const ws = +document.getElementById("sg-speed").value,
-        wc = +document.getElementById("sg-comp").value,
-        wq = +document.getElementById("sg-qual").value;
-  const sug = computeSuggestion(trials, ws, wc, wq);
-  if (!sug) { out.textContent = "No usable trials in this study."; return; }
-  await applyOptuna(suggestionToOptuna(sug.trial, sug.stroke), { keepMode: true });
-  out.innerHTML = `→ suggested <b>stroke_count=${sug.stroke}</b> (interpolated; companion params from nearest trial #${sug.trial.number}) · predicted quality ${sug.q.toFixed(4)} · bpp ${sug.bpp.toFixed(4)} · ${sug.sp.toFixed(3)} sec/MP. Loaded as Manual params — press Compress.`;
+  if (!Object.keys(p).length) { toast("Couldn't parse anything"); return; }
+  for (const [k, v] of Object.entries(p)) if (k in paramState) paramState[k] = v;
+  paramMode = "Manual";
+  document.querySelectorAll("#param-mode .seg-btn").forEach(b => b.classList.toggle("active", b.dataset.mode === "Manual"));
+  renderParams();
+  toast("Loaded config");
 }
 
 renderParams();
-initSuggestor();
 
 /* ============================================================
    IMAGE INPUT  (compress)
@@ -725,17 +565,17 @@ compressBtn.addEventListener("click", async () => {
   compressBtn.classList.add("busy");
   orbStatus.textContent = "compressing…";
 
-  // The suggestor fills the Manual parameters, so it submits as a Manual run.
-  const fillMode = paramMode === "Suggest" ? "Manual" : paramMode;
   const fd = new FormData();
   fd.append("image", currentFile);
-  fd.append("mode", fillMode);
-  if (fillMode !== "Auto") {
-    PARAMS.filter(p => p.modes.includes(fillMode)).forEach(p => {
+  fd.append("mode", paramMode);
+  if (paramMode === "Auto") {
+    fd.append("auto_config", paramState.auto_config);
+  } else {
+    PARAMS.filter(p => p.modes.includes(paramMode)).forEach(p => {
+      if (p.autoToggle && paramState[p.id + "__auto"]) { fd.append(p.id, p.autoToggle.value); return; }
       const v = paramState[p.id];
       fd.append(p.id, p.type === "check" ? (v ? "true" : "false") : v);
     });
-    fd.append("downsample_initialize", paramState.downsample_initialize ? "true" : "false");
   }
 
   try {
@@ -847,11 +687,14 @@ function card(d) {
   const badge = d.decoded
     ? `<span class="fs-btn" style="left:8px;right:auto;width:auto;padding:0 8px;opacity:1;color:var(--red);font-size:9px;letter-spacing:.12em;text-transform:uppercase;cursor:default">decoded</span>`
     : "";
-  const compareBlock = (!d.decoded && d.original_image)
+
+  // Only show codecs that haven't been generated yet; drop the whole row once both exist.
+  const haveJ = !!d.jpeg_image, haveA = !!d.avif_image;
+  const compareBlock = (!d.decoded && d.original_image && !(haveJ && haveA))
     ? `<div class="foot-row" style="align-items:center;gap:8px">
           <span class="k">Compare to:</span>
-          <button class="chip" data-act="cmp-jpeg" style="color:#7d8cff;border-color:#7d8cff">JPEG</button>
-          <button class="chip" data-act="cmp-avif" style="color:#34d39a;border-color:#34d39a">AVIF</button>
+          ${haveJ ? "" : `<button class="chip" data-act="cmp-jpeg" style="color:#7d8cff;border-color:#7d8cff">JPEG</button>`}
+          ${haveA ? "" : `<button class="chip" data-act="cmp-avif" style="color:#34d39a;border-color:#34d39a">AVIF</button>`}
         </div>`
     : "";
   el.innerHTML = `
@@ -888,12 +731,13 @@ function card(d) {
   return el;
 }
 
-// Encode the registry entry's original image with JPEG/AVIF at PBC's bpp, then expose
+// Encode the registry entry's original image with JPEG/AVIF at PBC3's bpp, then expose
 // it as a "Hold for …" button in the fullscreen viewer (same UX as hold-for-original).
+// Once generated the codec is cached on the entry, so the chip is removed and a repeat
+// click is impossible (renderRegistry rebuilds the card without it).
 async function compareCodec(d, codec, btn) {
-  if (!d.original_image) return;
+  if (!d.original_image || d[codec + "_image"]) return;
   const label = codec.toUpperCase();
-  const old = btn.textContent;
   btn.disabled = true;
   btn.textContent = label + "…";
   try {
@@ -908,18 +752,22 @@ async function compareCodec(d, codec, btn) {
     d[codec + "_image"] = r.image;
     d[codec + "_bpp"] = r.bpp;
     d[codec + "_q"] = r.q;
-    toast(`${label} q${r.q} · ${bppToRate(r.bpp).toFixed(1)}× — hold in fullscreen to compare`);
+    d[codec + "_mse"] = r.mse;
+    d[codec + "_quality"] = r.quality;
+    d[codec + "_size_kb"] = r.size_kb;
+    toast(`${label} q${r.q} ready — hold in fullscreen to compare`);
+    renderRegistry();
     if (!viewer.hidden && registry[viewIndex] === d) renderViewer();
   } catch (e) {
     toast(`${label} comparison failed`);
     console.error(e);
+    btn.disabled = false;
+    btn.textContent = label;
   }
-  btn.disabled = false;
-  btn.textContent = old;
 }
 
 function escapeParams(p) {
-  if (!p || p.mode === "Auto") return "Auto";
+  if (!p || p.mode === "Auto") return p && p.auto_config ? `Auto · ${p.auto_config}` : "Auto";
   return Object.entries(p).filter(([k]) => k !== "mode")
     .map(([k, v]) => `${k}=${Array.isArray(v) ? v.join(",") : v}`).join(" · ") || p.mode;
 }
@@ -954,6 +802,27 @@ function step(dir) {
   if (i >= 0 && i < registry.length) { viewIndex = i; renderViewer(); }
 }
 
+function viewerCaption(d) {
+  if (d.decoded)
+    return `Decoded in ${d.time_seconds}s  |  ${d.compression_rate}× compression`;
+  let cap = `Compressed ${d.compression_rate}× in ${d.time_seconds}s  |  MSE: ${d.mse}  |  Composite Quality: ${d.composite_quality}`;
+  if (d.jpeg_image) cap += `  |  JPEG q${d.jpeg_q} (${bppToRate(d.jpeg_bpp).toFixed(1)}×)`;
+  if (d.avif_image) cap += `  |  AVIF q${d.avif_q} (${bppToRate(d.avif_bpp).toFixed(1)}×)`;
+  return cap;
+}
+
+// While holding for JPEG/AVIF, describe how that codec did against PBC3 at the same bpp.
+function codecCompareCaption(d, codec) {
+  const label = codec.toUpperCase();
+  const fmtSize = d[codec + "_size_kb"], fmtMse = d[codec + "_mse"], fmtCq = d[codec + "_quality"], q = d[codec + "_q"];
+  const pct = (a, b) => Math.abs((a - b) / (b || 1e-9) * 100).toFixed(1);
+  const sizeWord = fmtSize >= d.compressed_kb ? "bigger" : "smaller";        // smaller file = good
+  const mseWord = fmtMse <= d.mse ? "better" : "worse";                      // lower MSE = good
+  const cqWord = fmtCq >= d.composite_quality ? "better" : "worse";          // higher CQ = good
+  return `${label} at q${q} compressed this image ${d.width}×${d.height} with a ${pct(fmtSize, d.compressed_kb)}% ${sizeWord} file size, `
+    + `${pct(fmtMse, d.mse)}% ${mseWord} MSE and ${pct(fmtCq, d.composite_quality)}% ${cqWord} Composite Quality Score.`;
+}
+
 function renderViewer() {
   const d = registry[viewIndex];
   if (!d) return;
@@ -962,37 +831,36 @@ function renderViewer() {
   holdJpeg.hidden = !d.jpeg_image;
   holdAvif.hidden = !d.avif_image;
   [holdBtn, holdJpeg, holdAvif].forEach(b => b.classList.remove("holding"));
-  let cap = d.decoded
-    ? `Decoded in ${d.time_seconds}s  |  ${d.compression_rate}× compression`
-    : `Compressed ${d.compression_rate}× in ${d.time_seconds}s  |  MSE: ${d.mse}  |  Composite Quality: ${d.composite_quality}`;
-  if (d.jpeg_image) cap += `  |  JPEG q${d.jpeg_q} (${bppToRate(d.jpeg_bpp).toFixed(1)}×)`;
-  if (d.avif_image) cap += `  |  AVIF q${d.avif_q} (${bppToRate(d.avif_bpp).toFixed(1)}×)`;
-  document.getElementById("viewer-caption").textContent = cap;
+  document.getElementById("viewer-caption").textContent = viewerCaption(d);
   prevBtn.disabled = viewIndex <= 0;
   nextBtn.disabled = viewIndex >= registry.length - 1;
 }
 
-function wireHold(btn, getSrc) {
+function wireHold(btn, getSrc, getCaption) {
+  const capEl = document.getElementById("viewer-caption");
   const release = () => {
     const d = registry[viewIndex];
     const img = viewerStage.querySelector("img");
     if (d && img) img.src = d.reconstructed_image;
+    if (d) capEl.textContent = viewerCaption(d);
     btn.classList.remove("holding");
   };
   btn.addEventListener("pointerdown", e => {
     e.preventDefault();
+    const d = registry[viewIndex];
     const img = viewerStage.querySelector("img");
     const src = getSrc();
     if (!img || !src) return;
     img.src = src;
+    if (getCaption && d) capEl.textContent = getCaption(d);
     btn.classList.add("holding");
   });
   btn.addEventListener("pointerup", release);
   btn.addEventListener("pointerleave", () => btn.classList.contains("holding") && release());
 }
 wireHold(holdBtn, () => { const d = registry[viewIndex]; return d && d.original_image; });
-wireHold(holdJpeg, () => { const d = registry[viewIndex]; return d && d.jpeg_image; });
-wireHold(holdAvif, () => { const d = registry[viewIndex]; return d && d.avif_image; });
+wireHold(holdJpeg, () => { const d = registry[viewIndex]; return d && d.jpeg_image; }, d => codecCompareCaption(d, "jpeg"));
+wireHold(holdAvif, () => { const d = registry[viewIndex]; return d && d.avif_image; }, d => codecCompareCaption(d, "avif"));
 
 /* ============================================================
    DOWNLOAD
@@ -1032,4 +900,4 @@ function toast(msg) {
 /* ============================================================
    BOOT
 ============================================================ */
-initRoster();
+initRoster();

static/index.html

@@ -16,7 +16,7 @@
   #hold-jpeg, #hold-avif { border-color: var(--hc); color: var(--hc); }
   #hold-jpeg.holding, #hold-avif.holding { background: var(--hc); border-color: var(--hc); color: #fff; }
 </style>
-<link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🧩</text></svg>">
+<link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>👁️</text></svg>">
 </head>
 <body>
 
@@ -24,7 +24,7 @@
 <section id="landing" class="section landing">
   <div class="landing-grid">
     <div class="landing-left">
-      <p class="eyebrow">PBC · v2.4</p>
+      <p class="eyebrow">PBC · v3.0</p>
       <h1 class="title">Probabilistic <em>Brush</em> Compression.</h1>
       <p class="lede">
         An unconventional lossy image compression algorithm. It compresses image