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

Skip to content

Commit fa4fbe1

Browse files
tacaswelltacaswell
committed
DOC: work on color documentation
1 parent 628f4c1 commit fa4fbe1

File tree

3 files changed

+164
-55
lines changed

3 files changed

+164
-55
lines changed

‎doc/users/colors.rst

Lines changed: 68 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,70 @@ Specifying Colors
77
In almost all places in matplotlib where a color can be specified by the user
88
it can be provided as:
99

10-
* ``(r, g, b)`` tuples
11-
* ``(r, g, b, a)`` tuples
12-
* hex string, ex ``#0F0F0F``, or ``#0F0F0F0F`` (with alpha channel)
13-
* float value between [0, 1] for gray level
14-
* One of ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``
15-
* valid CSS4/X11 color names
16-
* valid name from the `xkcd color survey
17-
<http://blog.xkcd.com/2010/05/03/color-survey-results/>`__ These
18-
names are prefixed with ``'xkcd:'`` (e.g., ``'xkcd:sky blue'``) to
19-
prevent name clashes with the CSS4/X11 names.
20-
* One of ``{'C0', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7', 'C8', 'C9'}`` which will use the
21-
color from the Nth element in ``mpl.rcparams['axes.prop_cycle']``.
10+
* a ``(r, g, b)`` tuple
11+
* a ``(r, g, b, a)`` tuple
12+
* a hex string RGB or RGBA string (ex ``'#0F0F0F'`` or ``'#0F0F0F0F'``)
13+
* a float value in ``[0, 1]`` inclusive for gray level
14+
* one of ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``
15+
* a X11/CSS4 color name
16+
* a name from the `xkcd color survey <http://xkcd.com/color/rgb/>`__
17+
prefixed with ``'xkcd:'`` (e.g., ``'xkcd:sky blue'``)
18+
* one of ``{'C0', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7', 'C8', 'C9'}``
2219

2320
All string specifications of color are case-insensitive.
2421

25-
Internally, mpl is moving to storing all colors as RGBA float quadruples.
2622

27-
There are 95 (out of 148 colors in the css color list) conflicts between the
28-
CSS4/X11 names and the xkcd names. Given that the former are the standard
29-
color names of the web, matplotlib should follow them. Thus, xkcd color names
30-
are prefixed with ``'xkcd:'``, for example ``'blue'`` maps to ``'#0000FF'``
31-
where as ``'xkcd:blue'`` maps to ``'#0343DF'``.
23+
``'CN'`` color selection
24+
------------------------
25+
26+
Color can be specified by a string matching the regex ``C[0-9]``.
27+
This can be passed any place that a color is currently accepted and
28+
can be used as a 'single character color' in format-string to
29+
`matplotlib.Axes.plot`.
30+
31+
This allows easy access to the color is the propriety cycle and to write code
32+
that will integrate with global changes to the style. For example
33+
34+
.. plot::
35+
:include-source: True
36+
37+
import matplotlib as mpl
38+
th = np.linspace(0, 2*np.pi, 128)
39+
40+
def demo(sty):
41+
mpl.style.use(sty)
42+
fig, ax = plt.subplots(figsize=(3, 3))
43+
44+
ax.set_title('style: {!r}'.format(sty), color='C0')
45+
46+
ax.plot(th, np.cos(th), 'C1', label='C1')
47+
ax.plot(th, np.sin(th), 'C2', label='C2')
48+
ax.legend()
49+
50+
demo('default')
51+
demo('seaborn')
52+
53+
will plot using the color of the first and sixth styles in
54+
``mpl.rcParams['axes.prop_cycle']``.
55+
56+
xkcd v X11/CSS4
57+
---------------
58+
59+
The xkcd colors are derived from a user survey conducted by the
60+
webcomic xkcd. `Details of the survey are available on the xkcd blog
61+
<http://blog.xkcd.com/2010/05/03/color-survey-results/>`__.
62+
63+
There are 95 (out of 148 colors in the css color list) name collisions
64+
between the X11/CSS4 names and the xkcd names, all but 3 of which have
65+
different hex values. For example ``'blue'`` maps to ``'#0000FF'``
66+
where as ``'xkcd:blue'`` maps to ``'#0343DF'``. Due to these name
67+
collisions all of the xkcd colors have ``'xkcd:'`` prefixed. As noted in
68+
the blog post, while it might be interesting to re-define the X11/CSS4 names
69+
based on such a survey we do not do so unilaterally.
70+
71+
The name collisions are shown in the table below, the color names
72+
where the hex values agree are shown in bold.
73+
3274

3375
.. plot::
3476

@@ -43,20 +85,22 @@ where as ``'xkcd:blue'`` maps to ``'#0343DF'``.
4385
ax = fig.add_axes([0, 0, 1, 1])
4486

4587
for j, n in enumerate(sorted(overlap, reverse=True)):
88+
weight = None
4689
cn = mcd.CSS4_COLORS[n]
4790
xkcd = mcd.XKCD_COLORS["xkcd:" + n].upper()
48-
if cn != xkcd:
49-
print(n, cn, xkcd)
91+
if cn == xkcd:
92+
weight = 'bold'
5093

5194
r1 = mpatch.Rectangle((0, j), 1, 1, color=cn)
5295
r2 = mpatch.Rectangle((1, j), 1, 1, color=xkcd)
53-
txt = ax.text(2, j+.5, ' ' + n, va='center', fontsize=10)
96+
txt = ax.text(2, j+.5, ' ' + n, va='center', fontsize=10,
97+
weight=weight)
5498
ax.add_patch(r1)
5599
ax.add_patch(r2)
56100
ax.axhline(j, color='k')
57101

58-
ax.text(.5, j + .1, 'X11', ha='center')
59-
ax.text(1.5, j + .1, 'XKCD', ha='center')
102+
ax.text(.5, j + 1.5, 'X11', ha='center', va='center')
103+
ax.text(1.5, j + 1.5, 'xkcd', ha='center', va='center')
60104
ax.set_xlim(0, 3)
61-
ax.set_ylim(0, j + 1)
105+
ax.set_ylim(0, j + 2)
62106
ax.axis('off')

‎doc/users/whats_new/style_changes.rst renamed to ‎doc/users/dflt_style_changes.rst

Lines changed: 79 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,87 @@
1-
Changes to the default style
2-
----------------------------
1+
==============================
2+
Changes to the default style
3+
==============================
34

45
The most important changes in matplotlib 2.0 are the changes to the
56
default style.
67

78
While it is impossible to select the best default for all cases, these
89
are designed to work well in the most common cases.
910

10-
These changes include:
1111

12-
Colors
13-
``````
12+
13+
colors, color cycles, and color maps
14+
====================================
15+
16+
Colors in default property cycle
17+
--------------------------------
18+
19+
The colors in the default proprety cycle have been changed from
20+
``['b', 'g', 'r', 'c', 'm', 'y', 'k']`` to the `Vega
21+
category10 palette
22+
<https://github.com/vega/vega/wiki/Scales#scale-range-literals>`__
23+
24+
.. plot::
25+
26+
27+
th = np.linspace(0, 2*np.pi, 512)
28+
29+
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(6, 3))
30+
31+
32+
def color_demo(ax, colors, title):
33+
ax.set_title(title)
34+
for j, c in enumerate(colors):
35+
v_offset = -(j / len(colors))
36+
ax.plot(th, .1*np.sin(th) + v_offset, color=c)
37+
ax.annotate("'C{}'".format(j), (0, v_offset),
38+
xytext=(-1.5, 0),
39+
ha='right',
40+
va='center',
41+
color=c,
42+
textcoords='offset points',
43+
family='monospace')
44+
45+
ax.annotate("{!r}".format(c), (2*np.pi, v_offset),
46+
xytext=(1.5, 0),
47+
ha='left',
48+
va='center',
49+
color=c,
50+
textcoords='offset points',
51+
family='monospace')
52+
ax.axis('off')
53+
54+
old_colors = ['b', 'g', 'r', 'c', 'm', 'y', 'k']
55+
56+
new_colors = ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728',
57+
'#9467bd', '#8c564b', '#e377c2', '#7f7f7f',
58+
'#bcbd22', '#17becf']
59+
60+
color_demo(ax1, old_colors, 'classic')
61+
color_demo(ax2, new_colors, 'v2.0')
62+
63+
fig.subplots_adjust(**{'bottom': 0.0, 'left': 0.059, 'right': 0.869, 'top': 0.895})
64+
65+
In addition to changing the colors, an additional method to specify
66+
colors was added. Previously, the default colors were the single
67+
character short-hand notations for red, green, blue, cyan, magenta,
68+
yellow, and black. This made them easy to type and usable in the
69+
abbreviated style string in ``plot``. On the other hand, the new
70+
colors are only specified via a hex value. To make in easy to access
71+
these colors the notation for colors ``'CN'`` was added to access
72+
colors. This allows the first 10 colors in
73+
``mpl.rcParms['axes.prop_cycle']`` to be easily accessed. See
74+
:ref:`colors` for more details.
75+
76+
77+
Other
78+
-----
1479

1580
- The default figure background color has changed from grey to white.
1681
Use the rcParam ``figure.facecolor`` to control this.
1782

1883
- The default cycle of colors to draw lines, markers and other content
19-
has been changed. It is based on the `Vega category10 palette
20-
<https://github.com/vega/vega/wiki/Scales#scale-range-literals>`__.
84+
has been changed.
2185

2286
- The default color map used for images and pcolor meshes, etc., has
2387
changed from ``jet`` to ``viridis``.
@@ -29,14 +93,14 @@ Colors
2993
default.
3094

3195
Plots
32-
`````
96+
=====
3397

3498
- The default size of the elements in a scatter plot is now based on
3599
the rcParam ``lines.markersize`` so it is consistent with ``plot(X,
36100
Y, 'o')``. The old value was 20, and the new value is 36 (6^2).
37101

38102
Hatching
39-
````````
103+
========
40104

41105
- The width of the lines in a hatch pattern is now configurable by the
42106
rcParam `hatch.linewidth`, with a default of 1 point. The old
@@ -48,7 +112,7 @@ Hatching
48112
- Agg: 1 px
49113

50114
Plot layout
51-
```````````
115+
===========
52116

53117
- The default dpi used for on-screen is now 100, which is the same as
54118
the old default for saving files. Due to this, the on-screen
@@ -81,7 +145,7 @@ Plot layout
81145
rcParam ``errorbar.capsize`` to control this.
82146

83147
Images
84-
``````
148+
======
85149

86150
- The default mode for image interpolation, in the rcParam
87151
``image.interpolation``, is now ``nearest``.
@@ -95,7 +159,7 @@ Images
95159
downsampling of an image.
96160

97161
Fonts
98-
`````
162+
=====
99163

100164
- The default font has changed from "Bitstream Vera Sans" to "DejaVu
101165
Sans". "DejaVu Sans" is an improvement on "Bistream Vera Sans" that
@@ -109,7 +173,7 @@ Fonts
109173
TeX backend is used (i.e. ``text.usetex`` is ``True``).
110174

111175
Dates
112-
`````
176+
=====
113177

114178
- The default date formats are now all based on ISO format, i.e., with
115179
the slowest-moving value first. The date formatters are still
@@ -118,7 +182,7 @@ Dates
118182
format dates based on the current locale.
119183

120184
Legends
121-
```````
185+
=======
122186

123187
- By default, the number of points displayed in a legend is now 1.
124188

@@ -129,7 +193,7 @@ Legends
129193
- The legend now has rounded corners by default.
130194

131195
mplot3d
132-
```````
196+
=======
133197

134198
- mplot3d now obeys some style-related rcParams, rather than using
135199
hard-coded defaults. These include:

‎doc/users/whats_new.rst

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,35 @@
11
.. _whats-new:
22

3-
************************
4-
What's new in matplotlib
5-
************************
3+
==========================
4+
What's new in matplotlib
5+
==========================
66

77
For a list of all of the issues and pull requests since the last
88
revision, see the :ref:`github-stats`.
99

10-
.. note::
11-
matplotlib 2.0 supports Python 2.7, and 3.4+
10+
.. contents:: Table of Contents
11+
:depth: 3
1212

13-
matplotlib 1.5 supports Python 2.7, 3.4, and 3.5
1413

15-
matplotlib 1.4 supports Python 2.6, 2.7, 3.3, and 3.4
1614

17-
matplotlib 1.3 supports Python 2.6, 2.7, 3.2, and 3.3
15+
New in matplotlib 2.0
16+
=====================
1817

19-
matplotlib 1.2 supports Python 2.6, 2.7, and 3.1
18+
.. note::
2019

21-
matplotlib 1.1 supports Python 2.4 to 2.7
20+
matplotlib 2.0 supports Python 2.7, and 3.4+
2221

2322

2423

25-
.. contents:: Table of Contents
26-
:depth: 2
24+
Default style changes
25+
---------------------
2726

27+
The major changes in v2.0 are related to overhauling the default styles.
2828

29+
.. toctree::
30+
:maxdepth: 2
2931

30-
New in matplotlib-2.0
31-
=====================
32+
dflt_style_changes
3233

3334

3435
Improved color conversion API and RGBA support
@@ -90,7 +91,7 @@ New rcparams added
9091

9192

9293
Added ``svg.hashsalt`` key to rcParams
93-
```````````````````````````````````````
94+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9495

9596
If ``svg.hashsalt`` is ``None`` (which it is by default), the svg
9697
backend uses ``uuid4`` to generate the hash salt. If it is not
@@ -99,7 +100,7 @@ backend uses ``uuid4`` to generate the hash salt. If it is not
99100

100101

101102
Removed the ``svg.image_noscale`` rcParam
102-
`````````````````````````````````````````
103+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103104

104105
As a result of the extensive changes to image handling, the
105106
``svg.image_noscale`` rcParam has been removed. The same

0 commit comments

Comments
 (0)