New updateImages method (for efficient image updates in response to continuous layout changes)

[robertcollar-kobold]

This PR adds Plotly.updateImages(gd, images) — a new public API method that efficiently updates layout images (and layout images only!). This method is most impactful when called in response to the plotly_relayouting event, which fires continuously during scroll-zooming or drag-panning. Together, they enable continuously updating layout images in response to axis range changes, as is required to display tiled image pyramids.

What wasn't working before?

Viewing images is most intuitive when using scroll-zoom and drag-pan to navigate. When viewing tiled image pyramids, image tiles would ideally be updated continuously while scrolling or dragging is ongoing. However, image tiles can only be added at the end of such actions, as the plotly_relayout event is only called once an action is complete.

Screen.Recording.2026-04-10.at.11.21.39.AM.mov

We can get around this by using the the private plotly_relayouting event, which fires continuously during these actions. However, doing so introduces a new problem. Adding images to the layout requires use of the update_layout method, which triggers the redraw pipeline. Calling update_layout in response to plotly_relayouting means that the redraw pipeline is triggered continuously in the middle of scrolling/panning — while relayouting is already ongoing! This causes unexpected behavior (scroll-zooming does not result in zooming on the axes, even as the traces zoom — though temporarily). CodePen to reproduce: https://codepen.io/robertcollar-kobold/pen/gbwKRva

Screen.Recording.2026-04-10.at.11.01.46.AM.mov

In theory we could turn to the react method, which is intended to calculate the delta with the previous figure and update only what has changed. However, it behaves similarly to the update_layout method in this context. CodePen to reproduce: https://codepen.io/robertcollar-kobold/pen/wBzXeXo

The new updateImages method resolves these problems by targeting layout images only, narrowing the scope of the layout update. Notably, it enables Plotly to reach performance parity with standard slippy map style tiled image viewers, which update image tiles continuously during scroll-zooming/drag-panning. Check out the example below:

Screen.Recording.2026-04-10.at.11.09.30.AM.mov

Considerations

1. This new public method is most impactful when called in response to the plotly_relayouting event, though it of course stands on its own as an efficient way to update layout images. We could amplify its impact by making plotly_relayouting public instead of private, but doing so might make it more likely that users call update_layout continuously (and concurrent with ongoing relayouting), in a way that performs poorly.
2. I don't see a need to expose updateImages in the python API. It's a minor addition that benefits most from use with plotly_relayouting, which is not accessible from the python API. If the latter were made public and exposed in the python API, then we might consider exposing updateImages in the python API as well. Note that similar methods (e.g., react) are not exposed in the python API.