pyqtgraph/doc/source/colormap.rst
Nils Nemitz 7d41e8a878
Color map linearization (#1797)
* extended color map functions

* assertion string, documentation pass, comment purge

* fix some documentation links

* simplify assert statement

* removed comments and redundancy, renamed modulated bar

* include modulatedBarData in documentation

* test running matplotlib with dummy backend

* skip color maps example on OSX/PySide6.1.1

* removed skipping of tests

* reverted some accidental whitespace, removed unneeded numpy import

* removed unneded alpha parameter
2021-06-08 20:41:46 -07:00

85 lines
2.8 KiB
ReStructuredText

Color Maps
==========
A color map defines a relationship between scalar data values and a range of colors. Color maps are
commonly used to generate false color images, color scatter-plot points, and illustrate the height
of surface plots.
PyQtGraph's :class:`~pyqtgraph.ColorMap` can conveniently be applied to images and interactively
adjusted by using :class:`~pyqtgraph.ColorBarItem`.
To provide interactively user-defined color mappings, see
:class:`~pyqtgraph.GradientEditorItem` and :class:`~pyqtgraph.GradientWidget`, which wraps it.
:class:`~pyqtgraph.GradientEditorItem` combines the editing with a histogram and controls for
interactively adjusting image levels.
ColorMap can also be used a convenient source of colors from a consistent palette or to generate
QPen and QBrush objects used to draw lines and fills that are colored according to their values
along the horizontal or vertical axis.
Sources for color maps
----------------------
Color maps can be user defined by assigning a number of *stops* over the range of 0 to 1. A color
is given for each stop, and the in-between values are generated by interpolation.
When map colors directly represent values, an improperly designed map can obscure detail over
certain ranges of values, while creating false detail in others. PyQtGraph includes the
perceptually uniform color maps provided by the
`Colorcet project <https://colorcet.holoviz.org/>`_. Color maps can also be imported from the
``colorcet`` library or from ``matplotlib``, if either of these is installed.
To see all available color maps, please run the `ColorMap` demonstration available in the suite of
:ref:`examples`.
Examples
--------
False color display of a 2D data set. Display levels are controlled by
a :class:`ColorBarItem <pyqtgraph.ColorBarItem>`:
.. literalinclude:: images/gen_example_false_color_image.py
:lines: 18-28
:dedent: 8
Using QtGui.QPen and QtGui.QBrush to color plots according to the plotted value:
.. literalinclude:: images/gen_example_gradient_plot.py
:lines: 16-33
:dedent: 8
.. image::
images/example_false_color_image.png
:width: 49%
:alt: Example of a false color image
.. image::
images/example_gradient_plot.png
:width: 49%
:alt: Example of drawing and filling plots with gradients
The use of color maps is also demonstrated in the `ImageView`, `Color Gradient Plots` and `ColorBarItem`
:ref:`examples`.
API Reference
-------------
.. autofunction:: pyqtgraph.colormap.listMaps
.. autofunction:: pyqtgraph.colormap.get
.. autofunction:: pyqtgraph.colormap.getFromMatplotlib
.. autofunction:: pyqtgraph.colormap.getFromColorcet
.. autofunction:: pyqtgraph.colormap.modulatedBarData
.. autoclass:: pyqtgraph.ColorMap
:members:
.. automethod:: pyqtgraph.ColorMap.__init__