vtkNamedColors.h 11.8 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/*=========================================================================

  Program:   Visualization Toolkit
  Module:    vtkNamedColors.h

  Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
  All rights reserved.
  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.

     This software is distributed WITHOUT ANY WARRANTY; without even
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     PURPOSE.  See the above copyright notice for more information.

=========================================================================*/
// .NAME vtkNamedColors - A class holding colors and their names.
// .SECTION Description
// vtkNamedColors is class that holds colors and their associated names.
18
19
20
21
22
23
24
25
26
27
//
// Color names are case insensitive and are stored as lower-case names
// along with a 4-element array whose elements are red, green, blue and alpha,
// in that order, corresponding to the RGBA value of the color.
//
// It is assumed that if the RGBA values are unsigned char then each element
// lies in the range 0...255 and if the RGBA values are double then each
// element lies in the range 0...1.
//
// The colors and names are those in http://en.wikipedia.org/wiki/Web_colors
28
29
30
31
32
// that are derived from the CSS3 specification:
// http://www.w3.org/TR/css3-color/#svg-color
// In this table common synonyms such as cyan/aqua and
// magenta/fuchsia are also included.
//
33
34
35
36
37
38
39
40
41
// Also included in this class are names and colors taken from
// Wrapping/Tcl/vtktesting/colors.tcl and Wrapping/Python/vtk/util/colors.py.
//
// Web colors and names in http://en.wikipedia.org/wiki/Web_colors take
// precedence over those in colors.tcl and colors.py. One consequence of this
// is that while colors.py and colors.tcl specify green as equivalent to
// (0,255,0), the web color standard defines it as (0,128,0).
//
// For a web page of VTK Named Colors and their RGB values, see:
42
// http://www.vtk.org/Wiki/VTK/Examples/Python/Visualization/VTKNamedColorPatches_html .
43
44
//
// The code used to generate this table is available from:
45
// http://www.vtk.org/Wiki/VTK/Examples/Python/Visualization/NamedColorPatches ,
46
// this is useful if you wish to generate your own table.
47
//
48
49
50
// The SetColor methods will overwrite existing colors if the name of the
// color being set matches an existing color. Note that ColorExists() can be
// used to test for existence of the color being set.
51
//
52
// In the case of the GetColor methods returning doubles, alternative versions,
53
54
55
56
57
58
59
60
61
// identified by the letters RGB in the names, are provided.
// These get functions return just the red, green and blue components of
// a color.

#ifndef __vtkNamedColors_h
#define __vtkNamedColors_h

#include "vtkCommonColorModule.h" // For export macro
#include "vtkObject.h"
Andrew Maclean's avatar
Andrew Maclean committed
62
63
64
#include "vtkColor.h" // Needed for vtkColor[34]ub
#include "vtkStdString.h" // Needed for arguments
#include "vtkStringArray.h" // For returning color names
65
66
67
68
69
70
71

class vtkNamedColorsDataStore;

class VTKCOMMONCOLOR_EXPORT vtkNamedColors : public vtkObject
{
public:
  vtkTypeMacro(vtkNamedColors, vtkObject);
Andrew Maclean's avatar
Andrew Maclean committed
72

73
  // Description:
Andrew Maclean's avatar
Andrew Maclean committed
74
75
76
77
  // Methods invoked by print to print information about the object
  // including superclasses. Typically not called by the user
  // (use Print() instead) but used in the hierarchical print
  // process to combine the output of several classes.
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
  virtual void PrintSelf(ostream &os, vtkIndent indent);

  // Description:
  // Create a new vtkNamedColors object.
  static vtkNamedColors* New();

  // Description:
  // Get the number of colors.
  int GetNumberOfColors();

  // Description:
  // Reset the colors in the color map to the original colors.
  // Any colors inserted by the user will be lost.
  void ResetColors();

  // Description:
  // Return true if the color exists.
  bool ColorExists(const vtkStdString & name);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
100
  // The color is returned as a vtkColor4ub class.
101
  // The color black is returned if the color is not found.
Andrew Maclean's avatar
Andrew Maclean committed
102
  vtkColor4ub GetColor4ub(const vtkStdString & name);
103
104
105
106

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
107
  // The color is returned as four unsigned char variables:
108
109
110
111
112
113
114
115
116
  // red, green, blue, alpha. The range of each element is 0...255.
  // The color black is returned if the color is not found.
  void GetColor(const vtkStdString & name,
                unsigned char & r, unsigned char & g,
                unsigned char & b, unsigned char & a);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
117
  // The color is returned as an unsigned char array:
118
119
120
121
122
123
124
  // [red, green, blue, alpha]. The range of each element is 0...255.
  // The color black is returned if the color is not found.
  void GetColor(const vtkStdString & name, unsigned char rgba[4]);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
125
126
127
128
129
130
131
132
  // The color is returned as a vtkColor4ub class.
  // The color black is returned if the color is not found.
  void GetColor(const vtkStdString & name, vtkColor4ub & rgba);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
  // The color is returned as a vtkColor4d class.
133
  // The color black is returned if the color is not found.
Andrew Maclean's avatar
Andrew Maclean committed
134
  vtkColor4d GetColor4d(const vtkStdString & name);
135
136
137
138

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
139
  // The color is returned as four double variables:
140
141
142
143
144
145
146
147
  // red, green, blue, alpha. The range of each element is 0...1.
  // The color black is returned if the color is not found.
  void GetColor(const vtkStdString & name,
                double & r, double & g, double & b, double & a);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
148
  // The color is returned as a double array:
149
150
151
152
153
154
155
  // [red, green, blue, alpha]. The range of each element is 0...1.
  // The color black is returned if the color is not found.
  void GetColor(const vtkStdString & name, double rgba[4]);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
  // The color is returned as a vtkColor4d class.
  // The color black is returned if the color is not found.
  void GetColor(const vtkStdString & name, vtkColor4d & rgba);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
  // The color is returned as a vtkColor3ub class.
  // The color black is returned if the color is not found.
  vtkColor3ub GetColor3ub(const vtkStdString & name);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
  // The color is returned as a vtkColor3d class.
171
  // The color black is returned if the color is not found.
Andrew Maclean's avatar
Andrew Maclean committed
172
  vtkColor3d GetColor3d(const vtkStdString & name);
173
174
175
176

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
177
  // The color is returned as three double variables:
178
179
  // red, green, blue. The range of each element is 0...1.
  // The color black is returned if the color is not found.
Andrew Maclean's avatar
Andrew Maclean committed
180
  void GetColor(const vtkStdString & name,
181
182
183
184
185
                   double & r, double & g, double & b);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
186
  // The color is returned as a double array:
187
188
189
190
  // [red, green, blue]. The range of each element is 0...1.
  // The color black is returned if the color is not found.
  void GetColorRGB(const vtkStdString & name, double rgb[3]);

Andrew Maclean's avatar
Andrew Maclean committed
191
192
193
194
195
196
197
198
199
200
201
202
203
204
  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
  // The color is returned as a vtkColor3ub class.
  // The color black is returned if the color is not found.
  void GetColor(const vtkStdString & name, vtkColor3ub & rgb);

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
  // The color is returned as a vtkColor3d class.
  // The color black is returned if the color is not found.
  void GetColor(const vtkStdString & name, vtkColor3d & rgb);

205
206
207
208
209
  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
  // The range of each color is 0...255.
  // No color is set if the name is empty.
210
  virtual void SetColor(const vtkStdString & name,
211
212
213
                const unsigned char & r, const unsigned char & g,
                const unsigned char & b, const unsigned char & a = 255);

Andrew Maclean's avatar
Andrew Maclean committed
214
215
216
217
218
  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
  // The range of each color is 0...1.
  // No color is set if the name is empty.
219
  virtual void SetColor(const vtkStdString & name,
Andrew Maclean's avatar
Andrew Maclean committed
220
221
222
                const double & r, const double & g,
                const double & b, const double & a = 1);

223
224
225
226
227
228
229
  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
  // The color is an unsigned char array:
  // [red, green, blue, alpha]. The range of each element is 0...255.
  // The user must ensure that the color array size is 4.
  // No color is set if the name is empty.
230
  virtual void SetColor(const vtkStdString & name, const unsigned char rgba[4]);
231
232
233
234

  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
235
  // The color is a vtkColor4ub class.
Andrew Maclean's avatar
Andrew Maclean committed
236
  // No color is set if the name is empty.
237
  virtual void SetColor(const vtkStdString & name, const vtkColor4ub & rgba);
Andrew Maclean's avatar
Andrew Maclean committed
238
239
240
241
242
243

  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
  // The color is a vtkColor3ub class.
  // No color is set if the name is empty.
244
  virtual void SetColor(const vtkStdString & name, const vtkColor3ub & rgb);
245
246
247
248
249
250
251

  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
  // The color is a double array:
  // [red, green, blue, alpha]. The range of each element is 0...1.
  // No color is set if the name is empty.
252
  virtual void SetColor(const vtkStdString & name, const double rgba[4]);
253

Andrew Maclean's avatar
Andrew Maclean committed
254
255
256
257
258
  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
  // The color is a vtkColor4d class.
  // No color is set if the name is empty.
259
  virtual void SetColor(const vtkStdString & name, const vtkColor4d & rgba);
Andrew Maclean's avatar
Andrew Maclean committed
260
261
262
263
264
265

  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
  // The color is a vtkColor3d class.
  // No color is set if the name is empty.
266
  virtual void SetColor(const vtkStdString & name, const vtkColor3d & rgb);
Andrew Maclean's avatar
Andrew Maclean committed
267

268
269
270
  // Description:
  // Remove the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
271
272
  // Examples for parsing are provided in:
  // TestNamedColors.cxx and TestNamedColorsIntegration.py
273
274
275
  void RemoveColor(const vtkStdString & name);

  // Description:
Andrew Maclean's avatar
Andrew Maclean committed
276
277
278
279
280
281
  // Return a string of color names with each name
  // delimited by a line feed.
  // This is easily parsed by the user into whatever
  // data structure they require.
  // Examples for parsing are provided in:
  // TestNamedColors.cxx and TestNamedColorsIntegration.py
Andrew Maclean's avatar
Andrew Maclean committed
282
283
284
  vtkStdString GetColorNames();

  // Description:
285
  // Return a string array of color names.
Andrew Maclean's avatar
Andrew Maclean committed
286
  void GetColorNames(vtkStringArray * colorNames);
287
288

  //  Description:
Andrew Maclean's avatar
Andrew Maclean committed
289
290
  // Return a string of synonyms such as
  // cyan/aqua and magenta/fuchsia.
291
  // The string is formatted such that a single line feed delimits
Andrew Maclean's avatar
Andrew Maclean committed
292
293
  // each color in the synonym and a double line feed delimits each
  // synonym.
294
  // Warning this could take a long time for very large color maps.
Andrew Maclean's avatar
Andrew Maclean committed
295
296
  // This is easily parsed by the user into whatever
  // data structure they require.
Andrew Maclean's avatar
Andrew Maclean committed
297
  vtkStdString GetSynonyms();
298
299
300
301
302
303
304
305

protected:
  vtkNamedColors();
  virtual ~vtkNamedColors();

private:
  // Description:
  // The implementation of the color map and other required methods.
306
  vtkNamedColorsDataStore *Colors;
307
308
309
310
311
312

  vtkNamedColors(const vtkNamedColors&);  // Not implemented.
  void operator=(const vtkNamedColors&);  // Not implemented.
};

#endif /* __vtkNamedColors_h */