cardio 2026.1.3__tar.gz

cardio-2026.1.3/LICENSE

@@ -0,0 +1,15 @@
+Apache Software License 2.0
+
+Copyright (c) 2023, Davis Marc Vigneault
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

cardio-2026.1.3/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.3
+Name: cardio
+Version: 2026.1.3
+Summary: A simple web-based viewer for 3D and 4D ('cine') medical imaging data.
+Keywords: Medical,Imaging,3D,4D,Visualization
+Author: Davis Marc Vigneault
+Author-email: Davis Marc Vigneault <davis.vigneault@gmail.com>
+License: Apache Software License 2.0
+         
+         Copyright (c) 2023, Davis Marc Vigneault
+         
+         Licensed under the Apache License, Version 2.0 (the "License");
+         you may not use this file except in compliance with the License.
+         You may obtain a copy of the License at
+         
+         http://www.apache.org/licenses/LICENSE-2.0
+         
+         Unless required by applicable law or agreed to in writing, software
+         distributed under the License is distributed on an "AS IS" BASIS,
+         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+         See the License for the specific language governing permissions and
+         limitations under the License.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: JavaScript
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: trame-vuetify>=3.0.2
+Requires-Dist: trame-vtk>=2.9.1
+Requires-Dist: itk>=5.4.4.post1
+Requires-Dist: vtk>=9.5.0
+Requires-Dist: tomlkit>=0.13.3
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: trame>=3.12.0
+Requires-Dist: trame-client>=3.10.1
+Requires-Dist: ruff>=0.12.10 ; extra == 'dev'
+Requires-Dist: isort>=6.0.1 ; extra == 'dev'
+Requires-Dist: bumpver>=2025.1131 ; extra == 'dev'
+Requires-Dist: pytest>=8.4.1 ; extra == 'dev'
+Requires-Dist: coverage>=7.10.4 ; extra == 'dev'
+Maintainer: Davis Marc Vigneault
+Maintainer-email: Davis Marc Vigneault <davis.vigneault@gmail.com>
+Requires-Python: >=3.10
+Project-URL: repository, https://github.com/sudomakeinstall/cardio
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# cardio
+
+`cardio` is a simple web-based viewer for 3D and 4D ('cine') medical imaging data,
+built primarily on [trame](https://github.com/kitware/trame),
+[vtk](https://github.com/kitware/vtk), and
+[itk](https://github.com/insightsoftwareconsortium/itk).  `cardio` can render sequences
+of mesh files (e.g., `*.obj` files), segmentation files (e.g., `*.nii.gz` files with
+discrete labels) and volume renderings of grayscale images (e.g., `*.nii.gz` files with
+continuous values).  `cardio` is launched from the commandline and may be configured via
+commandline arguments, a static TOML configuration file, or a combination of the two.
+
+## Quickstart
+
+### Installation
+
+```bash
+$ cd /path/to/your/project
+$ uv init
+$ uv add cardio
+$ . ./.venv/bin/activate
+(project) cardio --version
+cardio 2026.1.3
+```
+
+### Developing
+
+Ensuring you have all required dependencies:
+
+```bash
+$ uv sync --all-extras
+```
+
+Pre-commit checklist:
+
+```bash
+$ isort .
+$ ruff format
+$ pytest -v
+```
+
+Uploading:
+
+```bash
+$ bumpver update
+$ uv build --no-sources
+$ uv publish --token <pypi_api_key>
+```

cardio-2026.1.3/README.md

@@ -0,0 +1,47 @@
+# cardio
+
+`cardio` is a simple web-based viewer for 3D and 4D ('cine') medical imaging data,
+built primarily on [trame](https://github.com/kitware/trame),
+[vtk](https://github.com/kitware/vtk), and
+[itk](https://github.com/insightsoftwareconsortium/itk).  `cardio` can render sequences
+of mesh files (e.g., `*.obj` files), segmentation files (e.g., `*.nii.gz` files with
+discrete labels) and volume renderings of grayscale images (e.g., `*.nii.gz` files with
+continuous values).  `cardio` is launched from the commandline and may be configured via
+commandline arguments, a static TOML configuration file, or a combination of the two.
+
+## Quickstart
+
+### Installation
+
+```bash
+$ cd /path/to/your/project
+$ uv init
+$ uv add cardio
+$ . ./.venv/bin/activate
+(project) cardio --version
+cardio 2026.1.3
+```
+
+### Developing
+
+Ensuring you have all required dependencies:
+
+```bash
+$ uv sync --all-extras
+```
+
+Pre-commit checklist:
+
+```bash
+$ isort .
+$ ruff format
+$ pytest -v
+```
+
+Uploading:
+
+```bash
+$ bumpver update
+$ uv build --no-sources
+$ uv publish --token <pypi_api_key>
+```

cardio-2026.1.3/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"
+
+[project]
+name = "cardio"
+version = "2026.1.3"
+authors = [
+    {name = "Davis Marc Vigneault", email = "davis.vigneault@gmail.com"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: JavaScript",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+    "trame-vuetify>=3.0.2",
+    "trame-vtk>=2.9.1",
+    "itk>=5.4.4.post1",
+    "vtk>=9.5.0",
+    "tomlkit>=0.13.3",
+    "numpy>=2.2.6",
+    "pydantic>=2.11.7",
+    "pydantic-settings>=2.0.0",
+    "trame>=3.12.0",
+    "trame-client>=3.10.1",
+]
+description = "A simple web-based viewer for 3D and 4D ('cine') medical imaging data."
+keywords = ["Medical", "Imaging", "3D", "4D", "Visualization"]
+license = {file = "LICENSE"}
+maintainers = [
+    {name = "Davis Marc Vigneault", email = "davis.vigneault@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+
+[project.optional-dependencies]
+dev = [
+ "ruff>=0.12.10",
+ "isort>=6.0.1",
+ "bumpver>=2025.1131",
+ "pytest>=8.4.1",
+ "coverage>=7.10.4",
+]
+
+[project.gui-scripts]
+cardio = "cardio.app:main"
+
+[project.urls]
+repository = "https://github.com/sudomakeinstall/cardio"
+
+[tool.isort]
+profile = "black"
+
+[tool.bumpver]
+current_version = "2026.1.3"
+version_pattern = "YYYY.MM.INC0"
+commit_message = "ENH: Bump version from {old_version} => {new_version}"
+commit = true
+tag = true
+push = false
+
+[tool.bumpver.file_patterns]
+"pyproject.toml" = [
+    'current_version = "{version}"',
+    'version = "{version}"',
+]
+"src/cardio/__init__.py" = [
+    '__version__ = "{version}"',
+]
+"README.md" = [
+    'cardio {version}',
+]

cardio-2026.1.3/src/cardio/__init__.py

@@ -0,0 +1,29 @@
+from . import window_level
+from .logic import Logic
+from .mesh import Mesh
+from .object import Object
+from .scene import Scene
+from .screenshot import Screenshot
+from .segmentation import Segmentation
+from .ui import UI
+from .volume import Volume
+from .volume_property_presets import (
+    list_volume_property_presets,
+    load_volume_property_preset,
+)
+
+__all__ = [
+    "Object",
+    "Mesh",
+    "Volume",
+    "Segmentation",
+    "Scene",
+    "Screenshot",
+    "UI",
+    "Logic",
+    "load_volume_property_preset",
+    "list_volume_property_presets",
+    "window_level",
+]
+
+__version__ = "2026.1.3"

cardio-2026.1.3/src/cardio/app.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+
+import pydantic_settings as ps
+import trame as tm
+import trame.decorators
+
+from . import __version__
+from .logic import Logic
+from .scene import Scene
+from .ui import UI
+
+
+@tm.decorators.TrameApp()
+class CardioApp:
+    def __init__(self, server=None):
+        self.server = tm.app.get_server(server, client_type="vue3")
+
+        self.server.cli.add_argument(
+            "--config", help="TOML configuration file.", dest="cfg_file", required=False
+        )
+
+        self.server.cli.add_argument(
+            "--version", action="version", version=f"cardio {__version__}"
+        )
+
+        cli_settings = ps.CliSettingsSource(
+            Scene, root_parser=self.server.cli, cli_parse_args=True
+        )
+
+        args, unknown = self.server.cli.parse_known_args()
+        config_file = getattr(args, "cfg_file", None)
+
+        Scene._cli_source = cli_settings
+        Scene._config_file = config_file
+
+        try:
+            scene = Scene()
+        finally:
+            if hasattr(Scene, "_cli_source"):
+                delattr(Scene, "_cli_source")
+            if hasattr(Scene, "_config_file"):
+                delattr(Scene, "_config_file")
+
+        Logic(self.server, scene)
+        UI(self.server, scene)
+
+
+def main():
+    app = CardioApp()
+    app.server.start(open_browser=False)
+
+
+if __name__ == "__main__":
+    main()

cardio-2026.1.3/src/cardio/assets/bone.toml

@@ -0,0 +1,42 @@
+name = "Bone"
+description = "Bone"
+
+ambient = 1.0
+diffuse = 1.0
+specular = 0.0
+
+[[transfer_functions]]
+
+[transfer_functions.opacity]
+[[transfer_functions.opacity.points]]
+x = -1024.0
+y = 0.0
+
+[[transfer_functions.opacity.points]]
+x = 54.0
+y = 0.0
+
+[[transfer_functions.opacity.points]]
+x = 536.0
+y = 0.1
+
+[[transfer_functions.opacity.points]]
+x = 3071.0
+y = 0.1
+
+[transfer_functions.color]
+[[transfer_functions.color.points]]
+x = -1024.0
+color = [0.0, 0.0, 0.0]
+
+[[transfer_functions.color.points]]
+x = 54.0
+color = [0.0, 0.0, 0.0]
+
+[[transfer_functions.color.points]]
+x = 536.0
+color = [1.0, 1.0, 1.0]
+
+[[transfer_functions.color.points]]
+x = 3071.0
+color = [1.0, 1.0, 1.0]

cardio-2026.1.3/src/cardio/assets/vascular_closed.toml

@@ -0,0 +1,78 @@
+name = "Vascular_Closed"
+description = "Vascular (Closed)"
+
+ambient = 0.7
+diffuse = 0.4
+specular = 1.0
+
+[[transfer_functions]]
+
+[transfer_functions.opacity]
+[[transfer_functions.opacity.points]]
+x = 150
+y = 0.0
+
+[[transfer_functions.opacity.points]]
+x = 650
+y = 1.0
+
+[[transfer_functions.opacity.points]]
+x = 3071
+y = 1.0
+
+[transfer_functions.color]
+[[transfer_functions.color.points]]
+x = 150
+color = [1.0, 1.0, 1.0]
+
+[[transfer_functions.color.points]]
+x = 3071
+color = [1.0, 1.0, 1.0]
+
+[[transfer_functions]]
+
+[transfer_functions.opacity]
+[[transfer_functions.opacity.points]]
+x = -96.5
+y = 0.0
+
+[[transfer_functions.opacity.points]]
+x = 269.0
+y = 0.05
+
+[[transfer_functions.opacity.points]]
+x = 474.5
+y = 0.0
+
+[transfer_functions.color]
+[[transfer_functions.color.points]]
+x = -96.5
+color = [1.0, 1.0, 1.0]
+
+[[transfer_functions.color.points]]
+x = 474.5
+color = [1.0, 1.0, 1.0]
+
+[[transfer_functions]]
+
+[transfer_functions.opacity]
+[[transfer_functions.opacity.points]]
+x = 120
+y = 0.0
+
+[[transfer_functions.opacity.points]]
+x = 258.0
+y = 0.8
+
+[[transfer_functions.opacity.points]]
+x = 320
+y = 0.0
+
+[transfer_functions.color]
+[[transfer_functions.color.points]]
+x = 120
+color = [1.0, 0.0, 0.0]
+
+[[transfer_functions.color.points]]
+x = 320
+color = [1.0, 1.0, 0.0]

cardio-2026.1.3/src/cardio/assets/vascular_open.toml

@@ -0,0 +1,54 @@
+name = "Vascular_Open"
+description = "Vascular (Open)"
+
+ambient = 0.7
+diffuse = 0.4
+specular = 1.0
+
+[[transfer_functions]]
+
+[transfer_functions.opacity]
+[[transfer_functions.opacity.points]]
+x = -96.5
+y = 0.0
+
+[[transfer_functions.opacity.points]]
+x = 269.0
+y = 0.05
+
+[[transfer_functions.opacity.points]]
+x = 474.5
+y = 0.0
+
+[transfer_functions.color]
+[[transfer_functions.color.points]]
+x = -96.5
+color = [1.0, 1.0, 1.0]
+
+[[transfer_functions.color.points]]
+x = 474.5
+color = [1.0, 1.0, 1.0]
+
+[[transfer_functions]]
+
+[transfer_functions.opacity]
+[[transfer_functions.opacity.points]]
+x = 117
+y = 0.0
+
+[[transfer_functions.opacity.points]]
+x = 246.0
+y = 0.87
+
+[[transfer_functions.opacity.points]]
+x = 319
+y = 0.0
+
+[transfer_functions.color]
+[[transfer_functions.color.points]]
+x = 117
+color = [1.0, 0.0, 0.0]
+
+[[transfer_functions.color.points]]
+x = 319
+color = [1.0, 1.0, 0.0]

cardio-2026.1.3/src/cardio/assets/xray.toml

@@ -0,0 +1,42 @@
+name = "Radiograph"
+description = "Radiograph"
+
+ambient = 1.0
+diffuse = 1.0
+specular = 0.0
+
+[[transfer_functions]]
+
+[transfer_functions.opacity]
+[[transfer_functions.opacity.points]]
+x = -1024.0
+y = 0.0
+
+[[transfer_functions.opacity.points]]
+x = -200.0
+y = 0.0
+
+[[transfer_functions.opacity.points]]
+x = 300.0
+y = 0.01
+
+[[transfer_functions.opacity.points]]
+x = 3071.0
+y = 0.01
+
+[transfer_functions.color]
+[[transfer_functions.color.points]]
+x = -1024.0
+color = [0.0, 0.0, 0.0]
+
+[[transfer_functions.color.points]]
+x = -200.0
+color = [0.0, 0.0, 0.0]
+
+[[transfer_functions.color.points]]
+x = 300.0
+color = [1.0, 1.0, 1.0]
+
+[[transfer_functions.color.points]]
+x = 3071.0
+color = [1.0, 1.0, 1.0]

cardio-2026.1.3/src/cardio/blend_transfer_functions.py

@@ -0,0 +1,81 @@
+import numpy as np
+import vtk
+
+
+def blend_transfer_functions(tfs, scalar_range=(-2000, 2000), num_samples=512):
+    """
+    Blend multiple transfer functions using volume rendering emission-absorption model.
+
+    Based on the volume rendering equation from:
+    - Levoy, M. "Display of Surfaces from Volume Data" IEEE Computer Graphics and Applications, 1988
+    - Kajiya, J.T. & Von Herzen, B.P. "Ray tracing volume densities" ACM SIGGRAPH Computer Graphics, 1984
+    - Engel, K. et al. "Real-time Volume Graphics" A K Peters, 2006, Chapter 2
+
+    The volume rendering integral: I = ∫ C(s) * μ(s) * T(s) ds
+    where C(s) = emission color, μ(s) = opacity, T(s) = transmission
+
+    For discrete transfer functions, this becomes:
+    - Total emission = Σ(color_i * opacity_i)
+    - Total absorption = Σ(opacity_i)
+    - Final color = total_emission / total_absorption
+    """
+    if len(tfs) == 1:
+        return tfs[0]
+
+    sample_points = np.linspace(
+        start=scalar_range[0],
+        stop=scalar_range[1],
+        num=num_samples,
+    )
+
+    # Initialize arrays to store blended values
+    blended_opacity = []
+    blended_color = []
+
+    for scalar_val in sample_points:
+        # Accumulate emission and absorption for volume rendering
+        total_emission = [0.0, 0.0, 0.0]
+        total_absorption = 0.0
+
+        for otf, ctf in tfs:
+            # Get opacity and color for this scalar value
+            layer_opacity = otf.GetValue(scalar_val)
+            layer_color = [0.0, 0.0, 0.0]
+            ctf.GetColor(scalar_val, layer_color)
+
+            # Volume rendering accumulation:
+            # Emission = color * opacity (additive)
+            # Absorption = opacity (multiplicative through transmission)
+            for i in range(3):
+                total_emission[i] += layer_color[i] * layer_opacity
+
+            total_absorption += layer_opacity
+
+        # Clamp values to reasonable ranges
+        total_absorption = min(total_absorption, 1.0)
+        for i in range(3):
+            total_emission[i] = min(total_emission[i], 1.0)
+
+        # For the final color, normalize emission by absorption if absorption > 0
+        if total_absorption > 0.001:  # Avoid division by zero
+            final_color = [total_emission[i] / total_absorption for i in range(3)]
+        else:
+            final_color = [0.0, 0.0, 0.0]
+
+        # Clamp final colors
+        final_color = [min(c, 1.0) for c in final_color]
+
+        blended_opacity.append(total_absorption)
+        blended_color.append(final_color)
+
+    # Create new VTK transfer functions with blended values
+    blended_otf = vtk.vtkPiecewiseFunction()
+    blended_ctf = vtk.vtkColorTransferFunction()
+
+    for i, scalar_val in enumerate(sample_points):
+        blended_otf.AddPoint(scalar_val, blended_opacity[i])
+        blended_ctf.AddRGBPoint(
+            scalar_val, blended_color[i][0], blended_color[i][1], blended_color[i][2]
+        )
+
+    return blended_otf, blended_ctf

cardio-2026.1.3/src/cardio/color_transfer_function.py

@@ -0,0 +1,27 @@
+import pydantic as pc
+import vtk
+
+from .types import RGBColor
+
+
+class ColorTransferFunctionPoint(pc.BaseModel):
+    """A single point in a color transfer function."""
+
+    x: float = pc.Field(description="Scalar value")
+    color: RGBColor
+
+
+class ColorTransferFunctionConfig(pc.BaseModel):
+    """Configuration for a VTK color transfer function."""
+
+    points: list[ColorTransferFunctionPoint] = pc.Field(
+        min_length=1, description="Points defining the color transfer function"
+    )
+
+    @property
+    def vtk_function(self) -> vtk.vtkColorTransferFunction:
+        """Create VTK color transfer function from this configuration."""
+        ctf = vtk.vtkColorTransferFunction()
+        for point in self.points:
+            ctf.AddRGBPoint(point.x, *point.color)
+        return ctf