ultraplot 2.4.1__tar.gz → 2.5.0__tar.gz

{ultraplot-2.4.1/ultraplot.egg-info → ultraplot-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultraplot
-Version: 2.4.1
+Version: 2.5.0
 Summary: A succinct matplotlib wrapper for making beautiful, publication-quality graphics.
 Author-email: Casper van Elteren <caspervanelteren@gmail.com>, Luke Davis <lukelbd@gmail.com>
 Maintainer-email: Casper van Elteren <caspervanelteren@gmail.com>, "Matthew R. Becker" <becker.mr@gmail.com>

{ultraplot-2.4.1 → ultraplot-2.5.0}/docs/api.rst

@@ -133,6 +133,16 @@ Demo functions
    :toctree: api
 
 
+Text alignment
+==============
+
+.. automodule:: ultraplot.textalign
+   :no-private-members:
+
+.. automodsumm:: ultraplot.textalign
+   :toctree: api
+
+
 Miscellaneous functions
 =======================
 

{ultraplot-2.4.1 → ultraplot-2.5.0}/docs/fonts.py

@@ -100,6 +100,88 @@ fig, axs = uplt.show_fonts(family="tex-gyre")
 # :rcraw:`mathtext.fontset` back to one of matplotlib's math-specialized font sets
 # (e.g., ``'stixsans'`` or ``'dejavusans'``).
 #
+# In short, math fonts can be tailored to taste at three levels, depending on
+# how much of the "LaTeX look" you want:
+#
+# #. **Match the document font** (the default). With the ``'custom'`` font set,
+#    math follows the active text font -- including fonts assigned to
+#    individual text objects, as demonstrated below.
+# #. **Computer Modern symbols**. Keep the active font for letters and numbers
+#    but render ``\mathcal`` and big operators with authentic Computer Modern
+#    glyphs by setting :rcraw:`mathtext.cm_symbols` to ``True``
+#    (see :ref:`below <ug_fonts_cm>`).
+# #. **Full LaTeX**. Set matplotlib's :rcraw:`text.usetex` to ``True`` to
+#    delegate all text rendering to an external LaTeX installation. This gives
+#    complete LaTeX typesetting but is much slower and requires TeX on your
+#    system -- with the previous two options it is rarely necessary.
+#
+# The example below demonstrates the first level: the same expression rendered
+# with different fonts assigned per text object.
+
+# %%
+import ultraplot as uplt
+
+expr = (
+    r"$\mathcal{ABCXYZ}\quad"
+    r"\sum_{i=0}^{n}\quad"
+    r"\prod_{j=1}^{m}\quad"
+    r"\int_a^b\quad"
+    r"\oint_C$"
+)
+
+fig, axs = uplt.subplots(nrows=3, refwidth=6, refheight=1.1, share=False, span=False)
+for ax, font in zip(axs, ("TeX Gyre Heros", "Fira Math", "DejaVu Sans")):
+    ax.text(0.02, 0.5, expr, transform="axes", va="center", fontsize=24, fontname=font)
+    ax.format(title=font, titleloc="left")
+axs.format(xlocator="null", ylocator="null", xspineloc="none", yspineloc="none")
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+#
+# .. _ug_fonts_cm:
+#
+# Computer Modern symbols
+# ^^^^^^^^^^^^^^^^^^^^^^^
+#
+# If you want to retain the active alphabet and number fonts while using
+# Computer Modern for selected LaTeX-style symbols, set :rcraw:`mathtext.cm_symbols`
+# to ``True``. This routes ``\mathcal`` through ``cmsy10`` and big operators like
+# ``\sum``, ``\prod``, ``\int``, ``\oint``, ``\bigcup``, and ``\bigoplus`` through
+# ``cmex10``. This does not affect ordinary letters and numbers, and it does not
+# provide a Computer Modern ``\mathfrak`` font because matplotlib's bundled
+# mathtext fonts do not include one. Note that math text is parsed when the
+# figure is *drawn*, so the setting must be active at draw time -- assign it
+# globally rather than wrapping plotting commands in a context block.
+
+# %%
+fig, ax = uplt.subplots(refwidth=6, refheight=1.1)
+ax.text(0.02, 0.5, expr, transform="axes", va="center", fontsize=24)
+ax.format(
+    title="Default custom math text",
+    titleloc="left",
+    xlocator="null",
+    ylocator="null",
+    xspineloc="none",
+    yspineloc="none",
+)
+
+# %%
+uplt.rc["mathtext.cm_symbols"] = True
+fig, ax = uplt.subplots(refwidth=6, refheight=1.1)
+ax.text(0.02, 0.5, expr, transform="axes", va="center", fontsize=24)
+ax.format(
+    title="Computer Modern math symbols",
+    titleloc="left",
+    xlocator="null",
+    ylocator="null",
+    xspineloc="none",
+    yspineloc="none",
+)
+
+# %%
+uplt.rc["mathtext.cm_symbols"] = False  # restore the default
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+#
 # A table of math text containing the sans-serif fonts packaged with UltraPlot is shown
 # below. The dummy glyph "¤" is shown where a given math character is unavailable
 # for a particular font (in practice, the fallback font :rc:`mathtext.fallback` is used

{ultraplot-2.4.1 → ultraplot-2.5.0}/docs/insets_panels.py

@@ -88,8 +88,8 @@ fig.format(
 )
 
 # %%
-import ultraplot as uplt
 import numpy as np
+import ultraplot as uplt
 
 state = np.random.RandomState(51423)
 data = (state.rand(20, 20) - 0.48).cumsum(axis=1).cumsum(axis=0)
@@ -192,3 +192,74 @@ ix = ax.inset(
 )
 ix.format(xlim=(2, 4), ylim=(2, 4), color="red8", linewidth=1.5, ticklabelweight="bold")
 ix.pcolormesh(data, cmap="Grays", levels=N, inbounds=False)
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+# Hawkeye map insets
+# ~~~~~~~~~~~~~~~~~~
+#
+# :class:`~ultraplot.axes.GeoAxes` adds :meth:`~ultraplot.axes.GeoAxes.hawkeye`
+# for geographic callout maps. The inset is anchored at ``xy`` in a parent coordinate
+# system, and its ``size`` is a fraction of the parent axes. Supply ``extent`` to set
+# the inset map scope and draw a matching indicator and optional connectors on the
+# parent map. Hawkeyes are excluded from automatic layout, so they can extend beyond
+# the parent axes without reserving subplot space.
+#
+# Rectangular hawkeyes preserve both the requested extent and projection scale. A
+# circular frame cannot simultaneously preserve projection scale and display an exact
+# non-square extent. Circular hawkeyes therefore expand the shorter projected dimension
+# to retain the projection; use a square extent when the exact circular map scope is
+# important, or pass ``aspect='auto'`` to fit the exact extent with distortion.
+#
+# The following dependency-free example shows a Singapore city locator on a world map.
+# The returned inset is an ordinary geographic axes, so optional geospatial libraries
+# can draw external data inside it. For example, `OSMnx <https://osmnx.readthedocs.io/>`__
+# can provide street geometry when it is installed separately:
+#
+# .. code-block:: python
+#
+#    import osmnx as ox
+#    from cartopy import crs as ccrs
+#
+#    network = ox.graph_from_point((1.3521, 103.8198), dist=8_000, network_type="drive")
+#    streets = ox.graph_to_gdfs(network, nodes=False)
+#    streets.plot(ax=inax, color="0.3", linewidth=0.4, transform=ccrs.PlateCarree())
+#
+# The data download and OpenStreetMap attribution are the responsibility of the
+# application using that optional integration.
+
+# %%
+singapore = (103.8198, 1.3521)
+fig, ax = uplt.subplots(proj="robin", refwidth=4)
+ax.format(land=True, landcolor="gray8", oceancolor="blue9")
+ax.plot(
+    *singapore,
+    marker="o",
+    color="red",
+    markeredgecolor="white",
+    markeredgewidth=0.8,
+    ms=5,
+    transform="cyl",
+)
+ax.text(106, 4, "Singapore", color="red", size=7, transform="map")
+inax = ax.hawkeye(
+    (0.97, 0.97),
+    size=0.23,
+    anchor="ur",
+    proj="merc",
+    extent=(103.76, 103.90, 1.27, 1.41),
+    shape="circle",
+    target="circle",
+    connector="line",
+    color="red",
+    indicator_kw={"linewidth": 1.5},
+)
+inax.format(land=True, landcolor="gray9", oceancolor="blue9")
+inax.plot(
+    *singapore,
+    marker="o",
+    color="red",
+    markeredgecolor="white",
+    markeredgewidth=0.8,
+    ms=5,
+    transform="cyl",
+)

{ultraplot-2.4.1 → ultraplot-2.5.0}/docs/projections.py

@@ -516,6 +516,60 @@ fig.format(
 )
 
 
+# %% [raw] raw_mimetype="text/restructuredtext"
+# .. _ug_geo_layout:
+#
+# Geographic axes in mixed subplot layouts
+# -----------------------------------------
+#
+# Geographic axes preserve the aspect ratio required by their projection. This is
+# important for interpreting distances and shapes correctly, but it creates a layout
+# choice when a map shares a GridSpec with Cartesian axes or maps that have a different
+# natural aspect ratio. A fixed-aspect map cannot both fill a differently shaped subplot
+# slot *and* preserve its projection geometry.
+#
+# By default, UltraPlot preserves the map aspect. If the slot is a different shape, the
+# visible map is centered inside it. This keeps the map accurate, but decorations attached
+# to the visible map boundary can stop lining up with decorations on neighboring subplots.
+# For example, the following uses ``abcanchor='slot'`` to attach the map's a-b-c label to
+# its unadjusted GridSpec slot instead. The map itself remains aspect-faithful.
+
+# %%
+import ultraplot as uplt
+
+layout = [[1, 1, 1, 2, 2, 2], [3, 3, 4, 4, 5, 5]]
+fig, axs = uplt.subplots(layout, refwidth=2.4, proj={4: "cyl"}, share=False)
+axs[3].format(
+    lonlim=(0, 1),
+    latlim=(0, 1),
+    abcanchor="slot",  # align its a-b-c label with the Cartesian subplot slots
+)
+fig.format(abc="A.", abcloc="left")
+
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+# ``abcanchor`` has two modes:
+#
+# * ``'axes'`` (the default) attaches the label to the visible map boundary. This is
+#   usually best when the map is the visual focus.
+# * ``'slot'`` attaches it to the original GridSpec slot. This is useful when labels
+#   should form a regular grid across mixed subplot types.
+#
+# There are two other deliberate trade-offs, depending on what the figure needs:
+#
+# * Use ``aspect='auto'`` with :meth:`~ultraplot.axes.GeoAxes.format` to stretch a map
+#   to fill its slot. This preserves the GridSpec geometry but distorts the projection,
+#   so it is generally unsuitable when geographic shape or scale matters.
+# * Make the map the layout reference with ``ref=4`` in the above call to
+#   :func:`~ultraplot.ui.subplots`. UltraPlot then resizes the overall figure so that
+#   the map fills its slot while retaining its aspect. This is useful when the map,
+#   rather than the Cartesian axes, should determine the figure geometry.
+#
+# If none of these trade-offs is appropriate, change the map extent so that its natural
+# aspect better matches the intended GridSpec slot. That preserves projection geometry,
+# but necessarily changes the plotted geographic domain.
+
+
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_zoom:
 #

{ultraplot-2.4.1 → ultraplot-2.5.0}/docs/subplots.py

@@ -395,6 +395,14 @@ for (name1, equal), (name2, group) in zip(equals, groups):
 #    Explicit sharing levels still force sharing attempts and may warn when
 #    incompatible axes are encountered.
 #
+# When figure-level row or column labels and a shared spanning axis label use
+# the same side, the row or column labels are placed nearer the axes and the
+# spanning label is placed outside them. Control this gap with the
+# :rc:`leftlabel.sharedpad`, :rc:`rightlabel.sharedpad`,
+# :rc:`bottomlabel.sharedpad`, and :rc:`toplabel.sharedpad` settings. These
+# can also be passed to ``format`` without periods; for example,
+# ``fig.format(leftlabelsharedpad='2em')``.
+#
 # The below examples demonstrate the effect of various axis and label sharing
 # settings on the appearance of several subplot grids.
 

{ultraplot-2.4.1 → ultraplot-2.5.0}/pyproject.toml

@@ -66,6 +66,7 @@ exclude = ["**/*.ipynb"]
 
 [tool.pytest.ini_options]
 filterwarnings = [
+    "ignore:'parseString' deprecated - use 'parse_string':DeprecationWarning:matplotlib._fontconfig_pattern",
     "ignore:'resetCache' deprecated - use 'reset_cache':DeprecationWarning:matplotlib._fontconfig_pattern",
 ]
 mpl-default-style = { axes.prop_cycle = "cycler('color', ['#4c72b0ff', '#55a868ff', '#c44e52ff', '#8172b2ff', '#ccb974ff', '#64b5cdff'])" }

{ultraplot-2.4.1 → ultraplot-2.5.0}/ultraplot/__init__.py

@@ -101,6 +101,7 @@ if TYPE_CHECKING:
     from .scale import SineLatitudeScale as SineLatitudeScale
     from .scale import SymmetricalLogScale as SymmetricalLogScale
     from .text import CurvedText as CurvedText
+    from .textalign import align_text as align_text
     from .ultralayout import ColorbarLayoutSolver as ColorbarLayoutSolver
     from .ultralayout import compute_ultra_positions as compute_ultra_positions
     from .ultralayout import get_grid_positions_ultra as get_grid_positions_ultra

ultraplot-2.5.0/ultraplot/_version.py

@@ -0,0 +1 @@
+__version__ = '2.5.0'

{ultraplot-2.4.1 → ultraplot-2.5.0}/ultraplot/axes/base.py

@@ -4,6 +4,7 @@ The first-level axes subclass used for all ultraplot figures.
 Implements basic shared functionality.
 """
 
+import contextlib
 import copy
 import inspect
 import re
@@ -165,8 +166,9 @@ This is similar to `matplotlib.axes.Axes.inset_axes`.
 
 Parameters
 -----------
-bounds : 4-tuple of float
-    The (left, bottom, width, height) coordinates for the axes.
+bounds : 4-tuple of float or (4-tuple, transform)
+    The (left, bottom, width, height) coordinates for the axes. To specify the
+    coordinate system alongside the coordinates, pass ``(bounds, transform)``.
 %(axes.transform)s
     Default is to use the same projection as the current axes.
 %(axes.proj)s
@@ -382,6 +384,11 @@ leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad : float or unit-spec, d
 : :rc:`leftlabel.pad`, :rc:`toplabel.pad`, :rc:`rightlabel.pad`, :rc:`bottomlabel.pad`
     The padding between the labels and the axes content.
     %(units.pt)s
+leftlabelsharedpad, toplabelsharedpad, rightlabelsharedpad, bottomlabelsharedpad : float or unit-spec, default
+: :rc:`leftlabel.sharedpad`, :rc:`toplabel.sharedpad`, :rc:`rightlabel.sharedpad`, :rc:`bottomlabel.sharedpad`
+    The padding between side labels and a shared spanning axis label on the
+    same side. The spanning label is placed outside the side labels.
+    %(units.pt)s
 leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw : dict-like, optional
     Additional settings used to update the labels with ``text.update()``.
 figtitle
@@ -744,6 +751,20 @@ class _TransformedBoundsLocator:
         return bbox
 
 
+class _AspectAwareTransformedBoundsLocator(_TransformedBoundsLocator):
+    """Preserve an inset's lower-left anchor after box-aspect adjustment."""
+
+    def __call__(self, ax, renderer):
+        bbox = super().__call__(ax, renderer)
+        aspect = ax.get_aspect()
+        if aspect == "auto" or ax.get_adjustable() != "box":
+            return bbox
+        box_aspect = float(aspect) * ax.get_data_ratio()
+        fig_bbox = ax.figure.bbox
+        fig_aspect = fig_bbox.height / fig_bbox.width
+        return bbox.shrunk_to_aspect(box_aspect, bbox, fig_aspect)
+
+
 class _SideColorbarLocator:
     """Position a side colorbar beyond its parent axes decorations."""
 
@@ -957,6 +978,7 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         self._active_cycle = rc["axes.prop_cycle"]
         self._auto_format = None  # manipulated by wrapper functions
         self._abc_border_kwargs = {}
+        self._abc_anchor = "axes"
         self._abc_loc = None
         self._abc_pad = 0  # User's horizontal offset for abc label (in points)
         self._abc_title_pad = rc[
@@ -970,6 +992,10 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         self._altx_parent = None  # for cartesian axes only
         self._alty_parent = None
         self._colorbar_fill = None
+        self._align_texts = []  # texts registered for overlap avoidance
+        self._align_kwargs = {}  # solver settings from auto_align_text()
+        self._align_arrows = []  # connectors drawn back to displaced anchors
+        self._align_cache = None  # last solve, reused while its inputs hold
         self._inset_parent = None
         self._inset_bounds = None  # for introspection ony
         self._inset_zoom = False
@@ -1046,9 +1072,10 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         """
         Add an inset axes using arbitrary projection.
         """
-        # Converting transform to figure-relative coordinates
-        transform = self._get_transform(transform, "axes")
-        locator = self._make_inset_locator(bounds, transform)
+        # Convert coordinates to figure-relative coordinates while retaining the
+        # original bounds for aspect-aware geographic inset locators.
+        bounds_input, transform = self._parse_anchor(bounds, transform, default="axes")
+        locator = self._make_inset_locator(bounds_input, transform)
         bounds = locator(self, None).bounds
         label = kwargs.pop("label", "inset_axes")
         zorder = _not_none(zorder, 4)
@@ -1066,6 +1093,8 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         # automatically if we used data coords. Called by ax.apply_aspect()
         cls = mproj.get_projection_class(kwargs.pop("projection"))
         ax = cls(self.figure, bounds, zorder=zorder, label=label, **kwargs)
+        if ax._name in ("cartopy", "basemap"):
+            locator = _AspectAwareTransformedBoundsLocator(bounds_input, transform)
         ax.set_axes_locator(locator)
         ax._inset_parent = self
         ax._inset_bounds = bounds
@@ -1737,6 +1766,22 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         else:
             raise ValueError(f"Unknown transform {transform!r}.")
 
+    def _parse_anchor(self, coordinates, transform=None, default="data"):
+        """
+        Parse coordinates and their transform.
+
+        Coordinates can be passed with the transform separately or packaged as
+        a ``(coordinates, transform)`` tuple. The latter is useful for APIs
+        that accept a single anchor argument, such as ``inset_axes``.
+        """
+        if (
+            transform is None
+            and isinstance(coordinates, tuple)
+            and len(coordinates) == 2
+        ):
+            coordinates, transform = coordinates
+        return coordinates, self._get_transform(transform, default)
+
     def _register_guide(self, guide, obj, key, **kwargs):
         """
         Queue up or replace objects for legends and list-of-artist style colorbars.
@@ -3071,8 +3116,15 @@ class Axes(_ExternalModeMixin, maxes.Axes):
                     self.transAxes.inverted()
                 )
                 ax0, ax1 = abc_bbox.x0, abc_bbox.x1
+                ay0, ay1 = abc_bbox.y0, abc_bbox.y1
                 tx0, tx1 = title_bbox.x0, title_bbox.x1
-                if tx0 < ax1 + abc_title_sep and tx1 > ax0 - abc_title_sep:
+                ty0, ty1 = title_bbox.y0, title_bbox.y1
+                if (
+                    tx0 < ax1 + abc_title_sep
+                    and tx1 > ax0 - abc_title_sep
+                    and ty0 < ay1
+                    and ty1 > ay0
+                ):
                     base_x = title_obj.get_position()[0]
                     ha = title_obj.get_ha()
                     max_width = 0
@@ -3380,6 +3432,7 @@ class Axes(_ExternalModeMixin, maxes.Axes):
             self._colorbar_fill.update_ticks(manual_only=True)  # only if needed
         if self._inset_parent is not None and self._inset_zoom:
             self.indicate_inset_zoom()
+        self._apply_align_text(renderer)
         needs_inset_reflow = bool(getattr(self, "_inset_colorbar_needs_reflow", False))
         has_inset_frame = bool(
             getattr(self, "_inset_colorbar_frame", None) is not None
@@ -3417,6 +3470,7 @@ class Axes(_ExternalModeMixin, maxes.Axes):
             self._colorbar_fill.update_ticks(manual_only=True)  # only if needed
         if self._inset_parent is not None and self._inset_zoom:
             self.indicate_inset_zoom()
+        self._apply_align_text(renderer)
         bbox = super().get_tightbbox(renderer, *args, **kwargs)
         fig = self.figure
         if (
@@ -4047,6 +4101,7 @@ class Axes(_ExternalModeMixin, maxes.Axes):
     def text(
         self,
         *args,
+        avoid_overlap=None,
         border=False,
         bbox=False,
         bordercolor="w",
@@ -4074,6 +4129,10 @@ class Axes(_ExternalModeMixin, maxes.Axes):
 
         Other parameters
         ----------------
+        avoid_overlap : bool, default: :rc:`text.align`
+            Whether to automatically nudge this text at draw time so it does not
+            overlap other auto-aligned text or the plotted data. See
+            `~ultraplot.axes.Axes.auto_align_text` for the solver settings.
         border : bool, default: False
             Whether to draw border around text.
         borderwidth : float, default: 2
@@ -4103,6 +4162,7 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         See also
         --------
         matplotlib.axes.Axes.text
+        ultraplot.axes.Axes.auto_align_text
         """
         # Translate positional args
         # Audo-redirect to text2D for 3D axes if not enough arguments passed
@@ -4171,8 +4231,127 @@ class Axes(_ExternalModeMixin, maxes.Axes):
                 "bboxpad": bboxpad,
             }
         )
+        self._register_align_text(obj, avoid_overlap)
+        return obj
+
+    def _register_align_text(self, obj, avoid_overlap=None):
+        """
+        Queue a text object for draw-time overlap avoidance, or release it.
+        """
+        # The solver moves a label by inverting its transform, which only means
+        # anything for text that its transform actually positions. A Text3D is
+        # placed by the 3D projection instead, and its stored position is the data
+        # coordinate that feeds it, so a display-space nudge would not move the
+        # label -- it would rewrite the data point.
+        if hasattr(obj, "get_position_3d"):
+            return obj
+        # An explicit avoid_overlap=False beats the rc setting, so opting out is
+        # always available. Releasing a label also puts it back where the user
+        # asked for it, rather than stranding it wherever the solver left it.
+        if _not_none(avoid_overlap, rc["text.align"]):
+            if obj not in self._align_texts:
+                self._align_texts.append(obj)
+        else:
+            if obj in self._align_texts:
+                self._align_texts.remove(obj)
+            from ..textalign import _reset_label
+
+            if hasattr(obj, "_uplt_align_anchor"):
+                _reset_label(obj)
+        self.stale = True
         return obj
 
+    def auto_align_text(self, *objs, **kwargs):
+        """
+        Automatically reposition text so that it does not overlap.
+
+        Labels are relaxed away from each other, from the plotted data and from
+        the axes edges at draw time, then pulled back towards where you put them.
+        Because the solver runs on every draw, the layout stays valid when the
+        figure is resized or the data limits change.
+
+        Parameters
+        ----------
+        *objs : `~matplotlib.text.Text`, optional
+            The text or annotation objects to align. Default is every text
+            created with ``avoid_overlap=True`` plus, if none were, all the text
+            you added to the axes.
+        pad : float, default: :rc:`text.align.pad`
+            Padding in points kept around each label.
+        avoid_points : bool, default: True
+            Whether labels also repel the data points of lines and scatter plots.
+        avoid : sequence of `~matplotlib.artist.Artist`, optional
+            Extra artists whose bounding boxes the labels must stay clear of.
+        only_move : {'xy', 'x', 'y'}, default: 'xy'
+            Restrict movement to one axis. Use ``'y'`` when the horizontal
+            position of a label carries meaning, as on a time series.
+        max_iter : int, default: :rc:`text.align.maxiter`
+            Maximum number of relaxation iterations.
+        spring : float, default: 0.05
+            Strength of the pull back towards the original position. Larger
+            values keep labels closer to their anchors at the cost of overlap.
+        step : float, default: 0.6
+            Damping applied to each iteration's displacement.
+        clip : bool, default: True
+            Whether to keep labels inside the axes.
+        arrows : bool or dict, default: :rc:`text.align.arrows`
+            Whether to draw a connector from each displaced label back to the
+            point it labels. A dict is passed to `~matplotlib.patches.FancyArrowPatch`.
+        min_arrow_dist : float, default: 8.0
+            Only draw connectors for labels displaced further than this, in points.
+
+        Examples
+        --------
+        >>> import ultraplot as uplt
+        >>> fig, ax = uplt.subplots()
+        >>> ax.scatter(x, y)
+        >>> for xi, yi, name in zip(x, y, names):
+        ...     ax.text(xi, yi, name)
+        >>> ax.auto_align_text()
+
+        See also
+        --------
+        ultraplot.axes.Axes.text
+        ultraplot.axes.Axes.annotate
+        """
+        objs = [obj for arg in objs for obj in (arg if np.iterable(arg) else (arg,))]
+        if objs:
+            self._align_texts = list(objs)
+        elif not self._align_texts:
+            # Titles and a-b-c labels live in self.texts but are positioned by the
+            # layout engine, so they are not ours to move.
+            titles = set(map(id, self._title_dict.values()))
+            self._align_texts = [
+                t for t in self.texts if id(t) not in titles and t.get_text().strip()
+            ]
+        self._align_kwargs = kwargs
+        self.stale = True
+        return self._align_texts
+
+    def _apply_align_text(self, renderer):
+        """
+        Run the overlap solver for this axes (called on every draw).
+        """
+        if not self._align_texts:
+            # Every label was released; take their connectors with them
+            for patch in self._align_arrows:
+                with contextlib.suppress(Exception):
+                    patch.remove()
+            self._align_arrows = []
+            return
+        from ..textalign import align_text
+
+        kwargs = {
+            "pad": rc["text.align.pad"],
+            "max_iter": rc["text.align.maxiter"],
+            "arrows": rc["text.align.arrows"],
+            **self._align_kwargs,
+        }
+        try:
+            align_text(self, self._align_texts, renderer=renderer, **kwargs)
+        except Exception as err:  # never let label polish break a render
+            warnings._warn_ultraplot(f"Failed to auto-align text: {err}")
+
     @docstring._concatenate_inherited
     def annotate(
         self,
@@ -4190,16 +4369,24 @@ class Axes(_ExternalModeMixin, maxes.Axes):
         textcoords: Optional[Union[str, mtransforms.Transform]] = None,
         arrowprops: Optional[dict[str, Any]] = None,
         annotation_clip: Optional[bool] = None,
+        avoid_overlap: Optional[bool] = None,
         **kwargs: Any,
     ) -> Union[mtext.Annotation, "CurvedText"]:
         """
         Add an annotation. If `xy` is a pair of 1D arrays, draw curved text.
 
         For curved input with `arrowprops`, the arrow points to the curve center.
+
+        Parameters
+        ----------
+        avoid_overlap : bool, default: :rc:`text.align`
+            Whether to automatically nudge this annotation at draw time so it
+            does not overlap other auto-aligned text or the plotted data. See
+            `~ultraplot.axes.Axes.auto_align_text`.
         """
         curve_xy = self._coerce_curve_xy_from_xy_arg(xy)
         if curve_xy is None:
-            return super().annotate(
+            obj = super().annotate(
                 text,
                 xy=xy,
                 xytext=xytext,
@@ -4209,6 +4396,7 @@ class Axes(_ExternalModeMixin, maxes.Axes):
                 annotation_clip=annotation_clip,
                 **kwargs,
             )
+            return self._register_align_text(obj, avoid_overlap)
 
         x_curve, y_curve = curve_xy
         try: