cardio 2025.9.0__py3-none-any.whl → 2025.10.1__py3-none-any.whl

cardio/scene.py

@@ -1,54 +1,52 @@
 # System
 import logging
 import pathlib as pl
-
-# Type adapters for list types to improve CLI integration
-from typing import Annotated
+import typing as ty
 
 # Third Party
 import numpy as np
 import pydantic as pc
 import pydantic_settings as ps
 import vtk
-from pydantic import Field, PrivateAttr, TypeAdapter, field_validator, model_validator
 
 # Internal
 from .mesh import Mesh
 from .segmentation import Segmentation
 from .types import RGBColor
+from .utils import AngleUnit
 from .volume import Volume
 
-MeshListAdapter = TypeAdapter(list[Mesh])
-VolumeListAdapter = TypeAdapter(list[Volume])
-SegmentationListAdapter = TypeAdapter(list[Segmentation])
+MeshListAdapter = pc.TypeAdapter(list[Mesh])
+VolumeListAdapter = pc.TypeAdapter(list[Volume])
+SegmentationListAdapter = pc.TypeAdapter(list[Segmentation])
 
 # Create annotated types for better CLI integration
-MeshList = Annotated[
+MeshList = ty.Annotated[
     list[Mesh],
-    Field(
+    pc.Field(
         description='List of mesh objects. CLI usage: --meshes \'[{"label":"mesh1","directory":"./data/mesh1"}]\''
     ),
 ]
-VolumeList = Annotated[
+VolumeList = ty.Annotated[
     list[Volume],
-    Field(
+    pc.Field(
         description='Volume objects. CLI: --volumes \'[{"label":"vol1","directory":"./data/vol1"}]\''
     ),
 ]
-SegmentationList = Annotated[
+SegmentationList = ty.Annotated[
     list[Segmentation],
-    Field(
+    pc.Field(
         description='Segmentation objects. CLI: --segmentations \'[{"label":"seg1","directory":"./data/seg1"}]\''
     ),
 ]
 
 
 class Background(pc.BaseModel):
-    light: RGBColor = Field(
+    light: RGBColor = pc.Field(
         default=(1.0, 1.0, 1.0),
         description="Background color in light mode.  CLI usage: --background.light '[0.8,0.9,1.0]'",
     )
-    dark: RGBColor = Field(
+    dark: RGBColor = pc.Field(
         default=(0.0, 0.0, 0.0),
         description="Background color in dark mode.  CLI usage: --background.dark '[0.1,0.1,0.2]'",
     )
@@ -92,63 +90,83 @@ class Scene(ps.BaseSettings):
 
     project_name: str = "Cardio"
     current_frame: int = 0
-    screenshot_directory: pl.Path = pl.Path("./data/screenshots")
-    screenshot_subdirectory_format: str = "%Y-%m-%d-%H-%M-%S"
+    serialization_directory: pl.Path = pc.Field(
+        default=pl.Path("./data"),
+        description="Base directory for all serialized data (screenshots, exports, etc.)",
+    )
+    timestamp_format: str = pc.Field(
+        default="%Y-%m-%d-%H-%M-%S",
+        description="Timestamp format for serialized data subdirectories",
+    )
     rotation_factor: float = 3.0
-    background: Background = Field(
+    background: Background = pc.Field(
         default_factory=Background,
         description='Background colors. CLI usage: \'{"light": [0.8, 0.9, 1.0], "dark": [0.1, 0.1, 0.2]}\'',
     )
-    meshes: MeshList = Field(default_factory=list)
-    volumes: VolumeList = Field(default_factory=list)
-    segmentations: SegmentationList = Field(default_factory=list)
-    mpr_enabled: bool = Field(
+    meshes: MeshList = pc.Field(default_factory=list)
+    volumes: VolumeList = pc.Field(default_factory=list)
+    segmentations: SegmentationList = pc.Field(default_factory=list)
+    mpr_enabled: bool = pc.Field(
         default=False,
         description="Enable multi-planar reconstruction (MPR) mode with quad-view layout",
     )
-    active_volume_label: str = Field(
+    active_volume_label: str = pc.Field(
         default="",
         description="Label of the volume to use for multi-planar reconstruction",
     )
-    axial_slice: float = Field(
-        default=0.5, description="Axial slice position as fraction (0.0 to 1.0)"
+    axial_slice: float = pc.Field(
+        default=0.0,
+        description="Axial slice position in physical coordinates (LAS Z axis)",
     )
-    sagittal_slice: float = Field(
-        default=0.5, description="Sagittal slice position as fraction (0.0 to 1.0)"
+    sagittal_slice: float = pc.Field(
+        default=0.0,
+        description="Sagittal slice position in physical coordinates (LAS X axis)",
     )
-    coronal_slice: float = Field(
-        default=0.5, description="Coronal slice position as fraction (0.0 to 1.0)"
+    coronal_slice: float = pc.Field(
+        default=0.0,
+        description="Coronal slice position in physical coordinates (LAS Y axis)",
     )
-    mpr_window: float = Field(
+    mpr_window: float = pc.Field(
         default=800.0, description="Window width for MPR image display"
     )
-    mpr_level: float = Field(
+    mpr_level: float = pc.Field(
         default=200.0, description="Window level for MPR image display"
     )
-    mpr_window_level_preset: int = Field(
+    mpr_window_level_preset: int = pc.Field(
         default=7, description="Window/level preset key for MPR views"
     )
-    mpr_rotation_sequence: list = Field(
+    mpr_rotation_sequence: list = pc.Field(
         default_factory=list,
         description="Dynamic rotation sequence for MPR views - list of rotation steps",
     )
+    max_mpr_rotations: int = pc.Field(
+        default=20,
+        description="Maximum number of MPR rotations supported",
+    )
+    angle_units: AngleUnit = pc.Field(
+        default=AngleUnit.DEGREES,
+        description="Units for angle measurements in rotation serialization",
+    )
+    coordinate_system: str = pc.Field(
+        default="LAS", description="Coordinate system orientation (e.g., LAS, RAS, LPS)"
+    )
 
     # Field validators for JSON string inputs
-    @field_validator("meshes", mode="before")
+    @pc.field_validator("meshes", mode="before")
     @classmethod
     def validate_meshes(cls, v):
         if isinstance(v, str):
             return MeshListAdapter.validate_json(v)
         return v
 
-    @field_validator("volumes", mode="before")
+    @pc.field_validator("volumes", mode="before")
     @classmethod
     def validate_volumes(cls, v):
         if isinstance(v, str):
             return VolumeListAdapter.validate_json(v)
         return v
 
-    @field_validator("segmentations", mode="before")
+    @pc.field_validator("segmentations", mode="before")
     @classmethod
     def validate_segmentations(cls, v):
         if isinstance(v, str):
@@ -156,18 +174,18 @@ class Scene(ps.BaseSettings):
         return v
 
     # VTK objects as private attributes
-    _renderer: vtk.vtkRenderer = PrivateAttr(default_factory=vtk.vtkRenderer)
-    _renderWindow: vtk.vtkRenderWindow = PrivateAttr(
+    _renderer: vtk.vtkRenderer = pc.PrivateAttr(default_factory=vtk.vtkRenderer)
+    _renderWindow: vtk.vtkRenderWindow = pc.PrivateAttr(
         default_factory=vtk.vtkRenderWindow
     )
-    _renderWindowInteractor: vtk.vtkRenderWindowInteractor = PrivateAttr(
+    _renderWindowInteractor: vtk.vtkRenderWindowInteractor = pc.PrivateAttr(
         default_factory=vtk.vtkRenderWindowInteractor
     )
 
     # MPR render windows
-    _axial_renderWindow: vtk.vtkRenderWindow = PrivateAttr(default=None)
-    _coronal_renderWindow: vtk.vtkRenderWindow = PrivateAttr(default=None)
-    _sagittal_renderWindow: vtk.vtkRenderWindow = PrivateAttr(default=None)
+    _axial_renderWindow: vtk.vtkRenderWindow = pc.PrivateAttr(default=None)
+    _coronal_renderWindow: vtk.vtkRenderWindow = pc.PrivateAttr(default=None)
+    _sagittal_renderWindow: vtk.vtkRenderWindow = pc.PrivateAttr(default=None)
 
     @property
     def renderer(self) -> vtk.vtkRenderer:
@@ -193,7 +211,7 @@ class Scene(ps.BaseSettings):
     def sagittal_renderWindow(self) -> vtk.vtkRenderWindow:
         return self._sagittal_renderWindow
 
-    @model_validator(mode="after")
+    @pc.model_validator(mode="after")
     def setup_scene(self):
         # Validate unique labels
         self._validate_unique_labels()
@@ -264,6 +282,16 @@ class Scene(ps.BaseSettings):
                 "Active volume label specified but no volumes are available"
             )
 
+    @property
+    def screenshot_directory(self) -> pl.Path:
+        """Computed property that returns the screenshots subdirectory."""
+        return self.serialization_directory / "screenshots"
+
+    @property
+    def rotations_directory(self) -> pl.Path:
+        """Computed property that returns the rotations subdirectory."""
+        return self.serialization_directory / "rotations"
+
     @property
     def nframes(self) -> int:
         ns = []
@@ -316,6 +344,7 @@ class Scene(ps.BaseSettings):
 
             # Create and set interactor for axial
             axial_interactor = vtk.vtkRenderWindowInteractor()
+            axial_interactor.SetInteractorStyle(vtk.vtkInteractorStyle())
             self._axial_renderWindow.SetInteractor(axial_interactor)
 
             # Create coronal render window
@@ -327,6 +356,7 @@ class Scene(ps.BaseSettings):
 
             # Create and set interactor for coronal
             coronal_interactor = vtk.vtkRenderWindowInteractor()
+            coronal_interactor.SetInteractorStyle(vtk.vtkInteractorStyle())
             self._coronal_renderWindow.SetInteractor(coronal_interactor)
 
             # Create sagittal render window
@@ -338,6 +368,7 @@ class Scene(ps.BaseSettings):
 
             # Create and set interactor for sagittal
             sagittal_interactor = vtk.vtkRenderWindowInteractor()
+            sagittal_interactor.SetInteractorStyle(vtk.vtkInteractorStyle())
             self._sagittal_renderWindow.SetInteractor(sagittal_interactor)
 
     def hide_all_frames(self):

cardio/segmentation.py

@@ -8,16 +8,18 @@ import pydantic as pc
 import vtk
 
 # Internal
+from .orientation import (
+    reset_direction,
+)
 from .object import Object
 from .property_config import vtkPropertyConfig
-from .utils import InterpolatorType, reset_direction
 
 
 class Segmentation(Object):
     """Segmentation object with multi-label mesh extraction using SurfaceNets."""
 
     pattern: str = pc.Field(
-        default="${frame}.nii.gz",
+        default="{frame}.nii.gz",
         description="Filename pattern with $frame placeholder",
     )
     _actors: list[vtk.vtkActor] = pc.PrivateAttr(default_factory=list)
@@ -35,7 +37,7 @@ class Segmentation(Object):
 
             # Read and process segmentation image
             image = itk.imread(path)
-            image = reset_direction(image, InterpolatorType.NEAREST)
+            image = reset_direction(image)
             vtk_image = itk.vtk_image_from_image(image)
 
             # Create SurfaceNets3D filter

cardio/ui.py

@@ -1,15 +1,140 @@
+import functools as ft
+
 from trame.ui.vuetify3 import SinglePageWithDrawerLayout
 from trame.widgets import vtk as vtk_widgets
 from trame.widgets import vuetify3 as vuetify
 
 from .scene import Scene
 from .volume_property_presets import list_volume_property_presets
+from .window_level import presets
 
 
 class UI:
+    @property
+    def handled_events(self):
+        return [
+            "MouseMove",
+            "LeftButtonPress",
+            "LeftButtonRelease",
+            "RightButtonPress",
+            "RightButtonRelease",
+            "KeyPress",
+        ]
+
+    def event_listeners_for_view(self, view_name):
+        """Create event listeners for a specific view."""
+        result = {}
+        for event in self.handled_events:
+            callback = ft.partial(self.on_event, view_name=view_name)
+            result[event] = (callback, "[utils.vtk.event($event)]")
+        return result
+
+    def on_event(self, *args, view_name=None, **kwargs):
+        if not args:
+            return
+
+        event = args[0]
+
+        match event["type"]:
+            case "KeyPress":
+                if event["key"].isdigit():
+                    key_num = int(event["key"])
+                    if key_num in presets.keys():
+                        self.server.state.mpr_window_level_preset = key_num
+
+            case "LeftButtonPress":
+                self.left_dragging = True
+                self._store_mouse_position(view_name, event)
+
+            case "LeftButtonRelease":
+                self.left_dragging = False
+
+            case "RightButtonPress":
+                self.right_dragging = True
+                self._store_mouse_position(view_name, event)
+
+            case "RightButtonRelease":
+                self.right_dragging = False
+
+            case "MouseMove" if self.left_dragging:
+                if (
+                    view_name in {"axial", "sagittal", "coronal"}
+                    and view_name in self.last_mouse_pos
+                    and "position" in event
+                ):
+                    current_pos = [event["position"]["x"], event["position"]["y"]]
+                    dx = current_pos[0] - self.last_mouse_pos[view_name][0]
+                    dy = current_pos[1] - self.last_mouse_pos[view_name][1]
+                    self.last_mouse_pos[view_name] = current_pos
+
+                    current_window = getattr(self.server.state, "mpr_window", 400.0)
+                    current_level = getattr(self.server.state, "mpr_level", 40.0)
+
+                    window_delta = -dx * self.window_sensitivity
+                    level_delta = -dy * self.level_sensitivity
+                    new_window = max(1.0, current_window + window_delta)
+                    new_level = current_level + level_delta
+
+                    self.server.state.mpr_window = new_window
+                    self.server.state.mpr_level = new_level
+
+            case "MouseMove" if self.right_dragging:
+                if (
+                    view_name in {"axial", "sagittal", "coronal"}
+                    and view_name in self.last_mouse_pos
+                    and "position" in event
+                ):
+                    current_pos = [event["position"]["x"], event["position"]["y"]]
+                    dy = current_pos[1] - self.last_mouse_pos[view_name][1]
+                    self.last_mouse_pos[view_name] = current_pos
+
+                    base_slice_delta = dy * self.slice_sensitivity
+                    self._handle_slice_scroll(view_name, base_slice_delta)
+
+    def _store_mouse_position(self, view_name, event):
+        """Store mouse position for drag operations."""
+        if view_name and "position" in event:
+            self.last_mouse_pos[view_name] = [
+                event["position"]["x"],
+                event["position"]["y"],
+            ]
+
+    def _handle_slice_scroll(self, view_name, base_slice_delta):
+        """Handle slice scrolling for a specific view."""
+        match view_name:
+            case "axial":
+                current_slice = getattr(self.server.state, "axial_slice", 0.0)
+                bounds = getattr(self.server.state, "axial_slice_bounds", [0.0, 100.0])
+                slice_attr = "axial_slice"
+            case "sagittal":
+                current_slice = getattr(self.server.state, "sagittal_slice", 0.0)
+                bounds = getattr(
+                    self.server.state, "sagittal_slice_bounds", [0.0, 100.0]
+                )
+                slice_attr = "sagittal_slice"
+            case "coronal":
+                current_slice = getattr(self.server.state, "coronal_slice", 0.0)
+                bounds = getattr(
+                    self.server.state, "coronal_slice_bounds", [0.0, 100.0]
+                )
+                slice_attr = "coronal_slice"
+            case _:
+                return
+
+        min_bound, max_bound = min(bounds), max(bounds)
+        slice_delta = base_slice_delta if bounds[1] > bounds[0] else -base_slice_delta
+        new_slice = max(min_bound, min(max_bound, current_slice + slice_delta))
+        setattr(self.server.state, slice_attr, new_slice)
+
     def __init__(self, server, scene: Scene):
         self.server = server
         self.scene: Scene = scene
+        self.left_dragging = False
+        self.right_dragging = False
+        self.last_mouse_pos = {}
+        self.window_sensitivity = 5.0
+        self.level_sensitivity = 2.0
+        self.slice_sensitivity = 1.0
 
         self.setup()
 
@@ -63,7 +188,10 @@ class UI:
                     classes="pa-0 fill-height",
                 ):
                     view = vtk_widgets.VtkRemoteView(
-                        self.scene.renderWindow, interactive_ratio=1
+                        self.scene.renderWindow,
+                        interactor_events=("event_types", self.handled_events),
+                        **self.event_listeners_for_view("volume"),
+                        interactive_ratio=1,
                     )
                     self.server.controller.view_update = view.update
                     self.server.controller.view_reset_camera = view.reset_camera
@@ -88,15 +216,19 @@ class UI:
                             axial_view = vtk_widgets.VtkRemoteView(
                                 self.scene.axial_renderWindow,
                                 style="height: 100%; width: 100%;",
+                                interactor_events=("event_types", self.handled_events),
+                                **self.event_listeners_for_view("axial"),
                                 interactive_ratio=1,
                             )
                         with vuetify.VCol(
                             cols="6", classes="pa-1", style="height: 100%;"
                         ):
-                            # Volume view (reuse existing render window)
+                            # Volume view
                             volume_view = vtk_widgets.VtkRemoteView(
                                 self.scene.renderWindow,
                                 style="height: 100%; width: 100%;",
+                                interactor_events=("event_types", self.handled_events),
+                                **self.event_listeners_for_view("volume_mpr"),
                                 interactive_ratio=1,
                             )
 
@@ -109,6 +241,8 @@ class UI:
                             coronal_view = vtk_widgets.VtkRemoteView(
                                 self.scene.coronal_renderWindow,
                                 style="height: 100%; width: 100%;",
+                                interactor_events=("event_types", self.handled_events),
+                                **self.event_listeners_for_view("coronal"),
                                 interactive_ratio=1,
                             )
                         with vuetify.VCol(
@@ -118,6 +252,8 @@ class UI:
                             sagittal_view = vtk_widgets.VtkRemoteView(
                                 self.scene.sagittal_renderWindow,
                                 style="height: 100%; width: 100%;",
+                                interactor_events=("event_types", self.handled_events),
+                                **self.event_listeners_for_view("sagittal"),
                                 interactive_ratio=1,
                             )
 
@@ -207,10 +343,9 @@ class UI:
 
                     vuetify.VSlider(
                         v_if="mpr_enabled && active_volume_label",
-                        v_model=("axial_slice", 0.5),
-                        min=0.0,
-                        max=1.0,
-                        step=0.01,
+                        v_model=("axial_slice", 0.0),
+                        min=("axial_slice_bounds[0]", 0.0),
+                        max=("axial_slice_bounds[1]", 100.0),
                         hint="A (I ↔ S)",
                         persistent_hint=True,
                         dense=True,
@@ -220,10 +355,9 @@ class UI:
 
                     vuetify.VSlider(
                         v_if="mpr_enabled && active_volume_label",
-                        v_model=("sagittal_slice", 0.5),
-                        min=0.0,
-                        max=1.0,
-                        step=0.01,
+                        v_model=("sagittal_slice", 0.0),
+                        min=("sagittal_slice_bounds[0]", 0.0),
+                        max=("sagittal_slice_bounds[1]", 100.0),
                         hint="S (R ↔ L)",
                         persistent_hint=True,
                         dense=True,
@@ -233,10 +367,9 @@ class UI:
 
                     vuetify.VSlider(
                         v_if="mpr_enabled && active_volume_label",
-                        v_model=("coronal_slice", 0.5),
-                        min=0.0,
-                        max=1.0,
-                        step=0.01,
+                        v_model=("coronal_slice", 0.0),
+                        min=("coronal_slice_bounds[0]", 0.0),
+                        max=("coronal_slice_bounds[1]", 100.0),
                         hint="C (P ↔ A)",
                         persistent_hint=True,
                         dense=True,
@@ -262,6 +395,7 @@ class UI:
                                 small=True,
                                 dense=True,
                                 outlined=True,
+                                color="primary",
                             )
                         with vuetify.VCol(cols="4"):
                             vuetify.VBtn(
@@ -270,6 +404,7 @@ class UI:
                                 small=True,
                                 dense=True,
                                 outlined=True,
+                                color="primary",
                             )
                         with vuetify.VCol(cols="4"):
                             vuetify.VBtn(
@@ -278,6 +413,7 @@ class UI:
                                 small=True,
                                 dense=True,
                                 outlined=True,
+                                color="primary",
                             )
 
                     # Reset rotations button
@@ -291,22 +427,84 @@ class UI:
                         color="warning",
                         block=True,
                         classes="mb-2",
+                        prepend_icon="mdi-refresh",
                     )
 
-                    # Individual rotation sliders (show up to 10)
-                    for i in range(10):
-                        vuetify.VSlider(
+                    # Individual rotation sliders
+                    for i in range(self.scene.max_mpr_rotations):
+                        with vuetify.VRow(
                             v_if=f"mpr_enabled && active_volume_label && mpr_rotation_sequence && mpr_rotation_sequence.length > {i}",
-                            v_model=(f"mpr_rotation_angle_{i}", 0),
-                            min=-180,
-                            max=180,
-                            step=1,
-                            hint=(f"mpr_rotation_axis_{i}", f"Rotation {i + 1}"),
-                            persistent_hint=True,
-                            dense=True,
-                            hide_details=False,
-                            thumb_label=True,
-                        )
+                            no_gutters=True,
+                            classes="align-center mb-1",
+                        ):
+                            with vuetify.VCol(cols="8"):
+                                vuetify.VSlider(
+                                    v_model=(f"mpr_rotation_angle_{i}", 0),
+                                    min=-180,
+                                    max=180,
+                                    step=1,
+                                    hint=(
+                                        f"mpr_rotation_axis_{i}",
+                                        f"Rotation {i + 1}",
+                                    ),
+                                    persistent_hint=True,
+                                    dense=True,
+                                    hide_details=False,
+                                    thumb_label=True,
+                                )
+                            with vuetify.VCol(cols="2"):
+                                vuetify.VCheckbox(
+                                    v_model=(f"mpr_rotation_visible_{i}", True),
+                                    true_icon="mdi-eye",
+                                    false_icon="mdi-eye-off",
+                                    hide_details=True,
+                                    dense=True,
+                                    title="Toggle this rotation and all subsequent ones",
+                                )
+                            with vuetify.VCol(cols="2"):
+                                vuetify.VBtn(
+                                    icon="mdi-delete",
+                                    click=ft.partial(
+                                        self.server.controller.remove_rotation_event, i
+                                    ),
+                                    small=True,
+                                    dense=True,
+                                    color="error",
+                                    title="Remove this rotation and all subsequent ones",
+                                )
+
+                    # Angle units selector
+                    with vuetify.VRow(
+                        v_if="mpr_enabled && active_volume_label",
+                        no_gutters=True,
+                        classes="align-center mb-2 mt-2",
+                    ):
+                        with vuetify.VCol(cols="4"):
+                            vuetify.VLabel("Units:")
+                        with vuetify.VCol(cols="8"):
+                            vuetify.VSelect(
+                                v_model=("angle_units", "degrees"),
+                                items=("angle_units_items", []),
+                                item_title="text",
+                                item_value="value",
+                                dense=True,
+                                hide_details=True,
+                                outlined=True,
+                            )
+
+                    # Save rotations button
+                    vuetify.VBtn(
+                        "Save Rotations",
+                        v_if="mpr_enabled && active_volume_label && mpr_rotation_sequence && mpr_rotation_sequence.length > 0",
+                        click=self.server.controller.save_rotation_angles,
+                        small=True,
+                        dense=True,
+                        outlined=True,
+                        color="success",
+                        block=True,
+                        classes="mb-2",
+                        prepend_icon="mdi-content-save",
+                    )
 
                     vuetify.VDivider(classes="my-2")
 
@@ -412,10 +610,15 @@ class UI:
 
                 with vuetify.VRow(justify="center", classes="my-3"):
                     vuetify.VBtn(
-                        f"Capture Cine",
+                        "Capture Cine",
                         small=True,
+                        dense=True,
+                        outlined=True,
+                        color="info",
+                        block=True,
                         click=self.server.controller.screenshot,
                         title=f"Capture cine to {self.scene.screenshot_directory}",
+                        prepend_icon="mdi-video",
                     )
 
                 vuetify.VListSubheader("Appearance and Visibility")
@@ -518,10 +721,6 @@ class UI:
 
                         # Preset selection in collapsible panel
                         available_presets = list_volume_property_presets()
-                        current_preset = self.server.state[f"volume_preset_{v.label}"]
-                        current_desc = available_presets.get(
-                            current_preset, current_preset
-                        )
 
                         with vuetify.VExpansionPanels(
                             v_model=f"preset_panel_{v.label}",