flimkit-zstack-explorer 0.1.0__tar.gz

flimkit_zstack_explorer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FLIMKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flimkit_zstack_explorer-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: flimkit-zstack-explorer
+Version: 0.1.0
+Summary: 3D intensity and FLIM volume explorer for FLIMKit z-stacks
+Author-email: Alex Hunt <alexander.hunt@ed.ac.uk>
+License-Expression: MIT
+Keywords: FLIM,fluorescence,lifetime,z-stack,3D,zarr,pyvista
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: zarr>=2.16
+Requires-Dist: ome-zarr>=0.9
+Provides-Extra: gui
+Requires-Dist: pyvista>=0.44; extra == "gui"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# flimkit-zstack-explorer
+
+3D intensity and FLIM volume explorer for FLIMKit z-stacks. Takes a z-stack
+you've already loaded or fitted in FLIMKit, stacks its per-slice intensity
+and lifetime maps into `(Z, Y, X)` volumes, saves them as an OME-Zarr store,
+and opens a popout 3D viewer with the two volumes side by side.
+
+## What it does
+
+- Adds **Tools > 3D Z-stack Explorer...** to FLIMKit.
+- Only does anything once a z-stack is loaded (FOV mode > Z-stack); otherwise
+  it tells you to load one first.
+- Walks every slice in the loaded z-stack through the FOV preview panel's own
+  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).
+- 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.
+
+## Install
+
+```
+pip install flimkit-zstack-explorer[gui]
+```
+
+`[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.
+
+FLIMKit discovers this through the `flimkit.plugins` entry point, so there's
+nothing else to wire up. On start it appears under Tools.
+
+## From code
+
+```python
+from flimkit_zstack_explorer import build_zstack_volumes, save_ome_zarr, load_ome_zarr
+
+# app is FLIMKit's running App instance, with a z-stack loaded in its
+# FOV preview panel
+intensity_stack, lifetime_stack = build_zstack_volumes(app)
+save_ome_zarr('volume.zarr', intensity_stack, lifetime_stack,
+              voxel_size_um=(2.0, 0.5, 0.5))
+
+intensity_stack, lifetime_stack = load_ome_zarr('volume.zarr')
+```
+
+To view a store outside FLIMKit:
+
+```
+python -m flimkit_zstack_explorer.viewer --zarr volume.zarr
+```
+
+## Why a separate process for the viewer
+
+FLIMKit's UI is Tkinter; PyVista's is VTK. Running VTK's render loop on a
+background thread inside a Tkinter process is unreliable, especially on
+macOS, where GUI toolkits generally expect to own the main thread. Building
+the volume and saving to disk happens inside FLIMKit; the popout viewer is a
+plain `python -m flimkit_zstack_explorer.viewer` subprocess reading the
+saved store, so it gets its own main thread and doesn't touch Tkinter at
+all.
+
+## Development
+
+```
+pip install -e .[gui,test]
+pytest
+```
+
+`tests/test_volumes.py` exercises the z-stack-to-array logic against a fake
+FOV preview panel, so it runs without Tkinter or a real FLIMKit install.
+`tests/test_zarr_io.py` round-trips real arrays through zarr/ome-zarr.

flimkit_zstack_explorer-0.1.0/README.md

@@ -0,0 +1,74 @@
+# flimkit-zstack-explorer
+
+3D intensity and FLIM volume explorer for FLIMKit z-stacks. Takes a z-stack
+you've already loaded or fitted in FLIMKit, stacks its per-slice intensity
+and lifetime maps into `(Z, Y, X)` volumes, saves them as an OME-Zarr store,
+and opens a popout 3D viewer with the two volumes side by side.
+
+## What it does
+
+- Adds **Tools > 3D Z-stack Explorer...** to FLIMKit.
+- Only does anything once a z-stack is loaded (FOV mode > Z-stack); otherwise
+  it tells you to load one first.
+- Walks every slice in the loaded z-stack through the FOV preview panel's own
+  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).
+- 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.
+
+## Install
+
+```
+pip install flimkit-zstack-explorer[gui]
+```
+
+`[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.
+
+FLIMKit discovers this through the `flimkit.plugins` entry point, so there's
+nothing else to wire up. On start it appears under Tools.
+
+## From code
+
+```python
+from flimkit_zstack_explorer import build_zstack_volumes, save_ome_zarr, load_ome_zarr
+
+# app is FLIMKit's running App instance, with a z-stack loaded in its
+# FOV preview panel
+intensity_stack, lifetime_stack = build_zstack_volumes(app)
+save_ome_zarr('volume.zarr', intensity_stack, lifetime_stack,
+              voxel_size_um=(2.0, 0.5, 0.5))
+
+intensity_stack, lifetime_stack = load_ome_zarr('volume.zarr')
+```
+
+To view a store outside FLIMKit:
+
+```
+python -m flimkit_zstack_explorer.viewer --zarr volume.zarr
+```
+
+## Why a separate process for the viewer
+
+FLIMKit's UI is Tkinter; PyVista's is VTK. Running VTK's render loop on a
+background thread inside a Tkinter process is unreliable, especially on
+macOS, where GUI toolkits generally expect to own the main thread. Building
+the volume and saving to disk happens inside FLIMKit; the popout viewer is a
+plain `python -m flimkit_zstack_explorer.viewer` subprocess reading the
+saved store, so it gets its own main thread and doesn't touch Tkinter at
+all.
+
+## Development
+
+```
+pip install -e .[gui,test]
+pytest
+```
+
+`tests/test_volumes.py` exercises the z-stack-to-array logic against a fake
+FOV preview panel, so it runs without Tkinter or a real FLIMKit install.
+`tests/test_zarr_io.py` round-trips real arrays through zarr/ome-zarr.

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer/__init__.py

@@ -0,0 +1,19 @@
+FLIMKIT_PLUGIN_API = 1
+
+from flimkit_zstack_explorer.volumes import build_zstack_volumes
+from flimkit_zstack_explorer.zarr_io import save_ome_zarr, load_ome_zarr
+
+registered = False
+register_error = None
+try:
+    from flimkit_zstack_explorer import plugin as _plugin
+    registered = True
+except ImportError as exc:
+    register_error = exc
+
+__all__ = [
+    'FLIMKIT_PLUGIN_API',
+    'build_zstack_volumes',
+    'save_ome_zarr',
+    'load_ome_zarr',
+]

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer/plugin.py

@@ -0,0 +1,101 @@
+from flimkit.plugins import tool
+
+
+def _parent(app):
+    return getattr(app, 'root', None) or app
+
+
+def _deps_ok():
+    try:
+        import zarr  # noqa: F401
+        import ome_zarr  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+@tool(id='zstack_3d_explorer', label='3D Z-stack Explorer...', menu='Tools', order=850)
+def open_3d_explorer(app):
+    from tkinter import filedialog, messagebox
+
+    parent = _parent(app)
+    panel = getattr(app, '_fov_preview', None)
+    if not getattr(panel, '_zstack', None):
+        messagebox.showinfo(
+            'No z-stack loaded',
+            'This tool builds a 3D volume from a loaded z-stack.\n\n'
+            'Load or fit a z-stack first (FOV mode > Z-stack), then run '
+            'this tool again.',
+            parent=parent)
+        return
+
+    if not _deps_ok():
+        messagebox.showerror(
+            'Missing dependency',
+            'The 3D Z-stack Explorer needs zarr and ome-zarr.\n\n'
+            'Install with:\n\n    pip install flimkit-zstack-explorer',
+            parent=parent)
+        return
+
+    out_path = filedialog.asksaveasfilename(
+        parent=parent, title='Save 3D volume as OME-Zarr',
+        defaultextension='.zarr', initialfile='zstack_volume.zarr',
+        filetypes=[('OME-Zarr store', '*.zarr'), ('All files', '*')])
+    if not out_path:
+        return
+
+    _run_build_and_view(app, parent, out_path)
+
+
+def _run_build_and_view(app, parent, out_path):
+    import threading
+    from flimkit.UI.progress_window import ProgressWindow
+
+    n_slices = len(app._fov_preview._zstack)
+    win = ProgressWindow(parent, task_name='Building 3D volume')
+    win.set_progress(0, maximum=n_slices)
+
+    def on_progress(i, n):
+        app.root.after(0, lambda: win.set_progress(i, maximum=n))
+
+    def worker():
+        from flimkit_zstack_explorer.volumes import build_zstack_volumes
+        from flimkit_zstack_explorer.zarr_io import save_ome_zarr
+
+        try:
+            intensity, lifetime = build_zstack_volumes(app, progress=on_progress)
+            app.root.after(0, lambda: win.set_status('Saving OME-Zarr...'))
+            save_ome_zarr(out_path, intensity, lifetime)
+        except Exception as exc:
+            app.root.after(0, win.close)
+            app.root.after(0, lambda exc=exc: _show_error(parent, exc))
+            return
+        app.root.after(0, win.close)
+        app.root.after(0, lambda: _launch_viewer(out_path, parent))
+
+    threading.Thread(target=worker, daemon=True).start()
+
+
+def _show_error(parent, exc):
+    from tkinter import messagebox
+    messagebox.showerror('3D Z-stack Explorer failed',
+                          f'{type(exc).__name__}: {exc}', parent=parent)
+
+
+def _launch_viewer(zarr_path, parent):
+    import subprocess
+    import sys
+    from tkinter import messagebox
+
+    try:
+        subprocess.Popen([
+            sys.executable, '-m', 'flimkit_zstack_explorer.viewer',
+            '--zarr', str(zarr_path),
+        ])
+    except Exception as exc:
+        messagebox.showerror(
+            '3D Z-stack Explorer',
+            f'Volume saved to {zarr_path}, but the viewer failed to start:\n'
+            f'{type(exc).__name__}: {exc}\n\n'
+            'Install the viewer with: pip install "flimkit-zstack-explorer[gui]"',
+            parent=parent)

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer/viewer.py

@@ -0,0 +1,79 @@
+"""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/flimkit_zstack_explorer/volumes.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+import threading
+from typing import Callable, Optional, Tuple
+
+import numpy as np
+
+
+def _run_on_ui_thread(app, callback: Callable):
+    """Run `callback` on the Tkinter main thread and block for its result.
+
+    FLIMKit's own FOV preview panel is Tkinter/matplotlib state and is not
+    thread-safe, so anything that touches it (loading a slice, reading back
+    the rendered maps) has to happen on the main thread even when this
+    function is called from a worker thread.
+    """
+    if threading.current_thread() is threading.main_thread():
+        return callback()
+    root = getattr(app, 'root', None)
+    if root is None or not callable(getattr(root, 'after', None)):
+        raise RuntimeError('FLIMKit UI is not available')
+    done = threading.Event()
+    outcome = {}
+
+    def run():
+        try:
+            outcome['value'] = callback()
+        except BaseException as error:
+            outcome['error'] = error
+        finally:
+            done.set()
+
+    root.after(0, run)
+    done.wait()
+    if 'error' in outcome:
+        raise outcome['error']
+    return outcome.get('value')
+
+
+def build_zstack_volumes(
+    app,
+    progress: Optional[Callable[[int, int], None]] = None,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Build (intensity_stack, lifetime_stack) arrays, each shape (Z, Y, X),
+    from the z-stack currently loaded in FLIMKit's FOV preview panel.
+
+    Each z-slice is displayed through the panel's own `display_fit_results` /
+    `load_fov` (the same code path the app uses when you drag the z-slider)
+    so the maps match what you'd see on screen, rather than re-deriving the
+    intensity/lifetime math here. The panel is left showing whatever slice it
+    was on before this ran. Raises RuntimeError if no z-stack is loaded, or
+    if slices don't all share one shape.
+
+    Safe to call from any thread.
+    """
+    def get_zstack():
+        panel = getattr(app, '_fov_preview', None)
+        zstack = getattr(panel, '_zstack', None) if panel is not None else None
+        return panel, (list(zstack) if zstack else None)
+
+    panel, zstack = _run_on_ui_thread(app, get_zstack)
+    if not zstack:
+        raise RuntimeError('No z-stack is loaded in FLIMKit')
+
+    def show_slice(desc):
+        fit_result = desc.get('fit_result')
+        if fit_result is not None:
+            panel.display_fit_results(desc.get('ptu_path'), fit_result, _keep_zstack=True)
+        else:
+            panel.load_fov(desc.get('ptu_path'), _keep_zstack=True)
+        intensity = getattr(panel, '_intensity_map', None)
+        lifetime = getattr(panel, '_lifetime_map', None)
+        intensity = (np.array(intensity, dtype=np.float32, copy=True)
+                     if intensity is not None else None)
+        lifetime = (np.array(lifetime, dtype=np.float32, copy=True)
+                    if lifetime is not None else None)
+        return intensity, lifetime
+
+    original_i = _run_on_ui_thread(app, lambda: getattr(panel, '_z_i', 0))
+    intensity_slices = []
+    lifetime_slices = []
+    try:
+        for i, desc in enumerate(zstack):
+            intensity, lifetime = _run_on_ui_thread(app, lambda desc=desc: show_slice(desc))
+            if intensity is None:
+                raise RuntimeError(f'z-slice {i} ({desc.get("z", i)}) has no intensity image')
+            intensity_slices.append(intensity)
+            lifetime_slices.append(
+                lifetime if lifetime is not None
+                else np.full(intensity.shape[:2], np.nan, dtype=np.float32))
+            if progress is not None:
+                progress(i + 1, len(zstack))
+    finally:
+        def restore():
+            panel._z_i = original_i
+            panel._show_zstack_slice(original_i)
+            sync = getattr(panel, '_sync_z_slider', None)
+            if callable(sync):
+                sync()
+        _run_on_ui_thread(app, restore)
+
+    shape = intensity_slices[0].shape
+    for name, slices in (('intensity', intensity_slices), ('lifetime', lifetime_slices)):
+        for i, arr in enumerate(slices):
+            if arr.shape != shape:
+                raise RuntimeError(
+                    f'{name} slice {i} has shape {arr.shape}, expected {shape} '
+                    '(all z-slices must be the same size)')
+
+    return np.stack(intensity_slices), np.stack(lifetime_slices)

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer/zarr_io.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from typing import Optional, Sequence
+
+import numpy as np
+
+CHANNELS = ('intensity', 'lifetime_ns')
+
+
+def save_ome_zarr(
+    path: str,
+    intensity_stack: np.ndarray,
+    lifetime_stack: np.ndarray,
+    *,
+    voxel_size_um: Optional[Sequence[float]] = None,
+) -> str:
+    """Write intensity + lifetime volumes as a 2-channel OME-Zarr store.
+
+    `intensity_stack` and `lifetime_stack` must both be (Z, Y, X) and share
+    a shape. Channel 0 is intensity, channel 1 is lifetime in ns (NaN where
+    a slice had no fit). `voxel_size_um`, if given, is (z, y, x) physical
+    spacing used for the store's scale metadata; otherwise voxels are unit
+    spacing. Returns `path`.
+    """
+    if intensity_stack.shape != lifetime_stack.shape:
+        raise ValueError(
+            f'intensity {intensity_stack.shape} and lifetime {lifetime_stack.shape} '
+            'stacks must have the same shape')
+    if intensity_stack.ndim != 3:
+        raise ValueError(f'expected (Z, Y, X) stacks, got shape {intensity_stack.shape}')
+
+    import zarr
+    from ome_zarr.io import parse_url
+    from ome_zarr.writer import write_image
+
+    data = np.stack([
+        np.nan_to_num(intensity_stack, nan=0.0).astype(np.float32),
+        lifetime_stack.astype(np.float32),
+    ])
+
+    store = parse_url(str(path), mode='w').store
+    root = zarr.group(store=store)
+
+    nz, ny, nx = intensity_stack.shape
+    chunks = (1, 1, min(256, ny), min(256, nx))
+    write_image(image=data, group=root, axes='czyx', scaler=None,
+                storage_options=dict(chunks=chunks))
+
+    scale = [1.0] + [float(v) for v in (voxel_size_um or (1.0, 1.0, 1.0))]
+    root.attrs['flimkit_zstack_explorer'] = {
+        'channels': list(CHANNELS),
+        'voxel_size_um': scale[1:],
+    }
+    return str(path)
+
+
+def load_ome_zarr(path: str):
+    """Read back a store written by `save_ome_zarr`.
+
+    Returns (intensity_stack, lifetime_stack), each (Z, Y, X) numpy arrays.
+    """
+    import zarr
+    from ome_zarr.io import parse_url
+    from ome_zarr.reader import Reader
+
+    reader = Reader(parse_url(str(path)))
+    node = next(iter(reader()))
+    data = np.asarray(node.data[0])
+    if data.shape[0] != 2:
+        raise ValueError(f'expected a 2-channel store (intensity, lifetime), got shape {data.shape}')
+    return data[0], data[1]

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer.egg-info/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: flimkit-zstack-explorer
+Version: 0.1.0
+Summary: 3D intensity and FLIM volume explorer for FLIMKit z-stacks
+Author-email: Alex Hunt <alexander.hunt@ed.ac.uk>
+License-Expression: MIT
+Keywords: FLIM,fluorescence,lifetime,z-stack,3D,zarr,pyvista
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: zarr>=2.16
+Requires-Dist: ome-zarr>=0.9
+Provides-Extra: gui
+Requires-Dist: pyvista>=0.44; extra == "gui"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# flimkit-zstack-explorer
+
+3D intensity and FLIM volume explorer for FLIMKit z-stacks. Takes a z-stack
+you've already loaded or fitted in FLIMKit, stacks its per-slice intensity
+and lifetime maps into `(Z, Y, X)` volumes, saves them as an OME-Zarr store,
+and opens a popout 3D viewer with the two volumes side by side.
+
+## What it does
+
+- Adds **Tools > 3D Z-stack Explorer...** to FLIMKit.
+- Only does anything once a z-stack is loaded (FOV mode > Z-stack); otherwise
+  it tells you to load one first.
+- Walks every slice in the loaded z-stack through the FOV preview panel's own
+  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).
+- 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.
+
+## Install
+
+```
+pip install flimkit-zstack-explorer[gui]
+```
+
+`[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.
+
+FLIMKit discovers this through the `flimkit.plugins` entry point, so there's
+nothing else to wire up. On start it appears under Tools.
+
+## From code
+
+```python
+from flimkit_zstack_explorer import build_zstack_volumes, save_ome_zarr, load_ome_zarr
+
+# app is FLIMKit's running App instance, with a z-stack loaded in its
+# FOV preview panel
+intensity_stack, lifetime_stack = build_zstack_volumes(app)
+save_ome_zarr('volume.zarr', intensity_stack, lifetime_stack,
+              voxel_size_um=(2.0, 0.5, 0.5))
+
+intensity_stack, lifetime_stack = load_ome_zarr('volume.zarr')
+```
+
+To view a store outside FLIMKit:
+
+```
+python -m flimkit_zstack_explorer.viewer --zarr volume.zarr
+```
+
+## Why a separate process for the viewer
+
+FLIMKit's UI is Tkinter; PyVista's is VTK. Running VTK's render loop on a
+background thread inside a Tkinter process is unreliable, especially on
+macOS, where GUI toolkits generally expect to own the main thread. Building
+the volume and saving to disk happens inside FLIMKit; the popout viewer is a
+plain `python -m flimkit_zstack_explorer.viewer` subprocess reading the
+saved store, so it gets its own main thread and doesn't touch Tkinter at
+all.
+
+## Development
+
+```
+pip install -e .[gui,test]
+pytest
+```
+
+`tests/test_volumes.py` exercises the z-stack-to-array logic against a fake
+FOV preview panel, so it runs without Tkinter or a real FLIMKit install.
+`tests/test_zarr_io.py` round-trips real arrays through zarr/ome-zarr.

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+flimkit_zstack_explorer/__init__.py
+flimkit_zstack_explorer/plugin.py
+flimkit_zstack_explorer/viewer.py
+flimkit_zstack_explorer/volumes.py
+flimkit_zstack_explorer/zarr_io.py
+flimkit_zstack_explorer.egg-info/PKG-INFO
+flimkit_zstack_explorer.egg-info/SOURCES.txt
+flimkit_zstack_explorer.egg-info/dependency_links.txt
+flimkit_zstack_explorer.egg-info/entry_points.txt
+flimkit_zstack_explorer.egg-info/requires.txt
+flimkit_zstack_explorer.egg-info/top_level.txt
+tests/test_plugin_guard.py
+tests/test_viewer.py
+tests/test_volumes.py
+tests/test_zarr_io.py

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[flimkit.plugins]
+flimkit_zstack_explorer = flimkit_zstack_explorer

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer.egg-info/requires.txt

@@ -0,0 +1,9 @@
+numpy
+zarr>=2.16
+ome-zarr>=0.9
+
+[gui]
+pyvista>=0.44
+
+[test]
+pytest

flimkit_zstack_explorer-0.1.0/flimkit_zstack_explorer.egg-info/top_level.txt

@@ -0,0 +1 @@
+flimkit_zstack_explorer

flimkit_zstack_explorer-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ['setuptools>=68']
+build-backend = 'setuptools.build_meta'
+
+[project]
+name = 'flimkit-zstack-explorer'
+version = '0.1.0'
+description = '3D intensity and FLIM volume explorer for FLIMKit z-stacks'
+readme = 'README.md'
+requires-python = '>=3.12'
+license = 'MIT'
+authors = [
+    {name = 'Alex Hunt', email = 'alexander.hunt@ed.ac.uk'},
+]
+keywords = ['FLIM', 'fluorescence', 'lifetime', 'z-stack', '3D', 'zarr', 'pyvista']
+dependencies = [
+    'numpy',
+    'zarr>=2.16',
+    'ome-zarr>=0.9',
+]
+
+[project.optional-dependencies]
+gui = ['pyvista>=0.44']
+test = ['pytest']
+
+[project.entry-points.'flimkit.plugins']
+flimkit_zstack_explorer = 'flimkit_zstack_explorer'
+
+[tool.setuptools.packages.find]
+include = ['flimkit_zstack_explorer*']

flimkit_zstack_explorer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flimkit_zstack_explorer-0.1.0/tests/test_plugin_guard.py

@@ -0,0 +1,52 @@
+"""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

@@ -0,0 +1,20 @@
+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))

flimkit_zstack_explorer-0.1.0/tests/test_volumes.py

@@ -0,0 +1,106 @@
+import numpy as np
+import pytest
+
+from flimkit_zstack_explorer.volumes import build_zstack_volumes
+
+
+class FakePanel:
+    """Stands in for flimkit.UI.fov_preview.FOVPreviewPanel: enough of its
+    z-stack surface for build_zstack_volumes to drive without Tkinter."""
+
+    def __init__(self, zstack):
+        self._zstack = zstack
+        self._z_i = 0
+        self._intensity_map = None
+        self._lifetime_map = None
+        self.shown = []
+
+    def display_fit_results(self, ptu_path, fit_result, _keep_zstack=False):
+        self._intensity_map = fit_result['intensity']
+        self._lifetime_map = fit_result.get('lifetime')
+        self.shown.append(ptu_path)
+
+    def load_fov(self, ptu_path, _keep_zstack=False):
+        self._intensity_map = np.ones((4, 4), dtype=np.float32)
+        self._lifetime_map = None
+        self.shown.append(ptu_path)
+
+    def _show_zstack_slice(self, i):
+        self._z_i = i
+        desc = self._zstack[i]
+        if desc.get('fit_result') is not None:
+            self.display_fit_results(desc.get('ptu_path'), desc['fit_result'], _keep_zstack=True)
+        else:
+            self.load_fov(desc.get('ptu_path'), _keep_zstack=True)
+
+
+class FakeApp:
+    def __init__(self, panel):
+        self._fov_preview = panel
+        self.root = None
+
+
+def _slice(z, intensity, lifetime=None):
+    fit_result = {'intensity': np.array(intensity, dtype=np.float32)}
+    if lifetime is not None:
+        fit_result['lifetime'] = np.array(lifetime, dtype=np.float32)
+    return {'z': z, 'ptu_path': f'slice_{z}.ptu', 'fit_result': fit_result}
+
+
+def test_builds_stack_from_zstack_slices():
+    intensity = np.full((3, 3), 10.0)
+    lifetime = np.full((3, 3), 2.5)
+    zstack = [_slice(0, intensity, lifetime), _slice(1, intensity * 2, lifetime + 1)]
+    panel = FakePanel(zstack)
+    app = FakeApp(panel)
+
+    intensity_stack, lifetime_stack = build_zstack_volumes(app)
+
+    assert intensity_stack.shape == (2, 3, 3)
+    assert lifetime_stack.shape == (2, 3, 3)
+    assert np.allclose(intensity_stack[0], 10.0)
+    assert np.allclose(intensity_stack[1], 20.0)
+    assert np.allclose(lifetime_stack[1], 3.5)
+
+
+def test_missing_lifetime_becomes_nan_plane():
+    intensity = np.full((2, 2), 5.0)
+    zstack = [_slice(0, intensity, lifetime=None)]
+    panel = FakePanel(zstack)
+    app = FakeApp(panel)
+
+    _, lifetime_stack = build_zstack_volumes(app)
+
+    assert lifetime_stack.shape == (1, 2, 2)
+    assert np.all(np.isnan(lifetime_stack[0]))
+
+
+def test_no_zstack_raises():
+    panel = FakePanel(zstack=None)
+    app = FakeApp(panel)
+
+    with pytest.raises(RuntimeError, match='No z-stack'):
+        build_zstack_volumes(app)
+
+
+def test_mismatched_slice_shapes_raise():
+    zstack = [
+        _slice(0, np.zeros((3, 3))),
+        _slice(1, np.zeros((4, 4))),
+    ]
+    panel = FakePanel(zstack)
+    app = FakeApp(panel)
+
+    with pytest.raises(RuntimeError, match='same size'):
+        build_zstack_volumes(app)
+
+
+def test_restores_original_slice_after_building():
+    zstack = [_slice(0, np.zeros((2, 2))), _slice(1, np.ones((2, 2)))]
+    panel = FakePanel(zstack)
+    panel._z_i = 1
+    app = FakeApp(panel)
+
+    build_zstack_volumes(app)
+
+    assert panel._z_i == 1

flimkit_zstack_explorer-0.1.0/tests/test_zarr_io.py

@@ -0,0 +1,38 @@
+import numpy as np
+import pytest
+
+from flimkit_zstack_explorer.zarr_io import save_ome_zarr, load_ome_zarr
+
+
+def test_roundtrip(tmp_path):
+    rng = np.random.default_rng(0)
+    intensity = rng.poisson(50, size=(4, 16, 20)).astype(np.float32)
+    lifetime = rng.uniform(1.5, 3.5, size=(4, 16, 20)).astype(np.float32)
+    lifetime[0] = np.nan
+
+    path = str(tmp_path / 'volume.zarr')
+    save_ome_zarr(path, intensity, lifetime, voxel_size_um=(2.0, 0.5, 0.5))
+
+    i2, l2 = load_ome_zarr(path)
+    assert i2.shape == intensity.shape
+    assert l2.shape == lifetime.shape
+    assert np.allclose(i2, intensity)
+    # NaNs in the source lifetime slice are written as 0 by save_ome_zarr's
+    # nan_to_num pass on intensity only; lifetime itself is written as-is,
+    # so slice 0 round-trips as NaN.
+    assert np.all(np.isnan(l2[0]))
+    assert np.allclose(l2[1:], lifetime[1:])
+
+
+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)
+    with pytest.raises(ValueError, match='same shape'):
+        save_ome_zarr(str(tmp_path / 'bad.zarr'), intensity, lifetime)
+
+
+def test_requires_3d_stacks(tmp_path):
+    intensity = np.zeros((4, 4), dtype=np.float32)
+    lifetime = np.zeros((4, 4), dtype=np.float32)
+    with pytest.raises(ValueError, match='Z, Y, X'):
+        save_ome_zarr(str(tmp_path / 'bad2.zarr'), intensity, lifetime)