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

cardio/__init__.py

@@ -23,6 +23,7 @@ __all__ = [
     "Logic",
     "load_volume_property_preset",
     "list_volume_property_presets",
+    "window_level",
 ]
 
-__version__ = "2025.9.0"
+__version__ = "2025.10.1"

cardio/app.py

@@ -2,49 +2,42 @@
 
 # Third Party
 import pydantic_settings as ps
-import tomlkit as tk
 import trame as tm
+import trame.decorators
 
+# Internal
 from . import __version__
 from .logic import Logic
-
-# Internal
 from .scene import Scene
 from .ui import UI
 
 
-class CardioApp(tm.app.TrameApp):
-    def __init__(self, name=None):
-        super().__init__(server=name, client_type="vue3")
+@tm.decorators.TrameApp()
+class CardioApp:
+    def __init__(self, server=None):
+        self.server = tm.app.get_server(server, client_type="vue3")
 
-        # Add config file argument to Trame's parser
         self.server.cli.add_argument(
             "--config", help="TOML configuration file.", dest="cfg_file", required=False
         )
 
-        # Add version argument
         self.server.cli.add_argument(
             "--version", action="version", version=f"cardio {__version__}"
         )
 
-        # Create CLI settings source with Trame's parser - enable argument parsing
         cli_settings = ps.CliSettingsSource(
             Scene, root_parser=self.server.cli, cli_parse_args=True
         )
 
-        # Parse arguments to get config file path (use parse_known_args to avoid conflicts)
         args, unknown = self.server.cli.parse_known_args()
         config_file = getattr(args, "cfg_file", None)
 
-        # Set the CLI source and config file on the Scene class temporarily
         Scene._cli_source = cli_settings
         Scene._config_file = config_file
 
         try:
-            # Create Scene with CLI and config file support
             scene = Scene()
         finally:
-            # Clean up class attributes
             if hasattr(Scene, "_cli_source"):
                 delattr(Scene, "_cli_source")
             if hasattr(Scene, "_config_file"):

cardio/logic.py

@@ -21,6 +21,17 @@ class Logic:
             for volume in self.scene.volumes
         ]
 
+        # Initialize angle units items for dropdown
+        self.server.state.angle_units_items = [
+            {"text": "Degrees", "value": "degrees"},
+            {"text": "Radians", "value": "radians"},
+        ]
+
+        # Initialize slice bounds (will be updated when active volume changes)
+        self.server.state.axial_slice_bounds = [0.0, 100.0]
+        self.server.state.sagittal_slice_bounds = [0.0, 100.0]
+        self.server.state.coronal_slice_bounds = [0.0, 100.0]
+
         self.server.state.change("frame")(self.update_frame)
         self.server.state.change("playing")(self.play)
         self.server.state.change("theme_mode")(self.sync_background_color)
@@ -34,12 +45,16 @@ class Logic:
         )
         self.server.state.change("mpr_window_level_preset")(self.update_mpr_preset)
         self.server.state.change("mpr_rotation_sequence")(self.update_mpr_rotation)
+        self.server.state.change("angle_units")(self.sync_angle_units)
 
-        # Add handlers for individual rotation angles
-        for i in range(20):
+        # Add handlers for individual rotation angles and visibility
+        for i in range(self.scene.max_mpr_rotations):
             self.server.state.change(f"mpr_rotation_angle_{i}")(
                 self.update_mpr_rotation
             )
+            self.server.state.change(f"mpr_rotation_visible_{i}")(
+                self.update_mpr_rotation
+            )
 
         # Initialize visibility state variables
         for m in self.scene.meshes:
@@ -122,6 +137,7 @@ class Logic:
         self.server.controller.increment_frame = self.increment_frame
         self.server.controller.decrement_frame = self.decrement_frame
         self.server.controller.screenshot = self.screenshot
+        self.server.controller.save_rotation_angles = self.save_rotation_angles
         self.server.controller.reset_all = self.reset_all
         self.server.controller.close_application = self.close_application
 
@@ -142,22 +158,24 @@ class Logic:
         self.server.state.mpr_level = self.scene.mpr_level
         self.server.state.mpr_window_level_preset = self.scene.mpr_window_level_preset
         self.server.state.mpr_rotation_sequence = self.scene.mpr_rotation_sequence
+        self.server.state.angle_units = self.scene.angle_units.value
 
         # Initialize MPR presets data
         try:
             from .window_level import presets
 
             self.server.state.mpr_presets = [
-                {"text": preset.name, "value": key} for key, preset in presets.items()
-            ]
+                {"text": "Select W/L...", "value": None}
+            ] + [{"text": preset.name, "value": key} for key, preset in presets.items()]
         except Exception as e:
             print(f"Error initializing MPR presets: {e}")
             self.server.state.mpr_presets = []
 
-        # Initialize rotation angle states (up to 20 rotations like app.py)
-        for i in range(20):
+        # Initialize rotation angle states
+        for i in range(self.scene.max_mpr_rotations):
             setattr(self.server.state, f"mpr_rotation_angle_{i}", 0)
             setattr(self.server.state, f"mpr_rotation_axis_{i}", f"Rotation {i + 1}")
+            setattr(self.server.state, f"mpr_rotation_visible_{i}", True)
 
         # Apply initial preset to ensure window/level values are set correctly
         # Only update state values, don't call update methods yet since MPR may not be enabled
@@ -417,7 +435,7 @@ class Logic:
 
     @asynchronous.task
     async def screenshot(self):
-        dr = dt.datetime.now().strftime(self.scene.screenshot_subdirectory_format)
+        dr = dt.datetime.now().strftime(self.scene.timestamp_format)
         dr = self.scene.screenshot_directory / dr
         dr.mkdir(parents=True, exist_ok=True)
 
@@ -442,6 +460,65 @@ class Logic:
                         1 / self.server.state.bpm * 60 / self.scene.nframes
                     )
 
+    @asynchronous.task
+    async def save_rotation_angles(self):
+        """Save current rotation angles to a TOML file."""
+        import tomlkit as tk
+
+        # Get current timestamp
+        timestamp = dt.datetime.now()
+        timestamp_str = timestamp.strftime(self.scene.timestamp_format)
+        iso_timestamp = timestamp.isoformat()
+
+        # Get active volume label
+        active_volume_label = getattr(self.server.state, "active_volume_label", "")
+        if not active_volume_label:
+            print("Warning: No active volume selected for rotation saving")
+            return
+
+        # Create directory structure
+        save_dir = self.scene.rotations_directory / active_volume_label
+        save_dir.mkdir(parents=True, exist_ok=True)
+
+        # Create TOML structure
+        doc = tk.document()
+
+        # Metadata section
+        metadata = tk.table()
+        metadata["coordinate_system"] = self.scene.coordinate_system
+        metadata["units"] = self.scene.angle_units.value
+        metadata["timestamp"] = iso_timestamp
+        metadata["volume_label"] = active_volume_label
+        doc["metadata"] = metadata
+
+        # Slice positions section
+        slice_positions = tk.table()
+        slice_positions["axial"] = getattr(self.server.state, "axial_slice", 0.5)
+        slice_positions["sagittal"] = getattr(self.server.state, "sagittal_slice", 0.5)
+        slice_positions["coronal"] = getattr(self.server.state, "coronal_slice", 0.5)
+        doc["slice_positions"] = slice_positions
+
+        # Rotations section (array of tables)
+        rotation_sequence = getattr(self.server.state, "mpr_rotation_sequence", [])
+        rotations_array = tk.aot()
+
+        for i, rotation_def in enumerate(rotation_sequence):
+            rotation = tk.table()
+            rotation["axis"] = rotation_def["axis"]
+            angle = getattr(self.server.state, f"mpr_rotation_angle_{i}", 0)
+            rotation["angle"] = float(angle)
+            rotation["visible"] = getattr(
+                self.server.state, f"mpr_rotation_visible_{i}", True
+            )
+            rotations_array.append(rotation)
+
+        doc["rotations"] = rotations_array
+
+        # Save to file
+        output_path = save_dir / f"{timestamp_str}.toml"
+        with open(output_path, "w") as f:
+            f.write(tk.dumps(doc))
+
     def reset_all(self):
         self.server.state.frame = 0
         self.server.state.playing = False
@@ -465,6 +542,16 @@ class Logic:
             )
         self.server.controller.view_update()
 
+    def sync_angle_units(self, angle_units, **kwargs):
+        """Sync angle units selection - updates the scene configuration."""
+        from .utils import AngleUnit
+
+        # Update the scene's angle_units field based on UI selection
+        if angle_units == "degrees":
+            self.scene.angle_units = AngleUnit.DEGREES
+        elif angle_units == "radians":
+            self.scene.angle_units = AngleUnit.RADIANS
+
     def _initialize_clipping_state(self):
         """Initialize clipping state variables for all objects."""
         # Initialize mesh clipping state
@@ -546,6 +633,28 @@ class Logic:
         if not active_volume:
             return
 
+        # Update slice bounds based on active volume
+        try:
+            bounds = active_volume.get_physical_bounds()
+            self.server.state.axial_slice_bounds = [bounds[4], bounds[5]]  # Z bounds
+            self.server.state.sagittal_slice_bounds = [bounds[0], bounds[1]]  # X bounds
+            self.server.state.coronal_slice_bounds = [bounds[2], bounds[3]]  # Y bounds
+
+            # Initialize slice positions to volume center if they are currently 0.0 (scene defaults)
+            if self.server.state.axial_slice == 0.0:
+                self.server.state.axial_slice = (bounds[4] + bounds[5]) / 2  # Z center
+            if self.server.state.sagittal_slice == 0.0:
+                self.server.state.sagittal_slice = (
+                    bounds[0] + bounds[1]
+                ) / 2  # X center
+            if self.server.state.coronal_slice == 0.0:
+                self.server.state.coronal_slice = (
+                    bounds[2] + bounds[3]
+                ) / 2  # Y center
+        except (RuntimeError, IndexError) as e:
+            print(f"Error: Cannot get bounds for volume '{active_volume_label}': {e}")
+            return
+
         # Create MPR actors for current frame
         current_frame = getattr(self.server.state, "frame", 0)
         mpr_actors = active_volume.get_mpr_actors_for_frame(current_frame)
@@ -661,6 +770,14 @@ class Logic:
         level = getattr(self.server.state, "mpr_level", 40.0)
         current_frame = getattr(self.server.state, "frame", 0)
 
+        # Check if this change is from manual adjustment (not from preset)
+        # by checking if we're not in the middle of a preset update
+        if not getattr(self, "_updating_from_preset", False):
+            # Reset preset selection when manually adjusting window/level
+            current_preset = getattr(self.server.state, "mpr_window_level_preset", None)
+            if current_preset is not None:
+                self.server.state.mpr_window_level_preset = None
+
         # Update window/level for MPR actors
         active_volume.update_mpr_window_level(current_frame, window, level)
 
@@ -671,13 +788,24 @@ class Logic:
         """Update MPR window/level when preset changes."""
         from .window_level import presets
 
+        # Handle None value (Select W/L... option) - do nothing
+        if mpr_window_level_preset is None:
+            return
+
         if mpr_window_level_preset in presets:
             preset = presets[mpr_window_level_preset]
-            self.server.state.mpr_window = preset.window
-            self.server.state.mpr_level = preset.level
 
-            # Update the actual MPR views with new window/level
-            self.update_mpr_window_level()
+            # Set flag to indicate we're updating from preset
+            self._updating_from_preset = True
+            try:
+                self.server.state.mpr_window = preset.window
+                self.server.state.mpr_level = preset.level
+
+                # Update the actual MPR views with new window/level
+                self.update_mpr_window_level()
+            finally:
+                # Always clear the flag
+                self._updating_from_preset = False
 
     def update_mpr_rotation(self, **kwargs):
         """Update MPR views when rotation changes."""
@@ -704,13 +832,17 @@ class Logic:
         coronal_slice = getattr(self.server.state, "coronal_slice", 0.5)
         current_frame = getattr(self.server.state, "frame", 0)
 
-        # Get rotation data
+        # Get rotation data - include all visible rotations
         rotation_sequence = getattr(self.server.state, "mpr_rotation_sequence", [])
         rotation_angles = {}
+
+        # Include all visible rotations regardless of position
         for i in range(len(rotation_sequence)):
-            rotation_angles[i] = getattr(
-                self.server.state, f"mpr_rotation_angle_{i}", 0
-            )
+            is_visible = getattr(self.server.state, f"mpr_rotation_visible_{i}", True)
+            if is_visible:
+                rotation_angles[i] = getattr(
+                    self.server.state, f"mpr_rotation_angle_{i}", 0
+                )
 
         # Update slice positions with rotation
         active_volume.update_slice_positions(
@@ -744,7 +876,7 @@ class Logic:
             self.server.state.mpr_rotation_sequence = sequence
 
             # Reset angle states for all removed rotations
-            for i in range(index, 20):
+            for i in range(index, self.scene.max_mpr_rotations):
                 setattr(self.server.state, f"mpr_rotation_angle_{i}", 0)
 
             self.update_mpr_rotation_labels()
@@ -752,8 +884,9 @@ class Logic:
     def reset_mpr_rotations(self):
         """Reset all MPR rotations."""
         self.server.state.mpr_rotation_sequence = []
-        for i in range(20):
+        for i in range(self.scene.max_mpr_rotations):
             setattr(self.server.state, f"mpr_rotation_angle_{i}", 0)
+            setattr(self.server.state, f"mpr_rotation_visible_{i}", True)
         self.update_mpr_rotation_labels()
 
     def update_mpr_rotation_labels(self):
@@ -766,7 +899,7 @@ class Logic:
                 f"{rotation['axis']} ({i + 1})",
             )
         # Clear unused labels
-        for i in range(len(rotation_sequence), 20):
+        for i in range(len(rotation_sequence), self.scene.max_mpr_rotations):
             setattr(self.server.state, f"mpr_rotation_axis_{i}", f"Rotation {i + 1}")
 
     @asynchronous.task

cardio/mesh.py

@@ -3,7 +3,6 @@ import enum
 import logging
 
 # Third Party
-import numpy as np
 import pydantic as pc
 import vtk
 
@@ -50,7 +49,7 @@ class Mesh(Object):
     """Mesh object with subdivision support."""
 
     pattern: str = pc.Field(
-        default="${frame}.obj", description="Filename pattern with $frame placeholder"
+        default="{frame}.obj", description="Filename pattern with $frame placeholder"
     )
     _actors: list[vtk.vtkActor] = pc.PrivateAttr(default_factory=list)
     properties: vtkPropertyConfig = pc.Field(

cardio/object.py

@@ -3,7 +3,6 @@ import functools
 import logging
 import pathlib as pl
 import re
-import string
 
 # Third Party
 import pydantic as pc
@@ -22,6 +21,8 @@ class Object(pc.BaseModel):
     pattern: str | None = pc.Field(
         default=None, description="Filename pattern with ${frame} placeholder"
     )
+    frame_start: pc.NonNegativeInt = 0
+    frame_interval: pc.PositiveInt = 1
     file_paths: list[str] | None = pc.Field(
         default=None, description="Static list of file paths relative to directory"
     )
@@ -54,10 +55,10 @@ class Object(pc.BaseModel):
         if not isinstance(v, str):
             raise ValueError("pattern must be a string")
 
-        if not re.match(r"^[a-zA-Z0-9_\-.${}]+$", v):
+        if not re.match(r"^[a-zA-Z0-9_\-.${}:]+$", v):
             raise ValueError("Pattern contains unsafe characters")
 
-        if "${frame}" not in v and "$frame" not in v:
+        if "frame" not in v:
             raise ValueError("Pattern must contain $frame placeholder")
 
         return v
@@ -78,8 +79,7 @@ class Object(pc.BaseModel):
     def path_for_frame(self, frame: int) -> pl.Path:
         if self.pattern is None:
             raise ValueError("Cannot use path_for_frame with static file_paths")
-        template = string.Template(self.pattern)
-        filename = template.safe_substitute(frame=frame)
+        filename = self.pattern.format(frame=frame)
         return self.directory / filename
 
     @functools.cached_property
@@ -89,13 +89,13 @@ class Object(pc.BaseModel):
             return [self.directory / path for path in self.file_paths]
 
         paths = []
-        frame = 0
+        frame = self.frame_start
         while True:
             path = self.path_for_frame(frame)
             if not path.is_file():
                 break
             paths.append(path)
-            frame += 1
+            frame += self.frame_interval
         return paths
 
     @property

cardio/orientation.py

@@ -0,0 +1,215 @@
+# System
+from enum import Enum
+
+# Third Party
+import numpy as np
+import itk
+
+
+# DICOM LPS canonical orientation vector mappings
+class EulerAxis(Enum):
+    X = "X"
+    Y = "Y"
+    Z = "Z"
+
+
+class AngleUnits(Enum):
+    DEGREES = "degrees"
+    RADIANS = "radians"
+
+
+AXCODE_VECTORS = {
+    "L": (1, 0, 0),
+    "R": (-1, 0, 0),
+    "P": (0, 1, 0),
+    "A": (0, -1, 0),
+    "S": (0, 0, 1),
+    "I": (0, 0, -1),
+}
+
+
+def is_valid_axcode(axcode: str) -> bool:
+    """Validate medical imaging axcode string.
+
+    Valid axcode must have exactly 3 uppercase characters with:
+    - One of L or R (Left/Right)
+    - One of A or P (Anterior/Posterior)
+    - One of S or I (Superior/Inferior)
+    - No repeated characters
+    """
+    if len(axcode) != 3:
+        return False
+
+    if len(set(axcode)) != 3:
+        return False
+
+    has_lr = any(c in axcode for c in "LR")
+    has_ap = any(c in axcode for c in "AP")
+    has_si = any(c in axcode for c in "SI")
+
+    valid_chars = set("LRAPSI")
+    has_only_valid = all(c in valid_chars for c in axcode)
+
+    return has_lr and has_ap and has_si and has_only_valid
+
+
+def is_righthanded_axcode(axcode: str) -> bool:
+    """Check if axcode represents a right-handed coordinate system.
+
+    Right-handed when cross product of first two axes equals third axis.
+    Uses DICOM LPS canonical orientation.
+    """
+    if not is_valid_axcode(axcode):
+        raise ValueError(f"Invalid axcode: {axcode}")
+
+    v1 = np.array(AXCODE_VECTORS[axcode[0]])
+    v2 = np.array(AXCODE_VECTORS[axcode[1]])
+    v3 = np.array(AXCODE_VECTORS[axcode[2]])
+
+    cross = np.cross(v1, v2)
+
+    return np.array_equal(cross, v3)
+
+
+def axcode_transform_matrix(from_axcode: str, to_axcode: str) -> np.ndarray:
+    """Calculate transformation matrix between two coordinate spaces.
+
+    Returns matrix T such that: new_coords = T @ old_coords
+    Uses DICOM LPS canonical orientation for vector mappings.
+    """
+    if not is_valid_axcode(from_axcode):
+        raise ValueError(f"Invalid source axcode: {from_axcode}")
+    if not is_valid_axcode(to_axcode):
+        raise ValueError(f"Invalid target axcode: {to_axcode}")
+
+    # Create basis matrices (each column is a basis vector)
+    from_basis = np.array([AXCODE_VECTORS[c] for c in from_axcode]).T
+    to_basis = np.array([AXCODE_VECTORS[c] for c in to_axcode]).T
+
+    # Transformation matrix: T = to_basis @ from_basis^(-1)
+    return to_basis @ np.linalg.inv(from_basis)
+
+
+def euler_angle_to_rotation_matrix(
+    axis: EulerAxis, angle: float, units: AngleUnits = AngleUnits.DEGREES
+) -> np.ndarray:
+    """Create rotation matrix for given axis and angle.
+
+    Args:
+        axis: Rotation axis (X, Y, or Z)
+        angle: Rotation angle
+        units: Angle units (degrees or radians)
+
+    Returns:
+        3x3 rotation matrix
+    """
+    match units:
+        case AngleUnits.DEGREES:
+            angle_rad = np.radians(angle)
+        case AngleUnits.RADIANS:
+            angle_rad = angle
+
+    cos_a, sin_a = np.cos(angle_rad), np.sin(angle_rad)
+
+    match axis:
+        case EulerAxis.X:
+            return np.array([[1, 0, 0], [0, cos_a, -sin_a], [0, sin_a, cos_a]])
+        case EulerAxis.Y:
+            return np.array([[cos_a, 0, sin_a], [0, 1, 0], [-sin_a, 0, cos_a]])
+        case EulerAxis.Z:
+            return np.array([[cos_a, -sin_a, 0], [sin_a, cos_a, 0], [0, 0, 1]])
+
+
+def is_axis_aligned(image) -> bool:
+    """Check if ITK image orientation is axis-aligned.
+
+    An axis-aligned image has a direction matrix where:
+    - Each column has exactly one non-zero entry
+    - Non-zero entries are ±1
+
+    Args:
+        image: ITK image object
+
+    Returns:
+        True if image is axis-aligned, False otherwise
+    """
+    direction = itk.array_from_matrix(image.GetDirection())
+
+    # Check each column has exactly one non-zero entry
+    for col in range(direction.shape[1]):
+        non_zero_count = np.count_nonzero(direction[:, col])
+        if non_zero_count != 1:
+            return False
+
+    # Check non-zero entries are ±1
+    non_zero_values = direction[direction != 0]
+    if not np.allclose(np.abs(non_zero_values), 1.0):
+        return False
+
+    return True
+
+
+def reset_direction(image):
+    """Reset image direction to identity matrix, preserving physical extent."""
+    assert is_axis_aligned(image), "Input image must be axis-aligned"
+
+    origin = np.array(image.GetOrigin())
+    spacing = np.array(image.GetSpacing())
+    direction = itk.array_from_matrix(image.GetDirection())
+    size = np.array(image.GetLargestPossibleRegion().GetSize())
+    pixel_array = itk.array_from_image(image)
+
+    permutation = []
+    flips = []
+
+    for col in range(3):
+        row = np.nonzero(direction[:, col])[0][0]
+        permutation.append(row)
+        flips.append(direction[row, col] < 0)
+
+    array_permutation = [2 - p for p in reversed(permutation)]
+    pixel_array = np.transpose(pixel_array, array_permutation)
+
+    for i, should_flip in enumerate(reversed(flips)):
+        if should_flip:
+            pixel_array = np.flip(pixel_array, axis=i)
+
+    new_spacing = spacing[permutation]
+
+    adjusted_origin = origin.copy()
+    for i, should_flip in enumerate(flips):
+        if should_flip:
+            image_axis = permutation[i]
+            extent_vector = (
+                direction[:, image_axis] * (size[image_axis] - 1) * spacing[image_axis]
+            )
+            adjusted_origin += extent_vector
+
+    new_origin = adjusted_origin[permutation]
+
+    output = itk.image_from_array(pixel_array)
+    output.SetOrigin(new_origin)
+    output.SetSpacing(new_spacing)
+
+    return output
+
+
+def create_vtk_reslice_matrix(transform_3x3, origin):
+    """Create 4x4 VTK reslice matrix from 3x3 transform and origin.
+
+    Args:
+        transform_3x3: 3x3 coordinate transformation matrix
+        origin: 3-element origin position
+
+    Returns:
+        vtk.vtkMatrix4x4 for use with VTK reslice operations
+    """
+    import vtk
+
+    matrix = vtk.vtkMatrix4x4()
+    for i in range(3):
+        for j in range(3):
+            matrix.SetElement(i, j, transform_3x3[i, j])
+        matrix.SetElement(i, 3, origin[i])
+    matrix.SetElement(3, 3, 1.0)
+    return matrix