Menu
▾
▴
SF.net SVN: matplotlib:[7490] branches/v0_99_maint
|
From: <jd...@us...> - 2009-08-15 17:56:54
|
Revision: 7490
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7490&view=rev
Author: jdh2358
Date: 2009-08-15 17:56:44 +0000 (Sat, 15 Aug 2009)
Log Message:
-----------
added transformations tut, did some reorg
Modified Paths:
--------------
branches/v0_99_maint/CXX/IndirectPythonInterface.hxx
branches/v0_99_maint/agg24/include/agg_basics.h
branches/v0_99_maint/doc/users/index.rst
branches/v0_99_maint/doc/users/transforms_tutorial.rst
Added Paths:
-----------
branches/v0_99_maint/doc/pyplots/annotate_transform.py
branches/v0_99_maint/doc/users/annotations_intro.rst
branches/v0_99_maint/doc/users/legend_guide.rst
Removed Paths:
-------------
branches/v0_99_maint/doc/users/annotations_overview.rst
branches/v0_99_maint/doc/users/legend.rst
Modified: branches/v0_99_maint/CXX/IndirectPythonInterface.hxx
===================================================================
--- branches/v0_99_maint/CXX/IndirectPythonInterface.hxx 2009-08-15 17:40:27 UTC (rev 7489)
+++ branches/v0_99_maint/CXX/IndirectPythonInterface.hxx 2009-08-15 17:56:44 UTC (rev 7490)
@@ -193,6 +193,6 @@
void _XDECREF( PyObject *op );
char *__Py_PackageContext();
-};
+}
#endif // __CXX_INDIRECT_PYTHON_INTERFACE__HXX__
Modified: branches/v0_99_maint/agg24/include/agg_basics.h
===================================================================
--- branches/v0_99_maint/agg24/include/agg_basics.h 2009-08-15 17:40:27 UTC (rev 7489)
+++ branches/v0_99_maint/agg24/include/agg_basics.h 2009-08-15 17:56:44 UTC (rev 7490)
@@ -2,8 +2,8 @@
// Anti-Grain Geometry - Version 2.4
// Copyright (C) 2002-2005 Maxim Shemanarev (http://www.antigrain.com)
//
-// Permission to copy, use, modify, sell and distribute this software
-// is granted provided this copyright notice appears in all copies.
+// Permission to copy, use, modify, sell and distribute this software
+// is granted provided this copyright notice appears in all copies.
// This software is provided "as is" without express or implied
// warranty, and with no claim as to its suitability for any purpose.
//
@@ -25,12 +25,12 @@
#else
namespace agg
{
- // The policy of all AGG containers and memory allocation strategy
+ // The policy of all AGG containers and memory allocation strategy
// in general is that no allocated data requires explicit construction.
// It means that the allocator can be really simple; you can even
- // replace new/delete to malloc/free. The constructors and destructors
- // won't be called in this case, however everything will remain working.
- // The second argument of deallocate() is the size of the allocated
+ // replace new/delete to malloc/free. The constructors and destructors
+ // won't be called in this case, however everything will remain working.
+ // The second argument of deallocate() is the size of the allocated
// block. You can use this information if you wish.
//------------------------------------------------------------pod_allocator
template<class T> struct pod_allocator
@@ -40,8 +40,8 @@
};
// Single object allocator. It's also can be replaced with your custom
- // allocator. The difference is that it can only allocate a single
- // object and the constructor and destructor must be called.
+ // allocator. The difference is that it can only allocate a single
+ // object and the constructor and destructor must be called.
// In AGG there is no need to allocate an array of objects with
// calling their constructors (only single ones). So that, if you
// replace these new/delete to malloc/free make sure that the in-place
@@ -213,23 +213,23 @@
enum cover_scale_e
{
cover_shift = 8, //----cover_shift
- cover_size = 1 << cover_shift, //----cover_size
- cover_mask = cover_size - 1, //----cover_mask
- cover_none = 0, //----cover_none
- cover_full = cover_mask //----cover_full
+ cover_size = 1 << cover_shift, //----cover_size
+ cover_mask = cover_size - 1, //----cover_mask
+ cover_none = 0, //----cover_none
+ cover_full = cover_mask //----cover_full
};
//----------------------------------------------------poly_subpixel_scale_e
- // These constants determine the subpixel accuracy, to be more precise,
- // the number of bits of the fractional part of the coordinates.
+ // These constants determine the subpixel accuracy, to be more precise,
+ // the number of bits of the fractional part of the coordinates.
// The possible coordinate capacity in bits can be calculated by formula:
// sizeof(int) * 8 - poly_subpixel_shift, i.e, for 32-bit integers and
// 8-bits fractional part the capacity is 24 bits.
enum poly_subpixel_scale_e
{
poly_subpixel_shift = 8, //----poly_subpixel_shift
- poly_subpixel_scale = 1<<poly_subpixel_shift, //----poly_subpixel_scale
- poly_subpixel_mask = poly_subpixel_scale-1, //----poly_subpixel_mask
+ poly_subpixel_scale = 1<<poly_subpixel_shift, //----poly_subpixel_scale
+ poly_subpixel_mask = poly_subpixel_scale-1 //----poly_subpixel_mask
};
//----------------------------------------------------------filling_rule_e
@@ -253,7 +253,7 @@
{
return rad * 180.0 / pi;
}
-
+
//----------------------------------------------------------------rect_base
template<class T> struct rect_base
{
@@ -265,9 +265,9 @@
rect_base(T x1_, T y1_, T x2_, T y2_) :
x1(x1_), y1(y1_), x2(x2_), y2(y2_) {}
- void init(T x1_, T y1_, T x2_, T y2_)
+ void init(T x1_, T y1_, T x2_, T y2_)
{
- x1 = x1_; y1 = y1_; x2 = x2_; y2 = y2_;
+ x1 = x1_; y1 = y1_; x2 = x2_; y2 = y2_;
}
const self_type& normalize()
@@ -299,17 +299,17 @@
};
//-----------------------------------------------------intersect_rectangles
- template<class Rect>
+ template<class Rect>
inline Rect intersect_rectangles(const Rect& r1, const Rect& r2)
{
Rect r = r1;
- // First process x2,y2 because the other order
- // results in Internal Compiler Error under
- // Microsoft Visual C++ .NET 2003 69462-335-0000007-18038 in
+ // First process x2,y2 because the other order
+ // results in Internal Compiler Error under
+ // Microsoft Visual C++ .NET 2003 69462-335-0000007-18038 in
// case of "Maximize Speed" optimization option.
//-----------------
- if(r.x2 > r2.x2) r.x2 = r2.x2;
+ if(r.x2 > r2.x2) r.x2 = r2.x2;
if(r.y2 > r2.y2) r.y2 = r2.y2;
if(r.x1 < r2.x1) r.x1 = r2.x1;
if(r.y1 < r2.y1) r.y1 = r2.y1;
@@ -318,7 +318,7 @@
//---------------------------------------------------------unite_rectangles
- template<class Rect>
+ template<class Rect>
inline Rect unite_rectangles(const Rect& r1, const Rect& r2)
{
Rect r = r1;
@@ -336,26 +336,26 @@
//---------------------------------------------------------path_commands_e
enum path_commands_e
{
- path_cmd_stop = 0, //----path_cmd_stop
- path_cmd_move_to = 1, //----path_cmd_move_to
- path_cmd_line_to = 2, //----path_cmd_line_to
- path_cmd_curve3 = 3, //----path_cmd_curve3
- path_cmd_curve4 = 4, //----path_cmd_curve4
+ path_cmd_stop = 0, //----path_cmd_stop
+ path_cmd_move_to = 1, //----path_cmd_move_to
+ path_cmd_line_to = 2, //----path_cmd_line_to
+ path_cmd_curve3 = 3, //----path_cmd_curve3
+ path_cmd_curve4 = 4, //----path_cmd_curve4
path_cmd_curveN = 5, //----path_cmd_curveN
path_cmd_catrom = 6, //----path_cmd_catrom
path_cmd_ubspline = 7, //----path_cmd_ubspline
path_cmd_end_poly = 0x0F, //----path_cmd_end_poly
- path_cmd_mask = 0x0F //----path_cmd_mask
+ path_cmd_mask = 0x0F //----path_cmd_mask
};
//------------------------------------------------------------path_flags_e
enum path_flags_e
{
- path_flags_none = 0, //----path_flags_none
- path_flags_ccw = 0x10, //----path_flags_ccw
- path_flags_cw = 0x20, //----path_flags_cw
+ path_flags_none = 0, //----path_flags_none
+ path_flags_ccw = 0x10, //----path_flags_ccw
+ path_flags_cw = 0x20, //----path_flags_cw
path_flags_close = 0x40, //----path_flags_close
- path_flags_mask = 0xF0 //----path_flags_mask
+ path_flags_mask = 0xF0 //----path_flags_mask
};
//---------------------------------------------------------------is_vertex
@@ -372,7 +372,7 @@
//-----------------------------------------------------------------is_stop
inline bool is_stop(unsigned c)
- {
+ {
return c == path_cmd_stop;
}
@@ -416,7 +416,7 @@
inline bool is_close(unsigned c)
{
return (c & ~(path_flags_cw | path_flags_ccw)) ==
- (path_cmd_end_poly | path_flags_close);
+ (path_cmd_end_poly | path_flags_close);
}
//------------------------------------------------------------is_next_poly
@@ -440,19 +440,19 @@
//-------------------------------------------------------------is_oriented
inline bool is_oriented(unsigned c)
{
- return (c & (path_flags_cw | path_flags_ccw)) != 0;
+ return (c & (path_flags_cw | path_flags_ccw)) != 0;
}
//---------------------------------------------------------------is_closed
inline bool is_closed(unsigned c)
{
- return (c & path_flags_close) != 0;
+ return (c & path_flags_close) != 0;
}
//----------------------------------------------------------get_close_flag
inline unsigned get_close_flag(unsigned c)
{
- return c & path_flags_close;
+ return c & path_flags_close;
}
//-------------------------------------------------------clear_orientation
@@ -513,7 +513,7 @@
int x1, x2;
const T* ptr;
const_row_info() {}
- const_row_info(int x1_, int x2_, const T* ptr_) :
+ const_row_info(int x1_, int x2_, const T* ptr_) :
x1(x1_), x2(x2_), ptr(ptr_) {}
};
Added: branches/v0_99_maint/doc/pyplots/annotate_transform.py
===================================================================
--- branches/v0_99_maint/doc/pyplots/annotate_transform.py (rev 0)
+++ branches/v0_99_maint/doc/pyplots/annotate_transform.py 2009-08-15 17:56:44 UTC (rev 7490)
@@ -0,0 +1,34 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+x = np.arange(0, 10, 0.005)
+y = np.exp(-x/2.) * np.sin(2*np.pi*x)
+
+fig = plt.figure()
+ax = fig.add_subplot(111)
+ax.plot(x, y)
+ax.set_xlim(0, 10)
+ax.set_ylim(-1, 1)
+
+xdata, ydata = 5, 0
+xdisplay, ydisplay = ax.transData.transform((xdata, ydata))
+
+bbox = dict(boxstyle="round", fc="0.8")
+arrowprops = dict(
+ arrowstyle = "->",
+ connectionstyle = "angle,angleA=0,angleB=90,rad=10")
+
+offset = 72
+ax.annotate('data = (%.1f, %.1f)'%(xdata, ydata),
+ (xdata, ydata), xytext=(-2*offset, offset), textcoords='offset points',
+ bbox=bbox, arrowprops=arrowprops)
+
+
+disp = ax.annotate('display = (%.1f, %.1f)'%(xdisplay, ydisplay),
+ (xdisplay, ydisplay), xytext=(0.5*offset, -offset),
+ xycoords='figure pixels',
+ textcoords='offset points',
+ bbox=bbox, arrowprops=arrowprops)
+
+
+plt.show()
Copied: branches/v0_99_maint/doc/users/annotations_intro.rst (from rev 7489, branches/v0_99_maint/doc/users/annotations_overview.rst)
===================================================================
--- branches/v0_99_maint/doc/users/annotations_intro.rst (rev 0)
+++ branches/v0_99_maint/doc/users/annotations_intro.rst 2009-08-15 17:56:44 UTC (rev 7490)
@@ -0,0 +1,87 @@
+.. _annotations-tutorial:
+
+Annotating text
+===============
+
+For a more detailed introduction to annotations, see
+:ref:`plotting-guide-annotation`.
+
+The uses of the basic :func:`~matplotlib.pyplot.text` command above
+place text at an arbitrary position on the Axes. A common use case of
+text is to annotate some feature of the plot, and the
+:func:`~matplotlib.Axes.annotate` method provides helper functionality
+to make annotations easy. In an annotation, there are two points to
+consider: the location being annotated represented by the argument
+``xy`` and the location of the text ``xytext``. Both of these
+arguments are ``(x,y)`` tuples.
+
+.. plot:: pyplots/annotation_basic.py
+ :include-source:
+
+
+In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
+(text location) are in data coordinates. There are a variety of other
+coordinate systems one can choose -- you can specify the coordinate
+system of ``xy`` and ``xytext`` with one of the following strings for
+``xycoords`` and ``textcoords`` (default is 'data')
+
+==================== ====================================================
+argument coordinate system
+==================== ====================================================
+ 'figure points' points from the lower left corner of the figure
+ 'figure pixels' pixels from the lower left corner of the figure
+ 'figure fraction' 0,0 is lower left of figure and 1,1 is upper, right
+ 'axes points' points from lower left corner of axes
+ 'axes pixels' pixels from lower left corner of axes
+ 'axes fraction' 0,1 is lower left of axes and 1,1 is upper right
+ 'data' use the axes data coordinate system
+==================== ====================================================
+
+For example to place the text coordinates in fractional axes
+coordinates, one could do::
+
+ ax.annotate('local max', xy=(3, 1), xycoords='data',
+ xytext=(0.8, 0.95), textcoords='axes fraction',
+ arrowprops=dict(facecolor='black', shrink=0.05),
+ horizontalalignment='right', verticalalignment='top',
+ )
+
+For physical coordinate systems (points or pixels) the origin is the
+(bottom, left) of the figure or axes. If the value is negative,
+however, the origin is from the (right, top) of the figure or axes,
+analogous to negative indexing of sequences.
+
+Optionally, you can specify arrow properties which draws an arrow
+from the text to the annotated point by giving a dictionary of arrow
+properties in the optional keyword argument ``arrowprops``.
+
+
+==================== =====================================================
+``arrowprops`` key description
+==================== =====================================================
+width the width of the arrow in points
+frac the fraction of the arrow length occupied by the head
+headwidth the width of the base of the arrow head in points
+shrink move the tip and base some percent away from
+ the annotated point and text
+
+\*\*kwargs any key for :class:`matplotlib.patches.Polygon`,
+ e.g. ``facecolor``
+==================== =====================================================
+
+
+In the example below, the ``xy`` point is in native coordinates
+(``xycoords`` defaults to 'data'). For a polar axes, this is in
+(theta, radius) space. The text in this example is placed in the
+fractional figure coordinate system. :class:`matplotlib.text.Text`
+keyword args like ``horizontalalignment``, ``verticalalignment`` and
+``fontsize are passed from the `~matplotlib.Axes.annotate` to the
+``Text`` instance
+
+.. plot:: pyplots/annotation_polar.py
+ :include-source:
+
+For more on all the wild and wonderful things you can do with
+annotations, including fancy arrows, see :ref:`plotting-guide-annotation`
+and :ref:`pylab_examples-annotation_demo`.
+
Deleted: branches/v0_99_maint/doc/users/annotations_overview.rst
===================================================================
--- branches/v0_99_maint/doc/users/annotations_overview.rst 2009-08-15 17:40:27 UTC (rev 7489)
+++ branches/v0_99_maint/doc/users/annotations_overview.rst 2009-08-15 17:56:44 UTC (rev 7490)
@@ -1,87 +0,0 @@
-.. _annotations-tutorial:
-
-Annotating text
-===============
-
-For a more detailed introduction to annotations, see
-:ref:`plotting-guide-annotation`.
-
-The uses of the basic :func:`~matplotlib.pyplot.text` command above
-place text at an arbitrary position on the Axes. A common use case of
-text is to annotate some feature of the plot, and the
-:func:`~matplotlib.Axes.annotate` method provides helper functionality
-to make annotations easy. In an annotation, there are two points to
-consider: the location being annotated represented by the argument
-``xy`` and the location of the text ``xytext``. Both of these
-arguments are ``(x,y)`` tuples.
-
-.. plot:: pyplots/annotation_basic.py
- :include-source:
-
-
-In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
-(text location) are in data coordinates. There are a variety of other
-coordinate systems one can choose -- you can specify the coordinate
-system of ``xy`` and ``xytext`` with one of the following strings for
-``xycoords`` and ``textcoords`` (default is 'data')
-
-==================== ====================================================
-argument coordinate system
-==================== ====================================================
- 'figure points' points from the lower left corner of the figure
- 'figure pixels' pixels from the lower left corner of the figure
- 'figure fraction' 0,0 is lower left of figure and 1,1 is upper, right
- 'axes points' points from lower left corner of axes
- 'axes pixels' pixels from lower left corner of axes
- 'axes fraction' 0,1 is lower left of axes and 1,1 is upper right
- 'data' use the axes data coordinate system
-==================== ====================================================
-
-For example to place the text coordinates in fractional axes
-coordinates, one could do::
-
- ax.annotate('local max', xy=(3, 1), xycoords='data',
- xytext=(0.8, 0.95), textcoords='axes fraction',
- arrowprops=dict(facecolor='black', shrink=0.05),
- horizontalalignment='right', verticalalignment='top',
- )
-
-For physical coordinate systems (points or pixels) the origin is the
-(bottom, left) of the figure or axes. If the value is negative,
-however, the origin is from the (right, top) of the figure or axes,
-analogous to negative indexing of sequences.
-
-Optionally, you can specify arrow properties which draws an arrow
-from the text to the annotated point by giving a dictionary of arrow
-properties in the optional keyword argument ``arrowprops``.
-
-
-==================== =====================================================
-``arrowprops`` key description
-==================== =====================================================
-width the width of the arrow in points
-frac the fraction of the arrow length occupied by the head
-headwidth the width of the base of the arrow head in points
-shrink move the tip and base some percent away from
- the annotated point and text
-
-\*\*kwargs any key for :class:`matplotlib.patches.Polygon`,
- e.g. ``facecolor``
-==================== =====================================================
-
-
-In the example below, the ``xy`` point is in native coordinates
-(``xycoords`` defaults to 'data'). For a polar axes, this is in
-(theta, radius) space. The text in this example is placed in the
-fractional figure coordinate system. :class:`matplotlib.text.Text`
-keyword args like ``horizontalalignment``, ``verticalalignment`` and
-``fontsize are passed from the `~matplotlib.Axes.annotate` to the
-``Text`` instance
-
-.. plot:: pyplots/annotation_polar.py
- :include-source:
-
-For more on all the wild and wonderful things you can do with
-annotations, including fancy arrows, see :ref:`plotting-guide-annotation`
-and :ref:`pylab_examples-annotation_demo`.
-
Modified: branches/v0_99_maint/doc/users/index.rst
===================================================================
--- branches/v0_99_maint/doc/users/index.rst 2009-08-15 17:40:27 UTC (rev 7489)
+++ branches/v0_99_maint/doc/users/index.rst 2009-08-15 17:56:44 UTC (rev 7490)
@@ -22,7 +22,7 @@
artists.rst
legend_guide.rst
event_handling.rst
- annotation_guide.rst
+ annotations_guide.rst
legend.rst
transforms_tutorial.rst
toolkits.rst
Deleted: branches/v0_99_maint/doc/users/legend.rst
===================================================================
--- branches/v0_99_maint/doc/users/legend.rst 2009-08-15 17:40:27 UTC (rev 7489)
+++ branches/v0_99_maint/doc/users/legend.rst 2009-08-15 17:56:44 UTC (rev 7490)
@@ -1,182 +0,0 @@
-.. _plotting-guide-legend:
-
-************
-Legend guide
-************
-
-Do not proceed unless you already have read :func:`~matplotlib.pyplot.legend` and
-:class:`matplotlib.legend.Legend`!
-
-
-What to be displayed
-====================
-
-The legend command has a following call signature::
-
- legend(*args, **kwargs)
-
-If len(args) is 2, the first argument should be a list of artist to be
-labeled, and the second argument should a list of string labels. If
-len(args) is 0, it automatically generate the legend from label
-properties of the child artists by calling
-:meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method.
-For example, *ax.legend()* is equivalent to::
-
- handles, labels = ax.get_legend_handles_labels()
- ax.legend(handles, labels)
-
-The :meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method
-returns a tuple of two lists, i.e., list of artists and list of labels
-(python string). However, it does not return all of its child
-artists. It returns all artists in *ax.lines* and *ax.patches* and
-some artists in *ax.collection* which are instance of
-:class:`~matplotlib.collections.LineCollection` or
-:class:`~matplotlib.collections.RegularPolyCollection`. The label
-attributes (returned by get_label() method) of collected artists are
-used as text labels. If label attribute is empty string or starts with
-"_", that artist will be ignored.
-
-
- * Note that not all kind of artists are supported by the legend. The
- following is the list of artists that are currently supported.
-
- * :class:`~matplotlib.lines.Line2D`
- * :class:`~matplotlib.patches.Patch`
- * :class:`~matplotlib.collections.LineCollection`
- * :class:`~matplotlib.collections.RegularPolyCollection`
-
- Unfortunately, there is no easy workaround when you need legend for
- an artist not in the above list (You may use one of the supported
- artist as a proxy. See below), or customize it beyond what is
- supported by :class:`matplotlib.legend.Legend`.
-
- * Remember that some *pyplot* commands return artist not supported by
- legend, e.g., :func:`~matplotlib.pyplot.fill_between` returns
- :class:`~matplotlib.collections.PolyCollection` that is not
- supported. Or some return multiple artists. For example,
- :func:`~matplotlib.pyplot.plot` returns list of
- :class:`~matplotlib.lines.Line2D` instances, and
- :func:`~matplotlib.pyplot.errorbar` returns a length 3 tuple of
- :class:`~matplotlib.lines.Line2D` instances.
-
- * The legend does not care about the axes that given artists belongs,
- i.e., the artists may belong to other axes or even none.
-
-
-Adjusting the Order of Legend items
------------------------------------
-
-When you want to customize the list of artists to be displayed in the
-legend, or their order of appearance. There are a two options. First,
-you can keep lists of artists and labels, and explicitly use these for
-the first two argument of the legend call.::
-
- p1, = plot([1,2,3])
- p2, = plot([3,2,1])
- p3, = plot([2,3,1])
- legend([p2, p1], ["line 2", "line 1"])
-
-Or you may use :meth:`~matplotlib.axes.Axes.get_legend_handles_labels`
-to retrieve list of artist and labels and manipulate them before
-feeding them to legend call.::
-
- ax = subplot(1,1,1)
- p1, = ax.plot([1,2,3], label="line 1")
- p2, = ax.plot([3,2,1], label="line 2")
- p3, = ax.plot([2,3,1], label="line 3")
-
- handles, labels = ax.get_legend_handles_labels()
-
- # reverse the order
- ax.legend(handles[::-1], labels[::-1])
-
- # or sort them by labels
- import operator
- hl = sorted(zip(handles, labels),
- key=operator.itemgetter(1))
- handles2, labels2 = zip(*hl)
-
- ax.legend(handles2, labels2)
-
-
-Using Proxy Artist
-------------------
-
-When you want to display legend for an artist not supported by the
-matplotlib, you may use other supported artist as a proxy. For
-example, you may creates an proxy artist without adding it to the axes
-(so the proxy artist will not be drawn in the main axes) and feet it
-to the legend function.::
-
- p = Rectangle((0, 0), 1, 1, fc="r")
- legend([p], ["Red Rectangle"])
-
-
-Multicolumn Legend
-==================
-
-By specifying the keyword argument *ncol*, you can have a multi-column
-legend. Also, mode="expand" horizontally expand the legend to fill the
-axes area. See `legend_demo3.py
-<http://matplotlib.sourceforge.net/examples/pylab_examples/legend_demo3.html>`_
-for example.
-
-
-Legend location
-===============
-
-The location of the legend can be specified by the keyword argument
-*loc*, either by string or a integer number.
-
-============= ======
- String Number
-============= ======
- upper right 1
- upper left 2
- lower left 3
- lower right 4
- right 5
- center left 6
- center right 7
- lower center 8
- upper center 9
- center 10
-============= ======
-
-By default, the legend will anchor to the bbox of the axes
-(for legend) or the bbox of the figure (figlegend). You can specify
-your own bbox using *bbox_to_anchor* argument. *bbox_to_anchor* can be an
-instance of :class:`~matplotlib.transforms.BboxBase`, a tuple of 4
-floats (x, y, width, height of the bbox), or a tuple of 2 floats (x, y
-with width=height=0). Unless *bbox_transform* argument is given, the
-coordinates (even for the bbox instance) are considered as normalized
-axes coordinates.
-
-For example, if you want your axes legend located at the figure corner
-(instead of the axes corner)::
-
- l = legend(bbox_to_anchor=(0, 0, 1, 1), transform=gcf().transFigure)
-
-Also, you can place above or outer right-hand side of the axes,
-
-.. plot:: users/plotting/examples/simple_legend01.py
- :include-source:
-
-
-Multiple Legend
-===============
-
-Sometime, you want to split the legend into multiple ones.::
-
- p1, = plot([1,2,3])
- p2, = plot([3,2,1])
- legend([p1], ["Test1"], loc=1)
- legend([p2], ["Test2"], loc=4)
-
-However, the above code only shows the second legend. When the legend
-command is called, a new legend instance is created and old ones are
-removed from the axes. Thus, you need to manually add the removed
-legend.
-
-.. plot:: users/plotting/examples/simple_legend02.py
- :include-source:
Copied: branches/v0_99_maint/doc/users/legend_guide.rst (from rev 7489, branches/v0_99_maint/doc/users/legend.rst)
===================================================================
--- branches/v0_99_maint/doc/users/legend_guide.rst (rev 0)
+++ branches/v0_99_maint/doc/users/legend_guide.rst 2009-08-15 17:56:44 UTC (rev 7490)
@@ -0,0 +1,182 @@
+.. _plotting-guide-legend:
+
+************
+Legend guide
+************
+
+Do not proceed unless you already have read :func:`~matplotlib.pyplot.legend` and
+:class:`matplotlib.legend.Legend`!
+
+
+What to be displayed
+====================
+
+The legend command has a following call signature::
+
+ legend(*args, **kwargs)
+
+If len(args) is 2, the first argument should be a list of artist to be
+labeled, and the second argument should a list of string labels. If
+len(args) is 0, it automatically generate the legend from label
+properties of the child artists by calling
+:meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method.
+For example, *ax.legend()* is equivalent to::
+
+ handles, labels = ax.get_legend_handles_labels()
+ ax.legend(handles, labels)
+
+The :meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method
+returns a tuple of two lists, i.e., list of artists and list of labels
+(python string). However, it does not return all of its child
+artists. It returns all artists in *ax.lines* and *ax.patches* and
+some artists in *ax.collection* which are instance of
+:class:`~matplotlib.collections.LineCollection` or
+:class:`~matplotlib.collections.RegularPolyCollection`. The label
+attributes (returned by get_label() method) of collected artists are
+used as text labels. If label attribute is empty string or starts with
+"_", that artist will be ignored.
+
+
+ * Note that not all kind of artists are supported by the legend. The
+ following is the list of artists that are currently supported.
+
+ * :class:`~matplotlib.lines.Line2D`
+ * :class:`~matplotlib.patches.Patch`
+ * :class:`~matplotlib.collections.LineCollection`
+ * :class:`~matplotlib.collections.RegularPolyCollection`
+
+ Unfortunately, there is no easy workaround when you need legend for
+ an artist not in the above list (You may use one of the supported
+ artist as a proxy. See below), or customize it beyond what is
+ supported by :class:`matplotlib.legend.Legend`.
+
+ * Remember that some *pyplot* commands return artist not supported by
+ legend, e.g., :func:`~matplotlib.pyplot.fill_between` returns
+ :class:`~matplotlib.collections.PolyCollection` that is not
+ supported. Or some return multiple artists. For example,
+ :func:`~matplotlib.pyplot.plot` returns list of
+ :class:`~matplotlib.lines.Line2D` instances, and
+ :func:`~matplotlib.pyplot.errorbar` returns a length 3 tuple of
+ :class:`~matplotlib.lines.Line2D` instances.
+
+ * The legend does not care about the axes that given artists belongs,
+ i.e., the artists may belong to other axes or even none.
+
+
+Adjusting the Order of Legend items
+-----------------------------------
+
+When you want to customize the list of artists to be displayed in the
+legend, or their order of appearance. There are a two options. First,
+you can keep lists of artists and labels, and explicitly use these for
+the first two argument of the legend call.::
+
+ p1, = plot([1,2,3])
+ p2, = plot([3,2,1])
+ p3, = plot([2,3,1])
+ legend([p2, p1], ["line 2", "line 1"])
+
+Or you may use :meth:`~matplotlib.axes.Axes.get_legend_handles_labels`
+to retrieve list of artist and labels and manipulate them before
+feeding them to legend call.::
+
+ ax = subplot(1,1,1)
+ p1, = ax.plot([1,2,3], label="line 1")
+ p2, = ax.plot([3,2,1], label="line 2")
+ p3, = ax.plot([2,3,1], label="line 3")
+
+ handles, labels = ax.get_legend_handles_labels()
+
+ # reverse the order
+ ax.legend(handles[::-1], labels[::-1])
+
+ # or sort them by labels
+ import operator
+ hl = sorted(zip(handles, labels),
+ key=operator.itemgetter(1))
+ handles2, labels2 = zip(*hl)
+
+ ax.legend(handles2, labels2)
+
+
+Using Proxy Artist
+------------------
+
+When you want to display legend for an artist not supported by the
+matplotlib, you may use other supported artist as a proxy. For
+example, you may creates an proxy artist without adding it to the axes
+(so the proxy artist will not be drawn in the main axes) and feet it
+to the legend function.::
+
+ p = Rectangle((0, 0), 1, 1, fc="r")
+ legend([p], ["Red Rectangle"])
+
+
+Multicolumn Legend
+==================
+
+By specifying the keyword argument *ncol*, you can have a multi-column
+legend. Also, mode="expand" horizontally expand the legend to fill the
+axes area. See `legend_demo3.py
+<http://matplotlib.sourceforge.net/examples/pylab_examples/legend_demo3.html>`_
+for example.
+
+
+Legend location
+===============
+
+The location of the legend can be specified by the keyword argument
+*loc*, either by string or a integer number.
+
+============= ======
+ String Number
+============= ======
+ upper right 1
+ upper left 2
+ lower left 3
+ lower right 4
+ right 5
+ center left 6
+ center right 7
+ lower center 8
+ upper center 9
+ center 10
+============= ======
+
+By default, the legend will anchor to the bbox of the axes
+(for legend) or the bbox of the figure (figlegend). You can specify
+your own bbox using *bbox_to_anchor* argument. *bbox_to_anchor* can be an
+instance of :class:`~matplotlib.transforms.BboxBase`, a tuple of 4
+floats (x, y, width, height of the bbox), or a tuple of 2 floats (x, y
+with width=height=0). Unless *bbox_transform* argument is given, the
+coordinates (even for the bbox instance) are considered as normalized
+axes coordinates.
+
+For example, if you want your axes legend located at the figure corner
+(instead of the axes corner)::
+
+ l = legend(bbox_to_anchor=(0, 0, 1, 1), transform=gcf().transFigure)
+
+Also, you can place above or outer right-hand side of the axes,
+
+.. plot:: users/plotting/examples/simple_legend01.py
+ :include-source:
+
+
+Multiple Legend
+===============
+
+Sometime, you want to split the legend into multiple ones.::
+
+ p1, = plot([1,2,3])
+ p2, = plot([3,2,1])
+ legend([p1], ["Test1"], loc=1)
+ legend([p2], ["Test2"], loc=4)
+
+However, the above code only shows the second legend. When the legend
+command is called, a new legend instance is created and old ones are
+removed from the axes. Thus, you need to manually add the removed
+legend.
+
+.. plot:: users/plotting/examples/simple_legend02.py
+ :include-source:
Modified: branches/v0_99_maint/doc/users/transforms_tutorial.rst
===================================================================
--- branches/v0_99_maint/doc/users/transforms_tutorial.rst 2009-08-15 17:40:27 UTC (rev 7489)
+++ branches/v0_99_maint/doc/users/transforms_tutorial.rst 2009-08-15 17:56:44 UTC (rev 7490)
@@ -12,7 +12,7 @@
happens under the hood, but as you push the limits of custom figure
generation, it helps to have an understanding of these objects so you
can reuse the existing transformations matplotlib makes available to
-you, or create your own. The table below summarizes the existing
+you, or create your own (see :mod:`matplotlib.transforms`. The table below summarizes the existing
coordinate systems, the transformation object you should use to work
in that coordinate system, and the description of that system. In the
`Transformation Object` column, ``ax`` is a :class:`~matplotlib.axes.Axes` instance,
@@ -276,7 +276,8 @@
it, adjusting the zorder to make sure the shadow is drawn first and
then the object it is shadowing above it. The transforms module has a
helper transformation
-:class:~matplotlib.tranasforms.ScaledTranslation`. It is instantiated with::
+:class:`~matplotlib.transforms.ScaledTranslation`. It is
+instantiated with::
trans = ScaledTranslation(xt, yt, scale_trans)
@@ -287,7 +288,7 @@
to first scale `xty and `yt` specified in points to `display` space
before doing the final offset. The dpi and inches offset is a
common-enough use case that we have a special helper function to
-create it in :func:`~matplotlib.transforms.offset_copy`, which returns
+create it in :func:`matplotlib.transforms.offset_copy`, which returns
a new transform with an added offset. But in the example below, we'll
create the offset trransform ourselves. Note the use of the plus
operator in::
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
