Open CASCADE Technology Reference Manual 8.0.0
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions
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 double theC1, const double theC2, const double 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) noexcept
 Updates the color from specified named color.
 
constexpr const NCollection_Vec3< float > & Rgb () const noexcept
 Return the color as vector of 3 float elements.
 
constexpr operator const NCollection_Vec3< float > & () const noexcept
 Return the color as vector of 3 float elements.
 
void Values (double &theC1, double &theC2, double &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 double theC1, const double theC2, const double theC3, const Quantity_TypeOfColor theType)
 Updates a color according to the mode specified by theType. Throws exception if values are out of range.
 
constexpr double Red () const noexcept
 Returns the Red component (quantity of red) of the color within range [0.0; 1.0].
 
constexpr double Green () const noexcept
 Returns the Green component (quantity of green) of the color within range [0.0; 1.0].
 
constexpr double Blue () const noexcept
 Returns the Blue component (quantity of blue) of the color within range [0.0; 1.0].
 
double Hue () const noexcept
 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)
 
double Light () const noexcept
 Returns the Light component (value of the lightness) of the color within range [0.0; 1.0].
 
void ChangeIntensity (const double 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.
 
double Saturation () const noexcept
 Returns the Saturation component (value of the saturation) of the color within range [0.0; 1.0].
 
void ChangeContrast (const double 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.
 
bool IsDifferent (const Quantity_Color &theOther) const noexcept
 Returns TRUE if the distance between two colors is greater than Epsilon().
 
bool operator!= (const Quantity_Color &theOther) const noexcept
 Alias to IsDifferent().
 
bool IsEqual (const Quantity_Color &theOther) const noexcept
 Returns TRUE if the distance between two colors is no greater than Epsilon().
 
bool operator== (const Quantity_Color &theOther) const noexcept
 Alias to IsEqual().
 
double Distance (const Quantity_Color &theColor) const noexcept
 Returns the distance between two colors. It's a value between 0 and the square root of 3 (the black/white distance).
 
double SquareDistance (const Quantity_Color &theColor) const noexcept
 Returns the square of distance between two colors.
 
void Delta (const Quantity_Color &theColor, double &DC, double &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.
 
double 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 double theR, const double theG, const double theB)
 Returns the color from Quantity_NameOfColor enumeration nearest to specified RGB values.
 
static const charStringName (const Quantity_NameOfColor theColor) noexcept
 Returns the name of the color identified by the given Quantity_NameOfColor enumeration value.
 
static bool ColorFromName (const char *const theName, Quantity_NameOfColor &theColor) noexcept
 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 bool ColorFromName (const char *const theColorNameString, Quantity_Color &theColor) noexcept
 Finds color from predefined names.
 

Routines converting colors between different encodings and color spaces

void DumpJson (Standard_OStream &theOStream, int theDepth=-1) const
 Dumps the content of me into the stream.
 
bool InitFromJson (const Standard_SStream &theSStream, int &theStreamPos)
 Inits the content of me from the stream.
 
static bool ColorFromHex (const char *const 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) noexcept
 Returns hex sRGB string in format "#FFAAFF".
 
static NCollection_Vec3< floatConvert_sRGB_To_HLS (const NCollection_Vec3< float > &theRgb) noexcept
 Converts sRGB components into HLS ones.
 
static NCollection_Vec3< floatConvert_HLS_To_sRGB (const NCollection_Vec3< float > &theHls)
 Converts HLS components into RGB ones.
 
static NCollection_Vec3< floatConvert_LinearRGB_To_HLS (const NCollection_Vec3< float > &theRgb) noexcept
 Converts Linear RGB components into HLS ones.
 
static NCollection_Vec3< floatConvert_HLS_To_LinearRGB (const NCollection_Vec3< float > &theHls) noexcept
 Converts HLS components into linear RGB ones.
 
static NCollection_Vec3< floatConvert_LinearRGB_To_Lab (const NCollection_Vec3< float > &theRgb) noexcept
 Converts linear RGB components into CIE Lab ones.
 
static NCollection_Vec3< floatConvert_Lab_To_Lch (const NCollection_Vec3< float > &theLab) noexcept
 Converts CIE Lab components into CIE Lch ones.
 
static NCollection_Vec3< floatConvert_Lab_To_LinearRGB (const NCollection_Vec3< float > &theLab) noexcept
 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< floatConvert_Lch_To_Lab (const NCollection_Vec3< float > &theLch) noexcept
 Converts CIE Lch components into CIE Lab ones.
 
static constexpr void Color2argb (const Quantity_Color &theColor, int &theARGB) noexcept
 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 int theARGB, Quantity_Color &theColor) noexcept
 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 double Convert_LinearRGB_To_sRGB (double theLinearValue) noexcept
 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) noexcept
 Convert linear RGB component into sRGB using OpenGL specs formula (single precision), also known as gamma correction.
 
static double Convert_sRGB_To_LinearRGB (double thesRGBValue) noexcept
 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) noexcept
 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) noexcept
 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) noexcept
 Convert sRGB components into linear RGB using OpenGL specs formula.
 
static float Convert_LinearRGB_To_sRGB_approx22 (float theLinearValue) noexcept
 Convert linear RGB component into sRGB using approximated uniform gamma coefficient 2.2.
 
static float Convert_sRGB_To_LinearRGB_approx22 (float thesRGBValue) noexcept
 Convert sRGB component into linear RGB using approximated uniform gamma coefficient 2.2.
 
static NCollection_Vec3< floatConvert_LinearRGB_To_sRGB_approx22 (const NCollection_Vec3< float > &theRGB) noexcept
 Convert linear RGB components into sRGB using approximated uniform gamma coefficient 2.2.
 
static NCollection_Vec3< floatConvert_sRGB_To_LinearRGB_approx22 (const NCollection_Vec3< float > &theRGB) noexcept
 Convert sRGB components into linear RGB using approximated uniform gamma coefficient 2.2.
 
static void HlsRgb (const double theH, const double theL, const double theS, double &theR, double &theG, double &theB) noexcept
 Converts HLS components into sRGB ones.
 
static void RgbHls (const double theR, const double theG, const double theB, double &theH, double &theL, double &theS) noexcept
 Converts sRGB components into HLS ones.
 
static double Epsilon () noexcept
 Returns the value used to compare two colors for equality; 0.0001 by default.
 
static void SetEpsilon (const double theEpsilon) noexcept
 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 double theC1,
const double theC2,
const double 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 int theARGB,
Quantity_Color & theColor )
inlinestaticnoexcept

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()

constexpr double Quantity_Color::Blue ( ) const
inlineconstexprnoexcept

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

◆ ChangeContrast()

void Quantity_Color::ChangeContrast ( const double 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 double 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 constexpr void Quantity_Color::Color2argb ( const Quantity_Color & theColor,
int & theARGB )
inlinestaticconstexprnoexcept

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
[in]theColorcolor to convert
[out]theARGBresult color encoded as integer

◆ ColorFromHex()

static bool Quantity_Color::ColorFromHex ( const char *const 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 bool Quantity_Color::ColorFromName ( const char *const theColorNameString,
Quantity_Color & theColor )
inlinestaticnoexcept

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 bool Quantity_Color::ColorFromName ( const char *const theName,
Quantity_NameOfColor & theColor )
staticnoexcept

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 )
inlinestaticnoexcept

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)
inlinestaticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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)
staticnoexcept

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)
inlinestaticnoexcept

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)
staticnoexcept

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)
inlinestaticnoexcept

Convert linear RGB components into sRGB using OpenGL specs formula.

◆ Convert_LinearRGB_To_sRGB() [2/3]

static double Quantity_Color::Convert_LinearRGB_To_sRGB ( double theLinearValue)
inlinestaticnoexcept

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

◆ Convert_LinearRGB_To_sRGB() [3/3]

static float Quantity_Color::Convert_LinearRGB_To_sRGB ( float theLinearValue)
inlinestaticnoexcept

Convert linear RGB component into sRGB using OpenGL specs formula (single 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)
inlinestaticnoexcept

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)
inlinestaticnoexcept

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)
staticnoexcept

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)
inlinestaticnoexcept

Convert sRGB components into linear RGB using OpenGL specs formula.

◆ Convert_sRGB_To_LinearRGB() [2/3]

static double Quantity_Color::Convert_sRGB_To_LinearRGB ( double thesRGBValue)
inlinestaticnoexcept

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

◆ Convert_sRGB_To_LinearRGB() [3/3]

static float Quantity_Color::Convert_sRGB_To_LinearRGB ( float thesRGBValue)
inlinestaticnoexcept

Convert sRGB component into linear RGB using OpenGL specs formula (single 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)
inlinestaticnoexcept

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)
inlinestaticnoexcept

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

◆ Delta()

void Quantity_Color::Delta ( const Quantity_Color & theColor,
double & DC,
double & 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()

double 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()

double Quantity_Color::Distance ( const Quantity_Color & theColor) const
inlinenoexcept

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,
int theDepth = -1 ) const

Dumps the content of me into the stream.

◆ Epsilon()

static double Quantity_Color::Epsilon ( )
staticnoexcept

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

◆ Green()

constexpr double Quantity_Color::Green ( ) const
inlineconstexprnoexcept

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

◆ HlsRgb()

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

Converts HLS components into sRGB ones.

◆ Hue()

double Quantity_Color::Hue ( ) const
inlinenoexcept

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()

bool Quantity_Color::InitFromJson ( const Standard_SStream & theSStream,
int & theStreamPos )

Inits the content of me from the stream.

◆ IsDifferent()

bool Quantity_Color::IsDifferent ( const Quantity_Color & theOther) const
inlinenoexcept

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

◆ IsEqual()

bool Quantity_Color::IsEqual ( const Quantity_Color & theOther) const
inlinenoexcept

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

◆ Light()

double Quantity_Color::Light ( ) const
inlinenoexcept

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 double theR,
const double theG,
const double theB )
inlinestatic

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

◆ operator const NCollection_Vec3< float > &()

constexpr Quantity_Color::operator const NCollection_Vec3< float > & ( ) const
inlineconstexprnoexcept

Return the color as vector of 3 float elements.

◆ operator!=()

bool Quantity_Color::operator!= ( const Quantity_Color & theOther) const
inlinenoexcept

Alias to IsDifferent().

◆ operator==()

bool Quantity_Color::operator== ( const Quantity_Color & theOther) const
inlinenoexcept

Alias to IsEqual().

◆ Red()

constexpr double Quantity_Color::Red ( ) const
inlineconstexprnoexcept

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

◆ Rgb()

constexpr const NCollection_Vec3< float > & Quantity_Color::Rgb ( ) const
inlineconstexprnoexcept

Return the color as vector of 3 float elements.

◆ RgbHls()

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

Converts sRGB components into HLS ones.

◆ Saturation()

double Quantity_Color::Saturation ( ) const
inlinenoexcept

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

◆ SetEpsilon()

static void Quantity_Color::SetEpsilon ( const double theEpsilon)
staticnoexcept

Set the value used to compare two colors for equality.

◆ SetValues() [1/2]

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

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

◆ SetValues() [2/2]

void Quantity_Color::SetValues ( const Quantity_NameOfColor theName)
inlinenoexcept

Updates the color from specified named color.

◆ SquareDistance()

double Quantity_Color::SquareDistance ( const Quantity_Color & theColor) const
inlinenoexcept

Returns the square of distance between two colors.

◆ StringName()

static const char * Quantity_Color::StringName ( const Quantity_NameOfColor theColor)
staticnoexcept

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

◆ Values()

void Quantity_Color::Values ( double & theC1,
double & theC2,
double & 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: