I've done a couple of other checks over the weekend. It seems to me that ignoring the rev parameter. The colourscale is traversed in the direction of the difference in hue; i.e. if I use 0-240 I get red, yellow, green, turquoise, blue, if I use 240-0 I get blue, turquoise, green, yellow, red. If I do 240-360 I get blue, purple, red. I seem even able to do 240-720 to cycle more than once around the colourwheel.
It seems therefore that when specifying colours using the HLS colour model, the rev parameter isn't really needed. Renaming it alt_path and describing what this mean seems sensible. Something like "The hue is interpolated using the degree values provided and values >=360 or <0 can be used to ensure the interpolation travels the correct way around the colour wheel. If alt_hue_path is true then
the interpolation goes the opposite way around the colour wheel.
Something I hadn't realised until I looked at the code is that if you specify RGB colours, then these are transformed to HLS colours and the interpolation is performed in HSL space. I assume that the HSL colours are always in the 0-359.999 range and hence red will always have a hue of 0. In this case a red-blue or blue-red scale will cross green unless the rev (or alt_hue_path) is used.
Overall a description something like the following could replace the two paragraphs immediately preceding Table 19-1:
Each control point must specify the position in color map1 as well as three coordinates in HLS or RGB space. The first must correspond to position = 0, and the last to position = 1. If colors are provided in RGB space then these are converted to HLS space for the
interpolation with the derived hue always in the range [0,360).
When control points are provided in HLS space, values of hue outside the 0-360 degree range can be used to ensure the interpolation travels in the required direction around the color wheel. Also the alt_hue_path can be used to reverse the direction around the color wheel. When control points are provided in RGB space consideration must be given to the hue which will be generated (see plrgbhls) and hence the direction along which the color wheel will be traversed. Again alt_hue_path can be used to reverse the interpolation direction around the color wheel.
Also adding an asterisk to the 0-360 range stating:
Values outside the 0-360 range may be used to ensure correct interpolation around the color wheel.
From: Maurice LeBrun <email@example.com>
To: Alan W. Irwin <firstname.lastname@example.org>
Cc: Maurice LeBrun <email@example.com>; phil rosenberg <firstname.lastname@example.org>; "email@example.com" <firstname.lastname@example.org>
Sent: Monday, 13 August 2012, 0:03
Subject: Re: [Plplot-devel] cmap1 colourscale direction
On Sunday, August 12, 2012 at 12:59:53 (-0700) Alan W. Irwin writes:
> "path_includes_zero" usually does
describe the mathematical meaning,
> but that term is ambiguous for the special case when the hue range
> ends with zero or 360 since both path alternatives in that case
> include zero (or 360). To avoid ambiguity, how about dropping all
> special meaning from the name and using "alt_hue_path" instead (with
> appropriate docbook and doxygen documentation of exactly what that
> means in a mathematical sense)?