PerceptualColor

PerceptualColor Namespace Reference

Classes

class  AbstractDiagram
 
class  ChromaHueDiagram
 
class  ColorDialog
 
class  ColorPatch
 
class  ColorWheel
 
class  GradientSlider
 
struct  LchaDouble
 
struct  LchDouble
 
class  MultiSpinBox
 
class  MultiSpinBoxSection
 
class  RgbColorSpaceFactory
 
class  WheelColorPicker
 

Typedefs

using QColorFloatType = decltype(std::declval< QColor >().redF())
 
using QListSizeType = decltype(std::declval< QList< int > >().count())
 
using QStringLength = decltype(std::declval< QString >().length())
 
using QStringSize = decltype(std::declval< QString >().size())
 
using Quartet = QGenericMatrix< 1, 4, double >
 
using SquareMatrix3 = QGenericMatrix< 3, 3, double >
 
using Trio = QGenericMatrix< 1, 3, double >
 

Enumerations

enum  ColorModel {
  ColorModel::CielabD50, ColorModel::CielchD50, ColorModel::Hsl360_1_1, ColorModel::Hwb360_1_1,
  ColorModel::Invalid, ColorModel::OklabD65, ColorModel::OklchD65, ColorModel::Rgb1,
  ColorModel::XyzD50, ColorModel::XyzD65
}
 
enum  ColorSchemeType { ColorSchemeType::Light, ColorSchemeType::Dark }
 

Functions

template<int N, int M, typename T , typename... Args>
constexpr QGenericMatrix< N, M, T > createMatrix (Args... args)
 
SquareMatrix3 createSquareMatrix3 (double r0c0, double r0c1, double r0c2, double r1c0, double r1c1, double r1c2, double r2c0, double r2c1, double r2c2)
 
Trio createTrio (double first, double second, double third)
 
int decimalPlaces (const int rangeMax, const int significantFigures)
 
template<typename T = void>
void delayedEventProcessing (unsigned long msecWaitInitially=50, unsigned long msecWaitBetweenEventLoopPasses=50, int numberEventLoopPasses=3)
 
void drawQWidgetStyleSheetAware (QWidget *widget)
 
template<typename T >
QString enumerationToFullString ()
 
template<typename T >
QString enumeratorToFullString (const T &enumerator)
 
template<typename T >
QString enumeratorToString (const T &enumerator)
 
template<typename T >
constexpr quint8 fromFloatingToEightBit (const T &original)
 
QString fromMnemonicToRichText (const QString &mnemonicText)
 
QPair< QString, QStringgetPrefixSuffix (const QString &formatString)
 
std::optional< ColorSchemeTypeguessColorSchemeTypeFromWidget (QWidget *widget)
 
void initializeLibraryResources ()
 
void initializeTranslation (QCoreApplication *instance, std::optional< QStringList > newUiLanguages)
 
std::optional< SquareMatrix3inverseMatrix (const SquareMatrix3 &matrix)
 
template<typename First , typename... T>
bool isIn (First &&first, T &&...t)
 
template<typename A , typename B >
constexpr bool isNearlyEqual (A a, B b)
 
template<typename T >
constexpr bool isNearlyEqual (T a, T b, T epsilon)
 
template<typename T >
constexpr bool isOdd (const T &number)
 
template<typename T >
normalizedAngle360 (T value)
 
template<typename T >
void normalizePolar360 (T &radius, T &angleDegree)
 
QDebug operator<< (QDebug dbg, const PerceptualColor::GenericColor &value)
 
QDebug operator<< (QDebug dbg, const PerceptualColor::LchaDouble &value)
 
QDebug operator<< (QDebug dbg, const PerceptualColor::LchDouble &value)
 
QDebug operator<< (QDebug dbg, const PerceptualColor::MultiSpinBoxSection &value)
 
QDebug operator<< (QDebug dbg, const PerceptualColor::PolarPointF value)
 
QDebug operator<< (QDebug dbg, const PerceptualColor::RgbColor &value)
 
QVersionNumber perceptualColorRunTimeVersion ()
 
template<typename T >
QColor qColorFromRgbDouble (T red, T green, T blue)
 
QIcon qIconFromTheme (const QStringList &names, const QString &fallback, ColorSchemeType type)
 
template<typename T >
constexpr T roundToDigits (T value, int precision)
 
void setTranslation (QCoreApplication *instance, const QStringList &newUiLanguages)
 
qreal standardWheelStepCount (QWheelEvent *event)
 
cmsCIELab toCmsLab (const cmsCIELCh &value)
 
cmsCIELCh toCmsLch (const LchDouble &value)
 
LchDouble toLchDouble (const cmsCIELab &value)
 
LchDouble toLchDouble (const cmsCIELCh &value)
 
QImage transparencyBackground (qreal devicePixelRatioF)
 
Array2D< QColorwcsBasicColors (const QSharedPointer< PerceptualColor::RgbColorSpace > &colorSpace)
 

Variables

constexpr qreal gamutPrecisionCielab = 0.001
 
constexpr qreal gamutPrecisionOklab = gamutPrecisionCielab / 100
 
constexpr int overlap = 2
 
constexpr qreal pageStepAlpha = 10 * singleStepAlpha
 
constexpr int pageStepChroma = 10 * singleStepChroma
 
constexpr int pageStepHue = 10 * singleStepHue
 
constexpr int pageStepLightness = 10 * singleStepLightness
 
constexpr auto pi = M_PI
 
const QString richTextMarker = QStringLiteral(u"<a/>")
 
constexpr qreal scaleFromMinumumSizeHintToSizeHint = 1.2
 
constexpr qreal singleStepAlpha = 0.01
 
constexpr int singleStepChroma = 1
 
constexpr int singleStepHue = 360 / 100
 
constexpr int singleStepLightness = 1
 
constexpr double singleStepOklabc = 0.01
 
constexpr cmsCIEXYZ whitePointD65TwoDegree {0.95047, 1.00000, 1.08883}
 

Detailed Description

The namespace of this library.

All symbols that are provided in this library are encapsulated within this namespace.

Enumeration Type Documentation

◆ ColorModel

Identifiers for color models.

Enumerator
CielabD50 

Cielab color space using a D50 illuminant.

Lightness: [0, 100].
a: unbound.
b: unbound.

CielchD50 

Cielch color space using a D50 illuminant.

Lightness: [0, 100].
Chroma: unbound.
Hue: [0, 360[.

Hsl360_1_1 

A HSL color space.

Hue: [0, 360[.
Saturation: [0, 1].
Lightness: [0, 1].

Hwb360_1_1 

A HWB color space.

Hue: [0, 360[.
Whiteness: [0, 1].
Blackness: [0, 1].

Invalid 

Represents invalid data.

OklabD65 

Oklab color space, which by definition always and exclusively uses a D65 illuminant.

Lightness: [0, 1].
a: unbound.
b: unbound.

OklchD65 

Oklch color space, which by definition always and exclusively uses a D65 illuminant.

Lightness: [0, 1].
Chroma: unbound.
Hue: [0, 360[.

Rgb1 

An Rgb color space.

R: [0, 1].
G: [0, 1].
B: [0, 1].

XyzD50 

Xyz color space using a D50 illuminant.

X: unbound.
Y: [0, 1]. Diffuse white has a luminance (Y) of 1.0
Z: unbound.

XyzD65 

Xzy color space using a D65 illuminant.

X: unbound.
Y: [0, 1]. Diffuse white has a luminance (Y) of 1.0
Z: unbound.

Definition at line 30 of file helperconversion.h.

◆ ColorSchemeType

Represents the appearance of a theme.

Enumerator
Light 

Light theme.

Dark 

Dark theme.

Definition at line 33 of file helper.h.

Function Documentation

◆ decimalPlaces()

int PerceptualColor::decimalPlaces ( const int  rangeMax,
const int  significantFigures 
)

Calculates the required number of decimals to achieve the requested number of significant figures within the given range.

Parameters
rangeMaxThe maximum value of the range [0, rangeMax].
significantFiguresThe requested number of significant figures.
maxRange decimalPlaces(maxRange, 2) decimalPlaces(maxRange, 3) decimalPlaces(maxRange, 4)
1 1 2 3
2 1 2 3
100 0 0 1
255 0 0 1
360 0 0 1
Returns
The number of decimal places after the decimal point (in addition to the whole number part) required to achieve the requested number of significant figures within the given range.

Definition at line 108 of file helpermath.cpp.

◆ enumerationToFullString()

template<typename T >
QString PerceptualColor::enumerationToFullString ( )

The full-qualified C++ identifier as QString.

This can be useful for debugging purposes.

Template Parameters
TThe enumeration.
Precondition
The enumeration type is declared with Q_ENUM or Q_ENUM_NS.
Returns
The full-qualified C++ identifier as QString.

Definition at line 245 of file helper.h.

◆ enumeratorToFullString()

template<typename T >
QString PerceptualColor::enumeratorToFullString ( const T &  enumerator)

The full-qualified C++ identifier as QString.

This can be useful for debugging purposes.

Template Parameters
TThe enumeration type. Can usually be omitted.
Parameters
enumeratorAn enumerator.
Precondition
The enumeration type of the enumerator is declared with Q_ENUM or Q_ENUM_NS.
Returns
The full-qualified C++ identifier as QString, followed by the underlying integer value in parenthesis. If the enumerator does not exist (for example because you have done a static_cast of an invalid integer to the enum class), an empty String is returned instead. If the enumerator has synonyms (that means, there exist other enumerators that share the same integer with the current enumerator), all synonym enumerators are returned.
See also
enumeratorToString()

Definition at line 274 of file helper.h.

◆ enumeratorToString()

template<typename T >
QString PerceptualColor::enumeratorToString ( const T &  enumerator)

The C++ identifier as QString.

This can be useful for debugging purposes.

Template Parameters
TThe enumeration type. Can usually be omitted.
Parameters
enumeratorAn enumerator.
Precondition
The enumeration type of the enumerator is declared with Q_ENUM or Q_ENUM_NS.
Returns
The C++ identifier as QString, followed by the underlying integer value in parenthesis. If the enumerator does not exist (for example because you have done a static_cast of an invalid integer to the enum class), an empty String is returned instead. If the enumerator has synonyms (that means, there exist other enumerators that share the same integer with the current enumerator), all synonym enumerators are returned.
See also
enumeratorToFullString()

Definition at line 316 of file helper.h.

◆ operator<<() [1/3]

PERCEPTUALCOLOR_IMPORTEXPORT QDebug PerceptualColor::operator<< ( QDebug  dbg,
const PerceptualColor::LchaDouble value 
)

Adds QDebug() support for data type PerceptualColor::LchaDouble.

Parameters
dbgExisting debug object
valueValue to stream into the debug object
Returns
Debug object with value streamed in

Definition at line 58 of file lchadouble.cpp.

◆ operator<<() [2/3]

PERCEPTUALCOLOR_IMPORTEXPORT QDebug PerceptualColor::operator<< ( QDebug  dbg,
const PerceptualColor::LchDouble value 
)

Adds QDebug() support for data type PerceptualColor::LchDouble.

Parameters
dbgExisting debug object
valueValue to stream into the debug object
Returns
Debug object with value streamed in

Definition at line 60 of file lchdouble.cpp.

◆ operator<<() [3/3]

PERCEPTUALCOLOR_IMPORTEXPORT QDebug PerceptualColor::operator<< ( QDebug  dbg,
const PerceptualColor::MultiSpinBoxSection value 
)

Adds QDebug() support for data type PerceptualColor::MultiSpinBoxSection.

Parameters
dbgExisting debug object
valueValue to stream into the debug object
Returns
Debug object with value streamed in

Definition at line 245 of file multispinboxsection.cpp.

◆ perceptualColorRunTimeVersion()

PERCEPTUALCOLOR_IMPORTEXPORT QVersionNumber PerceptualColor::perceptualColorRunTimeVersion ( )

Against which version of this library you are running.

Returns
The library version with major, minor and patch version. Note that there is no pre-release identifier included. For example, if your application is running against version 1.2.3-alpha of this library, this function will return QVersionNumber(1, 2, 3).

To use this function, include version.h

See also
Version information at compiletime and runtime

Definition at line 33 of file version.cpp.

◆ setTranslation()

void PERCEPTUALCOLOR_IMPORTEXPORT PerceptualColor::setTranslation ( QCoreApplication instance,
const QStringList newUiLanguages 
)

Set the translation for the whole library.

After calling this function, all objects of this library that are created from now on are translated according to translation that was set.

Objects that were yet existing when calling are not always automatically updated: When calling this function, Qt sends a QEvent::LanguageChange event only to top-level widgets, and these will get updated then. You can send the event yourself to non-top-level widgets to update those widgets also. Note that also RgbColorSpaceFactory generates objects that might have localized properties; these objects do not support translation updates.

If you create objects that use translations before a translation has been set explicitly, than automatically an environment-dependant translation is loaded.

You might call this function again after a change of QLocale() to change the translation. Also, call this function again after destroying the QCoreApplication object and creating a new one.

It is safe to call this function multiple times.

Precondition
There exists exactly one instance of QCoreApplication to which the parameter points. This function is called from the same thread in which the QCoreApplication instance lives.
Parameters
instanceA pointer to the QCoreApplication instance for which the initialization will be done.
newUiLanguagesList of translations, ordered by priority, most important ones first, like in QLocale::uiLanguages().

Definition at line 55 of file settranslation.cpp.

◆ wcsBasicColors()

Array2D< QColor > PerceptualColor::wcsBasicColors ( const QSharedPointer< PerceptualColor::RgbColorSpace > &  colorSpace)

Palette derived from the basic colors as by WCS (World color survey).

The palette contains various tints and shades of the basic colors. The choice of the basic colors is based on the study by Brent Berlin and Paul Kay, who suggest that the basic color terms in almost all languages on earth follow a universal pattern. They propose that there are eleven basic color terms that appear in this order during the evolution of a language:

  1. black, white
  2. red
  3. green, yellow
  4. blue
  5. brown
  6. purple, pink, orange, gray

Additionally, people worldwide seem to agree quite well on the typical values of each of these color terms. This theory is a fascinating one and forms a good basis for choosing basic colors for this palette.

This widget's colors have been arranged largely according to the color wheel of the perceptually uniform color space. We start with the saturated basic colors: red, orange, yellow, green, blue, and purple in order of their hue angles. Next, we have pink and brown, which have roughly the same hue as red or orange but are less saturated. These are simply the less chromatic parts of this hue but are nevertheless perceived by humans as independent colors. For each of these basic colors, there are five variants in the order of tint, pure color, and shade. Following the saturated colors and eventually the less saturated ones, the gray axis comes in last place.

What exact colors are used? What exactly is a typical “red” or a “green”? Doesn’t every human have a slightly different feeling what a “typical” red or a “typical” blue is? We need a focal color, which is, according to Oxford Reference:

“A colour that is a prototypical instance of a particular colour name, such as a shade of red that a majority of viewers consider to be the best example of a red colour.”

The World Color Survey (WCS) is a significant study about focal colors of speakers of different languages across the world. The data from this survey is available online, and while it does not provide direct values for focal colors, various studies have used this data to determine focal colors for some basic color terms and a naming centroid for others.

The table below shows the WCS grid coordinates for the basic color terms along with the corresponding Cielab values for the focal color (where available) or the naming centroid (where focal color data is unavailable).

Basic color term WCS grid coordinates Cielab³ L Cielab³ a Cielab³ b
white¹ A0 96.00 -0.06 0.06
black¹ J0 15.60 -0.02 0.02
red¹ G1 41.22 61.40 17.92
yellow¹ C9 81.35 7.28 109.12
green¹ F17 51.57 -63.28 28.95
blue¹ F29 51.57 -3.41 -48.08
brown³ G7 41.22 17.04 45.95
purple³ G34 41.22 33.08 -30.50
pink³ E1 61.70 49.42 18.23
orange³ E6 61.70 29.38 64.40
gray not available

¹ Focal color as proposed by Focal colors are universal after all.

² Raw estimation of the naming centroid based on Fig. 4 of this document. (Fig. 5 would be the better choice, as it gives the focal color instead of the naming centroid, but unfortunately contains only red, yellow, green and blue, for which we have yet direct data.)

³ Lookup table providing Lab values for WCS grid coordinates and the corresponding explanation.

From this data, the colors in our palette have been derived as follows:

  • The gray axis has been defined manually, ignoring the WCS data. Chroma is 0. The lightness is 100% for white, 0% for black, and 75%, 50%, and 25% for the intermediate grays.
  • The other columns for chromatic colors use the WCS data for the swatch in the middle. Tints and shades are calculated by adding or reducing chroma and lightness within the Oklab color space. If the resulting color falls outside the color space, a nearby in-gamut color is chosen instead.
Parameters
colorSpaceThe color space in which the return value is calculated.
Returns
Palette derived from the basic colors. Provides as a list of basic colors (in this order: red, orange, yellow, green, blue, purple, pink, brown, gray axis). Each basic color is a list of 5 swatches (starting with the lightest and finishing with the darkest: 2 tints, the tone itself, 2 shades).
Note
The RGB value is rounded to full integers in the range [0, 255].

Definition at line 459 of file helper.cpp.

This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Sep 30 2023 03:48:36 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.