Image

def get_inverse_transform(
    self,
    *,
    warn: bool = True,
    ignore_intensity: bool = False,
) -> Any:
    """Get a composed transform that inverts the applied history.

    Returns a [`Compose`][torchio.Compose] of the inverse of each
    applied transform, in reverse order. Non-invertible transforms
    are skipped (with a warning if `warn=True`).

    Args:
        warn: Issue a warning for non-invertible transforms.
        ignore_intensity: Skip all intensity transforms.

    Returns:
        A `Compose` transform that undoes the history.
    """
    from ..transforms.inverse import get_inverse_transform

    return get_inverse_transform(
        self.applied_transforms,
        warn=warn,
        ignore_intensity=ignore_intensity,
    )

def apply_inverse_transform(self, **kwargs: Any) -> Self:
    """Apply the inverse of all applied transforms, in reverse order.

    Non-invertible transforms are skipped. Intensity transforms
    can be ignored with `ignore_intensity=True`.

    Args:
        **kwargs: Forwarded to
            `get_inverse_transform()` (`warn`,
            `ignore_intensity`).

    Returns:
        Data with transforms undone.

    Examples:
        >>> transformed = transform(subject)
        >>> restored = transformed.apply_inverse_transform()
    """
    inverse_transform = self.get_inverse_transform(**kwargs)
    result = inverse_transform(self)
    if hasattr(result, "applied_transforms"):
        result.applied_transforms = []
    return result

def clear_history(self) -> None:
    """Remove all applied transform records."""
    self.applied_transforms = []

def load(self) -> None:
    """Load data from disk into memory."""
    if self._data is not None:
        return
    if self._try_load_via_backend():
        return
    if self._path is None:
        msg = "Cannot load: no path or backend set"
        raise RuntimeError(msg)
    tensor, affine_array = self._reader(self._path, **self._reader_kwargs)
    self._data = tensor
    if self._affine is None:
        self._affine = AffineMatrix(affine_array)
    self._apply_channels_last()

def set_data(self, tensor: TypeImageData | np.ndarray) -> None:
    """Replace the image data with a new tensor.

    The lazy backend is refreshed so that `dataobj`, `dtype`, and
    `shape` stay coherent with the new tensor. The affine is preserved when
    one is set or can be read from the source header; for an image created
    without any source (e.g. `ScalarImage()` then `set_data`) it defaults to
    the identity affine.

    Args:
        tensor: 4D tensor with shape (C, I, J, K).
    """
    self._data = self._parse_tensor(tensor)
    self._refresh_backend_from_data()

def to(self, *args: Any, **kwargs: Any) -> Self:
    """Move image data and affine to a device and/or cast to a dtype.

    Accepts the same arguments as `torch.Tensor.to()`.

    Returns:
        `self` (modified in-place).
    """
    self._data = self.data.to(*args, **kwargs)
    if self._affine is not None:
        self._affine.to(*args, **kwargs)
    self._refresh_backend_from_data()
    return self

def numpy(self) -> np.ndarray:
    """Return the image data as a NumPy array.

    If the data is not loaded, reads it from disk first. The returned
    array shares memory with the tensor if possible (i.e., if the
    tensor is on CPU and not a view).

    Returns:
        4D array with shape (C, I, J, K).
    """
    return self.data.cpu().numpy()

def new_like(
    self,
    *,
    data: TypeImageData,
    affine: AffineMatrix | npt.ArrayLike | None = None,
) -> Self:
    r"""Create a new image of the same class with new data.

    Preserves metadata, annotations, and affine. Uses the existing
    affine unless a new one is provided. Works correctly with custom
    subclasses.

    Args:
        data: New 4D [`torch.Tensor`][torch.Tensor] with shape
            $(C, I, J, K)$.
        affine: New $4 \times 4$ affine. If `None`, uses `self.affine`.
    """
    new_affine = (
        self._parse_affine(affine) if affine is not None else self.affine.clone()
    )
    points_copy, bboxes_copy = self._deep_copy_annotations()
    return type(self)(
        data,
        affine=new_affine,
        points=points_copy,
        bounding_boxes=bboxes_copy,
        **dict(self._metadata),
    )

def save(
    self,
    path: str | Path,
    **kwargs: Any,
) -> None:
    """Save the image to a file.

    NIfTI-Zarr (`.nii.zarr`) files are written via `niizarr`
    (requires the `zarr` extra). All other formats are written
    with [SimpleITK](https://simpleitk.org/).

    Args:
        path: Output file path. The format is inferred from the
            extension.
        **kwargs: Extra keyword arguments forwarded to the
            writer. For SimpleITK formats these are passed to
            `SimpleITK.WriteImage()`.
    """
    path = Path(path)
    if is_nifti_zarr(path):
        self._save_nii_zarr(path)
    else:
        self._save_sitk(path, **kwargs)

def plot(self, **kwargs: Any) -> Any:
    """Plot 3 orthogonal slices of the image.

    Requires the `[plot]` extras (`pip install torchio[plot]`).
    See [`plot_image`][torchio.visualization.plot_image] for the
    full list of keyword arguments.
    """
    from ..visualization import plot_image

    return plot_image(self, **kwargs)

def plot_interactive(self, *, height: int = 300) -> Any:
    """Show an interactive NiiVue viewer in Jupyter.

    Requires `ipyniivue` (`pip install torchio[niivue]`).

    The widget supports scrolling through slices, zooming, and
    crosshair navigation.  Left hemisphere is displayed on the
    right side of the screen (radiological convention).

    Args:
        height: Height of the viewer in pixels.

    Returns:
        An `ipyniivue.NiiVue` widget.

    Raises:
        ImportError: If `ipyniivue` is not installed.
    """
    import tempfile

    import nibabel as nib
    import numpy as np

    from ..external.imports import get_ipyniivue

    nv = get_ipyniivue()

    data = self.data.cpu().float().numpy()
    if data.ndim == 4 and data.shape[0] == 1:
        data = data[0]
    affine = np.asarray(self.affine.data, dtype=np.float64)
    nii = nib.Nifti1Image(data, affine)
    with tempfile.NamedTemporaryFile(suffix=".nii.gz", delete=False) as f:
        nib.save(nii, f.name)
        path = f.name

    widget = nv.NiiVue(height=height)
    widget.opts.is_radiological_convention = True
    widget.add_volume(nv.Volume(path=path))
    return widget

def to_gif(
    self,
    output_path: str | Path | None = None,
    *,
    seconds: float = 5.0,
    direction: str = "I",
    loop: int = 0,
    rescale: bool = True,
    optimize: bool = True,
    reverse: bool = False,
) -> Any:
    """Save an animated GIF sweeping through slices.

    Requires `Pillow` (`pip install torchio[plot]`).

    When *output_path* is `None` and the code is running inside
    a Jupyter notebook, the GIF is written to a temporary file and
    returned as an `IPython.display.Image` for inline display.
    Outside Jupyter, *output_path* is required.

    Args:
        output_path: Path to the output `.gif` file.  `None`
            to auto-create a temporary file (Jupyter only).
        seconds: Duration of the full animation in seconds.
        direction: Anatomical sweep direction (`"I"`, `"S"`,
            `"A"`, `"P"`, `"R"`, or `"L"`).
        loop: Number of loops (0 = infinite).
        rescale: Rescale intensities to `[0, 255]`.
        optimize: Attempt to compress the GIF palette.
        reverse: Reverse the temporal order of frames.

    Returns:
        `IPython.display.Image` when running in Jupyter,
        `None` otherwise.

    Raises:
        ValueError: If *output_path* is `None` and the code is
            not running inside a Jupyter notebook.
    """
    output_path = _resolve_media_path(output_path, suffix=".gif")
    from ..visualization import make_gif

    make_gif(
        self,
        output_path,
        seconds=seconds,
        direction=direction,
        loop=loop,
        rescale=rescale,
        optimize=optimize,
        reverse=reverse,
    )
    if _in_jupyter():
        from IPython.display import Image as IPyImage

        return IPyImage(filename=str(output_path))
    return None

def to_video(
    self,
    output_path: str | Path | None = None,
    *,
    seconds: float = 5.0,
    direction: str = "I",
    verbosity: str = "error",
) -> Any:
    """Create an MP4 video sweeping through slices.

    Requires `ffmpeg-python` (`pip install torchio[video]`).

    When *output_path* is `None` and the code is running inside
    a Jupyter notebook, the video is written to a temporary file
    and returned as an `IPython.display.Video` for inline
    display.  Outside Jupyter, *output_path* is required.

    Args:
        output_path: Path to the output `.mp4` file.  `None`
            to auto-create a temporary file (Jupyter only).
        seconds: Duration of the full video in seconds.
        direction: Anatomical sweep direction (`"I"`, `"S"`,
            `"A"`, `"P"`, `"R"`, or `"L"`).
        verbosity: ffmpeg log level.

    Returns:
        `IPython.display.Video` when running in Jupyter,
        `None` otherwise.

    Raises:
        ValueError: If *output_path* is `None` and the code is
            not running inside a Jupyter notebook.
    """
    output_path = _resolve_media_path(output_path, suffix=".mp4")
    from ..visualization import make_video

    make_video(
        self,
        output_path,
        seconds=seconds,
        direction=direction,
        verbosity=verbosity,
    )
    if _in_jupyter():
        from IPython.display import Video

        return Video(
            str(output_path),
            embed=True,
            html_attributes="controls autoplay loop muted",
        )
    return None

def get_inverse_transform(
    self,
    *,
    warn: bool = True,
    ignore_intensity: bool = False,
) -> Any:
    """Get a composed transform that inverts the applied history.

    Returns a [`Compose`][torchio.Compose] of the inverse of each
    applied transform, in reverse order. Non-invertible transforms
    are skipped (with a warning if `warn=True`).

    Args:
        warn: Issue a warning for non-invertible transforms.
        ignore_intensity: Skip all intensity transforms.

    Returns:
        A `Compose` transform that undoes the history.
    """
    from ..transforms.inverse import get_inverse_transform

    return get_inverse_transform(
        self.applied_transforms,
        warn=warn,
        ignore_intensity=ignore_intensity,
    )

def apply_inverse_transform(self, **kwargs: Any) -> Self:
    """Apply the inverse of all applied transforms, in reverse order.

    Non-invertible transforms are skipped. Intensity transforms
    can be ignored with `ignore_intensity=True`.

    Args:
        **kwargs: Forwarded to
            `get_inverse_transform()` (`warn`,
            `ignore_intensity`).

    Returns:
        Data with transforms undone.

    Examples:
        >>> transformed = transform(subject)
        >>> restored = transformed.apply_inverse_transform()
    """
    inverse_transform = self.get_inverse_transform(**kwargs)
    result = inverse_transform(self)
    if hasattr(result, "applied_transforms"):
        result.applied_transforms = []
    return result

def clear_history(self) -> None:
    """Remove all applied transform records."""
    self.applied_transforms = []

def load(self) -> None:
    """Load data from disk into memory."""
    if self._data is not None:
        return
    if self._try_load_via_backend():
        return
    if self._path is None:
        msg = "Cannot load: no path or backend set"
        raise RuntimeError(msg)
    tensor, affine_array = self._reader(self._path, **self._reader_kwargs)
    self._data = tensor
    if self._affine is None:
        self._affine = AffineMatrix(affine_array)
    self._apply_channels_last()

def set_data(self, tensor: TypeImageData | np.ndarray) -> None:
    """Replace the image data with a new tensor.

    The lazy backend is refreshed so that `dataobj`, `dtype`, and
    `shape` stay coherent with the new tensor. The affine is preserved when
    one is set or can be read from the source header; for an image created
    without any source (e.g. `ScalarImage()` then `set_data`) it defaults to
    the identity affine.

    Args:
        tensor: 4D tensor with shape (C, I, J, K).
    """
    self._data = self._parse_tensor(tensor)
    self._refresh_backend_from_data()

def to(self, *args: Any, **kwargs: Any) -> Self:
    """Move image data and affine to a device and/or cast to a dtype.

    Accepts the same arguments as `torch.Tensor.to()`.

    Returns:
        `self` (modified in-place).
    """
    self._data = self.data.to(*args, **kwargs)
    if self._affine is not None:
        self._affine.to(*args, **kwargs)
    self._refresh_backend_from_data()
    return self

def numpy(self) -> np.ndarray:
    """Return the image data as a NumPy array.

    If the data is not loaded, reads it from disk first. The returned
    array shares memory with the tensor if possible (i.e., if the
    tensor is on CPU and not a view).

    Returns:
        4D array with shape (C, I, J, K).
    """
    return self.data.cpu().numpy()

def new_like(
    self,
    *,
    data: TypeImageData,
    affine: AffineMatrix | npt.ArrayLike | None = None,
) -> Self:
    r"""Create a new image of the same class with new data.

    Preserves metadata, annotations, and affine. Uses the existing
    affine unless a new one is provided. Works correctly with custom
    subclasses.

    Args:
        data: New 4D [`torch.Tensor`][torch.Tensor] with shape
            $(C, I, J, K)$.
        affine: New $4 \times 4$ affine. If `None`, uses `self.affine`.
    """
    new_affine = (
        self._parse_affine(affine) if affine is not None else self.affine.clone()
    )
    points_copy, bboxes_copy = self._deep_copy_annotations()
    return type(self)(
        data,
        affine=new_affine,
        points=points_copy,
        bounding_boxes=bboxes_copy,
        **dict(self._metadata),
    )

def save(
    self,
    path: str | Path,
    **kwargs: Any,
) -> None:
    """Save the image to a file.

    NIfTI-Zarr (`.nii.zarr`) files are written via `niizarr`
    (requires the `zarr` extra). All other formats are written
    with [SimpleITK](https://simpleitk.org/).

    Args:
        path: Output file path. The format is inferred from the
            extension.
        **kwargs: Extra keyword arguments forwarded to the
            writer. For SimpleITK formats these are passed to
            `SimpleITK.WriteImage()`.
    """
    path = Path(path)
    if is_nifti_zarr(path):
        self._save_nii_zarr(path)
    else:
        self._save_sitk(path, **kwargs)

def plot(self, **kwargs: Any) -> Any:
    """Plot 3 orthogonal slices of the image.

    Requires the `[plot]` extras (`pip install torchio[plot]`).
    See [`plot_image`][torchio.visualization.plot_image] for the
    full list of keyword arguments.
    """
    from ..visualization import plot_image

    return plot_image(self, **kwargs)

def plot_interactive(self, *, height: int = 300) -> Any:
    """Show an interactive NiiVue viewer in Jupyter.

    Requires `ipyniivue` (`pip install torchio[niivue]`).

    The widget supports scrolling through slices, zooming, and
    crosshair navigation.  Left hemisphere is displayed on the
    right side of the screen (radiological convention).

    Args:
        height: Height of the viewer in pixels.

    Returns:
        An `ipyniivue.NiiVue` widget.

    Raises:
        ImportError: If `ipyniivue` is not installed.
    """
    import tempfile

    import nibabel as nib
    import numpy as np

    from ..external.imports import get_ipyniivue

    nv = get_ipyniivue()

    data = self.data.cpu().float().numpy()
    if data.ndim == 4 and data.shape[0] == 1:
        data = data[0]
    affine = np.asarray(self.affine.data, dtype=np.float64)
    nii = nib.Nifti1Image(data, affine)
    with tempfile.NamedTemporaryFile(suffix=".nii.gz", delete=False) as f:
        nib.save(nii, f.name)
        path = f.name

    widget = nv.NiiVue(height=height)
    widget.opts.is_radiological_convention = True
    widget.add_volume(nv.Volume(path=path))
    return widget

def to_gif(
    self,
    output_path: str | Path | None = None,
    *,
    seconds: float = 5.0,
    direction: str = "I",
    loop: int = 0,
    rescale: bool = True,
    optimize: bool = True,
    reverse: bool = False,
) -> Any:
    """Save an animated GIF sweeping through slices.

    Requires `Pillow` (`pip install torchio[plot]`).

    When *output_path* is `None` and the code is running inside
    a Jupyter notebook, the GIF is written to a temporary file and
    returned as an `IPython.display.Image` for inline display.
    Outside Jupyter, *output_path* is required.

    Args:
        output_path: Path to the output `.gif` file.  `None`
            to auto-create a temporary file (Jupyter only).
        seconds: Duration of the full animation in seconds.
        direction: Anatomical sweep direction (`"I"`, `"S"`,
            `"A"`, `"P"`, `"R"`, or `"L"`).
        loop: Number of loops (0 = infinite).
        rescale: Rescale intensities to `[0, 255]`.
        optimize: Attempt to compress the GIF palette.
        reverse: Reverse the temporal order of frames.

    Returns:
        `IPython.display.Image` when running in Jupyter,
        `None` otherwise.

    Raises:
        ValueError: If *output_path* is `None` and the code is
            not running inside a Jupyter notebook.
    """
    output_path = _resolve_media_path(output_path, suffix=".gif")
    from ..visualization import make_gif

    make_gif(
        self,
        output_path,
        seconds=seconds,
        direction=direction,
        loop=loop,
        rescale=rescale,
        optimize=optimize,
        reverse=reverse,
    )
    if _in_jupyter():
        from IPython.display import Image as IPyImage

        return IPyImage(filename=str(output_path))
    return None

def to_video(
    self,
    output_path: str | Path | None = None,
    *,
    seconds: float = 5.0,
    direction: str = "I",
    verbosity: str = "error",
) -> Any:
    """Create an MP4 video sweeping through slices.

    Requires `ffmpeg-python` (`pip install torchio[video]`).

    When *output_path* is `None` and the code is running inside
    a Jupyter notebook, the video is written to a temporary file
    and returned as an `IPython.display.Video` for inline
    display.  Outside Jupyter, *output_path* is required.

    Args:
        output_path: Path to the output `.mp4` file.  `None`
            to auto-create a temporary file (Jupyter only).
        seconds: Duration of the full video in seconds.
        direction: Anatomical sweep direction (`"I"`, `"S"`,
            `"A"`, `"P"`, `"R"`, or `"L"`).
        verbosity: ffmpeg log level.

    Returns:
        `IPython.display.Video` when running in Jupyter,
        `None` otherwise.

    Raises:
        ValueError: If *output_path* is `None` and the code is
            not running inside a Jupyter notebook.
    """
    output_path = _resolve_media_path(output_path, suffix=".mp4")
    from ..visualization import make_video

    make_video(
        self,
        output_path,
        seconds=seconds,
        direction=direction,
        verbosity=verbosity,
    )
    if _in_jupyter():
        from IPython.display import Video

        return Video(
            str(output_path),
            embed=True,
            html_attributes="controls autoplay loop muted",
        )
    return None