flimkit-zstack-explorer 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+flimkit_zstack_explorer/__init__.py,sha256=pW_qMjT80Mnb1aMZCHhP6GGPgXBF7ffPka24clno5jY,452
+flimkit_zstack_explorer/plugin.py,sha256=9F2UDuJMUayyj3PskH8bqYZCvffiag4r0QLWaiXIhmk,3298
+flimkit_zstack_explorer/viewer.py,sha256=vKQEvC23HKylaZE6CcC75l5vwFAfukxvhiBm6KHx2jc,2921
+flimkit_zstack_explorer/volumes.py,sha256=n3rP2hcFw0a3fcK-YrnEtp0p2k1rxKAq32toXEubo0Y,4319
+flimkit_zstack_explorer/zarr_io.py,sha256=HAfqCCDeelY8xEnWADdYsvgXSP6mmfoAkXdFT3ekvxw,2338
+flimkit_zstack_explorer-0.1.0.dist-info/licenses/LICENSE,sha256=xRkLMCd6sG_d7rMTncTVtj94vE9hvqc3Dpwl24IpfiU,1064
+flimkit_zstack_explorer-0.1.0.dist-info/METADATA,sha256=hdakiIR5NSLYk1_t4oI5R_K1En4jgIIgyrUwgEN1dUE,3336
+flimkit_zstack_explorer-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flimkit_zstack_explorer-0.1.0.dist-info/entry_points.txt,sha256=U_gF0roUnvUsu3hlCHabbNbHGvWYv1AaD8Ys58a2134,68
+flimkit_zstack_explorer-0.1.0.dist-info/top_level.txt,sha256=vMm_lu3R3uwr_SEW05dLX2wwSdPeAjbSNL0MeLHvMXI,24
+flimkit_zstack_explorer-0.1.0.dist-info/RECORD,,

flimkit_zstack_explorer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flimkit_zstack_explorer-0.1.0.dist-info/entry_points.txt

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

flimkit_zstack_explorer-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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