Data

def set_mu(
    self,
    mu_water: float | torch.Tensor | None = None,
    mu_bone: float | torch.Tensor | None = None,
    hu_bone: float | torch.Tensor | None = None,
) -> None:
    """Recompute the LAC cache from new conversion parameters.

    Prefer this over setting `mu_water`, `mu_bone`, and `hu_bone` individually
    when calling under `torch.compile`, as it performs a single tensor op and
    avoids Python-side attribute mutations that would cause graph breaks.
    The stored scalar params (`self.mu_water` etc.) are intentionally *not*
    updated here; they remain as the baseline defaults.
    """
    self._image_mu_cache = hu_to_mu(
        self._image_hu,
        mu_water if mu_water is not None else self.mu_water,
        mu_bone if mu_bone is not None else self.mu_bone,
        hu_bone if hu_bone is not None else self.hu_bone,
    )

@classmethod
def from_filepath(
    cls,
    imagepath: str | Path,
    labelpath: str | Path | None = None,
    max_label: int | None = None,
    **mu,
) -> "Subject":
    """Load a subject from any TorchIO-supported file path.

    Args:
        imagepath: Path to the CT volume.
        labelpath: Optional path to a label map.
        max_label: Override the maximum label index. If provided, `n_classes`
            is set to `max_label + 1` instead of being inferred from the data.
        **mu: HU → μ conversion params. See `from_images` for details.
    """
    _validate_mu_kwargs(mu)
    image = ScalarImage(imagepath)
    label = LabelMap(labelpath) if labelpath is not None else None
    return cls.from_images(image, label, max_label, **mu)

@classmethod
def from_images(
    cls,
    image: ScalarImage,
    label: LabelMap | None = None,
    max_label: int | None = None,
    **mu,
) -> "Subject":
    """Construct a subject from TorchIO image objects.

    Args:
        image: CT volume as a `ScalarImage`.
        label: Optional segmentation as a `LabelMap`.
        max_label: Override the maximum label index. If provided, `n_classes`
            is set to `max_label + 1` instead of being inferred from the data.
        **mu: HU → μ conversion params (`convert_to_mu`, `mu_water`, `mu_bone`,
            `hu_bone`). Unspecified keys fall back to class-level defaults.

    Raises:
        TypeError: If any unrecognised key is passed via `**mu`.
    """
    _validate_mu_kwargs(mu)

    # Affine: invert in float64 for numerical accuracy, then downcast
    voxel_to_world_f64 = torch.from_numpy(image.affine).to(torch.float64)
    voxel_to_world = voxel_to_world_f64.to(torch.float32)
    world_to_voxel = voxel_to_world_f64.inverse().to(torch.float32)

    # Store raw HU — conversion is applied lazily via .image
    imagedata = cls._to_bcdhw(image.data).to(torch.float32)

    if label is not None:
        labeldata = cls._to_bcdhw(label.data).to(torch.float32)
    else:
        labeldata = torch.zeros_like(imagedata)

    isocenter = torch.tensor(image.get_center(), dtype=torch.float32)
    voxel_to_grid = cls._make_voxel_to_grid(imagedata.shape)

    return cls(
        imagedata,
        labeldata,
        voxel_to_world,
        world_to_voxel,
        voxel_to_grid,
        isocenter,
        max_label,
        **mu,
    )