Module imagingbook.common

Package imagingbook.common.color.quantize

Class KMeansClusteringQuantizer

java.lang.Object

imagingbook.common.color.quantize.KMeansClusteringQuantizer

All Implemented Interfaces:

ColorQuantizer

public class KMeansClusteringQuantizer
extends Object
implements ColorQuantizer

This class implements color quantization using k-means clustering of image pixels in RGB color space. It provides two modes for selecting initial color clusters: (a) random sampling of the input colors, (b) using the K most frequent colors. Note that this implementation is mainly to demonstrate the concept. Depending on the data size and number of quantization colors, this process may be excessively slow compared to other methods. It is usually impractical even for medium-sized images. During clustering all input pixels are used, i.e., no stochastic sub-sampling is applied (which could make the process a lot more efficient).

Version:

2022/11/06

See Also:

• MedianCutQuantizer
• OctreeQuantizer

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	KMeansClusteringQuantizer.InitialClusterMethod	Method for choosing initial color clusters.

Field Summary

Fields

Modifier and Type	Field	Description
static int	DefaultIterations
static long	RandomSeed	Seed for random number generation (set to a nonzero value to obtain repeatable results for debugging and testing).

Fields inherited from interface imagingbook.common.color.quantize.ColorQuantizer

MAX_RGB

Constructor Summary

Constructors

Constructor	Description
KMeansClusteringQuantizer(int[] pixels, int K)	Constructor, creates a new KMeansClusteringQuantizer with up to K colors, using default parameters.
KMeansClusteringQuantizer(int[] pixels, int K, KMeansClusteringQuantizer.InitialClusterMethod initMethod, int maxIterations)	Constructor, creates a new KMeansClusteringQuantizer with up to K colors, but never more than the number of colors found in the supplied pixel data.

Method Summary

Modifier and Type	Method	Description
float[][]	getColorMap()	Retrieves the color map produced by this color quantizer.
double	getTotalError()	Returns the final clustering error, calculated as the sum of the squared distances of the color samples to the associated cluster centers.
void	listClusters()	Lists the color clusters to System.out (for debugging only).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface imagingbook.common.color.quantize.ColorQuantizer

findColorIndex, getColorCount, quantize, quantize, quantize

Field Details

RandomSeed

public static long RandomSeed

Seed for random number generation (set to a nonzero value to obtain repeatable results for debugging and testing).

DefaultIterations

public static int DefaultIterations

Constructor Details

KMeansClusteringQuantizer

public KMeansClusteringQuantizer(int[] pixels,
 int K)

Constructor, creates a new KMeansClusteringQuantizer with up to K colors, using default parameters.

Parameters:

pixels - an image as a aRGB-encoded int array

K - the desired number of colors (1 or more)

KMeansClusteringQuantizer

public KMeansClusteringQuantizer(int[] pixels,
 int K,
 KMeansClusteringQuantizer.InitialClusterMethod initMethod,
 int maxIterations)

Constructor, creates a new KMeansClusteringQuantizer with up to K colors, but never more than the number of colors found in the supplied pixel data.

Parameters:

pixels - an image as a aRGB-encoded int array

K - the desired number of colors (1 or more)

initMethod - the method to initialize color clusters (KMeansClusteringQuantizer.InitialClusterMethod)

maxIterations - the maximum number of clustering iterations

Method Details

getColorMap

public float[][] getColorMap()

Description copied from interface: ColorQuantizer

Retrieves the color map produced by this color quantizer. The returned array is in the format float[idx][rgb], where rgb = 0 (red), 1 (green), 2 (blue) and 0 ≤ idx < nColors.

Specified by:

getColorMap in interface ColorQuantizer

Returns:

The table of reference (quantization) colors.

listClusters

public void listClusters()

Lists the color clusters to System.out (for debugging only).

getTotalError

public double getTotalError()

Returns the final clustering error, calculated as the sum of the squared distances of the color samples to the associated cluster centers. This calculation is performed during the final iteration.

Returns:

the final clustering error