Figure 1: A lovely Belgian windmill, fully indexed and dithered with perfectly awful, randomly selected colors.

-index

Given a palette or look-up table of reference colors and a source image, the command determines for each source image pixel, the most closely matching reference color in the palette. Depending on the map_palette flag, the pixels of the output image may hold reference colors or look-up table indices to the most closely matching color.

The command has the form :

-index { [palette] | predefined_palette },
  0<= dithering <= 1,
 

map_palette={ 0 | 1 }

  1. palette: An image selection or the index number of one among a number of predefined Look-up Tables (LUT). Either form furnishes the command with a set of reference colors among which it can find a “close match” for each pixel in the original image.

    When this parameter is an image selection (a numeric index in square brackets), the selected image is taken to be a single row, multicolumn set of reference colors, regardless of the image dimensions. The command indexes the pixels in the reference image from left-to-right, top-to-bottom, taking each pixel to be a reference color. While the image may be any size, it is rarely practical to have more than a few hundred reference colors, and a few dozen are usually ample. The image is almost always quite small.

    When this parameter is a integer, it is taken to be a reference to a number of built-in color lookup tables. As distributed, G'MIC has eight such tables:

    1. Default: the 256 colors of an 8×8×8 RGB color cube
    2. HSV: 256 steps counterclockwise, 360° around the HSV color circle,
    3. Line: 256 colors of varying saturation and luminance that collectively resembles the “average picture”,
    4. Hot: 256 steps from the black to red, red to yellow, and yellow to white vertices of the RGB color cube,
    5. Cool: 256 step ramp from cyan to magenta,
    6. Jet:256 step ramp clockwise around an arc of the HSV color circle, from 240° (blue), through 120° (green), 60° (yellow) and 0° (red), Often used in false color visualizations.
    7. Flag: 4 steps: black followed by the French tricolor,
    8. Cube: 256 step ramp traversing the black, red, green, yellow, cyan, white, blue and magenta vertices of the RGB color cube.

  2. dithering: (float from the closed interval [0, …, 1]) Sets the size of a neighborhood around which the command attempts to match the neighborhood average, rather than a single pixel. With nonzero dithering, the command factors nearby pixels through a kernel containing a dithering pattern (see -convolve). Otherwise, set to zero, it matches pixels without regard to the neighborhood.

  3. map_palette: (boolean), when False, output image pixels contain the index number that addresses the closest matching color in the palette. That is, the image is an index map. Superficially, the index map seems to be a gray scale; in fact, each pixel contains an index into the color palette addressing the closest matching color. The -map command, in conjunction with the given palette, outputs an image with indices replaced by the reference color. Otherwise, when True, the output image is directly composed with the closest matching reference colors.

When dithering is non-zero, -index can very nearly cancel out otherwise large mismatch errors. This is especially useful when the reference colors are fixed and have no great affinity to the colors in the given source image. The command takes into account the value of neighboring pixels and can assign reference colors to adjacent pixels that are also “wrong, but wrong in different directions”, so that, when averaged in the eye of the viewer, the two errors produce an aggregate that (more or less) approximates the color of the neighborhood. Look at the dithered and undithered CMYK examples below.

When the flag map_palette is set to False, output pixels are set to the numeric index of the position of the reference color in the palette, rather than the reference color itself. This indirection is useful for tabulating color usage statistics; the output constitutes an index map. Retaining the palette of reference colors, and applying the -map command to the palette and index map produces an output image with the reference colors replacing their indices.

Examples

     castlegate.jpg
A door at Castle Pernštejn, Nedvědice, Czech Republic, by Pudelek, Wikimedia Commons 
gmic -srand 67123             \
     -input castlegate.jpg    \
     4,4,1,3,u                \
     -normalize[-1] 0,255     \
     -index[-2] [-1],1,1      \
     -output[-2] cg_random.png
Indexed by sixteen randomly chosen reference colors, fully dithered 
gmic -input castlegate.jpg \
     --colormap[-1] 16,1,1 \
     -index[-2] [-1],0.5,1 \
     -output[-2] cg_optimal.png
Indexed by sixteen optimally chosen reference colors, as estimated by the -colormap command, partially dithered. 
gmic -input castlegate.jpg        \
     --colormap[-1] 16,1,1        \
     -index[-2] [-1],1,0          \
     -histogram[-2] '{-1,w}'      \
     -display_graph[-2] 800,600,3 \
     -output[-2] cg_graph.png
A graph indicating how frequently the optimal reference colors occur in the output image when fully dithered. 
gmic -input castlegate.jpg \
     -index[-1] 6,1,1      \
     -output[-1] cg_ftri.png
Indexed by black and the three colors of the French flag, fully dithered. 
gmic -input castlegate.jpg \
     '(0,255,255,0^255,0,255,0^255,255,0,0)'\
     -index[-2] [-1],0,1    \
     -output[-2] cg_cmyk.png

Indexed by CMYK, not dithered at all

 
gmic -input castlegate.jpg \
     '(0,255,255,0^255,0,255,0^255,255,0,0)'\
     -index[-2] [-1],1,1    \
     -output[-2] cg_cmyk2.png

Indexed by CMYK, fully dithered.

Technical Note: Color Mapping in G'MIC