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

[TimMonko]

Here is a quick summary of the why of my changes:

1. start from simplest to most advanced with each section (so samples, to builtin, to plugins, to code)
2. remove any mention of pip for plugin/extra installs, and refer to napari-plugin-manager so its compatible for all libraries
3. remove the "extra functionality" widgets included with readers, partly because this deserves a different page on inspecting data and because...
4. added napari-metadata to the section with napari-skimage for explanation on viewing and altering image display and metadata

Again thank you so so so so so much for this work @guiwitz, it might look like I did a lot, but I mostly just built on your great PR and moved things around 🥳 🍻

[TimMonko]

@napari-bot make html

[DragaDoncila]

@napari-bot make html

[DragaDoncila]

@TimMonko looks like there's a legitimate docs build issue here. I've had a read through the content and I think it's good otherwise!

[guiwitz]

Changes look great @TimMonko, especially the new napari-metadata section!

I had a look at the issue, which I only understood after creating a fresh local environment: we demo how to use ndevio to open a CZI file, but we don't have bioio-czi in the dependencies. This comes back to the earlier discussion whether the microscopy format discussion should entirely move to its own advanced section. Here we could then just demo opening a regular tiff image (originally I wanted to show how to open a zarr file, which is a default format for ndevio but never got it to work).

[guiwitz]

@TimMonko I opened an issue here about the problem opening zarr files.

[jni]

Thanks @DragaDoncila for reminding me to look at this PR. I love all the autogeneration going on here! Some comments:

• I think images (e.g. screenshots) in raw.github should be in _static
• I think data that is in raw.github should be moved to Cloudflare. Once we agree on a strategy I can move them.
• Other files would also be good to have under our control, e.g. someone's psu.edu page, so maybe we can say what the source is but store a copy in Cloudflare and build from that. Thoughts? (Bioimage Archive maybe we can just leave, that seems less temporary.)
• I kinda disagree with @TimMonko that the new dependencies are "small", and his list makes me kinda nervous, but I think it would be hairy to reduce them, so let's go ahead if we can get CI working.
• let's set the download directory at the top of the file (and make it if necessary), defaulting to, for example, ~/Desktop/napari-docs-build, not ~. Files in ~ are not visible on most OSs so the building the docs locally would be adding cruft to people's computer that they would have a hard time seeing.

[jni]

This should be added to _static. We decided a while back not to rely on raw.githubusercontent links in the docs, as they could one day be throttled.

[guiwitz]

This is from the napari-metadata plugin not the docs. Should we duplicate that file?

[guiwitz]

I now modified the download path to ~/Desktop/napari-docs-build

[guiwitz]

I now removed the dependency to the CZI reader and I'm opening a v5 ome.zarr file which ndevio supports by default. This is possible thanks to a recent fix to ndevio by @TimMonko, so it will only work build correctly once Tim makes a new release of ndevio. The idea is just to show something else than a tiff file without depending on another install, but if someone has a better idea, let me know. I changed to

[guiwitz]

One last question to the docs people. I see references to both the plugin section from the docs and the napari-plugin-manager docs (which I didn't know existed). Is that ok, should we only point to the manger? Are all the plugin manager docs going to move to that new location?