Kmeans Quantize 🍌

If you've ever used a flat posterize filter and been annoyed at how it evenly chops color values regardless of what's actually in the image, k-means quantization is the smarter version of that idea. Instead of slicing color space into equal buckets, it clusters your image's actual pixel colors into groups and represents each pixel by its cluster's center - so the palette it lands on is shaped by what's really in the picture, not an arbitrary grid.

How it actually works

K-means is a classic unsupervised clustering algorithm: pick some number of cluster centers, assign every pixel to its nearest center, recompute each center as the average of the pixels assigned to it, and repeat until it settles. The result is a reduced color palette that concentrates detail where your image actually has color variation and collapses flat regions efficiently - which is why k-means quantization tends to look meaningfully better than naive posterizing at the same color count, especially on images with a few dominant colors and some fine detail.

Inputs and outputs

Required:

• image - the picture to quantize.
• colors - how many color clusters to reduce to, 1-256, default 256. Lower numbers give you a more obviously stylized, flat-color look; higher numbers stay closer to the original while still cleaning up noisy gradients.
• individual - a boolean. Going by the name, this controls whether each image in a batch gets its own independent set of clusters, versus sharing one palette across the whole batch - worth toggling if you're processing a batch and want consistent colors across frames rather than each one solved separately.
• kmeans_pp - a boolean for k-means++ initialization, a well-known improvement over plain random cluster-center starts that tends to converge to a better result and more reliably avoid a bad random seed producing a lopsided palette.
• manhattan - a boolean for switching the distance metric from the default Euclidean to Manhattan (L1) distance when assigning pixels to clusters. Manhattan distance is less sensitive to large single-channel outliers and can produce a slightly different, sometimes more balanced clustering.
• seed - for reproducibility, since k-means initialization is stochastic.

Output is a single IMAGE - the quantized result.

Installing it

ComfyUI Manager, search "cgem156-ComfyUI". Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/laksjdjf/cgem156-ComfyUI

Restart ComfyUI. No model weights needed - this is a self-contained algorithm running on the image tensor, so it's fast and has zero external dependencies to worry about.

Where you'd actually reach for this

Flat-color stylization is the obvious use - turning a photorealistic render into something that reads more like cel art or a limited-palette illustration. It's also genuinely useful as a preprocessing step: reducing an image to a clean, small palette before feeding it into something that benefits from flatter color regions, or as a quick way to check what an image's dominant colors actually are.

Common issues

Set colors very low on a busy, high-detail image and you'll get harsh, blocky banding rather than a clean stylized look - that's k-means doing exactly what it's supposed to when there simply aren't enough clusters to represent the color variety present. If results look inconsistent between runs at the same settings, check your seed - k-means starts from random centers unless you fix it, and different starting points can converge to visibly different palettes, especially at low color counts where there's more than one reasonable clustering to land on.