Revision: 7244
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7244&view=rev
Author: leejjoon
Date: 2009-06-29 15:11:00 +0000 (Mon, 29 Jun 2009)
Log Message:
-----------
axes_grid: doc update
Modified Paths:
--------------
trunk/matplotlib/examples/axes_grid/demo_floating_axis.py
trunk/matplotlib/lib/mpl_toolkits/axes_grid/grid_helper_curvelinear.py
Added Paths:
-----------
trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axislines.rst
Added: trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axislines.rst
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axislines.rst
(rev 0)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axislines.rst
2009-06-29 15:11:00 UTC (rev 7244)
@@ -0,0 +1,250 @@
+.. _axislines-manual:
+
+=========
+Axislines
+=========
+
+Axislines includes a derived Axes implementation. The
+biggest difference is that the artists responsible to draw axis line,
+ticks, ticklabel and axis labels are separated out from the mpl's Axis
+class, which are much more than artists in the original
+mpl. This change was strongly motivated to support curvlinear
+grid. Here are a few things that axes_grid.axislines.Axes is different
+from original Axes from mpl.
+
+* Axis elements (axis line(spine), ticks, ticklabel and axis labels)
+ are drawn by a AxisArtist instance. Unlike Axis, left, right, top
+ and bottom axis are drawn by separate artists. And each of them may
+ have different tick location and different tick labels.
+
+* gridlines are drawn by a Gridlines instance. The change was
+ motivated that in curvelinear coordinate, a gridline may not cross
+ axislines (i.e., no associated ticks). In the original Axes class,
+ gridlines are tied to ticks.
+
+* ticklines can be rotated if necessary (i.e, along the gridlines)
+
+In summary, all these changes was to support
+
+* a curvelinear grid.
+* a floating axis
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_floating_axis.py
+
+
+*axes_grid.axislines.Axes* defines a *axis* attribute, which is a
+dictionary of AxisArtist instances. By default, the dictionary has 4
+AxisArtist instances, responsible for drawing of left, right, bottom
+and top axis.
+
+xaxis and yaxis attributes are still available, however they are set
+to not visible. As separate artists are used for rendering axis, some
+axis-related method in mpl may have no effect.
+In addition to AxisArtist instances, the axes_grid.axislines.Axes will
+have *gridlines* attribute (Gridlines), which obviously draws grid
+lines.
+
+In both AxisArtist and Gridlines, the calculation of tick and grid
+location is delegated to an instance of GridHelper class.
+axes_grid.axislines.Axes class uses GridHelperRectlinear as a grid
+helper. The GridHelperRectlinear class is a wrapper around the *xaxis*
+and *yaxis* of mpl's original Axes, and it was meant to work as the
+way how mpl's original axes works. For example, tick location changes
+using set_ticks method and etc. should work as expected. But change in
+artist properties (e.g., color) will not work in general, although
+some effort has been made so that some often-change attributes (color,
+etc.) are respected.
+
+
+AxisArtist
+==========
+
+AxisArtist can be considered as a container artist with following
+attributes which will draw ticks, labels, etc.
+
+ * line
+ * major_ticks, major_ticklabels
+ * minor_ticks, minor_ticklabels
+ * offsetText
+ * label
+
+
+line
+----
+
+Derived from Line2d class. Responsible for drawing a spinal(?) line.
+
+major_ticks, minor_ticks
+------------------------
+
+Derived from Line2d class. Note that ticks are markers.
+
+
+major_ticklabels, minor_ticklabels
+----------------------------------
+
+Derived from Text. Note that it is not a list of Text artist, but a
+single artist (similar to a collection).
+
+axislabel
+---------
+
+Derived from Text.
+
+
+Default AxisArtists
+-------------------
+
+By default, following for axis artists are defined.::
+
+ ax.axis["left"], ax.axis["bottom"], ax.axis["right"], ax.axis["top"]
+
+The ticklabels and axislabel of the top and the right axis are set to
+not visible.
+
+
+HowTo
+=====
+
+1. Changing tick locations and label.
+
+ Same as the original mpl's axes.::
+
+ ax.set_xticks([1,2,3])
+
+2. Changing axis properties like color, etc.
+
+ Change the properties of appropriate artists. For example, to change
+ the color of the ticklabels::
+
+ ax.axis["left"].major_ticklabels.set_color("r")
+
+
+GridHelper
+==========
+
+To actually define a curvelinear coordinate, you have to use your own
+grid helper. A generalised version of grid helper class is supplied
+and this class should be suffice in most of cases. A user may provide
+two functions which defines a transformation (and its inverse pair)
+from the curved coordinate to (rectlinear) image coordinate. Note that
+while ticks and grids are drawn for curved coordinate, the data
+transform of the axes itself (ax.transData) is still rectlinear
+(image) coordinate. ::
+
+
+ from mpl_toolkits.axes_grid.grid_helper_curvelinear \
+ import GridHelperCurveLinear
+ from mpl_toolkits.axes_grid.axislines import Subplot
+
+ # from curved coordinate to rectlinear coordinate.
+ def tr(x, y):
+ x, y = np.asarray(x), np.asarray(y)
+ return x, y-x
+
+ # from rectlinear coordinate to curved coordinate.
+ def inv_tr(x,y):
+ x, y = np.asarray(x), np.asarray(y)
+ return x, y+x
+
+
+ grid_helper = GridHelperCurveLinear((tr, inv_tr))
+
+ ax1 = Subplot(fig, 1, 1, 1, grid_helper=grid_helper)
+
+ fig.add_subplot(ax1)
+
+
+You may use matplotlib's Transform instance instead (but a
+inverse transformation must be defined). Often, coordinate range in a
+curved coordinate system may have a limited range, or may have
+cycles. In those cases, a more customized version of grid helper is
+required. ::
+
+
+ import mpl_toolkits.axes_grid.angle_helper as angle_helper
+
+ # PolarAxes.PolarTransform takes radian. However, we want our coordinate
+ # system in degree
+ tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform()
+
+
+ # extreme finder : find a range of coordinate.
+ # 20, 20 : number of sampling points along x, y direction
+ # The first coordinate (longitude, but theta in polar)
+ # has a cycle of 360 degree.
+ # The second coordinate (latitude, but radius in polar) has a minimum of 0
+ extreme_finder = angle_helper.ExtremeFinderCycle(20, 20,
+ lon_cycle = 360,
+ lat_cycle = None,
+ lon_minmax = None,
+ lat_minmax = (0, np.inf),
+ )
+
+ # Find a grid values appropriate for the coordinate (degree,
+ # minute, second). The argument is a approximate number of grids.
+ grid_locator1 = angle_helper.LocatorDMS(12)
+
+ # And also uses an appropriate formatter. Note that,the
+ # acceptable Locator and Formatter class is a bit different than
+ # that of mpl's, and you cannot directly use mpl's Locator and
+ # Formatter here (but may be possible in the future).
+ tick_formatter1 = angle_helper.FormatterDMS()
+
+ grid_helper = GridHelperCurveLinear(tr,
+ extreme_finder=extreme_finder,
+ grid_locator1=grid_locator1,
+ tick_formatter1=tick_formatter1
+ )
+
+
+Again, the *transData* of the axes is still a rectlinear coordinate
+(image coordinate). You may manually do conversion between two
+coordinates, or you may use Parasite Axes for convenience.::
+
+ ax1 = SubplotHost(fig, 1, 2, 2, grid_helper=grid_helper)
+
+ # A parasite axes with given transform
+ ax2 = ParasiteAxesAuxTrans(ax1, tr, "equal")
+ # note that ax2.transData == tr + ax1.transData
+ # Anthing you draw in ax2 will match the ticks and grids of ax1.
+ ax1.parasites.append(ax2)
+
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_curvelinear_grid.py
+
+
+
+FloatingAxis
+============
+
+A floating axis is an axis one of whose data coordinate is fixed, i.e,
+its location is not fixed in Axes coordinate but changes as axes data
+limits changes. A floating axis can be created using
+*new_floating_axis* method. However, it is your responsibility that
+the resulting AxisArtist is properly added to the axes. A recommended
+way is to add it as an item of Axes's axis attribute.::
+
+ # floating axis whose first (index starts from 0) coordinate
+ # (theta) is fixed at 60
+
+ ax1.axis["lat"] = axis = ax1.new_floating_axis(0, 60)
+ axis.label.set_text(r"$\theta = 60^{\circ}$")
+ axis.label.set_visible(True)
+
+
+See the first example of this page.
+
+Current Limitations and TODO's
+==============================
+
+The code need more refinement. Here is a incomplete list of issues and TODO's
+
+* No easy way to support a user customized tick location (for
+ curvelinear grid). A new Locator class needs to be created.
+
+* FloatingAxis may have coordinate limits, e.g., a floating axis of x
+ = 0, but y only spans from 0 to 1.
+
+* The location of axislabel of FloatingAxis needs to be optionally
+ given as a coordinate value. ex, a floating axis of x=0 with label at y=1
Modified: trunk/matplotlib/examples/axes_grid/demo_floating_axis.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/demo_floating_axis.py 2009-06-27
13:13:50 UTC (rev 7243)
+++ trunk/matplotlib/examples/axes_grid/demo_floating_axis.py 2009-06-29
15:11:00 UTC (rev 7244)
@@ -1,6 +1,5 @@
"""
-A floating axes for curvelinear grid.
-.
+An experimental support for curvelinear grid.
"""
@@ -8,6 +7,7 @@
"""
polar projection, but in a rectangular box.
"""
+ global ax1
import numpy as np
import mpl_toolkits.axes_grid.angle_helper as angle_helper
from matplotlib.projections import PolarAxes
@@ -40,19 +40,18 @@
ax1 = SubplotHost(fig, 1, 1, 1, grid_helper=grid_helper)
-
fig.add_subplot(ax1)
# Now creates floating axis
- grid_helper = ax1.get_grid_helper()
+ #grid_helper = ax1.get_grid_helper()
# floating axis whose first coordinate (theta) is fixed at 60
- ax1.axis["lat"] = axis = grid_helper.new_floating_axis(0, 60, axes=ax1)
+ ax1.axis["lat"] = axis = ax1.new_floating_axis(0, 60)
axis.label.set_text(r"$\theta = 60^{\circ}$")
axis.label.set_visible(True)
# floating axis whose second coordinate (r) is fixed at 6
- ax1.axis["lon"] = axis = grid_helper.new_floating_axis(1, 6, axes=ax1)
+ ax1.axis["lon"] = axis = ax1.new_floating_axis(1, 6)
axis.label.set_text(r"$r = 6$")
ax1.set_aspect(1.)
Modified: trunk/matplotlib/lib/mpl_toolkits/axes_grid/grid_helper_curvelinear.py
===================================================================
--- trunk/matplotlib/lib/mpl_toolkits/axes_grid/grid_helper_curvelinear.py
2009-06-27 13:13:50 UTC (rev 7243)
+++ trunk/matplotlib/lib/mpl_toolkits/axes_grid/grid_helper_curvelinear.py
2009-06-29 15:11:00 UTC (rev 7244)
@@ -14,7 +14,7 @@
"""
Helper class for a fixed axis.
"""
-
+
def __init__(self, grid_helper, side, nth_coord_ticks=None):
"""
nth_coord = along which coordinate value varies.
@@ -100,7 +100,7 @@
lon_factor,
lon_levs)
- grid_info["lat_labels"] = grid_finder.tick_formatter1("bottom",
+ grid_info["lat_labels"] = grid_finder.tick_formatter2("bottom",
lat_factor,
lat_levs)
@@ -321,7 +321,7 @@
if label_direction is None:
label_direction = "top"
-
+
_helper = FloatingAxisArtistHelper(self, nth_coord,
value,
label_direction=label_direction,
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
_______________________________________________
Matplotlib-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
