matplotlib.projections — Matplotlib 3.9.2 documentation (original) (raw)
Non-separable transforms that map from data space to screen space.
Projections are defined as Axes subclasses. They include 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 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 matplotlib.projections.polar.
- Any additional methods for additional convenience or features.
Once the projection Axes is defined, it can be used in one of two ways:
- By defining the class attribute
name, the projection Axes can be registered with matplotlib.projections.register_projection and subsequently simply invoked by name:
fig.add_subplot(projection="my_proj_name") - For more complex, parameterisable projections, a generic "projection" object may be defined which includes the method
_as_mpl_axes._as_mpl_axesshould take no arguments and return the projection's Axes subclass and a dictionary of additional arguments to pass to the subclass'__init__method. Subsequently a parameterised projection can be initialised with:
fig.add_subplot(projection=MyProjection(param1=param1_value))
where MyProjection is an object which implements a_as_mpl_axesmethod.
A full-fledged and heavily annotated example is inCustom projection. The polar plot functionality inmatplotlib.projections.polar may also be of interest.
class matplotlib.projections.ProjectionRegistry[source]#
Bases: object
A mapping of registered projection names to projection classes.
get_projection_class(name)[source]#
Get a projection class from its name.
get_projection_names()[source]#
Return the names of all projections currently registered.
register(*projections)[source]#
Register a new set of projections.
matplotlib.projections.get_projection_class(projection=None)[source]#
Get a projection class from its name.
If projection is None, a standard rectilinear projection is returned.
matplotlib.projections.get_projection_names()[source]#
Return the names of all projections currently registered.
matplotlib.projections.register_projection(cls)[source]#
Built-in projections#
Matplotlib has built-in support for polar and some geographic projections. See the following pages for more information: