Revision: 8163
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8163&view=rev
Author: leejjoon
Date: 2010-02-28 03:13:39 +0000 (Sun, 28 Feb 2010)
Log Message:
-----------
update annotation guide
Modified Paths:
--------------
trunk/matplotlib/doc/users/annotations_guide.rst
trunk/matplotlib/examples/pylab_examples/annotation_demo3.py
trunk/matplotlib/lib/matplotlib/text.py
Added Paths:
-----------
trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord01.py
trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord02.py
trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord03.py
Modified: trunk/matplotlib/doc/users/annotations_guide.rst
===================================================================
--- trunk/matplotlib/doc/users/annotations_guide.rst 2010-02-27 17:00:53 UTC
(rev 8162)
+++ trunk/matplotlib/doc/users/annotations_guide.rst 2010-02-28 03:13:39 UTC
(rev 8163)
@@ -4,10 +4,13 @@
Annotating Axes
****************
-Do not proceed unless you already have read
-:func:`~matplotlib.pyplot.text` and :func:`~matplotlib.pyplot.annotate`!
+Do not proceed unless you already have read :ref:`annotations-tutorial`,
+:func:`~matplotlib.pyplot.text` and
+:func:`~matplotlib.pyplot.annotate`!
+
+
Annotating with Text with Box
=============================
@@ -182,31 +185,6 @@
.. plot:: users/plotting/examples/annotate_simple04.py
-Using ConnectorPatch
-====================
-
-The ConnectorPatch is like an annotation without a text. While the
-annotate function is recommended in most of situation, the
-ConnectorPatch is useful when you want to connect points in different
-axes. ::
-
- from matplotlib.patches import ConnectionPatch
- xy = (0.2, 0.2)
- con = ConnectionPatch(xyA=xy, xyB=xy, coordsA="data", coordsB="data",
- axesA=ax1, axesB=ax2)
- ax2.add_artist(con)
-
-The above code connects point xy in data coordinate of ``ax1`` to
-point xy int data coordinate of ``ax2``. Here is a simple example.
-
-.. plot:: users/plotting/examples/connect_simple01.py
-
-
-While the ConnectorPatch instance can be added to any axes, but you
-may want it to be added to the axes in the latter (?) of the axes
-drawing order to prevent overlap (?) by other axes.
-
-
Placing Artist at the anchored location of the Axes
===================================================
@@ -282,6 +260,111 @@
Note that unlike the legend, the ``bbox_transform`` is set
to IdentityTransform by default.
+Using Complex Coordinate with Annotation
+========================================
+
+The Annotation in matplotlib support several types of coordinate as
+described in :ref:`annotations-tutorial`. For an advanced user who wants
+more control, it supports a few other options.
+
+ 1. :class:`~matplotlib.transforms.Transform` instance. For example, ::
+
+ ax.annotate("Test", xy=(0.5, 0.5), xycoords=ax.transAxes)
+
+ is identical to ::
+
+ ax.annotate("Test", xy=(0.5, 0.5), xycoords="axes fraction")
+
+ With this, you can annotate a point in other axes. ::
+
+ ax1, ax2 = subplot(121), subplot(122)
+ ax2.annotate("Test", xy=(0.5, 0.5), xycoords=ax1.transData,
+ xytext=(0.5, 0.5), textcoords=ax2.transData,
+ arrowprops=dict(arrowstyle="->"))
+
+ 2. :class:`~matplotlib.artist.Artist` instance. The xy value (or
+ xytext) is interpreted as a fractional coordinate of the bbox
+ (return value of *get_window_extent*) of the artist. ::
+
+ an1 = ax.annotate("Test 1", xy=(0.5, 0.5), xycoords="data",
+ va="center", ha="center",
+ bbox=dict(boxstyle="round", fc="w"))
+ an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1, # (1,0.5) of the
an1's bbox
+ xytext=(30,0), textcoords="offset points",
+ va="center", ha="left",
+ bbox=dict(boxstyle="round", fc="w"),
+ arrowprops=dict(arrowstyle="->"))
+
+ .. plot:: users/plotting/examples/annotate_simple_coord01.py
+
+ Note that it is your responsibility that the extent of the
+ coordinate artist (*an1* in above example) is determined before *an2*
+ gets drawn. In most cases, it means that an2 needs to be drawn
+ later than *an1*.
+
+
+ 3. A callable object that returns an instance of either
+ :class:`~matplotlib.transforms.BboxBase` or
+ :class:`~matplotlib.transforms.Transform`. If a transform is
+ returned, it is same as 1 and if bbox is returned, it is same
+ as 2. The callable object should take a single argument of
+ renderer instance. For example, following two commands give
+ identical results ::
+ an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1,
+ xytext=(30,0), textcoords="offset points")
+ an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1.get_window_extent,
+ xytext=(30,0), textcoords="offset points")
+
+
+ 4. A tuple of two coordinate specification. The first item is for
+ x-coordinate and the second is for y-coordinate. For example, ::
+
+ annotate("Test", xy=(0.5, 1), xycoords=("data", "axes fraction"))
+
+ 0.5 is in data coordinate, and 1 is in normalized axes coordinate.
+ You may use an atist or transform as with a tuple. For example,
+
+ .. plot:: users/plotting/examples/annotate_simple_coord02.py
+ :include-source:
+
+
+ 5. Sometimes, you want your annotation with some "offset points", but
+ not from the annotated point but from other
+ point. :class:`~matplotlib.text.OffsetFrom` is a helper class for such
+ case.
+
+ .. plot:: users/plotting/examples/annotate_simple_coord03.py
+ :include-source:
+
+ You may take a look at this example :ref:`pylab_examples-annotation_demo3`.
+
+Using ConnectorPatch
+====================
+
+The ConnectorPatch is like an annotation without a text. While the
+annotate function is recommended in most of situation, the
+ConnectorPatch is useful when you want to connect points in different
+axes. ::
+
+ from matplotlib.patches import ConnectionPatch
+ xy = (0.2, 0.2)
+ con = ConnectionPatch(xyA=xy, xyB=xy, coordsA="data", coordsB="data",
+ axesA=ax1, axesB=ax2)
+ ax2.add_artist(con)
+
+The above code connects point xy in data coordinate of ``ax1`` to
+point xy int data coordinate of ``ax2``. Here is a simple example.
+
+.. plot:: users/plotting/examples/connect_simple01.py
+
+
+While the ConnectorPatch instance can be added to any axes, but you
+may want it to be added to the axes in the latter (?) of the axes
+drawing order to prevent overlap (?) by other axes.
+
+
+
+
Advanced Topics
***************
Added: trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord01.py
===================================================================
--- trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord01.py
(rev 0)
+++ trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord01.py
2010-02-28 03:13:39 UTC (rev 8163)
@@ -0,0 +1,15 @@
+
+import matplotlib.pyplot as plt
+
+plt.figure(figsize=(3,2))
+ax=plt.subplot(111)
+an1 = ax.annotate("Test 1", xy=(0.5, 0.5), xycoords="data",
+ va="center", ha="center",
+ bbox=dict(boxstyle="round", fc="w"))
+an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1,
+ xytext=(30,0), textcoords="offset points",
+ va="center", ha="left",
+ bbox=dict(boxstyle="round", fc="w"),
+ arrowprops=dict(arrowstyle="->"))
+plt.show()
+
Added: trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord02.py
===================================================================
--- trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord02.py
(rev 0)
+++ trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord02.py
2010-02-28 03:13:39 UTC (rev 8163)
@@ -0,0 +1,16 @@
+
+import matplotlib.pyplot as plt
+
+plt.figure(figsize=(3,2))
+ax=plt.axes([0.1, 0.1, 0.8, 0.7])
+an1 = ax.annotate("Test 1", xy=(0.5, 0.5), xycoords="data",
+ va="center", ha="center",
+ bbox=dict(boxstyle="round", fc="w"))
+
+an2 = ax.annotate("Test 2", xy=(0.5, 1.), xycoords=an1,
+ xytext=(0.5,1.1), textcoords=(an1, "axes fraction"),
+ va="bottom", ha="center",
+ bbox=dict(boxstyle="round", fc="w"),
+ arrowprops=dict(arrowstyle="->"))
+plt.show()
+
Added: trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord03.py
===================================================================
--- trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord03.py
(rev 0)
+++ trunk/matplotlib/doc/users/plotting/examples/annotate_simple_coord03.py
2010-02-28 03:13:39 UTC (rev 8163)
@@ -0,0 +1,19 @@
+
+import matplotlib.pyplot as plt
+
+plt.figure(figsize=(3,2))
+ax=plt.axes([0.1, 0.1, 0.8, 0.7])
+an1 = ax.annotate("Test 1", xy=(0.5, 0.5), xycoords="data",
+ va="center", ha="center",
+ bbox=dict(boxstyle="round", fc="w"))
+
+from matplotlib.text import OffsetFrom
+offset_from = OffsetFrom(an1, (0.5, 0))
+an2 = ax.annotate("Test 2", xy=(0.1, 0.1), xycoords="data",
+ xytext=(0, -10), textcoords=offset_from,
+ # xytext is offset points from "xy=(0.5, 0), xycoords=an1"
+ va="top", ha="center",
+ bbox=dict(boxstyle="round", fc="w"),
+ arrowprops=dict(arrowstyle="->"))
+plt.show()
+
Modified: trunk/matplotlib/examples/pylab_examples/annotation_demo3.py
===================================================================
--- trunk/matplotlib/examples/pylab_examples/annotation_demo3.py
2010-02-27 17:00:53 UTC (rev 8162)
+++ trunk/matplotlib/examples/pylab_examples/annotation_demo3.py
2010-02-28 03:13:39 UTC (rev 8163)
@@ -76,17 +76,16 @@
from matplotlib.text import OffsetFrom
-ax2.annotate('xy=(0.5, 0)\nxycoords="bbox fraction"\nxybbox=artist',
- xy=(0.5, 0.), xycoords=t.get_window_extent,
+ax2.annotate('xy=(0.5, 0)\nxycoords=artist',
+ xy=(0.5, 0.), xycoords=t,
xytext=(0, -20), textcoords='offset points',
ha="center", va="top",
bbox=bbox_args,
arrowprops=arrow_args
)
-ax2.annotate('xy=(0.8, 0.5)\nxycoords="bbox"\nxybbox=ax1.transData',
+ax2.annotate('xy=(0.8, 0.5)\nxycoords=ax1.transData',
xy=(0.8, 0.5), xycoords=ax1.transData,
- #xytext=(0, 0), textcoords='data',
xytext=(10, 10), textcoords=OffsetFrom(ax2.bbox, (0, 0),
"points"),
ha="left", va="bottom",
bbox=bbox_args,
Modified: trunk/matplotlib/lib/matplotlib/text.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/text.py 2010-02-27 17:00:53 UTC (rev
8162)
+++ trunk/matplotlib/lib/matplotlib/text.py 2010-02-28 03:13:39 UTC (rev
8163)
@@ -1423,7 +1423,9 @@
x, y = l+w*xf, b+h*yf
elif isinstance(self._artist, Transform):
x, y = self._artist.transform_point(self._ref_coord)
-
+ else:
+ raise RuntimeError("unknown type")
+
sc = self._get_scale(renderer)
tr = Affine2D().scale(sc, sc).translate(x, y)
@@ -1780,7 +1782,12 @@
# 5 points below the top border
xy=(10,-5), xycoords='axes points'
+ You may use an instance of
+ :class:`~matplotlib.transforms.Transform` or
+ :class:`~matplotlib.artist.Artist`. See
+ :ref:`plotting-guide-annotation` for more details.
+
The *annotation_clip* attribute contols the visibility of the
annotation when it goes outside the axes area. If True, the
annotation will only be drawn when the *xy* is inside the
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Download Intel® Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
Matplotlib-checkins mailing list
Matplotlib-checkins@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
