QCPColorGradient
Public Types | |
enum | ColorInterpolation { ciRGB , ciHSV } |
enum | GradientPreset { gpGrayscale , gpHot , gpCold , gpNight , gpCandy , gpGeography , gpIon , gpThermal , gpPolar , gpSpectrum , gpJet , gpHues } |
enum | NanHandling { nhNone , nhLowestColor , nhHighestColor , nhTransparent , nhNanColor } |
Public Member Functions | |
QCPColorGradient () | |
QCPColorGradient (GradientPreset preset) | |
void | clearColorStops () |
QRgb | color (double position, const QCPRange &range, bool logarithmic=false) |
ColorInterpolation | colorInterpolation () const |
void | colorize (const double *data, const QCPRange &range, QRgb *scanLine, int n, int dataIndexFactor=1, bool logarithmic=false) |
void | colorize (const double *data, const unsigned char *alpha, const QCPRange &range, QRgb *scanLine, int n, int dataIndexFactor=1, bool logarithmic=false) |
QMap< double, QColor > | colorStops () const |
QCPColorGradient | inverted () const |
int | levelCount () const |
void | loadPreset (GradientPreset preset) |
QColor | nanColor () const |
NanHandling | nanHandling () const |
bool | operator!= (const QCPColorGradient &other) const |
bool | operator== (const QCPColorGradient &other) const |
bool | periodic () const |
void | setColorInterpolation (ColorInterpolation interpolation) |
void | setColorStopAt (double position, const QColor &color) |
void | setColorStops (const QMap< double, QColor > &colorStops) |
void | setLevelCount (int n) |
void | setNanColor (const QColor &color) |
void | setNanHandling (NanHandling handling) |
void | setPeriodic (bool enabled) |
Protected Member Functions | |
bool | stopsUseAlpha () const |
void | updateColorBuffer () |
Protected Attributes | |
QVector< QRgb > | mColorBuffer |
bool | mColorBufferInvalidated |
ColorInterpolation | mColorInterpolation |
QMap< double, QColor > | mColorStops |
int | mLevelCount |
QColor | mNanColor |
NanHandling | mNanHandling |
bool | mPeriodic |
Detailed Description
Defines a color gradient for use with e.g. QCPColorMap.
This class describes a color gradient which can be used to encode data with color. For example, QCPColorMap and QCPColorScale have setGradient methods which take an instance of this class. Colors are set with setColorStopAt(double position, const QColor &color) with a position from 0 to 1. In between these defined color positions, the color will be interpolated linearly either in RGB or HSV space, see setColorInterpolation.
Alternatively, load one of the preset color gradients shown in the image below, with loadPreset, or by directly specifying the preset in the constructor.
Apart from red, green and blue components, the gradient also interpolates the alpha values of the configured color stops. This allows to display some portions of the data range as transparent in the plot.
How NaN values are interpreted can be configured with setNanHandling.
The constructor QCPColorGradient(GradientPreset preset) allows directly converting a GradientPreset to a QCPColorGradient. This means that you can directly pass GradientPreset to all the setGradient methods, e.g.:
The total number of levels used in the gradient can be set with setLevelCount. Whether the color gradient shall be applied periodically (wrapping around) to data values that lie outside the data range specified on the plottable instance can be controlled with setPeriodic.
Definition at line 4752 of file qcustomplot.h.
Member Enumeration Documentation
◆ ColorInterpolation
Defines the color spaces in which color interpolation between gradient stops can be performed.
- See also
- setColorInterpolation
Definition at line 4761 of file qcustomplot.h.
◆ GradientPreset
Defines the available presets that can be loaded with loadPreset. See the documentation there for an image of the presets.
Enumerator | |
---|---|
gpGrayscale | Continuous lightness from black to white (suited for non-biased data representation) |
gpHot | Continuous lightness from black over firey colors to white (suited for non-biased data representation) |
gpCold | Continuous lightness from black over icey colors to white (suited for non-biased data representation) |
gpNight | Continuous lightness from black over weak blueish colors to white (suited for non-biased data representation) |
gpCandy | Blue over pink to white. |
gpGeography | Colors suitable to represent different elevations on geographical maps. |
gpIon | Half hue spectrum from black over purple to blue and finally green (creates banding illusion but allows more precise magnitude estimates) |
gpThermal | Colors suitable for thermal imaging, ranging from dark blue over purple to orange, yellow and white. |
gpPolar | Colors suitable to emphasize polarity around the center, with blue for negative, black in the middle and red for positive values. |
gpSpectrum | An approximation of the visible light spectrum (creates banding illusion but allows more precise magnitude estimates) |
gpJet | Hue variation similar to a spectrum, often used in numerical visualization (creates banding illusion but allows more precise magnitude estimates) |
gpHues | Full hue cycle, with highest and lowest color red (suitable for periodic data, such as angles and phases, see setPeriodic) |
Definition at line 4783 of file qcustomplot.h.
◆ NanHandling
Defines how NaN data points shall appear in the plot.
- See also
- setNanHandling, setNanColor
Enumerator | |
---|---|
nhNone | NaN data points are not explicitly handled and shouldn't occur in the data (this gives slight performance improvement) |
nhLowestColor | NaN data points appear as the lowest color defined in this QCPColorGradient. |
nhHighestColor | NaN data points appear as the highest color defined in this QCPColorGradient. |
nhTransparent | NaN data points appear transparent. |
nhNanColor | NaN data points appear as the color defined with setNanColor. |
Definition at line 4771 of file qcustomplot.h.
Constructor & Destructor Documentation
◆ QCPColorGradient() [1/2]
QCPColorGradient::QCPColorGradient | ( | ) |
Constructs a new, empty QCPColorGradient with no predefined color stops. You can add own color stops with setColorStopAt.
The color level count is initialized to 350.
Definition at line 16547 of file qcustomplot.cpp.
◆ QCPColorGradient() [2/2]
QCPColorGradient::QCPColorGradient | ( | GradientPreset | preset | ) |
Constructs a new QCPColorGradient initialized with the colors and color interpolation according to preset.
The color level count is initialized to 350.
Definition at line 16564 of file qcustomplot.cpp.
Member Function Documentation
◆ clearColorStops()
void QCPColorGradient::clearColorStops | ( | ) |
Clears all color stops.
- See also
- setColorStops, setColorStopAt
Definition at line 16989 of file qcustomplot.cpp.
◆ color()
QRgb QCPColorGradient::color | ( | double | position, |
const QCPRange & | range, | ||
bool | logarithmic = false ) |
This method is used to colorize a single data value given in position, to colors. The data range that shall be used for mapping the data value to the gradient is passed in range. logarithmic indicates whether the data value shall be mapped to a color logarithmically.
If an entire array of data values shall be converted, rather use colorize, for better performance.
The returned QRgb has its r, g and b components premultiplied with alpha (see QImage::Format_ARGB32_Premultiplied).
Definition at line 16840 of file qcustomplot.cpp.
◆ colorInterpolation()
|
inline |
Definition at line 4806 of file qcustomplot.h.
◆ colorize() [1/2]
void QCPColorGradient::colorize | ( | const double * | data, |
const QCPRange & | range, | ||
QRgb * | scanLine, | ||
int | n, | ||
int | dataIndexFactor = 1, | ||
bool | logarithmic = false ) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
This method is used to quickly convert a data array to colors. The colors will be output in the array scanLine. Both data and scanLine must have the length n when passed to this function. The data range that shall be used for mapping the data value to the gradient is passed in range. logarithmic indicates whether the data values shall be mapped to colors logarithmically.
if data actually contains 2D-data linearized via [row*columnCount + column]
, you can set dataIndexFactor to columnCount
to convert a column instead of a row of the data array, in scanLine. scanLine will remain a regular (1D) array. This works because data is addressed data[i*dataIndexFactor]
.
Use the overloaded method to additionally provide alpha map data.
The QRgb values that are placed in scanLine have their r, g, and b components premultiplied with alpha (see QImage::Format_ARGB32_Premultiplied).
Definition at line 16711 of file qcustomplot.cpp.
◆ colorize() [2/2]
void QCPColorGradient::colorize | ( | const double * | data, |
const unsigned char * | alpha, | ||
const QCPRange & | range, | ||
QRgb * | scanLine, | ||
int | n, | ||
int | dataIndexFactor = 1, | ||
bool | logarithmic = false ) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Additionally to the other overload of colorize, this method takes the array alpha, which has the same size and structure as data and encodes the alpha information per data point.
The QRgb values that are placed in scanLine have their r, g and b components premultiplied with alpha (see QImage::Format_ARGB32_Premultiplied).
Definition at line 16767 of file qcustomplot.cpp.
◆ colorStops()
Definition at line 4805 of file qcustomplot.h.
◆ inverted()
QCPColorGradient QCPColorGradient::inverted | ( | ) | const |
Returns an inverted gradient. The inverted gradient has all properties as this QCPColorGradient, but the order of the color stops is inverted.
- See also
- setColorStops, setColorStopAt
Definition at line 17001 of file qcustomplot.cpp.
◆ levelCount()
|
inline |
Definition at line 4804 of file qcustomplot.h.
◆ loadPreset()
void QCPColorGradient::loadPreset | ( | GradientPreset | preset | ) |
Clears the current color stops and loads the specified preset. A preset consists of predefined color stops and the corresponding color interpolation method.
The available presets are:
Definition at line 16880 of file qcustomplot.cpp.
◆ nanColor()
|
inline |
Definition at line 4808 of file qcustomplot.h.
◆ nanHandling()
|
inline |
Definition at line 4807 of file qcustomplot.h.
◆ operator!=()
|
inline |
Definition at line 4801 of file qcustomplot.h.
◆ operator==()
bool QCPColorGradient::operator== | ( | const QCPColorGradient & | other | ) | const |
Definition at line 16577 of file qcustomplot.cpp.
◆ periodic()
|
inline |
Definition at line 4809 of file qcustomplot.h.
◆ setColorInterpolation()
void QCPColorGradient::setColorInterpolation | ( | QCPColorGradient::ColorInterpolation | interpolation | ) |
Sets whether the colors in between the configured color stops (see setColorStopAt) shall be interpolated linearly in RGB or in HSV color space.
For example, a sweep in RGB space from red to green will have a muddy brown intermediate color, whereas in HSV space the intermediate color is yellow.
Definition at line 16643 of file qcustomplot.cpp.
◆ setColorStopAt()
void QCPColorGradient::setColorStopAt | ( | double | position, |
const QColor & | color ) |
Sets the color the gradient will have at the specified position (from 0 to 1). In between these color stops, the color is interpolated according to setColorInterpolation.
- See also
- setColorStops, clearColorStops
Definition at line 16630 of file qcustomplot.cpp.
◆ setColorStops()
Sets at which positions from 0 to 1 which color shall occur. The positions are the keys, the colors are the values of the passed QMap colorStops. In between these color stops, the color is interpolated according to setColorInterpolation.
A more convenient way to create a custom gradient may be to clear all color stops with clearColorStops (or creating a new, empty QCPColorGradient) and then adding them one by one with setColorStopAt.
- See also
- clearColorStops
Definition at line 16618 of file qcustomplot.cpp.
◆ setLevelCount()
void QCPColorGradient::setLevelCount | ( | int | n | ) |
Sets the number of discretization levels of the color gradient to n. The default is 350 which is typically enough to create a smooth appearance. The minimum number of levels is 2.
Definition at line 16593 of file qcustomplot.cpp.
◆ setNanColor()
void QCPColorGradient::setNanColor | ( | const QColor & | color | ) |
Sets the color that NaN data is represented by, if setNanHandling is set to ref nhNanColor.
- See also
- setNanHandling
Definition at line 16668 of file qcustomplot.cpp.
◆ setNanHandling()
void QCPColorGradient::setNanHandling | ( | QCPColorGradient::NanHandling | handling | ) |
Sets how NaNs in the data are displayed in the plot.
- See also
- setNanColor
Definition at line 16657 of file qcustomplot.cpp.
◆ setPeriodic()
void QCPColorGradient::setPeriodic | ( | bool | enabled | ) |
Sets whether data points that are outside the configured data range (e.g. QCPColorMap::setDataRange) are colored by periodically repeating the color gradient or whether they all have the same color, corresponding to the respective gradient boundary color.
As shown in the image above, gradients that have the same start and end color are especially suitable for a periodic gradient mapping, since they produce smooth color transitions throughout the color map. A preset that has this property is gpHues.
In practice, using periodic color gradients makes sense when the data corresponds to a periodic dimension, such as an angle or a phase. If this is not the case, the color encoding might become ambiguous, because multiple different data values are shown as the same color.
Definition at line 16688 of file qcustomplot.cpp.
◆ stopsUseAlpha()
|
protected |
Returns true if the color gradient uses transparency, i.e. if any of the configured color stops has an alpha value below 255.
Definition at line 17015 of file qcustomplot.cpp.
◆ updateColorBuffer()
|
protected |
Updates the internal color buffer which will be used by colorize and color, to quickly convert positions to colors. This is where the interpolation between color stops is calculated.
Definition at line 17030 of file qcustomplot.cpp.
Member Data Documentation
◆ mColorBuffer
|
protected |
Definition at line 4838 of file qcustomplot.h.
◆ mColorBufferInvalidated
|
protected |
Definition at line 4839 of file qcustomplot.h.
◆ mColorInterpolation
|
protected |
Definition at line 4832 of file qcustomplot.h.
◆ mColorStops
Definition at line 4831 of file qcustomplot.h.
◆ mLevelCount
|
protected |
Definition at line 4830 of file qcustomplot.h.
◆ mNanColor
|
protected |
Definition at line 4834 of file qcustomplot.h.
◆ mNanHandling
|
protected |
Definition at line 4833 of file qcustomplot.h.
◆ mPeriodic
|
protected |
Definition at line 4835 of file qcustomplot.h.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:15:14 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.