fdg-pet-ct-mlx 0.2.1__tar.gz

fdg_pet_ct_mlx-0.2.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+work/

fdg_pet_ct_mlx-0.2.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

fdg_pet_ct_mlx-0.2.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: fdg-pet-ct-mlx
+Version: 0.2.1
+Summary: Native MLX FDG PET image synthesis
+Author: Joseph Sandoval, Alfredo Sandoval Jr.
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Classifier: Operating System :: MacOS :: MacOS X
+Requires-Python: <3.15,>=3.13
+Requires-Dist: medmlx-core==0.2.3
+Requires-Dist: mlx<1,>=0.32.4
+Requires-Dist: numpy<3,>=2.0
+Provides-Extra: conversion
+Requires-Dist: torch<2.14,>=2.13; extra == 'conversion'
+Provides-Extra: dev
+Requires-Dist: pyright==1.1.414; extra == 'dev'
+Requires-Dist: pytest<10,>=8.4; extra == 'dev'
+Requires-Dist: ruff<1,>=0.13; extra == 'dev'
+Requires-Dist: scipy-stubs<1.19,>=1.18; extra == 'dev'
+Requires-Dist: scipy<2,>=1.13; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fdg-pet-ct-mlx
+
+Native MLX FDG PET synthesis for Apple Silicon. Turn a CT and its organ labels into
+a synthetic FDG PET (SUV) volume, locally on Mac.
+
+- Organ-level FDG activity from a label map
+- Scanner blur, scatter, randoms and count noise
+- Optional lesion uptake
+- FP32 using MLX; every random draw is controlled by an explicit integer seed
+
+Part of [MedMLX](https://github.com/MedMLX).
+[Technical notes](https://github.com/MedMLX/fdg-pet-ct-mlx/blob/main/docs/technical.md)
+
+[Quick start](#quick-start) · [Input and output](#input-and-output) · [Technical details](#technical-details) · [License](#license)
+
+## Requirements
+
+Apple Silicon Mac with Metal, Python 3.13 or 3.14 and [uv](https://docs.astral.sh/uv/).
+No model weights are needed.
+
+## Quick start
+
+Install the current source branch:
+
+```bash
+uv pip install "fdg-pet-ct-mlx @ git+https://github.com/MedMLX/fdg-pet-ct-mlx.git"
+```
+
+Organ and scanner settings are passed as profile objects; any object with the
+fields below works. This example uses simple dataclasses and a synthetic volume:
+
+```python
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import mlx.core as mx
+
+from fdg_pet_ct_mlx.acquisition import apply_acquisition_model
+from fdg_pet_ct_mlx.activity import synthesize_activity_map
+
+
+@dataclass(frozen=True)
+class Tissue:
+    suv_mean: float
+    suv_std: float
+    maisi_labels: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class Organs:
+    tissues: Mapping[str, Tissue]
+
+    def lookup_table(self, size: int) -> tuple[float, ...]:
+        table = [self.tissues["unclassified_soft_tissue"].suv_mean] * size
+        for tissue in self.tissues.values():
+            for label in tissue.maisi_labels:
+                if label < size:
+                    table[label] = tissue.suv_mean
+        return tuple(table)
+
+
+@dataclass(frozen=True)
+class Scanner:
+    scatter_fraction: float = 0.05
+    randoms_fraction: float = 0.02
+    fwhm_mm: tuple[float, float, float] = (5.0, 5.0, 5.0)
+    counts_per_suv: float = 100.0
+
+
+organ = Organs({
+    "background": Tissue(0.0, 0.0, (0,)),
+    "unclassified_soft_tissue": Tissue(1.0, 0.1, (1,)),
+})
+labels = mx.ones((16, 16, 16), dtype=mx.int32)
+ct_hu = mx.zeros(labels.shape, dtype=mx.float32)
+activity = synthesize_activity_map(labels, organ, seed=7, mx=mx)
+pet = apply_acquisition_model(
+    activity,
+    ct_hu,
+    scanner=Scanner(),
+    count_level=1.0,
+    spacing_mm=(2.0, 2.0, 2.0),
+    seed=8,
+    mx=mx,
+)
+mx.eval(pet)
+print(pet.shape, pet.dtype)  # (16, 16, 16), float32
+```
+
+## Input and output
+
+Inputs are a nonnegative integer label volume and a CT volume in HU on the same 3D
+grid. Organ profiles give each tissue's SUV mean, standard deviation and label
+values; scanner profiles give resolution (FWHM), scatter, randoms and counts.
+
+The output is a float32 SUVbw MLX array with the input shape. To add lesions, use
+`fdg_pet_ct_mlx.lesion.apply_lesion_uptake` with a lesion profile.
+
+Profile validation, resampling and file I/O are up to you. This is image-space
+synthesis; it does not simulate projection physics or reconstruction.
+
+## Technical details
+
+Activity synthesis and scanner effects operate on MLX arrays in float32.
+The acquisition model approximates blur, scatter, randoms and count noise in
+image space. Profiles, numerical contracts and development commands are described
+in [docs/technical.md](https://github.com/MedMLX/fdg-pet-ct-mlx/blob/main/docs/technical.md).
+
+## Intended use
+
+Research software, for research and education only; not for clinical diagnosis or
+treatment decisions. The output is a synthetic image from a simple image-space model, not
+a simulation of a real scanner. Outputs require human review.
+
+## License
+
+Apache-2.0; see [LICENSE](https://github.com/MedMLX/fdg-pet-ct-mlx/blob/main/LICENSE).
+See [THIRD_PARTY_NOTICES.md](https://github.com/MedMLX/fdg-pet-ct-mlx/blob/main/THIRD_PARTY_NOTICES.md) for dependency attribution.
+
+## Implementation mapping
+
+[Central implementation map](https://github.com/MedMLX/Med-MLX/blob/main/implementation-maps/fdg-pet-ct-mlx.json) records upstream-to-native changes, source references and qualification scope.

fdg_pet_ct_mlx-0.2.1/README.md

@@ -0,0 +1,122 @@
+# fdg-pet-ct-mlx
+
+Native MLX FDG PET synthesis for Apple Silicon. Turn a CT and its organ labels into
+a synthetic FDG PET (SUV) volume, locally on Mac.
+
+- Organ-level FDG activity from a label map
+- Scanner blur, scatter, randoms and count noise
+- Optional lesion uptake
+- FP32 using MLX; every random draw is controlled by an explicit integer seed
+
+Part of [MedMLX](https://github.com/MedMLX).
+[Technical notes](https://github.com/MedMLX/fdg-pet-ct-mlx/blob/main/docs/technical.md)
+
+[Quick start](#quick-start) · [Input and output](#input-and-output) · [Technical details](#technical-details) · [License](#license)
+
+## Requirements
+
+Apple Silicon Mac with Metal, Python 3.13 or 3.14 and [uv](https://docs.astral.sh/uv/).
+No model weights are needed.
+
+## Quick start
+
+Install the current source branch:
+
+```bash
+uv pip install "fdg-pet-ct-mlx @ git+https://github.com/MedMLX/fdg-pet-ct-mlx.git"
+```
+
+Organ and scanner settings are passed as profile objects; any object with the
+fields below works. This example uses simple dataclasses and a synthetic volume:
+
+```python
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import mlx.core as mx
+
+from fdg_pet_ct_mlx.acquisition import apply_acquisition_model
+from fdg_pet_ct_mlx.activity import synthesize_activity_map
+
+
+@dataclass(frozen=True)
+class Tissue:
+    suv_mean: float
+    suv_std: float
+    maisi_labels: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class Organs:
+    tissues: Mapping[str, Tissue]
+
+    def lookup_table(self, size: int) -> tuple[float, ...]:
+        table = [self.tissues["unclassified_soft_tissue"].suv_mean] * size
+        for tissue in self.tissues.values():
+            for label in tissue.maisi_labels:
+                if label < size:
+                    table[label] = tissue.suv_mean
+        return tuple(table)
+
+
+@dataclass(frozen=True)
+class Scanner:
+    scatter_fraction: float = 0.05
+    randoms_fraction: float = 0.02
+    fwhm_mm: tuple[float, float, float] = (5.0, 5.0, 5.0)
+    counts_per_suv: float = 100.0
+
+
+organ = Organs({
+    "background": Tissue(0.0, 0.0, (0,)),
+    "unclassified_soft_tissue": Tissue(1.0, 0.1, (1,)),
+})
+labels = mx.ones((16, 16, 16), dtype=mx.int32)
+ct_hu = mx.zeros(labels.shape, dtype=mx.float32)
+activity = synthesize_activity_map(labels, organ, seed=7, mx=mx)
+pet = apply_acquisition_model(
+    activity,
+    ct_hu,
+    scanner=Scanner(),
+    count_level=1.0,
+    spacing_mm=(2.0, 2.0, 2.0),
+    seed=8,
+    mx=mx,
+)
+mx.eval(pet)
+print(pet.shape, pet.dtype)  # (16, 16, 16), float32
+```
+
+## Input and output
+
+Inputs are a nonnegative integer label volume and a CT volume in HU on the same 3D
+grid. Organ profiles give each tissue's SUV mean, standard deviation and label
+values; scanner profiles give resolution (FWHM), scatter, randoms and counts.
+
+The output is a float32 SUVbw MLX array with the input shape. To add lesions, use
+`fdg_pet_ct_mlx.lesion.apply_lesion_uptake` with a lesion profile.
+
+Profile validation, resampling and file I/O are up to you. This is image-space
+synthesis; it does not simulate projection physics or reconstruction.
+
+## Technical details
+
+Activity synthesis and scanner effects operate on MLX arrays in float32.
+The acquisition model approximates blur, scatter, randoms and count noise in
+image space. Profiles, numerical contracts and development commands are described
+in [docs/technical.md](https://github.com/MedMLX/fdg-pet-ct-mlx/blob/main/docs/technical.md).
+
+## Intended use
+
+Research software, for research and education only; not for clinical diagnosis or
+treatment decisions. The output is a synthetic image from a simple image-space model, not
+a simulation of a real scanner. Outputs require human review.
+
+## License
+
+Apache-2.0; see [LICENSE](https://github.com/MedMLX/fdg-pet-ct-mlx/blob/main/LICENSE).
+See [THIRD_PARTY_NOTICES.md](https://github.com/MedMLX/fdg-pet-ct-mlx/blob/main/THIRD_PARTY_NOTICES.md) for dependency attribution.
+
+## Implementation mapping
+
+[Central implementation map](https://github.com/MedMLX/Med-MLX/blob/main/implementation-maps/fdg-pet-ct-mlx.json) records upstream-to-native changes, source references and qualification scope.

fdg_pet_ct_mlx-0.2.1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third-party notices
+
+The image-space FDG synthesis implementation is MedMLX-authored code licensed
+under [Apache-2.0](LICENSE). It does not distribute a pretrained model.
+
+## Dependencies
+
+MLX and NumPy provide array operations; the runtime, image-I/O and development
+dependencies are declared in [pyproject.toml](pyproject.toml). These packages are
+installed separately and retain their respective licenses. SciPy is used as an
+independent numerical reference in the tests.
+
+Input medical images and label maps are supplied by the caller. Their original
+dataset or provider terms apply independently of this package's source license.

fdg_pet_ct_mlx-0.2.1/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fdg-pet-ct-mlx"
+version = "0.2.1"
+description = "Native MLX FDG PET image synthesis"
+readme = "README.md"
+classifiers = ["Operating System :: MacOS :: MacOS X"]
+requires-python = ">=3.13,<3.15"
+license = "Apache-2.0"
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
+authors = [{ name = "Joseph Sandoval" }, { name = "Alfredo Sandoval Jr." }]
+dependencies = [
+  "medmlx-core==0.2.3",
+  "mlx>=0.32.4,<1",
+  "numpy>=2.0,<3",
+]
+
+[project.optional-dependencies]
+conversion = ["torch>=2.13,<2.14"]
+dev = [
+  "pyright==1.1.414",
+  "pytest>=8.4,<10",
+  "ruff>=0.13,<1",
+  "scipy>=1.13,<2",
+  "scipy-stubs>=1.18,<1.19",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fdg_pet_ct_mlx"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-config --strict-markers"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+extend-select = ["TID251", "TID252", "ANN401"]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.pyright]
+include = ["src","tests"]
+extraPaths = ["src"]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+enableTypeIgnoreComments = false
+reportUnnecessaryTypeIgnoreComment = "error"
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"typing.Any" = {msg = "Use a precise type and parse untyped values at the boundary."}
+"typing_extensions.Any" = {msg = "Use a precise type and parse untyped values at the boundary."}
+
+[tool.uv]
+constraint-dependencies = ["setuptools>=84.1.0", "filelock>=4.2.1", ]
+
+[tool.uv.sources]
+medmlx-core = { git = "https://github.com/MedMLX/medmlx.git", rev = "e765f0a94aa31e8dfcdc599e4a4206eaca84f8b0", subdirectory = "packages/core" }
+
+[tool.hatch.build.targets.sdist]
+exclude = ["AGENTS.md", "CLAUDE.md", ".claude", ".codex", ".cursor"]
+only-include = [
+  "src/fdg_pet_ct_mlx",
+  "pyproject.toml",
+  "README.md",
+  "LICENSE",
+  "THIRD_PARTY_NOTICES.md",
+]

fdg_pet_ct_mlx-0.2.1/src/fdg_pet_ct_mlx/__init__.py

@@ -0,0 +1,3 @@
+"""Native MLX FDG PET image synthesis."""
+
+__version__ = "0.2.1"

fdg_pet_ct_mlx-0.2.1/src/fdg_pet_ct_mlx/_typing.py

@@ -0,0 +1,68 @@
+"""Structural types for the subset of ``mlx.core`` used by this package.
+
+Every public function takes the MLX module as an explicit ``mx`` argument. Pass
+``mlx.core`` itself (or the module returned by ``medmlx_core.runtime.import_mlx``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from mlx.core import Dtype, array
+
+
+class RandomRuntime(Protocol):
+    """The ``mx.random`` functions used for seeded noise."""
+
+    def key(self, seed: int) -> array: ...
+    def normal(
+        self, shape: Sequence[int], dtype: Dtype, *, key: array | None = None
+    ) -> array: ...
+
+
+class FdgRuntime(Protocol):
+    """The ``mlx.core`` dtypes and operations used by the FDG kernels."""
+
+    @property
+    def array(self) -> type[array]: ...
+    @property
+    def float32(self) -> Dtype: ...
+    @property
+    def int32(self) -> Dtype: ...
+    @property
+    def int64(self) -> Dtype: ...
+    @property
+    def uint32(self) -> Dtype: ...
+    @property
+    def complex64(self) -> Dtype: ...
+    @property
+    def bool_(self) -> Dtype: ...
+    @property
+    def random(self) -> RandomRuntime: ...
+    def eval(self, *args: array) -> None: ...
+    def zeros(self, shape: Sequence[int], *, dtype: Dtype) -> array: ...
+    def ones(self, shape: Sequence[int], *, dtype: Dtype) -> array: ...
+    def full(self, shape: Sequence[int], vals: float, *, dtype: Dtype) -> array: ...
+    def reshape(self, a: array, /, shape: Sequence[int]) -> array: ...
+    def zeros_like(self, a: array, /) -> array: ...
+    def arange(self, start: int, stop: int, *, dtype: Dtype) -> array: ...
+    def all(self, a: array, /) -> array: ...
+    def isfinite(self, a: array, /) -> array: ...
+    def min(self, a: array, /) -> array: ...
+    def max(self, a: array, /) -> array: ...
+    def sum(self, a: array, /) -> array: ...
+    def mean(self, a: array, /) -> array: ...
+    def floor(self, a: array, /) -> array: ...
+    def exp(self, a: array, /) -> array: ...
+    def sqrt(self, a: array, /) -> array: ...
+    def clip(self, a: array, /, a_min: float, a_max: float) -> array: ...
+    def maximum(self, a: array, b: array | float, /) -> array: ...
+    def where(self, condition: array, x: array, y: array | int, /) -> array: ...
+    def logical_or(self, a: array, b: array, /) -> array: ...
+    def logical_and(self, a: array, b: array, /) -> array: ...
+    def moveaxis(self, a: array, /, source: int, destination: int) -> array: ...
+    def pad(self, a: array, pad_width: list[tuple[int, int]]) -> array: ...
+    def conv1d(self, input: array, weight: array, /) -> array: ...
+    def conv3d(self, input: array, weight: array, /) -> array: ...

fdg_pet_ct_mlx-0.2.1/src/fdg_pet_ct_mlx/acquisition.py

@@ -0,0 +1,140 @@
+"""Image-space approximation of a reconstructed PET volume.
+
+This applies simple multiplicative, additive, blur and noise steps directly to the
+SUV image. It does not simulate projection physics, attenuation correction or
+reconstruction.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING
+
+from fdg_pet_ct_mlx._typing import FdgRuntime
+from fdg_pet_ct_mlx.profiles import FdgScannerProfile
+
+if TYPE_CHECKING:
+    from mlx.core import array
+
+# FWHM = 2*sqrt(2*ln 2) * sigma for a Gaussian (about 2.3548).
+_FWHM_SIGMA = 2.0 * math.sqrt(2.0 * math.log(2.0))
+
+
+def apply_acquisition_model(
+    activity: array,
+    ct_hu: array,
+    *,
+    scanner: FdgScannerProfile,
+    count_level: float,
+    spacing_mm: tuple[float, float, float],
+    seed: int,
+    mx: FdgRuntime,
+) -> array:
+    """Turn a synthetic activity volume into a PET-like SUV volume.
+
+    Steps, in order, all in float32:
+
+    1. Multiply by a CT-dependent factor ``exp(-0.02 * clip((HU + 1000) / 1000, 0, 3))``.
+       This is a fixed heuristic, not a physical attenuation model: air gives 1.0 and
+       HU of 2000 or more gives about 0.94.
+    2. If ``scatter_fraction + randoms_fraction > 0``, add a uniform offset equal to
+       that sum times the mean of the whole volume (background voxels included, so the
+       offset depends on the grid extent).
+    3. Blur with ``gaussian_blur`` using ``scanner.fwhm_mm`` and ``spacing_mm``.
+    4. Convert to expected counts ``lam = SUV * counts_per_suv * count_level``, draw
+       ``max(lam + sqrt(max(lam, 0)) * N(0, 1), 0)`` (a Gaussian approximation to
+       Poisson noise, independent per voxel), and divide back by the same factor.
+
+    Args:
+        activity: SUV volume, shape ``(X, Y, Z)``.
+        ct_hu: CT in Hounsfield units on the same grid and in the same axis order as
+            ``activity``. Registration and resampling are the caller's job.
+        scanner: Scatter/randoms fractions, blur FWHM and counts per SUV.
+        count_level: Multiplier on ``scanner.counts_per_suv``. The product must be
+            positive; it is not checked.
+        spacing_mm: Voxel spacing in mm for each array axis.
+        seed: Seed for the noise draw.
+        mx: The ``mlx.core`` module.
+
+    Returns:
+        Nonnegative float32 SUV array with the shape of ``activity``, already evaluated.
+
+    Raises:
+        ValueError: If ``activity`` and ``ct_hu`` have different shapes.
+    """
+
+    if activity.shape != ct_hu.shape:
+        raise ValueError("activity and CT must share one grid")
+    hu = ct_hu.astype(mx.float32)
+    shifted = (hu + mx.array(1000.0, dtype=mx.float32)) / mx.array(1000.0, dtype=mx.float32)
+    mu = mx.clip(shifted, 0.0, 3.0)
+    residual = mx.exp(mx.array(-0.02, dtype=mx.float32) * mu)
+    volume = activity.astype(mx.float32) * residual
+    floor_fraction = scanner.scatter_fraction + scanner.randoms_fraction
+    if floor_fraction > 0.0:
+        volume = volume + mx.mean(volume) * mx.array(floor_fraction, dtype=mx.float32)
+    volume = gaussian_blur(volume, scanner.fwhm_mm, spacing_mm, mx)
+    counts_per = scanner.counts_per_suv * count_level
+    lam = volume * mx.array(counts_per, dtype=mx.float32)
+    noise = mx.random.normal(volume.shape, dtype=mx.float32, key=mx.random.key(seed))
+    zero = mx.array(0.0, dtype=mx.float32)
+    counts = mx.maximum(lam + mx.sqrt(mx.maximum(lam, 0.0)) * noise, zero)
+    suv = counts / mx.array(counts_per, dtype=mx.float32)
+    mx.eval(suv)
+    return suv
+
+
+def gaussian_blur(
+    volume: array,
+    fwhm_mm: tuple[float, float, float],
+    spacing_mm: tuple[float, float, float],
+    mx: FdgRuntime,
+) -> array:
+    """Blur a volume with a separable Gaussian, one 1-D pass per array axis.
+
+    For each axis, ``sigma = fwhm / (2 * sqrt(2 * ln 2)) / spacing`` in voxels. The
+    kernel is truncated at ``ceil(3 * sigma)`` voxels (at least 1) and normalized to
+    sum to 1. The volume is zero-padded, so values near the borders are pulled toward
+    zero. An axis with ``fwhm <= 0`` is skipped.
+
+    Args:
+        volume: Array with one axis per entry of ``fwhm_mm`` (3-D in this package).
+        fwhm_mm: Blur FWHM in mm for each array axis.
+        spacing_mm: Voxel spacing in mm for each array axis; must be positive.
+        mx: The ``mlx.core`` module.
+
+    Returns:
+        Float32 array with the shape of ``volume``, already evaluated.
+    """
+
+    blurred = volume.astype(mx.float32)
+    for axis, (fwhm, spacing) in enumerate(zip(fwhm_mm, spacing_mm, strict=True)):
+        sigma = (fwhm / _FWHM_SIGMA) / spacing
+        if sigma <= 0.0:
+            continue
+        blurred = _smooth_axis(blurred, _gaussian_kernel(sigma, mx), axis, mx)
+    mx.eval(blurred)
+    return blurred
+
+
+def _gaussian_kernel(sigma: float, mx: FdgRuntime) -> array:
+    # Truncate at 3 sigma; the kernel is symmetric, so conv1d's correlation equals
+    # convolution.
+    radius = max(1, math.ceil(3.0 * sigma))
+    axis = mx.arange(-radius, radius + 1, dtype=mx.float32)
+    scaled = axis / mx.array(sigma, dtype=mx.float32)
+    kernel = mx.exp(mx.array(-0.5, dtype=mx.float32) * scaled**2)
+    return kernel / mx.sum(kernel)
+
+
+def _smooth_axis(volume: array, kernel: array, axis: int, mx: FdgRuntime) -> array:
+    # MLX convolutions are channels-last: (batch, length, channels). Fold every
+    # other axis into the batch and use a single channel.
+    moved = mx.moveaxis(volume, axis, -1)
+    length = moved.shape[-1]
+    flat = mx.reshape(moved, (-1, length, 1))
+    weight = mx.reshape(kernel, (1, -1, 1))
+    pad = kernel.shape[0] // 2
+    padded = mx.pad(flat, [(0, 0), (pad, pad), (0, 0)])
+    out = mx.conv1d(padded, weight)
+    return mx.moveaxis(mx.reshape(out, moved.shape), -1, axis)

fdg_pet_ct_mlx-0.2.1/src/fdg_pet_ct_mlx/activity.py

@@ -0,0 +1,88 @@
+"""Per-voxel FDG activity (SUV) drawn from tissue statistics selected by label ID."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from fdg_pet_ct_mlx._typing import FdgRuntime
+from fdg_pet_ct_mlx.profiles import FdgOrganProfile
+
+if TYPE_CHECKING:
+    from mlx.core import array
+
+# MAISI label IDs run 0..200 (200 is the body envelope label in nv-generate-mlx), so the
+# lookup tables always cover at least that range.
+_LOOKUP_MIN = 201
+
+
+def synthesize_activity_map(
+    labels: array,
+    profile: FdgOrganProfile,
+    *,
+    seed: int,
+    mx: FdgRuntime,
+) -> array:
+    """Draw a nonnegative float32 SUV volume on the label grid.
+
+    Each voxel is ``max(mean[label] + std[label] * N(0, 1), 0)``, with independent
+    unit-normal draws per voxel and the profile's SUV mean and standard deviation for
+    that label. Means come from ``profile.lookup_table`` and standard deviations from
+    ``profile.tissues``. IDs that no tissue lists get the ``unclassified_soft_tissue``
+    standard deviation and, by the lookup-table convention, its mean. IDs at or above
+    the lookup size use the unclassified mean and standard deviation directly.
+
+    Args:
+        labels: MAISI label volume, shape ``(X, Y, Z)``. Any real integer or float
+            dtype is accepted if every value is finite, integral and in
+            ``[0, 2**31 - 1]``.
+        profile: Organ activity profile.
+        seed: Seed for the noise draw.
+        mx: The ``mlx.core`` module.
+
+    Returns:
+        Float32 SUV array with the shape of ``labels``, already evaluated.
+
+    Raises:
+        ValueError: If ``labels`` is not 3-D, is empty, is boolean or complex, or has
+            non-finite, negative, out-of-range or non-integral values.
+        KeyError: If ``profile.tissues`` has no ``"unclassified_soft_tissue"`` entry.
+    """
+
+    if labels.ndim != 3:
+        raise ValueError("activity labels must be a 3D volume")
+    if labels.size == 0:
+        raise ValueError("activity labels must be nonempty")
+    if labels.dtype == mx.complex64 or labels.dtype == mx.bool_:
+        raise ValueError("activity labels must contain real integral identifiers")
+    if not bool(mx.all(mx.isfinite(labels)).item()):
+        raise ValueError("activity labels must be finite")
+    lowest = cast(int | float, mx.min(labels).item())
+    highest_value = cast(int | float, mx.max(labels).item())
+    if lowest < 0 or highest_value > 2**31 - 1:
+        raise ValueError("activity labels must be in the nonnegative int32 range")
+    if not bool(mx.all(labels == mx.floor(labels)).item()):
+        raise ValueError("activity labels must be integral")
+    ids = labels.astype(mx.int32)
+    profile_labels = [label for spec in profile.tissues.values() for label in spec.maisi_labels]
+    size = max(max(profile_labels, default=0) + 1, _LOOKUP_MIN)
+    # Send every ID >= size to one extra table slot holding the unclassified values, so
+    # table size does not depend on the largest input ID.
+    ids = mx.where(ids < size, ids, size)
+    default = profile.tissues["unclassified_soft_tissue"]
+    means = mx.array((*profile.lookup_table(size), default.suv_mean), dtype=mx.float32)
+    stds = mx.array((*_std_table(profile, size), default.suv_std), dtype=mx.float32)
+    base = means[ids]
+    noise = mx.random.normal(ids.shape, dtype=mx.float32, key=mx.random.key(seed))
+    activity = mx.maximum(base + stds[ids] * noise, mx.array(0.0, dtype=mx.float32))
+    mx.eval(activity)
+    return activity
+
+
+def _std_table(profile: FdgOrganProfile, size: int) -> tuple[float, ...]:
+    unclassified = profile.tissues["unclassified_soft_tissue"].suv_std
+    table = [unclassified] * size
+    for spec in profile.tissues.values():
+        for label in spec.maisi_labels:
+            if label < size:
+                table[label] = spec.suv_std
+    return tuple(table)

fdg_pet_ct_mlx-0.2.1/src/fdg_pet_ct_mlx/lesion.py

@@ -0,0 +1,170 @@
+"""FDG-avid lesion uptake applied to an activity volume, selected by label ID.
+
+Lesion geometry comes only from the label volume. A requested necrotic core that
+the labeled lesion cannot support raises ``InvalidInputError``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from medmlx_core.errors import InvalidInputError
+
+from fdg_pet_ct_mlx._typing import FdgRuntime
+from fdg_pet_ct_mlx.acquisition import gaussian_blur
+from fdg_pet_ct_mlx.profiles import FdgLesionProfile, FdgOrganProfile
+
+if TYPE_CHECKING:
+    from mlx.core import array
+
+
+def apply_lesion_uptake(
+    activity: array,
+    labels: array,
+    *,
+    organ: FdgOrganProfile,
+    lesion: FdgLesionProfile,
+    spacing_mm: tuple[float, float, float],
+    seed: int,
+    mx: FdgRuntime,
+) -> array:
+    """Replace activity in FDG-avid lesion voxels with lesion uptake.
+
+    Let ``host`` be the ``suv_mean`` of the tissue that ``lesion.host_tissue`` assigns
+    to each avid voxel's label. In avid voxels the input activity is discarded and
+    replaced by:
+
+    1. ``host * tumor_to_background``;
+    2. if ``heterogeneity > 0``, times ``max(1 + heterogeneity * N(0, 1), 0)``, with
+       independent draws per voxel;
+    3. if ``necrosis_fraction > 0``, ``0.2 * host`` in the necrotic core (the 0.2 is a
+       fixed constant, not a profile field). The core is what remains after
+       repeatedly eroding the union of all avid voxels with a full 3x3x3 neighborhood
+       until its voxel count is at most ``necrosis_fraction`` times the avid count.
+       Erosion removes whole shells, so the core can be smaller than requested.
+       Voxels at the volume border erode because the mask is zero-padded;
+    4. if ``spillover_fwhm_mm > 0``, avid voxels are reset to ``host`` and the excess
+       ``(step 3 result - host)`` (negative in a necrotic core), blurred with an
+       isotropic Gaussian (``gaussian_blur``), is added to the whole volume, so lesion
+       SUV leaks into neighbors.
+
+    The result is clipped at zero. Voxels whose label is not in
+    ``avid_maisi_labels`` (for example non-avid cysts) keep their input activity, apart
+    from spill-over.
+
+    Args:
+        activity: SUV volume, shape ``(X, Y, Z)``, as from ``synthesize_activity_map``.
+        labels: MAISI label volume on the same grid and axis order as ``activity``; the
+            shapes are not checked. Values are cast to int32 without validation.
+        organ: Organ profile; supplies the host SUV means.
+        lesion: Lesion profile.
+        spacing_mm: Voxel spacing in mm for each array axis (used for spill-over).
+        seed: Seed for the heterogeneity noise; unused when ``heterogeneity == 0``.
+        mx: The ``mlx.core`` module.
+
+    Returns:
+        Float32 SUV array with the shape of ``activity``, evaluated with ``mx.eval``. If
+        no voxel carries an avid label and ``necrosis_fraction == 0``, ``activity`` itself
+        is returned as is (not a copy, and not re-evaluated).
+
+    Raises:
+        InvalidInputError: If ``necrosis_fraction > 0`` and there are no avid voxels,
+            or the lesion is too small to erode down to the requested core. This is a
+            ``ValueError`` subclass.
+        KeyError: If ``lesion.host_tissue`` names a tissue missing from ``organ.tissues``.
+    """
+
+    ids = labels.astype(mx.int32)
+    avid = _label_mask(ids, lesion.avid_maisi_labels, mx)
+    mx.eval(avid)
+    avid_voxels = int(cast(int, mx.sum(avid).item()))
+    if avid_voxels == 0:
+        if lesion.necrosis_fraction > 0.0:
+            raise InvalidInputError(
+                "necrosis_fraction requires FDG-avid lesion voxels in the label volume"
+            )
+        return activity
+
+    host = _host_map(ids, organ, lesion, mx)
+    target = host * mx.array(lesion.tumor_to_background, dtype=mx.float32)
+    if lesion.heterogeneity > 0.0:
+        noise = mx.random.normal(ids.shape, dtype=mx.float32, key=mx.random.key(seed))
+        scale = (
+            mx.array(1.0, dtype=mx.float32)
+            + mx.array(lesion.heterogeneity, dtype=mx.float32) * noise
+        )
+        target = target * mx.maximum(scale, mx.array(0.0, dtype=mx.float32))
+    if lesion.necrosis_fraction > 0.0:
+        necrotic = _necrosis_mask(avid, lesion.necrosis_fraction, mx)
+        target = mx.where(
+            necrotic,
+            host * mx.array(0.2, dtype=mx.float32),
+            target,
+        )
+    updated = mx.where(avid, target, activity)
+    if lesion.spillover_fwhm_mm > 0.0:
+        excess = mx.where(avid, updated - host, mx.zeros_like(updated))
+        spilled = gaussian_blur(
+            excess,
+            (
+                lesion.spillover_fwhm_mm,
+                lesion.spillover_fwhm_mm,
+                lesion.spillover_fwhm_mm,
+            ),
+            spacing_mm,
+            mx,
+        )
+        updated = mx.where(avid, host, activity) + spilled
+    result = mx.maximum(updated, mx.array(0.0, dtype=mx.float32))
+    mx.eval(result)
+    return result
+
+
+def _label_mask(ids: array, labels: tuple[int, ...], mx: FdgRuntime) -> array:
+    mask = mx.zeros(ids.shape, dtype=mx.bool_)
+    for label in labels:
+        mask = mx.logical_or(mask, ids == label)
+    return mask
+
+
+def _host_map(
+    ids: array,
+    organ: FdgOrganProfile,
+    lesion: FdgLesionProfile,
+    mx: FdgRuntime,
+) -> array:
+    host = mx.zeros(ids.shape, dtype=mx.float32)
+    for label, tissue in lesion.host_tissue.items():
+        value = mx.array(organ.tissues[tissue].suv_mean, dtype=mx.float32)
+        host = mx.where(ids == label, value, host)
+    return host
+
+
+def _necrosis_mask(avid: array, fraction: float, mx: FdgRuntime) -> array:
+    remaining = avid.astype(mx.float32)
+    # The mask is float32, so .item() returns a Python float; the cast only narrows the
+    # type for the checker.
+    core_target = float(cast(float, mx.sum(remaining).item())) * fraction
+    if core_target <= 0.0:
+        raise InvalidInputError("necrosis_fraction leaves no remaining lesion voxels")
+    while float(cast(float, mx.sum(remaining).item())) > core_target:
+        eroded = _erode(remaining, mx)
+        eroded_count = float(cast(float, mx.sum(eroded).item()))
+        current = float(cast(float, mx.sum(remaining).item()))
+        if eroded_count <= 0.0 or eroded_count >= current:
+            raise InvalidInputError(
+                "necrosis_fraction requires a lesion large enough to erode to the "
+                "requested necrotic core fraction"
+            )
+        remaining = eroded
+    return mx.logical_and(avid, remaining >= mx.array(0.5, dtype=mx.float32))
+
+
+def _erode(mask: array, mx: FdgRuntime) -> array:
+    volume = mask.astype(mx.float32)[None, ..., None]
+    weight = mx.ones((1, 3, 3, 3, 1), dtype=mx.float32)
+    padded = mx.pad(volume, [(0, 0), (1, 1), (1, 1), (1, 1), (0, 0)])
+    neighbor_sum = mx.conv3d(padded, weight)
+    # A voxel survives only if all 27 voxels of its 3x3x3 box are set; 26.5 avoids
+    # an exact float comparison against 27.
+    return (neighbor_sum[0, ..., 0] >= mx.array(26.5, dtype=mx.float32)).astype(mx.float32)

fdg_pet_ct_mlx-0.2.1/src/fdg_pet_ct_mlx/profiles.py

@@ -0,0 +1,98 @@
+"""Structural (duck-typed) profile inputs for activity, scanner and lesion settings.
+
+The package does not ship profile data, validate profile values or read profile
+files. Callers pass any object with these attributes. Label IDs are MAISI label
+IDs (the NV-Generate/MAISI label vocabulary); SUV values follow the body-weight
+convention but no weight or dose normalization is applied here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol
+
+
+class TissueActivity(Protocol):
+    """Activity distribution for one tissue class.
+
+    Attributes:
+        suv_mean: Mean SUV of the tissue.
+        suv_std: Standard deviation of the per-voxel Gaussian SUV noise, in SUV.
+        maisi_labels: MAISI label IDs belonging to this tissue.
+    """
+
+    @property
+    def suv_mean(self) -> float: ...
+    @property
+    def suv_std(self) -> float: ...
+    @property
+    def maisi_labels(self) -> tuple[int, ...]: ...
+
+
+class FdgOrganProfile(Protocol):
+    """Organ-level activity: tissue classes keyed by name.
+
+    ``tissues`` must contain ``"unclassified_soft_tissue"``, which supplies the mean
+    and standard deviation for label IDs that no tissue lists. If a label ID is
+    listed by several tissues, the one later in ``tissues`` supplies the standard
+    deviation; the mean comes from ``lookup_table``.
+    """
+
+    @property
+    def tissues(self) -> Mapping[str, TissueActivity]: ...
+    def lookup_table(self, size: int) -> tuple[float, ...]:
+        """Return the mean SUV for label IDs ``0..size-1`` as a tuple of length ``size``."""
+        ...
+
+
+class FdgScannerProfile(Protocol):
+    """Image-space scanner approximation settings.
+
+    Attributes:
+        scatter_fraction: Unitless; with ``randoms_fraction``, sets a uniform offset
+            equal to the volume mean times their sum.
+        randoms_fraction: Unitless; see ``scatter_fraction``.
+        fwhm_mm: Gaussian blur FWHM in mm, one entry per array axis. A value of 0 skips
+            that axis.
+        counts_per_suv: Expected counts per voxel per unit SUV at ``count_level=1``.
+    """
+
+    @property
+    def scatter_fraction(self) -> float: ...
+    @property
+    def randoms_fraction(self) -> float: ...
+    @property
+    def fwhm_mm(self) -> tuple[float, float, float]: ...
+    @property
+    def counts_per_suv(self) -> float: ...
+
+
+class FdgLesionProfile(Protocol):
+    """FDG-avid lesion settings.
+
+    Attributes:
+        avid_maisi_labels: MAISI label IDs whose voxels are treated as FDG-avid lesion.
+        host_tissue: Maps each avid label ID to a key of ``FdgOrganProfile.tissues``;
+            that tissue's ``suv_mean`` is the voxel's host (background) SUV. An avid
+            label with no entry has host SUV 0.
+        tumor_to_background: Lesion mean SUV as a multiple of the host SUV.
+        heterogeneity: Relative standard deviation of multiplicative Gaussian noise
+            on lesion voxels; 0 disables it.
+        necrosis_fraction: Target fraction (by voxel count, over all avid voxels) of
+            the lesion set to the necrotic core; 0 disables it.
+        spillover_fwhm_mm: FWHM in mm of an isotropic Gaussian that spreads the
+            lesion's excess SUV into neighboring voxels; 0 disables it.
+    """
+
+    @property
+    def avid_maisi_labels(self) -> tuple[int, ...]: ...
+    @property
+    def host_tissue(self) -> Mapping[int, str]: ...
+    @property
+    def tumor_to_background(self) -> float: ...
+    @property
+    def heterogeneity(self) -> float: ...
+    @property
+    def necrosis_fraction(self) -> float: ...
+    @property
+    def spillover_fwhm_mm(self) -> float: ...