vtkNamedColors.h 14 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
// identified by the letters RGB in the names, are provided.
// These get functions return just the red, green and blue components of
// a color.
56 57 58 59 60 61 62 63 64
//
// The class also provides methods for defining a color through an HTML color
// string. The following formats are supported:
//
// - #RGB                  (3-digit hexadecimal number, where #4F2 is a shortcut for #44FF22)
// - #RRGGBB               (6-digit hexadecimal number)
// - rgb(r, g, b)          (where r, g, b are in 0..255 or percentage values)
// - rgba(r, g, b, a)      (where r, g, b, are in 0..255 or percentage values, a is in 0.0..1.0)
// - a CSS3 color name     (e.g. "steelblue")
65

66 67
#ifndef vtkNamedColors_h
#define vtkNamedColors_h
68 69 70

#include "vtkCommonColorModule.h" // For export macro
#include "vtkObject.h"
Andrew Maclean's avatar
Andrew Maclean committed
71 72 73
#include "vtkColor.h" // Needed for vtkColor[34]ub
#include "vtkStdString.h" // Needed for arguments
#include "vtkStringArray.h" // For returning color names
74 75

class vtkNamedColorsDataStore;
76
class vtkColorStringParser;
77 78 79 80 81

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

83
  // Description:
Andrew Maclean's avatar
Andrew Maclean committed
84 85 86 87
  // 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.
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
  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
110
  // The color is returned as a vtkColor4ub class.
111
  // The color black is returned if the color is not found.
Andrew Maclean's avatar
Andrew Maclean committed
112
  vtkColor4ub GetColor4ub(const vtkStdString & name);
113 114 115 116

  // 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 four unsigned char variables:
118 119 120 121 122 123 124 125 126
  // 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
127
  // The color is returned as an unsigned char array:
128 129 130 131 132 133 134
  // [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
135 136 137 138 139 140 141 142
  // 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.
143
  // The color black is returned if the color is not found.
Andrew Maclean's avatar
Andrew Maclean committed
144
  vtkColor4d GetColor4d(const vtkStdString & name);
145 146 147 148

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
149
  // The color is returned as four double variables:
150 151 152 153 154 155 156 157
  // 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
158
  // The color is returned as a double array:
159 160 161 162 163 164 165
  // [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
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180
  // 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.
181
  // The color black is returned if the color is not found.
Andrew Maclean's avatar
Andrew Maclean committed
182
  vtkColor3d GetColor3d(const vtkStdString & name);
183 184 185 186

  // Description:
  // Get the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
187
  // The color is returned as three double variables:
188 189
  // 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
190
  void GetColor(const vtkStdString & name,
191 192 193 194 195
                   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
196
  // The color is returned as a double array:
197 198 199 200
  // [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
201 202 203 204 205 206 207 208 209 210 211 212 213 214
  // 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);

215 216 217 218 219
  // 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.
220
  virtual void SetColor(const vtkStdString & name,
221 222 223
                const unsigned char & r, const unsigned char & g,
                const unsigned char & b, const unsigned char & a = 255);

Andrew Maclean's avatar
Andrew Maclean committed
224 225 226 227 228
  // 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.
229
  virtual void SetColor(const vtkStdString & name,
Andrew Maclean's avatar
Andrew Maclean committed
230 231 232
                const double & r, const double & g,
                const double & b, const double & a = 1);

233 234 235 236 237 238 239
  // 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.
240
  virtual void SetColor(const vtkStdString & name, const unsigned char rgba[4]);
241 242 243 244

  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
245
  // The color is a vtkColor4ub class.
Andrew Maclean's avatar
Andrew Maclean committed
246
  // No color is set if the name is empty.
247
  virtual void SetColor(const vtkStdString & name, const vtkColor4ub & rgba);
Andrew Maclean's avatar
Andrew Maclean committed
248 249 250 251 252 253

  // 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.
254
  virtual void SetColor(const vtkStdString & name, const vtkColor3ub & rgb);
255 256 257 258 259 260 261

  // 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.
262
  virtual void SetColor(const vtkStdString & name, const double rgba[4]);
263

Andrew Maclean's avatar
Andrew Maclean committed
264 265 266 267 268
  // 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.
269
  virtual void SetColor(const vtkStdString & name, const vtkColor4d & rgba);
Andrew Maclean's avatar
Andrew Maclean committed
270 271 272 273 274 275

  // 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.
276
  virtual void SetColor(const vtkStdString & name, const vtkColor3d & rgb);
Andrew Maclean's avatar
Andrew Maclean committed
277

278 279 280
  // Description:
  // Remove the color by name.
  // The name is treated as being case-insensitive.
Andrew Maclean's avatar
Andrew Maclean committed
281 282
  // Examples for parsing are provided in:
  // TestNamedColors.cxx and TestNamedColorsIntegration.py
283 284 285
  void RemoveColor(const vtkStdString & name);

  // Description:
Andrew Maclean's avatar
Andrew Maclean committed
286 287 288 289 290 291
  // 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
292 293 294
  vtkStdString GetColorNames();

  // Description:
295
  // Return a string array of color names.
Andrew Maclean's avatar
Andrew Maclean committed
296
  void GetColorNames(vtkStringArray * colorNames);
297 298

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

309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339
  // Description:
  // Return a vtkColor4ub instance from an HTML color string in any of
  // the following formats:
  // - #RGB
  // - #RRGGBB
  // - rgb(r, g, b)
  // - rgba(r, g, b, a)
  // - a CSS3 color name, e.g. "steelblue"
  // If the string argument defines a color using one of the above formats
  // the method returns the successfully parsed color else returns a color
  // equal to `rgba(0, 0, 0, 0)`.
  vtkColor4ub HTMLColorToRGBA(const vtkStdString& colorString);

  // Description:
  // Return a vtkColor3ub instance from an HTML color string in any of
  // the following formats:
  // - #RGB
  // - #RRGGBB
  // - rgb(r, g, b)
  // - rgba(r, g, b, a)
  // - a CSS3 color name, e.g. "steelblue"
  // If the string argument defines a color using one of the above formats
  // the method returns the successfully parsed color else returns the color
  // black.
  vtkColor3ub HTMLColorToRGB(const vtkStdString& colorString);

  // Description:
  // Given a vtkColor3ub instance as input color return a valid HTML color
  // string in the `#RRGGBB` format.
  vtkStdString RGBToHTMLColor(const vtkColor3ub & rgb);

340 341 342 343 344
  // Description:
  // Given a vtkColor4ub instance as input color return a valid HTML color
  // string in the `rgba(r, g, b, a)` format.
  vtkStdString RGBAToHTMLColor(const vtkColor4ub & rgba);

345 346 347 348 349 350 351 352
  // Description:
  // Set the color by name.
  // The name is treated as being case-insensitive.
  // The color must be a valid HTML color string.
  // No color is set if the name is empty or if `htmlString` is not a valid
  // HTML color string.
  void SetColor(const vtkStdString & name, const vtkStdString & htmlString);

353 354 355 356 357 358 359
protected:
  vtkNamedColors();
  virtual ~vtkNamedColors();

private:
  // Description:
  // The implementation of the color map and other required methods.
360
  vtkNamedColorsDataStore *Colors;
361
  vtkColorStringParser* Parser;
362

363
  vtkNamedColors(const vtkNamedColors&) VTK_DELETE_FUNCTION;
364
  void operator=(const vtkNamedColors&) VTK_DELETE_FUNCTION;
365 366
};

367
#endif /* vtkNamedColors_h */