Repository: Project-MONAI/MONAI
File: monai/transforms/spatial/array.py (Python)

Code before:

    This transform is capable of lazy execution. See the :ref:`Lazy Resampling topic<lazy_resampling>`
    for more information.
    """

    backend = [TransformBackends.NUMPY, TransformBackends.TORCH]

    def __init__(
        self,
        axcodes: str | None = None,
        as_closest_canonical: bool = False,
        labels: Sequence[tuple[str, str]] | None = None,
        lazy: bool = False,
    ) -> None:
        """
        Args:
            axcodes: N elements sequence for spatial ND input's orientation.
                e.g. axcodes='RAS' represents 3D orientation:
                (Left, Right), (Posterior, Anterior), (Inferior, Superior).
                default orientation labels options are: 'L' and 'R' for the first dimension,
                'P' and 'A' for the second, 'I' and 'S' for the third.
            as_closest_canonical: if True, load the image as closest to canonical axis format.
            labels: optional, None or sequence of (2,) sequences
                (2,) sequences are labels for (beginning, end) of output axis.
                Defaults to using the ``"space"`` attribute of a metatensor,
                where appliable, or (('L', 'R'), ('P', 'A'), ('I', 'S'))``
                otherwise (i.e. for plain tensors).
            lazy: a flag to indicate whether this transform should execute lazily or not.
                Defaults to False

        Raises:
            ValueError: When ``axcodes=None`` and ``as_closest_canonical=True``. Incompatible values.

        See Also: `nibabel.orientations.ornt2axcodes`.

        """
        LazyTransform.__init__(self, lazy=lazy)
        if axcodes is None and not as_closest_canonical:
            raise ValueError("Incompatible values: axcodes=None and as_closest_canonical=True.")
        if axcodes is not None and as_closest_canonical:
            warnings.warn("using as_closest_canonical=True, axcodes ignored.")
        self.axcodes = axcodes
        self.as_closest_canonical = as_closest_canonical
        self.labels = labels

    def __call__(self, data_array: torch.Tensor, lazy: bool | None = None) -> torch.Tensor:
        """
        If input type is `MetaTensor`, original affine is extracted with `data_array.affine`.
        If input type is `torch.Tensor`, original affine is assumed to be identity.

        Args:

Review comment (suggestion):
I think this should explicitly say that when the "space" meta value is LPS and this argument is `None`, the value used will be `(("R", "L"), ("A", "P"), ("I", "S"))` as the axis labels. If `labels` is not `None`, it is used regardless of the "space" meta value. If `labels` is `None` and the "space" meta value is not LPS, then the meaning of that should be mentioned here as well.

Code after:
    Change the input image's orientation into the specified based on `axcodes`.

    This transform is capable of lazy execution. See the :ref:`Lazy Resampling topic<lazy_resampling>`
    for more information.
    """

    backend = [TransformBackends.NUMPY, TransformBackends.TORCH]

    @deprecated_arg_default(
        name="labels",
        old_default=(("L", "R"), ("P", "A"), ("I", "S")),
        new_default=None,
        msg_suffix=(
            "Default value changed to None meaning that the transform now uses the 'space' of a "
            "meta-tensor, if applicable, to determine appropriate axis labels."
        ),
    )
    def __init__(
        self,
        axcodes: str | None = None,
        as_closest_canonical: bool = False,
        labels: Sequence[tuple[str, str]] | None = None,
        lazy: bool = False,
    ) -> None:
        """
        Args:
            axcodes: N elements sequence for spatial ND input's orientation.
                e.g. axcodes='RAS' represents 3D orientation:
                (Left, Right), (Posterior, Anterior), (Inferior, Superior).
                default orientation labels options are: 'L' and 'R' for the first dimension,
                'P' and 'A' for the second, 'I' and 'S' for the third.
            as_closest_canonical: if True, load the image as closest to canonical axis format.
            labels: optional, None or sequence of (2,) sequences
                (2,) sequences are labels for (beginning, end) of output axis.
                If ``None``, an appropriate value is chosen depending on the
                value of the ``"space"`` metadata item of a metatensor: if
                ``"space"`` is ``"LPS"``, the value used is ``(('R', 'L'),
                ('A', 'P'), ('I', 'S'))``, if ``"space"`` is ``"RPS"`` or the
                input is not a meta-tensor or has no ``"space"`` item, the
                value ``(('L', 'R'), ('P', 'A'), ('I', 'S'))`` is used. If not
                ``None``, the provided value is always used and the ``"space"``
                metadata item (if any) of the input is ignored.
            lazy: a flag to indicate whether this transform should execute lazily or not.
                Defaults to False

        Raises:
            ValueError: When ``axcodes=None`` and ``as_closest_canonical=True``. Incompatible values.

        See Also: `nibabel.orientations.ornt2axcodes`.

        """