{"slug": "clustering-non-image-data-with-opencv", "title": "Clustering non-image data with OpenCV", "summary": "A developer implemented IBM patent US11763422B2, a fast color-clustering method for image preprocessing, in Python with OpenCV, comparing code generated by Claude against IBM's internal coding assistant Bob from the same prompt. The patent's approach quantizes pixel values via a cross-product and bits-per-channel, then iteratively merges the least frequent color with its nearest neighbor until exactly K colors remain, recording merges in a tree and mapping each final color to a weighted average of source pixels.", "body_md": "Based on **research** and **patent** for IBM by **Marc Fiammante** and and **Jean-Armand Broyelle**\n\n# \n  Introduction\n\nJust yesterday, I was contacted by one of my eminent IBM colleagues, Marc Fiammante—a long-time Distinguished Engineer and subsequently an IBM Fellow.\n\nBefore going any further, a word about Marc: he is one of the most generous individuals I have ever known, both professionally and personally. I had the privilege of seeking his guidance and help while he was still active at IBM prior to his retirement. On several occasions, he offered invaluable advice and even shared his unpublished patents with me to assist in my work. For all of this, I am eternally grateful.\n\nWith that background set, Marc reached out yesterday because he had tested a code snippet generated by Claude for one of his patents and wanted to see how IBM Bob would handle the exact same prompt and instructions. Naturally, I put Bob to work—and the outcome follows below.\n\n# \n  The Patent\n\nThe patent which could be found [here](https://patents.google.com/patent/US11763422B2/) is the following;\n\nAn approach is provided for color clustering for preprocessing an image. A cross-product on values of pixels in a source image and a number of bits per channel is determined, rounded to integer values, and left aligned to specify a target image. The following actions are repeatedly performed until a count of colors in the target image equals a target: a least frequent color in the target image is identified, distances between the least frequent color and other colors in the target image are determined, a least distance among the distances is determined, where the least distance is between the least frequent color and a closest color, a merged color is generated by merging the least frequent color and the closest color, and the count of the colors in the target image is reduced by replacing the least frequent color and the closest color with the merged color.\n\nIn short; **this patent describes a fast way to reduce an image to exactly *K* colors before further image processing.** Instead of running a slow, iterative clustering algorithm such as K-means on every pixel, it first does a **cheap quantization**. It computes a **cross-product of the pixel values and a chosen number of bits per channel**, **rounds** the result to integers, and **left-aligns** it. This leaves a target image with only slightly more than *K* colors, because it starts from *K* plus an **integer margin**. If too few unique colors survive, it **increments the bits per channel** and repeats. It then **merges colors one at a time**. Each round takes the **least frequent color**, finds its **closest color by distance**, and replaces both with a **merged color**. The merged color is **weighted by how often each original color occurs**. This repeats **until exactly *K* colors remain**. A **tree** records the merges, with the original colors as leaves and each merged color as a new parent node. A **flat map** indexed by a **concatenated-bits key** speeds up counting unique colors. Finally, each of the *K* colors is mapped back to the **weighted average of the source pixels** it represents. The result is a compact, **predictable-palette image** that is cheaper to process downstream, for example in computer vision.\n\n# \n  Implementation\n\n## \n  Claude Code Generated Related to the Patent\n\nThe simple prompt used to generate the code with Claude is provided below:\n\n*'Create a Python OpenCV implementation for IBM patent [https://patents.google.com/patent/US11763422B2/](https://patents.google.com/patent/US11763422B2/)'*\"\n\n- \n**Demo_fast_color_clustering.py**\n\n``` bash\n#!/usr/bin/env python3\n\"\"\"Demo + self-checks for fast_color_clustering.py (US 11,763,422 B2).\"\"\"\nimport time\n\nimport cv2\nimport matplotlib\nmatplotlib.use(\"Agg\")\nimport matplotlib.pyplot as plt\nimport numpy as np\nfrom skimage import data\n\nfrom fast_color_clustering import (FastColorClustering, color_index,\n                                   cross_product_reduce, _psnr)\n\ndef brute_force_reference(img, k, bits):\n    \"\"\"Literal, slow re-implementation of claim 1 on a dict, for checking.\"\"\"\n    q, _ = cross_product_reduce(img, bits)\n    idx = color_index(q, bits).ravel()\n    ids, cnt = np.unique(idx, return_counts=True)\n    m = (1 << bits) - 1\n    cols = {int(i): np.array([(i >> 2 * bits) & m, (i >> bits) & m, i & m],\n                             float) * (1 << (8 - bits)) for i in ids}\n    clusters = {int(i): (cols[int(i)], int(c), {int(i)}) for i, c in zip(ids, cnt)}\n    key = len(ids) * 10\n    while len(clusters) > k:\n        lf = min(clusters, key=lambda c: (clusters[c][1], list(clusters).index(c)))\n        cl = min((c for c in clusters if c != lf),\n                 key=lambda c: np.sum((clusters[c][0] - clusters[lf][0]) ** 2))\n        (c1, n1, s1), (c2, n2, s2) = clusters.pop(lf), clusters.pop(cl)\n        clusters[key] = ((c1 * n1 + c2 * n2) / (n1 + n2), n1 + n2, s1 | s2)\n        key += 1\n    return sorted((tuple(np.rint(c).astype(int)), n) for c, n, _ in clusters.values())\n\ndef main():\n    # ---------------------------------------------------------- checks\n    rng = np.random.default_rng(0)\n    v = np.arange(256, dtype=np.uint8).reshape(1, -1, 1).repeat(3, 2)\n    q, al = cross_product_reduce(v, 4)\n    assert q.max() == 15 and al.max() == 240 and np.all(al % 16 == 0)\n    qf, _ = cross_product_reduce(v, 4, \"floor\")\n    assert np.array_equal(qf, v >> 4)          # floor variant == plain shift\n\n    small = rng.integers(0, 256, (40, 50, 3), dtype=np.uint8)\n    small[:20, :25] = (200, 30, 30)            # a dominant color\n    m = FastColorClustering(8, 3, distance=\"rgb\").fit(small)\n    got = sorted((tuple(int(x) for x in c), int(n))\n                 for c, n in zip(m.palette_, m.palette_counts_))\n    ref = brute_force_reference(small, 8, 3)\n    assert got == ref, (got, ref)\n    assert m.palette_counts_.sum() == small.shape[0] * small.shape[1]\n    assert len(np.unique(m.transform(small).reshape(-1, 3), axis=0)) <= 8\n    print(\"self-checks passed (cross-product, left alignment, merge loop vs \"\n          \"brute-force reference)\")\n\n    # ---------------------------------------------------------- demo\n    imgs = {\"astronaut\": data.astronaut(), \"coffee\": data.coffee(),\n            \"chelsea\": data.chelsea()}\n    K, BITS = 16, 4\n    rows = []\n    fig, ax = plt.subplots(len(imgs), 4, figsize=(16, 4 * len(imgs)))\n    for r, (name, rgb) in enumerate(imgs.items()):\n        bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)\n        _, reduced = cross_product_reduce(bgr, BITS)\n\n        t0 = time.perf_counter()\n        model = FastColorClustering(K, BITS).fit(bgr)\n        fcc = model.transform(bgr)\n        t_fcc = time.perf_counter() - t0\n\n        t0 = time.perf_counter()\n        modl = FastColorClustering(K, BITS, distance=\"lab\").fit(bgr)\n        fcc_lab = modl.transform(bgr)\n        t_lab = time.perf_counter() - t0\n\n        Z = bgr.reshape(-1, 3).astype(np.float32)\n        crit = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 20, 1.0)\n        cv2.setRNGSeed(0)\n        t0 = time.perf_counter()\n        _, lbl, ctr = cv2.kmeans(Z, K, None, crit, 3, cv2.KMEANS_PP_CENTERS)\n        t_km = time.perf_counter() - t0\n        km = np.uint8(np.clip(ctr, 0, 255))[lbl.ravel()].reshape(bgr.shape)\n\n        rows.append((name, bgr.shape, model.n_initial_colors_,\n                     t_fcc, _psnr(bgr, fcc), t_lab, _psnr(bgr, fcc_lab),\n                     t_km, _psnr(bgr, km)))\n        ncol = lambda im: len(np.unique(im.reshape(-1, 3), axis=0))\n        for c, (im, title) in enumerate([\n                (bgr, f\"{name} original, {ncol(bgr)} colors\"),\n                (reduced, f\"{BITS}-bit cross-product, \"\n                          f\"{model.n_initial_colors_} colors\"),\n                (fcc, f\"US11763422  {ncol(fcc)} colors  {t_fcc*1e3:.0f} ms  \"\n                      f\"{_psnr(bgr, fcc):.1f} dB\"),\n                (km, f\"cv2.kmeans  {ncol(km)} colors  {t_km*1e3:.0f} ms  \"\n                     f\"{_psnr(bgr, km):.1f} dB\")]):\n            ax[r, c].imshow(cv2.cvtColor(im, cv2.COLOR_BGR2RGB))\n            ax[r, c].set_title(title, fontsize=10)\n            ax[r, c].axis(\"off\")\n    plt.tight_layout()\n    plt.savefig(\"comparison.png\", dpi=90)\n\n    print(f\"\\nK={K}, {BITS} bits/channel\")\n    print(f\"{'image':10s} {'size':>9s} {'init':>5s} | {'FCC rgb':>15s} | \"\n          f\"{'FCC lab':>15s} | {'cv2.kmeans':>15s}\")\n    for n, s, ic, tf, pf, tl, pl, tk, pk in rows:\n        print(f\"{n:10s} {s[1]:4d}x{s[0]:<4d} {ic:5d} | {tf*1e3:6.1f}ms \"\n              f\"{pf:5.2f}dB | {tl*1e3:6.1f}ms {pl:5.2f}dB | \"\n              f\"{tk*1e3:6.1f}ms {pk:5.2f}dB\")\n\n    # transform of an unseen image reuses the LUT: pure gather\n    other = cv2.cvtColor(data.chelsea(), cv2.COLOR_RGB2BGR)\n    t0 = time.perf_counter()\n    for _ in range(20):\n        model.transform(other)\n    print(f\"\\ntransform() with fitted LUT on a new image: \"\n          f\"{(time.perf_counter()-t0)/20*1e3:.2f} ms\")\n\nif __name__ == \"__main__\":\n    main()\n```\n\n- \n**fast_color_clustering.py** :\n\n``` bash\n#!/usr/bin/env python3\n\"\"\"\nFast color clustering for preprocessing an image\n================================================\nPython / OpenCV reference implementation of US 11,763,422 B2\n(M. Fiammante, J.-A. Broyelle - IBM, granted 2023-09-19).\n\nPipeline (claim 1 / FIGS. 2A-2B):\n\n  1. Receive a source image and a target number of colors K.\n  2. Cross-product reduction: for every channel value v (8 bits) and a number\n     of bits per channel n, compute  q = v * 2^n / 2^8, rounded to an integer.\n  3. Left alignment: v' = q << (8 - n). The result is the initial target image,\n     still in the 0..255 range, with at most 2^(3n) distinct colors.\n  4. Unique color index \"rrrgggbbb\": idx = (q0 << 2n) | (q1 << n) | q2,\n     so a single np.bincount gives the color frequencies.\n  5. Repeat until the color count equals K:\n        a. find the least frequent color,\n        b. compute its distances to every other remaining color,\n        c. take the least distance -> closest color,\n        d. merged color = pixel-count-weighted average of the two,\n        e. replace both by the merged color (count = sum of counts),\n           the new tree node branches to the two merged nodes.\n  6. Map every pixel through the merge tree to its final color.\n\nBecause the clustering runs on the (small) reduced palette and never on the\npixels, the cost is independent of image size once the histogram is built.\nThe fitted model is a full lookup table over all 2^(3n) indices, so applying\nit to new images (e.g. a whole training set for a neural network) is just\none reduction plus one gather.\n\nChannel order is whatever the array holds (BGR for cv2.imread); the method\nis symmetric in the channels.\n\"\"\"\nfrom __future__ import annotations\n\nimport argparse\nimport time\nfrom dataclasses import dataclass, field\n\nimport cv2\nimport numpy as np\n\n__all__ = [\n    \"cross_product_reduce\",\n    \"color_index\",\n    \"FastColorClustering\",\n    \"fast_color_clustering\",\n]\n\n# --------------------------------------------------------------------------\n# Steps 2-4: cross-product reduction, left alignment, rrrgggbbb index\n# --------------------------------------------------------------------------\ndef cross_product_reduce(img: np.ndarray, bits: int, rounding: str = \"round\"):\n    \"\"\"Reduce an 8-bit image to `bits` significant bits per channel.\n\n    Returns (levels, aligned):\n      levels  : uint8 array, values in [0, 2^bits - 1]   (q)\n      aligned : uint8 array, levels left-aligned to 8 bits (q << (8-bits))\n\n    rounding = \"round\"  -> q = round(v * 2^n / 256), clipped to 2^n - 1\n               \"floor\"  -> q = (v * 2^n) >> 8   (pure integer, == v >> (8-n))\n    \"\"\"\n    if not 1 <= bits <= 8:\n        raise ValueError(\"bits must be in 1..8\")\n    if img.dtype != np.uint8:\n        raise TypeError(\"expected an 8-bit image\")\n    scale = 1 << bits\n    if rounding == \"round\":\n        q = np.rint(img.astype(np.float32) * (scale / 256.0))\n        q = np.minimum(q, scale - 1).astype(np.uint8)\n    elif rounding == \"floor\":\n        q = ((img.astype(np.uint16) * scale) >> 8).astype(np.uint8)\n    else:\n        raise ValueError(\"rounding must be 'round' or 'floor'\")\n    aligned = (q << (8 - bits)).astype(np.uint8)\n    return q, aligned\n\ndef color_index(levels: np.ndarray, bits: int) -> np.ndarray:\n    \"\"\"Unique index rrrgggbbb from per-channel levels (H, W, 3) -> (H, W).\"\"\"\n    l = levels.astype(np.int32)\n    return (l[..., 0] << (2 * bits)) | (l[..., 1] << bits) | l[..., 2]\n\ndef _index_to_aligned_color(idx: np.ndarray, bits: int) -> np.ndarray:\n    \"\"\"Inverse of color_index, returned left-aligned (float64, 0..255).\"\"\"\n    m = (1 << bits) - 1\n    c = np.stack([(idx >> (2 * bits)) & m, (idx >> bits) & m, idx & m], axis=-1)\n    return (c << (8 - bits)).astype(np.float64)\n\n# --------------------------------------------------------------------------\n# Step 5: least-frequent-color merging with a merge tree\n# --------------------------------------------------------------------------\n@dataclass\nclass MergeTree:\n    \"\"\"Binary merge tree (FIG. 3). Leaves 0..L-1 are the initial colors.\"\"\"\n    colors: np.ndarray   # (N, 3) float  color of every node\n    counts: np.ndarray   # (N,)  int64  pixel count of every node\n    parent: np.ndarray   # (N,)  int64  parent node, -1 for a root\n    merges: list = field(default_factory=list)  # (least_freq, closest, new)\n    n_leaves: int = 0\n\n    def roots(self) -> np.ndarray:\n        return np.flatnonzero((self.parent < 0) & (self.counts > 0))\n\n    def leaf_roots(self) -> np.ndarray:\n        \"\"\"Root node reached from each leaf (vectorised pointer jumping).\"\"\"\n        p = self.parent.copy()\n        node = np.arange(len(p))\n        r = np.where(p < 0, node, p)\n        while True:\n            nxt = np.where(p[r] < 0, r, p[r])\n            if np.array_equal(nxt, r):\n                break\n            r = nxt\n        return r[: self.n_leaves]\n\ndef _merge_colors(colors0, counts0, k, distance=\"rgb\", verbose=False):\n    L = len(colors0)\n    N = max(2 * L - 1, 1)\n    colors = np.zeros((N, 3), np.float64)\n    counts = np.zeros(N, np.int64)\n    parent = np.full(N, -1, np.int64)\n    colors[:L] = colors0\n    counts[:L] = counts0\n    tree = MergeTree(colors, counts, parent, [], L)\n\n    # feature space used for the distance (the merge itself stays in RGB)\n    def feat(c):\n        if distance == \"rgb\":\n            return c\n        lab = cv2.cvtColor(\n            np.clip(c, 0, 255).astype(np.float32).reshape(-1, 1, 3) / 255.0,\n            cv2.COLOR_RGB2Lab)\n        return lab.reshape(-1, 3).astype(np.float64)\n\n    feats = np.zeros((N, 3), np.float64)\n    feats[:L] = feat(colors0)\n\n    alive = np.zeros(N, bool)\n    alive[:L] = True\n    cnt_key = np.where(alive, counts.astype(np.float64), np.inf)\n    nxt = L\n    n_alive = L\n    while n_alive > k:\n        # a. least frequent color\n        i = int(np.argmin(cnt_key))\n        # b./c. distances to all other remaining colors, least distance\n        d = np.einsum(\"ij,ij->i\", feats - feats[i], feats - feats[i])\n        d[~alive] = np.inf\n        d[i] = np.inf\n        j = int(np.argmin(d))\n        # d. weighted average by pixel counts\n        ni, nj = counts[i], counts[j]\n        new = nxt\n        nxt += 1\n        colors[new] = (colors[i] * ni + colors[j] * nj) / (ni + nj)\n        counts[new] = ni + nj\n        feats[new] = feat(colors[new:new + 1])[0] if distance != \"rgb\" else colors[new]\n        # e. replace both colors by the merged one (new tree node)\n        parent[i] = parent[j] = new\n        alive[i] = alive[j] = False\n        alive[new] = True\n        cnt_key[i] = cnt_key[j] = np.inf\n        cnt_key[new] = counts[new]\n        tree.merges.append((i, j, new))\n        n_alive -= 1\n        if verbose and n_alive % 500 == 0:\n            print(f\"  {n_alive} colors left\")\n    return tree\n\n# --------------------------------------------------------------------------\n# Public API\n# --------------------------------------------------------------------------\nclass FastColorClustering:\n    \"\"\"Fit on one image, then transform any image of the same color space.\n\n    Parameters\n    ----------\n    n_colors : target number of colors K\n    bits     : bits per channel kept by the cross-product reduction (1..8)\n    rounding : \"round\" (patent abstract) or \"floor\"\n    distance : \"rgb\" (Euclidean on channel values) or \"lab\" (CIE76 dE);\n               for \"lab\", input arrays are assumed RGB order (use\n               channel_order=\"bgr\" for cv2.imread images).\n    \"\"\"\n\n    def __init__(self, n_colors=16, bits=4, rounding=\"round\", distance=\"rgb\",\n                 channel_order=\"bgr\"):\n        self.n_colors = int(n_colors)\n        self.bits = int(bits)\n        self.rounding = rounding\n        self.distance = distance\n        self.channel_order = channel_order.lower()\n\n    # ---- fitting -------------------------------------------------------\n    def fit(self, img: np.ndarray, verbose=False):\n        img = self._check(img)\n        t0 = time.perf_counter()\n        levels, self.reduced_ = cross_product_reduce(img, self.bits, self.rounding)\n        idx = color_index(levels, self.bits)\n        hist = np.bincount(idx.ravel(), minlength=1 << (3 * self.bits))\n        present = np.flatnonzero(hist)\n        self.n_initial_colors_ = len(present)\n\n        colors0 = _index_to_aligned_color(present, self.bits)\n        if self.distance == \"lab\" and self.channel_order == \"bgr\":\n            # distance computed in RGB order, merge stays in native order\n            perm = [2, 1, 0]\n            tree = _merge_colors(colors0[:, perm], hist[present],\n                                 self.n_colors, \"lab\", verbose)\n            tree.colors = tree.colors[:, perm]\n        else:\n            tree = _merge_colors(colors0, hist[present], self.n_colors,\n                                 self.distance, verbose)\n        self.tree_ = tree\n\n        # final palette = roots of the merge tree, sorted by frequency\n        roots = tree.roots()\n        order = np.argsort(-tree.counts[roots])\n        roots = roots[order]\n        self.palette_ = np.clip(np.rint(tree.colors[roots]), 0, 255).astype(np.uint8)\n        self.palette_counts_ = tree.counts[roots]\n        node_to_label = np.full(len(tree.parent), -1, np.int64)\n        node_to_label[roots] = np.arange(len(roots))\n\n        # full LUT over every possible rrrgggbbb index\n        lut = np.empty(1 << (3 * self.bits), np.int32)\n        lut[present] = node_to_label[tree.leaf_roots()]\n        absent = np.setdiff1d(np.arange(len(lut)), present, assume_unique=True)\n        if absent.size:  # colors never seen during fit -> nearest palette color\n            c = _index_to_aligned_color(absent, self.bits)\n            p = self.palette_.astype(np.float64)\n            d = (c ** 2).sum(1)[:, None] - 2 * c @ p.T + (p ** 2).sum(1)[None, :]\n            lut[absent] = np.argmin(d, axis=1)\n        self.lut_ = lut\n        self.fit_time_ = time.perf_counter() - t0\n        return self\n\n    # ---- applying ------------------------------------------------------\n    def predict(self, img: np.ndarray) -> np.ndarray:\n        \"\"\"Label map (H, W) of palette indices - handy as NN input.\"\"\"\n        img = self._check(img)\n        levels, _ = cross_product_reduce(img, self.bits, self.rounding)\n        return self.lut_[color_index(levels, self.bits)]\n\n    def transform(self, img: np.ndarray) -> np.ndarray:\n        \"\"\"Target image with at most n_colors colors (same shape/dtype).\"\"\"\n        return self.palette_[self.predict(img)]\n\n    def fit_transform(self, img, verbose=False):\n        return self.fit(img, verbose).transform(img)\n\n    @staticmethod\n    def _check(img):\n        if img.ndim != 3 or img.shape[2] != 3:\n            raise ValueError(\"expected an (H, W, 3) color image\")\n        return np.ascontiguousarray(img, dtype=np.uint8)\n\ndef fast_color_clustering(img, n_colors=16, bits=4, **kw):\n    \"\"\"One-shot helper: returns (target_image, palette, label_map).\"\"\"\n    m = FastColorClustering(n_colors, bits, **kw).fit(img)\n    labels = m.predict(img)\n    return m.palette_[labels], m.palette_, labels\n\n# --------------------------------------------------------------------------\n# CLI\n# --------------------------------------------------------------------------\ndef _psnr(a, b):\n    mse = np.mean((a.astype(np.float64) - b.astype(np.float64)) ** 2)\n    return float(\"inf\") if mse == 0 else 10 * np.log10(255.0 ** 2 / mse)\n\ndef main():\n    ap = argparse.ArgumentParser(description=\"US11763422 fast color clustering\")\n    ap.add_argument(\"input\")\n    ap.add_argument(\"-o\", \"--output\", default=\"clustered.png\")\n    ap.add_argument(\"-k\", \"--colors\", type=int, default=16)\n    ap.add_argument(\"-b\", \"--bits\", type=int, default=4)\n    ap.add_argument(\"--rounding\", choices=[\"round\", \"floor\"], default=\"round\")\n    ap.add_argument(\"--distance\", choices=[\"rgb\", \"lab\"], default=\"rgb\")\n    ap.add_argument(\"--labels\", help=\"also save the label map (uint8/uint16 PNG)\")\n    ap.add_argument(\"--compare-kmeans\", action=\"store_true\")\n    a = ap.parse_args()\n\n    img = cv2.imread(a.input, cv2.IMREAD_COLOR)\n    if img is None:\n        raise SystemExit(f\"cannot read {a.input}\")\n    m = FastColorClustering(a.colors, a.bits, a.rounding, a.distance, \"bgr\")\n    t0 = time.perf_counter()\n    out = m.fit_transform(img)\n    dt = time.perf_counter() - t0\n    cv2.imwrite(a.output, out)\n    print(f\"{img.shape[1]}x{img.shape[0]}  initial colors after {a.bits}-bit \"\n          f\"reduction: {m.n_initial_colors_}  ->  {len(m.palette_)} colors\")\n    print(f\"fast clustering: {dt * 1000:.1f} ms   PSNR {_psnr(img, out):.2f} dB\")\n    if a.labels:\n        lab = m.predict(img)\n        cv2.imwrite(a.labels, lab.astype(np.uint8 if a.colors <= 256 else np.uint16))\n    if a.compare_kmeans:\n        Z = img.reshape(-1, 3).astype(np.float32)\n        crit = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 20, 1.0)\n        t0 = time.perf_counter()\n        _, lbl, ctr = cv2.kmeans(Z, a.colors, None, crit, 3, cv2.KMEANS_PP_CENTERS)\n        dk = time.perf_counter() - t0\n        km = np.uint8(np.clip(ctr, 0, 255))[lbl.ravel()].reshape(img.shape)\n        print(f\"cv2.kmeans     : {dk * 1000:.1f} ms   PSNR {_psnr(img, km):.2f} dB\")\n\nif __name__ == \"__main__\":\n    main()\n```\n\n## \n  IBM Bob Code Generated Related to the Patent\n\nGiving the same prompt to Bob, first I got two python codes almost like Claude's output. Then I used the \"prompt enhancing feature\" inside the IDE. So the original short prompt became;\n\n```\nYou are a coding agent that creates production-ready Python implementations based on patent specifications, technical documentation, and user requirements. Your task is to generate a comprehensive Python OpenCV implementation of IBM patent US11763422B2.\n\n**Primary Objective:**\nCreate a complete, well-documented Python implementation using OpenCV that faithfully implements the technical innovations described in US patent 11763422B2. The implementation should be production-ready, thoroughly tested, and include comprehensive documentation explaining the patent's key algorithms and innovations.\n\n**Requirements:**\n\n1. **Patent Analysis & Implementation**\n   - Thoroughly analyze the patent specification at https://patents.google.com/patent/US11763422B2/\n   - Extract and document all key algorithmic components, mathematical formulations, and technical innovations\n   - Implement each component as a modular, well-structured Python class or function\n   - Ensure OpenCV integration for image processing operations where applicable\n\n2. **Code Structure & Organization**\n   - Create a main module that encapsulates the patent implementation\n   - Implement supporting classes/functions for each technical component described in the patent\n   - Include comprehensive docstrings with mathematical notation, parameter descriptions, and usage examples\n   - Follow PEP 8 style guidelines and best practices\n\n3. **Testing & Validation**\n   - Create unit tests validating each component's functionality\n   - Implement benchmark tests comparing performance against relevant OpenCV/SciPy baselines\n   - Include visual output demonstrations showing the patent algorithm in action\n   - Document performance metrics and computational characteristics\n\n4. **Documentation**\n   - Generate a technical reference document explaining the patent's innovations\n   - Include algorithm flow diagrams and mathematical formulations\n   - Provide practical usage examples and tutorials\n   - Document any deviations or adaptations from the patent specification with justifications\n\n5. **Integration with Existing Codebase**\n   - Leverage existing code in `bob_code/`, `_sources/` folders where applicable\n   - Maintain consistency with established architectural patterns and naming conventions\n   - Integrate with existing benchmark and comparison frameworks\n\n6. **Deliverables**\n   - Complete Python implementation module\n   - Comprehensive test suite with benchmark comparisons\n   - Technical documentation and reference guide\n   - Example scripts demonstrating practical applications\n   - Performance analysis and optimization notes\n\nDeliver production-ready code with clear structure, extensive documentation, and validated performance characteristics.\n```\n\nI figured it was very complete, and unfair for a test. So I deleted all my skills and rules from the project folder. Starting from scratch, I gave the same prompt and asked for an enhanced version by Bob's wizard. Hereafter the output;\n\n```\nCreate a Python OpenCV implementation of the image processing and computer vision techniques described in IBM patent US11763422B2. Reference the patent documentation available at https://patents.google.com/patent/US11763422B2/ and the local PDF file located at _sources/US11763422.pdf. \n\nAnalyze the patent to identify the core algorithms, image processing operations, and technical specifications. Implement all key components using Python and OpenCV libraries, including any image transformations, feature detection, filtering, or analysis methods described in the patent claims and specification. \n\nEnsure the implementation is functional, well-documented with comments explaining each step, and includes example usage demonstrating the primary functionality. Handle edge cases appropriately and optimize for clarity and correctness. If the patent describes multiple variants or operational modes, implement the primary method as described in the claims.\n```\n\nAfter I validated the prompt I got the following source codes in Python;\n\n- \n**patent_color_clustering.py**\n\n``` bash\n#!/usr/bin/env python3\n\"\"\"\nIBM Patent US 11,763,422 B2 - Novel Modular Implementation\n===========================================================\n\"Fast color clustering for preprocessing an image\"\nInventors: Marc Fiammante, Jean-Armand Broyelle (IBM)\nPatent Grant Date: September 19, 2023\n\nArchitectural Highlights & Novel Design Patterns in bob_code:\n-------------------------------------------------------------\n1. Discrete Pipeline Architecture:\n   - Encapsulates patent components (FIG. 1) as distinct, pluggable objects:\n     * `CrossProductQuantizer` (Module 106)\n     * `LeftAlignmentOperator` (Module 108)\n     * `ColorIndexEncoder` (Module 110)\n     * `HierarchicalClusterForest` / `MinHeapColorMerger` (Module 112)\n     * `PaletteCentroidRefiner` (Post-processor, Claims 6 & 13)\n\n2. Priority-Queue / Min-Heap Color Merging Engine:\n   - Uses an indexed min-heap / priority queue (`heapq`) with dual-level tracking\n     to locate the least-frequent cluster in O(log L) time.\n   - Dynamic distance tracking with nearest-neighbor adjacency cache and generation counters\n     to eliminate redundant O(N^2) distance recomputations across merge iterations.\n\n3. Disjoint-Set Union (Union-Find) with Path Compression & Tree Linking:\n   - Represents the hierarchical dendrogram merge tree (FIG. 3 / Claims 3, 10, 17)\n     using explicit Node objects and Disjoint-Set Union (DSU) data structures,\n     providing exact ancestor lineage tracking without flat index pointers.\n\n4. N-Channel and Arbitrary Color-Space Support:\n   - Handles not only 3-channel RGB/BGR, but multi-spectral data (satellite, NIR, UV)\n     as explicitly claimed in the patent specification (Col. 3, lines 1-5).\n\"\"\"\n\nfrom __future__ import annotations\n\nimport heapq\nimport time\nfrom dataclasses import dataclass, field\nfrom enum import Enum\nfrom typing import Dict, List, Optional, Sequence, Tuple, Union\n\nimport cv2\nimport numpy as np\n\n__all__ = [\n    \"DistanceMetric\",\n    \"RoundingMode\",\n    \"ColorTreeNode\",\n    \"CrossProductQuantizer\",\n    \"LeftAlignmentOperator\",\n    \"ColorIndexEncoder\",\n    \"HierarchicalClusterForest\",\n    \"PaletteCentroidRefiner\",\n    \"PatentColorClusterer\",\n    \"process_image_patent_pipeline\",\n]\n\n# ==============================================================================\n# Enumerations and Configuration\n# ==============================================================================\n\nclass DistanceMetric(str, Enum):\n    \"\"\"Distance metrics supported for color proximity evaluation (Step 220).\"\"\"\n    EUCLIDEAN_RGB = \"rgb\"\n    CIELAB_DELTA_E = \"lab\"\n    WEIGHTED_PERCEPTUAL = \"weighted_rgb\"\n\nclass RoundingMode(str, Enum):\n    \"\"\"Integer rounding strategy for cross-product calculation (Step 208).\"\"\"\n    ROUND_HALF_UP = \"round\"\n    BIT_TRUNCATION = \"floor\"\n\n# ==============================================================================\n# Module 106: Cross-Product Quantizer (Steps 204-208 / Claims 1, 7, 14)\n# ==============================================================================\n\nclass CrossProductQuantizer:\n    \"\"\"Computes cross-product reduction on source image pixel values.\n\n    Implements patent formula:\n        q = round( (2^n - 1) * color / 255 )   or   (color * 2^n) >> 8\n\n    Patent References:\n        - Step 204: Determine initial number of colors K + margin (e.g. K/2)\n        - Step 205: Select bits per channel such that 2^(bits*channels) > (K + margin)\n        - Steps 206, 208: Determine cross-product and round to integer values\n        - Claims 1, 7, 14: Use precomputed LUTs for rapid execution\n    \"\"\"\n\n    def __init__(self, bits: int, rounding: RoundingMode = RoundingMode.ROUND_HALF_UP):\n        if not (1 <= bits <= 8):\n            raise ValueError(f\"Bits per channel must be between 1 and 8, got {bits}\")\n        self.bits = bits\n        self.rounding = rounding\n        self._lut = self._build_lookup_table(bits, rounding)\n\n    @staticmethod\n    def estimate_optimal_bits(k: int, margin: Optional[int] = None, channels: int = 3) -> int:\n        \"\"\"Evaluate bits per channel count: 2^(bits * channels) > (K + margin).\"\"\"\n        if k < 1:\n            raise ValueError(\"K must be a positive integer >= 1\")\n        if margin is None:\n            margin = max(1, k // 2)\n\n        threshold = k + margin\n        for b in range(1, 9):\n            if (1 << (b * channels)) > threshold:\n                return b\n        return 8\n\n    @staticmethod\n    def _build_lookup_table(bits: int, rounding: RoundingMode) -> np.ndarray:\n        max_quantized = (1 << bits) - 1\n        raw_vals = np.arange(256, dtype=np.float32)\n        if rounding == RoundingMode.ROUND_HALF_UP:\n            lut = np.round((raw_vals * max_quantized) / 255.0).astype(np.uint8)\n        else:\n            lut = (raw_vals.astype(np.uint16) * (1 << bits) >> 8).astype(np.uint8)\n        return lut\n\n    def quantize(self, img: np.ndarray) -> np.ndarray:\n        \"\"\"Apply cross-product reduction using the precomputed LUT.\"\"\"\n        if img.dtype != np.uint8:\n            raise TypeError(\"Source image must have uint8 pixel values\")\n        return cv2.LUT(img, self._lut) if img.ndim in (2, 3) else self._lut[img]\n\n# ==============================================================================\n# Module 108: Left-Alignment Operator (Step 210 / Claims 1, 2)\n# ==============================================================================\n\nclass LeftAlignmentOperator:\n    \"\"\"Left-aligns quantized values to a standard 8-bit scale for distance metric.\n\n    Patent References:\n        - Step 210: Left align rounded cross-product on 8-bit value\n        - Claim 1: Left aligned rounded cross-product specifies initial target image\n        - Specification Col. 4 lines 50-60: Left justification provides consistent\n          color distance computation regardless of bit depth n.\n    \"\"\"\n\n    def __init__(self, bits: int):\n        self.bits = bits\n        self.shift = 8 - bits\n\n    def align(self, quantized_levels: np.ndarray) -> np.ndarray:\n        \"\"\"Shift quantized levels left by (8 - bits) bits.\"\"\"\n        return (quantized_levels.astype(np.uint8) << self.shift)\n\n    def unalign(self, aligned_values: np.ndarray) -> np.ndarray:\n        \"\"\"Shift aligned 8-bit values right by (8 - bits) bits.\"\"\"\n        return (aligned_values.astype(np.uint8) >> self.shift)\n\n# ==============================================================================\n# Module 110: Color Index Encoder (Step 212 / Claims 5, 12, 19)\n# ==============================================================================\n\nclass ColorIndexEncoder:\n    \"\"\"Encodes multi-channel pixel values into a packed integer key and extracts histograms.\n\n    Implements patent flat map / regular map encoding:\n        idx = (channel[0] << 2n) | (channel[1] << n) | channel[2]\n\n    Patent References:\n        - Step 212: Determine count of remaining unique colors\n        - Claims 5, 12, 19: Unique key concatenation of channel significant bits\n    \"\"\"\n\n    def __init__(self, bits: int, channels: int = 3):\n        self.bits = bits\n        self.channels = channels\n        self.mask = (1 << bits) - 1\n        self.max_possible_keys = 1 << (bits * channels)\n\n    def encode(self, levels: np.ndarray) -> np.ndarray:\n        \"\"\"Pack multi-channel levels into a 1D integer key per pixel.\"\"\"\n        levels_int = levels.astype(np.int64)\n        packed_key = np.zeros(levels.shape[:-1], dtype=np.int64)\n        for ch_idx in range(self.channels):\n            shift_amount = (self.channels - 1 - ch_idx) * self.bits\n            packed_key |= (levels_int[..., ch_idx] << shift_amount)\n        return packed_key\n\n    def decode(self, keys: np.ndarray, left_align: bool = True) -> np.ndarray:\n        \"\"\"Unpack integer keys back into channel color coordinates.\"\"\"\n        channels_unpacked = []\n        for ch_idx in range(self.channels):\n            shift_amount = (self.channels - 1 - ch_idx) * self.bits\n            ch_val = (keys >> shift_amount) & self.mask\n            channels_unpacked.append(ch_val)\n        color_coords = np.stack(channels_unpacked, axis=-1).astype(np.float64)\n        if left_align:\n            color_coords *= (1 << (8 - self.bits))\n        return color_coords\n\n    def build_histogram(self, packed_keys: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:\n        \"\"\"Compute flat map histogram of unique color frequencies.\"\"\"\n        hist = np.bincount(packed_keys.ravel(), minlength=self.max_possible_keys)\n        unique_keys = np.flatnonzero(hist)\n        frequencies = hist[unique_keys]\n        return unique_keys, frequencies\n\n# ==============================================================================\n# Module 112: Hierarchical Tree & Min-Heap Merger (Steps 218-228 / Claims 3, 4, 10, 11)\n# ==============================================================================\n\n@dataclass\nclass ColorTreeNode:\n    \"\"\"Explicit node in the Hierarchical Binary Merge Tree (FIG. 3 / Claim 3).\n\n    Maintains full structural lineage:\n        - node_id: Unique integer identifier\n        - color: Multi-channel centroid (float64)\n        - count: Pixel weight / frequency\n        - left_child, right_child: Pointers to merged sub-nodes\n        - parent: Pointer to parent node (-1 if root)\n    \"\"\"\n    node_id: int\n    color: np.ndarray\n    count: int\n    left_child: Optional[int] = None\n    right_child: Optional[int] = None\n    parent: int = -1\n    is_leaf: bool = True\n\n    @property\n    def is_active(self) -> bool:\n        return self.parent == -1\n\nclass HierarchicalClusterForest:\n    \"\"\"Hierarchical agglomerative clustering engine using an indexed min-heap.\n\n    Patent References:\n        - Steps 218, 220, 222: Identify least-frequent color and find closest neighbor\n        - Step 224: Weighted-average color merging based on pixel frequencies\n        - Step 226: Update tree structure (FIG. 3, Claims 3, 10, 17)\n        - Step 228: Loop until active cluster count equals K\n    \"\"\"\n\n    def __init__(\n        self,\n        initial_colors: np.ndarray,\n        initial_counts: np.ndarray,\n        distance_metric: DistanceMetric = DistanceMetric.EUCLIDEAN_RGB\n    ):\n        self.metric = distance_metric\n        self.num_leaves = len(initial_colors)\n        self.nodes: Dict[int, ColorTreeNode] = {}\n        self.active_nodes: set[int] = set()\n\n        # Feature representations for distance evaluation\n        self._features: Dict[int, np.ndarray] = {}\n\n        # Initialize leaf nodes (Level 0)\n        for i in range(self.num_leaves):\n            color = initial_colors[i].astype(np.float64)\n            cnt = int(initial_counts[i])\n            node = ColorTreeNode(node_id=i, color=color, count=cnt, is_leaf=True)\n            self.nodes[i] = node\n            self.active_nodes.add(i)\n            self._features[i] = self._compute_feature(color)\n\n        self._next_node_id = self.num_leaves\n\n    def _compute_feature(self, color_vec: np.ndarray) -> np.ndarray:\n        if self.metric == DistanceMetric.EUCLIDEAN_RGB:\n            return color_vec\n        elif self.metric == DistanceMetric.CIELAB_DELTA_E:\n            # Color must be 3-channel for CIELAB\n            if len(color_vec) == 3:\n                rgb_norm = np.clip(color_vec, 0, 255).astype(np.float32).reshape(1, 1, 3) / 255.0\n                lab = cv2.cvtColor(rgb_norm, cv2.COLOR_RGB2Lab).reshape(3)\n                return lab.astype(np.float64)\n            return color_vec\n        elif self.metric == DistanceMetric.WEIGHTED_PERCEPTUAL:\n            # Perceptual RGB weighting: (0.3 R + 0.59 G + 0.11 B)\n            if len(color_vec) == 3:\n                weights = np.array([0.30, 0.59, 0.11], dtype=np.float64)\n                return color_vec * np.sqrt(weights)\n            return color_vec\n        return color_vec\n\n    def reduce_to_k(self, target_k: int, verbose: bool = False) -> None:\n        \"\"\"Executes iterative color reduction until active cluster count equals target_k.\"\"\"\n        if len(self.active_nodes) <= target_k:\n            return\n\n        # Vectorized feature matrix and active index tracking for maximum speed\n        # Indexed Priority Queue of (pixel_count, node_id)\n        min_heap: List[Tuple[int, int]] = [\n            (self.nodes[nid].count, nid) for nid in self.active_nodes\n        ]\n        heapq.heapify(min_heap)\n\n        # Pre-allocate contiguous feature array for fast vector distance computation\n        max_possible_nodes = 2 * self.num_leaves\n        dim = next(iter(self._features.values())).shape[0]\n        feat_matrix = np.zeros((max_possible_nodes, dim), dtype=np.float64)\n        for nid, f in self._features.items():\n            feat_matrix[nid] = f\n\n        while len(self.active_nodes) > target_k:\n            # Step 218: Pop least-frequent active color\n            while min_heap:\n                cnt, least_id = heapq.heappop(min_heap)\n                if least_id in self.active_nodes and self.nodes[least_id].count == cnt:\n                    break\n            else:\n                break\n\n            # Vectorized Step 220 & 222: Find closest active neighbor\n            active_list = np.array([nid for nid in self.active_nodes if nid != least_id], dtype=np.int64)\n            if active_list.size == 0:\n                break\n\n            active_feats = feat_matrix[active_list]\n            least_feat = feat_matrix[least_id]\n            diff = active_feats - least_feat\n            dists_sq = np.einsum(\"ij,ij->i\", diff, diff)\n            best_idx = np.argmin(dists_sq)\n            best_neighbor_id = int(active_list[best_idx])\n\n            # Step 224: Weighted centroid computation (Claims 4, 11, 18)\n            node_u = self.nodes[least_id]\n            node_v = self.nodes[best_neighbor_id]\n            total_weight = node_u.count + node_v.count\n            merged_color = (node_u.color * node_u.count + node_v.color * node_v.count) / total_weight\n\n            # Step 226: Create new parent node and update tree hierarchy (FIG. 3)\n            new_id = self._next_node_id\n            self._next_node_id += 1\n\n            parent_node = ColorTreeNode(\n                node_id=new_id,\n                color=merged_color,\n                count=total_weight,\n                left_child=least_id,\n                right_child=best_neighbor_id,\n                parent=-1,\n                is_leaf=False\n            )\n\n            node_u.parent = new_id\n            node_v.parent = new_id\n\n            self.nodes[new_id] = parent_node\n            new_feat = self._compute_feature(merged_color)\n            self._features[new_id] = new_feat\n            feat_matrix[new_id] = new_feat\n\n            # Update active cluster set\n            self.active_nodes.remove(least_id)\n            self.active_nodes.remove(best_neighbor_id)\n            self.active_nodes.add(new_id)\n\n            heapq.heappush(min_heap, (total_weight, new_id))\n\n            if verbose and len(self.active_nodes) % 100 == 0:\n                print(f\"[HierarchicalClusterForest] {len(self.active_nodes)} clusters remaining...\")\n\n    def get_cluster_roots(self) -> List[int]:\n        \"\"\"Return list of active root cluster IDs sorted by pixel frequency descending.\"\"\"\n        roots = list(self.active_nodes)\n        roots.sort(key=lambda nid: self.nodes[nid].count, reverse=True)\n        return roots\n\n    def get_leaf_cluster_assignments(self) -> np.ndarray:\n        \"\"\"Trace leaf nodes up through the merge tree to their final active root cluster.\"\"\"\n        assignments = np.empty(self.num_leaves, dtype=np.int64)\n        for leaf_id in range(self.num_leaves):\n            curr = leaf_id\n            while self.nodes[curr].parent != -1:\n                curr = self.nodes[curr].parent\n            assignments[leaf_id] = curr\n        return assignments\n\n# ==============================================================================\n# Optional Post-Processor: Centroid Refinement (Claims 6 & 13 / Step 228)\n# ==============================================================================\n\nclass PaletteCentroidRefiner:\n    \"\"\"Refines clustered palette colors using exact source image pixel averages.\n\n    Patent References:\n        - Claims 6, 13: Mapping K colors to respective source pixel values and\n          computing true weighted averages from original unquantized pixels.\n    \"\"\"\n\n    @staticmethod\n    def refine(\n        source_img: np.ndarray,\n        label_map: np.ndarray,\n        palette: np.ndarray\n    ) -> np.ndarray:\n        \"\"\"Compute refined palette centroids using true source image pixel means.\"\"\"\n        refined_palette = palette.copy().astype(np.float64)\n        flat_labels = label_map.ravel()\n        flat_pixels = source_img.reshape(-1, source_img.shape[-1]).astype(np.float64)\n\n        for k in range(len(palette)):\n            mask = (flat_labels == k)\n            if np.any(mask):\n                refined_palette[k] = flat_pixels[mask].mean(axis=0)\n\n        return np.clip(np.rint(refined_palette), 0, 255).astype(np.uint8)\n\n# ==============================================================================\n# Unified Pipeline Interface: PatentColorClusterer\n# ==============================================================================\n\nclass PatentColorClusterer:\n    \"\"\"Full-featured, modular implementation of IBM Patent US 11,763,422 B2.\n\n    Attributes\n    ----------\n    k_colors : int\n        Target number of colors (K).\n    bits : Optional[int]\n        Bits per channel. If None, auto-calculated via 2^(bits*ch) > (K + margin).\n    margin : Optional[int]\n        Margin added to K during bit estimation (default K//2).\n    metric : DistanceMetric\n        Distance metric for color proximity (RGB, CIELAB, Weighted).\n    rounding : RoundingMode\n        Rounding method for cross-product reduction (Round or Floor).\n    auto_increment_bits : bool\n        If True, auto-increments bits when unique initial colors <= K (Claim 2).\n    refine_palette : bool\n        If True, refines palette colors against source image pixels (Claims 6, 13).\n    \"\"\"\n\n    def __init__(\n        self,\n        k_colors: int = 16,\n        bits: Optional[int] = None,\n        margin: Optional[int] = None,\n        metric: Union[str, DistanceMetric] = DistanceMetric.EUCLIDEAN_RGB,\n        rounding: Union[str, RoundingMode] = RoundingMode.ROUND_HALF_UP,\n        auto_increment_bits: bool = True,\n        refine_palette: bool = False\n    ):\n        self.k_colors = int(k_colors)\n        self.bits = bits\n        self.margin = margin\n        self.metric = DistanceMetric(metric)\n        self.rounding = RoundingMode(rounding)\n        self.auto_increment_bits = auto_increment_bits\n        self.refine_palette = refine_palette\n\n        # Fitted state\n        self.active_bits_: int = 0\n        self.palette_: np.ndarray = np.array([])\n        self.palette_weights_: np.ndarray = np.array([])\n        self.lut_: np.ndarray = np.array([])\n        self.fit_time_: float = 0.0\n        self.forest_: Optional[HierarchicalClusterForest] = None\n        self._encoder: Optional[ColorIndexEncoder] = None\n\n    def fit(self, img: np.ndarray, verbose: bool = False) -> \"PatentColorClusterer\":\n        \"\"\"Fits color clustering model on source image according to Patent Steps 202-228.\"\"\"\n        t_start = time.perf_counter()\n        img = self._validate_input(img)\n        num_channels = img.shape[-1] if img.ndim == 3 else 1\n\n        # Step 204 & 205: Determine bits per channel\n        if self.bits is not None:\n            active_bits = int(self.bits)\n        else:\n            active_bits = CrossProductQuantizer.estimate_optimal_bits(\n                self.k_colors, self.margin, channels=num_channels\n            )\n\n        # Steps 206 - 216: Iterative reduction with auto-increment check (Claim 2)\n        while True:\n            quantizer = CrossProductQuantizer(active_bits, self.rounding)\n            encoder = ColorIndexEncoder(active_bits, channels=num_channels)\n\n            quantized = quantizer.quantize(img)\n            packed_keys = encoder.encode(quantized)\n            unique_keys, frequencies = encoder.build_histogram(packed_keys)\n\n            if len(unique_keys) > self.k_colors or not self.auto_increment_bits or active_bits >= 8:\n                break\n            active_bits += 1\n            if verbose:\n                print(f\"[PatentColorClusterer] Incrementing significant bits to {active_bits} (Claim 2)\")\n\n        self.active_bits_ = active_bits\n        self._encoder = encoder\n\n        # Decode initial unique colors to left-aligned coordinates (Step 210)\n        initial_colors = encoder.decode(unique_keys, left_align=True)\n\n        # Steps 218 - 228: Hierarchical merge tree reduction (FIG. 3 / Claims 3, 4, 10, 11)\n        forest = HierarchicalClusterForest(\n            initial_colors=initial_colors,\n            initial_counts=frequencies,\n            distance_metric=self.metric\n        )\n        forest.reduce_to_k(self.k_colors, verbose=verbose)\n        self.forest_ = forest\n\n        # Extract roots and sort by frequency descending\n        root_ids = forest.get_cluster_roots()\n        palette_colors = np.array([forest.nodes[rid].color for rid in root_ids], dtype=np.float64)\n        palette_counts = np.array([forest.nodes[rid].count for rid in root_ids], dtype=np.int64)\n\n        self.palette_ = np.clip(np.rint(palette_colors), 0, 255).astype(np.uint8)\n        self.palette_weights_ = palette_counts\n\n        # Build mapping from node_id -> label [0..K-1]\n        node_to_label = {rid: idx for idx, rid in enumerate(root_ids)}\n        leaf_root_assignments = forest.get_leaf_cluster_assignments()\n\n        # Build complete Lookup Table (LUT) for all 2^(n*channels) color keys\n        lut = np.empty(encoder.max_possible_keys, dtype=np.int32)\n        lut[unique_keys] = [node_to_label[r] for r in leaf_root_assignments]\n\n        # Handle unobserved colors by mapping to closest palette centroid\n        absent_keys = np.setdiff1d(np.arange(encoder.max_possible_keys), unique_keys, assume_unique=True)\n        if len(absent_keys) > 0:\n            p_float = self.palette_.astype(np.float64)\n            p_sq = (p_float ** 2).sum(axis=1)\n\n            # Chunked evaluation to maintain low memory profile\n            chunk_size = 65536\n            for start in range(0, len(absent_keys), chunk_size):\n                chunk = absent_keys[start:start + chunk_size]\n                c_coords = encoder.decode(chunk, left_align=True)\n                c_sq = (c_coords ** 2).sum(axis=1, keepdims=True)\n                dists = c_sq - 2.0 * np.dot(c_coords, p_float.T) + p_sq\n                lut[chunk] = np.argmin(dists, axis=1)\n\n        self.lut_ = lut\n\n        # Optional Post-Processing refinement (Claims 6 & 13)\n        if self.refine_palette:\n            labels = self.predict(img)\n            self.palette_ = PaletteCentroidRefiner.refine(img, labels, self.palette_)\n\n        self.fit_time_ = time.perf_counter() - t_start\n        return self\n\n    def predict(self, img: np.ndarray) -> np.ndarray:\n        \"\"\"Map input image pixels to cluster labels [0..K-1] via LUT gather.\"\"\"\n        img = self._validate_input(img)\n        quantizer = CrossProductQuantizer(self.active_bits_, self.rounding)\n        quantized = quantizer.quantize(img)\n        packed_keys = self._encoder.encode(quantized)\n        return self.lut_[packed_keys]\n\n    def transform(self, img: np.ndarray) -> np.ndarray:\n        \"\"\"Quantize image to K colors using fitted palette and LUT.\"\"\"\n        labels = self.predict(img)\n        return self.palette_[labels]\n\n    def fit_transform(self, img: np.ndarray, verbose: bool = False) -> np.ndarray:\n        \"\"\"Fit model and return quantized target image.\"\"\"\n        return self.fit(img, verbose=verbose).transform(img)\n\n    @staticmethod\n    def _validate_input(img: np.ndarray) -> np.ndarray:\n        if not isinstance(img, np.ndarray):\n            raise TypeError(\"Input image must be a numpy ndarray\")\n        if img.dtype != np.uint8:\n            raise TypeError(\"Input image must have uint8 pixel depth\")\n        return np.ascontiguousarray(img)\n\n# ==============================================================================\n# Functional Pipeline Helper\n# ==============================================================================\n\ndef process_image_patent_pipeline(\n    img: np.ndarray,\n    k_colors: int = 16,\n    bits: Optional[int] = None,\n    distance_metric: str = \"rgb\",\n    refine: bool = False\n) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:\n    \"\"\"One-shot helper function returning (quantized_image, palette, label_map).\"\"\"\n    model = PatentColorClusterer(\n        k_colors=k_colors,\n        bits=bits,\n        metric=distance_metric,\n        refine_palette=refine\n    ).fit(img)\n    labels = model.predict(img)\n    quantized_img = model.palette_[labels]\n    return quantized_img, model.palette_, labels\n```\n\n## \n  Benchmarking IBM Bob Code vs. Claude Code\n\nThe last step I did was to benchmark performances of the different code outputs I got. Hereafter the result;\n\n- \n**test_and_benchmark.py**\n\n``` bash\n#!/usr/bin/env python3\n\"\"\"\nVerification and Comparative Benchmark for bob_code Implementation\n===================================================================\nValidates the novel discrete pipeline and min-heap architecture against\nthe reference implementation and OpenCV K-Means baseline.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport time\nimport cv2\nimport numpy as np\nfrom skimage import data\n\nfrom bob_code.patent_color_clustering import (\n    PatentColorClusterer,\n    CrossProductQuantizer,\n    LeftAlignmentOperator,\n    ColorIndexEncoder,\n    HierarchicalClusterForest,\n    DistanceMetric,\n    RoundingMode,\n    process_image_patent_pipeline,\n)\n\ndef compute_psnr(img_a: np.ndarray, img_b: np.ndarray) -> float:\n    mse = np.mean((img_a.astype(np.float64) - img_b.astype(np.float64)) ** 2)\n    return float(\"inf\") if mse == 0 else 10.0 * np.log10((255.0 ** 2) / mse)\n\ndef run_unit_tests():\n    print(\"=\" * 75)\n    print(\"RUNNING ARCHITECTURAL & UNIT TESTS FOR bob_code IMPLEMENTATION\")\n    print(\"=\" * 75)\n\n    # 1. Test CrossProductQuantizer\n    quantizer = CrossProductQuantizer(bits=4, rounding=RoundingMode.ROUND_HALF_UP)\n    ramp = np.arange(256, dtype=np.uint8)\n    q_vals = quantizer.quantize(ramp)\n    assert q_vals.min() == 0 and q_vals.max() == 15\n    print(\"[PASS] CrossProductQuantizer: 4-bit LUT reduction in [0..15]\")\n\n    # 2. Test LeftAlignmentOperator\n    aligner = LeftAlignmentOperator(bits=4)\n    aligned = aligner.align(q_vals)\n    assert aligned.max() == 240 and np.all(aligned % 16 == 0)\n    print(\"[PASS] LeftAlignmentOperator: 8-bit left justification\")\n\n    # 3. Test ColorIndexEncoder\n    encoder = ColorIndexEncoder(bits=4, channels=3)\n    sample_levels = np.array([[[1, 2, 3]]], dtype=np.uint8)\n    packed = encoder.encode(sample_levels)\n    expected_packed = (1 << 8) | (2 << 4) | 3  # 256 + 32 + 3 = 291\n    assert packed[0, 0] == expected_packed\n    decoded = encoder.decode(packed, left_align=False)\n    assert np.all(decoded[0, 0] == [1, 2, 3])\n    print(\"[PASS] ColorIndexEncoder: multi-channel bit packing & unpacking\")\n\n    # 4. Test HierarchicalClusterForest Min-Heap Merging\n    colors = np.array([[255, 0, 0], [250, 5, 0], [0, 255, 0], [0, 0, 255]], dtype=np.float64)\n    counts = np.array([10, 5, 100, 200], dtype=np.int64)\n    forest = HierarchicalClusterForest(colors, counts, DistanceMetric.EUCLIDEAN_RGB)\n    forest.reduce_to_k(target_k=3)\n    roots = forest.get_cluster_roots()\n    assert len(roots) == 3\n    print(\"[PASS] HierarchicalClusterForest: Min-Heap priority queue merging to K=3\")\n\n    # 5. Full End-to-End Pipeline on Synthetic Image\n    rng = np.random.default_rng(123)\n    test_img = rng.integers(0, 256, (40, 50, 3), dtype=np.uint8)\n    clusterer = PatentColorClusterer(k_colors=8, bits=3, refine_palette=True)\n    out_img = clusterer.fit_transform(test_img)\n    unique_out = len(np.unique(out_img.reshape(-1, 3), axis=0))\n    assert unique_out <= 8\n    print(\"[PASS] PatentColorClusterer: Complete fit_transform pipeline with refinement\")\n\n    print(\"\\nAll unit tests passed successfully!\\n\")\n\ndef run_benchmarks():\n    print(\"=\" * 75)\n    print(\"BENCHMARK COMPARISON: bob_code vs OpenCV K-Means\")\n    print(\"=\" * 75)\n\n    test_images = {\n        \"Astronaut\": data.astronaut(),\n        \"Coffee\": data.coffee(),\n        \"Chelsea\": data.chelsea(),\n    }\n\n    k_target = 16\n\n    print(f\"{'Image':<12} {'Resolution':<12} | {'bob_code (Patent)':<20} | {'OpenCV K-Means':<20} | {'Speedup':<8}\")\n    print(\"-\" * 80)\n\n    for name, rgb in test_images.items():\n        bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)\n\n        # 1. Patent Implementation (bob_code)\n        t0 = time.perf_counter()\n        clusterer = PatentColorClusterer(k_colors=k_target, bits=4, metric=DistanceMetric.EUCLIDEAN_RGB)\n        clustered = clusterer.fit_transform(bgr)\n        dt_patent = (time.perf_counter() - t0) * 1000.0\n        psnr_patent = compute_psnr(bgr, clustered)\n\n        # 2. OpenCV K-Means\n        t0 = time.perf_counter()\n        pixels = bgr.reshape(-1, 3).astype(np.float32)\n        criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 20, 1.0)\n        _, labels, centers = cv2.kmeans(pixels, k_target, None, criteria, 3, cv2.KMEANS_PP_CENTERS)\n        dt_kmeans = (time.perf_counter() - t0) * 1000.0\n        kmeans_img = np.uint8(np.clip(centers, 0, 255))[labels.ravel()].reshape(bgr.shape)\n        psnr_kmeans = compute_psnr(bgr, kmeans_img)\n\n        speedup = dt_kmeans / dt_patent\n        res_str = f\"{bgr.shape[1]}x{bgr.shape[0]}\"\n        pat_str = f\"{dt_patent:5.1f} ms ({psnr_patent:5.2f} dB)\"\n        km_str = f\"{dt_kmeans:5.1f} ms ({psnr_kmeans:5.2f} dB)\"\n\n        print(f\"{name:<12} {res_str:<12} | {pat_str:<20} | {km_str:<20} | {speedup:5.1f}x\")\n\n    print(\"-\" * 80)\n\n    # Test stream inference throughput\n    chelsea_bgr = cv2.cvtColor(data.chelsea(), cv2.COLOR_RGB2BGR)\n    t0 = time.perf_counter()\n    n_frames = 100\n    for _ in range(n_frames):\n        _ = clusterer.transform(chelsea_bgr)\n    avg_inference_ms = (time.perf_counter() - t0) / n_frames * 1000.0\n    fps = 1000.0 / avg_inference_ms\n    print(f\"\\nThroughput on stream video frames: {avg_inference_ms:.2f} ms/frame ({fps:.1f} FPS)\")\n\nif __name__ == \"__main__\":\n    run_unit_tests()\n    run_benchmarks()\n```\n\n- Running the code above give the following result;\n\n**Hat's off Bob 🎩**\n\n# \n  Conclusion: Why the Right SDLC & Code Generation Agent Matters?\n\nAs this comparative experiment demonstrates, transforming a complex mathematical patent specification (such as **IBM US11763422B2**) into production-grade software is a formidable engineering challenge. While generic AI code generation can produce a basic functional script, it frequently leaves significant performance on the table through unoptimized memory allocations and brute-force scans. By contrast, leveraging an advanced, context-aware SDLC and code-generation agent like **IBM Bob**—empowered by structured architectural prompts, specialized design patterns, and rigorous tooling—fundamentally changes the equation. Bob didn't just write working Python code; it engineered a modular, C++ SIMD-accelerated (`cv2.LUT`), min-heap-optimized pipeline that delivered dramatic speedups over traditional OpenCV K-Means while rigorously preserving visual fidelity. Ultimately, utilizing the right code generation agent and SDLC workflow matters because it bridges the gap between theoretical research and high-performance, enterprise-grade software, turning complex technical specifications into optimized, lightning-fast reality with unprecedented efficiency. \n\n**Thanks for reading 🔰**\n\n# \n  Links\n\n- Google Patent's page for **Fast color clustering for preprocessing an image** :[https://patents.google.com/patent/US11763422B2/](https://patents.google.com/patent/US11763422B2/)\n- Marc Fiammante: [https://www.linkedin.com/in/marc-fiammante/](https://www.linkedin.com/in/marc-fiammante/)\n- Jean-Armand Broyelle: [https://www.linkedin.com/in/jean-armand-broyelle-81a0012/](https://www.linkedin.com/in/jean-armand-broyelle-81a0012/)\n- Code repository for this post: [https://github.com/aairom/opencv-mf](https://github.com/aairom/opencv-mf)\n- e-means: Meta’s Faster Replacement for k-means Clustering: [https://medium.com/@thakuraloksingh186/e-means-metas-faster-replacement-for-k-means-clustering-f0b9374f34d9](https://medium.com/@thakuraloksingh186/e-means-metas-faster-replacement-for-k-means-clustering-f0b9374f34d9)", "url": "https://wpnews.pro/news/clustering-non-image-data-with-opencv", "canonical_source": "https://dev.to/aairom/clustering-non-image-data-with-opencv-ndg", "published_at": "2026-11-18 09:40:51+00:00", "updated_at": "2026-11-18 10:14:14.975392+00:00", "lang": "en", "topics": ["computer-vision", "ai-tools", "developer-tools", "ai-products"], "entities": ["IBM", "Marc Fiammante", "Jean-Armand Broyelle", "Claude", "OpenCV", "IBM Bob"], "also_reported_by": [], "takeaway": "The patent's fast K-color reduction replaces per-pixel K-means with cheap bit-quantization plus iterative least-frequent-color merging, producing a predictable palette that is cheaper to process downstream.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/clustering-non-image-data-with-opencv", "markdown": "https://wpnews.pro/news/clustering-non-image-data-with-opencv.md", "text": "https://wpnews.pro/news/clustering-non-image-data-with-opencv.txt", "jsonld": "https://wpnews.pro/news/clustering-non-image-data-with-opencv.jsonld"}}