napari-virtual-reader 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- napari_virtual_reader-0.0.1/.github/workflows/test_and_deploy_pypi.yml +92 -0
- napari_virtual_reader-0.0.1/.gitignore +8 -0
- napari_virtual_reader-0.0.1/CHANGELOG.md +25 -0
- napari_virtual_reader-0.0.1/LICENSE +27 -0
- napari_virtual_reader-0.0.1/PKG-INFO +174 -0
- napari_virtual_reader-0.0.1/README.md +138 -0
- napari_virtual_reader-0.0.1/_release_notes/v0.0.1.md +52 -0
- napari_virtual_reader-0.0.1/pyproject.toml +64 -0
- napari_virtual_reader-0.0.1/src/napari_virtual_reader/__init__.py +6 -0
- napari_virtual_reader-0.0.1/src/napari_virtual_reader/_metadata.py +174 -0
- napari_virtual_reader-0.0.1/src/napari_virtual_reader/_reader.py +389 -0
- napari_virtual_reader-0.0.1/src/napari_virtual_reader/_widget.py +219 -0
- napari_virtual_reader-0.0.1/src/napari_virtual_reader/napari.yaml +37 -0
- napari_virtual_reader-0.0.1/tests/test_manifest.py +40 -0
- napari_virtual_reader-0.0.1/tests/test_reader.py +327 -0
- napari_virtual_reader-0.0.1/tests/test_widget.py +208 -0
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
name: test_and_deploy_pypi
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
tags: ["v*"]
|
|
7
|
+
pull_request:
|
|
8
|
+
branches: [main]
|
|
9
|
+
workflow_dispatch:
|
|
10
|
+
|
|
11
|
+
permissions:
|
|
12
|
+
contents: read
|
|
13
|
+
|
|
14
|
+
jobs:
|
|
15
|
+
test:
|
|
16
|
+
name: ${{ matrix.platform }} py${{ matrix.python-version }}
|
|
17
|
+
runs-on: ${{ matrix.platform }}
|
|
18
|
+
timeout-minutes: 30
|
|
19
|
+
env:
|
|
20
|
+
QT_API: pyqt6
|
|
21
|
+
PYTEST_QT_API: pyqt6
|
|
22
|
+
strategy:
|
|
23
|
+
fail-fast: false
|
|
24
|
+
matrix:
|
|
25
|
+
platform: [ubuntu-latest, windows-latest, macos-latest]
|
|
26
|
+
python-version: ["3.12", "3.13", "3.14"]
|
|
27
|
+
|
|
28
|
+
steps:
|
|
29
|
+
- uses: actions/checkout@v4
|
|
30
|
+
|
|
31
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
32
|
+
uses: actions/setup-python@v5
|
|
33
|
+
with:
|
|
34
|
+
python-version: ${{ matrix.python-version }}
|
|
35
|
+
|
|
36
|
+
- name: Set up Qt libraries (Linux)
|
|
37
|
+
if: runner.os == 'Linux'
|
|
38
|
+
uses: tlambert03/setup-qt-libs@v1
|
|
39
|
+
|
|
40
|
+
- name: Install Windows OpenGL
|
|
41
|
+
if: runner.os == 'Windows'
|
|
42
|
+
run: |
|
|
43
|
+
git clone --depth 1 https://github.com/pyvista/gl-ci-helpers.git
|
|
44
|
+
powershell gl-ci-helpers/appveyor/install_opengl.ps1
|
|
45
|
+
|
|
46
|
+
- name: Install dependencies
|
|
47
|
+
run: |
|
|
48
|
+
python -m pip install --upgrade pip
|
|
49
|
+
python -m pip install -e ".[testing]" "napari[pyqt6]" build twine
|
|
50
|
+
|
|
51
|
+
- name: Check code quality
|
|
52
|
+
run: python -m ruff check src tests
|
|
53
|
+
|
|
54
|
+
- name: Run tests
|
|
55
|
+
uses: aganders3/headless-gui@v2
|
|
56
|
+
with:
|
|
57
|
+
run: python -m pytest -q tests
|
|
58
|
+
|
|
59
|
+
- name: Verify package builds
|
|
60
|
+
run: |
|
|
61
|
+
python -m build --sdist --wheel
|
|
62
|
+
python -m twine check dist/*
|
|
63
|
+
|
|
64
|
+
deploy:
|
|
65
|
+
needs: [test]
|
|
66
|
+
runs-on: ubuntu-latest
|
|
67
|
+
timeout-minutes: 15
|
|
68
|
+
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
|
|
69
|
+
steps:
|
|
70
|
+
- uses: actions/checkout@v4
|
|
71
|
+
with:
|
|
72
|
+
fetch-depth: 0
|
|
73
|
+
|
|
74
|
+
- name: Set up Python
|
|
75
|
+
uses: actions/setup-python@v5
|
|
76
|
+
with:
|
|
77
|
+
python-version: "3.12"
|
|
78
|
+
|
|
79
|
+
- name: Install publish dependencies
|
|
80
|
+
run: |
|
|
81
|
+
python -m pip install --upgrade pip
|
|
82
|
+
python -m pip install --upgrade build twine
|
|
83
|
+
|
|
84
|
+
- name: Build and publish to PyPI
|
|
85
|
+
env:
|
|
86
|
+
TWINE_USERNAME: __token__
|
|
87
|
+
TWINE_PASSWORD: ${{ secrets.NAPARI_VIRTUAL_READER_TOKEN }}
|
|
88
|
+
TWINE_NON_INTERACTIVE: "1"
|
|
89
|
+
run: |
|
|
90
|
+
python -m build
|
|
91
|
+
python -m twine check dist/*
|
|
92
|
+
python -m twine upload dist/*
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Notable changes to napari-virtual-reader are recorded here. Publication status
|
|
4
|
+
is recorded separately from the release preparation date.
|
|
5
|
+
|
|
6
|
+
## 0.0.1 - 2026-11-05
|
|
7
|
+
|
|
8
|
+
### Added
|
|
9
|
+
|
|
10
|
+
- Experimental Alpha napari plugin with npe2 reader and widget registration.
|
|
11
|
+
- Lazy, reference-backed OME-Zarr image loading through refkv.
|
|
12
|
+
- Optional VZIP reference-archive saving without pixel conversion.
|
|
13
|
+
- Shared metadata inspector for Zarr structure and selected-layer metadata.
|
|
14
|
+
- Compatible CZI scene stacking and stored multiscale pyramid support.
|
|
15
|
+
- Automated tests, package validation, and tag-triggered PyPI publishing.
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
|
|
19
|
+
- Renamed the project from napari-refkv to napari-virtual-reader.
|
|
20
|
+
|
|
21
|
+
### Release Status
|
|
22
|
+
|
|
23
|
+
Initial experimental Alpha release, prepared for tag `v0.0.1`. GitHub Actions
|
|
24
|
+
and PyPI publication are pending. See the [release notes](_release_notes/v0.0.1.md)
|
|
25
|
+
for features, validation, and known limitations.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
Copyright (c) 2026, Sebastian Rhode
|
|
2
|
+
All rights reserved.
|
|
3
|
+
|
|
4
|
+
Redistribution and use in source and binary forms, with or without
|
|
5
|
+
modification, are permitted provided that the following conditions are met:
|
|
6
|
+
|
|
7
|
+
* Redistributions of source code must retain the above copyright notice, this
|
|
8
|
+
list of conditions and the following disclaimer.
|
|
9
|
+
|
|
10
|
+
* Redistributions in binary form must reproduce the above copyright notice,
|
|
11
|
+
this list of conditions and the following disclaimer in the documentation
|
|
12
|
+
and/or other materials provided with the distribution.
|
|
13
|
+
|
|
14
|
+
* Neither the name of napari-virtual-reader nor the names of its
|
|
15
|
+
contributors may be used to endorse or promote products derived from
|
|
16
|
+
this software without specific prior written permission.
|
|
17
|
+
|
|
18
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
19
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
20
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
21
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
22
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
23
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
24
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
25
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
26
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
27
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: napari-virtual-reader
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Experimental napari plugin for lazy virtual OME-Zarr images via refkv
|
|
5
|
+
Project-URL: Homepage, https://github.com/sebi06/napari-virtual-reader
|
|
6
|
+
Project-URL: Bug Tracker, https://github.com/sebi06/napari-virtual-reader/issues
|
|
7
|
+
Project-URL: Documentation, https://github.com/sebi06/napari-virtual-reader#readme
|
|
8
|
+
Project-URL: Source Code, https://github.com/sebi06/napari-virtual-reader
|
|
9
|
+
Author-email: Sebastian Rhode <sebrhode@gmail.com>
|
|
10
|
+
License-Expression: BSD-3-Clause
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: napari,ome-zarr,plugin,virtual
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Framework :: napari
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Image Processing
|
|
22
|
+
Requires-Python: >=3.12
|
|
23
|
+
Requires-Dist: dask[array]>=2024.1
|
|
24
|
+
Requires-Dist: napari>=0.10.0
|
|
25
|
+
Requires-Dist: numpy>=2
|
|
26
|
+
Requires-Dist: qtpy>=2.4
|
|
27
|
+
Requires-Dist: refkv[images,zarr]>=0.2.0
|
|
28
|
+
Requires-Dist: superqt>=0.7
|
|
29
|
+
Requires-Dist: zarr>=3.4
|
|
30
|
+
Provides-Extra: testing
|
|
31
|
+
Requires-Dist: pytest-qt>=4.4; extra == 'testing'
|
|
32
|
+
Requires-Dist: pytest>=8; extra == 'testing'
|
|
33
|
+
Requires-Dist: ruff>=0.9; extra == 'testing'
|
|
34
|
+
Requires-Dist: tifffile; extra == 'testing'
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
# napari-virtual-reader
|
|
38
|
+
|
|
39
|
+
**Experimental software - Alpha status.** APIs and behavior may change without
|
|
40
|
+
notice. Validate results independently before relying on them for analysis.
|
|
41
|
+
|
|
42
|
+
Open image files as lazy, reference-backed OME-Zarr in napari. No pixel
|
|
43
|
+
conversion, copied image data, or intermediate archive is required.
|
|
44
|
+
|
|
45
|
+
The plugin uses refkv directly. It does not depend on czitools, pylibCZIrw,
|
|
46
|
+
or the napari-czitools plugin.
|
|
47
|
+
|
|
48
|
+
## Install
|
|
49
|
+
|
|
50
|
+
Python 3.12 or newer is required. Install into the environment running napari:
|
|
51
|
+
|
|
52
|
+
```powershell
|
|
53
|
+
python -m pip install napari-virtual-reader
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
A working Qt backend is required. For a fresh environment:
|
|
57
|
+
|
|
58
|
+
```powershell
|
|
59
|
+
python -m pip install "napari[pyqt6]" napari-virtual-reader
|
|
60
|
+
napari
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Restart napari after installation. The package registers an npe2 reader and
|
|
64
|
+
widget through its `napari.manifest` entry point; no manual registration is
|
|
65
|
+
required. Check **Plugins > Plugin Manager** for **napari-virtual-reader**.
|
|
66
|
+
|
|
67
|
+
## Open an image
|
|
68
|
+
|
|
69
|
+
In napari, choose **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**,
|
|
70
|
+
select the input, and click **Open**. Preparation runs in a background worker; napari
|
|
71
|
+
provides its normal layer, contrast, time, and Z controls.
|
|
72
|
+
|
|
73
|
+
You can also use **File > Open** or drop a file on the napari canvas and choose
|
|
74
|
+
the napari-virtual-reader reader. Drop a file on the plugin dock to select it without
|
|
75
|
+
opening it yet.
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
import napari
|
|
79
|
+
|
|
80
|
+
viewer = napari.Viewer()
|
|
81
|
+
viewer.open("image.czi", plugin="napari-virtual-reader")
|
|
82
|
+
napari.run()
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Raw images are virtualized in memory through `refkv.zarrify.zarrify`. Existing
|
|
86
|
+
`.vzip` archives are opened directly. Original image files must remain available
|
|
87
|
+
and unchanged for as long as their layers are used. Nothing is written beside
|
|
88
|
+
the source by default.
|
|
89
|
+
|
|
90
|
+
### Save a VZIP Archive
|
|
91
|
+
|
|
92
|
+
In **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**, select an image and enable
|
|
93
|
+
**Save VZIP archive** before clicking **Open**. Choose the destination in the
|
|
94
|
+
save dialog; the suggested filename is a sibling `.vzip`. Saving runs in the
|
|
95
|
+
background, and the resulting image still opens lazily with the metadata panel.
|
|
96
|
+
The status shows the saved filename, with its full path available on hover.
|
|
97
|
+
|
|
98
|
+
Saving stores references to the original image, not converted pixel data.
|
|
99
|
+
The archive covers the complete source, including all scenes and pyramid levels.
|
|
100
|
+
Existing destinations require explicit replacement confirmation; failed writes
|
|
101
|
+
leave the old archive intact. Cancelling the save dialog cancels the open action.
|
|
102
|
+
The save option is disabled for inputs that are already VZIP archives.
|
|
103
|
+
File/Open and canvas drops remain in-memory operations without automatic saving.
|
|
104
|
+
|
|
105
|
+
## Metadata Inspector
|
|
106
|
+
|
|
107
|
+
The **Virtual Zarr metadata** dock opens on the right when using the refkv reader
|
|
108
|
+
through File/Open or drag-and-drop, without opening the plugin widget first.
|
|
109
|
+
It also appears with **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**.
|
|
110
|
+
Both workflows share one inspector that follows the selected image layer.
|
|
111
|
+
|
|
112
|
+
- **Zarr structure** shows expandable groups and arrays, including original
|
|
113
|
+
shapes, dtypes, attributes, chunk grids and codec configuration.
|
|
114
|
+
- **Metadata** shows the selected layer's OME metadata, source and channel
|
|
115
|
+
information, plus original scene transforms for stacked CZI images.
|
|
116
|
+
- A filter finds matching properties; selecting a row shows its complete,
|
|
117
|
+
selectable value below the tree.
|
|
118
|
+
|
|
119
|
+
The inspector uses a metadata-only snapshot collected in the background. It
|
|
120
|
+
does not scan pixel data or reconstruct the source hierarchy from displayed
|
|
121
|
+
layer shapes. Selecting an unrelated layer clears the inspector.
|
|
122
|
+
|
|
123
|
+
## Scope
|
|
124
|
+
|
|
125
|
+
- CZI, TIFF/OME-TIFF, and other refkv-supported files that expose OME image series.
|
|
126
|
+
Reader registration includes common microscopy and volumetric image extensions;
|
|
127
|
+
actual support is determined by refkv's parser and the file's metadata/codecs.
|
|
128
|
+
- One layer per channel. Compatible CZI scenes are stacked lazily along a leading
|
|
129
|
+
**S** axis, in numeric series order; for example, 28 equally sized 2D scenes
|
|
130
|
+
become one `(28, Y, X)` layer per channel. This also applies to CZI-derived
|
|
131
|
+
VZIP archives. Other formats retain separate series layers.
|
|
132
|
+
- CZI stacking requires matching axes, shapes, dtypes, physical scales and
|
|
133
|
+
pyramid levels. Incompatible scenes remain separate without cropping or
|
|
134
|
+
resampling. Scene-dependent stage origins are replaced by local coordinates
|
|
135
|
+
on the stacked layer; original origins and metadata remain available in
|
|
136
|
+
the layer's `metadata["scenes"]` list.
|
|
137
|
+
- Stored multiscale pyramids, OME axis ordering, physical scale/origin, channel
|
|
138
|
+
names, colors, and display windows.
|
|
139
|
+
- Regular and rectilinear chunk grids, without scanning complete lazy arrays
|
|
140
|
+
for contrast limits. Files without display windows use dtype bounds (0-1 for
|
|
141
|
+
floating point); adjust contrast in napari as needed.
|
|
142
|
+
- OME-Zarr 0.4 and 0.5 image metadata, including nested image hierarchies.
|
|
143
|
+
|
|
144
|
+
This is deliberately not a replacement for every refkv dataset interface:
|
|
145
|
+
non-image tables, audio, arbitrary tensors, remote inputs, and stores without
|
|
146
|
+
OME image metadata are outside this first version. There are no custom dimension
|
|
147
|
+
sliders or CZI-specific options.
|
|
148
|
+
|
|
149
|
+
## Development
|
|
150
|
+
|
|
151
|
+
```powershell
|
|
152
|
+
git clone https://github.com/sebi06/napari-virtual-reader.git
|
|
153
|
+
cd napari-virtual-reader
|
|
154
|
+
python -m pip install -e ".[testing]"
|
|
155
|
+
python -m pytest
|
|
156
|
+
python -m ruff check .
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Install a Qt backend as above if the development environment does not already
|
|
160
|
+
provide one. Development installs register the same napari plugin as PyPI installs.
|
|
161
|
+
|
|
162
|
+
## Releases
|
|
163
|
+
|
|
164
|
+
GitHub Actions tests pull requests and pushes to `main`. Publishing runs only
|
|
165
|
+
after the test matrix passes on a release tag such as `v0.0.1`.
|
|
166
|
+
|
|
167
|
+
Set `project.version` in `pyproject.toml` to the intended release version before
|
|
168
|
+
tagging; tags do not change the package version. PyPI requires a new
|
|
169
|
+
version for every upload. Manual workflow runs test and build without publishing.
|
|
170
|
+
|
|
171
|
+
See the [changelog](CHANGELOG.md) for the change history and the
|
|
172
|
+
[release notes](_release_notes/v0.0.1.md) for v0.0.1 features, validation, and
|
|
173
|
+
limitations. Publication status is recorded in those files and updated after
|
|
174
|
+
GitHub Actions and PyPI publication are verified.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# napari-virtual-reader
|
|
2
|
+
|
|
3
|
+
**Experimental software - Alpha status.** APIs and behavior may change without
|
|
4
|
+
notice. Validate results independently before relying on them for analysis.
|
|
5
|
+
|
|
6
|
+
Open image files as lazy, reference-backed OME-Zarr in napari. No pixel
|
|
7
|
+
conversion, copied image data, or intermediate archive is required.
|
|
8
|
+
|
|
9
|
+
The plugin uses refkv directly. It does not depend on czitools, pylibCZIrw,
|
|
10
|
+
or the napari-czitools plugin.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
Python 3.12 or newer is required. Install into the environment running napari:
|
|
15
|
+
|
|
16
|
+
```powershell
|
|
17
|
+
python -m pip install napari-virtual-reader
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
A working Qt backend is required. For a fresh environment:
|
|
21
|
+
|
|
22
|
+
```powershell
|
|
23
|
+
python -m pip install "napari[pyqt6]" napari-virtual-reader
|
|
24
|
+
napari
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Restart napari after installation. The package registers an npe2 reader and
|
|
28
|
+
widget through its `napari.manifest` entry point; no manual registration is
|
|
29
|
+
required. Check **Plugins > Plugin Manager** for **napari-virtual-reader**.
|
|
30
|
+
|
|
31
|
+
## Open an image
|
|
32
|
+
|
|
33
|
+
In napari, choose **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**,
|
|
34
|
+
select the input, and click **Open**. Preparation runs in a background worker; napari
|
|
35
|
+
provides its normal layer, contrast, time, and Z controls.
|
|
36
|
+
|
|
37
|
+
You can also use **File > Open** or drop a file on the napari canvas and choose
|
|
38
|
+
the napari-virtual-reader reader. Drop a file on the plugin dock to select it without
|
|
39
|
+
opening it yet.
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import napari
|
|
43
|
+
|
|
44
|
+
viewer = napari.Viewer()
|
|
45
|
+
viewer.open("image.czi", plugin="napari-virtual-reader")
|
|
46
|
+
napari.run()
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Raw images are virtualized in memory through `refkv.zarrify.zarrify`. Existing
|
|
50
|
+
`.vzip` archives are opened directly. Original image files must remain available
|
|
51
|
+
and unchanged for as long as their layers are used. Nothing is written beside
|
|
52
|
+
the source by default.
|
|
53
|
+
|
|
54
|
+
### Save a VZIP Archive
|
|
55
|
+
|
|
56
|
+
In **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**, select an image and enable
|
|
57
|
+
**Save VZIP archive** before clicking **Open**. Choose the destination in the
|
|
58
|
+
save dialog; the suggested filename is a sibling `.vzip`. Saving runs in the
|
|
59
|
+
background, and the resulting image still opens lazily with the metadata panel.
|
|
60
|
+
The status shows the saved filename, with its full path available on hover.
|
|
61
|
+
|
|
62
|
+
Saving stores references to the original image, not converted pixel data.
|
|
63
|
+
The archive covers the complete source, including all scenes and pyramid levels.
|
|
64
|
+
Existing destinations require explicit replacement confirmation; failed writes
|
|
65
|
+
leave the old archive intact. Cancelling the save dialog cancels the open action.
|
|
66
|
+
The save option is disabled for inputs that are already VZIP archives.
|
|
67
|
+
File/Open and canvas drops remain in-memory operations without automatic saving.
|
|
68
|
+
|
|
69
|
+
## Metadata Inspector
|
|
70
|
+
|
|
71
|
+
The **Virtual Zarr metadata** dock opens on the right when using the refkv reader
|
|
72
|
+
through File/Open or drag-and-drop, without opening the plugin widget first.
|
|
73
|
+
It also appears with **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**.
|
|
74
|
+
Both workflows share one inspector that follows the selected image layer.
|
|
75
|
+
|
|
76
|
+
- **Zarr structure** shows expandable groups and arrays, including original
|
|
77
|
+
shapes, dtypes, attributes, chunk grids and codec configuration.
|
|
78
|
+
- **Metadata** shows the selected layer's OME metadata, source and channel
|
|
79
|
+
information, plus original scene transforms for stacked CZI images.
|
|
80
|
+
- A filter finds matching properties; selecting a row shows its complete,
|
|
81
|
+
selectable value below the tree.
|
|
82
|
+
|
|
83
|
+
The inspector uses a metadata-only snapshot collected in the background. It
|
|
84
|
+
does not scan pixel data or reconstruct the source hierarchy from displayed
|
|
85
|
+
layer shapes. Selecting an unrelated layer clears the inspector.
|
|
86
|
+
|
|
87
|
+
## Scope
|
|
88
|
+
|
|
89
|
+
- CZI, TIFF/OME-TIFF, and other refkv-supported files that expose OME image series.
|
|
90
|
+
Reader registration includes common microscopy and volumetric image extensions;
|
|
91
|
+
actual support is determined by refkv's parser and the file's metadata/codecs.
|
|
92
|
+
- One layer per channel. Compatible CZI scenes are stacked lazily along a leading
|
|
93
|
+
**S** axis, in numeric series order; for example, 28 equally sized 2D scenes
|
|
94
|
+
become one `(28, Y, X)` layer per channel. This also applies to CZI-derived
|
|
95
|
+
VZIP archives. Other formats retain separate series layers.
|
|
96
|
+
- CZI stacking requires matching axes, shapes, dtypes, physical scales and
|
|
97
|
+
pyramid levels. Incompatible scenes remain separate without cropping or
|
|
98
|
+
resampling. Scene-dependent stage origins are replaced by local coordinates
|
|
99
|
+
on the stacked layer; original origins and metadata remain available in
|
|
100
|
+
the layer's `metadata["scenes"]` list.
|
|
101
|
+
- Stored multiscale pyramids, OME axis ordering, physical scale/origin, channel
|
|
102
|
+
names, colors, and display windows.
|
|
103
|
+
- Regular and rectilinear chunk grids, without scanning complete lazy arrays
|
|
104
|
+
for contrast limits. Files without display windows use dtype bounds (0-1 for
|
|
105
|
+
floating point); adjust contrast in napari as needed.
|
|
106
|
+
- OME-Zarr 0.4 and 0.5 image metadata, including nested image hierarchies.
|
|
107
|
+
|
|
108
|
+
This is deliberately not a replacement for every refkv dataset interface:
|
|
109
|
+
non-image tables, audio, arbitrary tensors, remote inputs, and stores without
|
|
110
|
+
OME image metadata are outside this first version. There are no custom dimension
|
|
111
|
+
sliders or CZI-specific options.
|
|
112
|
+
|
|
113
|
+
## Development
|
|
114
|
+
|
|
115
|
+
```powershell
|
|
116
|
+
git clone https://github.com/sebi06/napari-virtual-reader.git
|
|
117
|
+
cd napari-virtual-reader
|
|
118
|
+
python -m pip install -e ".[testing]"
|
|
119
|
+
python -m pytest
|
|
120
|
+
python -m ruff check .
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Install a Qt backend as above if the development environment does not already
|
|
124
|
+
provide one. Development installs register the same napari plugin as PyPI installs.
|
|
125
|
+
|
|
126
|
+
## Releases
|
|
127
|
+
|
|
128
|
+
GitHub Actions tests pull requests and pushes to `main`. Publishing runs only
|
|
129
|
+
after the test matrix passes on a release tag such as `v0.0.1`.
|
|
130
|
+
|
|
131
|
+
Set `project.version` in `pyproject.toml` to the intended release version before
|
|
132
|
+
tagging; tags do not change the package version. PyPI requires a new
|
|
133
|
+
version for every upload. Manual workflow runs test and build without publishing.
|
|
134
|
+
|
|
135
|
+
See the [changelog](CHANGELOG.md) for the change history and the
|
|
136
|
+
[release notes](_release_notes/v0.0.1.md) for v0.0.1 features, validation, and
|
|
137
|
+
limitations. Publication status is recorded in those files and updated after
|
|
138
|
+
GitHub Actions and PyPI publication are verified.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# napari-virtual-reader v0.0.1
|
|
2
|
+
|
|
3
|
+
Status: Release prepared; GitHub Actions and PyPI publication pending.
|
|
4
|
+
Release preparation date: 2026-11-05.
|
|
5
|
+
|
|
6
|
+
## Highlights
|
|
7
|
+
|
|
8
|
+
- Initial experimental Alpha release of napari-virtual-reader.
|
|
9
|
+
- Open supported images as lazy, reference-backed OME-Zarr without pixel conversion.
|
|
10
|
+
- Use napari's File/Open reader or the asynchronous plugin widget.
|
|
11
|
+
|
|
12
|
+
## What Changed
|
|
13
|
+
|
|
14
|
+
- Registered the reader and widget through the npe2 `napari.manifest` entry point.
|
|
15
|
+
- Added per-channel layers with OME axes, transforms, pyramids, colors, and display windows.
|
|
16
|
+
- Added compatible CZI scene stacking while retaining original scene metadata.
|
|
17
|
+
- Added atomic VZIP reference-archive saving with overwrite confirmation, without copying pixels.
|
|
18
|
+
- Added a shared, read-only inspector for Zarr structure and selected-layer metadata.
|
|
19
|
+
- Renamed napari-refkv to napari-virtual-reader, including its Python module and repository.
|
|
20
|
+
- Added automated tests and a test-gated, tag-triggered PyPI publishing workflow.
|
|
21
|
+
|
|
22
|
+
## Validation
|
|
23
|
+
|
|
24
|
+
- Local Windows test suite: 32 tests passed.
|
|
25
|
+
- Ruff lint checks passed.
|
|
26
|
+
- Source distribution and wheel built successfully with Hatchling.
|
|
27
|
+
- Strict Twine metadata and README checks passed for both distributions.
|
|
28
|
+
- npe2 discovered a non-editable wheel installation and resolved its reader and widget commands.
|
|
29
|
+
- Public PyPI has compatible releases for the declared runtime dependencies.
|
|
30
|
+
- GitHub Actions tests Windows, Linux, and macOS with Python 3.12-3.14; release-run results are pending.
|
|
31
|
+
|
|
32
|
+
## Publication
|
|
33
|
+
|
|
34
|
+
- Release tag: `v0.0.1` (pending creation).
|
|
35
|
+
- Release commit: The commit referenced by the annotated `v0.0.1` tag.
|
|
36
|
+
- GitHub release: [v0.0.1](https://github.com/sebi06/napari-virtual-reader/releases/tag/v0.0.1).
|
|
37
|
+
- PyPI version: [0.0.1](https://pypi.org/project/napari-virtual-reader/0.0.1/).
|
|
38
|
+
|
|
39
|
+
The URLs above are publication targets, not confirmation of successful publication.
|
|
40
|
+
|
|
41
|
+
## Known Limitations
|
|
42
|
+
|
|
43
|
+
- Experimental Alpha software: APIs and behavior may change without notice.
|
|
44
|
+
- Python 3.12 or newer, napari 0.10.0 or newer, and a working Qt backend are required.
|
|
45
|
+
- Original sources must remain available and unchanged while layers or VZIP archives reference them.
|
|
46
|
+
- Format support depends on refkv and the source's metadata and codecs, not just its extension.
|
|
47
|
+
- Only local images and VZIP archives with supported OME metadata are accepted.
|
|
48
|
+
- Remote inputs and non-image datasets are outside this release's scope.
|
|
49
|
+
- Incompatible CZI scenes remain separate rather than being cropped or resampled.
|
|
50
|
+
- Missing display windows use dtype bounds; floating-point images default to 0-1 contrast.
|
|
51
|
+
- Contrast may need manual adjustment.
|
|
52
|
+
- Validate results independently before relying on them for analysis.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.26"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "napari-virtual-reader"
|
|
7
|
+
version = "0.0.1"
|
|
8
|
+
description = "Experimental napari plugin for lazy virtual OME-Zarr images via refkv"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "BSD-3-Clause"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.12"
|
|
13
|
+
authors = [
|
|
14
|
+
{name = "Sebastian Rhode", email = "sebrhode@gmail.com"}
|
|
15
|
+
]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 3 - Alpha",
|
|
18
|
+
"Intended Audience :: Science/Research",
|
|
19
|
+
"Framework :: napari",
|
|
20
|
+
"Topic :: Scientific/Engineering :: Image Processing",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Programming Language :: Python :: 3.14",
|
|
25
|
+
"Operating System :: OS Independent",
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
keywords = ["napari", "plugin", "ome-zarr", "virtual"]
|
|
29
|
+
|
|
30
|
+
dependencies = [
|
|
31
|
+
"napari>=0.10.0",
|
|
32
|
+
"refkv[zarr,images]>=0.2.0",
|
|
33
|
+
"zarr>=3.4",
|
|
34
|
+
"dask[array]>=2024.1",
|
|
35
|
+
"numpy>=2",
|
|
36
|
+
"qtpy>=2.4",
|
|
37
|
+
"superqt>=0.7",
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
[project.optional-dependencies]
|
|
41
|
+
testing = ["pytest>=8", "pytest-qt>=4.4", "ruff>=0.9", "tifffile"]
|
|
42
|
+
|
|
43
|
+
[project.entry-points."napari.manifest"]
|
|
44
|
+
napari-virtual-reader = "napari_virtual_reader:napari.yaml"
|
|
45
|
+
|
|
46
|
+
[project.urls]
|
|
47
|
+
"Homepage" = "https://github.com/sebi06/napari-virtual-reader"
|
|
48
|
+
"Bug Tracker" = "https://github.com/sebi06/napari-virtual-reader/issues"
|
|
49
|
+
"Documentation" = "https://github.com/sebi06/napari-virtual-reader#readme"
|
|
50
|
+
"Source Code" = "https://github.com/sebi06/napari-virtual-reader"
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
[tool.hatch.build.targets.wheel]
|
|
54
|
+
packages = ["src/napari_virtual_reader"]
|
|
55
|
+
|
|
56
|
+
[tool.pytest.ini_options]
|
|
57
|
+
testpaths = ["tests"]
|
|
58
|
+
|
|
59
|
+
[tool.ruff]
|
|
60
|
+
target-version = "py312"
|
|
61
|
+
line-length = 88
|
|
62
|
+
|
|
63
|
+
[tool.ruff.lint]
|
|
64
|
+
select = ["E4", "E7", "E9", "F", "I"]
|