{"name":"napari-virtual-reader","display_name":"napari-virtual-reader","visibility":"public","icon":null,"categories":[],"schema_version":"0.2.1","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"napari-virtual-reader.get_reader","title":"Open as virtual OME-Zarr","python_name":"napari_virtual_reader._reader:napari_get_reader","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-virtual-reader.widget","title":"Open virtual OME-Zarr","python_name":"napari_virtual_reader._widget:VirtualReaderWidget","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":[{"command":"napari-virtual-reader.get_reader","filename_patterns":["*.czi","*.tif","*.tiff","*.svs","*.ndpi","*.nd2","*.lif","*.ims","*.vsi","*.qptiff","*.dcm","*.dicom","*.nii","*.nii.gz","*.nrrd","*.nhdr","*.mrc","*.map","*.vzip"],"accepts_directories":false}],"writers":null,"widgets":[{"command":"napari-virtual-reader.widget","display_name":"Open Data as virtual OME-ZARR","autogenerate":false,"default_dock_area":"right","tabify":false}],"sample_data":null,"themes":null,"menus":{},"submenus":null,"keybindings":null,"configurations":{}},"package_metadata":{"metadata_version":"2.5","name":"napari-virtual-reader","version":"0.0.2","dynamic":null,"platform":null,"supported_platform":null,"summary":"Experimental napari plugin for lazy virtual OME-Zarr images via refkv","description":"# napari-virtual-reader\n\n**Experimental software - Alpha status.** APIs and behavior may change without\nnotice. Validate results independently before relying on them for analysis.\n\nOpen image files as lazy, reference-backed OME-Zarr in napari. No pixel\nconversion, copied image data, or intermediate archive is required.\n\nThe plugin uses refkv directly. It does not depend on czitools, pylibCZIrw,\nor the napari-czitools plugin.\n\n<img src=\"https://raw.githubusercontent.com/sebi06/napari-virtual-reader/main/_images/czi_virtual_omezarr1.png\" alt=\"Alt Text\" style=\"width:80%; height:auto;\">\n\n## Install\n\nPython 3.12 or newer is required. Install into the environment running napari:\n\n```powershell\npython -m pip install napari-virtual-reader\n```\n\nA working Qt backend is required. For a fresh environment:\n\n```powershell\npython -m pip install \"napari[pyqt6]\" napari-virtual-reader\nnapari\n```\n\nRestart napari after installation. The package registers an npe2 reader and\nwidget through its `napari.manifest` entry point; no manual registration is\nrequired. Check **Plugins > Plugin Manager** for **napari-virtual-reader**.\n\n## Open an image\n\nIn napari, choose **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**,\nselect the input, and click **Open**. Preparation runs in a background worker; napari\nprovides its normal layer, contrast, time, and Z controls.\n\n<img src=\"https://raw.githubusercontent.com/sebi06/napari-virtual-reader/main/_images/reader_plugin.png\" alt=\"Alt Text\" style=\"width:50%; height:auto;\">\n\nYou can also use **File > Open** or drop a file on the napari canvas and choose\nthe napari-virtual-reader reader. Drop a file on the plugin dock to select it without\nopening it yet.\n\n```python\nimport napari\n\nviewer = napari.Viewer()\nviewer.open(\"image.czi\", plugin=\"napari-virtual-reader\")\nnapari.run()\n```\n\nRaw images are virtualized in memory through `refkv.zarrify.zarrify`. Existing\n`.vzip` archives are opened directly. Original image files must remain available\nand unchanged for as long as their layers are used. Nothing is written beside\nthe source by default.\n\n### Save a VZIP Archive\n\nIn **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**, select an image and enable\n**Save VZIP archive** before clicking **Open**. Choose the destination in the\nsave dialog; the suggested filename is a sibling `.vzip`. Saving runs in the\nbackground, and the resulting image still opens lazily with the metadata panel.\nThe status shows the saved filename, with its full path available on hover.\n\nSaving stores references to the original image, not converted pixel data.\nThe archive covers the complete source, including all scenes and pyramid levels.\nExisting destinations require explicit replacement confirmation; failed writes\nleave the old archive intact. Cancelling the save dialog cancels the open action.\nThe save option is disabled for inputs that are already VZIP archives.\nFile/Open and canvas drops remain in-memory operations without automatic saving.\n\n## Metadata Inspector\n\nThe **Virtual Zarr metadata** dock opens on the right when using the refkv reader\nthrough File/Open or drag-and-drop, without opening the plugin widget first.\nIt also appears with **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**.\nBoth workflows share one inspector that follows the selected image layer.\n\n- **Zarr structure** shows expandable groups and arrays, including original\n  shapes, dtypes, attributes, chunk grids and codec configuration.\n- **Metadata** shows the selected layer's OME metadata, source and channel\n  information, plus original scene transforms for stacked CZI images.\n- A filter finds matching properties; selecting a row shows its complete,\n  selectable value below the tree.\n\n<img src=\"https://raw.githubusercontent.com/sebi06/napari-virtual-reader/main/_images/czi_virtual_omezarr2.png\" alt=\"Alt Text\" style=\"width:80%; height:auto;\">\n\nThe inspector uses a metadata-only snapshot collected in the background. It\ndoes not scan pixel data or reconstruct the source hierarchy from displayed\nlayer shapes. Selecting an unrelated layer clears the inspector.\n\n## Scope\n\n- CZI, TIFF/OME-TIFF, and other refkv-supported files that expose OME image series.\n  Reader registration includes common microscopy and volumetric image extensions;\n  actual support is determined by refkv's parser and the file's metadata/codecs.\n- One layer per channel. Compatible CZI scenes are stacked lazily along a leading\n  **S** axis, in numeric series order. This also applies to CZI-derived\n  VZIP archives. Other formats retain separate series layers.\n- CZI stacking requires matching axes, shapes, dtypes, physical scales and\n  pyramid levels. Incompatible scenes remain separate without cropping or\n  resampling. Scene-dependent stage origins are replaced by local coordinates\n  on the stacked layer; original origins and metadata remain available in\n  the layer's `metadata[\"scenes\"]` list.\n- Stored multiscale pyramids, OME axis ordering, physical scale/origin, channel\n  names, colors, and display windows.\n- Regular and rectilinear chunk grids, without scanning complete lazy arrays\n  for contrast limits. Files without display windows use dtype bounds (0-1 for\n  floating point); adjust contrast in napari as needed.\n- OME-Zarr 0.4 and 0.5 image metadata, including nested image hierarchies.\n\nThis is deliberately not a replacement for every refkv dataset interface:\nnon-image tables, audio, arbitrary tensors, remote inputs, and stores without\nOME image metadata are outside this first version. There are no custom dimension\nsliders or CZI-specific options.\n\n## Development\n\n```powershell\ngit clone https://github.com/sebi06/napari-virtual-reader.git\ncd napari-virtual-reader\npython -m pip install -e \".[testing]\"\npython -m pytest\npython -m ruff check .\n```\n\nInstall a Qt backend as above if the development environment does not already\nprovide one. Development installs register the same napari plugin as PyPI installs.\n\n## Releases\n\nGitHub Actions tests pull requests and pushes to `main`. Publishing runs only\nafter the test matrix passes on a release tag in the form `vX.Y.Z`.\n\nSet `project.version` in `pyproject.toml` to the intended release version before\ntagging; tags do not change the package version. PyPI requires a new\nversion for every upload. Manual workflow runs test and build without publishing.\n\nSee the [changelog](CHANGELOG.md) for the change history and the\n[release notes](_release_notes/) for release-specific features, validation, and\nlimitations. Published tags and release details are available on\n[GitHub Releases](https://github.com/sebi06/napari-virtual-reader/releases).\n","description_content_type":"text/markdown","keywords":"napari,ome-zarr,plugin,virtual","home_page":null,"download_url":null,"author":null,"author_email":"Sebastian Rhode <sebrhode@gmail.com>","maintainer":null,"maintainer_email":null,"license":null,"classifier":["Development Status :: 3 - Alpha","Framework :: napari","Intended Audience :: Science/Research","Operating System :: OS Independent","Programming Language :: Python :: 3","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.14","Topic :: Scientific/Engineering :: Image Processing"],"requires_dist":["dask[array]>=2024.1","napari>=0.10.0","numpy>=2","qtpy>=2.4","refkv[images,zarr]>=0.2.0","superqt>=0.7","zarr>=3.4","pytest-qt>=4.4; extra == 'testing'","pytest>=8; extra == 'testing'","ruff>=0.9; extra == 'testing'","tifffile; extra == 'testing'"],"requires_python":">=3.12","requires_external":null,"project_url":["Homepage, https://github.com/sebi06/napari-virtual-reader","Bug Tracker, https://github.com/sebi06/napari-virtual-reader/issues","Documentation, https://github.com/sebi06/napari-virtual-reader#readme","Source Code, https://github.com/sebi06/napari-virtual-reader"],"provides_extra":["testing"],"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}