Repository: matplotlib/matplotlib
File: galleries/examples/text_labels_and_annotations/demo_annotation_box.py (Python)

Code before:
======================
Artists as annotations
======================

`.AnnotationBbox` facilitates annotating parts of the figure or axes using arbitrary
artists, such as texts, images, and `matplotlib.patches`. `.AnnotationBbox` supports
these artists via inputs that are subclasses of `.OffsetBox`, which is a class of
container artists for positioning an artist relative to a parent artist.
"""

import matplotlib.pyplot as plt
import numpy as np

from matplotlib.cbook import get_sample_data
from matplotlib.offsetbox import AnnotationBbox, DrawingArea, OffsetImage, TextArea
from matplotlib.patches import Annulus, Circle, ConnectionPatch

# %%%%
# Text
# ====
#
# `.AnnotationBbox` supports positioning annotations relative to data, Artists, and
# callables, as described in :ref:`annotations`. The  `.TextArea` is used to create a
# textbox that is not explicitly attached to an axes, which allows it to be used for
# annotating figure objects. The `Axes.annotate` method should be used when annotating
# an axes element (such as a plot) with text.
#
fig, axd = plt.subplot_mosaic([['t1', '.', 't2']], layout='compressed')

# Define a 1st position to annotate (display it with a marker)
xy1 = (.25, .75)
xy2 = (.75, .25)
axd['t1'].plot(*xy1, ".r")
axd['t2'].plot(*xy2, ".r")
axd['t1'].set(xlim=(0, 1), ylim=(0, 1), aspect='equal')
axd['t2'].set(xlim=(0, 1), ylim=(0, 1), aspect='equal')
# Draw an arrow between the points

c = ConnectionPatch(xyA=xy1, xyB=xy2,
                    coordsA=axd['t1'].transData, coordsB=axd['t2'].transData,
                    arrowstyle='->')
fig.add_artist(c)

# Annotate the ConnectionPatch position ('Test 1')
offsetbox = TextArea("Test 1")

ab1 = AnnotationBbox(offsetbox, (.5, .5),
                     xybox=(0, 0),
                     xycoords=c,
                     boxcoords="offset points",
                     arrowprops=dict(arrowstyle="->"),

Review comment (suggestion):
```suggestion
# annotating figure objects. The `.Axes.annotate` method should be used instead when
# annotating an axes element (such as a plot) with text.
```
to make it more clear this is an alternative to above. The dot fixes the ref warning.

Code after:
======================
Artists as annotations
======================

`.AnnotationBbox` facilitates using arbitrary artists as annotations, i.e. data at
position *xy* is annotated by a box containing an artist at position *xybox*. The
coordinate systems for these points are set via the *xycoords* and *boxcoords*
parameters, respectively; see the *xycoords* and *textcoords* parameters of
`.Axes.annotate` for a full listing of supported coordinate systems.
The box containing the artist is a subclass of `.OffsetBox`, which is a container
artist for positioning an artist relative to a parent artist.
"""
from pathlib import Path

import PIL

import matplotlib.pyplot as plt
import numpy as np

from matplotlib import get_data_path
from matplotlib.offsetbox import AnnotationBbox, DrawingArea, OffsetImage, TextArea
from matplotlib.patches import Annulus, Circle, ConnectionPatch

# %%%%
# Text
# ====
#
# `.AnnotationBbox` supports positioning annotations relative to data, Artists, and
# callables, as described in :ref:`annotations`. The  `.TextArea` is used to create a
# textbox that is not explicitly attached to an axes, which allows it to be used for
# annotating figure objects. When annotating an axes element (such as a plot) with text,
# use `.Axes.annotate` because it will create the text artist for you.

fig, axd = plt.subplot_mosaic([['t1', '.', 't2']], layout='compressed')

# Define a 1st position to annotate (display it with a marker)
xy1 = (.25, .75)
xy2 = (.75, .25)
axd['t1'].plot(*xy1, ".r")
axd['t2'].plot(*xy2, ".r")
axd['t1'].set(xlim=(0, 1), ylim=(0, 1), aspect='equal')
axd['t2'].set(xlim=(0, 1), ylim=(0, 1), aspect='equal')

# Draw a connection patch arrow between the points
c = ConnectionPatch(xyA=xy1, xyB=xy2,
                    coordsA=axd['t1'].transData, coordsB=axd['t2'].transData,
                    arrowstyle='->')
fig.add_artist(c)

# Annotate the ConnectionPatch position ('Test 1')
offsetbox = TextArea("Test 1")