cardio 2023.1.2__py3-none-any.whl → 2025.8.0__py3-none-any.whl

cardio/mesh.py

@@ -1,39 +1,259 @@
+# System
+import enum
 import logging
-import os
 
-from vtkmodules.vtkIOGeometry import vtkOBJReader
-from vtkmodules.vtkRenderingCore import vtkActor, vtkPolyDataMapper, vtkRenderer
+# Third Party
+import numpy as np
+import pydantic as pc
+import vtk
 
-from . import Object
+# Internal
+from .object import Object
+from .property_config import Representation, vtkPropertyConfig
+
+
+class SurfaceType(enum.Enum):
+    """Surface coloring types for mesh rendering."""
+
+    SOLID = "solid"
+    SQUEEZ = "squeez"
+
+
+def apply_elementwise(
+    array1: vtk.vtkFloatArray, array2: vtk.vtkFloatArray, func, name: str = "Result"
+) -> vtk.vtkFloatArray:
+    if array1.GetNumberOfTuples() != array2.GetNumberOfTuples():
+        raise ValueError(
+            f"Array lengths must match: {array1.GetNumberOfTuples()} != {array2.GetNumberOfTuples()}"
+        )
+
+    result_array = vtk.vtkFloatArray()
+    result_array.SetName(name)
+    result_array.SetNumberOfComponents(1)
+
+    for i in range(array1.GetNumberOfTuples()):
+        val1 = array1.GetValue(i)
+        val2 = array2.GetValue(i)
+        result = func(val1, val2)
+        result_array.InsertNextValue(result)
+
+    return result_array
+
+
+def calculate_squeez(current_area: float, ref_area: float) -> float:
+    if ref_area > 0:
+        return (current_area / ref_area) ** 0.5
+    return 1.0
 
 
 class Mesh(Object):
-    def __init__(self, cfg: str, renderer: vtkRenderer):
-        super().__init__(cfg, renderer)
-        self.actors: list[vtkActor] = []
+    """Mesh object with subdivision support."""
 
-        self.color_r: float = cfg["color_r"]
-        self.color_g: float = cfg["color_g"]
-        self.color_b: float = cfg["color_b"]
+    pattern: str = pc.Field(
+        default="${frame}.obj", description="Filename pattern with $frame placeholder"
+    )
+    _actors: list[vtk.vtkActor] = pc.PrivateAttr(default_factory=list)
+    properties: vtkPropertyConfig = pc.Field(
+        default_factory=vtkPropertyConfig, description="Property configuration"
+    )
+    loop_subdivision_iterations: int = pc.Field(ge=0, le=5, default=0)
+    surface_type: SurfaceType = pc.Field(default=SurfaceType.SOLID)
+    ctf_min: float = pc.Field(ge=0.0, default=0.7)
+    ctf_max: float = pc.Field(ge=0.0, default=1.3)
 
-        frame = 0
-        while os.path.exists(self.path_for_frame(frame)):
+    @pc.model_validator(mode="after")
+    def initialize_mesh(self):
+        # Pass 1: Load all frames and determine topology consistency
+        frame_data = []
+        for frame, path in enumerate(self.path_list):
             logging.info(f"{self.label}: Loading frame {frame}.")
-            reader = vtkOBJReader()
-            mapper = vtkPolyDataMapper()
-            actor = vtkActor()
-            reader.SetFileName(self.path_for_frame(frame))
-            mapper.SetInputConnection(reader.GetOutputPort())
-            actor.SetMapper(mapper)
+            reader = vtk.vtkOBJReader()
+            reader.SetFileName(path)
             reader.Update()
-            self.actors += [actor]
-            frame += 1
-
-    def setup_pipeline(self, frame: int):
-        for a in self.actors:
-            self.renderer.AddActor(a)
-            a.SetVisibility(False)
-            a.GetProperty().SetColor(self.color_r, self.color_g, self.color_b)
-        if self.visible:
-            self.actors[frame].SetVisibility(True)
-        self.renderer.ResetCamera()
+
+            if self.loop_subdivision_iterations > 0:
+                subdivision_filter = vtk.vtkLoopSubdivisionFilter()
+                subdivision_filter.SetInputConnection(reader.GetOutputPort())
+                subdivision_filter.SetNumberOfSubdivisions(
+                    self.loop_subdivision_iterations
+                )
+                subdivision_filter.Update()
+                polydata = subdivision_filter.GetOutput()
+            else:
+                polydata = reader.GetOutput()
+
+            if self.properties.representation == Representation.Surface:
+                polydata = self.calculate_mesh_areas(polydata)
+
+            frame_data.append(polydata)
+
+        consistent_topology = self._should_calculate_squeez(frame_data)
+
+        # Pass 2: Create actors with appropriate coloring
+        for frame, polydata in enumerate(frame_data):
+            mapper = self._setup_coloring(
+                polydata, frame_data, frame, consistent_topology
+            )
+
+            actor = vtk.vtkActor()
+            actor.SetMapper(mapper)
+
+            self._actors.append(actor)
+
+        return self
+
+    @property
+    def actors(self) -> list[vtk.vtkActor]:
+        return self._actors
+
+    def _setup_coloring(self, polydata, frame_data, frame, consistent_topology):
+        """Setup mesh coloring based on surface_type with smart fallback."""
+        if self.surface_type == SurfaceType.SQUEEZ:
+            if self._can_use_squeez_coloring(consistent_topology):
+                return self._setup_squeez_coloring(polydata, frame_data, frame)
+            else:
+                self._log_squeez_fallback()
+                return self._setup_solid_coloring(polydata)
+        else:  # SurfaceType.SOLID
+            return self._setup_solid_coloring(polydata)
+
+    def _can_use_squeez_coloring(self, consistent_topology):
+        """Check if SQUEEZ coloring is possible."""
+        return (
+            self.properties.representation == Representation.Surface
+            and consistent_topology
+        )
+
+    def _log_squeez_fallback(self):
+        """Log warning when falling back from SQUEEZ to solid coloring."""
+        if self.properties.representation != Representation.Surface:
+            logging.warning(
+                f"SQUEEZ coloring requested for {self.label} but representation is not Surface, falling back to solid coloring"
+            )
+        else:
+            logging.warning(
+                f"SQUEEZ coloring requested for {self.label} but topology inconsistent across frames, falling back to solid coloring"
+            )
+
+    def _setup_solid_coloring(self, polydata):
+        """Setup solid coloring using VTK property colors."""
+        mapper = vtk.vtkPolyDataMapper()
+        mapper.SetInputData(polydata)
+        mapper.ScalarVisibilityOff()
+        return mapper
+
+    def _setup_squeez_coloring(self, polydata, frame_data, frame):
+        """Setup SQUEEZ coloring with scalar data."""
+        ref_quality_array = frame_data[0].GetCellData().GetArray("Area")
+        if frame == 0:
+            ratio_array = apply_elementwise(
+                ref_quality_array, ref_quality_array, lambda x, y: 1.0, "SQUEEZ"
+            )
+        else:
+            current_quality_array = polydata.GetCellData().GetArray("Area")
+            ratio_array = apply_elementwise(
+                current_quality_array,
+                ref_quality_array,
+                calculate_squeez,
+                "SQUEEZ",
+            )
+        polydata.GetCellData().AddArray(ratio_array)
+        polydata.GetCellData().SetActiveScalars("SQUEEZ")
+
+        mapper = vtk.vtkPolyDataMapper()
+        mapper.SetInputData(polydata)
+        mapper = self.setup_scalar_coloring(mapper)
+        return mapper
+
+    def color_transfer_function(self):
+        ctf = vtk.vtkColorTransferFunction()
+        ctf.AddRGBPoint(0.7, 0.0, 0.0, 1.0)
+        ctf.AddRGBPoint(1.0, 1.0, 0.0, 0.0)
+        ctf.AddRGBPoint(1.3, 1.0, 1.0, 0.0)
+        return ctf
+
+    def setup_scalar_coloring(self, mapper):
+        mapper.SetColorModeToMapScalars()
+        mapper.SetScalarModeToUseCellData()
+        mapper.SetLookupTable(self.color_transfer_function())
+        mapper.SetScalarRange(self.ctf_min, self.ctf_max)
+        mapper.ScalarVisibilityOn()
+        mapper.SetInterpolateScalarsBeforeMapping(False)
+        return mapper
+
+    def calculate_mesh_areas(self, polydata):
+        """Calculate area of each triangle/cell in the mesh using VTK mesh quality."""
+        # Ensure we have triangles
+        triangle_filter = vtk.vtkTriangleFilter()
+        triangle_filter.SetInputData(polydata)
+        triangle_filter.Update()
+        triangulated = triangle_filter.GetOutput()
+
+        # Use VTK mesh quality to calculate areas
+        mesh_quality = vtk.vtkMeshQuality()
+        mesh_quality.SetInputData(triangulated)
+        mesh_quality.SetTriangleQualityMeasureToArea()
+        mesh_quality.SetQuadQualityMeasureToArea()
+        mesh_quality.SaveCellQualityOn()
+        mesh_quality.Update()
+
+        quality_output = mesh_quality.GetOutput()
+        quality_array = quality_output.GetCellData().GetArray("Quality")
+        quality_array.SetName("Area")
+
+        return quality_output
+
+    def _should_calculate_squeez(self, frame_data: list) -> bool:
+        if (
+            self.properties.representation != Representation.Surface
+            or len(frame_data) <= 1
+        ):
+            return False
+
+        reference_frame = frame_data[0]
+        ref_area_array = reference_frame.GetCellData().GetArray("Area")
+
+        if ref_area_array is None:
+            return False
+
+        ref_num_cells = reference_frame.GetNumberOfCells()
+        ref_num_points = reference_frame.GetNumberOfPoints()
+        ref_num_areas = ref_area_array.GetNumberOfTuples()
+
+        # Check all frames have identical topology
+        for polydata in frame_data[1:]:
+            area_array = polydata.GetCellData().GetArray("Area")
+            if (
+                area_array is None
+                or polydata.GetNumberOfCells() != ref_num_cells
+                or polydata.GetNumberOfPoints() != ref_num_points
+                or area_array.GetNumberOfTuples() != ref_num_areas
+            ):
+                return False
+
+        return True
+
+    def configure_actors(self):
+        """Configure actor properties without adding to renderer."""
+        for actor in self._actors:
+            actor.SetVisibility(False)
+            actor.SetProperty(self.properties.vtk_property)
+
+        # Apply flat shading for SQUEEZ coloring
+        if self._is_using_squeez_coloring():
+            for actor in self._actors:
+                actor.GetProperty().SetInterpolationToFlat()
+
+    def _is_using_squeez_coloring(self):
+        """Check if SQUEEZ coloring is actually being used (not fell back to solid)."""
+        if self.surface_type != SurfaceType.SQUEEZ:
+            return False
+
+        # Check if any actor has SQUEEZ scalar data
+        for actor in self._actors:
+            mapper = actor.GetMapper()
+            if mapper.GetInput():
+                squeez_array = mapper.GetInput().GetCellData().GetArray("SQUEEZ")
+                if squeez_array is not None:
+                    return True
+        return False

cardio/object.py

@@ -1,13 +1,186 @@
-from vtkmodules.vtkRenderingCore import vtkRenderer
+# System
+import functools
+import logging
+import pathlib as pl
+import re
+import string
 
+# Third Party
+import pydantic as pc
+import vtk
 
-class Object:
-    def __init__(self, cfg: str, renderer: vtkRenderer):
-        self.label: str = cfg["label"]
-        self.directory: str = cfg["directory"]
-        self.suffix: str = cfg["suffix"]
-        self.visible: bool = cfg["visible"]
-        self.renderer = renderer
+from .utils import calculate_combined_bounds
 
-    def path_for_frame(self, frame: int) -> str:
-        return f"{self.directory}/{frame}.{self.suffix}"
+
+class Object(pc.BaseModel):
+    """Base class for renderable objects with validated configuration."""
+
+    model_config = pc.ConfigDict(arbitrary_types_allowed=True, frozen=True)
+
+    label: str = pc.Field(description="Object identifier (only [a-zA-Z0-9_] allowed)")
+    directory: pl.Path = pc.Field(description="Directory containing object files")
+    pattern: str | None = pc.Field(
+        default=None, description="Filename pattern with ${frame} placeholder"
+    )
+    file_paths: list[str] | None = pc.Field(
+        default=None, description="Static list of file paths relative to directory"
+    )
+    visible: bool = pc.Field(
+        default=True, description="Whether object is initially visible"
+    )
+    clipping_enabled: bool = pc.Field(default=False)
+
+    @pc.field_validator("label")
+    @classmethod
+    def validate_label(cls, v: str) -> str:
+        """Validate that label contains only letters, numbers, and underscores."""
+        if not isinstance(v, str):
+            raise ValueError("label must be a string")
+
+        if not re.match(r"^[a-zA-Z0-9_]+$", v):
+            raise ValueError(
+                f"label '{v}' contains invalid characters. "
+                "Labels must contain only letters, numbers, and underscores."
+            )
+
+        return v
+
+    @pc.field_validator("pattern")
+    @classmethod
+    def validate_pattern(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+
+        if not isinstance(v, str):
+            raise ValueError("pattern must be a string")
+
+        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:
+            raise ValueError("Pattern must contain $frame placeholder")
+
+        return v
+
+    @pc.model_validator(mode="after")
+    def validate_pattern_or_file_paths(self):
+        if self.pattern is None and self.file_paths is None:
+            raise ValueError("Either pattern or file_paths must be provided")
+        if self.pattern is not None and self.file_paths is not None:
+            logging.info("Both pattern and file_paths specified; using file_paths.")
+
+        # Validate all paths for traversal attacks and file existence
+        for path in self.path_list:
+            if not path.resolve().is_relative_to(self.directory.resolve()):
+                raise ValueError(
+                    f"Path {path} would access files outside base directory"
+                )
+            if not path.is_file():
+                raise ValueError(f"File does not exist: {path}")
+
+        return self
+
+    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)
+        return self.directory / filename
+
+    @functools.cached_property
+    def path_list(self) -> list[pl.Path]:
+        """Return list of file paths, using static paths if provided, otherwise dynamic pattern-based paths."""
+        if self.file_paths is not None:
+            return [self.directory / path for path in self.file_paths]
+
+        paths = []
+        frame = 0
+        while True:
+            path = self.path_for_frame(frame)
+            if not path.is_file():
+                break
+            paths.append(path)
+            frame += 1
+        return paths
+
+    @property
+    def combined_bounds(self) -> list[float]:
+        """Get combined bounds encompassing all actors."""
+        if not hasattr(self, "actors") or not self.actors:
+            return [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+
+        return calculate_combined_bounds(self.actors)
+
+    @functools.cached_property
+    def clipping_planes(self) -> vtk.vtkPlanes:
+        """Generate clipping planes based on combined bounds of all actors."""
+        if not hasattr(self, "actors") or not self.actors:
+            return None
+
+        bounds = self.combined_bounds
+        planes = vtk.vtkPlanes()
+        self._create_clipping_planes_from_bounds(planes, bounds)
+        return planes
+
+    def _create_clipping_planes_from_bounds(self, planes: vtk.vtkPlanes, bounds):
+        """Create 6 clipping planes from box bounds."""
+
+        # Create 6 planes for the box faces
+        normals = [
+            [1, 0, 0],
+            [-1, 0, 0],  # x-min, x-max
+            [0, 1, 0],
+            [0, -1, 0],  # y-min, y-max
+            [0, 0, 1],
+            [0, 0, -1],  # z-min, z-max
+        ]
+        origins = [
+            [bounds[0], 0, 0],
+            [bounds[1], 0, 0],  # x-min, x-max
+            [0, bounds[2], 0],
+            [0, bounds[3], 0],  # y-min, y-max
+            [0, 0, bounds[4]],
+            [0, 0, bounds[5]],  # z-min, z-max
+        ]
+
+        points = vtk.vtkPoints()
+        norms = vtk.vtkDoubleArray()
+        norms.SetNumberOfComponents(3)
+        norms.SetName("Normals")
+
+        for normal, origin in zip(normals, origins):
+            points.InsertNextPoint(origin)
+            norms.InsertNextTuple(normal)
+
+        planes.SetPoints(points)
+        planes.SetNormals(norms)
+
+    def toggle_clipping(self, enabled: bool):
+        """Enable or disable clipping for all actors."""
+        if not hasattr(self, "actors"):
+            return
+
+        if enabled and self.clipping_planes:
+            # Apply clipping to all actors
+            for actor in self.actors:
+                mapper = actor.GetMapper()
+                mapper.SetClippingPlanes(self.clipping_planes)
+        else:
+            # Remove clipping from all actors
+            for actor in self.actors:
+                mapper = actor.GetMapper()
+                mapper.RemoveAllClippingPlanes()
+
+    def update_clipping_bounds(self, bounds):
+        """Update clipping bounds from UI controls."""
+        if not self.clipping_planes:
+            return
+
+        # Update clipping planes with new bounds
+        self._create_clipping_planes_from_bounds(self.clipping_planes, bounds)
+
+        # Apply to all actors if clipping is enabled
+        if self.clipping_enabled:
+            for actor in self.actors:
+                mapper = actor.GetMapper()
+                mapper.SetClippingPlanes(self.clipping_planes)

cardio/property_config.py

@@ -0,0 +1,56 @@
+# System
+import enum
+import functools
+
+# Third Party
+import pydantic as pc
+import vtk
+
+# Internal
+from .types import RGBColor, ScalarComponent
+
+
+class Representation(enum.IntEnum):
+    """Mesh representation modes for VTK rendering."""
+
+    Points = 0
+    Wireframe = 1
+    Surface = 2
+
+
+class Interpolation(enum.IntEnum):
+    """Mesh interpolation modes for VTK rendering."""
+
+    Flat = 0
+    Gouraud = 1
+    Phong = 2
+    PBR = 3
+
+
+class vtkPropertyConfig(pc.BaseModel):
+    """Configuration for mesh rendering properties."""
+
+    representation: Representation = pc.Field(
+        default=Representation.Surface, description="Rendering representation mode"
+    )
+    color: RGBColor = (1.0, 1.0, 1.0)
+    edge_visibility: bool = pc.Field(default=False, description="Show edges")
+    vertex_visibility: bool = pc.Field(default=False, description="Show vertices")
+    shading: bool = pc.Field(default=True, description="Enable shading")
+    interpolation: Interpolation = pc.Field(
+        default=Interpolation.Gouraud, description="Interpolation mode"
+    )
+    opacity: ScalarComponent = 1.0
+
+    @functools.cached_property
+    def vtk_property(self) -> vtk.vtkProperty:
+        """Create a fully configured VTK property from this configuration."""
+        _vtk_property = vtk.vtkProperty()
+        _vtk_property.SetRepresentation(self.representation.value)
+        _vtk_property.SetColor(*self.color)
+        _vtk_property.SetEdgeVisibility(self.edge_visibility)
+        _vtk_property.SetVertexVisibility(self.vertex_visibility)
+        _vtk_property.SetShading(self.shading)
+        _vtk_property.SetInterpolation(self.interpolation.value)
+        _vtk_property.SetOpacity(self.opacity)
+        return _vtk_property