Figure 1: A mapping from gray to color

-map

Map assigns palettes of reference colors to index maps. The index map is a single channel gray scale. The numeric values of its pixels are taken to be indices which select colors from a given palette of reference colors.

Informally, -map is the "paint-by-numbers" command. The palette corresponds to a box of enumerated paints; these can't be mixed nor used from somewhere else. The index map corresponds to the card printed with various enumerated regions. The painter corresponds to the -map command; he or she looks at the card and paints regions the color corresponding to the number printed in the region.

In a restricted sense, -map is the inverse operator of -index. When one sets that command's map_palette parameter False, -index produces a single channel gray scale image, the index map. its pixels contain indices that assign reference colors from the palette to the pixels. The -map command produces a new image by following all of the assignments indicated in the index map.

In a less restricted sense, one may regard any gray scale image as an index map; such need not be produced by -index. Taking this liberty, then -map becomes a tool to convert gray scales into "false color" images.

One practical aim of this idea is to make lucid features that are not particularly clear in some gray scale representation of a phenomenon. One makes a correspondence between gray levels and color (i. e., constructs a palette of reference colors) and then makes astute color assignments for those very nearly identical grays that are difficult to distinguish.

The command has the form:

`-map`	`{ [palette] \| predefined_palette },`
	`boundary`

palette: An image selection or the index number of one among a number of predefined Look-up Tables (LUT). Either form furnishes the -map command with an enumerated set of reference colors that it can assign to gray scale levels.

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 which may be selected through integers 0 through 7:
1. Default: the 256 colors of an 8×8×8 RGB color cube
2. HSV: 256 steps counterclockwise 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,
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.
boundary: Sets policy when indices in the map reference colors outside the range of the palette:
1. dirichlet: Assume the color beyond the reference palette is black.
2. neumann: Assume the color beyond reference palette is the same as that of the largest index value.
3. cyclic: Replace the out-of-bounds index, k with r = k modulo p, where p is the length of the pallete. That is, indices exceeding the length of the palette “wrap around” to the beginning of the palette. The color appearing in the output corresponds to r.

Example

Root polishing by Newton's method entails using a succession of trial values starting from initial guesses. These trial guesses take the form of complex numbers, x + iy. Some guesses converge very rapidly toward the roots of a given polynomial; others do not converge until thousands of iterations have taken place and some guesses never converge.

The picture below stems from a dense, rectangular mesh sampling the complex plane around the origin. Each sample becomes an initial guess for convergence under Newton's method to a designated root of some degree two (or greater) polynomial. If the guess converges to one of the other roots, the pixel corresponding to the sample is set to black. Otherwise, it is set to a gray.

The level of this gray, L, relates to the number of interations, i, through:

$L = \frac{176.752531}{\log (1 + i)}$

for total iterations i, an integer greater than zero. If it should happen that a sample value converges acceptably close to the root in as little as one iteration of Newton's Method, then L ≈ 255.0 and the pixel corresponding to the sample is set to white. As the number of iterations increase, the gray level, L, converges to zero, but never reaches it. If, after 10,000 iterations, the guess is still has not converged, we abandon all hope for that particular sample and set the corresponding pixel to L ≈ 19, the darkest gray in the image that is still not black. Samples that converge to a particular root compose its basin of attraction. The picture below depicts a portion of the basin of attraction for one root of some polynomial (for present purposes, it does not matter which one).

It turns out that the basin of attraction for a particular root has a really quite fantastic, fractal shape if the degree of the associated polynomial is two or higher. But there is a problem with the way we are imaging this basin of attraction. A sample that takes more than 10,000 iterations to converge upon the designated root is a very dark gray. A sample that converges to some other root is black. These two very distinct cases, that have very different meanings, have almost the same shade of gray!

This is the kind of conundrum that -map can fix.

	basin_index_map.png A basin of attraction for one of the roots of some polynomial. Very dark gray corresponds to parts of the basin which take a very large number of iterations before converging on a root. Black corresponds to other basins of attraction. `Tis not a very distinct distinction.
	palette.png We make a palette of reference colors that is almost a blue gray ramp, but we set the color corresponding to index 0 (black) to a violet. This color will correspond to samples that belong in other basins of attraction. We have also designated other indices as interesting; red, for example, corresponds to those samples that converge upon the designated root in just two iterations.
	basin.png gmic -input basin_index_map.png \ -input palette.png \ -map[-2] [-1],0 \ -remove[-1] \ -output[-1] basin.png Mapping violet to position 0 of the reference palette has given us a clear indication of samples that belong to other basins and those that belong to the designated basin, but take a great many iterations to converge. It appears that those high iteration samples trace out a Fatou set of some sort, which is interesting, but its investigation takes us rather far afield from G'MIC. The key takeaway is that `-map` made clear a pattern that is obscure and could otherwise escape our attention. But, with a new phenomenon made lucid through `-map,` we now have an interesting line of investigation that we may write up elsewhere in the sweet fullness of time.