napari-virtual-reader 0.0.2__tar.gz → 0.0.3__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.
Files changed (37) hide show
  1. napari_virtual_reader-0.0.3/.github/workflows/docs-pages.yml +49 -0
  2. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/.github/workflows/test_and_deploy_pypi.yml +2 -4
  3. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/.gitignore +3 -1
  4. napari_virtual_reader-0.0.3/CHANGELOG.md +91 -0
  5. napari_virtual_reader-0.0.3/PKG-INFO +313 -0
  6. napari_virtual_reader-0.0.3/README.md +277 -0
  7. napari_virtual_reader-0.0.3/_docs/README.md +48 -0
  8. napari_virtual_reader-0.0.3/_docs/czi-tile-assembly.html +893 -0
  9. napari_virtual_reader-0.0.3/_docs/czi-tile-assembly.mmd +9 -0
  10. napari_virtual_reader-0.0.3/_docs/czi-tile-assembly.src.html +178 -0
  11. napari_virtual_reader-0.0.3/_docs/index.html +719 -0
  12. napari_virtual_reader-0.0.3/_docs/index.src.html +15 -0
  13. napari_virtual_reader-0.0.3/_docs/plugin-workflow.html +862 -0
  14. napari_virtual_reader-0.0.3/_docs/plugin-workflow.mmd +11 -0
  15. napari_virtual_reader-0.0.3/_docs/plugin-workflow.src.html +149 -0
  16. napari_virtual_reader-0.0.3/_release_notes/v0.0.3.md +81 -0
  17. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/pyproject.toml +3 -3
  18. napari_virtual_reader-0.0.3/src/napari_virtual_reader/__init__.py +11 -0
  19. napari_virtual_reader-0.0.3/src/napari_virtual_reader/_czi_mosaic.py +473 -0
  20. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/src/napari_virtual_reader/_metadata.py +48 -16
  21. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/src/napari_virtual_reader/_reader.py +206 -25
  22. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/src/napari_virtual_reader/_widget.py +32 -6
  23. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/src/napari_virtual_reader/napari.yaml +4 -0
  24. napari_virtual_reader-0.0.3/tests/test_czi_mosaic.py +230 -0
  25. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/tests/test_reader.py +153 -0
  26. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/tests/test_widget.py +27 -17
  27. napari_virtual_reader-0.0.2/CHANGELOG.md +0 -47
  28. napari_virtual_reader-0.0.2/PKG-INFO +0 -179
  29. napari_virtual_reader-0.0.2/README.md +0 -143
  30. napari_virtual_reader-0.0.2/src/napari_virtual_reader/__init__.py +0 -6
  31. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/LICENSE +0 -0
  32. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_images/czi_virtual_omezarr1.png +0 -0
  33. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_images/czi_virtual_omezarr2.png +0 -0
  34. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_images/reader_plugin.png +0 -0
  35. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_release_notes/v0.0.1.md +0 -0
  36. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_release_notes/v0.0.2.md +0 -0
  37. {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/tests/test_manifest.py +0 -0
@@ -0,0 +1,49 @@
1
+ name: Publish visual guides
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ paths:
7
+ - "_docs/**"
8
+ - ".github/workflows/docs-pages.yml"
9
+ workflow_dispatch:
10
+
11
+ permissions:
12
+ contents: read
13
+
14
+ concurrency:
15
+ group: github-pages
16
+ cancel-in-progress: false
17
+
18
+ jobs:
19
+ deploy:
20
+ if: github.ref == 'refs/heads/main'
21
+ runs-on: ubuntu-latest
22
+ timeout-minutes: 10
23
+ permissions:
24
+ contents: read
25
+ pages: write
26
+ id-token: write
27
+ environment:
28
+ name: github-pages
29
+ url: ${{ steps.deployment.outputs.page_url }}
30
+ steps:
31
+ - uses: actions/checkout@v4
32
+
33
+ - name: Configure GitHub Pages
34
+ uses: actions/configure-pages@v5
35
+
36
+ - name: Stage standalone rendered pages
37
+ run: |
38
+ mkdir _site
39
+ cp _docs/index.html _docs/plugin-workflow.html _docs/czi-tile-assembly.html _site/
40
+ touch _site/.nojekyll
41
+
42
+ - name: Upload Pages artifact
43
+ uses: actions/upload-pages-artifact@v3
44
+ with:
45
+ path: _site
46
+
47
+ - name: Deploy GitHub Pages
48
+ id: deployment
49
+ uses: actions/deploy-pages@v4
@@ -39,14 +39,12 @@ jobs:
39
39
 
40
40
  - name: Install Windows OpenGL
41
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
42
+ uses: ssciwr/setup-mesa-dist-win@v3
45
43
 
46
44
  - name: Install dependencies
47
45
  run: |
48
46
  python -m pip install --upgrade pip
49
- python -m pip install -e ".[testing]" "napari[pyqt6]" build twine
47
+ python -m pip install -e ".[testing]" "napari[pyqt6]" "refkv[zarr,images]==0.2.0" build twine
50
48
 
51
49
  - name: Check code quality
52
50
  run: python -m ruff check src tests
@@ -5,4 +5,6 @@ __pycache__/
5
5
  .ruff_cache/
6
6
  .venv/
7
7
  build/
8
- dist/
8
+ dist/
9
+ /_drafts/image-sc-virtual-ome-zarr.md
10
+ /_docs/*.sheet*.png
@@ -0,0 +1,91 @@
1
+ # Changelog
2
+
3
+ <!-- markdownlint-configure-file {"MD024": {"siblings_only": true}} -->
4
+
5
+ Notable changes to napari-virtual-reader are recorded here. Publication status
6
+ is recorded separately from the release preparation date.
7
+
8
+ ## Unreleased
9
+
10
+ ## 0.0.3 - 2026-11-21
11
+
12
+ ### Changed
13
+
14
+ - Added lazy, chunk-local mosaic assembly for supported 2D CZI slide scans:
15
+ combine irregular native tiles and stored pyramid levels on a common extent,
16
+ preserve RGB/scalar channels and calibration, fill gaps with zero, and resolve
17
+ overlaps in numeric tile order. Record the assembly policy in layer metadata.
18
+ Unsupported tiles keep the incomplete-view warning. VZIP export retains the
19
+ original refkv layout, not the runtime mosaic.
20
+ - Warn when a CZI view omits unassembled tiles, including partial pyramids,
21
+ and preserve the warning in layer metadata. Applies to reader loads and
22
+ the opener, without reading pixels or changing image assembly.
23
+ - Packed-colour CZI images now open as one RGB/RGBA layer per acquisition
24
+ channel instead of separate B/G/R(/A) layers, including CZI-derived VZIP
25
+ metadata. Preserve lazy pyramids and scene stacks, handle codec-dependent
26
+ component order, and leave scalar fluorescence channels unchanged.
27
+ - Combined the file opener and metadata inspector in one plugin dock, with
28
+ loading and optional VZIP-save controls above the expanding inspector.
29
+ - File/Open, canvas drag-and-drop, and the plugin menu now share the same dock
30
+ regardless of opening order; reader loads reopen it when hidden.
31
+ - Added rendered visual guides for the plugin workflow and CZI tile assembly,
32
+ with automated GitHub Pages publishing.
33
+ - Marked the package as experimental Beta software.
34
+ - Pinned CI validation to PyPI's refkv 0.2.0 across the supported platform and
35
+ Python matrix; the runtime requirement remains refkv 0.2.0 or newer.
36
+
37
+ ### Fixed
38
+
39
+ - Prevented the metadata inspector from appearing as a separate dock above
40
+ the file-loading controls.
41
+ - Corrected the package's Beta classifier to the valid PyPI classifier.
42
+ - Replaced the legacy Windows CI OpenGL installer with maintained Mesa setup
43
+ for GUI validation.
44
+
45
+ ### Release Status
46
+
47
+ Release tag: `v0.0.3`. Tag-triggered GitHub Actions validates the supported
48
+ platforms and Python versions before publishing to PyPI.
49
+ See the [release notes](_release_notes/v0.0.3.md) for highlights, validation,
50
+ and known limitations.
51
+
52
+ ## 0.0.2 - 2026-11-06
53
+
54
+ ### Changed
55
+
56
+ - Added README screenshots of the plugin, image viewer, and metadata inspector.
57
+ - Used absolute screenshot URLs for GitHub and PyPI README rendering.
58
+ - Simplified the CZI scene-stacking description.
59
+ - Made the Releases section version-independent with permanent documentation links.
60
+
61
+ ### Fixed
62
+
63
+ - Replaced bracketed filename patterns with simple extension filters such as `*.czi` and `*.nii.gz` in the napari manifest.
64
+
65
+ ### Release Status
66
+
67
+ Patch release covering documentation and reader filename-pattern registration;
68
+ dependencies are unchanged.
69
+ Prepared for tag `v0.0.2`; GitHub Actions and PyPI publication are pending.
70
+ See the [release notes](_release_notes/v0.0.2.md) for details.
71
+
72
+ ## 0.0.1 - 2026-11-05
73
+
74
+ ### Added
75
+
76
+ - Experimental Alpha napari plugin with npe2 reader and widget registration.
77
+ - Lazy, reference-backed OME-Zarr image loading through refkv.
78
+ - Optional VZIP reference-archive saving without pixel conversion.
79
+ - Shared metadata inspector for Zarr structure and selected-layer metadata.
80
+ - Compatible CZI scene stacking and stored multiscale pyramid support.
81
+ - Automated tests, package validation, and tag-triggered PyPI publishing.
82
+
83
+ ### Changed
84
+
85
+ - Renamed the project from napari-refkv to napari-virtual-reader.
86
+
87
+ ### Release Status
88
+
89
+ Initial experimental Alpha release, prepared for tag `v0.0.1`. GitHub Actions
90
+ and PyPI publication are pending. See the [release notes](_release_notes/v0.0.1.md)
91
+ for features, validation, and known limitations.
@@ -0,0 +1,313 @@
1
+ Metadata-Version: 2.5
2
+ Name: napari-virtual-reader
3
+ Version: 0.0.3
4
+ Summary: Experimental napari plugin for reading microscopy image file formats, such as CZI as 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 :: 4 - Beta
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
+ A napari plugin for lazy, reference-backed OME-Zarr images using
40
+ [refkv](https://github.com/d-v-b/refkv).
41
+
42
+ ## Remarks
43
+
44
+ **Experimental software - Beta status.** APIs and behavior may change without
45
+ notice. Validate results independently before relying on them for analysis.
46
+
47
+ Open images without first converting them, writing a pixel copy, or creating
48
+ an intermediate archive. Requested regions are still decoded and composed in
49
+ memory for display; "virtual" does not mean zero memory use.
50
+
51
+ The plugin uses refkv directly. It does not depend on czitools, pylibCZIrw,
52
+ or the napari-czitools plugin.
53
+
54
+ This README describes the source checkout. Published releases may not yet include
55
+ all features below; see the [changelog](CHANGELOG.md) for unreleased changes.
56
+
57
+ The screenshots show the earlier two-dock layout. The current UI combines the
58
+ loading controls and metadata inspector in one dock.
59
+
60
+ <img src="https://raw.githubusercontent.com/sebi06/napari-virtual-reader/main/_images/czi_virtual_omezarr1.png" alt="CZI image displayed in napari with the earlier separate opener and metadata docks" style="width:80%; height:auto;">
61
+
62
+ ## Visual guides
63
+
64
+ - [How the plugin works](https://sebi06.github.io/napari-virtual-reader/plugin-workflow.html):
65
+ lazy loading, the combined dock, metadata and VZIP archives.
66
+ - [How CZI tile assembly works](https://sebi06.github.io/napari-virtual-reader/czi-tile-assembly.html):
67
+ tile placement, chunk reads, coordinate mapping, pyramids and limitations.
68
+
69
+ These links open rendered HTML on GitHub Pages, not GitHub's HTML source viewer.
70
+ The editable sources and standalone pages are in [_docs](_docs/);
71
+ see the [documentation publishing notes](_docs/README.md) for regeneration and deployment.
72
+
73
+ ## Install
74
+
75
+ Python 3.12 or newer is required. Install into the environment running napari:
76
+
77
+ ```powershell
78
+ python -m pip install napari-virtual-reader
79
+ ```
80
+
81
+ A working Qt backend is required. For a fresh environment:
82
+
83
+ ```powershell
84
+ python -m pip install "napari[pyqt6]" napari-virtual-reader
85
+ napari
86
+ ```
87
+
88
+ Restart napari after installation. The package registers an npe2 reader and
89
+ widget through its `napari.manifest` entry point; no manual registration is
90
+ required. Check **Plugins > Plugin Manager** for **napari-virtual-reader**.
91
+
92
+ The plugin is also listed on
93
+ [napari hub](https://napari-hub.org/plugins/napari-virtual-reader.html).
94
+
95
+ ## Format-specific features
96
+
97
+ ### CZI image files
98
+
99
+ - **RGB images:** brightfield colour images open as one RGB/RGBA layer per
100
+ acquisition channel, not separate red, green, and blue layers. Fluorescence
101
+ channels remain separate.
102
+ - **Large 2D images and pyramids:** supported 2D mosaics are assembled on demand,
103
+ including full resolution when native tiles are available. Napari switches
104
+ between stored resolution levels as you zoom, without loading the whole image
105
+ or writing a converted copy.
106
+ - **Multiple scenes:** compatible scenes share an **S** dimension slider.
107
+ Scenes with different sizes or scales remain separate.
108
+
109
+ **Why assembly helps:** refkv can expose irregular or overlapping CZI tiles
110
+ separately from its regular image levels. Reading only those levels can omit
111
+ native resolution or show just an overview. The plugin places supported tiles
112
+ using their CZI coordinates and groups them into the available resolution levels.
113
+ Placement restores the missing view; lazy, chunk-by-chunk reads make it practical
114
+ without building the whole slide in memory. It does not invent missing pixels
115
+ or resolution levels.
116
+
117
+ **This extra assembly is CZI-only.** Other formats can display images and pyramids
118
+ already exposed by refkv, but the plugin does **not yet assemble their separate
119
+ irregular tile arrays**. General lazy loading is not a general tile-assembly solution.
120
+
121
+ Open the **original CZI** to use mosaic assembly; reopening a VZIP archive
122
+ does not currently restore this assembly. Overlapping tiles use a fixed
123
+ "later tile wins" rule, so overlap regions can look different from ZEN.
124
+ If some tiles cannot be assembled, the plugin warns that the view may be
125
+ incomplete. See [Scope](#scope) for technical details and limitations.
126
+
127
+ ## Open an image
128
+
129
+ In napari, choose **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**,
130
+ select the input, and click **Open**. This dock prepares the image in a background
131
+ worker; napari provides its normal layer, contrast, time, and Z controls.
132
+
133
+ The plugin uses one dock: the file selector, **Save VZIP archive**, and **Open**
134
+ controls stay at the top, with the metadata inspector below. The inspector
135
+ receives the remaining vertical space as the dock is resized.
136
+
137
+ You can also use **File > Open** or drop a file on the napari canvas and choose
138
+ the napari-virtual-reader reader. Drop a file on the plugin dock to select it without
139
+ opening it yet.
140
+
141
+ ```python
142
+ import napari
143
+
144
+ viewer = napari.Viewer()
145
+ viewer.open("image.czi", plugin="napari-virtual-reader")
146
+ napari.run()
147
+ ```
148
+
149
+ Raw images are virtualized in memory through `refkv.zarrify.zarrify`. Existing
150
+ `.vzip` archives are opened directly. Original image files must remain available
151
+ and unchanged for as long as their layers are used. Nothing is written beside
152
+ the source by default.
153
+
154
+ ### Save a VZIP Archive
155
+
156
+ In **Plugins > napari-virtual-reader > Open Data as virtual OME-ZARR**, select an image and enable
157
+ **Save VZIP archive** before clicking **Open**. Choose the destination in the
158
+ save dialog; the suggested filename is a sibling `.vzip`. Saving runs in the
159
+ background, and the resulting image still opens lazily with the metadata panel.
160
+ The status shows the saved filename, with its full path available on hover.
161
+
162
+ Saving stores refkv's reference layout, not converted pixel data. It retains
163
+ the image series, pyramid levels and separate tile arrays exposed by refkv,
164
+ not just the selected napari layer. It is not a self-contained image backup:
165
+ the referenced source must remain available and unchanged.
166
+ Existing destinations require explicit replacement confirmation; failed writes
167
+ leave the old archive intact. Cancelling the save dialog cancels the open action.
168
+ The save option is disabled for inputs that are already VZIP archives.
169
+ File/Open and canvas drops remain in-memory operations without automatic saving.
170
+
171
+ The saved archive retains refkv's original reference layout, not the plugin's
172
+ runtime mosaic composition. Refkv's live pyramid-factor summary is not saved
173
+ in VZIP. If a CZI-derived archive contains separate tile arrays, reopening it
174
+ still warns about unassembled tiles; open the original CZI to use mosaic assembly.
175
+ Archive reads also depend on refkv's source-access policy; an archive can fail to
176
+ open if that policy does not permit its referenced local files.
177
+
178
+ ## Metadata Inspector
179
+
180
+ The metadata inspector is embedded below the loading controls in the
181
+ **Open Data as virtual OME-ZARR** dock, which opens on the right by default.
182
+ Using the refkv reader through File/Open or canvas drag-and-drop automatically
183
+ opens this same dock, without requiring the plugin menu first. Opening the
184
+ plugin from the menu before or after a reader load reuses the dock rather than
185
+ creating a second panel. A new reader load also reopens the dock if it was hidden.
186
+ The inspector follows the selected image layer, independently of how it was loaded.
187
+
188
+ - **Zarr structure** shows expandable groups and arrays, including original
189
+ shapes, dtypes, attributes, chunk grids and codec configuration.
190
+ - **Metadata** shows the selected layer's OME metadata, source and channel
191
+ information, plus original scene transforms for stacked CZI images.
192
+ - A filter finds matching properties; selecting a row shows its complete,
193
+ selectable value below the tree.
194
+
195
+ <img src="https://raw.githubusercontent.com/sebi06/napari-virtual-reader/main/_images/czi_virtual_omezarr2.png" alt="Zarr structure and image metadata in the earlier separate metadata dock" style="width:80%; height:auto;">
196
+
197
+ The inspector uses a metadata-only snapshot collected during reader preparation
198
+ (in the background when using the plugin's **Open** button). It does not scan
199
+ pixel data or reconstruct the source hierarchy from displayed layer shapes.
200
+ Selecting an unrelated layer clears the inspector.
201
+
202
+ ## Scope
203
+
204
+ - **Lazy CZI mosaic assembly:** for 2D slide-scan series with an OME image and
205
+ refkv's live pyramid-factor summary, the plugin assembles irregular and
206
+ overlapping tiles alongside the existing image levels. Full resolution is
207
+ included when native tiles are available. Each requested output chunk is at
208
+ most 1024 x 1024 pixels per acquisition channel and reads only intersecting
209
+ source regions. This bounds output tasks, not total memory: a compressed source
210
+ chunk can require full decoding, and concurrent tasks use separate buffers.
211
+ No full mosaic or converted image is written.
212
+ - Mosaic levels share the finest level's spatial extent. Coarse levels use
213
+ nearest-neighbour sampling to align differing origins and clipped/odd edges
214
+ with napari's shape-derived pyramid transforms. Native full-resolution
215
+ pixels are not resampled. Gaps are zero; overlaps use **later numeric refkv
216
+ tile wins**, with tiles drawn over any existing assembled level. This is
217
+ deterministic, not blending or image registration, and is not guaranteed to
218
+ match ZEN/libCZI overlap selection or codec rounding pixel-for-pixel.
219
+ `metadata["czi_assembly"]` records bounds, factors, full-resolution availability,
220
+ tile count, and compositing policy. The inspector's Zarr tree still describes
221
+ the original reference store, not the runtime mosaic.
222
+ Missing resolution levels are not generated, and gaps at one level are not
223
+ filled from another. Source read/decode errors propagate; they are not replaced
224
+ with zero-filled pixels.
225
+ - **Remaining incomplete CZI views:** time/Z tile stacks, scenes without an
226
+ OME image, unclassified tile scales, and VZIPs without the live calibration
227
+ summary are not assembled by this implementation. Unsupported tiles retain
228
+ the napari warning once per source load and `metadata["reader_warning"]`.
229
+ An input without any supported OME image still fails explicitly. Use
230
+ napari-czitools for those cases; do not assume a displayed pyramid is complete
231
+ when the warning is present.
232
+ - CZI, TIFF/OME-TIFF, and other refkv-supported files that expose OME image series.
233
+ Reader registration includes common microscopy and volumetric image extensions;
234
+ actual support is determined by refkv's parser and the file's metadata/codecs.
235
+ The extra tile assembler and incomplete-tile warning are CZI-specific; absence
236
+ of that warning for another format does not establish that its view is complete.
237
+ - One layer per acquisition channel. Packed-colour CZI images (`Bgr24`, `Bgr48`,
238
+ `Bgr96Float`, and `Bgra32`) open as RGB/RGBA layers rather than separate colour
239
+ components. Detection uses refkv's CZI profile and component chunk layout,
240
+ not channel count or names. Component order is corrected per pyramid level:
241
+ raw/Zstd/LZW BGR(A) is reordered, while JPEG/JPEG-XR RGB(A) is retained.
242
+ Complex-valued packed-colour CZI pixels are not supported.
243
+ - Compatible CZI scenes are stacked lazily along a leading
244
+ **S** axis, in numeric series order. This also applies to CZI-derived
245
+ VZIP archives. Other formats retain separate series layers.
246
+ - RGB/RGBA keeps its component axis last, outside napari's dimension sliders;
247
+ ordinary fluorescence channels remain separate additive layers. Loading and
248
+ reordering stay lazy, preserve pixel dtype, and do not write converted images.
249
+ - CZI stacking requires matching axes, shapes, dtypes, physical scales and
250
+ pyramid levels. Incompatible scenes remain separate without cropping or
251
+ resampling. Axes with differing scene origins use zero translation on the
252
+ stacked layer; shared origins are retained. Original origins and metadata
253
+ remain available in the layer's `metadata["scenes"]` list.
254
+ - Stored multiscale pyramids, OME axis ordering, physical scale/origin, channel
255
+ names, colors, and display windows.
256
+ - Regular and rectilinear chunk grids, without scanning complete lazy arrays
257
+ for contrast limits. Files without display windows use dtype bounds (0-1 for
258
+ floating point); adjust contrast in napari as needed.
259
+ - OME-Zarr 0.4 and 0.5 image metadata, including nested image hierarchies.
260
+
261
+ This is deliberately not a replacement for every refkv dataset interface:
262
+ non-image tables, audio, arbitrary tensors, remote inputs, and stores without
263
+ OME image metadata are outside this first version. There are no custom dimension
264
+ sliders or CZI-specific options.
265
+
266
+ ## Development
267
+
268
+ ```powershell
269
+ git clone https://github.com/sebi06/napari-virtual-reader.git
270
+ cd napari-virtual-reader
271
+ python -m pip install -e ".[testing]"
272
+ python -m pytest
273
+ python -m ruff check .
274
+ ```
275
+
276
+ Install a Qt backend as above if the development environment does not already
277
+ provide one. Development installs register the same napari plugin as PyPI installs.
278
+
279
+ Source guide:
280
+
281
+ - [_reader.py](src/napari_virtual_reader/_reader.py): reference stores, lazy
282
+ layers, axes, colours, scenes, warnings and archive saving.
283
+ - [_czi_mosaic.py](src/napari_virtual_reader/_czi_mosaic.py): native tile
284
+ placement, spatial indexing and on-demand pyramid composition.
285
+ - [_widget.py](src/napari_virtual_reader/_widget.py): loading controls,
286
+ preparation workers and Qt-thread delivery of layers.
287
+ - [_metadata.py](src/napari_virtual_reader/_metadata.py): shared dock access
288
+ and a read-only inspector built from metadata snapshots.
289
+
290
+ ## Releases
291
+
292
+ Version [0.0.3](_release_notes/v0.0.3.md) adds lazy 2D CZI mosaic assembly,
293
+ packed-colour CZI handling, a combined loading and metadata dock, and visual
294
+ documentation. The package remains experimental Beta software; review
295
+ [Scope](#scope) before using it for analysis.
296
+
297
+ The package workflow tests pull requests and pushes to `main` against
298
+ `refkv[zarr,images]==0.2.0` from PyPI on Linux, Windows, and macOS with
299
+ Python 3.12, 3.13, and 3.14. The runtime requirement remains refkv 0.2.0 or newer.
300
+ PyPI publishing
301
+ runs only after its test matrix passes on a pushed tag beginning with `v`;
302
+ use the release convention `vX.Y.Z`.
303
+
304
+ Set `project.version` in `pyproject.toml` to the intended release version before
305
+ tagging; tags do not change the package version. PyPI requires a new
306
+ version for every upload. Manual runs of the package workflow test and build
307
+ without publishing to PyPI. The separate documentation workflow publishes
308
+ GitHub Pages on relevant pushes to `main` or a manual run on `main`.
309
+
310
+ See the [changelog](CHANGELOG.md) for the change history and the
311
+ [release notes](_release_notes/) for release-specific features, validation, and
312
+ limitations. Published tags and release details are available on
313
+ [GitHub Releases](https://github.com/sebi06/napari-virtual-reader/releases).