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.
- napari_virtual_reader-0.0.3/.github/workflows/docs-pages.yml +49 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/.github/workflows/test_and_deploy_pypi.yml +2 -4
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/.gitignore +3 -1
- napari_virtual_reader-0.0.3/CHANGELOG.md +91 -0
- napari_virtual_reader-0.0.3/PKG-INFO +313 -0
- napari_virtual_reader-0.0.3/README.md +277 -0
- napari_virtual_reader-0.0.3/_docs/README.md +48 -0
- napari_virtual_reader-0.0.3/_docs/czi-tile-assembly.html +893 -0
- napari_virtual_reader-0.0.3/_docs/czi-tile-assembly.mmd +9 -0
- napari_virtual_reader-0.0.3/_docs/czi-tile-assembly.src.html +178 -0
- napari_virtual_reader-0.0.3/_docs/index.html +719 -0
- napari_virtual_reader-0.0.3/_docs/index.src.html +15 -0
- napari_virtual_reader-0.0.3/_docs/plugin-workflow.html +862 -0
- napari_virtual_reader-0.0.3/_docs/plugin-workflow.mmd +11 -0
- napari_virtual_reader-0.0.3/_docs/plugin-workflow.src.html +149 -0
- napari_virtual_reader-0.0.3/_release_notes/v0.0.3.md +81 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/pyproject.toml +3 -3
- napari_virtual_reader-0.0.3/src/napari_virtual_reader/__init__.py +11 -0
- napari_virtual_reader-0.0.3/src/napari_virtual_reader/_czi_mosaic.py +473 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/src/napari_virtual_reader/_metadata.py +48 -16
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/src/napari_virtual_reader/_reader.py +206 -25
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/src/napari_virtual_reader/_widget.py +32 -6
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/src/napari_virtual_reader/napari.yaml +4 -0
- napari_virtual_reader-0.0.3/tests/test_czi_mosaic.py +230 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/tests/test_reader.py +153 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/tests/test_widget.py +27 -17
- napari_virtual_reader-0.0.2/CHANGELOG.md +0 -47
- napari_virtual_reader-0.0.2/PKG-INFO +0 -179
- napari_virtual_reader-0.0.2/README.md +0 -143
- napari_virtual_reader-0.0.2/src/napari_virtual_reader/__init__.py +0 -6
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/LICENSE +0 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_images/czi_virtual_omezarr1.png +0 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_images/czi_virtual_omezarr2.png +0 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_images/reader_plugin.png +0 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_release_notes/v0.0.1.md +0 -0
- {napari_virtual_reader-0.0.2 → napari_virtual_reader-0.0.3}/_release_notes/v0.0.2.md +0 -0
- {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
|
-
|
|
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
|
|
@@ -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).
|