Speed up evoked time plotting

[larsoner]

Closes #14242

@wmvanvliet I generalized our blit code. Looks like it's actually pretty clean, steps:

1. Generalize our brain blit code to a more general version _BlitManager
2. Use that version in 3D plotting
3. Use that version in evoked.plot and evoked.plot_topo
4. Use that version in our animate_topomap code
5. Speed up animate_topomap by actually blitting properly (working around a matplotilb issue where the figure would silently invalidate and draw nothing if you tried to use the correct blit path)

Minor changes to evoked.plot and evoked.topo are that the time axvline will stay on top now, but I think that's reasonable (and expected).

(5) was a pain to discover -- turns out to be caused by the modification of the contours, which removes and re-adds the set to the axes, which invalidates the draw, causing a full redraw (with nothing left to draw, so you get a blank plot). The workaround I came up with is to add a dummy no-op ax class pass to the contour call, and then pull the contours from it. I'm going to work on upstreaming a warning about this and a less-hacky way to get the contours... but it might be a bit to land etc. In the meantime I think the no-op class is workable, and has a big performance boost.

(5) speeds up report.add_evoked from about 8s to 5s by dropping the timepoint code from over 3s to under 1s.

I then also sped up how images are embedded in reports to cut down another second off that 5s add_evokeds.

I used Claude Opus 5 to investigate (iterating / reviewing multiple versions).

[larsoner]

@wmvanvliet okay to merge or did you need to test / look further?

[wmvanvliet]

Could you explain a bit some of the changes in this PR? It looks like MNE-Python need to work around blitting bugs in matplotlib of something. Why is the coding dealing with low-level image functions?

[larsoner]

Sure -- this PR was targeting blitting and speed, so I decided to tack on a few other loosely related fixes that could in principle be separated into separate PRs if needed.

1. Evoked.plot and plot_topo blitting

This was the starting idea and set of changes (the #14242 part).

2. Blitting bug for plot_topomap

Back in #13905, I spent a lot of time trying to get blitting right, but it turned out I got it mostly wrong because I hit a matplotlib bug involving silent invalidation of the figure when adding a new artist (adding a new contour to the figure caused it not draw the blit artists!). The real fix is in matplotlib/matplotlib#32271 (and another PR that warns a user that "this new artist broke blitting" that I haven't opened yet), but in the meantime the same thing -- getting new contours at the current levels for new data -- can be achieved by creating a dummy figure and/or axes, adding a contour to that with the same levels, and then pulling the necessary info from that temporary object over to the contour object on the blitting axes. Rather than doing plt.figure().axes().contour(...), NoopAxes allows creation of a ContourSet without ever actually drawing it or needing a real matplotlib figure. It's a safe enough work around until my upstream ContourSet.set_data PR lands and we (2 years from now) get to drop the workaround. (I'll add notes about that once the proper fix lands upstream and we can actually use it here.)

3. Report image capture

One case where these blitting and image paths matter is in report.add_evokeds. While incorporating _BlitManager there for the animate_topomap code, I noticed we were using an inefficient path: if we wanted an ndarray, we would fig.savefig to PNG then read this back to ndarray... when we could have accessed the fig.canvas data directly with proper casting. With this change, the report.add_evokeds is now bottlenecked by Agg draws, not our blitting code (1 and 2 above) or how we capture images (this point).

EDIT: Now allows lossy image saving, too, for speed and storage savings.

4. CircleCI

The CircleCI changes are just tacked on since they speed things up (and reduce cost!).

[wmvanvliet]

I appreciate the explanation, now I know why this is way more complicated then I thought it would be.

[larsoner]

Want me to split it up? Easy enough for me to do

[wmvanvliet]

Just trying to follow all the logic. But it looks good, no need to split this up into smaller PRs I think.

[wmvanvliet]

Now that things have moved around, this comment seems out of place. At this particular point, the code is clear: the caller asked for image_format="rgba" so that is what we will use. I think this comment needs to be further down (see my other comment)

[wmvanvliet]

Here is were we distinguish between whether the image was converted to svg/png or not and hence needs to be decoded. So this might be the place for a comment like "grab the pixels straight from the canvas"

[larsoner]

Fixed, thanks for the review @wmvanvliet ! Marking for merge-when-green