search

napari / docs

Documentation for napari (other than API docs)
BSD 3-Clause "New" or "Revised" License
11 stars 36 forks source link

Documenting file formats supported by napari ecosystem #44

Open junxini opened 2 years ago

junxini commented 2 years ago

🚀 Feature

Prior to opening a file, I want to know which file formats are supported, so that I know whether the napari ecosystem can be used to view my image

Current behavior (0.4.16)

There’s a lack of documentation that guides the user through the image loading step and informs them of formats that are supported by napari

Pitch

Additional context

This feature request is under epic https://github.com/napari/napari/issues/4611, in collaboration with @DragaDoncila, @chili-chiu, and @Lisa-czi

Czaki commented 2 years ago

This requires dropping npe1 plugins.

alisterburt commented 2 years ago

Thanks for this @junxini - to clarify

A full list of file formats supported by the napari ecosystem broken down by:

What do you mean exactly by 'a full list', where do you want this to live? A full list of everything NOT installed by the user will likely become huge - I can imagine this living in the docs somewhere as a reference but can't see it living in napari itself in a particularly useful way

DragaDoncila commented 2 years ago

This requires dropping npe1 plugins.

With the shim work we should be able to discern file formats supported by legacy plugins as well as new npe2 ones, albeit maybe with a lesser degree of confidence.

What do you mean exactly by 'a full list', where do you want this to live?

At a minimum this should be a list of file formats supported by builtins, and would live on the website. Currently this should be everything on this list, and maybe it would be as easy as just linking out to this list. I do think this should be relatively front and centre on the website - it's strange that right now there's nowhere you can go to find out what we can read.

In terms of the full ecosystem including plugins, we will soon support filtering by file extensions on the hub, but we may also want to provide a dedicated search functionality for formats on the hub. This will also be supported by napari/napari#4614

chili-chiu commented 2 years ago

At a minimum this should be a list of file formats supported by builtins, and would live on the website. Currently this should be everything on this list, and maybe it would be as easy as just linking out to this list. I do think this should be relatively front and centre on the website - it's strange that right now there's nowhere you can go to find out what we can read.

@DragaDoncila is it accurate to say that napari supports file formats included in the imageio library plus Numpy-like arrays (e.g. Zarr)? Are there other reader libraries napari use?

Also, is the image layer page the right place to include this information?

DragaDoncila commented 2 years ago

@chili-chiu yes that is correct, you would just add CSV, npy and zarr to that list. There are no other reader functions that we currently use, so this would be a comprehensive listing.

In terms of where to put it maybe it should be on the image layer page, but also on the getting started page? I would imagine it's something if want to see pretty early on in my napari journey as a user.

melissawm commented 2 years ago

Moving this over to the napari/docs repo - please continue the discussion there!

psobolewskiPhD commented 1 year ago

Bumping this. I definitely think it would be helpful to have a docs page dedicated to opening/importing images, which would outline what builtins covers and suggest a few plugins for common formats. For example, one thing I've found confusing for example, is napari zarr support. At present it seems like we just say napari can handle Zarr and that's it: https://napari.org/stable/search.html?q=zarr There is a lot of scattered info on image.sc but it's also not always clear what is current, etc. Zarr is definitely a Thing now, so having one place where it's spelled out what napari can do with it would be great. e.g. my current understanding is with pip install zarr napari can handle vanilla zarr via builtins, but not ome-zarr, which requires a plugin, napari-ome-zarr: https://github.com/ome/napari-ome-zarr

Some additional plugins that appear useful in this domain: napari-hierarchical supports hdf5: https://github.com/jwindhager/napari-hierarchical the one mentioned above: https://github.com/manzt/napari-lazy-openslide and another WSI plugin: https://github.com/AstraZeneca/napari-wsi

Edit: note I don't think we need to document every plugin, but list some key players for key formats and point to the hub which lets you search by extension.

DragaDoncila commented 1 year ago

@psobolewskiPhD yeah, agreed we probably need to have a dedicated doc on importing/opening files, and common plugins. Of course I'm hesitant to recommend specific plugins just because I don't know the state of maintenance and we can't necessarily "vouch" for any of them, but I agree there are some that should absolutely be highlighted, including napari-aicsimageio probably?

psobolewskiPhD commented 9 months ago

File > Open File vs File > Open with plugin should also be documented as part of this effort, see https://github.com/napari/napari/pull/4347