Open CASCADE Technology 7.8.2.dev
Quantity_Color Class Reference

This class allows the definition of an RGB color as triplet of 3 normalized floating point values (red, green, blue). More...

#include <Quantity_Color.hxx>

Public Member Functions

 Quantity_Color ()
 Creates Quantity_NOC_YELLOW color (for historical reasons).
 
 Quantity_Color (const Quantity_NameOfColor theName)
 Creates the color from enumeration value.
 
 Quantity_Color (const Standard_Real theC1, const Standard_Real theC2, const Standard_Real theC3, const Quantity_TypeOfColor theType)
 Creates a color according to the definition system theType. Throws exception if values are out of range.
 
 Quantity_Color (const NCollection_Vec3< float > &theRgb)
 Define color from linear RGB values.
 
Quantity_NameOfColor Name () const
 Returns the name of the nearest color from the Quantity_NameOfColor enumeration.
 
void SetValues (const Quantity_NameOfColor theName)
 Updates the color from specified named color.
 
const NCollection_Vec3< float > & Rgb () const
 Return the color as vector of 3 float elements.
 
 operator const NCollection_Vec3< float > & () const
 Return the color as vector of 3 float elements.
 
void Values (Standard_Real &theC1, Standard_Real &theC2, Standard_Real &theC3, const Quantity_TypeOfColor theType) const
 Returns in theC1, theC2 and theC3 the components of this color according to the color system definition theType.
 
void SetValues (const Standard_Real theC1, const Standard_Real theC2, const Standard_Real theC3, const Quantity_TypeOfColor theType)
 Updates a color according to the mode specified by theType. Throws exception if values are out of range.
 
Standard_Real Red () const
 Returns the Red component (quantity of red) of the color within range [0.0; 1.0].
 
Standard_Real Green () const
 Returns the Green component (quantity of green) of the color within range [0.0; 1.0].
 
Standard_Real Blue () const
 Returns the Blue component (quantity of blue) of the color within range [0.0; 1.0].
 
Standard_Real Hue () const
 Returns the Hue component (hue angle) of the color in degrees within range [0.0; 360.0], 0.0 being Red. -1.0 is a special value reserved for grayscale color (S should be 0.0)
 
Standard_Real Light () const
 Returns the Light component (value of the lightness) of the color within range [0.0; 1.0].
 
void ChangeIntensity (const Standard_Real theDelta)
 Increases or decreases the intensity (variation of the lightness). The delta is a percentage. Any value greater than zero will increase the intensity. The variation is expressed as a percentage of the current value.
 
Standard_Real Saturation () const
 Returns the Saturation component (value of the saturation) of the color within range [0.0; 1.0].
 
void ChangeContrast (const Standard_Real theDelta)
 Increases or decreases the contrast (variation of the saturation). The delta is a percentage. Any value greater than zero will increase the contrast. The variation is expressed as a percentage of the current value.
 
Standard_Boolean IsDifferent (const Quantity_Color &theOther) const
 Returns TRUE if the distance between two colors is greater than Epsilon().
 
Standard_Boolean operator!= (const Quantity_Color &theOther) const
 Alias to IsDifferent().
 
Standard_Boolean IsEqual (const Quantity_Color &theOther) const
 Returns TRUE if the distance between two colors is no greater than Epsilon().
 
Standard_Boolean operator== (const Quantity_Color &theOther) const
 Alias to IsEqual().
 
Standard_Real Distance (const Quantity_Color &theColor) const
 Returns the distance between two colors. It's a value between 0 and the square root of 3 (the black/white distance).
 
Standard_Real SquareDistance (const Quantity_Color &theColor) const
 Returns the square of distance between two colors.
 
void Delta (const Quantity_Color &theColor, Standard_Real &DC, Standard_Real &DI) const
 Returns the percentage change of contrast and intensity between this and another color. <DC> and <DI> are percentages, either positive or negative. The calculation is with respect to this color. If <DC> is positive then <me> is more contrasty. If <DI> is positive then <me> is more intense.
 
Standard_Real DeltaE2000 (const Quantity_Color &theOther) const
 Returns the value of the perceptual difference between this color and theOther, computed using the CIEDE2000 formula. The difference is in range [0, 100.], with 1 approximately corresponding to the minimal perceivable difference (usually difference 5 or greater is needed for the difference to be recognizable in practice).
 

Static Public Member Functions

static Quantity_NameOfColor Name (const Standard_Real theR, const Standard_Real theG, const Standard_Real theB)
 Returns the color from Quantity_NameOfColor enumeration nearest to specified RGB values.
 
static Standard_CString StringName (const Quantity_NameOfColor theColor)
 Returns the name of the color identified by the given Quantity_NameOfColor enumeration value.
 
static Standard_Boolean ColorFromName (const Standard_CString theName, Quantity_NameOfColor &theColor)
 Finds color from predefined names. For example, the name of the color which corresponds to "BLACK" is Quantity_NOC_BLACK. Returns FALSE if name is unknown.
 
static Standard_Boolean ColorFromName (const Standard_CString theColorNameString, Quantity_Color &theColor)
 Finds color from predefined names.
 

Routines converting colors between different encodings and color spaces

void DumpJson (Standard_OStream &theOStream, Standard_Integer theDepth=-1) const
 Dumps the content of me into the stream.
 
Standard_Boolean InitFromJson (const Standard_SStream &theSStream, Standard_Integer &theStreamPos)
 Inits the content of me from the stream.
 
static bool ColorFromHex (const Standard_CString theHexColorString, Quantity_Color &theColor)
 Parses the string as a hex color (like "#FF0" for short sRGB color, or "#FFFF00" for sRGB color)
 
static TCollection_AsciiString ColorToHex (const Quantity_Color &theColor, const bool theToPrefixHash=true)
 Returns hex sRGB string in format "#FFAAFF".
 
static NCollection_Vec3< float > Convert_sRGB_To_HLS (const NCollection_Vec3< float > &theRgb)
 Converts sRGB components into HLS ones.
 
static NCollection_Vec3< float > Convert_HLS_To_sRGB (const NCollection_Vec3< float > &theHls)
 Converts HLS components into RGB ones.
 
static NCollection_Vec3< float > Convert_LinearRGB_To_HLS (const NCollection_Vec3< float > &theRgb)
 Converts Linear RGB components into HLS ones.
 
static NCollection_Vec3< float > Convert_HLS_To_LinearRGB (const NCollection_Vec3< float > &theHls)
 Converts HLS components into linear RGB ones.
 
static NCollection_Vec3< float > Convert_LinearRGB_To_Lab (const NCollection_Vec3< float > &theRgb)
 Converts linear RGB components into CIE Lab ones.
 
static NCollection_Vec3< float > Convert_Lab_To_Lch (const NCollection_Vec3< float > &theLab)
 Converts CIE Lab components into CIE Lch ones.
 
static NCollection_Vec3< float > Convert_Lab_To_LinearRGB (const NCollection_Vec3< float > &theLab)
 Converts CIE Lab components into linear RGB ones. Note that the resulting values may be out of the valid range for RGB.
 
static NCollection_Vec3< float > Convert_Lch_To_Lab (const NCollection_Vec3< float > &theLch)
 Converts CIE Lch components into CIE Lab ones.
 
static void Color2argb (const Quantity_Color &theColor, Standard_Integer &theARGB)
 Convert the color value to ARGB integer value, with alpha equals to 0. So the output is formatted as 0x00RRGGBB. Note that this unpacking does NOT involve non-linear sRGB -> linear RGB conversion, as would be usually expected for RGB color packed into 4 bytes.
 
static void Argb2color (const Standard_Integer theARGB, Quantity_Color &theColor)
 Convert integer ARGB value to Color. Alpha bits are ignored. Note that this packing does NOT involve linear -> non-linear sRGB conversion, as would be usually expected to preserve higher (for human eye) color precision in 4 bytes.
 
static Standard_Real Convert_LinearRGB_To_sRGB (Standard_Real theLinearValue)
 Convert linear RGB component into sRGB using OpenGL specs formula (double precision), also known as gamma correction.
 
static float Convert_LinearRGB_To_sRGB (float theLinearValue)
 Convert linear RGB component into sRGB using OpenGL specs formula (single precision), also known as gamma correction.
 
static Standard_Real Convert_sRGB_To_LinearRGB (Standard_Real thesRGBValue)
 Convert sRGB component into linear RGB using OpenGL specs formula (double precision), also known as gamma correction.
 
static float Convert_sRGB_To_LinearRGB (float thesRGBValue)
 Convert sRGB component into linear RGB using OpenGL specs formula (single precision), also known as gamma correction.
 
template<typename T >
static NCollection_Vec3< T > Convert_LinearRGB_To_sRGB (const NCollection_Vec3< T > &theRGB)
 Convert linear RGB components into sRGB using OpenGL specs formula.
 
template<typename T >
static NCollection_Vec3< T > Convert_sRGB_To_LinearRGB (const NCollection_Vec3< T > &theRGB)
 Convert sRGB components into linear RGB using OpenGL specs formula.
 
static float Convert_LinearRGB_To_sRGB_approx22 (float theLinearValue)
 Convert linear RGB component into sRGB using approximated uniform gamma coefficient 2.2.
 
static float Convert_sRGB_To_LinearRGB_approx22 (float thesRGBValue)
 Convert sRGB component into linear RGB using approximated uniform gamma coefficient 2.2.
 
static NCollection_Vec3< float > Convert_LinearRGB_To_sRGB_approx22 (const NCollection_Vec3< float > &theRGB)
 Convert linear RGB components into sRGB using approximated uniform gamma coefficient 2.2.
 
static NCollection_Vec3< float > Convert_sRGB_To_LinearRGB_approx22 (const NCollection_Vec3< float > &theRGB)
 Convert sRGB components into linear RGB using approximated uniform gamma coefficient 2.2.
 
static void HlsRgb (const Standard_Real theH, const Standard_Real theL, const Standard_Real theS, Standard_Real &theR, Standard_Real &theG, Standard_Real &theB)
 Converts HLS components into sRGB ones.
 
static void RgbHls (const Standard_Real theR, const Standard_Real theG, const Standard_Real theB, Standard_Real &theH, Standard_Real &theL, Standard_Real &theS)
 Converts sRGB components into HLS ones.
 
static Standard_Real Epsilon ()
 Returns the value used to compare two colors for equality; 0.0001 by default.
 
static void SetEpsilon (const Standard_Real theEpsilon)
 Set the value used to compare two colors for equality.
 

Detailed Description

This class allows the definition of an RGB color as triplet of 3 normalized floating point values (red, green, blue).

Although Quantity_Color can be technically used for pass-through storage of RGB triplet in any color space, other OCCT interfaces taking/returning Quantity_Color would expect them in linear space. Therefore, take a look into methods converting to and from non-linear sRGB color space, if needed; for instance, application usually providing color picking within 0..255 range in sRGB color space.

Constructor & Destructor Documentation

◆ Quantity_Color() [1/4]

Quantity_Color::Quantity_Color ( )
inline

Creates Quantity_NOC_YELLOW color (for historical reasons).

◆ Quantity_Color() [2/4]

Quantity_Color::Quantity_Color ( const Quantity_NameOfColor theName)
inline

Creates the color from enumeration value.

◆ Quantity_Color() [3/4]

Quantity_Color::Quantity_Color ( const Standard_Real theC1,
const Standard_Real theC2,
const Standard_Real theC3,
const Quantity_TypeOfColor theType )

Creates a color according to the definition system theType. Throws exception if values are out of range.

◆ Quantity_Color() [4/4]

Quantity_Color::Quantity_Color ( const NCollection_Vec3< float > & theRgb)
explicit

Define color from linear RGB values.

Member Function Documentation

◆ Argb2color()

static void Quantity_Color::Argb2color ( const Standard_Integer theARGB,
Quantity_Color & theColor )
inlinestatic

Convert integer ARGB value to Color. Alpha bits are ignored. Note that this packing does NOT involve linear -> non-linear sRGB conversion, as would be usually expected to preserve higher (for human eye) color precision in 4 bytes.

◆ Blue()

Standard_Real Quantity_Color::Blue ( ) const
inline

Returns the Blue component (quantity of blue) of the color within range [0.0; 1.0].

◆ ChangeContrast()

void Quantity_Color::ChangeContrast ( const Standard_Real theDelta)

Increases or decreases the contrast (variation of the saturation). The delta is a percentage. Any value greater than zero will increase the contrast. The variation is expressed as a percentage of the current value.

◆ ChangeIntensity()

void Quantity_Color::ChangeIntensity ( const Standard_Real theDelta)

Increases or decreases the intensity (variation of the lightness). The delta is a percentage. Any value greater than zero will increase the intensity. The variation is expressed as a percentage of the current value.

◆ Color2argb()

static void Quantity_Color::Color2argb ( const Quantity_Color & theColor,
Standard_Integer & theARGB )
inlinestatic

Convert the color value to ARGB integer value, with alpha equals to 0. So the output is formatted as 0x00RRGGBB. Note that this unpacking does NOT involve non-linear sRGB -> linear RGB conversion, as would be usually expected for RGB color packed into 4 bytes.

Parameters
theColor[in] color to convert
theARGB[out] result color encoded as integer

◆ ColorFromHex()

static bool Quantity_Color::ColorFromHex ( const Standard_CString theHexColorString,
Quantity_Color & theColor )
static

Parses the string as a hex color (like "#FF0" for short sRGB color, or "#FFFF00" for sRGB color)

Parameters
theHexColorStringthe string to be parsed
theColora color that is a result of parsing
Returns
true if parsing was successful, or false otherwise

◆ ColorFromName() [1/2]

static Standard_Boolean Quantity_Color::ColorFromName ( const Standard_CString theColorNameString,
Quantity_Color & theColor )
inlinestatic

Finds color from predefined names.

Parameters
theColorNameStringthe color name
theColora found color
Returns
false if the color name is unknown, or true if the search by color name was successful

◆ ColorFromName() [2/2]

static Standard_Boolean Quantity_Color::ColorFromName ( const Standard_CString theName,
Quantity_NameOfColor & theColor )
static

Finds color from predefined names. For example, the name of the color which corresponds to "BLACK" is Quantity_NOC_BLACK. Returns FALSE if name is unknown.

◆ ColorToHex()

static TCollection_AsciiString Quantity_Color::ColorToHex ( const Quantity_Color & theColor,
const bool theToPrefixHash = true )
inlinestatic

Returns hex sRGB string in format "#FFAAFF".

◆ Convert_HLS_To_LinearRGB()

static NCollection_Vec3< float > Quantity_Color::Convert_HLS_To_LinearRGB ( const NCollection_Vec3< float > & theHls)
inlinestatic

Converts HLS components into linear RGB ones.

◆ Convert_HLS_To_sRGB()

static NCollection_Vec3< float > Quantity_Color::Convert_HLS_To_sRGB ( const NCollection_Vec3< float > & theHls)
static

Converts HLS components into RGB ones.

◆ Convert_Lab_To_Lch()

static NCollection_Vec3< float > Quantity_Color::Convert_Lab_To_Lch ( const NCollection_Vec3< float > & theLab)
static

Converts CIE Lab components into CIE Lch ones.

◆ Convert_Lab_To_LinearRGB()

static NCollection_Vec3< float > Quantity_Color::Convert_Lab_To_LinearRGB ( const NCollection_Vec3< float > & theLab)
static

Converts CIE Lab components into linear RGB ones. Note that the resulting values may be out of the valid range for RGB.

◆ Convert_Lch_To_Lab()

static NCollection_Vec3< float > Quantity_Color::Convert_Lch_To_Lab ( const NCollection_Vec3< float > & theLch)
static

Converts CIE Lch components into CIE Lab ones.

◆ Convert_LinearRGB_To_HLS()

static NCollection_Vec3< float > Quantity_Color::Convert_LinearRGB_To_HLS ( const NCollection_Vec3< float > & theRgb)
inlinestatic

Converts Linear RGB components into HLS ones.

◆ Convert_LinearRGB_To_Lab()

static NCollection_Vec3< float > Quantity_Color::Convert_LinearRGB_To_Lab ( const NCollection_Vec3< float > & theRgb)
static

Converts linear RGB components into CIE Lab ones.

◆ Convert_LinearRGB_To_sRGB() [1/3]

template<typename T >
static NCollection_Vec3< T > Quantity_Color::Convert_LinearRGB_To_sRGB ( const NCollection_Vec3< T > & theRGB)
inlinestatic

Convert linear RGB components into sRGB using OpenGL specs formula.

◆ Convert_LinearRGB_To_sRGB() [2/3]

static float Quantity_Color::Convert_LinearRGB_To_sRGB ( float theLinearValue)
inlinestatic

Convert linear RGB component into sRGB using OpenGL specs formula (single precision), also known as gamma correction.

◆ Convert_LinearRGB_To_sRGB() [3/3]

static Standard_Real Quantity_Color::Convert_LinearRGB_To_sRGB ( Standard_Real theLinearValue)
inlinestatic

Convert linear RGB component into sRGB using OpenGL specs formula (double precision), also known as gamma correction.

◆ Convert_LinearRGB_To_sRGB_approx22() [1/2]

static NCollection_Vec3< float > Quantity_Color::Convert_LinearRGB_To_sRGB_approx22 ( const NCollection_Vec3< float > & theRGB)
inlinestatic

Convert linear RGB components into sRGB using approximated uniform gamma coefficient 2.2.

◆ Convert_LinearRGB_To_sRGB_approx22() [2/2]

static float Quantity_Color::Convert_LinearRGB_To_sRGB_approx22 ( float theLinearValue)
inlinestatic

Convert linear RGB component into sRGB using approximated uniform gamma coefficient 2.2.

◆ Convert_sRGB_To_HLS()

static NCollection_Vec3< float > Quantity_Color::Convert_sRGB_To_HLS ( const NCollection_Vec3< float > & theRgb)
static

Converts sRGB components into HLS ones.

◆ Convert_sRGB_To_LinearRGB() [1/3]

template<typename T >
static NCollection_Vec3< T > Quantity_Color::Convert_sRGB_To_LinearRGB ( const NCollection_Vec3< T > & theRGB)
inlinestatic

Convert sRGB components into linear RGB using OpenGL specs formula.

◆ Convert_sRGB_To_LinearRGB() [2/3]

static float Quantity_Color::Convert_sRGB_To_LinearRGB ( float thesRGBValue)
inlinestatic

Convert sRGB component into linear RGB using OpenGL specs formula (single precision), also known as gamma correction.

◆ Convert_sRGB_To_LinearRGB() [3/3]

static Standard_Real Quantity_Color::Convert_sRGB_To_LinearRGB ( Standard_Real thesRGBValue)
inlinestatic

Convert sRGB component into linear RGB using OpenGL specs formula (double precision), also known as gamma correction.

◆ Convert_sRGB_To_LinearRGB_approx22() [1/2]

static NCollection_Vec3< float > Quantity_Color::Convert_sRGB_To_LinearRGB_approx22 ( const NCollection_Vec3< float > & theRGB)
inlinestatic

Convert sRGB components into linear RGB using approximated uniform gamma coefficient 2.2.

◆ Convert_sRGB_To_LinearRGB_approx22() [2/2]

static float Quantity_Color::Convert_sRGB_To_LinearRGB_approx22 ( float thesRGBValue)
inlinestatic

Convert sRGB component into linear RGB using approximated uniform gamma coefficient 2.2.

◆ Delta()

void Quantity_Color::Delta ( const Quantity_Color & theColor,
Standard_Real & DC,
Standard_Real & DI ) const

Returns the percentage change of contrast and intensity between this and another color. <DC> and <DI> are percentages, either positive or negative. The calculation is with respect to this color. If <DC> is positive then <me> is more contrasty. If <DI> is positive then <me> is more intense.

◆ DeltaE2000()

Standard_Real Quantity_Color::DeltaE2000 ( const Quantity_Color & theOther) const

Returns the value of the perceptual difference between this color and theOther, computed using the CIEDE2000 formula. The difference is in range [0, 100.], with 1 approximately corresponding to the minimal perceivable difference (usually difference 5 or greater is needed for the difference to be recognizable in practice).

◆ Distance()

Standard_Real Quantity_Color::Distance ( const Quantity_Color & theColor) const
inline

Returns the distance between two colors. It's a value between 0 and the square root of 3 (the black/white distance).

◆ DumpJson()

void Quantity_Color::DumpJson ( Standard_OStream & theOStream,
Standard_Integer theDepth = -1 ) const

Dumps the content of me into the stream.

◆ Epsilon()

static Standard_Real Quantity_Color::Epsilon ( )
static

Returns the value used to compare two colors for equality; 0.0001 by default.

◆ Green()

Standard_Real Quantity_Color::Green ( ) const
inline

Returns the Green component (quantity of green) of the color within range [0.0; 1.0].

◆ HlsRgb()

static void Quantity_Color::HlsRgb ( const Standard_Real theH,
const Standard_Real theL,
const Standard_Real theS,
Standard_Real & theR,
Standard_Real & theG,
Standard_Real & theB )
inlinestatic

Converts HLS components into sRGB ones.

◆ Hue()

Standard_Real Quantity_Color::Hue ( ) const
inline

Returns the Hue component (hue angle) of the color in degrees within range [0.0; 360.0], 0.0 being Red. -1.0 is a special value reserved for grayscale color (S should be 0.0)

◆ InitFromJson()

Standard_Boolean Quantity_Color::InitFromJson ( const Standard_SStream & theSStream,
Standard_Integer & theStreamPos )

Inits the content of me from the stream.

◆ IsDifferent()

Standard_Boolean Quantity_Color::IsDifferent ( const Quantity_Color & theOther) const
inline

Returns TRUE if the distance between two colors is greater than Epsilon().

◆ IsEqual()

Standard_Boolean Quantity_Color::IsEqual ( const Quantity_Color & theOther) const
inline

Returns TRUE if the distance between two colors is no greater than Epsilon().

◆ Light()

Standard_Real Quantity_Color::Light ( ) const
inline

Returns the Light component (value of the lightness) of the color within range [0.0; 1.0].

◆ Name() [1/2]

Quantity_NameOfColor Quantity_Color::Name ( ) const

Returns the name of the nearest color from the Quantity_NameOfColor enumeration.

◆ Name() [2/2]

static Quantity_NameOfColor Quantity_Color::Name ( const Standard_Real theR,
const Standard_Real theG,
const Standard_Real theB )
inlinestatic

Returns the color from Quantity_NameOfColor enumeration nearest to specified RGB values.

◆ operator const NCollection_Vec3< float > &()

Quantity_Color::operator const NCollection_Vec3< float > & ( ) const
inline

Return the color as vector of 3 float elements.

◆ operator!=()

Standard_Boolean Quantity_Color::operator!= ( const Quantity_Color & theOther) const
inline

Alias to IsDifferent().

◆ operator==()

Standard_Boolean Quantity_Color::operator== ( const Quantity_Color & theOther) const
inline

Alias to IsEqual().

◆ Red()

Standard_Real Quantity_Color::Red ( ) const
inline

Returns the Red component (quantity of red) of the color within range [0.0; 1.0].

◆ Rgb()

const NCollection_Vec3< float > & Quantity_Color::Rgb ( ) const
inline

Return the color as vector of 3 float elements.

◆ RgbHls()

static void Quantity_Color::RgbHls ( const Standard_Real theR,
const Standard_Real theG,
const Standard_Real theB,
Standard_Real & theH,
Standard_Real & theL,
Standard_Real & theS )
inlinestatic

Converts sRGB components into HLS ones.

◆ Saturation()

Standard_Real Quantity_Color::Saturation ( ) const
inline

Returns the Saturation component (value of the saturation) of the color within range [0.0; 1.0].

◆ SetEpsilon()

static void Quantity_Color::SetEpsilon ( const Standard_Real theEpsilon)
static

Set the value used to compare two colors for equality.

◆ SetValues() [1/2]

void Quantity_Color::SetValues ( const Quantity_NameOfColor theName)
inline

Updates the color from specified named color.

◆ SetValues() [2/2]

void Quantity_Color::SetValues ( const Standard_Real theC1,
const Standard_Real theC2,
const Standard_Real theC3,
const Quantity_TypeOfColor theType )

Updates a color according to the mode specified by theType. Throws exception if values are out of range.

◆ SquareDistance()

Standard_Real Quantity_Color::SquareDistance ( const Quantity_Color & theColor) const
inline

Returns the square of distance between two colors.

◆ StringName()

static Standard_CString Quantity_Color::StringName ( const Quantity_NameOfColor theColor)
static

Returns the name of the color identified by the given Quantity_NameOfColor enumeration value.

◆ Values()

void Quantity_Color::Values ( Standard_Real & theC1,
Standard_Real & theC2,
Standard_Real & theC3,
const Quantity_TypeOfColor theType ) const

Returns in theC1, theC2 and theC3 the components of this color according to the color system definition theType.


The documentation for this class was generated from the following file: