Autogenerate images of parts of the viewer (#621)

# References and Motivation

With 0.6.0 on the way, there have been _many_ changes to the UI from
0.5.6, especially when considering the years of napari development. Much
of these changes have been done by me, and in recognition of that, I
would like to update the current static images used throughout the docs
with dynamically generated ones, so that any future UI changes do not
require thorough updates of the docs. This PR was originally conceived
slightly before, and then [discussed at 2025-03-13/14 docs
meeting](https://hackmd.io/10DKrIMhREmk9sa_QRirlg#2025-03-1314); the
docs meeting concluded that this PR should be made quickly, merged, and
then checked for any flakiness (since it requires a merge) or appearance
issues in the auto-generation. Then, we can make specific updates to the
script (or new scripts) in order to improve visualization for various
places in the docs. These are presently designed as proof-of-principle
and change things as needed. Conceivably, this can also replace images
where we hide building up a napari viewer instance, only to take an
nbscreenshot. I believe this script method is considerably faster, but
does require a bit less intuitive of a setup compared to the screenshot
method. Overall, this takes less than 3 seconds to generate over 20
images. I'm aware that many of these are not currently needed in the
docs, but may provide inspiration and design principles, even for the
autogeneration, moving forward. We'll clean up what exactly is
autogenerated in follow-up PRs. In follow ups, we can also consider
adding unique stylings to Qt elements on the fly, such as making a
certain button of interest have a yellow border.

Useful current places:
1. [viewer
tutorial](https://napari.org/dev/tutorials/fundamentals/viewer.html#viewer-buttons)
buttons, popups (e.g. we just added grid popup and the buttons below are
already out of date),, anything with console, etc. quite a few static
images in here
2. [layers tutorial](https://napari.org/dev/guides/layers.html)
3. [quick
start](https://napari.org/dev/tutorials/fundamentals/quick_start.html).
console related images
4. [various buttons and images in how to each
layer](https://napari.org/dev/howtos/layers/image.html)

And in the future, because we can more quickly generate images, we can
conceivably use more focused images throughout the docs.

This will require doing something with doc merges as force-orphan to
prevent build up of repo size with changing binaries, though nicely,
these images are so far quite small in size (comparatively)

# Description

In one single file, our goal is to autogenerate various elements of the
UI; these are either initially gotten with `viewer.screenshot` of the
current viewer state, or in follow-ups as specific pixmaps of the
widgets (or a defined group of widgets). These pixmaps are defined by
dictionaries at the top of the file, making it easier to find and
contribute to an image of interest. It also serves as models for 'set
up' of different element types (popups, menus, other states)

These include:
1. single widget elements always visible in the UI 
2. menus, and specific submenus
3. triggered popup widgets, like grid, roll, ndisplay
4. groups of widgets. these are my favorite, but will take the most
thought to define because it allows us to dynamically 'crop' the viewer
to areas of interest. Lovely!

The current implementation prioritizes speed, but may need to add some
QTimer / sleep events for CI, not sure.

# Autogenerated image examples

## Viewer and folder structure

![image](https://github.com/user-attachments/assets/dc4b05f3-f485-4012-8d94-845f358f34c2)

## Single widgets

![image](https://github.com/user-attachments/assets/5a4fddad-410c-49f8-b3a1-e3e8ca23477c)

## Menus

![image](https://github.com/user-attachments/assets/c86426c9-6979-42ce-80ce-6cbdd3a03bf5)

## Popups

![image](https://github.com/user-attachments/assets/cc2611a9-95c2-4c8f-a35f-f81ad2285518)

## Combined groups of widgets

![image](https://github.com/user-attachments/assets/8a0ce0bf-5c37-407a-a6e4-571c19785c39)


# Original PR Description

This is _really_ a draft of trying to autogenerate images that we can
use throughout the docs. I think this would _also_ speed up doc
generation in certain areas with reusable doc images, so that
nbscreenshot would not need to be as frequent. Everything is getting
saved into `images/_autogenerated` and could be used elsewhere.

1. Tries to autogenerate grabbing and saving many parts of the viewer
using the attributes of the viewer

Needs:
1. Popups are not working right, sometimes they trigger, often its the
dims slider popup. I probably need to just directly call the button, but
I'm having a tough time figuring out where the buttons live.
6. I think the timing of things has me really confused. I think QTimer
is necessary to wait for things to popup, but I can't figure out why
these popups aren't working
7. Also sometimes the console popups and saves as a screenshot, other
times its just the thin dock area prior to the console popup.

Examples of what _should_ appear in autogenerated if CI does it the same
was as locally

![image](https://github.com/user-attachments/assets/a9e3be59-bd61-481e-a046-62251177f5a8)

---------

Co-authored-by: Melissa Weber Mendonça <[email protected]>

Author: TimMonko

docs/_scripts/autogenerate_gui_images.py

@@ -0,0 +1,377 @@
+from pathlib import Path
+
+from qtpy.QtCore import QTimer, QPoint, QRect
+import napari
+
+from napari._qt.qt_event_loop import get_qapp
+from napari._qt.qt_resources import get_stylesheet
+from napari._qt.dialogs.qt_modal import QtPopup
+from qtpy.QtWidgets import QApplication, QWidget
+
+DOCS = REPO_ROOT_PATH = Path(__file__).resolve().parent.parent
+IMAGES_PATH = DOCS / "images" / "_autogenerated"
+IMAGES_PATH.mkdir(parents=True, exist_ok=True)
+WIDGETS_PATH = IMAGES_PATH / "widgets"
+WIDGETS_PATH.mkdir(parents=True, exist_ok=True)
+MENUS_PATH = IMAGES_PATH / "menus"
+MENUS_PATH.mkdir(parents=True, exist_ok=True)
+POPUPS_PATH = IMAGES_PATH / "popups"
+POPUPS_PATH.mkdir(parents=True, exist_ok=True)
+REGION_PATH = IMAGES_PATH / "regions"
+REGION_PATH.mkdir(parents=True, exist_ok=True)
+
+def _get_widget_components(qt_window: QWidget) -> dict:
+    """Get visible widget components from the Qt window.
+    
+    Parameters
+    ----------
+    qt_window : QWidget
+        qt_window of the viewer.
+    
+    Returns
+    -------
+    dict
+        Dictionary with keys corresponding to widget names for saving
+        and values corresponding to the QWidget itself
+    """
+    return {
+        "welcome_widget": find_widget_by_class(qt_window, "QtWelcomeWidget"),
+        
+        "console_dock": find_widget_by_name(qt_window, "console"),
+        
+        "dimension_slider": find_widget_by_class(qt_window, "QtDims"),
+        
+        # Layer list components
+        "layer_list_dock": find_widget_by_name(qt_window, "layer list"),
+        "layer_buttons": find_widget_by_class(qt_window, "QtLayerButtons"),
+        "layer_list": find_widget_by_class(qt_window, "QtLayerList"),
+        "viewer_buttons": find_widget_by_class(qt_window, "QtViewerButtons"),
+        
+        # Layer controls
+        "layer_controls_dock": find_widget_by_name(qt_window, "layer controls"),
+       
+        # TODO: mouse over part of the image to show intensity stuff
+        "status_bar": find_widget_by_class(qt_window, "ViewerStatusBar"),
+    }
+    
+def _get_menu_components(qt_window: QWidget) -> dict:
+    """Get menu bar components from the Qt window.
+    
+    Parameters
+    ----------
+    qt_window : QWidget
+        qt_window of the viewer.
+        
+    Returns
+    -------
+    dict
+        Dictionary with keys corresponding to menu names for saving
+        and values corresponding to the menu widget location.
+    """
+    
+    return {
+        "file_menu": find_widget_by_name(qt_window, "napari/file"),
+        "samples_menu": find_widget_by_name(qt_window, "napari/file/samples/napari"),
+        "view_menu": find_widget_by_name(qt_window, "napari/view"),
+        "layers_menu": find_widget_by_name(qt_window, "napari/layers"),
+        "plugins_menu": find_widget_by_name(qt_window, "napari/plugins"),
+        "window_menu": find_widget_by_name(qt_window, "napari/window"),
+        "help_menu": find_widget_by_name(qt_window, "napari/help"),
+    }
+    
+def _get_button_popups_configs(
+    viewer: napari.Viewer,
+) -> list[dict]:
+    """Get configurations for capturing popups that appear when clicking on viewer buttons.
+    
+    Parameters
+    ----------
+    viewer : napari.Viewer
+    
+    Returns
+    -------
+    list[dict]
+        List of dictionaries with the following keys:
+        - name: str
+            Name of the popup.
+        - prep: callable
+            Function to prepare the viewer before opening the popup.
+        - button: QtViewerButton
+            Button that opens the popup.
+    """
+    viewer_buttons = find_widget_by_class(
+        viewer.window._qt_window,
+        "QtViewerButtons"
+    )
+    return [
+        {
+            "name": "ndisplay_2D_popup",
+            "prep": lambda: setattr(viewer.dims, "ndisplay", 2),
+            "button": viewer_buttons.ndisplayButton,
+        },
+        {
+            "name": "roll_dims_popup",
+            "prep": lambda: setattr(viewer.dims, "ndisplay", 2),
+            "button": viewer_buttons.rollDimsButton,
+        },
+        {
+            "name": "ndisplay_3D_popup",
+            "prep": lambda: setattr(viewer.dims, "ndisplay", 3),
+            "button": viewer_buttons.ndisplayButton,
+        },
+        {
+            "name": "grid_popup",
+            "prep": None,
+            "button": viewer_buttons.gridViewButton,
+        }
+    ]
+
+def _get_viewer_regions() -> list[dict]:
+    """Get regions of the viewer to capture as a single image.
+    
+    Returns
+    -------
+    list[dict]
+        List of dictionaries with the following keys:
+        - name: str
+            Name of the region.
+        - components: list of str
+            Names of components to determine the bounding region
+    """
+    return [
+        {
+            "name": "console_and_buttons",
+            "components": ["console_dock", "viewer_buttons"]
+        },
+        {
+            "name": "layer_list_and_controls",
+            "components": ["layer_list_dock", "layer_controls_dock"]
+        },
+    ]
+
+def autogenerate_images():
+    """Autogenerate images of the GUI components.
+    
+    This function opens a napari viewer, takes screenshots of the GUI components,
+    and saves them to the images/_autogenerated folder.
+    
+    At first, the viewer is prepped for various states and screenshots are taken
+    of the whole viewer, with a moused-over sample image. 
+    
+    Then, the function captures visible widgets, triggers menus, and then captures
+    right-click button popups.
+    
+    Finally, the viewer is closed and the Qt application is executed
+    to ensure all widgets are properly cleaned up.
+    """
+    app = get_qapp()
+    
+    # Create viewer with visible window
+    viewer = napari.Viewer(show=True)
+    
+    # Print Qt widget hierarchy
+    # print_widget_hierarchy(viewer.window._qt_window)
+    
+    viewer.window._qt_window.resize(1000, 800)
+    viewer.window._qt_window.setStyleSheet(get_stylesheet("dark"))
+    
+    # Ensure window is active
+    viewer.window._qt_window.activateWindow()
+    viewer.window._qt_window.raise_()
+    app.processEvents()
+    
+    viewer.screenshot(str(IMAGES_PATH / "viewer_empty.png"), canvas_only=False)
+    viewer.open_sample(plugin='napari', sample='cells3d')
+    
+    # Mouse over canvas for status bar update
+    viewer.layers.selection = [viewer.layers[0]]
+    viewer.mouse_over_canvas = True
+    viewer.cursor.position = [25, 50, 120]
+    viewer.update_status_from_cursor()
+    app.processEvents() # Ensure viewer is fully initialized
+
+    viewer.screenshot(str(IMAGES_PATH / "viewer_cells3d.png"), canvas_only=False)
+
+    # Open the console
+    viewer_buttons = find_widget_by_class(viewer.window._qt_window, "QtViewerButtons")
+    viewer_buttons.consoleButton.click()
+    app.processEvents()
+    
+    viewer.screenshot(str(IMAGES_PATH / "viewer_cells3d_console.png"), canvas_only=False)
+    
+    widget_componenets = _get_widget_components(viewer.window._qt_window)
+    for name, widget in widget_componenets.items():
+        capture_widget(widget, name)
+        
+    menu_components = _get_menu_components(viewer.window._qt_window)
+    for name, menu in menu_components.items():
+        capture_menu(menu, name)
+        
+    button_popups_configs = _get_button_popups_configs(viewer)
+    for config in button_popups_configs:
+        capture_popups(config)
+
+    for region in _get_viewer_regions():
+        capture_viewer_region(viewer, region["components"], region["name"])
+
+    close_all(viewer)
+    app.exec_()
+
+def capture_popups(config):
+    """Capture popups that appear when clicking on viewer buttons."""
+    app = get_qapp()
+    close_existing_popups()
+
+    if config["prep"] is not None:
+        config["prep"]()
+
+    app.processEvents()
+    config["button"].customContextMenuRequested.emit(QPoint())
+    app.processEvents()
+    popups = [w for w in QApplication.topLevelWidgets() if isinstance(w, QtPopup) and w.isVisible()]
+    
+    if not popups:
+        return print(f"No popup found for {config['name']}")
+
+    popup = popups[-1] # grab the most recent popup, just in case
+    
+    app.processEvents()
+
+    pixmap = popup.grab()
+    pixmap.save(str(POPUPS_PATH / f"{config['name']}.png"))
+    popup.close()
+    app.processEvents()
+
+def capture_widget(widget, name):
+    """Capture a widget and save it to a file."""
+    if widget is None:
+        return print(f"Could not find {name}")
+
+    pixmap = widget.grab()
+    pixmap.save(str(WIDGETS_PATH / f"{name}.png"))
+    return
+
+def capture_menu(menu, name):
+    """Show a menu and take screenshot of it."""
+    if menu is None:
+        return print(f"Could not find menu {name}")
+    
+    menu.popup(menu.parent().mapToGlobal(menu.pos()))
+    
+    pixmap = menu.grab()
+    pixmap.save(str(MENUS_PATH / f"{name}.png"))
+    menu.hide()
+    return
+
+def capture_viewer_region(viewer, component_names, save_name):
+    """Capture a screenshot of a region containing multiple components.
+    
+    Requires that the component is defined in _get_widget_components
+    
+    Parameters
+    ----------
+    viewer : napari.Viewer
+        The napari viewer
+    component_names : list of str
+        Names of components to determine the bounding region
+    save_name : str
+        Name of the output image file
+    """
+    app = get_qapp()
+    qt_window = viewer.window._qt_window
+    widget_components = _get_widget_components(qt_window)
+    
+    # Find the bounding rectangle for all requested components
+    min_x, min_y = float('inf'), float('inf')
+    max_x, max_y = float('-inf'), float('-inf')
+    
+    for name in component_names:
+        if name not in widget_components or widget_components[name] is None:
+            print(f"Component {name} not found, skipping")
+            continue
+            
+        widget = widget_components[name]
+        # Map to global coordinates
+        global_pos = widget.mapToGlobal(widget.rect().topLeft())
+        global_rect = widget.rect()
+        global_rect.moveTo(global_pos)
+        
+        min_x = min(min_x, global_rect.left())
+        min_y = min(min_y, global_rect.top())
+        max_x = max(max_x, global_rect.right())
+        max_y = max(max_y, global_rect.bottom())
+    
+    if min_x == float('inf'):
+        print(f"No valid components found for {save_name}")
+        return
+    
+    region = QRect(QPoint(min_x, min_y), QPoint(max_x, max_y))
+    
+    app.processEvents()
+    screen = QApplication.primaryScreen()
+    pixmap = screen.grabWindow(0, region.x(), region.y(), region.width(), region.height())
+    pixmap.save(str(REGION_PATH / f"{save_name}.png"))
+
+def close_all(viewer):
+    viewer.close()
+    QTimer.singleShot(10, lambda: get_qapp().quit())
+
+def close_existing_popups():
+    """Close any existing popups."""
+    for widget in QApplication.topLevelWidgets():
+        if isinstance(widget, QtPopup):
+            widget.close()
+            
+    get_qapp().processEvents()
+
+def find_widget_by_name(parent, name):
+    """Find a widget by its object name."""
+    if parent.objectName() == name:
+        return parent
+        
+    for child in parent.children():
+        if hasattr(child, 'objectName') and child.objectName() == name:
+            return child
+        
+        if hasattr(child, 'children'):
+            found = find_widget_by_name(child, name)
+            if found:
+                return found
+    
+    return None
+
+def find_widget_by_class(parent, class_name):
+    """Find a child widget by its class name."""
+    if parent.__class__.__name__ == class_name:
+        return parent
+        
+    for child in parent.children():
+        if child.__class__.__name__ == class_name:
+            return child
+        
+        if hasattr(child, 'children'):
+            found = find_widget_by_class(child, class_name)
+            if found:
+                return found
+    
+    return None
+
+
+def print_widget_hierarchy(widget, indent=0, max_depth=None):
+    """Print a hierarchy of child widgets with their class names and object names."""
+
+    if max_depth is not None and indent > max_depth:
+        return
+        
+    class_name = widget.__class__.__name__
+    object_name = widget.objectName()
+    name_str = f" (name: '{object_name}')" if object_name else ""
+    print(" " * indent + f"- {class_name}{name_str}")
+    
+    for child in widget.children():
+        if hasattr(child, "children"):
+            print_widget_hierarchy(child, indent + 4, max_depth)
+
+    
+if __name__ == "__main__":
+    autogenerate_images()