Adjust defaults for isoluminant sequential/divergent.
[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  * Usage:
30  * - Decide which type of color map you need and how many colors the map should
31  *   contain.
32  * - Allocate memory for you color map (3 * unsigned char for each color entry).
33  * - Call the function that generates your color map.
34  *
35  * All colors are represented as unsigned char sRGB triplets, with each value in
36  * [0,255].
37  */
38
39 namespace ColorMap {
40
41 /*
42  * Brewer-like color maps, as described in
43  * M. Wijffelaars, R. Vliegen, J.J. van Wijk, E.-J. van der Linden. Generating
44  * color palettes using intuitive parameters. In Computer Graphics Forum, vol. 27,
45  * no. 3, pp. 743-750, 2008.
46  */
47
48 // Create a sequential color map with n colors of the given hue in [0,2*PI].
49
50 const float BrewerSequentialDefaultHue = 0.0;
51 const float BrewerSequentialDefaultContrast = 0.88f;
52 float BrewerSequentialDefaultContrastForSmallN(int n); // only for discrete color maps, i.e. n <= 9
53 const float BrewerSequentialDefaultSaturation = 0.6f;
54 const float BrewerSequentialDefaultBrightness = 0.75f;
55 const float BrewerSequentialDefaultWarmth = 0.15f;
56
57 void BrewerSequential(int n, unsigned char* srgb_colormap,
58         float hue = BrewerSequentialDefaultHue,
59         float contrast = BrewerSequentialDefaultContrast,
60         float saturation = BrewerSequentialDefaultSaturation,
61         float brightness = BrewerSequentialDefaultBrightness,
62         float warmth = BrewerSequentialDefaultWarmth);
63
64 // Create a diverging color map with n colors. Half of them will have the given
65 // hue (in [0,2*PI]), the other half will have a hue that has the distance given
66 // by divergence (in [0,2*PI]) to that hue, and they will meet in the middle at
67 // a neutral color.
68
69 const float BrewerDivergingDefaultHue = 0.0;
70 const float BrewerDivergingDefaultDivergence = 4.18879020479f; // 2/3 * 2PI
71 const float BrewerDivergingDefaultContrast = 0.88f;
72 float BrewerDivergingDefaultContrastForSmallN(int n); // only for discrete color maps, i.e. n <= 9
73 const float BrewerDivergingDefaultSaturation = 0.6f;
74 const float BrewerDivergingDefaultBrightness = 0.75f;
75 const float BrewerDivergingDefaultWarmth = 0.15f;
76
77 void BrewerDiverging(int n, unsigned char* srgb_colormap,
78         float hue = BrewerDivergingDefaultHue,
79         float divergence = BrewerDivergingDefaultDivergence,
80         float contrast = BrewerDivergingDefaultContrast,
81         float saturation = BrewerDivergingDefaultSaturation,
82         float brightness = BrewerDivergingDefaultBrightness,
83         float warmth = BrewerDivergingDefaultWarmth);
84
85 // Create a qualitative color map with n colors. The colors will have the same
86 // saturation; lightness and hue will differ. The parameter hue sets the hue of
87 // the first color, and the parameter divergence defines the hue range starting
88 // from that hue that can be used for the colors.
89
90 const float BrewerQualitativeDefaultHue = 0.0f;
91 const float BrewerQualitativeDefaultDivergence = 4.18879020479f; // 2/3 * 2PI
92 const float BrewerQualitativeDefaultContrast = 0.5f;
93 const float BrewerQualitativeDefaultSaturation = 0.5f;
94 const float BrewerQualitativeDefaultBrightness = 0.8f;
95
96 void BrewerQualitative(int n, unsigned char* colormap,
97         float hue = BrewerQualitativeDefaultHue,
98         float divergence = BrewerQualitativeDefaultDivergence,
99         float contrast = BrewerQualitativeDefaultContrast,
100         float saturation = BrewerQualitativeDefaultSaturation,
101         float brightness = BrewerQualitativeDefaultBrightness);
102
103 /*
104  * Isoluminant color maps.
105  *
106  * These are useful for coloring surfaces because their constant luminance
107  * allows non-interfering combination with shading.
108  */
109
110 // Create a sequential isoluminant color map with n colors.
111
112 const float IsoluminantSequentialDefaultLuminance = 0.5f;
113 const float IsoluminantSequentialDefaultSaturation = 0.5f;
114 const float IsoluminantSequentialDefaultHue = 0.349065850399f; // 20 deg
115
116 void IsoluminantSequential(int n, unsigned char* colormap,
117         float luminance = IsoluminantSequentialDefaultLuminance,
118         float saturation = IsoluminantSequentialDefaultSaturation,
119         float hue = IsoluminantSequentialDefaultHue);
120
121 // Create a diverging isoluminant color map with n colors.
122
123 const float IsoluminantDivergingDefaultLuminance = 0.5f;
124 const float IsoluminantDivergingDefaultSaturation = 0.5f;
125 const float IsoluminantDivergingDefaultHue = 0.349065850399f; // 20 deg
126 const float IsoluminantDivergingDefaultDivergence = 4.18879020479f; // 2/3 * 2PI
127
128 void IsoluminantDiverging(int n, unsigned char* colormap,
129         float luminance = IsoluminantDivergingDefaultLuminance,
130         float saturation = IsoluminantDivergingDefaultSaturation,
131         float hue = IsoluminantDivergingDefaultHue,
132         float divergence = IsoluminantDivergingDefaultDivergence);
133
134 // Create a qualitative isoluminant color map with n colors.
135
136 const float IsoluminantQualitativeDefaultLuminance = 0.5f;
137 const float IsoluminantQualitativeDefaultSaturation = 0.35f;
138 const float IsoluminantQualitativeDefaultHue = 0.0f;
139 const float IsoluminantQualitativeDefaultDivergence = 4.18879020479f; // 2/3 * 2PI
140
141 void IsoluminantQualitative(int n, unsigned char* colormap,
142         float luminance = IsoluminantQualitativeDefaultLuminance,
143         float saturation = IsoluminantQualitativeDefaultSaturation,
144         float hue = IsoluminantQualitativeDefaultHue,
145         float divergence = IsoluminantQualitativeDefaultDivergence);
146
147 /*
148  * CubeHelix color maps, as described in
149  * Green, D. A., 2011, A colour scheme for the display of astronomical intensity
150  * images, Bulletin of the Astronomical Society of India, 39, 289.
151  */
152
153 // Create a CubeHelix colormap with n colors. The parameter hue (in [0,2*PI])
154 // sets the hue of the first color. The parameter rot sets the number of
155 // rotations. It can be negative for backwards rotation. The saturation parameter
156 // determines the saturation of the colors; higher values may lead to clipping
157 // of colors in the sRGB space. The gamma parameter sets optional gamma correction.
158 // The return value is the number of colors that had to be clipped.
159
160 const float CubeHelixDefaultHue = 0.523598775598f; // 1/12 * 2PI
161 const float CubeHelixDefaultRotations = -1.5f;
162 const float CubeHelixDefaultSaturation = 1.2f;
163 const float CubeHelixDefaultGamma = 1.0f;
164
165 int CubeHelix(int n, unsigned char* colormap,
166         float hue = CubeHelixDefaultHue,
167         float rotations = CubeHelixDefaultRotations,
168         float saturation = CubeHelixDefaultSaturation,
169         float gamma = CubeHelixDefaultGamma);
170
171 /*
172  * Moreland color maps, as described in
173  * K. Moreland, Diverging Color Maps for Scientific Visualization, Proc. Int.
174  * Symp. Visual Computing, December 2009, DOI 10.1007/978-3-642-10520-3_9.
175  */
176
177 // Create a Moreland colormap with n colors. Specify the two endpoints
178 // of the colormap as sRGB colors; all intermediate colors will be generated.
179
180 const unsigned char MorelandDefaultR0 = 180;
181 const unsigned char MorelandDefaultG0 = 4;
182 const unsigned char MorelandDefaultB0 = 38;
183 const unsigned char MorelandDefaultR1 = 59;
184 const unsigned char MorelandDefaultG1 = 76;
185 const unsigned char MorelandDefaultB1 = 192;
186
187 void Moreland(int n, unsigned char* colormap,
188         unsigned char sr0 = MorelandDefaultR0,
189         unsigned char sg0 = MorelandDefaultG0,
190         unsigned char sb0 = MorelandDefaultB0,
191         unsigned char sr1 = MorelandDefaultR1,
192         unsigned char sg1 = MorelandDefaultG1,
193         unsigned char sb1 = MorelandDefaultB1);
194
195 /*
196  * McNames color maps, as described in
197  * J. McNames, An Effective Color Scale for Simultaneous Color and Gray-Scale Publications,
198  * IEEE Signal Processing Magazine 23(1), January 2006, DOI 10.1109/MSP.2006.1593340.
199  *
200  * Note: Use CubeHelix instead! The McNames color maps are perceptually not linear in luminance!
201  */
202
203 // Create a McNames colormap with n colors. Specify the number of
204 // periods.
205
206 const float McNamesDefaultPeriods = 2.0f;
207
208 void McNames(int n, unsigned char* colormap,
209         float periods = McNamesDefaultPeriods);
210
211 }
212
213 #endif