bone-cutting-plane-visualization 0.1.0__py3-none-any.whl

bone_cutting_plane_visualization/__init__.py

@@ -0,0 +1,61 @@
+"""Standalone data contracts and VTK rendering for bone cutting-plane plans."""
+
+from .classification import classify_regions
+from .data import (
+    LabeledVolume,
+    RegionClassificationVolume,
+    ResectionPlanData,
+    SelectedCuttingPlanes,
+    TumorSafetyMarginData,
+    VolumeGeometry,
+)
+from .geometry import plane_box_intersection
+from .ubd import (
+    IncompleteResectionPlanError,
+    load_labeled_volume,
+    load_resection_plan,
+    save_resection_plan,
+)
+from .visualization import (
+    BoneTumorVisualizer,
+    MeshLayer,
+    PatientOrientationCube,
+    PolygonLayer,
+    SurfaceLayer,
+    VisualizationModel,
+    VisualizationScene,
+    patient_orientation_cube,
+    resection_boundary,
+    visualize_bone_and_tumor,
+    visualize_labeled_volume,
+    visualize_resection,
+    visualize_tumor_convex_hull,
+)
+
+__all__ = [
+    "BoneTumorVisualizer",
+    "IncompleteResectionPlanError",
+    "LabeledVolume",
+    "MeshLayer",
+    "PatientOrientationCube",
+    "PolygonLayer",
+    "RegionClassificationVolume",
+    "ResectionPlanData",
+    "SelectedCuttingPlanes",
+    "SurfaceLayer",
+    "TumorSafetyMarginData",
+    "VisualizationModel",
+    "VisualizationScene",
+    "VolumeGeometry",
+    "classify_regions",
+    "load_labeled_volume",
+    "load_resection_plan",
+    "patient_orientation_cube",
+    "plane_box_intersection",
+    "resection_boundary",
+    "save_resection_plan",
+    "visualize_bone_and_tumor",
+    "visualize_labeled_volume",
+    "visualize_resection",
+    "visualize_tumor_convex_hull",
+]

bone_cutting_plane_visualization/classification.py

@@ -0,0 +1,38 @@
+"""Portable region classification matching the historical native implementation."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .data import LabeledVolume, RegionClassificationVolume, SelectedCuttingPlanes
+
+
+def classify_regions(
+    volume: LabeledVolume,
+    cutting_planes: SelectedCuttingPlanes,
+    *,
+    chunk_size: int = 1_000_000,
+) -> RegionClassificationVolume:
+    """Classify normal bone by the first plane whose positive half-space contains it."""
+
+    if not isinstance(volume, LabeledVolume):
+        raise TypeError("volume must be a LabeledVolume")
+    if not isinstance(cutting_planes, SelectedCuttingPlanes):
+        raise TypeError("cutting_planes must be SelectedCuttingPlanes")
+    if not isinstance(chunk_size, int) or isinstance(chunk_size, bool) or chunk_size <= 0:
+        raise ValueError("chunk_size must be a positive integer")
+
+    result = volume.data.astype(np.int32, copy=True)
+    result[result == -1] = 2
+    flat = result.ravel()
+    dimensions = volume.shape
+
+    for plane_index, equation in enumerate(cutting_planes.equations, start=1):
+        remaining = np.flatnonzero(flat == 2)
+        for start in range(0, len(remaining), chunk_size):
+            positions = remaining[start : start + chunk_size]
+            i, j, k = np.unravel_index(positions, dimensions)
+            values = i * equation[0] + j * equation[1] + k * equation[2] + equation[3]
+            flat[positions[values > 0.0]] = -plane_index
+
+    return RegionClassificationVolume(result)

bone_cutting_plane_visualization/cli.py

@@ -0,0 +1,107 @@
+"""Command-line entry points for UBD-backed visualization."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .ubd import IncompleteResectionPlanError, load_labeled_volume, load_resection_plan
+from .visualization import (
+    BoneTumorVisualizer,
+    visualize_bone_and_tumor,
+    visualize_resection,
+    visualize_tumor_convex_hull,
+)
+
+
+def _render_options(args: argparse.Namespace) -> dict:
+    return {
+        "interactive": not args.offscreen,
+        "offscreen": args.offscreen,
+        "screenshot": args.screenshot,
+        "window_size": tuple(args.window_size),
+    }
+
+
+def _view(args: argparse.Namespace) -> int:
+    volume, geometry = load_labeled_volume(args.ubd)
+    visualize_bone_and_tumor(volume, geometry=geometry, **_render_options(args))
+    return 0
+
+
+def _hull(args: argparse.Namespace) -> int:
+    volume, geometry = load_labeled_volume(args.ubd)
+    visualize_tumor_convex_hull(volume, geometry=geometry, **_render_options(args))
+    return 0
+
+
+def _plan(args: argparse.Namespace) -> int:
+    plan = load_resection_plan(args.ubd)
+    visualize_resection(
+        plan,
+        show_retained=args.view != "resected",
+        boundary_only=args.view == "boundary",
+        **_render_options(args),
+    )
+    return 0
+
+
+def _inspect(args: argparse.Namespace) -> int:
+    try:
+        plan = load_resection_plan(args.ubd)
+    except IncompleteResectionPlanError:
+        volume, geometry = load_labeled_volume(args.ubd)
+        print(f"kind=labeled-volume shape={volume.shape} mmpd={geometry.spacing[0]:g}")
+        return 0
+    print(
+        f"kind=resection-plan shape={plan.labeled_volume.shape} "
+        f"planes={plan.cutting_planes.count} keep_rate={plan.keep_rate:.6f} "
+        f"mmpd={plan.geometry.spacing[0]:g}"
+    )
+    return 0
+
+
+def _add_render_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--screenshot", type=Path, help="also save the rendered view as PNG")
+    parser.add_argument(
+        "--offscreen", action="store_true", help="render without opening an interactive window"
+    )
+    parser.add_argument(
+        "--window-size",
+        type=int,
+        nargs=2,
+        default=(1100, 800),
+        metavar=("WIDTH", "HEIGHT"),
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="bone-cutting-plane-viz")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    view = subparsers.add_parser("view", help="visualize bone and tumor from .ubd.npz")
+    view.add_argument("ubd", type=Path)
+    _add_render_arguments(view)
+    view.set_defaults(handler=_view)
+    hull = subparsers.add_parser("hull", help="visualize bone, tumor, and tumor hull")
+    hull.add_argument("ubd", type=Path)
+    _add_render_arguments(hull)
+    hull.set_defaults(handler=_hull)
+    plan = subparsers.add_parser("plan", help="visualize a complete resection-plan .ubd.npz")
+    plan.add_argument("ubd", type=Path)
+    plan.add_argument("--view", choices=("kept", "resected", "boundary"), default="kept")
+    _add_render_arguments(plan)
+    plan.set_defaults(handler=_plan)
+    inspect = subparsers.add_parser("inspect", help="inspect a visualization .ubd.npz")
+    inspect.add_argument("ubd", type=Path)
+    inspect.set_defaults(handler=_inspect)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if hasattr(args, "window_size") and any(value <= 0 for value in args.window_size):
+        raise ValueError("window dimensions must be positive")
+    return int(args.handler(args))
+
+
+__all__ = ["BoneTumorVisualizer", "build_parser", "main"]

bone_cutting_plane_visualization/compatibility.py

@@ -0,0 +1,171 @@
+"""Array-based adapters for callers migrating to the typed public API."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from .classification import classify_regions
+from .data import (
+    LabeledVolume,
+    RegionClassificationVolume,
+    ResectionPlanData,
+    SelectedCuttingPlanes,
+    TumorSafetyMarginData,
+    VolumeGeometry,
+)
+from .visualization import (
+    BOUNDARY_COLOR_MAP,
+    BOUNDARY_LABEL_NAMES,
+    DEFAULT_COLOR_MAP,
+    DEFAULT_LABEL_NAMES,
+    BoneTumorVisualizer,
+    VisualizationScene,
+)
+
+RegionSolver = Callable[[np.ndarray, np.ndarray], np.ndarray]
+
+
+def plan_from_arrays(
+    volume: np.ndarray,
+    equations: np.ndarray,
+    *,
+    solved_volume: np.ndarray | None = None,
+    geometry: VolumeGeometry | None = None,
+    region_solver: RegionSolver | None = None,
+    danger_bone_mask: np.ndarray | None = None,
+    safety_margin_mm: float = 0.0,
+) -> ResectionPlanData:
+    """Convert the former NumPy arguments into one validated plan object."""
+
+    labeled = LabeledVolume(volume)
+    planes = SelectedCuttingPlanes(equations)
+    if solved_volume is not None and region_solver is not None:
+        raise ValueError("provide solved_volume or region_solver, not both")
+    if solved_volume is not None:
+        classification = RegionClassificationVolume(solved_volume)
+    elif region_solver is not None:
+        classification = RegionClassificationVolume(region_solver(labeled.data, planes.equations))
+    else:
+        classification = classify_regions(labeled, planes)
+    resolved_geometry = geometry if geometry is not None else VolumeGeometry()
+
+    safety = None
+    danger = (
+        np.zeros(labeled.shape, dtype=bool)
+        if danger_bone_mask is None
+        else np.asarray(danger_bone_mask, dtype=bool)
+    )
+    if danger.shape != labeled.shape:
+        raise ValueError("danger_bone_mask must have the same shape as volume")
+    if safety_margin_mm > 0 or np.any(danger):
+        protected = labeled.tumor_mask | danger
+        planning = labeled.to_numpy(copy=True)
+        planning[protected] = 1
+        safety = TumorSafetyMarginData(LabeledVolume(planning), protected, danger, safety_margin_mm)
+    return ResectionPlanData(labeled, planes, classification, resolved_geometry, safety)
+
+
+def visualize_resection_arrays(
+    volume: np.ndarray,
+    equations: np.ndarray,
+    *,
+    solved_volume: np.ndarray | None = None,
+    geometry: VolumeGeometry | None = None,
+    region_solver: RegionSolver | None = None,
+    show_retained: bool = True,
+    danger_bone_mask: np.ndarray | None = None,
+    safety_margin_mm: float = 0.0,
+    **render_options: Any,
+) -> VisualizationScene:
+    plan = plan_from_arrays(
+        volume,
+        equations,
+        solved_volume=solved_volume,
+        geometry=geometry,
+        region_solver=region_solver,
+        danger_bone_mask=danger_bone_mask,
+        safety_margin_mm=safety_margin_mm,
+    )
+    return BoneTumorVisualizer(plan.geometry).show_resection(
+        plan, show_retained=show_retained, **render_options
+    )
+
+
+def visualize_volume(
+    data: np.ndarray,
+    color_map: Mapping[float, tuple[float, float, float, float]] | None = None,
+    *,
+    label_names: Mapping[float, str] | None = None,
+    title: str = "Volume visualization",
+    geometry: VolumeGeometry | None = None,
+    interactive: bool = True,
+    offscreen: bool = False,
+    screenshot: str | Path | None = None,
+    window_size: tuple[int, int] = (1100, 800),
+) -> VisualizationScene:
+    visualizer = BoneTumorVisualizer(geometry)
+    model = visualizer.prepare_labeled_volume(
+        data,
+        color_map=DEFAULT_COLOR_MAP if color_map is None else color_map,
+        label_names=DEFAULT_LABEL_NAMES if label_names is None else label_names,
+        title=title,
+    )
+    return visualizer.render(
+        model,
+        interactive=interactive,
+        offscreen=offscreen,
+        screenshot=screenshot,
+        window_size=window_size,
+    )
+
+
+def visualize_solution(
+    data: np.ndarray,
+    equations: np.ndarray,
+    show_volume: bool,
+    show_only_resected_bone: bool = False,
+    show_only_boundary: bool = False,
+    *,
+    geometry: VolumeGeometry | None = None,
+    interactive: bool = True,
+    offscreen: bool = False,
+    screenshot: str | Path | None = None,
+    window_size: tuple[int, int] = (1100, 800),
+) -> VisualizationScene | None:
+    plan = plan_from_arrays(data, equations, geometry=geometry)
+    retained = int(np.count_nonzero(plan.classification.retained_mask))
+    resected = int(np.count_nonzero(plan.classification.resected_mask))
+    print(f"- keep_rate: {plan.keep_rate * 100:7.3f}% ({retained}/{retained + resected})")
+    if not show_volume:
+        return None
+    visualizer = BoneTumorVisualizer(plan.geometry)
+    render_options = {
+        "interactive": interactive,
+        "offscreen": offscreen,
+        "screenshot": screenshot,
+        "window_size": window_size,
+    }
+    if show_only_boundary:
+        boundary = visualizer.prepare_resection_boundary(plan)
+        return visualizer.render(boundary, **render_options)
+    return visualizer.show_resection(
+        plan,
+        show_retained=not show_only_resected_bone,
+        **render_options,
+    )
+
+
+__all__ = [
+    "BOUNDARY_COLOR_MAP",
+    "BOUNDARY_LABEL_NAMES",
+    "DEFAULT_COLOR_MAP",
+    "DEFAULT_LABEL_NAMES",
+    "plan_from_arrays",
+    "visualize_resection_arrays",
+    "visualize_solution",
+    "visualize_volume",
+]