Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit c6d2581

Browse files
timhoffmtimhoffm
authored
Merge pull request #19093 from jeromefv/specifying_colors
DOCS: Specifying Colors tutorial format & arrange
2 parents 4285ae0 + faecefa commit c6d2581

File tree

3 files changed

+115
-59
lines changed

3 files changed

+115
-59
lines changed

‎doc/_static/color_zorder_A.png

4.4 KB
Loading

‎doc/_static/color_zorder_B.png

3.89 KB
Loading

‎tutorials/colors/colors.py

Lines changed: 115 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -3,61 +3,114 @@
33
Specifying Colors
44
*****************
55
6-
Matplotlib recognizes the following formats to specify a color:
7-
8-
* an RGB or RGBA (red, green, blue, alpha) tuple of float values in closed
9-
interval ``[0, 1]`` (e.g., ``(0.1, 0.2, 0.5)`` or ``(0.1, 0.2, 0.5, 0.3)``);
10-
* a hex RGB or RGBA string (e.g., ``'#0f0f0f'`` or ``'#0f0f0f80'``;
11-
case-insensitive);
12-
* a shorthand hex RGB or RGBA string, equivalent to the hex RGB or RGBA
13-
string obtained by duplicating each character, (e.g., ``'#abc'``, equivalent
14-
to ``'#aabbcc'``, or ``'#abcd'``, equivalent to ``'#aabbccdd'``;
15-
case-insensitive);
16-
* a string representation of a float value in ``[0, 1]`` inclusive for gray
17-
level (e.g., ``'0.8'`` for light gray);
18-
* one of the characters ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``, which
19-
are short-hand notations for shades of blue, green, red, cyan, magenta,
20-
yellow, black, and white. Note that the colors ``'g', 'c', 'm', 'y'`` do not
21-
coincide with the X11/CSS4 colors. Their particular shades were chosen for
22-
better visibility of colored lines against typical backgrounds.
23-
* a X11/CSS4 color name (case-insensitive);
24-
* a name from the `xkcd color survey`_, prefixed with ``'xkcd:'`` (e.g.,
25-
``'xkcd:sky blue'``; case insensitive);
26-
* one of the Tableau Colors from the 'T10' categorical palette (the default
27-
color cycle): ``{'tab:blue', 'tab:orange', 'tab:green', 'tab:red',
28-
'tab:purple', 'tab:brown', 'tab:pink', 'tab:gray', 'tab:olive', 'tab:cyan'}``
29-
(case-insensitive);
30-
* a "CN" color spec, i.e. ``'C'`` followed by a number, which is an index into
31-
the default property cycle (:rc:`axes.prop_cycle`); the indexing is intended
32-
to occur at rendering time, and defaults to black if the cycle does not
33-
include color.
6+
Matplotlib recognizes the following formats in the table below to specify a
7+
color.
8+
9+
+--------------------------------------+--------------------------------------+
10+
| Format | Example |
11+
+======================================+======================================+
12+
| RGB or RGBA (red, green, blue, alpha)| - ``(0.1, 0.2, 0.5)`` |
13+
| tuple of float values in a closed | - ``(0.1, 0.2, 0.5, 0.3)`` |
14+
| interval [0, 1]. | |
15+
+--------------------------------------+--------------------------------------+
16+
| Case-insensitive hex RGB or RGBA | - ``'#0f0f0f'`` |
17+
| string. | - ``'#0f0f0f80'`` |
18+
+--------------------------------------+--------------------------------------+
19+
| Case-insensitive RGB or RGBA string | - ``'#abc'`` as ``'#aabbcc'`` |
20+
| equivalent hex shorthand of | - ``'#fb1'`` as ``'#ffbb11'`` |
21+
| duplicated characters. | |
22+
+--------------------------------------+--------------------------------------+
23+
| String representation of float value | - ``'0.8'`` as light gray |
24+
| in closed interval ``[0, 1]`` for | - ``'0'`` as black |
25+
| black and white, respectively. | - ``'1'`` as white |
26+
+--------------------------------------+--------------------------------------+
27+
| Single character shorthand notation | - ``'b'`` as blue |
28+
| for shades of colors. | - ``'g'`` as green |
29+
| | - ``'r'`` as red |
30+
| .. note:: The colors green, cyan, | - ``'c'`` as cyan |
31+
| magenta, and yellow do not | - ``'m'`` as magenta |
32+
| coincide with X11/CSS4 | - ``'y'`` as yellow |
33+
| colors. | - ``'k'`` as black |
34+
| | - ``'w'`` as white |
35+
+--------------------------------------+--------------------------------------+
36+
| Case-insensitive X11/CSS4 color name | - ``'aquamarine'`` |
37+
| with no spaces. | - ``'mediumseagreen'`` |
38+
+--------------------------------------+--------------------------------------+
39+
| Case-insensitive color name from | - ``'xkcd:sky blue'`` |
40+
| `xkcd color survey`_ with ``'xkcd:'``| - ``'xkcd:eggshell'`` |
41+
| prefix. | |
42+
+--------------------------------------+--------------------------------------+
43+
| Case-insensitive Tableau Colors from | - ``'tab:blue'`` |
44+
| 'T10' categorical palette. | - ``'tab:orange'`` |
45+
| | - ``'tab:green'`` |
46+
| | - ``'tab:red'`` |
47+
| | - ``'tab:purple'`` |
48+
| .. note:: This is the default color | - ``'tab:brown'`` |
49+
| cycle. | - ``'tab:pink'`` |
50+
| | - ``'tab:gray'`` |
51+
| | - ``'tab:olive'`` |
52+
| | - ``'tab:cyan'`` |
53+
+--------------------------------------+--------------------------------------+
54+
| "CN" color spec where ``'C'`` | - ``'C0'`` |
55+
| precedes a number acting as an index | - ``'C1'`` |
56+
| into the default property cycle. +--------------------------------------+
57+
| | :rc:`axes.prop_cycle` |
58+
| .. note:: Matplotlib indexes color | |
59+
| at draw time and defaults | |
60+
| to black if cycle does not | |
61+
| include color. | |
62+
+--------------------------------------+--------------------------------------+
3463
3564
.. _xkcd color survey: https://xkcd.com/color/rgb/
3665
37-
"Red", "Green", and "Blue" are the intensities of those colors, the combination
38-
of which span the colorspace.
66+
.. seealso::
3967
40-
How "Alpha" behaves depends on the ``zorder`` of the Artist. Higher
41-
``zorder`` Artists are drawn on top of lower Artists, and "Alpha" determines
42-
whether the lower artist is covered by the higher.
43-
If the old RGB of a pixel is ``RGBold`` and the RGB of the
44-
pixel of the Artist being added is ``RGBnew`` with Alpha ``alpha``,
45-
then the RGB of the pixel is updated to:
46-
``RGB = RGBOld * (1 - Alpha) + RGBnew * Alpha``. Alpha
47-
of 1 means the old color is completely covered by the new Artist, Alpha of 0
48-
means that pixel of the Artist is transparent.
68+
The following links provide more information on colors in Matplotlib.
69+
* :doc:`/gallery/color/color_demo` Example
70+
* `matplotlib.colors` API
71+
* :doc:`/gallery/color/named_colors` Example
4972
50-
For more information on colors in matplotlib see
73+
"Red", "Green", and "Blue" are the intensities of those colors. In combination,
74+
they represent the colorspace.
75+
76+
Matplotlib draws Artists based on the ``zorder`` parameter. If there are no
77+
specified values, Matplotlib defaults to the order of the Artists added to the
78+
Axes.
79+
80+
The alpha for an Artist controls opacity. It indicates how the RGB color of the
81+
new Artist combines with RGB colors already on the Axes.
82+
83+
The two Artists combine with alpha compositing. Matplotlib uses the equation
84+
below to compute the result of blending a new Artist.
85+
86+
::
87+
88+
RGB_{new} = RGB_{below} * (1 - \\alpha) + RGB_{artist} * \\alpha
89+
90+
Alpha of 1 indicates the new Artist completely covers the previous color.
91+
Alpha of 0 for top color is not visible; however, it contributes to blending
92+
for intermediate values as the cumulative result of all previous Artists. The
93+
following table contains examples.
94+
95+
+---------------+-------------------------------------------------------------+
96+
| Alpha value | Visual |
97+
+===============+=============================================================+
98+
| ``0.3`` | .. image:: ../../_static/color_zorder_A.png |
99+
+---------------+-------------------------------------------------------------+
100+
| ``1`` | .. image:: ../../_static/color_zorder_B.png |
101+
+---------------+-------------------------------------------------------------+
102+
103+
.. note::
104+
105+
Re-ordering Artists is not commutative in Matplotlib.
51106
52-
* the :doc:`/gallery/color/color_demo` example;
53-
* the `matplotlib.colors` API;
54-
* the :doc:`/gallery/color/named_colors` example.
55107
56108
"CN" color selection
57109
--------------------
58110
59-
"CN" colors are converted to RGBA as soon as the artist is created. For
60-
example,
111+
Matplotlib converts "CN" colors to RGBA when drawing Artists. The
112+
:doc:`/tutorials/intermediate/color_cycle` section contains additional
113+
information about controlling colors and style properties.
61114
"""
62115

63116

@@ -78,33 +131,34 @@ def demo(sty):
78131
ax.plot(th, np.sin(th), 'C2', label='C2')
79132
ax.legend()
80133

134+
81135
demo('default')
82136
demo('seaborn')
83137

84138
###############################################################################
85-
# will use the first color for the title and then plot using the second
86-
# and third colors of each style's :rc:`axes.prop_cycle`.
87-
#
139+
# The first color ``'C0'`` is the title. Each plot uses the second and third
140+
# colors of each style's :rc:`axes.prop_cycle`. They are ``'C1'`` and ``'C2'``,
141+
# respectively.
88142
#
89143
# .. _xkcd-colors:
90144
#
91145
# xkcd v X11/CSS4
92146
# ---------------
93147
#
94-
# The xkcd colors are derived from a user survey conducted by the
95-
# webcomic xkcd. `Details of the survey are available on the xkcd blog
148+
# The xkcd colors come from a user survey conducted by the webcomic xkcd.
149+
# Details of the survey are available on the `xkcd blog
96150
# <https://blog.xkcd.com/2010/05/03/color-survey-results/>`__.
97151
#
98-
# Out of 148 colors in the CSS color list, there are 95 name collisions
99-
# between the X11/CSS4 names and the xkcd names, all but 3 of which have
100-
# different hex values. For example ``'blue'`` maps to ``'#0000FF'``
101-
# where as ``'xkcd:blue'`` maps to ``'#0343DF'``. Due to these name
102-
# collisions all of the xkcd colors have ``'xkcd:'`` prefixed. As noted in
103-
# the blog post, while it might be interesting to re-define the X11/CSS4 names
104-
# based on such a survey, we do not do so unilaterally.
152+
# There are 95 out of 148 colors with name collisions between the X11/CSS4
153+
# names and the xkcd names. Only three of these colors have the same hex
154+
# values.
155+
#
156+
# For example, ``'blue'`` maps to ``'#0000FF'`` whereas ``'xkcd:blue'`` maps to
157+
# ``'#0343DF'``. Due to these name collisions, all xkcd colors have the
158+
# ``'xkcd:'`` prefix.
105159
#
106-
# The name collisions are shown in the table below; the color names
107-
# where the hex values agree are shown in bold.
160+
# The visual below shows name collisions. Color names where hex values agree
161+
# are bold.
108162

109163
import matplotlib._color_data as mcd
110164
import matplotlib.patches as mpatch
@@ -135,3 +189,5 @@ def demo(sty):
135189
ax.set_xlim(0, 3)
136190
ax.set_ylim(0, j + 2)
137191
ax.axis('off')
192+
193+
plt.show()

0 commit comments

Comments
 (0)