[FEATURE]: get_subplot_geometry()

[FEATURE]: get_subplot_geometry() — Expose Computed Subplot Cell Pixel Positions

Summary

When building dashboards or figures with custom overlays, users frequently need to know
the exact pixel position and dimensions of each subplot cell. Plotly computes these
internally but never surfaces them. This issue proposes a new method
get_subplot_geometry() that returns the computed pixel boundaries of every subplot
in a figure for production use.

---

Problem Statement

There is currently no reliable way to answer the question:

"Where exactly, in pixels, does subplot xy start and how wide and tall is it?"

Users who need this information are forced to either:

• Hardcode pixel values based on trial and error (breaks on resize or data change)
• Reverse-engineer Plotly's internal domain-to-pixel calculations (brittle, undocumented)
• Call full_figure_for_development(), which is explicitly not for production use, slow,
  and returns normalized domain values (0–1) rather than actual pixels

This is a recurring pain point for users building:

• Dashboards where external HTML elements must align with specific subplot axes
• Stacked figures that need pixel-perfect y-axis alignment across separate charts
• Custom annotation layers that anchor to subplot cell boundaries
• Accessibility tools that need to describe where each chart lives on screen

---

Proposed Solution

A new method on Figure and FigureWidget:

geometry = fig.get_subplot_geometry()

Example Return Structure

{
    "subplots": {
        "xy": {
            "x": 80,
            "y": 60,
            "width": 400,
            "height": 300,
            "x2": 480,
            "y2": 360
        },
        "x2y2": {
            "x": 520,
            "y": 60,
            "width": 400,
            "height": 300,
            "x2": 920,
            "y2": 360
        }
    },
    "figure": {
        "total_width": 1000,
        "total_height": 800
    }
}

x and y are the top-left corner of the inner plotting area (inside the axes,
excluding tick labels and axis titles), measured in pixels from the top-left of
the figure.

Optional Parameters

# Include outer bounding box that covers tick labels and axis titles
fig.get_subplot_geometry(include_axis_labels=True)

# Limit results to specific subplots
fig.get_subplot_geometry(subplots=["xy", "x2y2"])

Two Backend Paths, One Interface

• FigureWidget in Jupyter: queries the live graph div directly for true
  browser-rendered pixel values
• Static Figure: falls back to a scoped Kaleido render using the figure's
  explicit width and height

The user does not manage which path is used — the method selects automatically.

JavaScript Access

// No new method needed for JS users
gd._computedLayout.subplots["xy"].x
gd._computedLayout.subplots["xy"].width
gd._computedLayout.figure.total_width

---

Why Not Use full_figure_for_development()?

full_figure_for_development() exposes normalized domain values (e.g. [0.0, 0.45])
but:

• Does not return pixel positions
• Is documented as not for production use
• Is slow and returns a very large object
• Does not reflect true browser dimensions when using FigureWidget

This feature is the production-safe, pixel-accurate alternative for layout geometry
specifically.

---

Prior Art

Tool	Equivalent
matplotlib	ax.get_position(), ax.get_window_extent()
bokeh	plot.inner_width, plot.inner_height
Browser DOM	element.getBoundingClientRect()

---

Backward Compatibility

This is a purely additive change. No existing figures, attributes, or workflows
are affected.

---

Related Issues

• Companion to: [FEATURE]: get_computed_values() (https://github.com/plotly/plotly.py/issues/5552)
• Companion to: [FEATURE]: autorangePadding() (https://github.com/plotly/plotly.py/issues/5555)
• Related to any issue requesting axis alignment across multiple figures

---

I'm happy to help refine the return structure, naming conventions, or scope.
The goal is to open a concrete discussion rather than a vague wish.

Start by locating the Figure and FigureWidget entry points and the existing layout or geometry handling behind them. Compare the proposed live graph-div path with the static Kaleido path, then define tests for returned subplot and figure dimensions, filtering, and axis-label inclusion. Done means one consistent interface works for both backends with documented pixel coordinates.