Given one or more selected images and a count, -colormap generates palettes containing like numbers of estimated “good-fit” colors. Palettes are small images, usually one pixel high and a just a few pixels long, though it is not unusual to have a few hundred pixels in a palette. Each pixel is a color swatch, and tend to reflect the dominant colors of the image. One could think of the -colormap command as a "dominant color detector."
Use -colormap with -index to make a new image that uses very few colors compared to the original, but remains a reasonably good reproduction.
Use -colormap with -map to convert gray scales into false color images.
The command has the form:
Color count (desired palette size)
Method: 0|1 (median cut only | median cut and k-means)
Sort 0|1 (ascending or descending)
Color count: Sets the size of the color palette. -colormap prepares a palette of this many colors so estimated as to fairly match the original hues in the given image. If the count is zero, every unique color in the original becomes a part of the palette; this is practical only for small images or images which have been color-reduced and imaged through -index or -autoindex; these images have only limited numbers of unique colors.
Method: When False, -colormap only uses the median-cut method. Otherwise, (True) -colormap harnesses the k-means clustering algorithm to refine an initial median-cut-based estimate. The extra stage adds some processing overhead.
Sort: When unspecified, the colors in the palette are approximately ordered from dark-to-light, but have not been fully sorted. Sorting with a '0' flag strictly arranges the palette from dark to light. Sorting with a '1' flag orders from light-to-dark.
Consider writing your palettes in a high precision format such as .cimg. In particular, eight bit unsigned integer formats will shave away the hard-won precision furnished by the k-means algorithm; you may as well not use k-means at all if you then save your color map in an eight bit .png or .jpg file.
If you find yourself invoking -colormap often, then making reduced-color versions of the originals with -index, consider using -autoindex which combines -colormap and -index. Note that -autoindex generates the palette internally, deleting it when finished. Running -colormap[…] 0,0 with the output of -autoindex referenced in the selector will recover an equivalent version of the palette.
Technical Note: Color Mapping in G'MIC
— Garry Osgood