[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.

首先定位 Figure 和 FigureWidget 的入口点，以及它们背后的现有布局或几何处理。将提议的 live graph-div 路径与静态 Kaleido 路径进行比较，然后为返回的 subplot 和 figure 尺寸、过滤以及轴标签包含情况定义测试。当一个一致的接口能够在两个后端上工作，并且像素坐标已有文档说明时，即可视为完成。