`plscmap1l`: Set cmap1 colors using a piece-wise linear relationship
Prev | Chapter 18. The Common API for PLplot | Next

#### `plscmap1l`: Set cmap1 colors using a piece-wise linear relationship

`plscmap1l (` | itype ,
| npts ,
| intensity ,
| coord1 ,
| coord2 ,
| coord3 ,
| alt_hue_path `)`;

Set cmap1 colors using a piece-wise linear relationship between the cmap1 intensity index (0.0-1.0) and position in HLS or RGB color space (see the section called “Color Map1”). May be called at any time.

The idea here is to specify a number of control points that define the mapping between input cmap1 intensity indices and HLS (or RGB). Between these points, linear interpolation is used which gives a smooth variation of color with intensity index. Any number of control points may be specified, located at arbitrary positions, although typically 2 - 4 are enough. Another way of stating this is that we are traversing a given number of lines through HLS (or RGB) space as we move through cmap1 intensity indices. The control points at the minimum and maximum position (0 and 1) must always be specified. By adding more control points you can get more variation. One good technique for plotting functions that vary about some expected average is to use an additional 2 control points in the center (position ~= 0.5) that are the same lightness as the background (typically white for paper output, black for crt), and same hue as the boundary control points. This allows the highs and lows to be very easily distinguished.

Each control point must specify the cmap1 intensity index and the associated three coordinates in HLS or RGB space. The first point must correspond to position = 0, and the last to position = 1.

The default behaviour is for the hue to be linearly interpolated between the control points. Since the hue lies in the range [0, 360] this corresponds to interpolation around the "front" of the color wheel (red<->green<->blue<->red). If `alt_hue_path[i]` is true, then an alternative interpolation is used between control points `i` and `i+1`. If `hue[i+1]-hue[i] > 0` then interpolation is between `hue[i]` and `hue[i+1] - 360`, otherwise between `hue[i]` and `hue[i+1] + 360`. You can consider this as interpolation around the "back" or "reverse" of the color wheel. Specifying `alt_hue_path=NULL` is equivalent to setting `alt_hue_path[] = false` for every control point.

Table 18.1. Examples of interpolation

Hue | alt_hue_path | color scheme
--- | --- | ---
[120 240] | false | green-cyan-blue
[240 120] | false | blue-cyan-green
[120 240] | true | green-yellow-red-magenta-blue
[240 120] | true | blue-magenta-red-yellow-green

Table 18.2. Bounds on coordinates

RGB | R | [0, 1] | magnitude
RGB | G | [0, 1] | magnitude
RGB | B | [0, 1] | magnitude
HLS | hue | [0, 360] | degrees
HLS | lightness | [0, 1] | magnitude
HLS | saturation | [0, 1] | magnitude

`itype` (``PLBOOL``, input)

  true: RGB, false: HLS.

`npts` (``PLINT``, input)

  number of control points

`intensity` (``PLFLT_VECTOR``, input)

  A vector containing the cmap1 intensity index (0.0-1.0) in ascending order for each control point.

`coord1` (``PLFLT_VECTOR``, input)

  A vector containing the first coordinate (H or R) for each control point.

`coord2` (``PLFLT_VECTOR``, input)

  A vector containing the second coordinate (L or G) for each control point.

`coord3` (``PLFLT_VECTOR``, input)

  A vector containing the third coordinate (S or B) for each control point.

`alt_hue_path` (``PLBOOL_VECTOR``, input)

  A vector (with `npts - 1` elements) containing the alternative interpolation method Boolean value for each control point interval. (`alt_hue_path[i]` refers to the interpolation interval between the `i` and `i + 1` control points).

Redacted form: `plscmap1l(itype, intensity, coord1, coord2, coord3, alt_hue_path)`

This function is used in examples 8, 11, 12, 15, 20, and 21.

Prev | Up | Next
`plscmap1a`: Set semitransparent cmap1 RGBA colors. | Home | `plscmap1la`: Set cmap1 colors and alpha transparency using a piece-wise linear relationship