{{ message }}
-
Notifications
You must be signed in to change notification settings - Fork 62
Expand file tree
/
Copy pathadd_new_projection.html
More file actions
262 lines (237 loc) · 16.8 KB
/
Copy pathadd_new_projection.html
File metadata and controls
262 lines (237 loc) · 16.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Developer's guide for creating scales and transformations — Matplotlib 3.1.3 documentation</title>
<link rel="stylesheet" href="../_static/mpl.css?v3.1.3-2-g782f6ef56"
type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css"
type="text/css" />
<link rel="stylesheet" href="../_static/graphviz.css" type="text/css" />
<link rel="stylesheet" href="../_static/gallery.css" type="text/css" />
<link rel="stylesheet" href="../_static/copybutton.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/clipboard.min.js"></script>
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript">var copybuttonSkipText = '>>> ';</script>
<script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Matplotlib 3.1.3 documentation"
href="../_static/opensearch.xml"/>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html"
/>
<link rel="search" title="Search" href="../search.html"
/>
<link rel="top" title="Matplotlib 3.1.3 documentation" href="../index.html" />
<link rel="up" title="The Matplotlib Developers' Guide" href="index.html" />
<link rel="next" title="Working with Matplotlib source code" href="gitwash/index.html" />
<link rel="prev" title="Plot directive documentation" href="plot_directive.html" />
<link rel="canonical" href="https://matplotlib.org/3.4.3/devel/add_new_projection.html" />
<script data-domain="matplotlib.org" defer="defer" src="https://views.scientific-python.org/js/script.js"></script>
</head>
<body>
<div id="unreleased-message"> You are reading an old version of the documentation (v3.1.3). For the latest version see <a href="/stable/">https://matplotlib.org/stable/</a> </div>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px; position: relative;">
<a href="../index.html">
<div style="float: left; position: absolute; width: 496px; bottom: 0; padding-bottom: 24px"><span style="float: right; color: #789; background: white">Version 3.1.3</span></div>
<img src="../_static/logo2_compressed.svg" height="125px" border="0" alt="matplotlib"/></a>
<!-- The "Fork me on github" ribbon -->
<div id="forkongithub"><a href="https://github.com/matplotlib/matplotlib">Fork me on GitHub</a></div>
</div>
<nav class="main-nav">
<ul>
<li><a href="../users/installing.html">Installation</a></li>
<li><a href="../contents.html">Documentation</a></li>
<li><a href="../gallery/index.html">Examples</a></li>
<li><a href="../tutorials/index.html">Tutorials</a></li>
<li><a href="index.html">Contributing</a></li>
<li class="nav-right">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" placeholder="Search"/>
</form>
</li>
</ul>
</nav>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="gitwash/index.html" title="Working with Matplotlib source code"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="plot_directive.html" title="Plot directive documentation"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">home</a>| </li>
<li><a href="../contents.html">contents</a> »</li>
<li><a href="index.html" accesskey="U">The Matplotlib Developers' Guide</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Developer's guide for creating scales and transformations</a><ul>
<li><a class="reference internal" href="#creating-a-new-scale">Creating a new scale</a></li>
<li><a class="reference internal" href="#creating-a-new-projection">Creating a new projection</a></li>
<li><a class="reference internal" href="#api-documentation">API documentation</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../contents.html">Documentation overview</a><ul>
<li><a href="index.html">The Matplotlib Developers' Guide</a><ul>
<li>Previous: <a href="plot_directive.html" title="previous chapter">Plot directive documentation</a></li>
<li>Next: <a href="gitwash/index.html" title="next chapter">Working with <em>Matplotlib</em> source code</a></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="sidebar-pagesource" role="note" aria-label="source link"
style="margin-top: 1.5em; padding-top: 0.1em; border-top: 1px solid #86989b">
<a href="../_sources/devel/add_new_projection.rst.txt"
style="color: #c0c0c0" rel="nofollow">Show Page Source</a>
</div>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="developer-s-guide-for-creating-scales-and-transformations">
<span id="adding-new-scales"></span><h1>Developer's guide for creating scales and transformations<a class="headerlink" href="#developer-s-guide-for-creating-scales-and-transformations" title="Permalink to this headline">¶</a></h1>
<p>Matplotlib supports the addition of custom procedures that transform
the data before it is displayed.</p>
<p>There is an important distinction between two kinds of
transformations. Separable transformations, working on a single
dimension, are called "scales", and non-separable transformations,
that handle data in two or more dimensions at a time, are called
"projections".</p>
<p>From the user's perspective, the scale of a plot can be set with
<a class="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.set_xscale.html#matplotlib.axes.Axes.set_xscale" title="matplotlib.axes.Axes.set_xscale"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_xscale()</span></code></a> and
<a class="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.set_yscale.html#matplotlib.axes.Axes.set_yscale" title="matplotlib.axes.Axes.set_yscale"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_yscale()</span></code></a>. Projections can be chosen
using the <code class="docutils literal notranslate"><span class="pre">projection</span></code> keyword argument to the
<code class="xref py py-func docutils literal notranslate"><span class="pre">plot()</span></code> or <code class="xref py py-func docutils literal notranslate"><span class="pre">subplot()</span></code>
functions, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">plot</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">projection</span><span class="o">=</span><span class="s2">"custom"</span><span class="p">)</span>
</pre></div>
</div>
<p>This document is intended for developers and advanced users who need
to create new scales and projections for matplotlib. The necessary
code for scales and projections can be included anywhere: directly
within a plot script, in third-party code, or in the matplotlib source
tree itself.</p>
<div class="section" id="creating-a-new-scale">
<span id="creating-new-scale"></span><h2>Creating a new scale<a class="headerlink" href="#creating-a-new-scale" title="Permalink to this headline">¶</a></h2>
<p>Adding a new scale consists of defining a subclass of
<a class="reference internal" href="../api/scale_api.html#matplotlib.scale.ScaleBase" title="matplotlib.scale.ScaleBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">matplotlib.scale.ScaleBase</span></code></a>, that includes the following
elements:</p>
<ul class="simple">
<li>A transformation from data coordinates into display coordinates.</li>
<li>An inverse of that transformation. This is used, for example, to
convert mouse positions from screen space back into data space.</li>
<li>A function to limit the range of the axis to acceptable values
(<code class="docutils literal notranslate"><span class="pre">limit_range_for_scale()</span></code>). A log scale, for instance, would
prevent the range from including values less than or equal to zero.</li>
<li>Locators (major and minor) that determine where to place ticks in
the plot, and optionally, how to adjust the limits of the plot to
some "good" values. Unlike <code class="docutils literal notranslate"><span class="pre">limit_range_for_scale()</span></code>, which is
always enforced, the range setting here is only used when
automatically setting the range of the plot.</li>
<li>Formatters (major and minor) that specify how the tick labels
should be drawn.</li>
</ul>
<p>Once the class is defined, it must be registered with matplotlib so
that the user can select it.</p>
<p>A full-fledged and heavily annotated example is in
<a class="reference internal" href="../gallery/scales/custom_scale.html"><span class="doc">Custom scale</span></a>. There are also some classes
in <a class="reference internal" href="../api/scale_api.html#module-matplotlib.scale" title="matplotlib.scale"><code class="xref py py-mod docutils literal notranslate"><span class="pre">matplotlib.scale</span></code></a> that may be used as starting points.</p>
</div>
<div class="section" id="creating-a-new-projection">
<span id="creating-new-projection"></span><h2>Creating a new projection<a class="headerlink" href="#creating-a-new-projection" title="Permalink to this headline">¶</a></h2>
<p>Adding a new projection consists of defining a projection axes which
subclasses <a class="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><code class="xref py py-class docutils literal notranslate"><span class="pre">matplotlib.axes.Axes</span></code></a> and includes the following
elements:</p>
<ul class="simple">
<li>A transformation from data coordinates into display coordinates.</li>
<li>An inverse of that transformation. This is used, for example, to
convert mouse positions from screen space back into data space.</li>
<li>Transformations for the gridlines, ticks and ticklabels. Custom
projections will often need to place these elements in special
locations, and matplotlib has a facility to help with doing so.</li>
<li>Setting up default values (overriding <a class="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.cla.html#matplotlib.axes.Axes.cla" title="matplotlib.axes.Axes.cla"><code class="xref py py-meth docutils literal notranslate"><span class="pre">cla()</span></code></a>),
since the defaults for a rectilinear axes may not be appropriate.</li>
<li>Defining the shape of the axes, for example, an elliptical axes, that will be
used to draw the background of the plot and for clipping any data elements.</li>
<li>Defining custom locators and formatters for the projection. For
example, in a geographic projection, it may be more convenient to
display the grid in degrees, even if the data is in radians.</li>
<li>Set up interactive panning and zooming. This is left as an
"advanced" feature left to the reader, but there is an example of
this for polar plots in <a class="reference internal" href="../api/projections_api.html#module-matplotlib.projections.polar" title="matplotlib.projections.polar"><code class="xref py py-mod docutils literal notranslate"><span class="pre">matplotlib.projections.polar</span></code></a>.</li>
<li>Any additional methods for additional convenience or features.</li>
</ul>
<p>Once the projection axes is defined, it can be used in one of two ways:</p>
<ul>
<li><p class="first">By defining the class attribute <code class="docutils literal notranslate"><span class="pre">name</span></code>, the projection axes can be
registered with <a class="reference internal" href="../api/projections_api.html#matplotlib.projections.register_projection" title="matplotlib.projections.register_projection"><code class="xref py py-func docutils literal notranslate"><span class="pre">matplotlib.projections.register_projection()</span></code></a>
and subsequently simply invoked by name:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">plt</span><span class="o">.</span><span class="n">axes</span><span class="p">(</span><span class="n">projection</span><span class="o">=</span><span class="s1">'my_proj_name'</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p class="first">For more complex, parameterisable projections, a generic "projection" object
may be defined which includes the method <code class="docutils literal notranslate"><span class="pre">_as_mpl_axes</span></code>. <code class="docutils literal notranslate"><span class="pre">_as_mpl_axes</span></code>
should take no arguments and return the projection's axes subclass and a
dictionary of additional arguments to pass to the subclass' <code class="docutils literal notranslate"><span class="pre">__init__</span></code>
method. Subsequently a parameterised projection can be initialised with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">plt</span><span class="o">.</span><span class="n">axes</span><span class="p">(</span><span class="n">projection</span><span class="o">=</span><span class="n">MyProjection</span><span class="p">(</span><span class="n">param1</span><span class="o">=</span><span class="n">param1_value</span><span class="p">))</span>
</pre></div>
</div>
<p>where MyProjection is an object which implements a <code class="docutils literal notranslate"><span class="pre">_as_mpl_axes</span></code> method.</p>
</li>
</ul>
<p>A full-fledged and heavily annotated example is in
<a class="reference internal" href="../gallery/misc/custom_projection.html"><span class="doc">Custom projection</span></a>. The polar plot
functionality in <a class="reference internal" href="../api/projections_api.html#module-matplotlib.projections.polar" title="matplotlib.projections.polar"><code class="xref py py-mod docutils literal notranslate"><span class="pre">matplotlib.projections.polar</span></code></a> may also be of
interest.</p>
</div>
<div class="section" id="api-documentation">
<h2>API documentation<a class="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><a class="reference internal" href="../api/scale_api.html#module-matplotlib.scale" title="matplotlib.scale"><code class="xref py py-mod docutils literal notranslate"><span class="pre">matplotlib.scale</span></code></a></li>
<li><a class="reference internal" href="../api/projections_api.html#module-matplotlib.projections" title="matplotlib.projections"><code class="xref py py-mod docutils literal notranslate"><span class="pre">matplotlib.projections</span></code></a></li>
<li><a class="reference internal" href="../api/projections_api.html#module-matplotlib.projections.polar" title="matplotlib.projections.polar"><code class="xref py py-mod docutils literal notranslate"><span class="pre">matplotlib.projections.polar</span></code></a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright 2002 - 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the Matplotlib development team; 2012 - 2018 The Matplotlib development team.
<br />
Last updated on Feb 09, 2020.
Created using
<a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
Doc version v3.1.3-2-g782f6ef56.
</div>
</body>
<footer>
</footer>
</html>
You can’t perform that action at this time.