# Clustering non-image data with OpenCV

> Source: <https://dev.to/aairom/clustering-non-image-data-with-opencv-ndg>
> Published: 2026-11-18 09:40:51+00:00

**Key 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.

Based on **research** and **patent** for IBM by **Marc Fiammante** and and **Jean-Armand Broyelle**

# 
  Introduction

Just yesterday, I was contacted by one of my eminent IBM colleagues, Marc Fiammante—a long-time Distinguished Engineer and subsequently an IBM Fellow.

Before 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.

With 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.

# 
  The Patent

The patent which could be found [here](https://patents.google.com/patent/US11763422B2/) is the following;

An 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.

In 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.

# 
  Implementation

## 
  Claude Code Generated Related to the Patent

The simple prompt used to generate the code with Claude is provided below:

*'Create a Python OpenCV implementation for IBM patent [https://patents.google.com/patent/US11763422B2/](https://patents.google.com/patent/US11763422B2/)'*"

- 
**Demo_fast_color_clustering.py**

``` bash
#!/usr/bin/env python3
"""Demo + self-checks for fast_color_clustering.py (US 11,763,422 B2)."""
import time

import cv2
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
import numpy as np
from skimage import data

from fast_color_clustering import (FastColorClustering, color_index,
                                   cross_product_reduce, _psnr)

def brute_force_reference(img, k, bits):
    """Literal, slow re-implementation of claim 1 on a dict, for checking."""
    q, _ = cross_product_reduce(img, bits)
    idx = color_index(q, bits).ravel()
    ids, cnt = np.unique(idx, return_counts=True)
    m = (1 << bits) - 1
    cols = {int(i): np.array([(i >> 2 * bits) & m, (i >> bits) & m, i & m],
                             float) * (1 << (8 - bits)) for i in ids}
    clusters = {int(i): (cols[int(i)], int(c), {int(i)}) for i, c in zip(ids, cnt)}
    key = len(ids) * 10
    while len(clusters) > k:
        lf = min(clusters, key=lambda c: (clusters[c][1], list(clusters).index(c)))
        cl = min((c for c in clusters if c != lf),
                 key=lambda c: np.sum((clusters[c][0] - clusters[lf][0]) ** 2))
        (c1, n1, s1), (c2, n2, s2) = clusters.pop(lf), clusters.pop(cl)
        clusters[key] = ((c1 * n1 + c2 * n2) / (n1 + n2), n1 + n2, s1 | s2)
        key += 1
    return sorted((tuple(np.rint(c).astype(int)), n) for c, n, _ in clusters.values())

def main():
    # ---------------------------------------------------------- checks
    rng = np.random.default_rng(0)
    v = np.arange(256, dtype=np.uint8).reshape(1, -1, 1).repeat(3, 2)
    q, al = cross_product_reduce(v, 4)
    assert q.max() == 15 and al.max() == 240 and np.all(al % 16 == 0)
    qf, _ = cross_product_reduce(v, 4, "floor")
    assert np.array_equal(qf, v >> 4)          # floor variant == plain shift

    small = rng.integers(0, 256, (40, 50, 3), dtype=np.uint8)
    small[:20, :25] = (200, 30, 30)            # a dominant color
    m = FastColorClustering(8, 3, distance="rgb").fit(small)
    got = sorted((tuple(int(x) for x in c), int(n))
                 for c, n in zip(m.palette_, m.palette_counts_))
    ref = brute_force_reference(small, 8, 3)
    assert got == ref, (got, ref)
    assert m.palette_counts_.sum() == small.shape[0] * small.shape[1]
    assert len(np.unique(m.transform(small).reshape(-1, 3), axis=0)) <= 8
    print("self-checks passed (cross-product, left alignment, merge loop vs "
          "brute-force reference)")

    # ---------------------------------------------------------- demo
    imgs = {"astronaut": data.astronaut(), "coffee": data.coffee(),
            "chelsea": data.chelsea()}
    K, BITS = 16, 4
    rows = []
    fig, ax = plt.subplots(len(imgs), 4, figsize=(16, 4 * len(imgs)))
    for r, (name, rgb) in enumerate(imgs.items()):
        bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
        _, reduced = cross_product_reduce(bgr, BITS)

        t0 = time.perf_counter()
        model = FastColorClustering(K, BITS).fit(bgr)
        fcc = model.transform(bgr)
        t_fcc = time.perf_counter() - t0

        t0 = time.perf_counter()
        modl = FastColorClustering(K, BITS, distance="lab").fit(bgr)
        fcc_lab = modl.transform(bgr)
        t_lab = time.perf_counter() - t0

        Z = bgr.reshape(-1, 3).astype(np.float32)
        crit = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 20, 1.0)
        cv2.setRNGSeed(0)
        t0 = time.perf_counter()
        _, lbl, ctr = cv2.kmeans(Z, K, None, crit, 3, cv2.KMEANS_PP_CENTERS)
        t_km = time.perf_counter() - t0
        km = np.uint8(np.clip(ctr, 0, 255))[lbl.ravel()].reshape(bgr.shape)

        rows.append((name, bgr.shape, model.n_initial_colors_,
                     t_fcc, _psnr(bgr, fcc), t_lab, _psnr(bgr, fcc_lab),
                     t_km, _psnr(bgr, km)))
        ncol = lambda im: len(np.unique(im.reshape(-1, 3), axis=0))
        for c, (im, title) in enumerate([
                (bgr, f"{name} original, {ncol(bgr)} colors"),
                (reduced, f"{BITS}-bit cross-product, "
                          f"{model.n_initial_colors_} colors"),
                (fcc, f"US11763422  {ncol(fcc)} colors  {t_fcc*1e3:.0f} ms  "
                      f"{_psnr(bgr, fcc):.1f} dB"),
                (km, f"cv2.kmeans  {ncol(km)} colors  {t_km*1e3:.0f} ms  "
                     f"{_psnr(bgr, km):.1f} dB")]):
            ax[r, c].imshow(cv2.cvtColor(im, cv2.COLOR_BGR2RGB))
            ax[r, c].set_title(title, fontsize=10)
            ax[r, c].axis("off")
    plt.tight_layout()
    plt.savefig("comparison.png", dpi=90)

    print(f"\nK={K}, {BITS} bits/channel")
    print(f"{'image':10s} {'size':>9s} {'init':>5s} | {'FCC rgb':>15s} | "
          f"{'FCC lab':>15s} | {'cv2.kmeans':>15s}")
    for n, s, ic, tf, pf, tl, pl, tk, pk in rows:
        print(f"{n:10s} {s[1]:4d}x{s[0]:<4d} {ic:5d} | {tf*1e3:6.1f}ms "
              f"{pf:5.2f}dB | {tl*1e3:6.1f}ms {pl:5.2f}dB | "
              f"{tk*1e3:6.1f}ms {pk:5.2f}dB")

    # transform of an unseen image reuses the LUT: pure gather
    other = cv2.cvtColor(data.chelsea(), cv2.COLOR_RGB2BGR)
    t0 = time.perf_counter()
    for _ in range(20):
        model.transform(other)
    print(f"\ntransform() with fitted LUT on a new image: "
          f"{(time.perf_counter()-t0)/20*1e3:.2f} ms")

if __name__ == "__main__":
    main()
```

- 
**fast_color_clustering.py** :

``` bash
#!/usr/bin/env python3
"""
Fast color clustering for preprocessing an image
================================================
Python / OpenCV reference implementation of US 11,763,422 B2
(M. Fiammante, J.-A. Broyelle - IBM, granted 2023-09-19).

Pipeline (claim 1 / FIGS. 2A-2B):

  1. Receive a source image and a target number of colors K.
  2. Cross-product reduction: for every channel value v (8 bits) and a number
     of bits per channel n, compute  q = v * 2^n / 2^8, rounded to an integer.
  3. Left alignment: v' = q << (8 - n). The result is the initial target image,
     still in the 0..255 range, with at most 2^(3n) distinct colors.
  4. Unique color index "rrrgggbbb": idx = (q0 << 2n) | (q1 << n) | q2,
     so a single np.bincount gives the color frequencies.
  5. Repeat until the color count equals K:
        a. find the least frequent color,
        b. compute its distances to every other remaining color,
        c. take the least distance -> closest color,
        d. merged color = pixel-count-weighted average of the two,
        e. replace both by the merged color (count = sum of counts),
           the new tree node branches to the two merged nodes.
  6. Map every pixel through the merge tree to its final color.

Because the clustering runs on the (small) reduced palette and never on the
pixels, the cost is independent of image size once the histogram is built.
The fitted model is a full lookup table over all 2^(3n) indices, so applying
it to new images (e.g. a whole training set for a neural network) is just
one reduction plus one gather.

Channel order is whatever the array holds (BGR for cv2.imread); the method
is symmetric in the channels.
"""
from __future__ import annotations

import argparse
import time
from dataclasses import dataclass, field

import cv2
import numpy as np

__all__ = [
    "cross_product_reduce",
    "color_index",
    "FastColorClustering",
    "fast_color_clustering",
]

# --------------------------------------------------------------------------
# Steps 2-4: cross-product reduction, left alignment, rrrgggbbb index
# --------------------------------------------------------------------------
def cross_product_reduce(img: np.ndarray, bits: int, rounding: str = "round"):
    """Reduce an 8-bit image to `bits` significant bits per channel.

    Returns (levels, aligned):
      levels  : uint8 array, values in [0, 2^bits - 1]   (q)
      aligned : uint8 array, levels left-aligned to 8 bits (q << (8-bits))

    rounding = "round"  -> q = round(v * 2^n / 256), clipped to 2^n - 1
               "floor"  -> q = (v * 2^n) >> 8   (pure integer, == v >> (8-n))
    """
    if not 1 <= bits <= 8:
        raise ValueError("bits must be in 1..8")
    if img.dtype != np.uint8:
        raise TypeError("expected an 8-bit image")
    scale = 1 << bits
    if rounding == "round":
        q = np.rint(img.astype(np.float32) * (scale / 256.0))
        q = np.minimum(q, scale - 1).astype(np.uint8)
    elif rounding == "floor":
        q = ((img.astype(np.uint16) * scale) >> 8).astype(np.uint8)
    else:
        raise ValueError("rounding must be 'round' or 'floor'")
    aligned = (q << (8 - bits)).astype(np.uint8)
    return q, aligned

def color_index(levels: np.ndarray, bits: int) -> np.ndarray:
    """Unique index rrrgggbbb from per-channel levels (H, W, 3) -> (H, W)."""
    l = levels.astype(np.int32)
    return (l[..., 0] << (2 * bits)) | (l[..., 1] << bits) | l[..., 2]

def _index_to_aligned_color(idx: np.ndarray, bits: int) -> np.ndarray:
    """Inverse of color_index, returned left-aligned (float64, 0..255)."""
    m = (1 << bits) - 1
    c = np.stack([(idx >> (2 * bits)) & m, (idx >> bits) & m, idx & m], axis=-1)
    return (c << (8 - bits)).astype(np.float64)

# --------------------------------------------------------------------------
# Step 5: least-frequent-color merging with a merge tree
# --------------------------------------------------------------------------
@dataclass
class MergeTree:
    """Binary merge tree (FIG. 3). Leaves 0..L-1 are the initial colors."""
    colors: np.ndarray   # (N, 3) float  color of every node
    counts: np.ndarray   # (N,)  int64  pixel count of every node
    parent: np.ndarray   # (N,)  int64  parent node, -1 for a root
    merges: list = field(default_factory=list)  # (least_freq, closest, new)
    n_leaves: int = 0

    def roots(self) -> np.ndarray:
        return np.flatnonzero((self.parent < 0) & (self.counts > 0))

    def leaf_roots(self) -> np.ndarray:
        """Root node reached from each leaf (vectorised pointer jumping)."""
        p = self.parent.copy()
        node = np.arange(len(p))
        r = np.where(p < 0, node, p)
        while True:
            nxt = np.where(p[r] < 0, r, p[r])
            if np.array_equal(nxt, r):
                break
            r = nxt
        return r[: self.n_leaves]

def _merge_colors(colors0, counts0, k, distance="rgb", verbose=False):
    L = len(colors0)
    N = max(2 * L - 1, 1)
    colors = np.zeros((N, 3), np.float64)
    counts = np.zeros(N, np.int64)
    parent = np.full(N, -1, np.int64)
    colors[:L] = colors0
    counts[:L] = counts0
    tree = MergeTree(colors, counts, parent, [], L)

    # feature space used for the distance (the merge itself stays in RGB)
    def feat(c):
        if distance == "rgb":
            return c
        lab = cv2.cvtColor(
            np.clip(c, 0, 255).astype(np.float32).reshape(-1, 1, 3) / 255.0,
            cv2.COLOR_RGB2Lab)
        return lab.reshape(-1, 3).astype(np.float64)

    feats = np.zeros((N, 3), np.float64)
    feats[:L] = feat(colors0)

    alive = np.zeros(N, bool)
    alive[:L] = True
    cnt_key = np.where(alive, counts.astype(np.float64), np.inf)
    nxt = L
    n_alive = L
    while n_alive > k:
        # a. least frequent color
        i = int(np.argmin(cnt_key))
        # b./c. distances to all other remaining colors, least distance
        d = np.einsum("ij,ij->i", feats - feats[i], feats - feats[i])
        d[~alive] = np.inf
        d[i] = np.inf
        j = int(np.argmin(d))
        # d. weighted average by pixel counts
        ni, nj = counts[i], counts[j]
        new = nxt
        nxt += 1
        colors[new] = (colors[i] * ni + colors[j] * nj) / (ni + nj)
        counts[new] = ni + nj
        feats[new] = feat(colors[new:new + 1])[0] if distance != "rgb" else colors[new]
        # e. replace both colors by the merged one (new tree node)
        parent[i] = parent[j] = new
        alive[i] = alive[j] = False
        alive[new] = True
        cnt_key[i] = cnt_key[j] = np.inf
        cnt_key[new] = counts[new]
        tree.merges.append((i, j, new))
        n_alive -= 1
        if verbose and n_alive % 500 == 0:
            print(f"  {n_alive} colors left")
    return tree

# --------------------------------------------------------------------------
# Public API
# --------------------------------------------------------------------------
class FastColorClustering:
    """Fit on one image, then transform any image of the same color space.

    Parameters
    ----------
    n_colors : target number of colors K
    bits     : bits per channel kept by the cross-product reduction (1..8)
    rounding : "round" (patent abstract) or "floor"
    distance : "rgb" (Euclidean on channel values) or "lab" (CIE76 dE);
               for "lab", input arrays are assumed RGB order (use
               channel_order="bgr" for cv2.imread images).
    """

    def __init__(self, n_colors=16, bits=4, rounding="round", distance="rgb",
                 channel_order="bgr"):
        self.n_colors = int(n_colors)
        self.bits = int(bits)
        self.rounding = rounding
        self.distance = distance
        self.channel_order = channel_order.lower()

    # ---- fitting -------------------------------------------------------
    def fit(self, img: np.ndarray, verbose=False):
        img = self._check(img)
        t0 = time.perf_counter()
        levels, self.reduced_ = cross_product_reduce(img, self.bits, self.rounding)
        idx = color_index(levels, self.bits)
        hist = np.bincount(idx.ravel(), minlength=1 << (3 * self.bits))
        present = np.flatnonzero(hist)
        self.n_initial_colors_ = len(present)

        colors0 = _index_to_aligned_color(present, self.bits)
        if self.distance == "lab" and self.channel_order == "bgr":
            # distance computed in RGB order, merge stays in native order
            perm = [2, 1, 0]
            tree = _merge_colors(colors0[:, perm], hist[present],
                                 self.n_colors, "lab", verbose)
            tree.colors = tree.colors[:, perm]
        else:
            tree = _merge_colors(colors0, hist[present], self.n_colors,
                                 self.distance, verbose)
        self.tree_ = tree

        # final palette = roots of the merge tree, sorted by frequency
        roots = tree.roots()
        order = np.argsort(-tree.counts[roots])
        roots = roots[order]
        self.palette_ = np.clip(np.rint(tree.colors[roots]), 0, 255).astype(np.uint8)
        self.palette_counts_ = tree.counts[roots]
        node_to_label = np.full(len(tree.parent), -1, np.int64)
        node_to_label[roots] = np.arange(len(roots))

        # full LUT over every possible rrrgggbbb index
        lut = np.empty(1 << (3 * self.bits), np.int32)
        lut[present] = node_to_label[tree.leaf_roots()]
        absent = np.setdiff1d(np.arange(len(lut)), present, assume_unique=True)
        if absent.size:  # colors never seen during fit -> nearest palette color
            c = _index_to_aligned_color(absent, self.bits)
            p = self.palette_.astype(np.float64)
            d = (c ** 2).sum(1)[:, None] - 2 * c @ p.T + (p ** 2).sum(1)[None, :]
            lut[absent] = np.argmin(d, axis=1)
        self.lut_ = lut
        self.fit_time_ = time.perf_counter() - t0
        return self

    # ---- applying ------------------------------------------------------
    def predict(self, img: np.ndarray) -> np.ndarray:
        """Label map (H, W) of palette indices - handy as NN input."""
        img = self._check(img)
        levels, _ = cross_product_reduce(img, self.bits, self.rounding)
        return self.lut_[color_index(levels, self.bits)]

    def transform(self, img: np.ndarray) -> np.ndarray:
        """Target image with at most n_colors colors (same shape/dtype)."""
        return self.palette_[self.predict(img)]

    def fit_transform(self, img, verbose=False):
        return self.fit(img, verbose).transform(img)

    @staticmethod
    def _check(img):
        if img.ndim != 3 or img.shape[2] != 3:
            raise ValueError("expected an (H, W, 3) color image")
        return np.ascontiguousarray(img, dtype=np.uint8)

def fast_color_clustering(img, n_colors=16, bits=4, **kw):
    """One-shot helper: returns (target_image, palette, label_map)."""
    m = FastColorClustering(n_colors, bits, **kw).fit(img)
    labels = m.predict(img)
    return m.palette_[labels], m.palette_, labels

# --------------------------------------------------------------------------
# CLI
# --------------------------------------------------------------------------
def _psnr(a, b):
    mse = np.mean((a.astype(np.float64) - b.astype(np.float64)) ** 2)
    return float("inf") if mse == 0 else 10 * np.log10(255.0 ** 2 / mse)

def main():
    ap = argparse.ArgumentParser(description="US11763422 fast color clustering")
    ap.add_argument("input")
    ap.add_argument("-o", "--output", default="clustered.png")
    ap.add_argument("-k", "--colors", type=int, default=16)
    ap.add_argument("-b", "--bits", type=int, default=4)
    ap.add_argument("--rounding", choices=["round", "floor"], default="round")
    ap.add_argument("--distance", choices=["rgb", "lab"], default="rgb")
    ap.add_argument("--labels", help="also save the label map (uint8/uint16 PNG)")
    ap.add_argument("--compare-kmeans", action="store_true")
    a = ap.parse_args()

    img = cv2.imread(a.input, cv2.IMREAD_COLOR)
    if img is None:
        raise SystemExit(f"cannot read {a.input}")
    m = FastColorClustering(a.colors, a.bits, a.rounding, a.distance, "bgr")
    t0 = time.perf_counter()
    out = m.fit_transform(img)
    dt = time.perf_counter() - t0
    cv2.imwrite(a.output, out)
    print(f"{img.shape[1]}x{img.shape[0]}  initial colors after {a.bits}-bit "
          f"reduction: {m.n_initial_colors_}  ->  {len(m.palette_)} colors")
    print(f"fast clustering: {dt * 1000:.1f} ms   PSNR {_psnr(img, out):.2f} dB")
    if a.labels:
        lab = m.predict(img)
        cv2.imwrite(a.labels, lab.astype(np.uint8 if a.colors <= 256 else np.uint16))
    if a.compare_kmeans:
        Z = img.reshape(-1, 3).astype(np.float32)
        crit = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 20, 1.0)
        t0 = time.perf_counter()
        _, lbl, ctr = cv2.kmeans(Z, a.colors, None, crit, 3, cv2.KMEANS_PP_CENTERS)
        dk = time.perf_counter() - t0
        km = np.uint8(np.clip(ctr, 0, 255))[lbl.ravel()].reshape(img.shape)
        print(f"cv2.kmeans     : {dk * 1000:.1f} ms   PSNR {_psnr(img, km):.2f} dB")

if __name__ == "__main__":
    main()
```

## 
  IBM Bob Code Generated Related to the Patent

Giving 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;

```
You 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.

**Primary Objective:**
Create 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.

**Requirements:**

1. **Patent Analysis & Implementation**
   - Thoroughly analyze the patent specification at https://patents.google.com/patent/US11763422B2/
   - Extract and document all key algorithmic components, mathematical formulations, and technical innovations
   - Implement each component as a modular, well-structured Python class or function
   - Ensure OpenCV integration for image processing operations where applicable

2. **Code Structure & Organization**
   - Create a main module that encapsulates the patent implementation
   - Implement supporting classes/functions for each technical component described in the patent
   - Include comprehensive docstrings with mathematical notation, parameter descriptions, and usage examples
   - Follow PEP 8 style guidelines and best practices

3. **Testing & Validation**
   - Create unit tests validating each component's functionality
   - Implement benchmark tests comparing performance against relevant OpenCV/SciPy baselines
   - Include visual output demonstrations showing the patent algorithm in action
   - Document performance metrics and computational characteristics

4. **Documentation**
   - Generate a technical reference document explaining the patent's innovations
   - Include algorithm flow diagrams and mathematical formulations
   - Provide practical usage examples and tutorials
   - Document any deviations or adaptations from the patent specification with justifications

5. **Integration with Existing Codebase**
   - Leverage existing code in `bob_code/`, `_sources/` folders where applicable
   - Maintain consistency with established architectural patterns and naming conventions
   - Integrate with existing benchmark and comparison frameworks

6. **Deliverables**
   - Complete Python implementation module
   - Comprehensive test suite with benchmark comparisons
   - Technical documentation and reference guide
   - Example scripts demonstrating practical applications
   - Performance analysis and optimization notes

Deliver production-ready code with clear structure, extensive documentation, and validated performance characteristics.
```

I 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;

```
Create 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. 

Analyze 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. 

Ensure 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.
```

After I validated the prompt I got the following source codes in Python;

- 
**patent_color_clustering.py**

``` bash
#!/usr/bin/env python3
"""
IBM Patent US 11,763,422 B2 - Novel Modular Implementation
===========================================================
"Fast color clustering for preprocessing an image"
Inventors: Marc Fiammante, Jean-Armand Broyelle (IBM)
Patent Grant Date: September 19, 2023

Architectural Highlights & Novel Design Patterns in bob_code:
-------------------------------------------------------------
1. Discrete Pipeline Architecture:
   - Encapsulates patent components (FIG. 1) as distinct, pluggable objects:
     * `CrossProductQuantizer` (Module 106)
     * `LeftAlignmentOperator` (Module 108)
     * `ColorIndexEncoder` (Module 110)
     * `HierarchicalClusterForest` / `MinHeapColorMerger` (Module 112)
     * `PaletteCentroidRefiner` (Post-processor, Claims 6 & 13)

2. Priority-Queue / Min-Heap Color Merging Engine:
   - Uses an indexed min-heap / priority queue (`heapq`) with dual-level tracking
     to locate the least-frequent cluster in O(log L) time.
   - Dynamic distance tracking with nearest-neighbor adjacency cache and generation counters
     to eliminate redundant O(N^2) distance recomputations across merge iterations.

3. Disjoint-Set Union (Union-Find) with Path Compression & Tree Linking:
   - Represents the hierarchical dendrogram merge tree (FIG. 3 / Claims 3, 10, 17)
     using explicit Node objects and Disjoint-Set Union (DSU) data structures,
     providing exact ancestor lineage tracking without flat index pointers.

4. N-Channel and Arbitrary Color-Space Support:
   - Handles not only 3-channel RGB/BGR, but multi-spectral data (satellite, NIR, UV)
     as explicitly claimed in the patent specification (Col. 3, lines 1-5).
"""

from __future__ import annotations

import heapq
import time
from dataclasses import dataclass, field
from enum import Enum
from typing import Dict, List, Optional, Sequence, Tuple, Union

import cv2
import numpy as np

__all__ = [
    "DistanceMetric",
    "RoundingMode",
    "ColorTreeNode",
    "CrossProductQuantizer",
    "LeftAlignmentOperator",
    "ColorIndexEncoder",
    "HierarchicalClusterForest",
    "PaletteCentroidRefiner",
    "PatentColorClusterer",
    "process_image_patent_pipeline",
]

# ==============================================================================
# Enumerations and Configuration
# ==============================================================================

class DistanceMetric(str, Enum):
    """Distance metrics supported for color proximity evaluation (Step 220)."""
    EUCLIDEAN_RGB = "rgb"
    CIELAB_DELTA_E = "lab"
    WEIGHTED_PERCEPTUAL = "weighted_rgb"

class RoundingMode(str, Enum):
    """Integer rounding strategy for cross-product calculation (Step 208)."""
    ROUND_HALF_UP = "round"
    BIT_TRUNCATION = "floor"

# ==============================================================================
# Module 106: Cross-Product Quantizer (Steps 204-208 / Claims 1, 7, 14)
# ==============================================================================

class CrossProductQuantizer:
    """Computes cross-product reduction on source image pixel values.

    Implements patent formula:
        q = round( (2^n - 1) * color / 255 )   or   (color * 2^n) >> 8

    Patent References:
        - Step 204: Determine initial number of colors K + margin (e.g. K/2)
        - Step 205: Select bits per channel such that 2^(bits*channels) > (K + margin)
        - Steps 206, 208: Determine cross-product and round to integer values
        - Claims 1, 7, 14: Use precomputed LUTs for rapid execution
    """

    def __init__(self, bits: int, rounding: RoundingMode = RoundingMode.ROUND_HALF_UP):
        if not (1 <= bits <= 8):
            raise ValueError(f"Bits per channel must be between 1 and 8, got {bits}")
        self.bits = bits
        self.rounding = rounding
        self._lut = self._build_lookup_table(bits, rounding)

    @staticmethod
    def estimate_optimal_bits(k: int, margin: Optional[int] = None, channels: int = 3) -> int:
        """Evaluate bits per channel count: 2^(bits * channels) > (K + margin)."""
        if k < 1:
            raise ValueError("K must be a positive integer >= 1")
        if margin is None:
            margin = max(1, k // 2)

        threshold = k + margin
        for b in range(1, 9):
            if (1 << (b * channels)) > threshold:
                return b
        return 8

    @staticmethod
    def _build_lookup_table(bits: int, rounding: RoundingMode) -> np.ndarray:
        max_quantized = (1 << bits) - 1
        raw_vals = np.arange(256, dtype=np.float32)
        if rounding == RoundingMode.ROUND_HALF_UP:
            lut = np.round((raw_vals * max_quantized) / 255.0).astype(np.uint8)
        else:
            lut = (raw_vals.astype(np.uint16) * (1 << bits) >> 8).astype(np.uint8)
        return lut

    def quantize(self, img: np.ndarray) -> np.ndarray:
        """Apply cross-product reduction using the precomputed LUT."""
        if img.dtype != np.uint8:
            raise TypeError("Source image must have uint8 pixel values")
        return cv2.LUT(img, self._lut) if img.ndim in (2, 3) else self._lut[img]

# ==============================================================================
# Module 108: Left-Alignment Operator (Step 210 / Claims 1, 2)
# ==============================================================================

class LeftAlignmentOperator:
    """Left-aligns quantized values to a standard 8-bit scale for distance metric.

    Patent References:
        - Step 210: Left align rounded cross-product on 8-bit value
        - Claim 1: Left aligned rounded cross-product specifies initial target image
        - Specification Col. 4 lines 50-60: Left justification provides consistent
          color distance computation regardless of bit depth n.
    """

    def __init__(self, bits: int):
        self.bits = bits
        self.shift = 8 - bits

    def align(self, quantized_levels: np.ndarray) -> np.ndarray:
        """Shift quantized levels left by (8 - bits) bits."""
        return (quantized_levels.astype(np.uint8) << self.shift)

    def unalign(self, aligned_values: np.ndarray) -> np.ndarray:
        """Shift aligned 8-bit values right by (8 - bits) bits."""
        return (aligned_values.astype(np.uint8) >> self.shift)

# ==============================================================================
# Module 110: Color Index Encoder (Step 212 / Claims 5, 12, 19)
# ==============================================================================

class ColorIndexEncoder:
    """Encodes multi-channel pixel values into a packed integer key and extracts histograms.

    Implements patent flat map / regular map encoding:
        idx = (channel[0] << 2n) | (channel[1] << n) | channel[2]

    Patent References:
        - Step 212: Determine count of remaining unique colors
        - Claims 5, 12, 19: Unique key concatenation of channel significant bits
    """

    def __init__(self, bits: int, channels: int = 3):
        self.bits = bits
        self.channels = channels
        self.mask = (1 << bits) - 1
        self.max_possible_keys = 1 << (bits * channels)

    def encode(self, levels: np.ndarray) -> np.ndarray:
        """Pack multi-channel levels into a 1D integer key per pixel."""
        levels_int = levels.astype(np.int64)
        packed_key = np.zeros(levels.shape[:-1], dtype=np.int64)
        for ch_idx in range(self.channels):
            shift_amount = (self.channels - 1 - ch_idx) * self.bits
            packed_key |= (levels_int[..., ch_idx] << shift_amount)
        return packed_key

    def decode(self, keys: np.ndarray, left_align: bool = True) -> np.ndarray:
        """Unpack integer keys back into channel color coordinates."""
        channels_unpacked = []
        for ch_idx in range(self.channels):
            shift_amount = (self.channels - 1 - ch_idx) * self.bits
            ch_val = (keys >> shift_amount) & self.mask
            channels_unpacked.append(ch_val)
        color_coords = np.stack(channels_unpacked, axis=-1).astype(np.float64)
        if left_align:
            color_coords *= (1 << (8 - self.bits))
        return color_coords

    def build_histogram(self, packed_keys: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
        """Compute flat map histogram of unique color frequencies."""
        hist = np.bincount(packed_keys.ravel(), minlength=self.max_possible_keys)
        unique_keys = np.flatnonzero(hist)
        frequencies = hist[unique_keys]
        return unique_keys, frequencies

# ==============================================================================
# Module 112: Hierarchical Tree & Min-Heap Merger (Steps 218-228 / Claims 3, 4, 10, 11)
# ==============================================================================

@dataclass
class ColorTreeNode:
    """Explicit node in the Hierarchical Binary Merge Tree (FIG. 3 / Claim 3).

    Maintains full structural lineage:
        - node_id: Unique integer identifier
        - color: Multi-channel centroid (float64)
        - count: Pixel weight / frequency
        - left_child, right_child: Pointers to merged sub-nodes
        - parent: Pointer to parent node (-1 if root)
    """
    node_id: int
    color: np.ndarray
    count: int
    left_child: Optional[int] = None
    right_child: Optional[int] = None
    parent: int = -1
    is_leaf: bool = True

    @property
    def is_active(self) -> bool:
        return self.parent == -1

class HierarchicalClusterForest:
    """Hierarchical agglomerative clustering engine using an indexed min-heap.

    Patent References:
        - Steps 218, 220, 222: Identify least-frequent color and find closest neighbor
        - Step 224: Weighted-average color merging based on pixel frequencies
        - Step 226: Update tree structure (FIG. 3, Claims 3, 10, 17)
        - Step 228: Loop until active cluster count equals K
    """

    def __init__(
        self,
        initial_colors: np.ndarray,
        initial_counts: np.ndarray,
        distance_metric: DistanceMetric = DistanceMetric.EUCLIDEAN_RGB
    ):
        self.metric = distance_metric
        self.num_leaves = len(initial_colors)
        self.nodes: Dict[int, ColorTreeNode] = {}
        self.active_nodes: set[int] = set()

        # Feature representations for distance evaluation
        self._features: Dict[int, np.ndarray] = {}

        # Initialize leaf nodes (Level 0)
        for i in range(self.num_leaves):
            color = initial_colors[i].astype(np.float64)
            cnt = int(initial_counts[i])
            node = ColorTreeNode(node_id=i, color=color, count=cnt, is_leaf=True)
            self.nodes[i] = node
            self.active_nodes.add(i)
            self._features[i] = self._compute_feature(color)

        self._next_node_id = self.num_leaves

    def _compute_feature(self, color_vec: np.ndarray) -> np.ndarray:
        if self.metric == DistanceMetric.EUCLIDEAN_RGB:
            return color_vec
        elif self.metric == DistanceMetric.CIELAB_DELTA_E:
            # Color must be 3-channel for CIELAB
            if len(color_vec) == 3:
                rgb_norm = np.clip(color_vec, 0, 255).astype(np.float32).reshape(1, 1, 3) / 255.0
                lab = cv2.cvtColor(rgb_norm, cv2.COLOR_RGB2Lab).reshape(3)
                return lab.astype(np.float64)
            return color_vec
        elif self.metric == DistanceMetric.WEIGHTED_PERCEPTUAL:
            # Perceptual RGB weighting: (0.3 R + 0.59 G + 0.11 B)
            if len(color_vec) == 3:
                weights = np.array([0.30, 0.59, 0.11], dtype=np.float64)
                return color_vec * np.sqrt(weights)
            return color_vec
        return color_vec

    def reduce_to_k(self, target_k: int, verbose: bool = False) -> None:
        """Executes iterative color reduction until active cluster count equals target_k."""
        if len(self.active_nodes) <= target_k:
            return

        # Vectorized feature matrix and active index tracking for maximum speed
        # Indexed Priority Queue of (pixel_count, node_id)
        min_heap: List[Tuple[int, int]] = [
            (self.nodes[nid].count, nid) for nid in self.active_nodes
        ]
        heapq.heapify(min_heap)

        # Pre-allocate contiguous feature array for fast vector distance computation
        max_possible_nodes = 2 * self.num_leaves
        dim = next(iter(self._features.values())).shape[0]
        feat_matrix = np.zeros((max_possible_nodes, dim), dtype=np.float64)
        for nid, f in self._features.items():
            feat_matrix[nid] = f

        while len(self.active_nodes) > target_k:
            # Step 218: Pop least-frequent active color
            while min_heap:
                cnt, least_id = heapq.heappop(min_heap)
                if least_id in self.active_nodes and self.nodes[least_id].count == cnt:
                    break
            else:
                break

            # Vectorized Step 220 & 222: Find closest active neighbor
            active_list = np.array([nid for nid in self.active_nodes if nid != least_id], dtype=np.int64)
            if active_list.size == 0:
                break

            active_feats = feat_matrix[active_list]
            least_feat = feat_matrix[least_id]
            diff = active_feats - least_feat
            dists_sq = np.einsum("ij,ij->i", diff, diff)
            best_idx = np.argmin(dists_sq)
            best_neighbor_id = int(active_list[best_idx])

            # Step 224: Weighted centroid computation (Claims 4, 11, 18)
            node_u = self.nodes[least_id]
            node_v = self.nodes[best_neighbor_id]
            total_weight = node_u.count + node_v.count
            merged_color = (node_u.color * node_u.count + node_v.color * node_v.count) / total_weight

            # Step 226: Create new parent node and update tree hierarchy (FIG. 3)
            new_id = self._next_node_id
            self._next_node_id += 1

            parent_node = ColorTreeNode(
                node_id=new_id,
                color=merged_color,
                count=total_weight,
                left_child=least_id,
                right_child=best_neighbor_id,
                parent=-1,
                is_leaf=False
            )

            node_u.parent = new_id
            node_v.parent = new_id

            self.nodes[new_id] = parent_node
            new_feat = self._compute_feature(merged_color)
            self._features[new_id] = new_feat
            feat_matrix[new_id] = new_feat

            # Update active cluster set
            self.active_nodes.remove(least_id)
            self.active_nodes.remove(best_neighbor_id)
            self.active_nodes.add(new_id)

            heapq.heappush(min_heap, (total_weight, new_id))

            if verbose and len(self.active_nodes) % 100 == 0:
                print(f"[HierarchicalClusterForest] {len(self.active_nodes)} clusters remaining...")

    def get_cluster_roots(self) -> List[int]:
        """Return list of active root cluster IDs sorted by pixel frequency descending."""
        roots = list(self.active_nodes)
        roots.sort(key=lambda nid: self.nodes[nid].count, reverse=True)
        return roots

    def get_leaf_cluster_assignments(self) -> np.ndarray:
        """Trace leaf nodes up through the merge tree to their final active root cluster."""
        assignments = np.empty(self.num_leaves, dtype=np.int64)
        for leaf_id in range(self.num_leaves):
            curr = leaf_id
            while self.nodes[curr].parent != -1:
                curr = self.nodes[curr].parent
            assignments[leaf_id] = curr
        return assignments

# ==============================================================================
# Optional Post-Processor: Centroid Refinement (Claims 6 & 13 / Step 228)
# ==============================================================================

class PaletteCentroidRefiner:
    """Refines clustered palette colors using exact source image pixel averages.

    Patent References:
        - Claims 6, 13: Mapping K colors to respective source pixel values and
          computing true weighted averages from original unquantized pixels.
    """

    @staticmethod
    def refine(
        source_img: np.ndarray,
        label_map: np.ndarray,
        palette: np.ndarray
    ) -> np.ndarray:
        """Compute refined palette centroids using true source image pixel means."""
        refined_palette = palette.copy().astype(np.float64)
        flat_labels = label_map.ravel()
        flat_pixels = source_img.reshape(-1, source_img.shape[-1]).astype(np.float64)

        for k in range(len(palette)):
            mask = (flat_labels == k)
            if np.any(mask):
                refined_palette[k] = flat_pixels[mask].mean(axis=0)

        return np.clip(np.rint(refined_palette), 0, 255).astype(np.uint8)

# ==============================================================================
# Unified Pipeline Interface: PatentColorClusterer
# ==============================================================================

class PatentColorClusterer:
    """Full-featured, modular implementation of IBM Patent US 11,763,422 B2.

    Attributes
    ----------
    k_colors : int
        Target number of colors (K).
    bits : Optional[int]
        Bits per channel. If None, auto-calculated via 2^(bits*ch) > (K + margin).
    margin : Optional[int]
        Margin added to K during bit estimation (default K//2).
    metric : DistanceMetric
        Distance metric for color proximity (RGB, CIELAB, Weighted).
    rounding : RoundingMode
        Rounding method for cross-product reduction (Round or Floor).
    auto_increment_bits : bool
        If True, auto-increments bits when unique initial colors <= K (Claim 2).
    refine_palette : bool
        If True, refines palette colors against source image pixels (Claims 6, 13).
    """

    def __init__(
        self,
        k_colors: int = 16,
        bits: Optional[int] = None,
        margin: Optional[int] = None,
        metric: Union[str, DistanceMetric] = DistanceMetric.EUCLIDEAN_RGB,
        rounding: Union[str, RoundingMode] = RoundingMode.ROUND_HALF_UP,
        auto_increment_bits: bool = True,
        refine_palette: bool = False
    ):
        self.k_colors = int(k_colors)
        self.bits = bits
        self.margin = margin
        self.metric = DistanceMetric(metric)
        self.rounding = RoundingMode(rounding)
        self.auto_increment_bits = auto_increment_bits
        self.refine_palette = refine_palette

        # Fitted state
        self.active_bits_: int = 0
        self.palette_: np.ndarray = np.array([])
        self.palette_weights_: np.ndarray = np.array([])
        self.lut_: np.ndarray = np.array([])
        self.fit_time_: float = 0.0
        self.forest_: Optional[HierarchicalClusterForest] = None
        self._encoder: Optional[ColorIndexEncoder] = None

    def fit(self, img: np.ndarray, verbose: bool = False) -> "PatentColorClusterer":
        """Fits color clustering model on source image according to Patent Steps 202-228."""
        t_start = time.perf_counter()
        img = self._validate_input(img)
        num_channels = img.shape[-1] if img.ndim == 3 else 1

        # Step 204 & 205: Determine bits per channel
        if self.bits is not None:
            active_bits = int(self.bits)
        else:
            active_bits = CrossProductQuantizer.estimate_optimal_bits(
                self.k_colors, self.margin, channels=num_channels
            )

        # Steps 206 - 216: Iterative reduction with auto-increment check (Claim 2)
        while True:
            quantizer = CrossProductQuantizer(active_bits, self.rounding)
            encoder = ColorIndexEncoder(active_bits, channels=num_channels)

            quantized = quantizer.quantize(img)
            packed_keys = encoder.encode(quantized)
            unique_keys, frequencies = encoder.build_histogram(packed_keys)

            if len(unique_keys) > self.k_colors or not self.auto_increment_bits or active_bits >= 8:
                break
            active_bits += 1
            if verbose:
                print(f"[PatentColorClusterer] Incrementing significant bits to {active_bits} (Claim 2)")

        self.active_bits_ = active_bits
        self._encoder = encoder

        # Decode initial unique colors to left-aligned coordinates (Step 210)
        initial_colors = encoder.decode(unique_keys, left_align=True)

        # Steps 218 - 228: Hierarchical merge tree reduction (FIG. 3 / Claims 3, 4, 10, 11)
        forest = HierarchicalClusterForest(
            initial_colors=initial_colors,
            initial_counts=frequencies,
            distance_metric=self.metric
        )
        forest.reduce_to_k(self.k_colors, verbose=verbose)
        self.forest_ = forest

        # Extract roots and sort by frequency descending
        root_ids = forest.get_cluster_roots()
        palette_colors = np.array([forest.nodes[rid].color for rid in root_ids], dtype=np.float64)
        palette_counts = np.array([forest.nodes[rid].count for rid in root_ids], dtype=np.int64)

        self.palette_ = np.clip(np.rint(palette_colors), 0, 255).astype(np.uint8)
        self.palette_weights_ = palette_counts

        # Build mapping from node_id -> label [0..K-1]
        node_to_label = {rid: idx for idx, rid in enumerate(root_ids)}
        leaf_root_assignments = forest.get_leaf_cluster_assignments()

        # Build complete Lookup Table (LUT) for all 2^(n*channels) color keys
        lut = np.empty(encoder.max_possible_keys, dtype=np.int32)
        lut[unique_keys] = [node_to_label[r] for r in leaf_root_assignments]

        # Handle unobserved colors by mapping to closest palette centroid
        absent_keys = np.setdiff1d(np.arange(encoder.max_possible_keys), unique_keys, assume_unique=True)
        if len(absent_keys) > 0:
            p_float = self.palette_.astype(np.float64)
            p_sq = (p_float ** 2).sum(axis=1)

            # Chunked evaluation to maintain low memory profile
            chunk_size = 65536
            for start in range(0, len(absent_keys), chunk_size):
                chunk = absent_keys[start:start + chunk_size]
                c_coords = encoder.decode(chunk, left_align=True)
                c_sq = (c_coords ** 2).sum(axis=1, keepdims=True)
                dists = c_sq - 2.0 * np.dot(c_coords, p_float.T) + p_sq
                lut[chunk] = np.argmin(dists, axis=1)

        self.lut_ = lut

        # Optional Post-Processing refinement (Claims 6 & 13)
        if self.refine_palette:
            labels = self.predict(img)
            self.palette_ = PaletteCentroidRefiner.refine(img, labels, self.palette_)

        self.fit_time_ = time.perf_counter() - t_start
        return self

    def predict(self, img: np.ndarray) -> np.ndarray:
        """Map input image pixels to cluster labels [0..K-1] via LUT gather."""
        img = self._validate_input(img)
        quantizer = CrossProductQuantizer(self.active_bits_, self.rounding)
        quantized = quantizer.quantize(img)
        packed_keys = self._encoder.encode(quantized)
        return self.lut_[packed_keys]

    def transform(self, img: np.ndarray) -> np.ndarray:
        """Quantize image to K colors using fitted palette and LUT."""
        labels = self.predict(img)
        return self.palette_[labels]

    def fit_transform(self, img: np.ndarray, verbose: bool = False) -> np.ndarray:
        """Fit model and return quantized target image."""
        return self.fit(img, verbose=verbose).transform(img)

    @staticmethod
    def _validate_input(img: np.ndarray) -> np.ndarray:
        if not isinstance(img, np.ndarray):
            raise TypeError("Input image must be a numpy ndarray")
        if img.dtype != np.uint8:
            raise TypeError("Input image must have uint8 pixel depth")
        return np.ascontiguousarray(img)

# ==============================================================================
# Functional Pipeline Helper
# ==============================================================================

def process_image_patent_pipeline(
    img: np.ndarray,
    k_colors: int = 16,
    bits: Optional[int] = None,
    distance_metric: str = "rgb",
    refine: bool = False
) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
    """One-shot helper function returning (quantized_image, palette, label_map)."""
    model = PatentColorClusterer(
        k_colors=k_colors,
        bits=bits,
        metric=distance_metric,
        refine_palette=refine
    ).fit(img)
    labels = model.predict(img)
    quantized_img = model.palette_[labels]
    return quantized_img, model.palette_, labels
```

## 
  Benchmarking IBM Bob Code vs. Claude Code

The last step I did was to benchmark performances of the different code outputs I got. Hereafter the result;

- 
**test_and_benchmark.py**

``` bash
#!/usr/bin/env python3
"""
Verification and Comparative Benchmark for bob_code Implementation
===================================================================
Validates the novel discrete pipeline and min-heap architecture against
the reference implementation and OpenCV K-Means baseline.
"""

from __future__ import annotations

import time
import cv2
import numpy as np
from skimage import data

from bob_code.patent_color_clustering import (
    PatentColorClusterer,
    CrossProductQuantizer,
    LeftAlignmentOperator,
    ColorIndexEncoder,
    HierarchicalClusterForest,
    DistanceMetric,
    RoundingMode,
    process_image_patent_pipeline,
)

def compute_psnr(img_a: np.ndarray, img_b: np.ndarray) -> float:
    mse = np.mean((img_a.astype(np.float64) - img_b.astype(np.float64)) ** 2)
    return float("inf") if mse == 0 else 10.0 * np.log10((255.0 ** 2) / mse)

def run_unit_tests():
    print("=" * 75)
    print("RUNNING ARCHITECTURAL & UNIT TESTS FOR bob_code IMPLEMENTATION")
    print("=" * 75)

    # 1. Test CrossProductQuantizer
    quantizer = CrossProductQuantizer(bits=4, rounding=RoundingMode.ROUND_HALF_UP)
    ramp = np.arange(256, dtype=np.uint8)
    q_vals = quantizer.quantize(ramp)
    assert q_vals.min() == 0 and q_vals.max() == 15
    print("[PASS] CrossProductQuantizer: 4-bit LUT reduction in [0..15]")

    # 2. Test LeftAlignmentOperator
    aligner = LeftAlignmentOperator(bits=4)
    aligned = aligner.align(q_vals)
    assert aligned.max() == 240 and np.all(aligned % 16 == 0)
    print("[PASS] LeftAlignmentOperator: 8-bit left justification")

    # 3. Test ColorIndexEncoder
    encoder = ColorIndexEncoder(bits=4, channels=3)
    sample_levels = np.array([[[1, 2, 3]]], dtype=np.uint8)
    packed = encoder.encode(sample_levels)
    expected_packed = (1 << 8) | (2 << 4) | 3  # 256 + 32 + 3 = 291
    assert packed[0, 0] == expected_packed
    decoded = encoder.decode(packed, left_align=False)
    assert np.all(decoded[0, 0] == [1, 2, 3])
    print("[PASS] ColorIndexEncoder: multi-channel bit packing & unpacking")

    # 4. Test HierarchicalClusterForest Min-Heap Merging
    colors = np.array([[255, 0, 0], [250, 5, 0], [0, 255, 0], [0, 0, 255]], dtype=np.float64)
    counts = np.array([10, 5, 100, 200], dtype=np.int64)
    forest = HierarchicalClusterForest(colors, counts, DistanceMetric.EUCLIDEAN_RGB)
    forest.reduce_to_k(target_k=3)
    roots = forest.get_cluster_roots()
    assert len(roots) == 3
    print("[PASS] HierarchicalClusterForest: Min-Heap priority queue merging to K=3")

    # 5. Full End-to-End Pipeline on Synthetic Image
    rng = np.random.default_rng(123)
    test_img = rng.integers(0, 256, (40, 50, 3), dtype=np.uint8)
    clusterer = PatentColorClusterer(k_colors=8, bits=3, refine_palette=True)
    out_img = clusterer.fit_transform(test_img)
    unique_out = len(np.unique(out_img.reshape(-1, 3), axis=0))
    assert unique_out <= 8
    print("[PASS] PatentColorClusterer: Complete fit_transform pipeline with refinement")

    print("\nAll unit tests passed successfully!\n")

def run_benchmarks():
    print("=" * 75)
    print("BENCHMARK COMPARISON: bob_code vs OpenCV K-Means")
    print("=" * 75)

    test_images = {
        "Astronaut": data.astronaut(),
        "Coffee": data.coffee(),
        "Chelsea": data.chelsea(),
    }

    k_target = 16

    print(f"{'Image':<12} {'Resolution':<12} | {'bob_code (Patent)':<20} | {'OpenCV K-Means':<20} | {'Speedup':<8}")
    print("-" * 80)

    for name, rgb in test_images.items():
        bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)

        # 1. Patent Implementation (bob_code)
        t0 = time.perf_counter()
        clusterer = PatentColorClusterer(k_colors=k_target, bits=4, metric=DistanceMetric.EUCLIDEAN_RGB)
        clustered = clusterer.fit_transform(bgr)
        dt_patent = (time.perf_counter() - t0) * 1000.0
        psnr_patent = compute_psnr(bgr, clustered)

        # 2. OpenCV K-Means
        t0 = time.perf_counter()
        pixels = bgr.reshape(-1, 3).astype(np.float32)
        criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 20, 1.0)
        _, labels, centers = cv2.kmeans(pixels, k_target, None, criteria, 3, cv2.KMEANS_PP_CENTERS)
        dt_kmeans = (time.perf_counter() - t0) * 1000.0
        kmeans_img = np.uint8(np.clip(centers, 0, 255))[labels.ravel()].reshape(bgr.shape)
        psnr_kmeans = compute_psnr(bgr, kmeans_img)

        speedup = dt_kmeans / dt_patent
        res_str = f"{bgr.shape[1]}x{bgr.shape[0]}"
        pat_str = f"{dt_patent:5.1f} ms ({psnr_patent:5.2f} dB)"
        km_str = f"{dt_kmeans:5.1f} ms ({psnr_kmeans:5.2f} dB)"

        print(f"{name:<12} {res_str:<12} | {pat_str:<20} | {km_str:<20} | {speedup:5.1f}x")

    print("-" * 80)

    # Test stream inference throughput
    chelsea_bgr = cv2.cvtColor(data.chelsea(), cv2.COLOR_RGB2BGR)
    t0 = time.perf_counter()
    n_frames = 100
    for _ in range(n_frames):
        _ = clusterer.transform(chelsea_bgr)
    avg_inference_ms = (time.perf_counter() - t0) / n_frames * 1000.0
    fps = 1000.0 / avg_inference_ms
    print(f"\nThroughput on stream video frames: {avg_inference_ms:.2f} ms/frame ({fps:.1f} FPS)")

if __name__ == "__main__":
    run_unit_tests()
    run_benchmarks()
```

- Running the code above give the following result;

**Hat's off Bob 🎩**

# 
  Conclusion: Why the Right SDLC & Code Generation Agent Matters?

As 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. 

**Thanks for reading 🔰**

# 
  Links

- Google Patent's page for **Fast color clustering for preprocessing an image** :[https://patents.google.com/patent/US11763422B2/](https://patents.google.com/patent/US11763422B2/)
- Marc Fiammante: [https://www.linkedin.com/in/marc-fiammante/](https://www.linkedin.com/in/marc-fiammante/)
- Jean-Armand Broyelle: [https://www.linkedin.com/in/jean-armand-broyelle-81a0012/](https://www.linkedin.com/in/jean-armand-broyelle-81a0012/)
- Code repository for this post: [https://github.com/aairom/opencv-mf](https://github.com/aairom/opencv-mf)
- 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)
