Main Page · Class Overview · Hierarchy · All Classes
Public Types | Public Functions | Protected Functions
QCPColorGradient Class Reference

Defines a color gradient for use with e.g. QCPColorMap. More...

Public Types

enum  ColorInterpolation
enum  GradientPreset

Public Functions

 QCPColorGradient (GradientPreset preset=gpCold)
bool operator== (const QCPColorGradient &other) const
bool operator!= (const QCPColorGradient &other) const
int levelCount () const
QMap< double, QColor > colorStops () const
ColorInterpolation colorInterpolation () const
bool periodic () const
void setLevelCount (int n)
void setColorStops (const QMap< double, QColor > &colorStops)
void setColorStopAt (double position, const QColor &color)
void setColorInterpolation (ColorInterpolation interpolation)
void setPeriodic (bool enabled)
void colorize (const double *data, const QCPRange &range, QRgb *scanLine, int n, int dataIndexFactor=1, bool logarithmic=false)
QRgb color (double position, const QCPRange &range, bool logarithmic=false)
void loadPreset (GradientPreset preset)
void clearColorStops ()
QCPColorGradient inverted () const

Protected Functions

void updateColorBuffer ()

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 a setGradient method which takes an instance of this class. You set colors 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.

QCPColorGradient.png

The fact that the QCPColorGradient(GradientPreset preset) constructor allows directly converting a GradientPreset to a QCPColorGradient, you can also directly pass GradientPreset to all the setGradient methods, e.g.:

colorMap->setGradient(QCPColorGradient::gpHot);

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.

Member Enumeration Documentation

Defines the color spaces in which color interpolation between gradient stops can be performed.

See Also
setColorInterpolation

Defines the available presets that can be loaded with loadPreset. See the documentation there for an image of the presets.

Constructor & Destructor Documentation

QCPColorGradient::QCPColorGradient ( GradientPreset  preset = gpCold)

Constructs a new QCPColorGradient initialized with the colors and color interpolation according to preset.

The color level count is initialized to 350.

Member Function Documentation

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.

QCPColorGradient-levelcount.png
void QCPColorGradient::setColorStops ( const QMap< double, QColor > &  colorStops)

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 and then adding them one by one with setColorStopAt.

See Also
clearColorStops
void QCPColorGradient::setColorStopAt ( double  position,
const QColor &  color 
)

Sets the color the gradient will have at position (from 0 to 1). In between these color stops, the color is interpolated according to setColorInterpolation.

See Also
setColorStops, clearColorStops
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.

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.

QCPColorGradient-periodic.png

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, periodic color gradients make especially 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.

void QCPColorGradient::colorize ( const double *  data,
const QCPRange range,
QRgb *  scanLine,
int  n,
int  dataIndexFactor = 1,
bool  logarithmic = false 
)

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].

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.

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:

QCPColorGradient.png
void QCPColorGradient::clearColorStops ( )

Clears all color stops.

See Also
setColorStops, setColorStopAt
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
void QCPColorGradient::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.


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