bone-cutting-plane-visualization 0.1.0__tar.gz

bone_cutting_plane_visualization-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GGN_2015
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bone_cutting_plane_visualization-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: bone-cutting-plane-visualization
+Version: 0.1.0
+Summary: Standalone VTK visualization for bone tumor cutting-plane plans
+License: MIT License
+        
+        Copyright (c) 2026 GGN_2015
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ct-mri-dicom-nii-reader<0.2,>=0.1.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Provides-Extra: viz
+Requires-Dist: vtk>=9.2; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: all
+Requires-Dist: vtk>=9.2; extra == "all"
+Requires-Dist: pytest>=8; extra == "all"
+Requires-Dist: ruff>=0.6; extra == "all"
+Dynamic: license-file
+
+# bone-cutting-plane-visualization
+
+Standalone data contracts and VTK visualization for bone-tumor cutting-plane
+plans. The package is independent of any planning or optimization repository.
+
+All persisted inputs use the `.ubd.npz` format from
+[`ct-mri-dicom-nii-reader`](https://pypi.org/project/ct-mri-dicom-nii-reader/).
+Volumes are interpreted in `(Left, Posterior, Superior)` axis order. Standard
+UBD files can be used for the bone/tumor and convex-hull views; a compatible,
+namespaced extension stores a complete resection plan in one UBD archive.
+
+## Installation
+
+```powershell
+python -m pip install -e ".[all]"
+```
+
+The mandatory runtime dependency on `ct-mri-dicom-nii-reader` provides the UBD
+loader and `BodyData` contract. VTK remains optional so data inspection and
+scene preparation work on headless systems:
+
+```powershell
+python -m pip install -e .
+python -m pip install -e ".[viz]"
+```
+
+## Data contracts
+
+The public plan consists of five explicit classes:
+
+- `LabeledVolume`: `-1` normal bone, `0` other, `1` tumor.
+- `SelectedCuttingPlanes`: ordered index-space rows `[a, b, c, d]`.
+- `RegionClassificationVolume`: negative retained bone and `2` resected bone.
+- `VolumeGeometry`: spacing, LPS origin, and index-to-LPS direction.
+- `TumorSafetyMarginData`: optional planning volume, protected mask, danger-bone
+  mask, and physical margin.
+
+`ResectionPlanData` combines them and validates shapes, labels, plane references,
+and safety-margin clearance.
+
+```python
+import numpy as np
+
+from bone_cutting_plane_visualization import (
+    ResectionPlanData,
+    SelectedCuttingPlanes,
+    classify_regions,
+    load_labeled_volume,
+    save_resection_plan,
+)
+
+volume, geometry = load_labeled_volume("case-labels.ubd.npz")
+planes = SelectedCuttingPlanes(
+    np.asarray([[1.0, 0.0, 0.0, -42.5]], dtype=np.float64)
+)
+classification = classify_regions(volume, planes)
+plan = ResectionPlanData(volume, planes, classification, geometry)
+save_resection_plan(plan, "case-plan.ubd.npz")
+```
+
+Arrays are copied, normalized to stable dtypes, and exposed read-only.
+
+Callers migrating from NumPy-based APIs can use `compatibility.plan_from_arrays`,
+`compatibility.visualize_resection_arrays`, `compatibility.visualize_volume`,
+and `compatibility.visualize_solution`. These adapters depend only on this package;
+they never import a planning repository.
+
+## UBD plan extension
+
+Every plan archive retains the standard UBD v1 fields:
+
+```text
+format_version, body_data, image_type, mmpd
+```
+
+It adds the following `bcv_` fields:
+
+```text
+bcv_schema_version
+bcv_cutting_planes
+bcv_region_classification
+bcv_spacing_mm
+bcv_origin_lps_mm
+bcv_direction_index_to_lps
+bcv_has_safety_margin
+bcv_safety_planning_volume       # present when enabled
+bcv_safety_protected_mask        # present when enabled
+bcv_safety_danger_bone_mask      # present when enabled
+bcv_safety_margin_mm             # present when enabled
+```
+
+Unknown fields are ignored by `UnifiedBodyDataLoader`, so a plan archive remains
+readable as an ordinary mask UBD file. The package verifies that compatibility
+after every save. Because UBD stores one scalar `mmpd`, persisted plans require
+isotropic spacing. Direct in-memory visualization still supports arbitrary valid
+`VolumeGeometry` values.
+
+## Visualization
+
+```python
+from bone_cutting_plane_visualization import load_resection_plan, visualize_resection
+
+plan = load_resection_plan("case-plan.ubd.npz")
+visualize_resection(plan)
+```
+
+The final view includes retained normal bone, resected normal bone, tumor,
+optional safety-margin bone, bounded cutting-plane polygons, legend, retention
+rate, and the same camera and visual styling as the source implementation. Every
+VTK scene also includes a compact black orientation cube with white edges and
+`L/R`, `P/A`, and `S/i` face labels. It is scaled from the physical volume bounds
+and placed beyond the negative X/Y side of the LPS bounds, outside the clinical
+geometry and business legend.
+
+The CLI accepts only `.ubd.npz` inputs:
+
+```powershell
+bone-cutting-plane-viz view case-labels.ubd.npz
+bone-cutting-plane-viz hull case-labels.ubd.npz
+bone-cutting-plane-viz plan case-plan.ubd.npz
+bone-cutting-plane-viz plan case-plan.ubd.npz --view resected
+bone-cutting-plane-viz plan case-plan.ubd.npz --offscreen --screenshot plan.png
+bone-cutting-plane-viz inspect case-plan.ubd.npz
+```
+
+## Development
+
+```powershell
+python -m pytest
+ruff check src tests
+```

bone_cutting_plane_visualization-0.1.0/README.md

@@ -0,0 +1,131 @@
+# bone-cutting-plane-visualization
+
+Standalone data contracts and VTK visualization for bone-tumor cutting-plane
+plans. The package is independent of any planning or optimization repository.
+
+All persisted inputs use the `.ubd.npz` format from
+[`ct-mri-dicom-nii-reader`](https://pypi.org/project/ct-mri-dicom-nii-reader/).
+Volumes are interpreted in `(Left, Posterior, Superior)` axis order. Standard
+UBD files can be used for the bone/tumor and convex-hull views; a compatible,
+namespaced extension stores a complete resection plan in one UBD archive.
+
+## Installation
+
+```powershell
+python -m pip install -e ".[all]"
+```
+
+The mandatory runtime dependency on `ct-mri-dicom-nii-reader` provides the UBD
+loader and `BodyData` contract. VTK remains optional so data inspection and
+scene preparation work on headless systems:
+
+```powershell
+python -m pip install -e .
+python -m pip install -e ".[viz]"
+```
+
+## Data contracts
+
+The public plan consists of five explicit classes:
+
+- `LabeledVolume`: `-1` normal bone, `0` other, `1` tumor.
+- `SelectedCuttingPlanes`: ordered index-space rows `[a, b, c, d]`.
+- `RegionClassificationVolume`: negative retained bone and `2` resected bone.
+- `VolumeGeometry`: spacing, LPS origin, and index-to-LPS direction.
+- `TumorSafetyMarginData`: optional planning volume, protected mask, danger-bone
+  mask, and physical margin.
+
+`ResectionPlanData` combines them and validates shapes, labels, plane references,
+and safety-margin clearance.
+
+```python
+import numpy as np
+
+from bone_cutting_plane_visualization import (
+    ResectionPlanData,
+    SelectedCuttingPlanes,
+    classify_regions,
+    load_labeled_volume,
+    save_resection_plan,
+)
+
+volume, geometry = load_labeled_volume("case-labels.ubd.npz")
+planes = SelectedCuttingPlanes(
+    np.asarray([[1.0, 0.0, 0.0, -42.5]], dtype=np.float64)
+)
+classification = classify_regions(volume, planes)
+plan = ResectionPlanData(volume, planes, classification, geometry)
+save_resection_plan(plan, "case-plan.ubd.npz")
+```
+
+Arrays are copied, normalized to stable dtypes, and exposed read-only.
+
+Callers migrating from NumPy-based APIs can use `compatibility.plan_from_arrays`,
+`compatibility.visualize_resection_arrays`, `compatibility.visualize_volume`,
+and `compatibility.visualize_solution`. These adapters depend only on this package;
+they never import a planning repository.
+
+## UBD plan extension
+
+Every plan archive retains the standard UBD v1 fields:
+
+```text
+format_version, body_data, image_type, mmpd
+```
+
+It adds the following `bcv_` fields:
+
+```text
+bcv_schema_version
+bcv_cutting_planes
+bcv_region_classification
+bcv_spacing_mm
+bcv_origin_lps_mm
+bcv_direction_index_to_lps
+bcv_has_safety_margin
+bcv_safety_planning_volume       # present when enabled
+bcv_safety_protected_mask        # present when enabled
+bcv_safety_danger_bone_mask      # present when enabled
+bcv_safety_margin_mm             # present when enabled
+```
+
+Unknown fields are ignored by `UnifiedBodyDataLoader`, so a plan archive remains
+readable as an ordinary mask UBD file. The package verifies that compatibility
+after every save. Because UBD stores one scalar `mmpd`, persisted plans require
+isotropic spacing. Direct in-memory visualization still supports arbitrary valid
+`VolumeGeometry` values.
+
+## Visualization
+
+```python
+from bone_cutting_plane_visualization import load_resection_plan, visualize_resection
+
+plan = load_resection_plan("case-plan.ubd.npz")
+visualize_resection(plan)
+```
+
+The final view includes retained normal bone, resected normal bone, tumor,
+optional safety-margin bone, bounded cutting-plane polygons, legend, retention
+rate, and the same camera and visual styling as the source implementation. Every
+VTK scene also includes a compact black orientation cube with white edges and
+`L/R`, `P/A`, and `S/i` face labels. It is scaled from the physical volume bounds
+and placed beyond the negative X/Y side of the LPS bounds, outside the clinical
+geometry and business legend.
+
+The CLI accepts only `.ubd.npz` inputs:
+
+```powershell
+bone-cutting-plane-viz view case-labels.ubd.npz
+bone-cutting-plane-viz hull case-labels.ubd.npz
+bone-cutting-plane-viz plan case-plan.ubd.npz
+bone-cutting-plane-viz plan case-plan.ubd.npz --view resected
+bone-cutting-plane-viz plan case-plan.ubd.npz --offscreen --screenshot plan.png
+bone-cutting-plane-viz inspect case-plan.ubd.npz
+```
+
+## Development
+
+```powershell
+python -m pytest
+ruff check src tests
+```

bone_cutting_plane_visualization-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bone-cutting-plane-visualization"
+version = "0.1.0"
+description = "Standalone VTK visualization for bone tumor cutting-plane plans"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+dependencies = [
+    "ct-mri-dicom-nii-reader>=0.1.2,<0.2",
+    "numpy>=1.26",
+    "scipy>=1.11",
+]
+
+[project.optional-dependencies]
+viz = ["vtk>=9.2"]
+dev = ["pytest>=8", "ruff>=0.6"]
+all = ["vtk>=9.2", "pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+bone-cutting-plane-viz = "bone_cutting_plane_visualization.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["bone_cutting_plane_visualization*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100

bone_cutting_plane_visualization-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bone_cutting_plane_visualization-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"]