TwoPy 0.1.0__py3-none-any.whl

twopy/napari/launcher.py

@@ -0,0 +1,175 @@
+"""Command-line launcher for the twopy napari app.
+
+Inputs: optional ``recording_data.h5`` path and preview/ROI command-line
+arguments.
+Outputs: a napari viewer, either empty or populated with a converted recording.
+
+The launcher is the application entry point. It should stay thin: query and
+analysis workflows belong in dedicated helpers that the controls call.
+"""
+
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+
+from twopy.napari.controls import add_twopy_magicgui_controls
+from twopy.napari.layout import place_response_options_after_recording_list
+from twopy.napari.loading import resolve_or_convert_launch_recording
+from twopy.napari.types import NapariRecordingView
+from twopy.napari.viewer import create_viewer, open_recording_in_napari
+
+__all__ = ["launch_napari", "main"]
+
+
+def launch_napari(
+    recording_data_path: Path | None = None,
+    *,
+    roi_file_to_load: Path | None = None,
+    roi_save_file: Path | None = None,
+    movie_start_frame: int = 0,
+    movie_end_frame: int | None = None,
+    load_movie: bool = True,
+) -> NapariRecordingView | None:
+    """Launch napari and start the event loop.
+
+    Args:
+        recording_data_path: Optional path to a source recording, converted
+            folder, or ``recording_data.h5``. When omitted, twopy opens the
+            current directory or ``./twopy`` recording if one exists; otherwise
+            it opens an empty viewer with folder-based recording selection.
+        roi_file_to_load: Optional saved ROI HDF5 path to reopen.
+        roi_save_file: Optional ROI output path for the Save ROIs button.
+        movie_start_frame: First movie preview frame.
+        movie_end_frame: Last movie frame to load. ``None`` means the final
+            movie frame.
+        load_movie: Whether to add the aligned movie layer.
+
+    Returns:
+        ``NapariRecordingView`` when a recording is loaded at startup,
+        otherwise ``None``.
+
+    This is the script-facing launcher. It may convert source data before
+    opening napari, but all analysis still starts from converted HDF5 files.
+    """
+    resolved_recording = resolve_or_convert_launch_recording(recording_data_path)
+    movie_range = (int(movie_start_frame), movie_end_frame) if load_movie else None
+    viewer = create_viewer()
+    if resolved_recording is None:
+        from twopy.napari.plotting import (
+            add_twopy_response_options_widget,
+            add_twopy_response_plot_widget,
+        )
+
+        response_plot_widget, _response_plot_dock = add_twopy_response_plot_widget(
+            viewer,
+            recording=None,
+        )
+        control_docks = add_twopy_magicgui_controls(
+            viewer,
+            roi_labels_layer=None,
+            roi_save_file=(
+                roi_save_file.expanduser()
+                if roi_save_file is not None
+                else Path.cwd() / "rois.h5"
+            ),
+            response_plot_widget=response_plot_widget,
+        )
+        _response_options_widget, response_options_dock = (
+            add_twopy_response_options_widget(viewer, response_plot_widget)
+        )
+        place_response_options_after_recording_list(
+            viewer,
+            control_docks.loaded_recordings_dock_widget,
+            response_options_dock,
+        )
+        view = None
+    else:
+        paths = resolved_recording.paths
+        view = open_recording_in_napari(
+            paths.recording_data_path,
+            viewer=viewer,
+            roi_set=roi_file_to_load,
+            roi_save_file=roi_save_file,
+            movie_path=paths.movie_path,
+            movie_frame_range=movie_range,
+        )
+
+    import napari
+
+    napari.run()
+    return view
+
+
+def parse_launch_args() -> Namespace:
+    """Parse command-line arguments for ``python -m twopy.napari``.
+
+    Args:
+        None.
+
+    Returns:
+        Parsed argument namespace.
+    """
+    parser = ArgumentParser(
+        description="Launch napari for a twopy-converted recording.",
+    )
+    parser.add_argument(
+        "recording_data_path",
+        nargs="?",
+        type=Path,
+        help=(
+            "Path to a source recording, converted folder, or recording_data.h5. "
+            "If omitted, twopy checks the current directory and ./twopy output, "
+            "then opens an empty viewer if neither exists."
+        ),
+    )
+    parser.add_argument(
+        "--roi-file-to-load",
+        dest="roi_file_to_load",
+        type=Path,
+        default=None,
+        help="Optional existing ROI HDF5 file to load into the Labels layer.",
+    )
+    parser.add_argument(
+        "--roi-save-file",
+        dest="roi_save_file",
+        type=Path,
+        default=None,
+        help="Optional ROI HDF5 output path for the Save ROIs button.",
+    )
+    parser.add_argument(
+        "--movie-start",
+        type=int,
+        default=0,
+        help="First frame for the movie preview.",
+    )
+    parser.add_argument(
+        "--movie-end",
+        type=int,
+        default=None,
+        help="Last frame for the movie preview. Defaults to the final frame.",
+    )
+    parser.add_argument(
+        "--no-movie",
+        action="store_true",
+        help="Skip loading movie preview frames and show only the mean image.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    """Run the twopy napari launcher from the command line.
+
+    Args:
+        None.
+
+    Returns:
+        None.
+    """
+    args = parse_launch_args()
+    launch_napari(
+        args.recording_data_path,
+        roi_file_to_load=args.roi_file_to_load,
+        roi_save_file=args.roi_save_file,
+        movie_start_frame=args.movie_start,
+        movie_end_frame=args.movie_end,
+        load_movie=not args.no_movie,
+    )

twopy/napari/layout.py

@@ -0,0 +1,147 @@
+"""Napari dock-layout helpers for twopy widgets.
+
+Inputs: napari viewer and dock-widget objects.
+Outputs: best-effort Qt dock placement.
+
+These helpers own visual placement only. If napari or Qt internals change, the
+widgets still exist and continue to work; only the preferred layout is skipped.
+"""
+
+from twopy.napari.protocols import NapariViewer
+
+__all__ = [
+    "place_loaded_recordings_dock_after_load",
+    "place_response_options_after_recording_list",
+    "place_save_rois_dock_before_layer_list",
+]
+
+
+def place_save_rois_dock_before_layer_list(
+    viewer: NapariViewer,
+    save_rois_dock_widget: object,
+) -> None:
+    """Place Save ROIs between napari layer controls and layer list.
+
+    Args:
+        viewer: Napari viewer that owns the dock widgets.
+        save_rois_dock_widget: Dock widget returned for the Save ROIs panel.
+
+    Returns:
+        None.
+    """
+    try:
+        from qtpy.QtCore import Qt
+    except ImportError:
+        return
+
+    window = viewer.window
+    qt_window = getattr(window, "_qt_window", None)
+    qt_viewer = getattr(window, "_qt_viewer", None)
+    if qt_window is None or qt_viewer is None:
+        return
+
+    layer_controls = getattr(qt_viewer, "dockLayerControls", None)
+    layer_list = getattr(qt_viewer, "dockLayerList", None)
+    if layer_controls is None or layer_list is None:
+        return
+    if not hasattr(qt_window, "splitDockWidget") or not hasattr(
+        qt_window,
+        "resizeDocks",
+    ):
+        return
+
+    qt_window.splitDockWidget(
+        layer_controls,
+        save_rois_dock_widget,
+        Qt.Orientation.Vertical,
+    )
+    qt_window.resizeDocks(
+        [layer_controls, save_rois_dock_widget, layer_list],
+        [layer_controls.minimumHeight(), 120, 10000],
+        Qt.Orientation.Vertical,
+    )
+
+
+def place_loaded_recordings_dock_after_load(
+    viewer: NapariViewer,
+    load_dock_widget: object,
+    loaded_recordings_dock_widget: object,
+) -> None:
+    """Stack Loaded Recordings under the Load Recording dock.
+
+    Args:
+        viewer: Napari viewer that owns the dock widgets.
+        load_dock_widget: Dock widget returned for load controls.
+        loaded_recordings_dock_widget: Dock widget returned for the loaded
+            recordings panel.
+
+    Returns:
+        None.
+    """
+    try:
+        from qtpy.QtCore import Qt
+    except ImportError:
+        return
+
+    qt_window = getattr(viewer.window, "_qt_window", None)
+    if qt_window is None:
+        return
+    if not hasattr(qt_window, "splitDockWidget") or not hasattr(
+        qt_window,
+        "resizeDocks",
+    ):
+        return
+    qt_window.splitDockWidget(
+        load_dock_widget,
+        loaded_recordings_dock_widget,
+        Qt.Orientation.Vertical,
+    )
+    qt_window.resizeDocks(
+        [load_dock_widget, loaded_recordings_dock_widget],
+        [260, 180],
+        Qt.Orientation.Vertical,
+    )
+
+
+def place_response_options_after_recording_list(
+    viewer: NapariViewer,
+    loaded_recordings_dock_widget: object | None,
+    response_options_dock_widget: object | None,
+) -> None:
+    """Stack response options under the Loaded Recordings dock.
+
+    Args:
+        viewer: Napari viewer that owns the dock widgets.
+        loaded_recordings_dock_widget: Dock widget returned for the loaded
+            recordings panel.
+        response_options_dock_widget: Dock widget returned for response
+            options.
+
+    Returns:
+        None.
+    """
+    if loaded_recordings_dock_widget is None or response_options_dock_widget is None:
+        return
+    try:
+        from qtpy.QtCore import Qt
+    except ImportError:
+        return
+
+    qt_window = getattr(viewer.window, "_qt_window", None)
+    if qt_window is None:
+        return
+    if not hasattr(qt_window, "splitDockWidget") or not hasattr(
+        qt_window,
+        "resizeDocks",
+    ):
+        return
+    qt_window.splitDockWidget(
+        loaded_recordings_dock_widget,
+        response_options_dock_widget,
+        Qt.Orientation.Vertical,
+    )
+    qt_window.resizeDocks(
+        [loaded_recordings_dock_widget, response_options_dock_widget],
+        [180, 10000],
+        Qt.Orientation.Vertical,
+    )

twopy/napari/loading.py

@@ -0,0 +1,207 @@
+"""Recording loading helpers for the twopy napari adapter.
+
+Inputs: user-selected recording folders, converted folders, or recording files.
+Outputs: converted recording paths ready for napari.
+
+This module may trigger conversion when a selected source recording does not
+yet have twopy HDF5 output. It keeps that write behavior out of the read-only
+path resolver.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import h5py
+
+from twopy.conversion import convert_recording_to_twopy
+from twopy.napari.constants import RECORDING_DATA_FILENAME
+from twopy.napari.paths import NapariRecordingPaths, PathInput, is_default_path
+from twopy.napari.paths import resolve_recording_paths as resolve_converted_paths
+from twopy.session import discover_session_files
+
+__all__ = [
+    "ResolvedNapariRecording",
+    "resolve_or_convert_launch_recording",
+    "resolve_or_convert_recording",
+]
+
+
+@dataclass(frozen=True)
+class ResolvedNapariRecording:
+    """Resolved recording paths plus whether napari had to convert first.
+
+    Inputs: one selected path.
+    Outputs: converted paths and a conversion flag for user-facing status.
+    """
+
+    paths: NapariRecordingPaths
+    was_converted: bool
+
+
+def resolve_or_convert_recording(path: PathInput) -> ResolvedNapariRecording:
+    """Resolve a selected recording path, converting source data if needed.
+
+    Args:
+        path: User-selected source folder, converted folder, or
+            ``recording_data.h5`` path.
+
+    Returns:
+        Converted recording paths and whether conversion was run.
+
+    Raises:
+        ValueError: If the path is neither converted twopy output nor a source
+            recording folder.
+
+    Existing converted files win. If ``recording_data.h5`` exists but
+    ``aligned_movie.h5`` is missing and the source recording can be identified,
+    conversion rewrites that same output folder to repair the pair.
+    """
+    selected = Path.cwd() if is_default_path(path) else Path(path).expanduser()
+    try:
+        paths = resolve_converted_paths(selected)
+    except ValueError as error:
+        source_dir = _source_recording_dir(selected)
+        if source_dir is None:
+            raise error
+        converted = convert_recording_to_twopy(source_dir)
+        return ResolvedNapariRecording(
+            paths=resolve_converted_paths(converted.path),
+            was_converted=True,
+        )
+
+    if paths.movie_path is not None:
+        return ResolvedNapariRecording(paths=paths, was_converted=False)
+
+    source_dir = _source_recording_dir_for_converted_selection(
+        selected=selected,
+        recording_data_path=paths.recording_data_path,
+    )
+    if source_dir is None:
+        return ResolvedNapariRecording(paths=paths, was_converted=False)
+
+    converted = convert_recording_to_twopy(
+        source_dir,
+        output_dir=paths.recording_data_path.parent,
+    )
+    return ResolvedNapariRecording(
+        paths=resolve_converted_paths(converted.path),
+        was_converted=True,
+    )
+
+
+def resolve_or_convert_launch_recording(
+    recording_data_path: PathInput | None,
+) -> ResolvedNapariRecording | None:
+    """Resolve startup recording paths for the ``twopy`` command.
+
+    Args:
+        recording_data_path: Optional command-line path.
+
+    Returns:
+        Converted recording paths, or ``None`` when no startup recording is
+        available.
+
+    An explicit command-line path may be source or converted data. With no path,
+    twopy checks the current folder for converted output first, then treats the
+    current folder as a source recording only if it has the expected source file
+    shape.
+    """
+    if recording_data_path is not None:
+        return resolve_or_convert_recording(recording_data_path)
+
+    cwd = Path.cwd()
+    for candidate in (cwd / RECORDING_DATA_FILENAME, cwd / "twopy", cwd):
+        try:
+            return resolve_or_convert_recording(candidate)
+        except ValueError:
+            continue
+    return None
+
+
+def _source_recording_dir_for_converted_selection(
+    *,
+    selected: Path,
+    recording_data_path: Path,
+) -> Path | None:
+    """Infer the source recording folder for incomplete converted output.
+
+    Args:
+        selected: User-selected path.
+        recording_data_path: Existing converted ``recording_data.h5`` path.
+
+    Returns:
+        Source recording folder, or ``None`` when it cannot be inferred.
+    """
+    candidates = [
+        _source_dir_from_recording_data(recording_data_path),
+        selected,
+        selected.parent,
+        recording_data_path.parent.parent,
+    ]
+    if recording_data_path.parent.name == "twopy":
+        candidates.insert(0, recording_data_path.parent.parent)
+    return _first_source_recording_dir(tuple(candidates))
+
+
+def _source_recording_dir(path: Path) -> Path | None:
+    """Return the source recording folder implied by one selected path.
+
+    Args:
+        path: User-selected path.
+
+    Returns:
+        Source recording folder, or ``None``.
+    """
+    candidates = [path]
+    if path.is_file():
+        candidates.append(path.parent)
+    if path.name == "twopy":
+        candidates.append(path.parent)
+    if path.parent.name == "twopy":
+        candidates.append(path.parent.parent)
+    return _first_source_recording_dir(tuple(candidates))
+
+
+def _source_dir_from_recording_data(recording_data_path: Path) -> Path | None:
+    """Read the source recording folder recorded during conversion.
+
+    Args:
+        recording_data_path: Existing converted recording file.
+
+    Returns:
+        Source recording path, or ``None`` if the file cannot be read.
+    """
+    try:
+        with h5py.File(recording_data_path, "r") as h5_file:
+            value = h5_file.attrs.get("source_session_dir")
+    except OSError:
+        return None
+    if isinstance(value, bytes):
+        value = value.decode("utf-8")
+    if not isinstance(value, str) or value == "":
+        return None
+    return Path(value).expanduser()
+
+
+def _first_source_recording_dir(candidates: tuple[Path | None, ...]) -> Path | None:
+    """Return the first candidate with the expected source recording files.
+
+    Args:
+        candidates: Possible source recording folders.
+
+    Returns:
+        Resolved source folder, or ``None``.
+    """
+    seen: set[Path] = set()
+    for candidate in candidates:
+        if candidate is None:
+            continue
+        expanded = candidate.expanduser()
+        if expanded in seen:
+            continue
+        seen.add(expanded)
+        try:
+            return discover_session_files(expanded).session_dir.resolve()
+        except (FileNotFoundError, ValueError):
+            continue
+    return None

twopy/napari/movie.py

@@ -0,0 +1,71 @@
+"""Movie frame-range helpers for the twopy napari adapter.
+
+Inputs: GUI or CLI movie frame numbers.
+Outputs: validated inclusive frame ranges and HDF5 reader stop indices.
+
+Napari controls show inclusive frame numbers because that is the intuitive UI
+contract. The converted movie reader uses Python's exclusive stop convention,
+so the conversion happens in one small helper.
+"""
+
+__all__ = ["exclusive_stop", "resolve_movie_frame_range"]
+
+
+def resolve_movie_frame_range(
+    *,
+    start_frame: int,
+    end_frame: int | None,
+    frame_count: int,
+    zero_end_means_last: bool = False,
+) -> tuple[int, int]:
+    """Resolve and validate an inclusive movie frame range.
+
+    Args:
+        start_frame: First movie frame.
+        end_frame: Last movie frame, or ``None`` for the final frame.
+        frame_count: Number of available movie frames.
+        zero_end_means_last: Whether ``start=0, end=0`` should mean the final
+            frame. The empty-launch widget uses this before it knows the movie
+            length.
+
+    Returns:
+        Inclusive ``(start, end)`` movie frame range.
+    """
+    if start_frame < 0:
+        msg = f"movie_start_frame must be at least 0; got {start_frame}"
+        raise ValueError(msg)
+    if frame_count < 1:
+        msg = f"movie must have at least 1 frame; got {frame_count}"
+        raise ValueError(msg)
+
+    last_frame = frame_count - 1
+    if end_frame is None or (
+        zero_end_means_last and start_frame == 0 and end_frame == 0
+    ):
+        resolved_end = last_frame
+    else:
+        resolved_end = end_frame
+
+    if resolved_end < start_frame:
+        msg = (
+            "movie_end_frame must be greater than or equal to "
+            f"movie_start_frame; got {resolved_end} < {start_frame}"
+        )
+        raise ValueError(msg)
+    if resolved_end > last_frame:
+        msg = f"movie_end_frame must be at most {last_frame}; got {resolved_end}"
+        raise ValueError(msg)
+    return (start_frame, resolved_end)
+
+
+def exclusive_stop(end_frame: int | None) -> int | None:
+    """Convert an inclusive end frame to a reader stop frame.
+
+    Args:
+        end_frame: Inclusive final frame, or ``None`` for the final movie
+            frame.
+
+    Returns:
+        Exclusive stop index for ``ConvertedMovie.read_frames``.
+    """
+    return None if end_frame is None else end_frame + 1