***************************************************************************
                    COLOR HELIX PALETTE GENERATOR
                Copyright (C) 2011-2013 by Ingo Thies 
***************************************************************************

**** License info *********************************************************
    Colorhelix is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 2 of the License, or
    (at your option) any later version.

    Colorhelix is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Colorhelix. If not, see <http://www.gnu.org/licenses/>.
***************************************************************************

Based on the CUBEHELIX colour scheme invented by  David Green, 2011,
(see: http://adsabs.harvard.edu/abs/2011BASI...39..289G)

Motivation: Generate a colour scheme with separate hue and lightness.
Benefits: 

1. Clear perception of intensity by using an intuitive
   colouring ("dark = low intensity, bright = high intensity").

2. Intensity maps are easily interpreted even by partially
   or fully colour-blind people.

3. B/W printing converts colour in monotonic greyscales.

A good introduction can be found in David Green's paper on Cubehelix,
http://arxiv.org/abs/1108.5083.

Features: COLORHELIX further improves the CUBEHELIX colour scheme by
using the CIE 1976 and DIN99d/o L,a,b colour space in which lightness and
colour hue are well separated, and differences in the colour coordinates
a*, b* are an approximate measure for the perceived colour differences.
From v0.91 also IPT and IPT-EUC (Shizhe Shen 2009) are supported.
From v0.95 also CIECAM02 is included (but still experimental).

Methods: The colour scheme is first defined in the L*a*b* coordinates
where the colour curve spirals around the L axis by altering the
colour coordinates a* and b* (in contrast: CUBEHELIX spirals around
the gray axis r=g=b by altering r,g,b in an approximate equal-luma
plane given by linear weights for each r,g,b). The L,*a,*b* are then
converted into the CIEXYZ (1931) space and, finally, into sRGB.

The mathematical details are well described on Wikipedia,
http://en.wikipedia.org/wiki/Lab_color_space
http://en.wikipedia.org/wiki/CIE_1931_color_space
http://en.wikipedia.org/wiki/SRGB

Further information is available on Bruce Lindbloom's website,
http://www.brucelindbloom.com/index.html

For conversion matrices, in particular,
http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html

**** Contents ****
---- Source files:
Makefile                              The Makefile for easy installation
color_functions.f90                   Several colour calculation functions (not all are currently used by Colorhelix)
colorhelix.f90                        Colorhelix main program
colorhelix_module.f90                 Colorhelix routines & variables
diverse_mathconst.f90                 Mathmatical constants like pi (NOTE: Some are also included in color_functions)
palette_modules.f90                   RGB palette functions
testrgbtable.f90                      RGB palette test & conversion program.

---- Data & parameter files
colorhelix.inp                        Colorhelix parameter input file
testrgbtable.inp                      Dummy input file for easy piping
CIE1931border_400-700-1nm.dat         Border of the CIE 1931 colour "horseshoe"
planckcurve-fullrange.dat             Planckian locus from 400 K to infinity
planckcurve-negative.dat              Planckian locus geometrically extrapolated beyond infinity

---- Gnuplot scripts
testrgbtable.gp                       Script to test RGB tables
CIE1931tics_400-700-1nm.gp            Gnuplot tics (=arrows) & labels to the CIE 1931 border
planckxytics-kelvin-1000-10000.gp     Gnuplot tics for the Planckian locus.

---- Other
README                                This file

**** Installation ****
COLORHELIX is written in Fortran 90 and is best to be compiled
with the GNU Fortran compiler using GNUmake:

make colorhelix

**** Usage ****
In colorhelix.inp, the following parameters can be set:
(sample file)
256			Total number of levels (i.e. 0:255 has 256 levels)
1	-1		Model 0:RGB, 1:CIELAB, 2+3:DIN99d+o, 4+5:IPT+EUC; 1:mimic RGB spin & phase in Lab, -1: Lab s&p in RGB
0.75			Start colour
0.5			Rotations
2.	2		Saturation, force maxsat (0:off, 1:on, 2:min(sat,max), 3:maxsat times sat)
0.2	0.8	1	test range for maximum saturation check; enable-flag (>0 for on)
0.8	1.	1.	gray gamma, rotation gamma, amp power
0.30	0.59	0.11  	RGB-to-gray luma weights (used if preset==0)
0	1		RGB model (from rgb-primaries.asc), luma preset

** Levels **
The total number of colour levels = the number of resolved intensity steps. Typically,
numbers above 256 are rarely resolved by the RGB device and the users eyes, however,
up to 65536 levels (from 0 to 65535) are allowed. The highest level has the index
n_levels-1.

** Colour model **
Colorhelix currently supports 4 colour models, in particular:
0: RGB    - the Cubehelix method invented by Dave Green (2011)
1: CIELAB - a*-b* colour helix around the neutral L* axis
2: DIN99d - same in the more recent DIN99d version of L,a,b
3: DIN99o - same in the current DIN99 L,a,b space
4: IPT    - same in the IPT color space (tends to desaturate)
5: IPT-EUC- same in the Euclidian IPT color space (Shizhe Shen 2009, better saturation)

In addition, a special RGB cube mode is available as colour model -1. Here, the colours
are maximally saturated, so that always at least one channel is either zero or full.
While this may disrupt monotonicity (at least of the perceived luminance) this provides
a quick & dirty method to get extra vivid colours. The maximum saturation is controlled
by the saturation variable (values >1 are ignored). This full-cube mode is a simple way
to estimate the full gamut in different colour models (this needs post-process the data
written by Colorhelix).

** Colour sequence **
The most frequently used parameters are the start colour and the number of rotations
during the increase from black to white. These are in principle described in Green's
paper, but behave slightly different here due to the different metric in L*a*b*.
An approximation to CUBEHELIX can be achieved by setting the "mimic RGB spin & phase"
parameter (2nd parameter in the 2nd line) to +1. The start colour is then initialised
with an offset and negative direction. Per default it is set to -1 which makes the
Cubehelix mode (model = 0) behave in a similar way as L*a*b*. This, however, only
applies to the rough colour sequence. The exact colour hue and saturation, of course,
differs.

The conversion of the helix parameters between RGB (=Cubehelix) and L*a*b* (COLORHELIX)
is as follows:

start_RGB = 3/4*(1-start_Lab); rotations_RGB=-rotations_Lab
start_Lab = 1-4/3*start_rgb;   rotations_Lab=-rotations_RGB

rotations = unchanged.

** Saturation **
Further parameters are the saturation and maximum saturation mode. Saturation means
maximum radius in the L*a*b* space (or 1/2 radius in RGB space).

Max-saturation mode =0 means to use the saturation directly. 1 sets it to the maximally
possible value without colour truncation in RGB. 2 applies the input saturation as an
upper limit, otherwise use max. saturation. 3, finally, scales the max. saturation
with the input saturation (which means, of course, that values >1 always lead to
truncation). Note that the maximum no-truncation saturation differs with the
colour hue.

Max-sat mode >=10 finds the maximum saturation for which the palette
remains (strictly) monotonic. Max-sat mode >=20 uses this as only criterion, while
mode 10-19 uses the minimum of no-clipping and monotonic saturation (recommended).

*NEW* (and beta): Max. saturation tested only within a given range (may be switched
on and off by the integer flag in the third column). This is useful especially for the
new CIECAM02 modes which tend to over-saturate near the endpoints 0 or 1 for some
palette settings.

** Gamma corrections **
The gray gamma does what it is expected to do - adjusting the "speed"
of lightness increase. Values above 1 light up the dark regions, while
values <1 make the palette darker at the lower parts (NOTE: This has changed
since last update on 2012-07-03 to match gnuplot's intrinsic cubehelix mode).
Rotation gamma does the same to the rotational phase, i.e. the colour
change.
Finally, amp power puts an exponent to the colour saturation profile
during ascending the L (or grey) axis. Note that this is still experimental,
and values other than 1 may lead to confusing results.

** RGB model **
Allows to select the preferred RGB model. The RGB primaries and white points are
taken from rgb-primaries.asc. You may also define your own RGB preset (e.g.
change the white point etc.) by editing this file.
Please note that it doesn't make any sense to chose an RGB model which doesn't
fit your computer display. I.e. a model with a huge theoretical gamut won't
bring better colours if your display cannot deliver them. In particular, the RGB
model "ProPhoto" is rather theoretical since it contains imaginary colours (which
don't even exist under ideal circumstances). It is included here merely for
completeness.
In fact, the choice of the RGB model doesn't change the actual appearance in the
RGB helix mode, but alters the conversion to/from the other colour spaces. The
same is true for changing the white point. For most displays the default RGB
model (sRGB) is the correct one.

If you want to change the white balance of the actually displayed, this has to be
done in your display preferences rather than in Colorhelix.

** Favorite presets **
The start colour and the number of rotations can alternatively be loaded from
the file colorhelix-favorites.txt. Just set a number between 0 and the highest
favorite number. If one is found, this is used instead of the parameters from
colorhelix.inp. The RGB-like flag is automatically set to 1 (RGB mode for both
models [new in July 2012]). All other parameters (like saturation, gamma etc.)
remain unchanged.

**** Application of the output ****
COLORHELIX outputs three colour palettes

- colorhelix.rgb         sRGB colour palette (values from 0 to 1)
- colorhelix.xyz         CIE XYZ (1931) palette (values from 0 to 100)
- colorhelix.lab         CIE LAB (1976) palette (values from 0 to approx. 150)

All palettes have the form
#Level    value1    value2    value3
0
...
maxlevel

These can easily be used by plotting software like gnuplot. For programs which
require another format, the user is encouraged to add such output formats
to COLORHELIX.

Problems: For certain parameters the RGB-to-Grey conversion may lead to non-monotonic
greyscales. In most cases this can be solved by reducing the saturation or changing
the luma weights. However, since the luma weights of printers cannot be changed by
Colorhelix, using less-saturated colours of fall-back to RGB Cubehelix mode is recommended
for printing.

**** Test the colour tables ****
The program TESTRGBTABLE (make testrgbtable) allows a quick test of any RGB table.
If the input file is 'colorhelix.rgb', then several auxiliary data (like e.g. the
RGB primaries) are also used. For any other RGB table, currently sRGB is assumed.
For easy transformation to other RGB spaces the user can temporarily copy the file
to 'colorhelix.rgb' (note that this will be overwritten by any COLORHELIX run in
the same folder) and edit the accompanying auxiliary files. However, sRGB is currently
the most widely used RGB space, and most others (like Apple RGB) are quite similar
to it.
