-
-
Notifications
You must be signed in to change notification settings - Fork 8.4k
Expand file tree
/
Copy path__init__.py
More file actions
124 lines (90 loc) · 4.36 KB
/
Copy path__init__.py
File metadata and controls
124 lines (90 loc) · 4.36 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
"""
Non-separable transforms that map from data space to screen space.
Projections are defined as `~.axes.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 `~.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 `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_axes``
should 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_axes`` method.
A full-fledged and heavily annotated example is in
:doc:`/gallery/misc/custom_projection`. The polar plot functionality in
`matplotlib.projections.polar` may also be of interest.
"""
from .. import _api, axes, _docstring
from .geo import AitoffAxes, HammerAxes, LambertAxes, MollweideAxes
from .polar import PolarAxes
try:
from mpl_toolkits.mplot3d import Axes3D
except Exception:
import warnings
warnings.warn("Unable to import Axes3D. This may be due to multiple versions of "
"Matplotlib being installed (e.g. as a system package and as a pip "
"package). As a result, the 3D projection is not available.")
Axes3D = None
class ProjectionRegistry:
"""A mapping of registered projection names to projection classes."""
def __init__(self):
self._all_projection_types = {}
def register(self, *projections):
"""Register a new set of projections."""
for projection in projections:
name = projection.name
self._all_projection_types[name] = projection
def get_projection_class(self, name, _error_cls=KeyError):
"""Get a projection class from its *name*."""
return _api.getitem_checked(self._all_projection_types, _error_cls=_error_cls,
projection=name)
def get_projection_names(self):
"""Return the names of all projections currently registered."""
return sorted(self._all_projection_types)
projection_registry = ProjectionRegistry()
projection_registry.register(
axes.Axes,
PolarAxes,
AitoffAxes,
HammerAxes,
LambertAxes,
MollweideAxes,
)
if Axes3D is not None:
projection_registry.register(Axes3D)
else:
# remove from namespace if not importable
del Axes3D
def register_projection(cls):
projection_registry.register(cls)
def get_projection_class(projection=None):
"""
Get a projection class from its name.
If *projection* is None, a standard rectilinear projection is returned.
"""
if projection is None:
projection = 'rectilinear'
return projection_registry.get_projection_class(projection, _error_cls=ValueError)
get_projection_names = projection_registry.get_projection_names
_docstring.interpd.register(projection_names=get_projection_names())