ENH: add overlay Brain GUI

[payamsash]

Reference issue (if any)

following #13995 and "We also have an issue with interactivity, in that the Brain interface can have widgets that control colorbar limits for example. So we'll want to add a "data key" (maybe there is some better name?) drop-down there that allows controlling the limits for the given key / set of data, and we'll need some private var to track the currently "active" (meaning: colorbar is the one shown, and the limits / smoothing etc. changed by GUI interaction) data key."

What does this implement/fix?

Add a box next to the "Color Limits", (it should be hidden when there's only one overlay), switching it should update _active_data_key and refresh the fmin/fmid/fmax/smoothing sliders. so when add_data(remove_existing=False) is called after the viewer is already open, the box should update its items. but we'd need to add a small set_items(items) method to _AbstractWdgt and put it in both _qt.py and _notebook.py, because now the set_range calls setRange(min, max) which is numeric-only and not compatible with QComboBox.

not sure if there's a simpler way? @larsoner

Additional information

I'll probably use Claude AI for code review.

[larsoner]

Feel free to ping me when to look or try!

Bonus points if you update an example to show this... maybe use multiple (dSPM, sLORETA, eLORETA?) solvers in https://mne.tools/stable/auto_tutorials/inverse/30_mne_dspm_loreta.html and overlay them with some suitable alpha and different colormaps (red/green/blue?). It could make for a cool visualization at the end of the example, and then easy to test interactively. But not obligatory if you have other ideas!

[payamsash]

Hi again Eric , please review #13995 first, then for this PR:

• with the interactive python it works as expected (try attached script), but with notebook I always need to do one extra click on the brain to make changes take effect. can you help with this?
• when we change the overlay we can control the cmap (and other stuff) for that overlay but we always have both (all) overlays on the brain surface, which I guess is what we wanted. but looking at this example (still rendering) its difficult to compare when they all overlap, so I would suggest that we could have a button like lock/unlock to control the overlays on the surface. wdyt @larsoner

[test_overlay.py](https://github.com/user-attachments/files/29881122/test_overlay.py)

[larsoner]

File did not attach properly... but I would say yes in the GUI having a visibility toggle for each data layer makes sense. But in my example having a fully transparent black->50% alpha green colormap, overlaid with a fully transparent black->50% alpha blue colormap, overlaid with the same in red it seems like you should be able to see where they overlap based on the hues and colors.

For notebook... it's not used super widely so is probably buggy. I don't use it in practice so your debugging might be as good as mine 😄

[payamsash]

ok, thanks @larsoner. so I leave the notebook issue to another fix (should I document it somewhere?), also pls check the example again and feel free to modify the params.

[larsoner]

Hah okay yeah this image:

Not super useful 😄 Feel free to adjust to something you think could be useful... maybe in some example overlay the visual response and auditory response in the same brain using just two colormaps instead? Might mirror a real-world use case a bit better

[larsoner]

Instead of messing with private attrs, can we use public ones but with a update=True default that you can set to update=False here?

[payamsash]

Done. Also I moved the example from 30_mne_dspm_loreta.py to 10_overview.py, because this tutorial already shows audio and visual activity in sensor space, so maybe adding the overlaid brain activity here is a good idea.

[larsoner]

Just pushed a little transparent=True fix

Thanks @payamsash !