update annotation guide

leejjoon · leejjoon · commit 207fa994d318 · 2010-02-28T03:13:39.000Z
svn path=/trunk/matplotlib/; revision=8163
diff --git a/doc/users/annotations_guide.rst b/doc/users/annotations_guide.rst
@@ -4,8 +4,11 @@
 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 @@ lower-left corner and (1,1) means top-right.
 .. 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 @@ legend (as a matter of fact, this is how the legend is created).
 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
 ***************
 
diff --git a/doc/users/plotting/examples/annotate_simple_coord01.py b/doc/users/plotting/examples/annotate_simple_coord01.py
@@ -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()
+
diff --git a/doc/users/plotting/examples/annotate_simple_coord02.py b/doc/users/plotting/examples/annotate_simple_coord02.py
@@ -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()
+
diff --git a/doc/users/plotting/examples/annotate_simple_coord03.py b/doc/users/plotting/examples/annotate_simple_coord03.py
@@ -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()
+
diff --git a/examples/pylab_examples/annotation_demo3.py b/examples/pylab_examples/annotation_demo3.py
@@ -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,
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -1423,7 +1423,9 @@ def __call__(self, renderer):
             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,6 +1782,11 @@ def __init__(self, s, xy,
           # 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
