src/Quantity/Quantity_Color.hxx

   1 // Created by: NW,JPB,CAL
   2 // Copyright (c) 1991-1999 Matra Datavision
   3 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _Quantity_Color_HeaderFile
  17 #define _Quantity_Color_HeaderFile
  18
  19 #include <Standard.hxx>
  20 #include <Standard_DefineAlloc.hxx>
  21 #include <Standard_Handle.hxx>
  22 #include <Standard_ShortReal.hxx>
  23
  24 #include <Quantity_NameOfColor.hxx>
  25 #include <Quantity_TypeOfColor.hxx>
  26 #include <TCollection_AsciiString.hxx>
  27 #include <NCollection_Vec4.hxx>
  28 class Quantity_ColorDefinitionError;
  29
  30
  31 //! This class allows the definition of a colour.
  32 //! The names of the colours are from the X11 specification.
  33 //! color object may be used for numerous applicative purposes.
  34 //! A color is defined by:
  35 //! -   its respective quantities of red, green and blue (R-G-B values), or
  36 //! -   its hue angle and its values of lightness and  saturation (H-L-S values).
  37 //! These two color definition systems are equivalent.
  38 //! Use this class in conjunction with:
  39 //! -   the Quantity_TypeOfColor enumeration
  40 //! which identifies the color definition system you are using,
  41 //! -   the Quantity_NameOfColor enumeration
  42 //! which lists numerous predefined colors and
  43 //! identifies them by their name.
  44 class Quantity_Color
  45 {
  46 public:
  47
  48   DEFINE_STANDARD_ALLOC
  49
  50
  51   //! Creates Quantity_NOC_YELLOW color.
  52   Standard_EXPORT Quantity_Color();
  53
  54   //! Creates the color from enumeration value.
  55   Standard_EXPORT Quantity_Color(const Quantity_NameOfColor AName);
  56
  57   //! Creates a color according to the definition system theType.
  58   //! Quantity_TOC_RGB:
  59   //!  - theR1 the value of Red   within range [0.0; 1.0]
  60   //!  - theR2 the value of Green within range [0.0; 1.0]
  61   //!  - theR3 the value of Blue  within range [0.0; 1.0]
  62   //!
  63   //! Quantity_TOC_HLS:
  64   //!  - theR1 is the Hue (H) angle in degrees within range [0.0; 360.0], 0.0 being Red.
  65   //!    Value -1.0 is a special value reserved for grayscale color (S should be 0.0).
  66   //!  - theR2 is the Lightness  (L) within range [0.0; 1.0]
  67   //!  - theR3 is the Saturation (S) within range [0.0; 1.0]
  68   Standard_EXPORT Quantity_Color (const Standard_Real theR1,
  69                                   const Standard_Real theR2,
  70                                   const Standard_Real theR3,
  71                                   const Quantity_TypeOfColor theType);
  72
  73   //! Define color from RGB values.
  74   Standard_EXPORT explicit Quantity_Color (const NCollection_Vec3<float>& theRgb);
  75
  76   //! Increases or decreases the contrast by <ADelta>.
  77   //! <ADelta> is a percentage. Any value greater than zero
  78   //! will increase the contrast.
  79   //! The variation is expressed as a percentage of the
  80   //! current value.
  81   //! It is a variation of the saturation.
  82   Standard_EXPORT void ChangeContrast (const Standard_Real ADelta);
  83
  84   //! Increases or decreases the intensity by <ADelta>.
  85   //! <ADelta> is a percentage. Any value greater than zero
  86   //! will increase the intensity.
  87   //! The variation is expressed as a percentage of the
  88   //! current value.
  89   //! It is a variation of the lightness.
  90   Standard_EXPORT void ChangeIntensity (const Standard_Real ADelta);
  91
  92   //! Updates the colour <me> from the definition of the
  93   //! colour <AName>.
  94   Standard_EXPORT void SetValues (const Quantity_NameOfColor AName);
  95
  96   //! Updates a color according to the mode specified by theType.
  97   //! Quantity_TOC_RGB:
  98   //!  - theR1 the value of Red   within range [0.0; 1.0]
  99   //!  - theR2 the value of Green within range [0.0; 1.0]
 100   //!  - theR3 the value of Blue  within range [0.0; 1.0]
 101   //!
 102   //! Quantity_TOC_HLS:
 103   //!  - theR1 is the Hue (H) angle in degrees within range [0.0; 360.0], 0.0 being Red.
 104   //!    -1.0 is a special value reserved for grayscale color (S should be 0.0).
 105   //!  - theR2 is the Lightness  (L) within range [0.0; 1.0]
 106   //!  - theR3 is the Saturation (S) within range [0.0; 1.0]
 107   Standard_EXPORT void SetValues (const Standard_Real theR1,
 108                                   const Standard_Real theR2,
 109                                   const Standard_Real theR3,
 110                                   const Quantity_TypeOfColor theType);
 111
 112   //! Returns the percentage change of contrast and intensity
 113   //! between <me> and <AColor>.
 114   //! <DC> and <DI> are percentages, either positive or negative.
 115   //! The calculation is with respect to the current value of <me>
 116   //! If <DC> is positive then <me> is more contrasty.
 117   //! If <DI> is positive then <me> is more intense.
 118   Standard_EXPORT void Delta (const Quantity_Color& AColor, Standard_Real& DC, Standard_Real& DI) const;
 119
 120   //! Returns the distance between two colours. It's a
 121   //! value between 0 and the square root of 3
 122   //! (the black/white distance)
 123   Standard_EXPORT Standard_Real Distance (const Quantity_Color& AColor) const;
 124
 125   //! Returns the square of distance between two colours.
 126   Standard_EXPORT Standard_Real SquareDistance (const Quantity_Color& AColor) const;
 127
 128   //! Returns the Blue component (quantity of blue) of the color within range [0.0; 1.0].
 129   Standard_EXPORT Standard_Real Blue() const;
 130
 131   //! Returns the Green component (quantity of green) of the color within range [0.0; 1.0].
 132   Standard_EXPORT Standard_Real Green() const;
 133
 134   //! Returns the Hue component (hue angle) of the color
 135   //! in degrees within range [0.0; 360.0], 0.0 being Red.
 136   //! -1.0 is a special value reserved for grayscale color (S should be 0.0)
 137   Standard_EXPORT Standard_Real Hue() const;
 138
 139   //! Returns Standard_True if the distance between <me> and
 140   //! <Other> is greater than Epsilon ().
 141   Standard_EXPORT Standard_Boolean IsDifferent (const Quantity_Color& Other) const;
 142 Standard_Boolean operator != (const Quantity_Color& Other) const
 143 {
 144   return IsDifferent(Other);
 145 }
 146
 147   //! Returns true if the Other color is
 148   //! -   different from, or
 149   //! -   equal to this color.
 150   //! Two colors are considered to be equal if their
 151   //! distance is no greater than Epsilon().
 152   //! These methods are aliases of operator != and operator ==.
 153   Standard_EXPORT Standard_Boolean IsEqual (const Quantity_Color& Other) const;
 154 Standard_Boolean operator == (const Quantity_Color& Other) const
 155 {
 156   return IsEqual(Other);
 157 }
 158
 159   //! Returns the Light component (value of the lightness) of the color within range [0.0; 1.0].
 160   Standard_EXPORT Standard_Real Light() const;
 161
 162   //! Returns the name of the color defined by its
 163   //! quantities of red R, green G and blue B; more
 164   //! precisely this is the nearest color from the
 165   //! Quantity_NameOfColor enumeration.
 166   //! Exceptions
 167   //! Standard_OutOfRange if R, G or B is less than 0. or greater than 1.
 168   Standard_EXPORT Quantity_NameOfColor Name() const;
 169
 170   //! Returns the Red component (quantity of red) of the color within range [0.0; 1.0].
 171   Standard_EXPORT Standard_Real Red() const;
 172
 173   //! Returns the Saturation component (value of the saturation) of the color within range [0.0; 1.0].
 174   Standard_EXPORT Standard_Real Saturation() const;
 175
 176   //! Return the color as vector of 3 float elements.
 177   operator const NCollection_Vec3<float>&() const { return *(const NCollection_Vec3<float>* )this; }
 178
 179   //! Returns in theR1, theR2 and theR3 the components of this color according to the color system definition theType.
 180   //! If theType is Quantity_TOC_RGB:
 181   //!  - theR1 the value of Red   between 0.0 and 1.0
 182   //!  - theR2 the value of Green between 0.0 and 1.0
 183   //!  - theR3 the value of Blue  between 0.0 and 1.0
 184   //! If theType is Quantity_TOC_HLS:
 185   //!  - theR1 is the Hue (H) angle in degrees within range [0.0; 360.0], 0.0 being Red.
 186   //!    -1.0 is a special value reserved for grayscale color (S should be 0.0).
 187   //!  - theR2 is the Lightness  (L) within range [0.0; 1.0]
 188   //!  - theR3 is the Saturation (S) within range [0.0; 1.0]
 189   Standard_EXPORT void Values (Standard_Real& theR1,
 190                                Standard_Real& theR2,
 191                                Standard_Real& theR3,
 192                                const Quantity_TypeOfColor theType) const;
 193
 194   //! Sets the specified value used to compare <me> and
 195   //! an other color in IsDifferent and in IsEqual methods.
 196   //! Warning: The default value is 0.0001
 197   Standard_EXPORT static void SetEpsilon (const Standard_Real AnEpsilon);
 198
 199   //! Returns the specified value used to compare <me> and
 200   //! an other color in IsDifferent and in IsEqual methods.
 201   Standard_EXPORT static Standard_Real Epsilon();
 202
 203   //! Returns the name of the colour for which the RGB components
 204   //! are nearest to <R>, <G> and <B>.
 205   Standard_EXPORT static Quantity_NameOfColor Name (const Standard_Real R, const Standard_Real G, const Standard_Real B);
 206
 207   //! Returns the name of the color identified by
 208   //! AName in the Quantity_NameOfColor enumeration.
 209   //! For example, the name of the color which
 210   //! corresponds to Quantity_NOC_BLACK is "BLACK".
 211   //! Exceptions
 212   //! Standard_OutOfRange if AName in not known
 213   //! in the Quantity_NameOfColor enumeration.
 214   Standard_EXPORT static Standard_CString StringName (const Quantity_NameOfColor AColor);
 215
 216   //! Finds color from predefined names.
 217   //! For example, the name of the color which
 218   //! corresponds to "BLACK" is Quantity_NOC_BLACK.
 219   //! Returns false if name is unknown.
 220   Standard_EXPORT static Standard_Boolean ColorFromName (const Standard_CString theName, Quantity_NameOfColor& theColor);
 221
 222   //! Finds color from predefined names.
 223   //! For example, the name of the color which
 224   //! corresponds to "BLACK" is Quantity_NOC_BLACK.
 225   //! Returns false if name is unknown.
 226   //! @param theColorNameString the color name
 227   //! @param theColor a found color
 228   //! @return false if the color name is unknown, or true if the search by color name was successful
 229   static Standard_Boolean ColorFromName (const Standard_CString theColorNameString, Quantity_Color& theColor)
 230   {
 231     Quantity_NameOfColor aColorName = Quantity_NOC_BLACK;
 232     if (!ColorFromName (theColorNameString, aColorName))
 233     {
 234       return false;
 235     }
 236     theColor = aColorName;
 237     return true;
 238   }
 239
 240   //! Parses the string as a hex color (like "#FF0" for short RGB color, or "#FFFF00" for RGB color)
 241   //! @param theHexColorString the string to be parsed
 242   //! @param theColor a color that is a result of parsing
 243   //! @return true if parsing was successful, or false otherwise
 244   Standard_EXPORT static bool ColorFromHex (const Standard_CString theHexColorString, Quantity_Color& theColor);
 245
 246   //! Returns hex sRGB string in format "#FFAAFF".
 247   static TCollection_AsciiString ColorToHex (const Quantity_Color& theColor,
 248                                              const bool theToPrefixHash = true)
 249   {
 250     NCollection_Vec3<Standard_ShortReal> anSRgb = (NCollection_Vec3<Standard_ShortReal> )theColor;
 251     NCollection_Vec3<Standard_Integer> anSRgbInt (anSRgb * 255.0f + NCollection_Vec3<Standard_ShortReal> (0.5f));
 252     char aBuff[10];
 253     Sprintf (aBuff, theToPrefixHash ? "#%02X%02X%02X" : "%02X%02X%02X",
 254              anSRgbInt.r(), anSRgbInt.g(), anSRgbInt.b());
 255     return aBuff;
 256   }
 257
 258   //! Converts HLS components into RGB ones.
 259   Standard_EXPORT static void HlsRgb (const Standard_Real H, const Standard_Real L, const Standard_Real S, Standard_Real& R, Standard_Real& G, Standard_Real& B);
 260
 261   //! Converts RGB components into HLS ones.
 262   Standard_EXPORT static void RgbHls (const Standard_Real R, const Standard_Real G, const Standard_Real B, Standard_Real& H, Standard_Real& L, Standard_Real& S);
 263
 264   //! Convert the Color value to ARGB integer value.
 265   //! theARGB has Alpha equal to zero, so the output is
 266   //! formatted as 0x00RRGGBB
 267   Standard_EXPORT static void Color2argb (const Quantity_Color& theColor, Standard_Integer& theARGB);
 268
 269   //! Convert integer ARGB value to Color. Alpha bits are ignored
 270   Standard_EXPORT static void Argb2color (const Standard_Integer theARGB, Quantity_Color& theColor);
 271
 272   //! Internal test
 273   Standard_EXPORT static void Test();
 274
 275   //! Dumps the content of me into the stream
 276   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, const Standard_Integer theDepth = -1) const;
 277
 278 private:
 279
 280   //! Converts HLS components into RGB ones.
 281   Standard_EXPORT static void hlsrgb (const Standard_ShortReal H, const Standard_ShortReal L, const Standard_ShortReal S, Standard_ShortReal& R, Standard_ShortReal& G, Standard_ShortReal& B);
 282
 283   //! Converts RGB components into HLS ones.
 284   Standard_EXPORT static void rgbhls (const Standard_ShortReal R, const Standard_ShortReal G, const Standard_ShortReal B, Standard_ShortReal& H, Standard_ShortReal& L, Standard_ShortReal& S);
 285
 286   //! Returns the values of a predefined colour according to
 287   //! the mode specified by TypeOfColor
 288   //! TOC_RGB : <R1> the value of red between 0. and 1.
 289   //! <R2> the value of green between 0. and 1.
 290   //! <R3> the value of blue between 0. and 1.
 291   //!
 292   //! TOC_HLS : <R1> is the hue angle in degrees, 0. being red
 293   //! <R2> is the lightness between 0. and 1.
 294   //! <R3> is the saturation between 0. and 1.
 295   Standard_EXPORT static void ValuesOf (const Quantity_NameOfColor AName, const Quantity_TypeOfColor AType, Standard_ShortReal& R1, Standard_ShortReal& R2, Standard_ShortReal& R3);
 296
 297
 298   Standard_ShortReal MyRed;
 299   Standard_ShortReal MyGreen;
 300   Standard_ShortReal MyBlue;
 301
 302 };
 303
 304 #endif // _Quantity_Color_HeaderFile