Improve open image section

[guiwitz]

References and relevant issues

Improving the section about images was discussed at the napari hackaton and in a more general PR about docs reorganisation.

Description

The PR expands and modernizes the previous version. The main improvement is a more detailed section about using reader plugins to import formats not natively supported by napari. In more details, the section now:

• shows how to use "bundle" importers, i.e. readers that group multiple readers for different formats. ndevio is used as an example
• shows how to use a single-format reader with napari-meshio as an example
• shows that different imports might generate different outcomes regarding dimensions. An example is shown on how to fix dimensions via a plugin using napari-skimage
• shows how to deal if multiple readers are available for a single format

All the examples use downloadable data (from openmicroscopy and the BioImage Archive) and are generated, not screenshots. As discussed in #working-group-documentation > Capturing images, this implies that plugins are required to build the documentation. I added dependencies to pixi.toml, but being a complete beginner with it, someone should check if that's correct (especially given the multiple sections with dependencies). Also those dependencies might be missing when not using pixi?

[TimMonko]

@guiwitz this is BEAUTIFUL. Gorgeous, fantastic, amazing, well written, and inspiring. You clearly spent a ton of time on this and I'm absolutely LOVING this contribution. I don't have too many comments because I really like the organization and flow.

Also... Holy smokes @guiwitz I actually had a panic attack. 😱 Have you actually tried ndevio? It's certainly mature enough that I share it with folks, but to put it in here like this is both an honor and so intimidating. I am a big believer in it, so getting eyes on it would be great lol. I guess the main flaw with it is that it's pypi only at the moment. It looks like I'd be able to add it to conda-forge with bioio-ome-tiff and bioio-ome-zarr (and the option for bioio-lif) which would at least be a start! I will work on it this week (regardless!). Unfortunately, I don't know of another "catch-all" reader that works with modern napari, so that might be the one to go with.

Would be good to get feedback from others.
Also, this might be a good file to mention https://github.com/napari/napari-tiff . I havne't worked on this much, so hopefully others can describe its value better than I can.

I added dependencies to pixi.toml, but being a complete beginner with it, someone should check if that's correct (especially given the multiple sections with dependencies). Also those dependencies might be missing when not using pixi?

For this, we have the unfortunate problem that we would need to add the dependencies to napari's pyproject -- the full build workflow on CI will fail right now (if we trigger it with the bot). https://github.com/napari/napari/blob/326d0144b22b7808cd16dfeb49c48590d94869d9/pyproject.toml#L276-L304
It's one of those complicated issues with how we have things organized, sadly.

But we can test with pixi though locally! i.e. pixi run docs-live. For some reason it seems like the code blocks aren't showing outputs, despite seeing C:\Users\timmo\Documents\GitHub\napari-docs\docs\getting_started/open_images.md: Executing notebook using local CWD [mystnb]... so I'll try to look into it

Good news too, the additional dependencies don't add too much, which is good and should be easily maintainable:

  + P aicspylibczi          3.3.1
  + P aiobotocore           3.1.0
  + P aioitertools          0.13.0
  + P bioio                 3.2.0
  + P bioio-base            3.2.0
  + P bioio-czi             2.4.2
  + P bioio-imageio         1.3.0
  + P bioio-ome-tiff        1.4.0
  + P bioio-ome-zarr        3.2.1
  + P bioio-tifffile        1.3.0
  + P botocore              1.42.19
  + P cmake                 4.2.1
  + P elementpath           5.1.0
  + P imagecodecs           2026.1.1
  + P jmespath              1.0.1
  + P kerchunk              0.2.9
  + P macro-kit             0.4.10
  + P magic-class           0.7.20
  + P napari-meshio         0.0.2
  + P napari-skimage        0.6.0
  + P nbatch                0.0.4
  + P ndev-settings         0.4.0
  + P ndevio                0.7.0
  + P ome-types             0.6.3
  + P pydantic-extra-types  2.11.0
  + P pylibczirw            5.1.1
  ~ P pyqt5-sip             12.17.2   ->  12.18.0
  + P s3fs                  2026.1.0
  + P semver                3.0.4
  + P ujson                 5.11.0
  + P validators            0.35.0
  + P xmlschema             4.3.0
  + P xmltodict             1.0.2
  + P xsdata                25.7

[TimMonko]

Once we release napari-metadata, I think this would be a good spot to also expose metadata (and would be my preference). At that point, I will likely reduce my I/O Utilities widget to be much slimmer and prioritize napari-metadata

[guiwitz]

I can also remove that section. But I find it useful to show that some readers offer more than just opening images. It's the case also e.g. for the napari-czitools (but I didn't want to have that plugin as a dependency).

[TimMonko]

This will be another spot we can refer to napari-metadata

[TimMonko]

Alright, I figured out the build issue, it's the matter of the pooch cells timing out because of the download time. By default, the cell execution limit is 30 seconds.

nbclient.exceptions.CellTimeoutError: A cell timed out while it was being executed, after 30 seconds.
The message was: Cell execution timed out.
Here is a preview of the cell contents:
-------------------
['import pooch', 'import os', 'from pathlib import Path', 'import napari', 'from napari.utils import nbscreenshot']
...
['        url="https://downloads.openmicroscopy.org/images/OME-TIFF/2016-06/MitoCheck/00001_01.ome.tiff",', "        known_hash='7c5c8c7c3e3a09ec38eb478fec47fc3458ba9cc79dda924b918cba83572054ab',", "        fname = '00001_01.ome.tiff',", '        path=Path(os.path.expanduser("~"))', '        )']
-------------------

While I think it makes sense to increase the timeout for this individual cell, perhaps we also want to consider smaller downloads?

Aha, yes its all so beautiful now once the cells execute. Not sure about the geometry warning though

[TimMonko]

oops, maybe this needs to be a string? The docs aren't making it obvious to me, where it looks like it doesn't need to be a string... https://myst-nb.readthedocs.io/en/latest/computation/execute.html#execution-timeout
I'm confused, but making it a string seemed to fix it locally... 🤷 I don't know why its not something like :tags: [execution_timeout = 300] I'm confused lol

Suggested change

	:execution: {"timeout": 300}
	:execution: {"timeout": "300"}

I currently get this error...

Exception occurred:
  File "C:\Users\timmo\Documents\GitHub\napari-docs\.pixi\envs\default\Lib\site-packages\nbformat\validator.py", line 509, in validate
    raise error
nbformat.validator.NotebookValidationError: 300 is not of type 'string'

Failed validating 'type' in notebook['properties']['metadata']['properties']['execution']['patternProperties']['^.*$']:

On instance['metadata']['execution']['timeout']:
300
The full traceback has been saved in C:\Users\timmo\AppData\Local\Temp\sphinx-err-bny55o5w.log, if you want to report the issue to the developers.

[TimMonko]

Or maybe it should be in the config at the top of the notebook?

[guiwitz]

I noted the same issue when trying to transforming the md file to notebook with jupytext complaining about that timeout, but I haven't figured out a solution yet. Will investigate more...

[guiwitz]

Regarding dependencies: is there an explanation anywhere on the "machinery" used to build docs? It's not clear to me why the dependencies have to be added to napari.

[melissawm]

I don't think there's anything beyond https://napari.org/stable/tutorials/fundamentals/installation.html#using-constraints-files . Unfortunately since we're using the two repos it's a bit convoluted, but this allows us to do

pip install napari[docs]

and have the docs dependencies follow the general constraints required for reliably building napari itself.

[DragaDoncila]

This is awesome @guiwitz 🤩 ! I left a couple of comments, but I think once we figure out the CI issues this is ready to go in. I mentioned to Tim earlier today that it would be great to expand a bit on the different File -> Open options (File, File(s), File(s) as stack, Folder...), but that should come in a separate PR imo.