text: /*=========================================================================
  
    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.
  
  =========================================================================*/
  /**
   * @class   vtkNamedColors
   * @brief   A class holding colors and their names.
   *
   * vtkNamedColors is class that holds colors and their associated names.
   *
   * 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
   * 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.
   *
   * 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:
   * http://www.vtk.org/Wiki/VTK/Examples/Python/Visualization/VTKNamedColorPatches_html .
   *
   * The code used to generate this table is available from:
   * http://www.vtk.org/Wiki/VTK/Examples/Python/Visualization/NamedColorPatches ,
   * this is useful if you wish to generate your own table.
   *
   * 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.
   *
   * In the case of the GetColor methods returning doubles, alternative versions,
   * identified by the letters RGB in the names, are provided.
   * These get functions return just the red, green and blue components of
   * a color.
   *
   * 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")
  */
  
  #ifndef vtkNamedColors_h
  #define vtkNamedColors_h
  
  #include "vtkCommonColorModule.h" // For export macro
  #include "vtkObject.h"
  #include "vtkColor.h" // Needed for vtkColor[34]ub
  #include "vtkStdString.h" // Needed for arguments
  #include "vtkStringArray.h" // For returning color names
  
  class vtkNamedColorsDataStore;
  class vtkColorStringParser;
  
  class VTKCOMMONCOLOR_EXPORT vtkNamedColors : public vtkObject
  {
  public:
    vtkTypeMacro(vtkNamedColors, vtkObject);
  
    /**
     * 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.
     */
    void PrintSelf(ostream& os, vtkIndent indent) VTK_OVERRIDE;
  
    /**
     * Create a new vtkNamedColors object.
     */
    static vtkNamedColors* New();
  
    /**
     * Get the number of colors.
     */
    int GetNumberOfColors();
  
    /**
     * Reset the colors in the color map to the original colors.
     * Any colors inserted by the user will be lost.
     */
    void ResetColors();
  
    /**
     * Return true if the color exists.
     */
    bool ColorExists(const vtkStdString & name);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * The color is returned as a vtkColor4ub class.
     * The color black is returned if the color is not found.
     */
    vtkColor4ub GetColor4ub(const vtkStdString & name);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * The color is returned as four unsigned char variables:
     * 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);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * The color is returned as an unsigned char array:
     * [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]);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * 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);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * The color is returned as a vtkColor4d class.
     * The color black is returned if the color is not found.
     */
    vtkColor4d GetColor4d(const vtkStdString & name);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * The color is returned as four double variables:
     * 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);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * The color is returned as a double array:
     * [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]);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * 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);
  
    /**
     * 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);
  
    /**
     * 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.
     */
    vtkColor3d GetColor3d(const vtkStdString & name);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * The color is returned as three double variables:
     * red, green, blue. 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);
  
    /**
     * Get the color by name.
     * The name is treated as being case-insensitive.
     * The color is returned as a double array:
     * [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]);
  
    /**
     * 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);
  
    /**
     * 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);
  
    /**
     * 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.
     */
    virtual void SetColor(const vtkStdString & name,
                  const unsigned char & r, const unsigned char & g,
                  const unsigned char & b, const unsigned char & a = 255);
  
    /**
     * 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.
     */
    virtual void SetColor(const vtkStdString & name,
                  const double & r, const double & g,
                  const double & b, const double & a = 1);
  
    /**
     * 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.
     */
    virtual void SetColor(const vtkStdString & name, const unsigned char rgba[4]);
  
    /**
     * Set the color by name.
     * The name is treated as being case-insensitive.
     * The color is a vtkColor4ub class.
     * No color is set if the name is empty.
     */
    virtual void SetColor(const vtkStdString & name, const vtkColor4ub & rgba);
  
    /**
     * 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.
     */
    virtual void SetColor(const vtkStdString & name, const vtkColor3ub & rgb);
  
    /**
     * 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.
     */
    virtual void SetColor(const vtkStdString & name, const double rgba[4]);
  
    /**
     * 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.
     */
    virtual void SetColor(const vtkStdString & name, const vtkColor4d & rgba);
  
    /**
     * 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.
     */
    virtual void SetColor(const vtkStdString & name, const vtkColor3d & rgb);
  
    /**
     * Remove the color by name.
     * The name is treated as being case-insensitive.
     * Examples for parsing are provided in:
     * TestNamedColors.cxx and TestNamedColorsIntegration.py
     */
    void RemoveColor(const vtkStdString & name);
  
    /**
     * 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
     */
    vtkStdString GetColorNames();
  
    /**
     * Return a string array of color names.
     */
    void GetColorNames(vtkStringArray * colorNames);
  
    /**
     * Return a string of synonyms such as
     * cyan/aqua and magenta/fuchsia.
     * The string is formatted such that a single line feed delimits
     * each color in the synonym and a double line feed delimits each
     * synonym.
     * Warning this could take a long time for very large color maps.
     * This is easily parsed by the user into whatever
     * data structure they require.
     */
    vtkStdString GetSynonyms();
  
    /**
     * 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);
  
    /**
     * 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);
  
    /**
     * Given a vtkColor3ub instance as input color return a valid HTML color
     * string in the `#RRGGBB` format.
     */
    vtkStdString RGBToHTMLColor(const vtkColor3ub & rgb);
  
    /**
     * 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);
  
    /**
     * 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);
  
  protected:
    vtkNamedColors();
    ~vtkNamedColors() VTK_OVERRIDE;
  
  private:
    //@{
    /**
     * The implementation of the color map and other required methods.
     */
    vtkNamedColorsDataStore *Colors;
    vtkColorStringParser* Parser;
    //@}
  
    vtkNamedColors(const vtkNamedColors&) VTK_DELETE_FUNCTION;
    void operator=(const vtkNamedColors&) VTK_DELETE_FUNCTION;
  };
  
  #endif /* vtkNamedColors_h */
  