7dbd17a5aa
Former-commit-id:133dc97f67[formerlya02aeb236c] [formerly9f19e3f712] [formerly133dc97f67[formerlya02aeb236c] [formerly9f19e3f712] [formerly06a8b51d6d[formerly9f19e3f712[formerly 64fa9254b946eae7e61bbc3f513b7c3696c4f54f]]]] Former-commit-id:06a8b51d6dFormer-commit-id:9bb8decbcf[formerly8e80217e59] [formerly377dcd10b9[formerly3360eb6c5f]] Former-commit-id:377dcd10b9Former-commit-id:e2ecdcfe33
134 lines
4.7 KiB
ReStructuredText
Executable file
134 lines
4.7 KiB
ReStructuredText
Executable file
.. _adding-new-scales:
|
|
|
|
***********************************************
|
|
Adding new scales and projections to matplotlib
|
|
***********************************************
|
|
|
|
.. ::author Michael Droettboom
|
|
|
|
Matplotlib supports the addition of custom procedures that transform
|
|
the data before it is displayed.
|
|
|
|
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".
|
|
|
|
From the user's perspective, the scale of a plot can be set with
|
|
:meth:`~matplotlib.axes.Axes.set_xscale` and
|
|
:meth:`~matplotlib.axes.Axes.set_xscale`. Projections can be chosen
|
|
using the ``projection`` keyword argument to the
|
|
:func:`~matplotlib.pylab.plot` or :func:`~matplotlib.pylab.subplot`
|
|
functions, e.g.::
|
|
|
|
plot(x, y, projection="custom")
|
|
|
|
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.
|
|
|
|
.. _creating-new-scale:
|
|
|
|
Creating a new scale
|
|
====================
|
|
|
|
Adding a new scale consists of defining a subclass of
|
|
:class:`matplotlib.scale.ScaleBase`, that includes the following
|
|
elements:
|
|
|
|
- A transformation from data coordinates into display coordinates.
|
|
|
|
- An inverse of that transformation. This is used, for example, to
|
|
convert mouse positions from screen space back into data space.
|
|
|
|
- A function to limit the range of the axis to acceptable values
|
|
(``limit_range_for_scale()``). A log scale, for instance, would
|
|
prevent the range from including values less than or equal to
|
|
zero.
|
|
|
|
- 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 ``limit_range_for_scale()``, which is
|
|
always enforced, the range setting here is only used when
|
|
automatically setting the range of the plot.
|
|
|
|
- Formatters (major and minor) that specify how the tick labels
|
|
should be drawn.
|
|
|
|
Once the class is defined, it must be registered with matplotlib so
|
|
that the user can select it.
|
|
|
|
A full-fledged and heavily annotated example is in
|
|
:file:`examples/api/custom_scale_example.py`. There are also some classes
|
|
in :mod:`matplotlib.scale` that may be used as starting points.
|
|
|
|
|
|
.. _creating-new-projection:
|
|
|
|
Creating a new projection
|
|
=========================
|
|
|
|
Adding a new projection consists of defining a subclass of
|
|
:class:`matplotlib.axes.Axes`, that includes the following elements:
|
|
|
|
- A transformation from data coordinates into display coordinates.
|
|
|
|
- An inverse of that transformation. This is used, for example, to
|
|
convert mouse positions from screen space back into data space.
|
|
|
|
- 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.
|
|
|
|
- Setting up default values (overriding
|
|
:meth:`~matplotlib.axes.Axes.cla`), since the defaults for a
|
|
rectilinear axes may not be appropriate.
|
|
|
|
- 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.
|
|
|
|
- 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.
|
|
|
|
- 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 :mod:`matplotlib.projections.polar`.
|
|
|
|
- Any additional methods for additional convenience or features.
|
|
|
|
Once the class is defined, it must be registered with matplotlib
|
|
so that the user can select it.
|
|
|
|
A full-fledged and heavily annotated example is in
|
|
:file:`examples/api/custom_projection_example.py`. The polar plot
|
|
functionality in :mod:`matplotlib.projections.polar` may also be of
|
|
interest.
|
|
|
|
API documentation
|
|
=================
|
|
|
|
matplotlib.scale
|
|
----------------
|
|
|
|
.. automodule:: matplotlib.scale
|
|
:members:
|
|
:show-inheritance:
|
|
|
|
matplotlib.projections
|
|
----------------------
|
|
|
|
.. automodule:: matplotlib.projections
|
|
:members:
|
|
:show-inheritance:
|
|
|
|
matplotlib.projections.polar
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. automodule:: matplotlib.projections.polar
|
|
:members:
|
|
:show-inheritance:
|