Implement CubeHelix color maps, and reorganize command line and GUI accordingly.
[gencolormap.git] / colormap.hpp
1 /*
2  * Copyright (C) 2015 Computer Graphics Group, University of Siegen
3  * Written by Martin Lambers <martin.lambers@uni-siegen.de>
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy
6  * of this software and associated documentation files (the "Software"), to deal
7  * in the Software without restriction, including without limitation the rights
8  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9  * copies of the Software, and to permit persons to whom the Software is
10  * furnished to do so, subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in
13  * all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
18  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21  * SOFTWARE.
22  */
23
24 #ifndef COLORMAP_HPP
25 #define COLORMAP_HPP
26
27 /* Generate color maps for scientific visualization purposes.
28  *
29  * This implements the methods described in
30  * "Generating Color Palettes using Intuitive Parameters" by
31  * Martijn Wijffelaars, Roel Vliegen, Jarke J. van Wijk and Erik-Jan van der
32  * Linden, Eurographics/IEEE-VGTC Symposium on Visualization 2008
33  *
34  * Usage:
35  *
36  * Decide which type of color map you need and how many colors the map should
37  * contain:
38  * - For a continuous range of values (e.g. temperature, size, ...):
39  *   Sequential map with a single hue, at least 200 colors
40  * - For a continuous of values around a neutral middle (e.g. deviation from an
41  *   ideal value):
42  *   Diverging map, composed of two sequential maps with a neutral color in the
43  *   middle, at least 200 colors
44  *
45  * Allocate memory for your color map, and call the function that generates your
46  * map. All colors are represented as unsigned char sRGB triplets, with each
47  * value in [0,255].
48  */
49
50 namespace ColorMap {
51
52 /*
53  * Brewer-like color maps, as described in
54  * M. Wijffelaars, R. Vliegen, J.J. van Wijk, E.-J. van der Linden. Generating
55  * color palettes using intuitive parameters. In Computer Graphics Forum, vol. 27,
56  * no. 3, pp. 743-750, 2008.
57  */
58
59 // Create a sequential color map with n colors of the given hue in [0,2*PI].
60
61 const float BrewerSequentialDefaultHue = 0.0;
62 const float BrewerSequentialDefaultContrast = 0.88f;
63 float BrewerSequentialDefaultContrastForSmallN(int n); // only for discrete color maps, i.e. n <= 9
64 const float BrewerSequentialDefaultSaturation = 0.6f;
65 const float BrewerSequentialDefaultBrightness = 0.75f;
66 const float BrewerSequentialDefaultWarmth = 0.15f;
67
68 void BrewerSequential(int n, unsigned char* srgb_colormap,
69         float hue = BrewerSequentialDefaultHue,
70         float contrast = BrewerSequentialDefaultContrast,
71         float saturation = BrewerSequentialDefaultSaturation,
72         float brightness = BrewerSequentialDefaultBrightness,
73         float warmth = BrewerSequentialDefaultWarmth);
74
75 // Create a diverging color map with n colors. Half of them will have the given
76 // hue (in [0,2*PI]), the other half will have a hue that has the distance given
77 // by divergence (in [0,2*PI]) to that hue, and they will meet in the middle at
78 // a neutral color.
79
80 const float BrewerDivergingDefaultHue = 0.0;
81 const float BrewerDivergingDefaultDivergence = 4.18879020479f; // 2/3 * 2PI
82 const float BrewerDivergingDefaultContrast = 0.88f;
83 float BrewerDivergingDefaultContrastForSmallN(int n); // only for discrete color maps, i.e. n <= 9
84 const float BrewerDivergingDefaultSaturation = 0.6f;
85 const float BrewerDivergingDefaultBrightness = 0.75f;
86 const float BrewerDivergingDefaultWarmth = 0.15f;
87
88 void BrewerDiverging(int n, unsigned char* srgb_colormap,
89         float hue = BrewerDivergingDefaultHue,
90         float divergence = BrewerDivergingDefaultDivergence,
91         float contrast = BrewerDivergingDefaultContrast,
92         float saturation = BrewerDivergingDefaultSaturation,
93         float brightness = BrewerDivergingDefaultBrightness,
94         float warmth = BrewerDivergingDefaultWarmth);
95
96 // Create a qualitative color map with n colors. The colors will have the same
97 // saturation; lightness and hue will differ. The parameter hue sets the hue of
98 // the first color, and the parameter divergence defines the hue range starting
99 // from that hue that can be used for the colors.
100
101 const float BrewerQualitativeDefaultHue = 0.0f;
102 const float BrewerQualitativeDefaultDivergence = 4.18879020479f; // 2/3 * 2PI
103 const float BrewerQualitativeDefaultContrast = 0.5f;
104 const float BrewerQualitativeDefaultSaturation = 0.5f;
105 const float BrewerQualitativeDefaultBrightness = 1.0f;
106
107 void BrewerQualitative(int n, unsigned char* colormap,
108         float hue = BrewerQualitativeDefaultHue,
109         float divergence = BrewerQualitativeDefaultDivergence,
110         float contrast = BrewerQualitativeDefaultContrast,
111         float saturation = BrewerQualitativeDefaultSaturation,
112         float brightness = BrewerQualitativeDefaultBrightness);
113
114 /*
115  * CubeHelix color maps, as described in
116  * Green, D. A., 2011, A colour scheme for the display of astronomical intensity
117  * images, Bulletin of the Astronomical Society of India, 39, 289.
118  */
119
120 // Create a CubeHelix colormap with n colors. The parameter hue (in [0,2*PI])
121 // sets the hue of the first color. The parameter rot sets the number of
122 // rotations. It can be negative for backwards rotation. The saturation parameter
123 // determines the saturation of the colors; higher values may lead to clipping
124 // of colors in the sRGB space. The gamma parameter sets optional gamma correction.
125 // The return value is the number of colors that had to be clipped.
126
127 const float CubeHelixDefaultHue = 5.23598775598f; // 5/6 * 2PI
128 const float CubeHelixDefaultRotations = -1.5f;
129 const float CubeHelixDefaultSaturation = 1.2f;
130 const float CubeHelixDefaultGamma = 1.0f;
131
132 int CubeHelix(int n, unsigned char* colormap,
133         float hue = CubeHelixDefaultHue,
134         float rotations = CubeHelixDefaultRotations,
135         float saturation = CubeHelixDefaultSaturation,
136         float gamma = CubeHelixDefaultGamma);
137 }
138
139 #endif