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

cardio/mesh.py

@@ -1,12 +1,9 @@
-# System
 import enum
 import logging
 
-# Third Party
 import pydantic as pc
 import vtk
 
-# Internal
 from .object import Object
 from .property_config import Representation, vtkPropertyConfig
 

cardio/object.py

@@ -1,10 +1,8 @@
-# System
 import functools
 import logging
 import pathlib as pl
 import re
 
-# Third Party
 import pydantic as pc
 import vtk
 

cardio/orientation.py

@@ -1,9 +1,7 @@
-# System
 from enum import Enum
 
-# Third Party
-import numpy as np
 import itk
+import numpy as np
 
 
 # DICOM LPS canonical orientation vector mappings
@@ -13,6 +11,11 @@ class EulerAxis(Enum):
     Z = "Z"
 
 
+class AxisConvention(Enum):
+    ITK = "itk"  # X=Left, Y=Posterior, Z=Superior
+    ROMA = "roma"  # X=Superior, Y=Posterior, Z=Left
+
+
 class AngleUnits(Enum):
     DEGREES = "degrees"
     RADIANS = "radians"

cardio/piecewise_function.py

@@ -1,8 +1,6 @@
-# Third Party
 import pydantic as pc
 import vtk
 
-# Internal
 from .types import ScalarComponent
 
 

cardio/property_config.py

@@ -1,12 +1,9 @@
-# System
 import enum
 import functools
 
-# Third Party
 import pydantic as pc
 import vtk
 
-# Internal
 from .types import RGBColor, ScalarComponent
 
 

cardio/rotation.py

@@ -0,0 +1,211 @@
+# System
+import datetime as dt
+import pathlib as pl
+import typing as ty
+
+# Third Party
+import numpy as np
+import pydantic as pc
+import tomlkit as tk
+
+# Internal
+from .orientation import AngleUnits, AxisConvention
+
+
+class RotationStep(pc.BaseModel):
+    """Single rotation step (stored in ITK convention, radians)."""
+
+    axes: ty.Literal["X", "Y", "Z"]
+    angle: float = 0.0
+    visible: bool = True
+    name: str = ""
+    name_editable: bool = True
+    deletable: bool = True
+
+    @pc.model_validator(mode="before")
+    @classmethod
+    def handle_legacy_format(cls, data):
+        """Handle legacy 'angles' list format and 'axis' field."""
+        if isinstance(data, dict):
+            if "angles" in data and "angle" not in data:
+                angles = data["angles"]
+                if isinstance(angles, list) and len(angles) > 0:
+                    data["angle"] = angles[0]
+                else:
+                    data["angle"] = angles
+            if "axis" in data and "axes" not in data:
+                data["axes"] = data["axis"]
+        return data
+
+    def to_convention(
+        self, convention: AxisConvention, units: AngleUnits
+    ) -> tuple[str, float]:
+        """Convert to target convention/units for serialization."""
+        axis = self.axes
+        angle = self.angle
+
+        if convention == AxisConvention.ROMA:
+            axis = {"X": "Z", "Y": "Y", "Z": "X"}[axis]
+            angle = -angle
+
+        if units == AngleUnits.DEGREES:
+            angle = np.degrees(angle)
+
+        return axis, angle
+
+    @classmethod
+    def from_convention(
+        cls,
+        axes: str,
+        angle: float,
+        convention: AxisConvention,
+        units: AngleUnits,
+        **kwargs,
+    ) -> "RotationStep":
+        """Create from target convention/units (for deserialization)."""
+        if units == AngleUnits.DEGREES:
+            angle = np.radians(angle)
+
+        if convention == AxisConvention.ROMA:
+            axes = {"X": "Z", "Y": "Y", "Z": "X"}[axes]
+            angle = -angle
+
+        return cls(axes=axes, angle=angle, **kwargs)
+
+
+class RotationMetadata(pc.BaseModel):
+    """Metadata for TOML files."""
+
+    coordinate_system: ty.Literal["LPS"] = "LPS"
+    axis_convention: AxisConvention = AxisConvention.ITK
+    units: AngleUnits = AngleUnits.RADIANS
+    timestamp: str = pc.Field(default_factory=lambda: dt.datetime.now().isoformat())
+    volume_label: str = ""
+
+
+class RotationSequence(pc.BaseModel):
+    """Complete rotation sequence (stored in ITK convention, radians)."""
+
+    model_config = pc.ConfigDict(frozen=False)
+
+    metadata: RotationMetadata = pc.Field(default_factory=RotationMetadata)
+    angles_list: list[RotationStep] = pc.Field(default_factory=list)
+
+    @pc.field_validator("angles_list", mode="before")
+    @classmethod
+    def convert_legacy_list(cls, v):
+        """Convert legacy list of dicts to list of RotationStep."""
+        if isinstance(v, list) and len(v) > 0 and isinstance(v[0], dict):
+            return [RotationStep(**item) for item in v]
+        return v
+
+    def to_dict_for_ui(self) -> dict:
+        """Convert to UI format (always ITK/radians internally).
+
+        Note: UI expects 'angles' as a list for backward compatibility.
+        """
+        return {
+            "angles_list": [
+                {
+                    "axes": step.axes,
+                    "angles": [step.angle],
+                    "visible": step.visible,
+                    "name": step.name,
+                    "name_editable": step.name_editable,
+                    "deletable": step.deletable,
+                }
+                for step in self.angles_list
+            ]
+        }
+
+    @classmethod
+    def from_ui_dict(cls, data: dict, volume_label: str = "") -> "RotationSequence":
+        """Create from UI format (assumes ITK/radians)."""
+        angles_list = [RotationStep(**step) for step in data.get("angles_list", [])]
+        metadata = RotationMetadata(volume_label=volume_label)
+        return cls(metadata=metadata, angles_list=angles_list)
+
+    def to_toml(
+        self, target_convention: AxisConvention, target_units: AngleUnits
+    ) -> str:
+        """Serialize to TOML with conversions."""
+        doc = tk.document()
+
+        metadata_table = tk.table()
+        metadata_table["coordinate_system"] = self.metadata.coordinate_system
+        metadata_table["axis_convention"] = target_convention.value
+        metadata_table["units"] = target_units.value
+        metadata_table["timestamp"] = self.metadata.timestamp
+        metadata_table["volume_label"] = self.metadata.volume_label
+        doc["metadata"] = metadata_table
+
+        rotations_array = tk.aot()
+        for step in self.angles_list:
+            rotation = tk.table()
+            converted_axis, converted_angle = step.to_convention(
+                target_convention, target_units
+            )
+            rotation["axes"] = converted_axis
+            rotation["angle"] = converted_angle
+            rotation["visible"] = step.visible
+            rotation["name"] = step.name
+            rotation["name_editable"] = step.name_editable
+            rotation["deletable"] = step.deletable
+            rotations_array.append(rotation)
+
+        doc["angles_list"] = rotations_array
+
+        return tk.dumps(doc)
+
+    @classmethod
+    def from_toml(cls, toml_content: str) -> "RotationSequence":
+        """Deserialize from TOML with conversions."""
+        doc = tk.loads(toml_content)
+
+        metadata_dict = doc.get("metadata", {})
+        convention = AxisConvention(metadata_dict.get("axis_convention", "itk"))
+        units = AngleUnits(metadata_dict.get("units", "radians"))
+
+        metadata = RotationMetadata(
+            coordinate_system=metadata_dict.get("coordinate_system", "LPS"),
+            axis_convention=convention,
+            units=units,
+            timestamp=metadata_dict.get("timestamp", dt.datetime.now().isoformat()),
+            volume_label=metadata_dict.get("volume_label", ""),
+        )
+
+        angles_list_data = doc.get("angles_list", [])
+        angles_list = []
+        for item in angles_list_data:
+            axes = item.get("axes", "X")
+            angle = item.get("angle", 0.0)
+            step = RotationStep.from_convention(
+                axes=axes,
+                angle=angle,
+                convention=convention,
+                units=units,
+                visible=item.get("visible", True),
+                name=item.get("name", ""),
+                name_editable=item.get("name_editable", True),
+                deletable=item.get("deletable", True),
+            )
+            angles_list.append(step)
+
+        return cls(metadata=metadata, angles_list=angles_list)
+
+    @classmethod
+    def from_file(cls, path: pl.Path) -> "RotationSequence":
+        """Load from TOML file."""
+        with open(path, "r") as f:
+            return cls.from_toml(f.read())
+
+    def to_file(
+        self,
+        path: pl.Path,
+        target_convention: AxisConvention,
+        target_units: AngleUnits,
+    ):
+        """Save to TOML file."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            f.write(self.to_toml(target_convention, target_units))

cardio/scene.py

@@ -1,19 +1,17 @@
-# System
 import logging
 import pathlib as pl
 import typing as ty
 
-# Third Party
 import numpy as np
 import pydantic as pc
 import pydantic_settings as ps
 import vtk
 
-# Internal
 from .mesh import Mesh
+from .orientation import AngleUnits, AxisConvention
+from .rotation import RotationSequence
 from .segmentation import Segmentation
 from .types import RGBColor
-from .utils import AngleUnit
 from .volume import Volume
 
 MeshListAdapter = pc.TypeAdapter(list[Mesh])
@@ -107,24 +105,16 @@ class Scene(ps.BaseSettings):
     volumes: VolumeList = pc.Field(default_factory=list)
     segmentations: SegmentationList = pc.Field(default_factory=list)
     mpr_enabled: bool = pc.Field(
-        default=False,
+        default=True,
         description="Enable multi-planar reconstruction (MPR) mode with quad-view layout",
     )
     active_volume_label: str = pc.Field(
         default="",
         description="Label of the volume to use for multi-planar reconstruction",
     )
-    axial_slice: float = pc.Field(
-        default=0.0,
-        description="Axial slice position in physical coordinates (LAS Z axis)",
-    )
-    sagittal_slice: float = pc.Field(
-        default=0.0,
-        description="Sagittal slice position in physical coordinates (LAS X axis)",
-    )
-    coronal_slice: float = pc.Field(
-        default=0.0,
-        description="Coronal slice position in physical coordinates (LAS Y axis)",
+    mpr_origin: list = pc.Field(
+        default_factory=lambda: [0.0, 0.0, 0.0],
+        description="MPR origin position [x, y, z] in LPS coordinates",
     )
     mpr_window: float = pc.Field(
         default=800.0, description="Window width for MPR image display"
@@ -135,20 +125,42 @@ class Scene(ps.BaseSettings):
     mpr_window_level_preset: int = pc.Field(
         default=7, description="Window/level preset key for MPR views"
     )
-    mpr_rotation_sequence: list = pc.Field(
-        default_factory=list,
-        description="Dynamic rotation sequence for MPR views - list of rotation steps",
+    mpr_rotation_sequence: RotationSequence = pc.Field(
+        default_factory=RotationSequence,
+        description="Dynamic rotation sequence for MPR views",
+    )
+    mpr_rotation_file: pl.Path | None = pc.Field(
+        default=None,
+        description="Path to TOML file containing rotation configuration to load",
     )
     max_mpr_rotations: int = pc.Field(
         default=20,
         description="Maximum number of MPR rotations supported",
     )
-    angle_units: AngleUnit = pc.Field(
-        default=AngleUnit.DEGREES,
+    angle_units: AngleUnits = pc.Field(
+        default=AngleUnits.RADIANS,
         description="Units for angle measurements in rotation serialization",
     )
     coordinate_system: str = pc.Field(
-        default="LAS", description="Coordinate system orientation (e.g., LAS, RAS, LPS)"
+        default="LPS", description="Coordinate system orientation (e.g., LPS, RAS, LAS)"
+    )
+    axis_convention: AxisConvention = pc.Field(
+        default=AxisConvention.ITK,
+        description="Axis convention for saved rotations (ITK: X=L,Y=P,Z=S; Roma: X=S,Y=P,Z=L)",
+    )
+    mpr_crosshairs_enabled: bool = pc.Field(
+        default=True, description="Show crosshair lines indicating slice intersections"
+    )
+    mpr_crosshair_colors: dict = pc.Field(
+        default_factory=lambda: {
+            "axial": (0.0, 0.5, 1.0),
+            "sagittal": (1.0, 0.3, 0.3),
+            "coronal": (0.3, 1.0, 0.3),
+        },
+        description="RGB colors for crosshair lines (keyed by view name)",
+    )
+    mpr_crosshair_width: float = pc.Field(
+        default=1.5, description="Line width for crosshair lines"
     )
 
     # Field validators for JSON string inputs
@@ -173,6 +185,23 @@ class Scene(ps.BaseSettings):
             return SegmentationListAdapter.validate_json(v)
         return v
 
+    @pc.model_validator(mode="after")
+    def load_rotation_file(self):
+        """Load rotation sequence from TOML file if specified."""
+        if self.mpr_rotation_file is not None and self.mpr_rotation_file.exists():
+            self.mpr_rotation_sequence = RotationSequence.from_file(
+                self.mpr_rotation_file
+            )
+            if (
+                not self.active_volume_label
+                and self.mpr_rotation_sequence.metadata.volume_label
+            ):
+                self.active_volume_label = (
+                    self.mpr_rotation_sequence.metadata.volume_label
+                )
+
+        return self
+
     # VTK objects as private attributes
     _renderer: vtk.vtkRenderer = pc.PrivateAttr(default_factory=vtk.vtkRenderer)
     _renderWindow: vtk.vtkRenderWindow = pc.PrivateAttr(

cardio/segmentation.py

@@ -1,17 +1,14 @@
-# System
 import logging
 
-# Third Party
 import itk
 import numpy as np
 import pydantic as pc
 import vtk
 
-# Internal
+from .object import Object
 from .orientation import (
     reset_direction,
 )
-from .object import Object
 from .property_config import vtkPropertyConfig
 
 

cardio/transfer_function_pair.py

@@ -1,8 +1,6 @@
-# Third Party
 import pydantic as pc
 import vtk
 
-# Internal
 from .color_transfer_function import ColorTransferFunctionConfig
 from .piecewise_function import PiecewiseFunctionConfig
 

cardio/types.py

@@ -1,7 +1,5 @@
-# System
 import typing
 
-# Third Party
 import pydantic as pc
 
 ScalarComponent: typing.TypeAlias = typing.Annotated[