mplot3d: make Axes3D.annotate accept (x, y, z) and reproject on draw by sanrishi · Pull Request #31267 · matplotlib/matplotlib

sanrishi · 2026-03-10T13:24:00Z

PR Description

AI Disclosure

I used an AI assistant for code navigation and prototyping; all changes were heavily reviewed, tested locally, and manually verified by me to ensure they match Matplotlib's internal standards.

Summary

Fixes mplot3d annotations being anchored in projected 2D snapshot space instead of 3D data space (#7927). Currently, Axes3D inherits the 2D Axes.annotate, meaning annotations do not reproject when the 3D view changes (rotate/zoom), even though other 3D artists update using Axes3D.M.

What this PR changes

New 3D Artist: Adds art3d.Annotation3D which stores a 3D anchor and reprojects it on every draw using the current 3D projection (Axes3D.M via proj3d._proj_transform_clip).
API Override & Validation: Axes3D.annotate now automatically upgrades to Annotation3D when either xy or xytext is passed as a 3-tuple, seamlessly supporting hybrid 2D/3D coordinate inputs.
Strict Coordinate Enforcement: Uses _api.check_in_list to enforce that 3D tuples are only accepted when xycoords='data' (or textcoords='data').
Draw-Time Projection: Performs the 3D→2D projection at the start of Annotation3D.draw() so 2D annotation_clip and clip_on special-casing behave correctly without timing traps.

Clipping / layout behavior

clip_on=True behavior matches 2D Axes.annotate special-casing (clip to ax.patch).
Adds axlim_clip kwarg (default False) for Annotation3D to cull annotations outside the view limits.
Annotation3D.get_tightbbox() returns None since projected positions aren't meaningful for the layout engine.

Visual Proof & Minimal Reproducible Example

A full demonstration of this new behavior has been added to the docs in the new gallery example: galleries/examples/mplot3d/annotations3d.py.

Below is a minimal reproducible example demonstrating the fix. The black arrow uses the new 3D tracking, while the orange arrow shows the old 2D snapshot drifting bug.

import numpy as np
import matplotlib.pyplot as plt

fig = plt.figure()
ax = fig.add_subplot(projection="3d")

xs = ys = zs = np.arange(10)
sc = ax.scatter(xs, ys, zs, depthshade=True)

x0, y0, z0 = xs[5], ys[5], zs[5]

# NEW BEHAVIOR: 3D anchor follows camera rotation
ax.annotate(
    "3D annotate anchor",
    (x0, y0, z0),
    xytext=(0, 12),
    textcoords="offset points",
    arrowprops=dict(arrowstyle="->", lw=1),
    clip_on=True,
    axlim_clip=False,
)

# OLD BEHAVIOR: 2D snapshot drifts
fig.canvas.draw()
snap = sc.get_offsets()[5]
ax.annotate(
    "2D snapshot",
    snap,
    xytext=(0, -15),
    textcoords="offset points",
    arrowprops=dict(arrowstyle="->", lw=1, color="C1"),
    color="C1",
)

ax.set_title("Rotate/zoom: 3D annotation follows; 2D snapshot drifts")
plt.show()

PR checklist

"closes mplot3d annotate uses the 2D projection coordinates system #7927 " is in the body of the PR description to link the related issue
new and changed code is tested
Plotting related features are demonstrated in an example
New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

scottshambaugh

I tried this out locally and it works well! A number of comments here, but I agree on the overall direction.

Needed docs updates:

A What's New entry
A new gallery example for annotations in 3D (somewhat like https://matplotlib.org/devdocs/gallery/mplot3d/text3d.html, though I think this example is messy)

lib/mpl_toolkits/mplot3d/axes3d.py

scottshambaugh · 2026-03-10T18:59:14Z

lib/mpl_toolkits/mplot3d/tests/test_axes3d.py

+    assert clip_box is not None
+    assert np.all(clip_box.extents == ax.bbox.extents)
+
+


We will need at least:

Image comparison tests that compare the 2D xytext cases here (both 2D and 3D point positions) with a direct call of Axes.annotate. This ensures equivalency with the new method.

Image comparison tests for axlim_clip cases.

A new baseline image test with different cases. One of the axes should be log scale.

Take a look at the tests we have for annotate in the 2D case to see what else might be needed

Thanks for clarification!
Added test coverage!

Could you update the view angle of the baseline images so that annotations are not offscreen or on top of each other?

Oh yeahI i was also looking that and angle is not good
DONE!

Some of the annotations don't look like they're behaving correctly. Make sure you're using the images as a diagnostic tool

Yea i noticed that camera plane inversion is happening in images generated
I will respond you after fixing it!

lib/mpl_toolkits/mplot3d/axes3d.py

scottshambaugh · 2026-03-10T19:07:00Z

lib/mpl_toolkits/mplot3d/axes3d.py

+            arrowprops=arrowprops, annotation_clip=annotation_clip, **kwargs)
+
+        if xyz is not None:
+            art3d.annotation_2d_to_3d(a, xyz, xyztext=xyztext, axlim_clip=axlim_clip)


When axlim_clip = True, I see the following behavior:

xyz coordinate is clipped, the text and arrow disappear (I think this is correct)

The text coordinate is clipped, matplotlib crashes (needs to be fixed)

scottshambaugh · 2026-03-10T19:18:27Z

lib/mpl_toolkits/mplot3d/axes3d.py

+            text, xy, xytext=xytext, xycoords=xycoords, textcoords=textcoords,
+            arrowprops=arrowprops, annotation_clip=annotation_clip, **kwargs)
+
+        if xyz is not None:


There should also be a path that allows xyztext is not None and xyz is None (2D data location, 3D text location).

Excellent point, @scottshambaugh. I've updated the logic to upgrade to Annotation3D if xyz OR xyztext is a 3-tuple, and added a safeguard in art3d.py so it doesn't try to re-project a None anchor. Also added a quick unit test to ensure the text continues to follow camera rotations in this hybrid state!

lib/mpl_toolkits/mplot3d/art3d.py

lib/mpl_toolkits/mplot3d/axes3d.py

scottshambaugh

Left some more comments, I'll try this out again locally once these are addressed. Also, it looks like tests are failing.

scottshambaugh · 2026-03-11T22:51:20Z

doc/release/next_whats_new/3d_annotations.rst

@@ -0,0 +1,11 @@
+3D annotations follow the view


I think something like "3D annotations can anchor to 3D coordinates" is clearer

scottshambaugh · 2026-03-11T22:52:40Z

galleries/examples/mplot3d/annotations3d.py

+:meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.annotate` supports anchoring annotations in
+3D data coordinates by passing ``(x, y, z)`` for *xy* (with ``xycoords='data'``,
+the default).  The annotation is projected during draws, so it stays attached
+to the point as the view changes.


This should explain a bit more the different annotation modes (data, etc) and also how/why you would want to use 2D annotations

Thanks for clarification
DONE!

scottshambaugh · 2026-03-11T22:53:26Z

doc/release/next_whats_new/3d_annotations.rst

+draws, so it stays attached to the intended point when rotating or zooming the
+3D view.
+
+The new keyword-only parameter ``axlim_clip`` can be used to hide annotations


Probably don't need this detail, as axlim_clip is a param on all 3D artists

scottshambaugh · 2026-03-11T22:56:13Z

lib/mpl_toolkits/mplot3d/tests/test_axes3d.py

+    assert_delta(ann_fs)
+
+
+@mpl3d_image_comparison(['annotate3d_equivalent_to_axes_annotate.png'],


For this, please use the fig_ref, fig_test type of image comparison test. That ensures both are giving the pixel-equivalent output, and saves us from having to add a baseline image (which takes up space in the git history)

That is smart thinking
DONE!

scottshambaugh · 2026-03-11T22:58:10Z

lib/mpl_toolkits/mplot3d/art3d.py

+
+    This intentionally opts out of layout (like `Text3D`) by returning None from
+    `get_tightbbox`.
+    """


I believe this should have an __init__ that calls set_3d_properties, like other functions here. And the docstring should include the parameters for that init.

scottshambaugh · 2026-03-11T23:01:08Z

lib/mpl_toolkits/mplot3d/axes3d.py

+            If a 3-tuple *xy* is passed with *xycoords* not equal to ``'data'``,
+            or if a 3-tuple *xytext* is passed with the text position not in
+            data coordinates.
+        """


There should be an _api.check_in_list call for xycoords and anything else that's a string key

scottshambaugh · 2026-03-11T23:03:38Z

lib/mpl_toolkits/mplot3d/tests/test_axes3d.py

    ax.set_visible(False)


+def test_annotate_3d_follows_view():


I don't think this is necessary with the image test.

Good point the old p0 != p1 check was a weak proxy. I rewrote test_annotate_3d_follows_view as a @check_figures_equal test: fig_test draws the 3D annotation, rotates the view, and redraws; fig_ref sets the final view up front and uses a pre-projected 2D snapshot with a direct matplotlib.axes.Axes.annotate call.

This gives a pixel-level equivalence check without adding a baseline image. is this logic looking good?

scottshambaugh · 2026-03-11T23:05:50Z

lib/mpl_toolkits/mplot3d/tests/test_axes3d.py

+
+@mpl3d_image_comparison(['annotate3d_cases.png'],
+                        remove_text=False, style='mpl20')
+def test_annotate_3d_cases():


You can make this just one subplot with 2 linear and 1 log axes. But please test all four permutations of 2D & 3D coordinates for data and text.

Updated test_annotate_3d_cases per your suggestion: it’s now a single 3D subplot with zscale='log' and four annotations covering all xy/xytext 2D/3D permutations.

The “xy=2D” cases use a pre-projected 2D snapshot from get_offsets() after a draw (legacy behavior), so those permutations are well-defined. Baseline annotate3d_cases.png was regenerated accordingly.

scottshambaugh · 2026-03-11T23:07:17Z

lib/mpl_toolkits/mplot3d/tests/test_axes3d.py

+    assert not np.allclose(p0, p1)
+
+
+def test_annotate_3d_text_position_clipped_does_not_crash():


You don't need a special test for this, just the image test with all the permutations of axlim_clip is fine.

Thanks for clarification
DONE!

scottshambaugh · 2026-03-11T23:07:47Z

lib/mpl_toolkits/mplot3d/tests/test_axes3d.py

+    assert np.all(clip_box.extents == ax.bbox.extents)
+
+
+def test_annotate_3d_text_position_with_2d_anchor():


This should already be covered by the baseline image test.

github-actions bot added the topic: mplot3d label Mar 10, 2026

scottshambaugh reviewed Mar 10, 2026

View reviewed changes

github-actions bot added the Documentation: examples files in galleries/examples label Mar 11, 2026

sanrishi requested a review from scottshambaugh March 11, 2026 07:04

github-actions bot added the Documentation: API files in lib/ and doc/api label Mar 11, 2026

anntzer reviewed Mar 11, 2026

View reviewed changes

lib/mpl_toolkits/mplot3d/axes3d.py Outdated Show resolved Hide resolved

sanrishi requested a review from anntzer March 11, 2026 09:11

scottshambaugh reviewed Mar 11, 2026

View reviewed changes

sanrishi force-pushed the fix-issue-7927-3d-annotations branch from 36eacc9 to 3164685 Compare March 12, 2026 13:17

sanrishi added 21 commits March 12, 2026 19:07

mplot3d: add 3D annotate support

7d01202

mplot3d: fix annotate line length

d31332d

mplot3d: document 3D annotate behavior

ebfdcb8

docs: add 3D annotate whatsnew and example

53d479d

mplot3d: add image tests for annotate3d

fa781cb

mplot3d: warn on unused axlim_clip

9d84f24

mplot3d: allow 3D xytext with 2D xy

7b6a28f

mplot3d: handle clipped 3D xytext

ad9eedf

mplot3d: fix test spacing

ad4c9e9

docs: fix trailing blank lines

2c2d940

docs: add Axes3D.annotate autosummary

e2f7195

mplot3d: test annotate3d offset coords

152fb7c

docs: clarify 3D-annotate whatsnew title

6b268f9

docs: address reviewer feedback on 3D annotations

88870c5

docs: trim axlim_clip mention

f79624f

mplot3d: compare annotate3d via check_figures_equal

ec53835

mplot3d: add Annotation3D init

d6e00fd

docs: clarify Axes3D.annotate return type

23b2eee

docs: expand parameter descriptions in annotate3d

b4b257f

mplot3d: validate annotate3d coord strings

ffde85a

mplot3d: make follow-view test image-based

6e08e74

sanrishi added 3 commits March 12, 2026 19:13

test: consolidate annotate3d cases and test all xy/xytext permutations

b9245f6

tests: cover clipped 3D xytext via image test

c6d9869

tests: drop redundant hybrid annotate3d unit test

a42cedc

sanrishi force-pushed the fix-issue-7927-3d-annotations branch from 3164685 to a42cedc Compare March 12, 2026 13:46

docs: avoid unresolved Annotation3D crossrefs

9060ed1

sanrishi requested a review from scottshambaugh March 12, 2026 18:55

test: adjust view angles to prevent annotation overlap in baselines

38cd31b

		assert clip_box is not None
		assert np.all(clip_box.extents == ax.bbox.extents)

		assert_delta(ann_fs)


		@mpl3d_image_comparison(['annotate3d_equivalent_to_axes_annotate.png'],

		assert not np.allclose(p0, p1)


		def test_annotate_3d_text_position_clipped_does_not_crash():

		assert np.all(clip_box.extents == ax.bbox.extents)


		def test_annotate_3d_text_position_with_2d_anchor():

Uh oh!

Conversation

sanrishi commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Description

AI Disclosure

Summary

What this PR changes

Clipping / layout behavior

Visual Proof & Minimal Reproducible Example

PR checklist

Uh oh!

scottshambaugh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

scottshambaugh Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

scottshambaugh Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

scottshambaugh left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sanrishi Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sanrishi Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sanrishi commented Mar 10, 2026 •

edited

Loading

scottshambaugh Mar 12, 2026 •

edited

Loading

scottshambaugh Mar 13, 2026 •

edited

Loading

scottshambaugh left a comment •

edited

Loading

sanrishi Mar 12, 2026 •

edited

Loading

sanrishi Mar 12, 2026 •

edited

Loading