Color Palette Extractor

Extracting a color palette isn't as simple as picking the most frequent pixels. A high-resolution image can have millions of unique colors.

To find the true "dominant" thematic colors, this tool uses a classic machine learning algorithm called K-Means Clustering.

• Downsampling: Processing millions of pixels on the main thread would freeze the browser. First, the image is downscaled to a maximum width of 200px using an OffscreenCanvas. This reduces the dataset from millions of pixels to a maximum of 40,000 without significantly altering the dominant visual colors.
• K-Means++ Initialization: The algorithm needs starting points (centroids). Instead of picking them randomly, we use K-Means++, which picks the first centroid randomly, and then selects subsequent centroids that are as far away as possible from the existing ones to ensure a diverse palette.
• Optimization Loop: Every pixel is assigned to its nearest centroid in 3D RGB space. Then, the centroid is mathematically moved to the exact center of all the pixels assigned to it. This loop repeats up to 20 times until the colors stabilize.
• Deduplication: Finally, we sort the centroids by how many pixels they "own" (most dominant first) and filter out colors that are visually indistinguishable (distance < 15 in RGB space).

K-Means involves calculating the Euclidean distance between every single pixel and every centroid, multiple times per second.

To prevent this heavy math from causing the UI to stutter, the clustering loop is entirely offloaded to a background thread (image.worker.ts). This guarantees your browser remains perfectly responsive while the algorithm crunches the numbers locally.

No algorithm is perfect. K-Means groups colors into hard boundaries. If an image is mostly a smooth sunset gradient, the algorithm might result in arbitrary, harsh bands of color being selected as "dominant."

Additionally, because we downsample the image to 200px to maintain performance, colors that only appear in tiny details (like a 1px thin border) will be averaged out by the canvas scaling and completely ignored by the algorithm.