flimkit-zstack-explorer 0.1.0__tar.gz → 0.2.0__tar.gz

{flimkit_zstack_explorer-0.1.0 → flimkit_zstack_explorer-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flimkit-zstack-explorer
-Version: 0.1.0
+Version: 0.2.0
 Summary: 3D intensity and FLIM volume explorer for FLIMKit z-stacks
 Author-email: Alex Hunt <alexander.hunt@ed.ac.uk>
 License-Expression: MIT
@@ -33,21 +33,46 @@ and opens a popout 3D viewer with the two volumes side by side.
   display code (the same path used when you drag the z-slider), so the
   volume matches what's on screen slice by slice.
 - Saves a 2-channel OME-Zarr store (channel 0 = intensity, channel 1 =
-  lifetime in ns, NaN where a slice had no per-pixel fit).
+  lifetime in ns, NaN where a slice had no per-pixel fit). Saving to a path
+  that already has a store from a previous run overwrites it.
 - Opens a [PyVista](https://pyvista.org) volume viewer in its own process —
   intensity on the left, FLIM lifetime on the right, camera-linked — so it
   doesn't compete with FLIMKit's Tkinter UI for the main thread.
+- Intensity is clipped to its 99th percentile before rendering, the same
+  clip FLIMKit's own 2D intensity view uses, so a few hot pixels don't wash
+  out the whole volume.
+- The FLIM pane has live sliders for the lifetime min/max color range
+  (defaulting to the 2nd/98th percentile, like FLIMKit's "Auto" scale
+  button) and a colormap picker with the same palette as FLIMKit's 2D FLIM
+  view (hsv, viridis, cool, hot, twilight).
+- **Tools > Open Saved 3D Volume...** reopens a `.zarr` store from a
+  previous run — no z-stack needs to be loaded for this one, it just opens
+  the viewer against whatever store you point it at.
 
 ## Install
 
 ```
-pip install flimkit-zstack-explorer[gui]
+pip install 'flimkit-zstack-explorer[gui]'
 ```
 
+Quote it — in zsh (macOS's default shell), an unquoted `[gui]` is a glob
+pattern and the command fails with "no matches found" without installing
+anything.
+
 `[gui]` adds PyVista, which does the actual 3D rendering. Without it, the
 volume-building and OME-Zarr saving still work, but the viewer step will
 tell you it's missing and how to install it.
 
+Install it into the same Python environment FLIMKit itself runs from —
+a separate environment or a different `python`/`pip` on your `PATH` will
+install cleanly but leave FLIMKit unable to see it. Verify with:
+
+```bash
+python -c "import flimkit_zstack_explorer, pyvista; print('ok')"
+```
+
+run from the same terminal you launch FLIMKit from.
+
 FLIMKit discovers this through the `flimkit.plugins` entry point, so there's
 nothing else to wire up. On start it appears under Tools.
 

{flimkit_zstack_explorer-0.1.0 → flimkit_zstack_explorer-0.2.0}/README.md

@@ -14,21 +14,46 @@ and opens a popout 3D viewer with the two volumes side by side.
   display code (the same path used when you drag the z-slider), so the
   volume matches what's on screen slice by slice.
 - Saves a 2-channel OME-Zarr store (channel 0 = intensity, channel 1 =
-  lifetime in ns, NaN where a slice had no per-pixel fit).
+  lifetime in ns, NaN where a slice had no per-pixel fit). Saving to a path
+  that already has a store from a previous run overwrites it.
 - Opens a [PyVista](https://pyvista.org) volume viewer in its own process —
   intensity on the left, FLIM lifetime on the right, camera-linked — so it
   doesn't compete with FLIMKit's Tkinter UI for the main thread.
+- Intensity is clipped to its 99th percentile before rendering, the same
+  clip FLIMKit's own 2D intensity view uses, so a few hot pixels don't wash
+  out the whole volume.
+- The FLIM pane has live sliders for the lifetime min/max color range
+  (defaulting to the 2nd/98th percentile, like FLIMKit's "Auto" scale
+  button) and a colormap picker with the same palette as FLIMKit's 2D FLIM
+  view (hsv, viridis, cool, hot, twilight).
+- **Tools > Open Saved 3D Volume...** reopens a `.zarr` store from a
+  previous run — no z-stack needs to be loaded for this one, it just opens
+  the viewer against whatever store you point it at.
 
 ## Install
 
 ```
-pip install flimkit-zstack-explorer[gui]
+pip install 'flimkit-zstack-explorer[gui]'
 ```
 
+Quote it — in zsh (macOS's default shell), an unquoted `[gui]` is a glob
+pattern and the command fails with "no matches found" without installing
+anything.
+
 `[gui]` adds PyVista, which does the actual 3D rendering. Without it, the
 volume-building and OME-Zarr saving still work, but the viewer step will
 tell you it's missing and how to install it.
 
+Install it into the same Python environment FLIMKit itself runs from —
+a separate environment or a different `python`/`pip` on your `PATH` will
+install cleanly but leave FLIMKit unable to see it. Verify with:
+
+```bash
+python -c "import flimkit_zstack_explorer, pyvista; print('ok')"
+```
+
+run from the same terminal you launch FLIMKit from.
+
 FLIMKit discovers this through the `flimkit.plugins` entry point, so there's
 nothing else to wire up. On start it appears under Tools.
 

{flimkit_zstack_explorer-0.1.0 → flimkit_zstack_explorer-0.2.0}/flimkit_zstack_explorer/plugin.py

@@ -47,6 +47,36 @@ def open_3d_explorer(app):
     _run_build_and_view(app, parent, out_path)
 
 
+@tool(id='zstack_3d_open_saved', label='Open Saved 3D Volume...', menu='Tools', order=851)
+def open_saved_volume(app):
+    from tkinter import filedialog, messagebox
+
+    parent = _parent(app)
+
+    if not _deps_ok():
+        messagebox.showerror(
+            'Missing dependency',
+            'Opening a saved 3D volume needs zarr and ome-zarr.\n\n'
+            'Install with:\n\n    pip install flimkit-zstack-explorer',
+            parent=parent)
+        return
+
+    path = filedialog.askdirectory(
+        parent=parent, title='Open a saved 3D volume (OME-Zarr)', mustexist=True)
+    if not path:
+        return
+
+    from ome_zarr.io import parse_url
+    if parse_url(path) is None:
+        messagebox.showerror(
+            'Not an OME-Zarr store',
+            f"{path}\n\ndoesn't look like an OME-Zarr store saved by this tool.",
+            parent=parent)
+        return
+
+    _launch_viewer(path, parent)
+
+
 def _run_build_and_view(app, parent, out_path):
     import threading
     from flimkit.UI.progress_window import ProgressWindow

flimkit_zstack_explorer-0.2.0/flimkit_zstack_explorer/viewer.py

@@ -0,0 +1,152 @@
+"""Standalone popout 3D viewer. Runs in its own process (see plugin.py),
+never imports tkinter/flimkit, so it doesn't fight FLIMKit's Tk mainloop
+for the main thread.
+
+Run directly with: python -m flimkit_zstack_explorer.viewer --zarr <path>
+"""
+from __future__ import annotations
+import argparse
+import sys
+
+import numpy as np
+
+# Same names, same order, as flimkit.utils.display.COLORMAPS, so the FLIM
+# volume offers the same palette as FLIMKit's own 2D lifetime view.
+COLORMAPS = ['hsv', 'viridis', 'cool', 'hot', 'twilight']
+
+
+def _missing_pyvista():
+    sys.stderr.write(
+        'flimkit-zstack-explorer: pyvista is required for the 3D viewer.\n'
+        'Install it with:\n\n'
+        '    pip install "flimkit-zstack-explorer[gui]"\n\n')
+    sys.exit(1)
+
+
+def _set_lifetime_colormap(actor, name):
+    import pyvista as pv
+    lut = pv.LookupTable(cmap=name)
+    lut.apply_opacity('linear')
+    actor.mapper.lookup_table = lut
+
+
+def _masked_grid(values, mask, name, dimensions, spacing):
+    """Build an ImageData for `values` and drop every cell where `mask` is
+    False, via a threshold filter.
+
+    A volume mapper's own opacity/NaN handling doesn't reliably drop
+    individual voxels (tested: NaN cells with nan_opacity=0 still render as
+    solid fill), so masked-out voxels are removed from the geometry outright
+    rather than made transparent.
+    """
+    import pyvista as pv
+    grid = pv.ImageData()
+    grid.dimensions = dimensions
+    grid.spacing = spacing
+    grid.cell_data[name] = np.where(mask, values, 0).flatten(order='F')
+    grid.cell_data['_mask'] = mask.astype(np.float32).flatten(order='F')
+    return grid.threshold(0.5, scalars='_mask')
+
+
+def show(intensity_stack: np.ndarray, lifetime_stack: np.ndarray, *,
+         voxel_size_um=(1.0, 1.0, 1.0), title: str = 'FLIMKit 3D Z-stack Explorer'):
+    try:
+        import pyvista as pv
+    except ImportError:
+        _missing_pyvista()
+        return
+
+    spacing = tuple(float(v) for v in voxel_size_um)[::-1]
+    dimensions = tuple(np.array(intensity_stack.shape)[::-1] + 1)
+
+    # Clipped to the 99th percentile, same as FLIMKit's own 2D intensity
+    # view (flimkit/UI/fov_preview.py), so a handful of hot pixels don't
+    # wash out the whole volume's opacity ramp. Zero-intensity voxels (no
+    # signal) are dropped from the geometry entirely.
+    intensity_clip = np.percentile(intensity_stack, 99) if intensity_stack.size else 1.0
+    intensity_clipped = np.clip(intensity_stack, 0, intensity_clip)
+    intensity_grid = _masked_grid(
+        intensity_clipped, intensity_stack > 0, 'intensity', dimensions, spacing)
+
+    # Voxels with no per-pixel fit (NaN lifetime) are dropped the same way.
+    lifetime_grid = _masked_grid(
+        lifetime_stack, np.isfinite(lifetime_stack), 'lifetime_ns', dimensions, spacing)
+
+    valid_lifetime = lifetime_stack[np.isfinite(lifetime_stack)]
+    if valid_lifetime.size:
+        lt_min, lt_max = float(valid_lifetime.min()), float(valid_lifetime.max())
+        # 2nd/98th percentile default, same as FLIMKit's "Auto" scale button.
+        vmin = float(np.percentile(valid_lifetime, 2))
+        vmax = float(np.percentile(valid_lifetime, 98))
+    else:
+        lt_min, lt_max, vmin, vmax = 0.0, 1.0, 0.0, 1.0
+    if lt_max <= lt_min:
+        lt_max = lt_min + 1.0
+    if vmax <= vmin:
+        vmin, vmax = lt_min, lt_max
+
+    plotter = pv.Plotter(shape=(1, 2), title=title)
+
+    plotter.subplot(0, 0)
+    if intensity_grid.n_cells:
+        plotter.add_volume(intensity_grid, scalars='intensity', cmap='inferno',
+                            opacity='linear', name='intensity')
+    else:
+        plotter.add_text('No intensity signal', font_size=10, color='grey')
+    plotter.add_text('Intensity', font_size=12)
+    plotter.add_axes()
+
+    plotter.subplot(0, 1)
+    if lifetime_grid.n_cells:
+        lifetime_actor = plotter.add_volume(
+            lifetime_grid, scalars='lifetime_ns', cmap='viridis',
+            opacity='linear', name='lifetime', show_scalar_bar=False)
+        lifetime_actor.mapper.scalar_range = (vmin, vmax)
+        plotter.add_scalar_bar('lifetime (ns)', mapper=lifetime_actor.mapper)
+
+        def set_vmin(value):
+            _, hi = lifetime_actor.mapper.scalar_range
+            lo = min(float(value), hi)
+            lifetime_actor.mapper.scalar_range = (lo, hi)
+            plotter.update_scalar_bar_range((lo, hi))
+
+        def set_vmax(value):
+            lo, _ = lifetime_actor.mapper.scalar_range
+            hi = max(float(value), lo)
+            lifetime_actor.mapper.scalar_range = (lo, hi)
+            plotter.update_scalar_bar_range((lo, hi))
+
+        def set_cmap(name):
+            _set_lifetime_colormap(lifetime_actor, name)
+
+        plotter.add_slider_widget(
+            set_vmin, rng=(lt_min, lt_max), value=vmin, title='lifetime min (ns)',
+            pointa=(0.52, 0.92), pointb=(0.98, 0.92), style='modern')
+        plotter.add_slider_widget(
+            set_vmax, rng=(lt_min, lt_max), value=vmax, title='lifetime max (ns)',
+            pointa=(0.52, 0.80), pointb=(0.98, 0.80), style='modern')
+        plotter.add_text_slider_widget(
+            set_cmap, data=COLORMAPS, value=COLORMAPS.index('viridis'),
+            pointa=(0.52, 0.68), pointb=(0.98, 0.68), style='modern')
+    else:
+        plotter.add_text('No per-pixel fit data', font_size=10, color='grey')
+    plotter.add_text('FLIM (lifetime)', font_size=12)
+    plotter.add_axes()
+
+    plotter.link_views()
+    plotter.show()
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--zarr', required=True, help='Path to an OME-Zarr store '
+                         'written by flimkit_zstack_explorer.zarr_io.save_ome_zarr')
+    args = parser.parse_args(argv)
+
+    from flimkit_zstack_explorer.zarr_io import load_ome_zarr
+    intensity, lifetime = load_ome_zarr(args.zarr)
+    show(intensity, lifetime, title=f'FLIMKit 3D Z-stack Explorer - {args.zarr}')
+
+
+if __name__ == '__main__':
+    main()

{flimkit_zstack_explorer-0.1.0 → flimkit_zstack_explorer-0.2.0}/flimkit_zstack_explorer/zarr_io.py

@@ -1,4 +1,6 @@
 from __future__ import annotations
+import os
+import shutil
 from typing import Optional, Sequence
 
 import numpy as np
@@ -32,6 +34,14 @@ def save_ome_zarr(
     from ome_zarr.io import parse_url
     from ome_zarr.writer import write_image
 
+    # ome-zarr's 'w' mode doesn't clear an existing store, so writing to the
+    # same path twice (the save dialog defaults to the same filename every
+    # run) hits leftover array nodes from the previous write.
+    if os.path.isdir(path):
+        shutil.rmtree(path)
+    elif os.path.exists(path):
+        os.remove(path)
+
     data = np.stack([
         np.nan_to_num(intensity_stack, nan=0.0).astype(np.float32),
         lifetime_stack.astype(np.float32),

{flimkit_zstack_explorer-0.1.0 → flimkit_zstack_explorer-0.2.0}/flimkit_zstack_explorer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flimkit-zstack-explorer
-Version: 0.1.0
+Version: 0.2.0
 Summary: 3D intensity and FLIM volume explorer for FLIMKit z-stacks
 Author-email: Alex Hunt <alexander.hunt@ed.ac.uk>
 License-Expression: MIT
@@ -33,21 +33,46 @@ and opens a popout 3D viewer with the two volumes side by side.
   display code (the same path used when you drag the z-slider), so the
   volume matches what's on screen slice by slice.
 - Saves a 2-channel OME-Zarr store (channel 0 = intensity, channel 1 =
-  lifetime in ns, NaN where a slice had no per-pixel fit).
+  lifetime in ns, NaN where a slice had no per-pixel fit). Saving to a path
+  that already has a store from a previous run overwrites it.
 - Opens a [PyVista](https://pyvista.org) volume viewer in its own process —
   intensity on the left, FLIM lifetime on the right, camera-linked — so it
   doesn't compete with FLIMKit's Tkinter UI for the main thread.
+- Intensity is clipped to its 99th percentile before rendering, the same
+  clip FLIMKit's own 2D intensity view uses, so a few hot pixels don't wash
+  out the whole volume.
+- The FLIM pane has live sliders for the lifetime min/max color range
+  (defaulting to the 2nd/98th percentile, like FLIMKit's "Auto" scale
+  button) and a colormap picker with the same palette as FLIMKit's 2D FLIM
+  view (hsv, viridis, cool, hot, twilight).
+- **Tools > Open Saved 3D Volume...** reopens a `.zarr` store from a
+  previous run — no z-stack needs to be loaded for this one, it just opens
+  the viewer against whatever store you point it at.
 
 ## Install
 
 ```
-pip install flimkit-zstack-explorer[gui]
+pip install 'flimkit-zstack-explorer[gui]'
 ```
 
+Quote it — in zsh (macOS's default shell), an unquoted `[gui]` is a glob
+pattern and the command fails with "no matches found" without installing
+anything.
+
 `[gui]` adds PyVista, which does the actual 3D rendering. Without it, the
 volume-building and OME-Zarr saving still work, but the viewer step will
 tell you it's missing and how to install it.
 
+Install it into the same Python environment FLIMKit itself runs from —
+a separate environment or a different `python`/`pip` on your `PATH` will
+install cleanly but leave FLIMKit unable to see it. Verify with:
+
+```bash
+python -c "import flimkit_zstack_explorer, pyvista; print('ok')"
+```
+
+run from the same terminal you launch FLIMKit from.
+
 FLIMKit discovers this through the `flimkit.plugins` entry point, so there's
 nothing else to wire up. On start it appears under Tools.
 

{flimkit_zstack_explorer-0.1.0 → flimkit_zstack_explorer-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'setuptools.build_meta'
 
 [project]
 name = 'flimkit-zstack-explorer'
-version = '0.1.0'
+version = '0.2.0'
 description = '3D intensity and FLIM volume explorer for FLIMKit z-stacks'
 readme = 'README.md'
 requires-python = '>=3.12'

flimkit_zstack_explorer-0.2.0/tests/test_plugin_guard.py

@@ -0,0 +1,101 @@
+"""Verifies the Tools menu entry is a *guarded* action (per the approved
+design: always visible, but refuses to run without a loaded z-stack)
+rather than actually disabled/hidden."""
+import pytest
+
+flimkit = pytest.importorskip('flimkit', reason='requires a FLIMKit install')
+
+from flimkit_zstack_explorer.plugin import open_3d_explorer, open_saved_volume
+
+
+class NoZStackApp:
+    root = None
+    _fov_preview = None
+
+
+class EmptyZStackApp:
+    root = None
+
+    class _fov_preview:
+        _zstack = []
+
+
+def test_guard_shows_message_when_no_zstack(monkeypatch):
+    calls = []
+    monkeypatch.setattr('tkinter.messagebox.showinfo',
+                         lambda *a, **k: calls.append((a, k)))
+
+    open_3d_explorer(NoZStackApp())
+
+    assert len(calls) == 1
+    assert 'z-stack' in calls[0][0][0].lower() or 'z-stack' in calls[0][0][1].lower()
+
+
+def test_guard_shows_message_when_zstack_empty(monkeypatch):
+    calls = []
+    monkeypatch.setattr('tkinter.messagebox.showinfo',
+                         lambda *a, **k: calls.append((a, k)))
+
+    open_3d_explorer(EmptyZStackApp())
+
+    assert len(calls) == 1
+
+
+def test_does_not_prompt_for_save_path_without_zstack(monkeypatch):
+    monkeypatch.setattr('tkinter.messagebox.showinfo', lambda *a, **k: None)
+
+    def fail_if_called(*a, **k):
+        raise AssertionError('should not prompt for a save path without a z-stack')
+
+    monkeypatch.setattr('tkinter.filedialog.asksaveasfilename', fail_if_called)
+
+    open_3d_explorer(NoZStackApp())
+
+
+def test_open_saved_volume_rejects_non_zarr_dir(tmp_path, monkeypatch):
+    plain_dir = tmp_path / 'not_a_store'
+    plain_dir.mkdir()
+    monkeypatch.setattr('tkinter.filedialog.askdirectory', lambda **k: str(plain_dir))
+
+    errors = []
+    monkeypatch.setattr('tkinter.messagebox.showerror',
+                         lambda *a, **k: errors.append((a, k)))
+
+    launched = []
+    monkeypatch.setattr('subprocess.Popen', lambda *a, **k: launched.append((a, k)))
+
+    open_saved_volume(NoZStackApp())
+
+    assert len(errors) == 1
+    assert not launched
+
+
+def test_open_saved_volume_launches_viewer_for_a_real_store(tmp_path, monkeypatch):
+    from flimkit_zstack_explorer.zarr_io import save_ome_zarr
+    import numpy as np
+
+    store = tmp_path / 'volume.zarr'
+    save_ome_zarr(str(store), np.zeros((2, 4, 4), dtype=np.float32),
+                  np.zeros((2, 4, 4), dtype=np.float32))
+
+    monkeypatch.setattr('tkinter.filedialog.askdirectory', lambda **k: str(store))
+
+    launched = []
+    monkeypatch.setattr('subprocess.Popen', lambda args, **k: launched.append(args))
+
+    open_saved_volume(NoZStackApp())
+
+    assert len(launched) == 1
+    assert '--zarr' in launched[0]
+    assert str(store) in launched[0]
+
+
+def test_open_saved_volume_no_op_when_dialog_cancelled(monkeypatch):
+    monkeypatch.setattr('tkinter.filedialog.askdirectory', lambda **k: '')
+
+    launched = []
+    monkeypatch.setattr('subprocess.Popen', lambda *a, **k: launched.append((a, k)))
+
+    open_saved_volume(NoZStackApp())
+
+    assert not launched

flimkit_zstack_explorer-0.2.0/tests/test_viewer.py

@@ -0,0 +1,133 @@
+import numpy as np
+import pytest
+
+pytest.importorskip('pyvista', reason='requires the [gui] extra')
+
+import pyvista as pv
+
+from flimkit_zstack_explorer.viewer import (
+    COLORMAPS, _masked_grid, _set_lifetime_colormap, show,
+)
+
+
+def test_masked_grid_drops_exact_cell_count():
+    shape = (10, 20, 24)
+    dims = tuple(np.array(shape)[::-1] + 1)
+    rng = np.random.default_rng(0)
+
+    intensity = rng.poisson(50, size=shape).astype(np.float32)
+    zero_idx = rng.choice(intensity.size, 500, replace=False)
+    intensity.flat[zero_idx] = 0
+    grid = _masked_grid(intensity, intensity > 0, 'intensity', dims, (1.0, 1.0, 1.0))
+    assert grid.n_cells == intensity.size - 500
+
+    lifetime = rng.uniform(1.5, 3.5, size=shape).astype(np.float32)
+    lifetime[3] = np.nan  # a whole slice with no per-pixel fit
+    grid = _masked_grid(lifetime, np.isfinite(lifetime), 'lifetime_ns', dims, (1.0, 1.0, 1.0))
+    assert grid.n_cells == lifetime.size - shape[1] * shape[2]
+
+
+def test_masked_grid_all_dropped_yields_empty_grid():
+    shape = (2, 4, 4)
+    dims = tuple(np.array(shape)[::-1] + 1)
+    values = np.zeros(shape, dtype=np.float32)
+    grid = _masked_grid(values, values > 0, 'intensity', dims, (1.0, 1.0, 1.0))
+    assert grid.n_cells == 0
+
+
+def test_show_handles_all_zero_intensity_and_all_nan_lifetime(monkeypatch):
+    # Must not crash even when every voxel is masked out in one or both
+    # volumes (add_volume errors on an empty grid, so show() has to skip it).
+    pv.OFF_SCREEN = True
+    monkeypatch.setattr(pv.Plotter, 'show', lambda self, *a, **k: None)
+
+    intensity = np.zeros((3, 8, 8), dtype=np.float32)
+    lifetime = np.full((3, 8, 8), np.nan, dtype=np.float32)
+
+    show(intensity, lifetime)
+
+
+def _spy_on_add_volume(monkeypatch):
+    calls = []
+    original = pv.Plotter.add_volume
+
+    def spy(self, grid, **kwargs):
+        actor = original(self, grid, **kwargs)
+        calls.append((grid, kwargs, actor))
+        return actor
+
+    monkeypatch.setattr(pv.Plotter, 'add_volume', spy)
+    return calls
+
+
+def test_show_builds_offscreen_without_error(monkeypatch):
+    pv.OFF_SCREEN = True
+    monkeypatch.setattr(pv.Plotter, 'show', lambda self, *a, **k: None)
+
+    rng = np.random.default_rng(0)
+    intensity = rng.poisson(50, size=(4, 12, 16)).astype(np.float32)
+    lifetime = rng.uniform(1.5, 3.5, size=(4, 12, 16)).astype(np.float32)
+    lifetime[0] = np.nan
+
+    show(intensity, lifetime, voxel_size_um=(2.0, 0.5, 0.5))
+
+
+def test_intensity_is_clipped_to_99th_percentile(monkeypatch):
+    pv.OFF_SCREEN = True
+    monkeypatch.setattr(pv.Plotter, 'show', lambda self, *a, **k: None)
+    calls = _spy_on_add_volume(monkeypatch)
+
+    rng = np.random.default_rng(1)
+    intensity = rng.poisson(50, size=(3, 20, 20)).astype(np.float32)
+    expected_clip = float(np.percentile(intensity, 99))
+    intensity[0, 0, 0] = 1_000_000.0  # a hot pixel outlier
+    lifetime = np.full((3, 20, 20), 2.0, dtype=np.float32)
+
+    show(intensity, lifetime)
+
+    intensity_grid = calls[0][0]
+    assert intensity_grid.cell_data['intensity'].max() <= expected_clip + 1e-3
+    assert intensity_grid.cell_data['intensity'].min() >= 0
+
+
+def test_lifetime_scalar_range_defaults_to_2nd_98th_percentile(monkeypatch):
+    pv.OFF_SCREEN = True
+    monkeypatch.setattr(pv.Plotter, 'show', lambda self, *a, **k: None)
+    calls = _spy_on_add_volume(monkeypatch)
+
+    rng = np.random.default_rng(2)
+    intensity = np.full((3, 16, 16), 10.0, dtype=np.float32)
+    lifetime = rng.uniform(1.0, 4.0, size=(3, 16, 16)).astype(np.float32)
+    expected_vmin = float(np.percentile(lifetime, 2))
+    expected_vmax = float(np.percentile(lifetime, 98))
+
+    show(intensity, lifetime)
+
+    lifetime_actor = calls[1][2]
+    lo, hi = lifetime_actor.mapper.scalar_range
+    assert lo == pytest.approx(expected_vmin, abs=1e-3)
+    assert hi == pytest.approx(expected_vmax, abs=1e-3)
+
+
+def test_set_lifetime_colormap_swaps_colors_and_keeps_opacity_ramp():
+    grid = pv.ImageData()
+    grid.dimensions = (5, 5, 5)
+    grid.spacing = (1, 1, 1)
+    grid.cell_data['lifetime_ns'] = np.linspace(0, 1, 64).astype(np.float32)
+
+    plotter = pv.Plotter(off_screen=True)
+    actor = plotter.add_volume(grid, scalars='lifetime_ns', cmap='viridis',
+                                opacity='linear')
+    original_colors = actor.mapper.lookup_table.values.copy()
+
+    for name in COLORMAPS:
+        _set_lifetime_colormap(actor, name)
+        assert actor.mapper.lookup_table is not None
+        # Opacity ramps from transparent to opaque across the table, same
+        # shape 'linear' produces for every colormap.
+        alpha = actor.mapper.lookup_table.values[:, -1]
+        assert alpha[0] < alpha[-1]
+
+    _set_lifetime_colormap(actor, 'hot')
+    assert not np.array_equal(actor.mapper.lookup_table.values, original_colors)
+    plotter.close()

{flimkit_zstack_explorer-0.1.0 → flimkit_zstack_explorer-0.2.0}/tests/test_zarr_io.py

@@ -24,6 +24,22 @@ def test_roundtrip(tmp_path):
     assert np.allclose(l2[1:], lifetime[1:])
 
 
+def test_saving_to_same_path_twice_overwrites(tmp_path):
+    # The save dialog defaults to the same filename every run, so re-running
+    # the tool against a path that already has a store must overwrite it
+    # rather than hitting ome-zarr's ContainsArrayError on leftover nodes.
+    intensity = np.full((3, 8, 8), 10.0, dtype=np.float32)
+    lifetime = np.full((3, 8, 8), 2.0, dtype=np.float32)
+    path = str(tmp_path / 'zstack_volume.zarr')
+
+    save_ome_zarr(path, intensity, lifetime)
+    save_ome_zarr(path, intensity * 2, lifetime + 1)
+
+    i2, l2 = load_ome_zarr(path)
+    assert np.allclose(i2, 20.0)
+    assert np.allclose(l2, 3.0)
+
+
 def test_shape_mismatch_raises(tmp_path):
     intensity = np.zeros((3, 4, 4), dtype=np.float32)
     lifetime = np.zeros((3, 5, 5), dtype=np.float32)

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer/viewer.py

@@ -1,79 +0,0 @@
-"""Standalone popout 3D viewer. Runs in its own process (see plugin.py),
-never imports tkinter/flimkit, so it doesn't fight FLIMKit's Tk mainloop
-for the main thread.
-
-Run directly with: python -m flimkit_zstack_explorer.viewer --zarr <path>
-"""
-from __future__ import annotations
-import argparse
-import sys
-
-import numpy as np
-
-
-def _missing_pyvista():
-    sys.stderr.write(
-        'flimkit-zstack-explorer: pyvista is required for the 3D viewer.\n'
-        'Install it with:\n\n'
-        '    pip install "flimkit-zstack-explorer[gui]"\n\n')
-    sys.exit(1)
-
-
-def show(intensity_stack: np.ndarray, lifetime_stack: np.ndarray, *,
-         voxel_size_um=(1.0, 1.0, 1.0), title: str = 'FLIMKit 3D Z-stack Explorer'):
-    try:
-        import pyvista as pv
-    except ImportError:
-        _missing_pyvista()
-        return
-
-    spacing = tuple(float(v) for v in voxel_size_um)
-
-    intensity_grid = pv.ImageData()
-    intensity_grid.dimensions = np.array(intensity_stack.shape)[::-1] + 1
-    intensity_grid.spacing = spacing[::-1]
-    intensity_grid.cell_data['intensity'] = intensity_stack.flatten(order='F')
-
-    # Background (no-fit / no-signal) voxels are pinned to 0, which is below
-    # any real lifetime in the data, so the 'linear' opacity transfer
-    # function used below fades them out automatically without needing a
-    # second per-voxel opacity field (PyVista's add_volume only accepts an
-    # opacity transfer function keyed by the volume's own scalar range).
-    lifetime_grid = pv.ImageData()
-    lifetime_grid.dimensions = np.array(lifetime_stack.shape)[::-1] + 1
-    lifetime_grid.spacing = spacing[::-1]
-    finite_lifetime = np.where(np.isfinite(lifetime_stack), lifetime_stack, 0.0)
-    lifetime_grid.cell_data['lifetime_ns'] = finite_lifetime.flatten(order='F')
-
-    plotter = pv.Plotter(shape=(1, 2), title=title)
-
-    plotter.subplot(0, 0)
-    plotter.add_volume(intensity_grid, scalars='intensity', cmap='inferno',
-                        opacity='linear', name='intensity')
-    plotter.add_text('Intensity', font_size=12)
-    plotter.add_axes()
-
-    plotter.subplot(0, 1)
-    plotter.add_volume(lifetime_grid, scalars='lifetime_ns', cmap='turbo',
-                        opacity='linear', name='lifetime')
-    plotter.add_scalar_bar('lifetime (ns)')
-    plotter.add_text('FLIM (lifetime)', font_size=12)
-    plotter.add_axes()
-
-    plotter.link_views()
-    plotter.show()
-
-
-def main(argv=None):
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('--zarr', required=True, help='Path to an OME-Zarr store '
-                         'written by flimkit_zstack_explorer.zarr_io.save_ome_zarr')
-    args = parser.parse_args(argv)
-
-    from flimkit_zstack_explorer.zarr_io import load_ome_zarr
-    intensity, lifetime = load_ome_zarr(args.zarr)
-    show(intensity, lifetime, title=f'FLIMKit 3D Z-stack Explorer - {args.zarr}')
-
-
-if __name__ == '__main__':
-    main()

flimkit_zstack_explorer-0.1.0/tests/test_plugin_guard.py

@@ -1,52 +0,0 @@
-"""Verifies the Tools menu entry is a *guarded* action (per the approved
-design: always visible, but refuses to run without a loaded z-stack)
-rather than actually disabled/hidden."""
-import pytest
-
-flimkit = pytest.importorskip('flimkit', reason='requires a FLIMKit install')
-
-from flimkit_zstack_explorer.plugin import open_3d_explorer
-
-
-class NoZStackApp:
-    root = None
-    _fov_preview = None
-
-
-class EmptyZStackApp:
-    root = None
-
-    class _fov_preview:
-        _zstack = []
-
-
-def test_guard_shows_message_when_no_zstack(monkeypatch):
-    calls = []
-    monkeypatch.setattr('tkinter.messagebox.showinfo',
-                         lambda *a, **k: calls.append((a, k)))
-
-    open_3d_explorer(NoZStackApp())
-
-    assert len(calls) == 1
-    assert 'z-stack' in calls[0][0][0].lower() or 'z-stack' in calls[0][0][1].lower()
-
-
-def test_guard_shows_message_when_zstack_empty(monkeypatch):
-    calls = []
-    monkeypatch.setattr('tkinter.messagebox.showinfo',
-                         lambda *a, **k: calls.append((a, k)))
-
-    open_3d_explorer(EmptyZStackApp())
-
-    assert len(calls) == 1
-
-
-def test_does_not_prompt_for_save_path_without_zstack(monkeypatch):
-    monkeypatch.setattr('tkinter.messagebox.showinfo', lambda *a, **k: None)
-
-    def fail_if_called(*a, **k):
-        raise AssertionError('should not prompt for a save path without a z-stack')
-
-    monkeypatch.setattr('tkinter.filedialog.asksaveasfilename', fail_if_called)
-
-    open_3d_explorer(NoZStackApp())

flimkit_zstack_explorer-0.1.0/tests/test_viewer.py

@@ -1,20 +0,0 @@
-import numpy as np
-import pytest
-
-pytest.importorskip('pyvista', reason='requires the [gui] extra')
-
-import pyvista as pv
-
-from flimkit_zstack_explorer.viewer import show
-
-
-def test_show_builds_offscreen_without_error(monkeypatch):
-    pv.OFF_SCREEN = True
-    monkeypatch.setattr(pv.Plotter, 'show', lambda self, *a, **k: None)
-
-    rng = np.random.default_rng(0)
-    intensity = rng.poisson(50, size=(4, 12, 16)).astype(np.float32)
-    lifetime = rng.uniform(1.5, 3.5, size=(4, 12, 16)).astype(np.float32)
-    lifetime[0] = np.nan
-
-    show(intensity, lifetime, voxel_size_um=(2.0, 0.5, 0.5))