API for programmatically loading single elements into Napari

Use case

• As a plugin developer, I want to programmatically display a single SpatialData image so that my plugin can support SpatialData as storage format and provide interaction specific to some element(s).

Workarounds

Currently, I have these options:

• ✓ Instruct the user to open the GUI of napari-spatialdata, double-click on (the only) coordinate system, double-click on the image name.
• ✗ Request Napari to use the plugin for opening the SpatialData path:

  viewer.open(sdata_path, plugin="napari-spatialdata")
  

  Here, I cannot pass the element name. **kwargs are passed to Napari's add_layer method, so there is no way to extend this. Also, napari-spatialdata returns layer data [(None,)] which is a sentinal that tells Napari that the plugin successfully read the path, but loaded no layer.
• ✗ Request Napari to use the plugin for opening the element path:

  viewer.open(sdata_path / "images" / image_name, plugin="napari-spatialdata")
  

  This is an invalid command, the plugin only accepts valid SpatialData paths, not subpaths to contained elements.
• ✓ Reimplement everything on my own.
  Use spatialdata.read_zarr(sdata_path).images[image_name] and pass the array and transformation to Napari. However, I have to handle both SpatialImage/MultiscaleSpatialImage, extract the scale levels to a plain list, order the axes, convert the transformation to a plain matrix… basically rebuilding the private function _adjust_channels_order (which I cannot savely import) and add_sdata_image.

It remains for discussion whether such an API should:

• add the element to the viewer
• or just read and convert the SpatialData element to arguments that can be passed to viewer.add_image(…) so that the user/developer has further control over passing them to the viewer.

Requirements:

• Given a SpatialData path, element names (and optional coordinate system), read and convert the element to be compatible with Napari, for example as layer data tuple Tuple[DataType, Metadata, LayerName].
• If adding the element to the viewer, return a reference to the layer.
• Allow loading without GUI because it takes a lot of screen space and can hinder using other Napari plugins at the same time.

Start by tracing the existing napari-spatialdata loading path, including viewer.open, add_sdata_image, and the private _adjust_channels_order helper. Compare spatialdata.read_zarr(sdata_path).images[image_name] with the current GUI flow, then define whether the API adds a layer or returns Napari-compatible layer data. Done means a named element can be loaded without the GUI and, if applicable, a layer reference is returned.