Added documentation, supported add_axes regarding _as_mpl_axes.

Phil Elson · Phil Elson · commit 756dd8c1c6a5 · 2012-02-06T16:48:42.000Z
diff --git a/doc/devel/add_new_projection.rst b/doc/devel/add_new_projection.rst
@@ -71,8 +71,9 @@ in :mod:`matplotlib.scale` that may be used as starting points.
 Creating a new projection
 =========================
 
-Adding a new projection consists of defining a subclass of
-:class:`matplotlib.axes.Axes`, that includes the following elements:
+Adding a new projection consists of defining a projection axes which
+subclasses :class:`matplotlib.axes.Axes` and includes the following 
+elements:
 
   - A transformation from data coordinates into display coordinates.
 
@@ -98,11 +99,33 @@ Adding a new projection consists of defining a subclass of
   - 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`.
+    
+  - Optionally define the class attribute ``NAME`` which can be 
+    registered with :func:`matplotlib.projections.register_projection` 
+    and used for simple projection instantiation such as 
+    ``plt.axes(projection=NAME)``, where ``NAME`` is a string. 
 
   - 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.
+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 :func:`matplotlib.projections.register_projection` 
+    and subsequently simply invoked by name::  
+    
+        plt.axes(projection=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::
+    
+        plt.axes(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
 :file:`examples/api/custom_projection_example.py`.  The polar plot
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -702,8 +702,16 @@ def add_axes(self, *args, **kwargs):
                         projection)
                 projection = 'polar'
 
+            if isinstance(projection, basestring) or projection is None:
+                projection_class = get_projection_class(projection)
+            elif hasattr(projection, '_as_mpl_axes'):
+                projection_class, extra_kwargs = projection._as_mpl_axes()
+                kwargs.update(**extra_kwargs)
+            else:
+                TypeError('projection must be a string, None or implement a _as_mpl_axes method. Got %r' % projection)
+            
             a = projection_factory(projection, self, rect, **kwargs)
-
+            
         self._axstack.add(key, a)
         self.sca(a)
         return a
@@ -714,10 +722,11 @@ def add_subplot(self, *args, **kwargs):
         Add a subplot.  Examples:
 
             fig.add_subplot(111)
-            fig.add_subplot(1,1,1)            # equivalent but more general
-            fig.add_subplot(212, axisbg='r')  # add subplot with red background
-            fig.add_subplot(111, polar=True)  # add a polar subplot
-            fig.add_subplot(sub)              # add Subplot instance sub
+            fig.add_subplot(1,1,1)                    # equivalent but more general
+            fig.add_subplot(212, axisbg='r')          # add subplot with red background
+            fig.add_subplot(111, projection='polar')  # add a polar subplot
+            fig.add_subplot(111, polar=True)          # add a polar subplot
+            fig.add_subplot(sub)                      # add Subplot instance sub
 
         *kwargs* are legal :class:`!matplotlib.axes.Axes` kwargs plus
         *projection*, which chooses a projection type for the axes.
@@ -751,18 +760,20 @@ def add_subplot(self, *args, **kwargs):
             ispolar = kwargs.pop('polar', False)
             projection = kwargs.pop('projection', None)
             if ispolar:
-                if projection is not None and projection != 'polar':
+                if projection is not None:
                     raise ValueError(
-                        "polar=True, yet projection='%s'. " +
+                        "polar=True, yet projection=%r. " +
                         "Only one of these arguments should be supplied." %
                         projection)
                 projection = 'polar'
 
             if isinstance(projection, basestring) or projection is None:
                 projection_class = get_projection_class(projection)
-            else:
+            elif hasattr(projection, '_as_mpl_axes'):
                 projection_class, extra_kwargs = projection._as_mpl_axes()
                 kwargs.update(**extra_kwargs)
+            else:
+                TypeError('projection must be a string, None or implement a _as_mpl_axes method. Got %r' % projection)
 
             # Remake the key without projection kwargs:
             key = self._make_key(*args, **kwargs)
diff --git a/lib/matplotlib/projections/__init__.py b/lib/matplotlib/projections/__init__.py
@@ -56,10 +56,19 @@ def get_projection_class(projection=None):
     if projection is None:
         projection = 'rectilinear'
 
-    try:
-        return projection_registry.get_projection_class(projection)
-    except KeyError:
-        raise ValueError("Unknown projection '%s'" % projection)
+    if isinstance(projection, basestring):
+        try:
+            return projection_registry.get_projection_class(projection)
+        except KeyError:
+            raise ValueError("Unknown projection '%s'" % projection)
+        
+    elif hasattr(projection, '_as_mpl_axes'):
+        projection_class, extra_kwargs = projection._as_mpl_axes()
+        kwargs.update(**extra_kwargs)
+    else:
+        TypeError('projection must be a string, None or implement a _as_mpl_axes method. Got %r' % projection)
+
+    
 
 def projection_factory(projection, figure, rect, **kwargs):
     """
diff --git a/lib/matplotlib/projections/polar.py b/lib/matplotlib/projections/polar.py
@@ -757,4 +757,14 @@ def drag_pan(self, button, key, x, y):
 #             return mpath.Path(result, codes)
 #         transform_path_non_affine = transform_path
 
-
+class Polar(object):
+    """
+    Represents the polar projection, a Polar instance can be used to initialise
+    a polar plot in the standard ways, for example::
+    
+        plt.axes(projection=Polar())
+        
+    """
+    def _as_mpl_axes(self):
+        # implement the matplotlib axes interface
+        return PolarAxes, {}
