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?

Depends on napari/napari#8581

[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

[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.

[TimMonko]

Woohoo! Once we have the dependencies in we can start building this and looking at it.
@guiwitz I think the only blocker here is the size of the remote data that you've introduced. Which is quite sad because the data you picked is really beautiful! (I want to make sure I stash these away somewhere for my own sake!)

We discussed this at last weeks docs meeting that we want to reduce the size of the pooch retrieved images because 1) it will slow down CI and 2) we are then pinging someone's servers constantly.

It's really nice that you were able to get these images from a place that isn't Zenodo, because we've had difficulty from them recently. Do you have any smaller data that we could use (ideally <5MB or so)? We are also happy to help locate data for this because we know how challenging it can be to locate stuff.

Also, napari-metadata is released, so we can rethink how to add that here. But I don't want to slow down this PR any more than we have, so we should perhaps save it for a follow-up :) (unless you want to work on it here)

[psobolewskiPhD]

Grrr, our constraints process failed again:
sphinx-external-toc was updated, it now depends on sphinx-multitoc-numbering, which doesn't explicitly support parallel builds, which triggers a warning, which is a fail.
But, our napari prs don't do a parallel build because they build examples, so the warnings didn't occur!

I tried to look into supressing that warning, but it wasn't really working.
I made issues with the two repos:

• v1.1.0: new sphinx_multitoc_numbering dependency results in warnings on parallel builds executablebooks/sphinx-external-toc#115
• When running a sphinx build in parallel, get warning that this extension isn't safe executablebooks/sphinx-multitoc-numbering#27

So I think for now it's best to just set upper pin on sphinx-external-toc.

[psobolewskiPhD]

@napari-bot make html

[psobolewskiPhD]

OK, here is the pinning PR: napari/napari#8591
And I ran a full build, which should skip the issue for now: https://app.circleci.com/pipelines/github/napari/docs/1775/workflows/5f92fb5a-bd1a-4d26-af04-e348e9114da4/jobs/1776

[psobolewskiPhD]

Alas, the fail looks real, related to the timeout:
https://github.com/napari/docs/actions/runs/21326630119/job/61385042991#step:9:636

[guiwitz]

It's really nice that you were able to get these images from a place that isn't Zenodo, because we've had difficulty from them recently. Do you have any smaller data that we could use (ideally <5MB or so)? We are also happy to help locate data for this because we know how challenging it can be to locate stuff.

@TimMonko I had not realized the issue was with the ome.tif file which is indeed quite large. I will search for another one. I guess the czi at 25Mb is fine? It would be hard to find a small one.

[psobolewskiPhD]

I think that download is going to be a problem. Maybe we can try the approach from:
napari/napari#8508
cc @Czaki

[TimMonko]

Here is a not very interesting 10MB czi that I took at one point. Just checked my local computer quick to see what I have. I could grab a smaller one probably in the coming days, but I don't really have much interesting to image right now.

https://drive.google.com/file/d/1TDP1u8UHb4q4-l_wljS2tOmmjQc4RA8s/view?usp=sharing

[guiwitz]

I modified a bit the document to use smaller images. Now the czi and tif file come from IDR and the BioImage Archive and are only around 4Mb in size, so hopefully the timeout issue should be gone.

[psobolewskiPhD]

@napari-bot make html

[psobolewskiPhD]

Looks like a code cell is failing 😭

/home/circleci/project/docs/docs/getting_started/open_images.md: WARNING: Notebook exception traceback saved in: /home/circleci/project/docs/docs/_build/html/reports/getting_started/open_images.err.log [mystnb.exec]

[psobolewskiPhD]

This is pretty great! Thanks for your efforts with this and bearing with us through all the various CI issues.
I made a few comments, which I think improve some phrasing.
My most important issues are:

• consistency in vocab: so using consistent naming and styling of file formats (tif or TIFF not a mix, etc.) and referring to the napari reader as builtin, like the GUI.
• concern about the pip installation instructions. I'd really prefer if this guide was focused on just reading data and didn't delve into pip installations and things, which are not universal. So maybe we can pick a different example plugin that is simpler to install and avoid that?