<divid="unreleased-message"> You are reading an old version of the documentation (v3.0.2). For the latest version see <ahref="/stable/">https://matplotlib.org/stable/</a></div>
<spanid="adding-new-scales"></span><h1>Developer's guide for creating scales and transformations<aclass="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
<aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.set_xscale.html#matplotlib.axes.Axes.set_xscale" title="matplotlib.axes.Axes.set_xscale"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">set_xscale()</span></code></a> and
<aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.set_yscale.html#matplotlib.axes.Axes.set_yscale" title="matplotlib.axes.Axes.set_yscale"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">set_yscale()</span></code></a>. Projections can be chosen
using the <codeclass="docutils literal notranslate"><spanclass="pre">projection</span></code> keyword argument to the
<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>
<divclass="section" id="creating-a-new-scale">
<spanid="creating-new-scale"></span><h2>Creating a new scale<aclass="headerlink" href="#creating-a-new-scale" title="Permalink to this headline">¶</a></h2>
<p>Adding a new scale consists of defining a subclass of
<aclass="reference internal" href="../api/scale_api.html#matplotlib.scale.ScaleBase" title="matplotlib.scale.ScaleBase"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">matplotlib.scale.ScaleBase</span></code></a>, that includes the following
elements:</p>
<ulclass="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
(<codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="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
<aclass="reference internal" href="../gallery/scales/custom_scale.html"><spanclass="doc">Custom scale</span></a>. There are also some classes
in <aclass="reference internal" href="../api/scale_api.html#module-matplotlib.scale" title="matplotlib.scale"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">matplotlib.scale</span></code></a> that may be used as starting points.</p>
<spanid="creating-new-projection"></span><h2>Creating a new projection<aclass="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 <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">matplotlib.axes.Axes</span></code></a> and includes the following
elements:</p>
<ulclass="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>
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 <aclass="reference internal" href="../api/projections_api.html#module-matplotlib.projections.polar" title="matplotlib.projections.polar"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="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><pclass="first">By defining the class attribute <codeclass="docutils literal notranslate"><spanclass="pre">name</span></code>, the projection axes can be
<li><pclass="first">For more complex, parameterisable projections, a generic "projection" object
may be defined which includes the method <codeclass="docutils literal notranslate"><spanclass="pre">_as_mpl_axes</span></code>. <codeclass="docutils literal notranslate"><spanclass="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' <codeclass="docutils literal notranslate"><spanclass="pre">__init__</span></code>
method. Subsequently a parameterised projection can be initialised with:</p>
<p>where MyProjection is an object which implements a <codeclass="docutils literal notranslate"><spanclass="pre">_as_mpl_axes</span></code> method.</p>
</li>
</ul>
<p>A full-fledged and heavily annotated example is in
<aclass="reference internal" href="../gallery/misc/custom_projection.html"><spanclass="doc">Custom projection</span></a>. The polar plot
functionality in <aclass="reference internal" href="../api/projections_api.html#module-matplotlib.projections.polar" title="matplotlib.projections.polar"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">matplotlib.projections.polar</span></code></a> may also be of
interest.</p>
</div>
<divclass="section" id="api-documentation">
<h2>API documentation<aclass="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h2>