# LICENSE HEADER MANAGED BY add-license-header
#
# Copyright 2018 Kornia Team
#
# 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.
#

import sys
import warnings
from typing import Any, Dict, Iterator, List, Literal, Optional, Sequence, Tuple, Union, cast

import torch
from torch import nn

from kornia.augmentation._2d.base import RigidAffineAugmentationBase2D
from kornia.augmentation._2d.geometric.elastic_transform import RandomElasticTransform
from kornia.augmentation._2d.geometric.fisheye import RandomFisheye
from kornia.augmentation._2d.geometric.thin_plate_spline import RandomThinPlateSpline
from kornia.augmentation._3d.base import AugmentationBase3D, RigidAffineAugmentationBase3D
from kornia.augmentation.base import _AugmentationBase
from kornia.augmentation.utils.helpers import _boxes_to_padded_tensor, _raise_input_rank_error
from kornia.constants import DataKey, Resample
from kornia.core.check import _check_async
from kornia.core.external import PILImage as Image
from kornia.core.external import numpy as np
from kornia.core.mixin.image_module import _is_pil_image, _rebuild_container
from kornia.core.ops import eye_like
from kornia.core.utils import _normalize_to_float32_or_float64, is_autocast_enabled, is_exporting
from kornia.geometry.boxes import Boxes, VideoBoxes
from kornia.geometry.keypoints import Keypoints, VideoKeypoints
from kornia.image.utils import image_to_tensor

from .base import TransformMatrixMinIn
from .image import ImageSequential
from .ops import AugmentationSequentialOps, DataType, InputSequentialOps, _filter_child_options, _validate_extra_args
from .params import ParamItem
from .patch import PatchSequential
from .video import VideoSequential

__all__ = ["AugmentationSequential"]

# Dynamo cannot trace membership checks against a Python set; tuples keep these constants
# capture-friendly while preserving the membership-only behavior used below.
_BOXES_OPTIONS = (DataKey.BBOX, DataKey.BBOX_XYXY, DataKey.BBOX_XYWH)
_KEYPOINTS_OPTIONS = (DataKey.KEYPOINTS,)
_IMG_OPTIONS = (DataKey.INPUT, DataKey.IMAGE)
_MSK_OPTIONS = (DataKey.MASK,)
_CLS_OPTIONS = (DataKey.CLASS, DataKey.LABEL)
# Warps without a transformation matrix: they move the image but not keypoints or boxes (#4420).
_NON_RIGID_WARPS = (RandomElasticTransform, RandomFisheye, RandomThinPlateSpline)

MaskDataType = Union[torch.Tensor, List[torch.Tensor]]


def _is_numpy_array(arg: Any) -> bool:
    # Look NumPy up instead of importing it through the lazy loader: an array can exist only once NumPy is
    # imported, and an import inside a compiled ``forward`` is a graph break (``importlib.import_module``).
    numpy_module = sys.modules.get("numpy")
    return numpy_module is not None and isinstance(arg, numpy_module.ndarray)


# The inputs AugmentationSequential accepts next to a 3D child; a 4D tensor is ambiguous there.
_VOLUME_BATCH_SHAPES = "either (D, H, W) or (B, C, D, H, W)"


class AugmentationSequential(TransformMatrixMinIn, ImageSequential):
    r"""Augment aligned images, masks, boxes, keypoints and labels with one parameter draw.

    ``augmented = AugmentationSequential(*transforms, data_keys=keys)(*inputs)`` applies each selected child to the
    aligned positional inputs and returns them in the same order. ``data_keys`` supports images, masks, boxes,
    keypoints and class labels; inversion only reverses supported geometric children, so it is not generally a lossless
    round trip. It records the selected children and their sampled parameters in ``_params`` for replay; use
    :class:`~kornia.augmentation.container.ImageSequential` for an image tensor alone, or
    :class:`~kornia.augmentation.container.VideoSequential` for a video tensor alone.

    .. image:: _static/img/AugmentationSequential.png

    Args:
        *args: a list of kornia augmentation modules.

        data_keys: the input type sequential for applying augmentations. Accepts "input", "image", "mask",
                   "bbox", "bbox_xyxy", "bbox_xywh", "keypoints", "class", "label".

        same_on_batch: apply the same transformation across the batch. If None, it will not overwrite the function-wise
                       settings.

        keepdim: whether to keep the output shape the same as input (True) or broadcast it to the batch form (False).
                 If None, it will not overwrite the function-wise settings.

        random_apply: randomly select children to apply. The selected children run in random order and repeat when the
                      requested count exceeds the number of children that can be drawn: the children with a nonzero
                      selection weight, mix augmentations not counted, plus one place when the count and the mix
                      augmentations together reach the number of children, since a mix augmentation is then certain to
                      take a place. With only mix children one of them is drawn, and with all weights 0 and no mix child
                      nothing is.
                      An int or a range that is not fixed to the number of children also repeats when the drawn count
                      exceeds the sum of the weights. That rule is deprecated since kornia 0.9.1, with a
                      ``FutureWarning`` on the calls whose draw it changes, as in
                      :class:`~kornia.augmentation.container.ImageSequential`.
                      If int, a fixed number of transformations will be selected.
                      If (a,), x number of transformations (a <= x <= len(args)) will be selected.
                      If (a, b), x number of transformations (a <= x <= b) will be selected.
                      If True, the whole list of args will be processed as a sequence in a random order, whatever the
                      scale of the weights, and so will a count fixed to the number of children. With a non-mix child of
                      weight 0 or more than one mix augmentation, that count cannot be filled: children repeat and some
                      may be left out.
                      If False, the whole list of args will be processed as a sequence in original order.
        random_apply_weights: selection weights for each child, as in
                              :class:`~kornia.augmentation.container.ImageSequential`.

        transformation_matrix_mode: computation mode for the chained transformation matrix, via `.transform_matrix`
                                    attribute.
                                    If `silent`, the default, the transformation matrix is computed silently and a
                                    direct non-rigid module is skipped rather than treated as an identity. Nested
                                    containers are not handled consistently; see the Convention note below.
                                    If `rigid`, transformation matrix will be computed silently and the non-rigid
                                    modules will trigger errors.
                                    If `skip`, transformation matrix will be totally ignored.
                                    In a caller's autocast region `.transform_matrix` keeps the input's dtype, and
                                    float32 input is computed in float32.
                                    The validator also accepts `silence`, an alias that behaves
                                    like `silent`; any other value raises ``ValueError``.

        extra_args: a dict keyed by ``kornia.constants.DataKey`` that **replaces** the default
                    ``{DataKey.MASK: {'resample': Resample.NEAREST, 'align_corners': None}}`` rather than
                    merging into it, so an override that omits a key drops that key's default. An empty dict
                    is falsy and restores the default. ``DataKey.IMAGE`` honours both entries and
                    ``DataKey.KEYPOINTS`` honours neither. For ``DataKey.MASK`` on a 2D geometric augmentation
                    that uses the base mask path the ``resample`` entry is honoured in both directions, and a
                    dict without one resamples masks with nearest neighbour. ``align_corners`` is
                    handler-dependent: some warps honor it, but resize mask paths replace it.
                    :class:`~kornia.augmentation.RandomResizedCrop` in the default ``cropping_mode='slice'``
                    ignores it for nearest resampling.
                    :class:`~kornia.augmentation.RandomElasticTransform` has its own mask path and honours
                    both entries. As in the constructors, ``resample`` may be a string, an int or a
                    ``kornia.constants.Resample`` member.

    Convention:
        - each child keeps the contract of its own base and class; mix and 3D children do not inherit every
          :class:`~kornia.augmentation.AugmentationBase2D` convention.
        - ``data_keys`` names one entry per positional argument, case-insensitively: ``input`` (alias
          ``image``), ``mask``, ``bbox``, ``bbox_xyxy``, ``bbox_xywh``, ``keypoints`` and ``label`` (alias
          ``class``); any other name raises a ``ValueError`` that is also a ``KeyError``. With ``data_keys=None``
          the call takes a dict whose keys are these names, optionally followed by a ``_`` or ``-`` suffix
          (``mask_2``, ``class_id``). The longest matching name wins and a suffix needs its separator:
          ``bbox_xyxy2`` is a ``bbox`` key and must hold vertices. Unrecognized keys (``images``, ``masks``,
          ``labels``) are returned unchanged, without a warning. The input dict is not modified.
        - the layouts are ``(B, C, H, W)`` for images and masks, ``(B, N, 4, 2)`` vertices for ``bbox``,
          ``(B, N, 4)`` for ``bbox_xyxy`` and ``bbox_xywh``, and ``(B, N, 2)`` in ``(x, y)`` for ``keypoints``;
          ``N = 0`` is accepted. 3D inputs are ``(D, H, W)`` or ``(B, C, D, H, W)``; rank 4 is rejected as
          ambiguous. A ``(B, H, W)`` mask is returned as ``(B, 1, H, W)``, or as ``(B, H, W)`` under
          ``keepdim=True``. A single tensor mask, ``(H, W)``, ``(1, H, W)``, ``(1, C, H, W)`` or one ``(C, H, W)``,
          next to a ``(B, C, H, W)`` image is repeated to batch ``B`` before the first child, so each sample's own
          parameters apply to its copy; a 3D mask whose leading size is ``B`` is read as ``(B, H, W)``. A list of
          masks is not repeated. A single ``(1, T, C, H, W)`` mask is repeated the same way next to a
          ``(B, T, C, H, W)`` video. Next to a BTCHW video a ``(B, T, H, W)`` mask is read with one channel and
          returned as ``(B, T, 1, H, W)``, and a single ``(1, T, H, W)`` mask is repeated too. Any other mask rank
          next to a video, or a 5D mask next to a non-video image, raises ``ValueError`` instead of guessing. A
          replay with no image (``params=`` given, no ``INPUT`` key) reads the batch to repeat to from the recorded
          params instead. A wrong input rank raises :class:`~kornia.core.exceptions.InputRankError` with the message
          a bare augmentation gives; next to a video or 3D child it lists the shapes the container runs, the
          video's 5D layout or ``(D, H, W)`` and ``(B, C, D, H, W)``
          (`#4424 <https://github.com/kornia/kornia/issues/4424>`_).
        - boxes use the inclusive ``xyxy_plus`` convention of :class:`~kornia.geometry.boxes.Boxes`. Flips map
          ``x' = W - 1 - x`` and ``y' = H - 1 - y`` for every key, as :func:`~kornia.geometry.transform.hflip`
          does. Labels pass through geometric steps untouched.
        - masks are resampled with nearest interpolation by default (see ``extra_args``; padding can still add the
          fill value) and come back in their own dtype. Floating masks use the image's working dtype; integer
          masks use at least float32 (float64 with a float64 image). Integer labels not exactly representable
          in that working dtype raise ``RuntimeError`` instead of being rounded, unless checks are disabled
          (``kornia.core.check.disable_checks``, ``python -O`` or ``KORNIA_CHECKS=0``). On accelerators an
          asynchronous assertion may report by the next synchronization; MPS before torch 2.13 checks on the host.
        - a ``mask`` list contains one tensor per image sample, in sample order. Each entry is
          ``(H, W)``, ``(C, H, W)`` or ``(1, C, H, W)``, with matching spatial dimensions; channel counts
          may differ. Each entry uses its sample's gate, transform parameters and matrix, including in
          nested sequences, auto-augment policies, replay and inverse. Full-batch mask tensors must use
          separate ``mask`` data keys; a list with incompatible length or entry shape raises ``ValueError``,
          also in an inverse without an image. Video, mix and 3D children, and a geometric
          :class:`~kornia.augmentation.container.PatchSequential`, do not support mask lists and raise
          ``NotImplementedError``. Inverse warps can only approximately restore resampled pixels and
          cannot recover pixels moved out of the frame.
        - the ``mask``, box and ``keypoints`` handlers of a geometric child, or of a custom
          :class:`~kornia.augmentation.RigidAffineAugmentationBase2D` subclass, receive the transform of the
          call's ``params``: the one the child recorded when it last transformed an image with those params, while no
          value in them has been replaced or edited in place, or else one recomputed from them, so a replay without
          the image, after a newer draw or after an edit follows ``params``. Inference tensors have no version
          counter, so an in-place edit made inside ``torch.inference_mode`` is not seen; replace the value instead.
          The mask limitations above apply; a handler the subclass does not implement raises
          ``NotImplementedError``. A non-rigid warp child has no matrix, so the coordinate keys are refused; see
          the note below.
        - ``.inverse()`` undoes the 2D geometric steps and leaves intensity, custom rigid and non-rigid steps
          applied. 3D geometric children raise ``NotImplementedError``, mix children ``RuntimeError``. Tensor
          boxes come back as axis-aligned enclosures; pass :class:`~kornia.geometry.boxes.Boxes` to keep rotated
          corners. Content lost to cropping, padding or interpolation is not recovered.
        - ``same_on_batch`` and ``keepdim`` default to ``None``, which keeps each child's own setting;
          ``True`` or ``False`` overrides it.
        - Nested :class:`AugmentationSequential` children contribute the matrix they record for the current call
          under their own ``transformation_matrix_mode``; one whose children are all non-rigid records none and is
          skipped. In ``silent`` mode, plain :class:`ImageSequential` children contribute their geometric operations,
          using each operation's recorded parameters even when the sampled sequence repeats a member. The ``rigid``
          mode still rejects a plain image sequence, and ``skip`` records no matrix.

    .. note::
        :class:`~kornia.augmentation.RandomElasticTransform`, :class:`~kornia.augmentation.RandomThinPlateSpline`
        and :class:`~kornia.augmentation.RandomFisheye` warp the image without a transformation matrix, so a
        keypoint or box data key raises ``NotImplementedError`` when any of them is in the pipeline, nested
        containers included. The check reads the pipeline, not the sampled gates: it raises at ``p=0`` and when
        ``random_apply`` does not draw the warp. A ``mask`` key follows the image through
        :class:`~kornia.augmentation.RandomElasticTransform` and raises on the other two
        (`#4420 <https://github.com/kornia/kornia/issues/4420>`_).

    .. note::
        A mix child (e.g. RandomMixUpV2, RandomCutMixV2, RandomMosaic) receives ``mask``, box and ``keypoints``
        keys with the image's parameters; keys it does not implement raise ``NotImplementedError``, as in a
        direct call. A ``class``/``label`` key raises ``NotImplementedError`` from the container.

    .. note::
        See a working example `here <https://www.kornia.org/tutorials/nbs/data_augmentation_sequential.html>`__.

    See Also:
        - :class:`~kornia.augmentation.container.ImageSequential`: chains transforms for an image tensor only.
        - :class:`~kornia.augmentation.container.VideoSequential`: chains transforms for a video tensor only.

    Examples:
        >>> import kornia
        >>> input = torch.randn(2, 3, 5, 6)
        >>> mask = torch.ones(2, 3, 5, 6)
        >>> bbox = torch.tensor([[
        ...     [1., 1.],
        ...     [2., 1.],
        ...     [2., 2.],
        ...     [1., 2.],
        ... ]]).expand(2, 1, -1, -1)
        >>> points = torch.tensor([[[1., 1.]]]).expand(2, -1, -1)
        >>> aug_list = AugmentationSequential(
        ...     kornia.augmentation.ColorJiggle(0.1, 0.1, 0.1, 0.1, p=1.0),
        ...     kornia.augmentation.RandomAffine(360, p=1.0),
        ...     data_keys=["input", "mask", "bbox", "keypoints"],
        ...     same_on_batch=False,
        ...     random_apply=10,
        ... )
        >>> out = aug_list(input, mask, bbox, points)
        >>> [o.shape for o in out]
        [torch.Size([2, 3, 5, 6]), torch.Size([2, 3, 5, 6]), torch.Size([2, 1, 4, 2]), torch.Size([2, 1, 2])]
        >>> # apply the exact augmentation again.
        >>> out_rep = aug_list(input, mask, bbox, points, params=aug_list._params)
        >>> [(o == o_rep).all() for o, o_rep in zip(out, out_rep)]
        [tensor(True), tensor(True), tensor(True), tensor(True)]
        >>> # inverse the augmentations
        >>> out_inv = aug_list.inverse(*out)
        >>> [o.shape for o in out_inv]
        [torch.Size([2, 3, 5, 6]), torch.Size([2, 3, 5, 6]), torch.Size([2, 1, 4, 2]), torch.Size([2, 1, 2])]

    This example demonstrates the integration of VideoSequential and AugmentationSequential.

        >>> import kornia
        >>> input = torch.randn(2, 3, 5, 6)[None]
        >>> mask = torch.ones(2, 3, 5, 6)[None]
        >>> bbox = torch.tensor([[
        ...     [1., 1.],
        ...     [2., 1.],
        ...     [2., 2.],
        ...     [1., 2.],
        ... ]]).expand(2, 1, -1, -1)[None]
        >>> points = torch.tensor([[[1., 1.]]]).expand(2, -1, -1)[None]
        >>> aug_list = AugmentationSequential(
        ...     VideoSequential(
        ...         kornia.augmentation.ColorJiggle(0.1, 0.1, 0.1, 0.1, p=1.0),
        ...         kornia.augmentation.RandomAffine(360, p=1.0),
        ...     ),
        ...     data_keys=["input", "mask", "bbox", "keypoints"]
        ... )
        >>> out = aug_list(input, mask, bbox, points)
        >>> [o.shape for o in out]  # doctest: +ELLIPSIS
        [torch.Size([1, 2, 3, 5, 6]), torch.Size([1, 2, 3, 5, 6]), ...([1, 2, 1, 4, 2]), torch.Size([1, 2, 1, 2])]

    Perform ``OneOf`` transformation with ``random_apply=1`` and ``random_apply_weights``
    in ``AugmentationSequential``.

        >>> import kornia
        >>> input = torch.randn(2, 3, 5, 6)[None]
        >>> mask = torch.ones(2, 3, 5, 6)[None]
        >>> bbox = torch.tensor([[
        ...     [1., 1.],
        ...     [2., 1.],
        ...     [2., 2.],
        ...     [1., 2.],
        ... ]]).expand(2, 1, -1, -1)[None]
        >>> points = torch.tensor([[[1., 1.]]]).expand(2, -1, -1)[None]
        >>> aug_list = AugmentationSequential(
        ...     VideoSequential(
        ...         kornia.augmentation.RandomAffine(360, p=1.0),
        ...     ),
        ...     VideoSequential(
        ...         kornia.augmentation.ColorJiggle(0.1, 0.1, 0.1, 0.1, p=1.0),
        ...     ),
        ...     data_keys=["input", "mask", "bbox", "keypoints"],
        ...     random_apply=1,
        ...     random_apply_weights=[0.5, 0.3]
        ... )
        >>> out = aug_list(input, mask, bbox, points)
        >>> [o.shape for o in out]  # doctest: +ELLIPSIS
        [torch.Size([1, 2, 3, 5, 6]), torch.Size([1, 2, 3, 5, 6]), ...([1, 2, 1, 4, 2]), torch.Size([1, 2, 1, 2])]

    Use separate full-batch mask arguments when their channel counts differ:

        >>> import kornia.augmentation as K
        >>> input = torch.randn(2, 3, 32, 32)
        >>> mask_a = torch.ones(2, 3, 32, 32)
        >>> mask_b = torch.ones(2, 2, 32, 32)
        >>> aug_list = K.AugmentationSequential(
        ...     K.RandomHorizontalFlip(p=1.0),
        ...     data_keys=["input", "mask", "mask"],
        ... )
        >>> out = aug_list(input, mask_a, mask_b)
        >>> [value.shape for value in out]
        [torch.Size([2, 3, 32, 32]), torch.Size([2, 3, 32, 32]), torch.Size([2, 2, 32, 32])]

    With ``data_keys=None``, dictionary keys match data-key names case-insensitively, optionally followed
    by an underscore or hyphen suffix (for example, ``image_2`` or ``bbox_xyxy-left``). The longest matching
    name wins, so coordinate boxes with an underscore/hyphen suffix retain their coordinate format.
    Without that separator, ``bbox_xyxy2`` matches ``bbox`` and requires vertex boxes. ``input`` and ``class`` are
    aliases of ``image`` and ``label``. Unrecognized items are returned without augmentation, and the
    caller's dictionary is left intact.

        >>> import kornia.augmentation as K
        >>> img = torch.randn(1, 3, 256, 256)
        >>> mask = [torch.ones(1, 3, 256, 256), torch.ones(1, 2, 256, 256)]
        >>> bbox = [
        ...    torch.tensor([[28.0, 53.0, 143.0, 164.0], [254.0, 158.0, 364.0, 290.0], [307.0, 204.0, 413.0, 350.0]]),
        ...    torch.tensor([[254.0, 158.0, 364.0, 290.0], [307.0, 204.0, 413.0, 350.0]])
        ... ]
        >>> bbox = [Boxes.from_tensor(i).data for i in bbox]
        >>> aug_dict = K.AugmentationSequential(
        ...    K.ColorJiggle(0.1, 0.1, 0.1, 0.1, p=1.0),
        ...    K.RandomHorizontalFlip(p=1.0),
        ...    K.ImageSequential(K.RandomHorizontalFlip(p=1.0)),
        ...    K.ImageSequential(K.ColorJiggle(0.1, 0.1, 0.1, 0.1, p=1.0)),
        ...    data_keys=None,
        ...    same_on_batch=False,
        ...    random_apply=10,
        ... )
        >>> data = {'image': img, 'mask': mask[0], 'mask-b': mask[1], 'bbox': bbox[0], 'bbox-other':bbox[1]}
        >>> out = aug_dict(data)
        >>> out.keys()
        dict_keys(['image', 'mask', 'mask-b', 'bbox', 'bbox-other'])

    """

    input_dtype = None
    mask_dtype = None

    def __init__(
        self,
        *args: Union[_AugmentationBase, ImageSequential],
        data_keys: Optional[Union[Sequence[str], Sequence[int], Sequence[DataKey]]] = (DataKey.INPUT,),
        same_on_batch: Optional[bool] = None,
        keepdim: Optional[bool] = None,
        random_apply: Union[int, bool, Tuple[int, int]] = False,
        random_apply_weights: Optional[Union[Sequence[float], torch.Tensor]] = None,
        transformation_matrix_mode: str = "silent",
        extra_args: Optional[Dict[DataKey, Dict[str, Any]]] = None,
    ) -> None:
        self._transform_matrix: Optional[torch.Tensor]
        self._transform_matrices: List[Optional[torch.Tensor]] = []

        super().__init__(
            *args,
            same_on_batch=same_on_batch,
            keepdim=keepdim,
            random_apply=random_apply,
            random_apply_weights=random_apply_weights,
            # `inverse` below leaves a plain `nn.Module` child applied; keep that when nested in another container.
            if_unsupported_ops="skip",
        )

        self._parse_transformation_matrix_mode(transformation_matrix_mode)

        self._valid_ops_for_transform_computation: Tuple[Any, ...] = (
            RigidAffineAugmentationBase2D,
            RigidAffineAugmentationBase3D,
            AugmentationSequential,
        )

        self.data_keys: Optional[List[DataKey]]
        if data_keys is not None:
            self.data_keys = [DataKey.get(inp) for inp in data_keys]
        else:
            self.data_keys = data_keys

        if self.data_keys:
            if any(in_type not in DataKey for in_type in self.data_keys):
                raise AssertionError(f"`data_keys` must be in {DataKey}. Got {self.data_keys}.")

            if self.data_keys[0] != DataKey.INPUT:
                raise NotImplementedError(f"The first input must be {DataKey.INPUT}.")

        self.transform_op = AugmentationSequentialOps(self.data_keys)

        self.contains_video_sequential: bool = False
        self.contains_3d_augmentation: bool = False
        for arg in args:
            if isinstance(arg, PatchSequential) and not arg.is_intensity_only():
                warnings.warn(
                    "Geometric transformation detected in PatchSeqeuntial, which would break bbox, mask.", stacklevel=1
                )
            if isinstance(arg, VideoSequential):
                self.contains_video_sequential = True
            # NOTE: only for images are supported for 3D.
            if isinstance(arg, AugmentationBase3D):
                self.contains_3d_augmentation = True
        self._transform_matrix = None
        extra_args = extra_args or {DataKey.MASK: {"resample": Resample.NEAREST, "align_corners": None}}
        # Normalize a ``resample`` override as the constructors do, so a string or int works like a member.
        self.extra_args = {
            key: {**value, "resample": Resample.get(value["resample"])} if "resample" in value else value
            for key, value in extra_args.items()
        }

    def clear_state(self) -> None:
        """Reset cached params and transformation-matrix state."""
        self._reset_transform_matrix_state()
        return super().clear_state()

    def _update_transform_matrix_for_valid_op(self, module: nn.Module) -> None:
        if is_exporting():
            return
        matrix = module.transform_matrix
        # A nested container whose children are all non-rigid records no matrix under its own mode: skip it, as its
        # own mode skipped them. Appending ``None`` made the product raise or drop it depending on the child order.
        if matrix is not None:
            self._transform_matrices.append(matrix)

    @staticmethod
    def _image_sequence_matrices(
        container: ImageSequential,
        params: List[ParamItem],
        input: DataType,
        extra_args: Optional[Dict[str, Any]] = None,
        sequence_matrices: Optional[Iterator[Optional[torch.Tensor]]] = None,
    ) -> Iterator[torch.Tensor]:
        """Read invocation snapshots and parameter-aware geometric matrices from a plain image sequence."""
        for param in params:
            module = container.get_submodule(param.name)
            child_args = _filter_child_options(module, extra_args, param)
            if type(module) is ImageSequential:
                yield from AugmentationSequential._image_sequence_matrices(
                    module, InputSequentialOps.get_sequential_module_param(param), input, child_args, sequence_matrices
                )
            elif isinstance(module, AugmentationSequential):
                if sequence_matrices is None and type(module) is AugmentationSequential:
                    if module._transformation_matrix_arg != "skip":
                        yield from AugmentationSequential._image_sequence_matrices(
                            module, InputSequentialOps.get_sequential_module_param(param), input, child_args
                        )
                else:
                    matrix = module.transform_matrix if sequence_matrices is None else next(sequence_matrices)
                    if matrix is not None:
                        yield matrix
            elif isinstance(module, (RigidAffineAugmentationBase2D, RigidAffineAugmentationBase3D)):
                yield InputSequentialOps.get_transform_matrix(module, param, input, extra_args=child_args)

    def _update_image_sequence_matrix(
        self,
        module: nn.Module,
        param: ParamItem,
        input: DataType,
        extra_args: Optional[Dict[str, Any]] = None,
        image_transformed: bool = True,
    ) -> None:
        """Collect nested matrices, using invocation snapshots only after an image call."""
        extra_args = _filter_child_options(module, extra_args, param)
        if (
            type(module) is ImageSequential
            and self._transformation_matrix_arg in ("silent", "silence")
            and not is_exporting()
        ):
            self._transform_matrices.extend(
                self._image_sequence_matrices(
                    module,
                    InputSequentialOps.get_sequential_module_param(param),
                    input,
                    extra_args,
                    iter(module._sequence_matrices) if image_transformed else None,
                )
            )
        else:
            self._update_transform_matrix_by_module(module)

    def transform_inputs(
        self, input: torch.Tensor, params: List[ParamItem], extra_args: Optional[Dict[str, Any]] = None
    ) -> torch.Tensor:
        """Apply prepared parameters and record the current transformation matrix.

        Nested containers use this entry point instead of :meth:`forward`.

        Args:
            input: Input tensor.
            params: Parameters for each child in execution order.
            extra_args: Optional overrides forwarded to child modules.

        Returns:
            Transformed tensor.
        """
        extra_args = _validate_extra_args(self, extra_args, params)
        self.clear_state()
        for param in params:
            module = self.get_submodule(param.name)
            input = InputSequentialOps.transform(input, module=module, param=param, extra_args=extra_args)
            self._update_image_sequence_matrix(module, param, input, extra_args=extra_args)
        if not is_exporting():
            self._params = params
        return input

    def identity_matrix(self, input: torch.Tensor) -> torch.Tensor:
        """Return identity matrix."""
        if self.contains_3d_augmentation:
            return eye_like(4, input)

        return eye_like(3, input)

    def inverse(
        self,
        *args: Union[DataType, Dict[str, DataType]],
        params: Optional[List[ParamItem]] = None,
        data_keys: Optional[Union[List[str], List[int], List[DataKey]]] = None,
    ) -> Union[DataType, List[DataType], Dict[str, DataType]]:
        """Reverse the transformation applied.

        See the Convention block on :class:`~kornia.augmentation.container.AugmentationSequential`.

        Number of input tensors must align with the number of``data_keys``. If ``data_keys`` is not set, use
        ``self.data_keys`` by default.
        """
        original_keys = None
        if len(args) == 1 and isinstance(args[0], dict):
            original_keys, data_keys, args, invalid_data = self._preproc_dict_data(cast(Dict[str, DataType], args[0]))

        # args here should already be `DataType`
        # NOTE: how to right type to: unpacked args <-> tuple of args to unpack
        # issue with `self._preproc_dict_data` return args type

        original_data_keys = self.transform_op.data_keys
        self.transform_op.data_keys = self.transform_op.preproc_datakeys(data_keys)

        try:
            if params is None:
                params = self._params
            self._validate_args_datakeys(*args, data_keys=self.transform_op.data_keys, params=params)

            in_args = self._arguments_preproc(*args, data_keys=self.transform_op.data_keys)

            if params is None:
                raise ValueError(
                    "No parameters available for inversing, please run a forward pass first "
                    "or passing valid params into this function."
                )

            present = set(self.transform_op.data_keys)
            extra_args = {
                key: _validate_extra_args(self, value, params)
                for key, value in self.extra_args.items()
                if key in present
            }
            outputs: List[DataType] = in_args
            for param in params[::-1]:
                module = self.get_submodule(param.name)
                outputs = self.transform_op.inverse(*outputs, module=module, param=param, extra_args=extra_args)
                if len(self.transform_op.data_keys) == 1 or not isinstance(outputs, (list, tuple)):
                    # One data key can itself hold a mask list; keep it as one argument for the next child.
                    outputs = [outputs]

            outputs = self._arguments_postproc(args, outputs, data_keys=self.transform_op.data_keys)

        finally:
            self.transform_op.data_keys = original_data_keys
        if isinstance(original_keys, tuple):
            result = {k: v for v, k in zip(outputs, original_keys)}
            if invalid_data:
                result.update(invalid_data)
            return result

        if len(outputs) == 1 and isinstance(outputs, list):
            return outputs[0]

        return outputs

    @staticmethod
    def _validate_mask_list(mask: List[torch.Tensor], batch: int, size: Optional[torch.Size]) -> None:
        """Validate the per-sample mask-list layout before any child runs."""
        if len(mask) != batch:
            raise ValueError(f"Mask list must contain one entry per sample ({batch}); got {len(mask)}.")
        for i, entry in enumerate(mask):
            if not isinstance(entry, torch.Tensor):
                raise ValueError(f"Mask list entry {i} must be a torch.Tensor; got {type(entry).__name__}.")
            if entry.ndim not in (2, 3, 4) or (entry.ndim == 4 and entry.shape[0] != 1):
                raise ValueError(
                    f"Mask list entry {i} must be (H, W), (C, H, W) or (1, C, H, W); "
                    f"got {tuple(entry.shape)}. Use separate mask data keys for full-batch tensors."
                )
            if size is not None and entry.shape[-2:] != size:
                raise ValueError(f"Mask list entry {i} must have spatial size {tuple(size)}; got {tuple(entry.shape)}.")

    def _reject_coordinates_through_non_rigid_warps(self, data_keys: List[DataKey]) -> None:
        # The check reads the pipeline, not the sampled gates, so a call raises at any ``p`` and whichever children
        # ``random_apply`` draws: a pipeline cannot pass on some batches and fail on others.
        for key in data_keys:
            if key not in _KEYPOINTS_OPTIONS and key not in _BOXES_OPTIONS:
                continue
            for module in self.modules():
                if isinstance(module, _NON_RIGID_WARPS):
                    raise NotImplementedError(
                        f"{type(module).__name__} does not support {key.name.lower()} inputs. "
                        "See https://github.com/kornia/kornia/issues/4420."
                    )

    def _validate_args_datakeys(
        self, *args: DataType, data_keys: List[DataKey], params: Optional[List[ParamItem]] = None
    ) -> None:
        if len(args) != len(data_keys):
            raise AssertionError(
                f"The number of inputs must align with the number of data_keys. Got {len(args)} and {len(data_keys)}."
            )
        # A plain loop, not next(generator, None): Dynamo on torch 2.5/2.6 cannot trace next() with a default.
        image = None
        for arg, key in zip(args, data_keys):
            if key in _IMG_OPTIONS:
                image = arg
                break
        image_size: Optional[torch.Size] = None
        # Set once at construction from this container's children; distinguishes a video from a 5D
        # ``(B, C, D, H, W)`` 3D image, which this function leaves untouched, as before.
        is_video = self.contains_video_sequential
        if isinstance(image, torch.Tensor) and (image.ndim in (2, 3, 4) or (image.ndim == 5 and is_video)):
            image_batch: Optional[int] = image.shape[0] if image.ndim in (4, 5) else 1
            image_size = image.shape[-2:]
        elif image is None and params is not None and not self.contains_3d_augmentation:
            # A replay has no image; only the mask batch is checked, against the recorded params.
            image_batch = self._batch_size_from_params(params)
        else:
            return
        if image_batch is None:
            return
        # The frame axis of a video, 1 for BTCHW and 2 for BCTHW. A list, not next(generator, None), which Dynamo on
        # torch 2.5/2.6 cannot trace (see above).
        videos = [c for c in self.children() if isinstance(c, VideoSequential)] if is_video else []
        temporal_dim = videos[0]._temporal_channel if videos else 1
        for mask, key in zip(args, data_keys):
            if key not in _MSK_OPTIONS:
                continue
            if isinstance(mask, list):
                self._validate_mask_list(mask, image_batch, image_size)
                continue
            if not isinstance(mask, torch.Tensor):
                continue
            # A mask next to a video is 5D, or (B, T, H, W) next to a BTCHW video, which VideoSequential reads with
            # one channel as it reads a (B, H, W) mask next to an image. A 5D mask is never valid next to an image.
            # Any other combination raises here instead of guessing and failing later with a confusing reshape error.
            if mask.ndim == 5 and not is_video:
                raise ValueError(f"A 5D mask is only valid next to a video; got mask {tuple(mask.shape)}.")
            if is_video and not (mask.ndim == 5 or (mask.ndim == 4 and temporal_dim == 1)):
                raise ValueError(
                    "A mask next to a video must be 5D, (1, T, C, H, W) or (B, T, C, H, W), or (1, T, H, W) or "
                    f"(B, T, H, W) next to a BTCHW video; got mask {tuple(mask.shape)}."
                )
            if (
                is_video
                and isinstance(image, torch.Tensor)
                and image.ndim == 5
                and mask.shape[temporal_dim] != image.shape[temporal_dim]
            ):
                raise ValueError(
                    "Video and mask must have the same number of frames; "
                    f"got video {tuple(image.shape)} and mask {tuple(mask.shape)}."
                )
            mask_batch = mask.shape[0] if mask.ndim in (4, 5) else 1
            if image_size is None:
                if mask_batch not in (1, image_batch):
                    raise ValueError(f"Mask batch size must be 1 or {image_batch}; got mask {tuple(mask.shape)}.")
                continue
            if mask_batch not in (1, image_batch) or mask.shape[-2:] != image_size:
                raise ValueError(
                    "Image and mask must have matching spatial dimensions and compatible batch sizes "
                    f"(1 or {image_batch}); got image {tuple(image.shape)} and mask {tuple(mask.shape)}."
                )

    def _arguments_preproc(
        self, *args: DataType, data_keys: List[DataKey], params: Optional[List[ParamItem]] = None
    ) -> List[DataType]:
        # Resolve this call's image dtype before any mask is converted, so a mask that precedes the image in
        # dictionary insertion order uses it too, rather than the previous call's image dtype (or ``float32`` on
        # a fresh container). It is kept in a local rather than read back from ``self.input_dtype``, so the same
        # conversion happens under ``torch.export``, where that attribute is deliberately left untouched. Masks
        # after an image use the most recent image, as before; a call with no image falls back to the attribute.
        working_dtype = self.input_dtype
        image_batch: Optional[int] = None
        has_image = False
        for arg, dcate in zip(args, data_keys):
            if DataKey.get(dcate) in _IMG_OPTIONS:
                has_image = True
                working_dtype = cast(torch.Tensor, arg).dtype
                # Only a batched ``(B, C, H, W)`` image, or a video's ``(B, T, C, H, W)``, has a batch to
                # broadcast a single mask over; a 5D 3D-augmentation volume is left alone, as before.
                if isinstance(arg, torch.Tensor) and (
                    arg.ndim == 4 or (arg.ndim == 5 and self.contains_video_sequential)
                ):
                    image_batch = arg.shape[0]
                break
        if not has_image and params is not None:
            # A replay has no image in this call; fall back to the batch its params were drawn for.
            image_batch = self._batch_size_from_params(params)
        inp: List[DataType] = []
        for arg, dcate in zip(args, data_keys):
            if DataKey.get(dcate) in _IMG_OPTIONS:
                arg = cast(torch.Tensor, arg)
                working_dtype = arg.dtype
                if not is_exporting():
                    self.input_dtype = arg.dtype
                inp.append(arg)
            elif DataKey.get(dcate) in _MSK_OPTIONS:
                # Output dtypes are read back per argument in ``_arguments_postproc``; ``mask_dtype`` only records
                # the last mask's dtype for callers that read the attribute. The test is on ``arg``: it used to be
                # on the accumulator ``inp``, which is always a list, so a tensor mask was indexed at ``arg[0]``
                # and an empty batch raised ``IndexError``. Like ``input_dtype``, the attribute is not written under
                # ``torch.export``: creating an instance attribute during capture fails the export on torch 2.9.
                if not is_exporting():
                    if isinstance(arg, list):
                        if len(arg) > 0:
                            self.mask_dtype = arg[0].dtype
                    else:
                        self.mask_dtype = cast(torch.Tensor, arg).dtype
                inp.append(self._preproc_mask(arg, working_dtype, image_batch))
            elif DataKey.get(dcate) in _KEYPOINTS_OPTIONS:
                inp.append(self._preproc_keypoints(arg, dcate))
            elif DataKey.get(dcate) in _BOXES_OPTIONS:
                inp.append(self._preproc_boxes(arg, dcate))
            elif DataKey.get(dcate) in _CLS_OPTIONS:
                inp.append(arg)
            else:
                raise NotImplementedError(f"input type of {dcate} is not implemented.")
        return inp

    def _arguments_postproc(
        self, in_args: List[DataType], out_args: List[DataType], data_keys: List[DataKey]
    ) -> List[DataType]:
        out: List[DataType] = []
        for in_arg, out_arg, dcate in zip(in_args, out_args, data_keys):
            if DataKey.get(dcate) in _IMG_OPTIONS:
                # It is torch.Tensor type already.
                out.append(out_arg)
                # TODO: may add the float to integer (for masks), etc.
            elif DataKey.get(dcate) in _MSK_OPTIONS:
                _out_m = self._postproc_mask(cast(MaskDataType, out_arg), cast(MaskDataType, in_arg))
                out.append(_out_m)

            elif DataKey.get(dcate) in _KEYPOINTS_OPTIONS:
                _out_k = self._postproc_keypoint(in_arg, cast(Keypoints, out_arg), dcate)
                if is_autocast_enabled() and isinstance(in_arg, (torch.Tensor, Keypoints)):
                    if isinstance(_out_k, list):
                        _out_k = [i.type(in_arg.dtype) for i in _out_k]
                    else:
                        _out_k = _out_k.type(in_arg.dtype)
                out.append(_out_k)

            elif DataKey.get(dcate) in _BOXES_OPTIONS:
                _out_b = self._postproc_boxes(in_arg, cast(Boxes, out_arg), dcate)
                if is_autocast_enabled() and isinstance(in_arg, (torch.Tensor, Boxes)):
                    if isinstance(_out_b, list):
                        _out_b = [i.type(in_arg.dtype) for i in _out_b]
                    else:
                        _out_b = _out_b.type(in_arg.dtype)
                out.append(_out_b)

            elif DataKey.get(dcate) in _CLS_OPTIONS:
                out.append(out_arg)

            else:
                raise NotImplementedError(f"input type of {dcate} is not implemented.")

        return out

    def _video_or_volume_shapes(self) -> str:
        """Describe the input shapes this container accepts next to a video or 3D child, for a rejected rank."""
        # A list, not next(generator, None), as in _preproc_mask. Read from the children at error time, so that a
        # module unpickled from an older kornia, which lacks any newer attribute, still runs.
        videos = [c for c in self.children() if isinstance(c, VideoSequential)]
        if videos:
            return "(" + ", ".join(videos[0].data_format) + ")"
        return _VOLUME_BATCH_SHAPES

    def forward(
        self,
        *args: Union[DataType, Dict[str, DataType]],
        params: Optional[List[ParamItem]] = None,
        data_keys: Optional[Union[List[str], List[int], List[DataKey]]] = None,
    ) -> Union[DataType, List[DataType], Dict[str, DataType]]:
        """Compute multiple tensors simultaneously according to ``self.data_keys``.

        See the Convention block on :class:`~kornia.augmentation.container.AugmentationSequential`.
        """
        self.clear_state()

        # Strip trailing ``None`` positional args. The legacy torch.onnx.export tracer
        # rebinds keyword-only defaults (``params``/``data_keys``) as positional, so
        # ``forward(x)`` arrives as ``forward(x, None, None)``. Real data inputs are
        # always tensors / Boxes / Keypoints / dicts — never ``None``, so this is safe.
        while args and args[-1] is None:
            args = args[:-1]

        # Unpack/handle dictionary args
        original_keys = None
        if len(args) == 1 and isinstance(args[0], dict):
            original_keys, data_keys, args, invalid_data = self._preproc_dict_data(cast(Dict[str, DataType], args[0]))

        original_data_keys = self.transform_op.preproc_datakeys(data_keys)
        self.transform_op.data_keys = original_data_keys

        try:
            self._validate_args_datakeys(*args, data_keys=original_data_keys, params=params)
            self._reject_coordinates_through_non_rigid_warps(original_data_keys)

            in_args = self._arguments_preproc(*args, data_keys=original_data_keys, params=params)

            # Annotation handlers may read the matrix recorded by the image call. Process INPUT first for every child,
            # including nested containers and policies, then restore the caller's order below.
            input_first_order = list(range(len(original_data_keys)))
            if DataKey.INPUT in original_data_keys:
                image_index = original_data_keys.index(DataKey.INPUT)
                input_first_order.insert(0, input_first_order.pop(image_index))
                in_args = [in_args[i] for i in input_first_order]
                self.transform_op.data_keys = [original_data_keys[i] for i in input_first_order]

            if DataKey.INPUT in original_data_keys:
                inp = in_args[0]
                if not isinstance(inp, torch.Tensor):
                    raise ValueError(f"`INPUT` should be a torch.Tensor but `{type(inp)}` received.")
                if self.contains_3d_augmentation and len(inp.shape) == 4:
                    # A 4D tensor is ambiguous next to 3D augmentations: (C, D, H, W) or a 2D batch.
                    _raise_input_rank_error(inp.shape, _VOLUME_BATCH_SHAPES)

            if params is None:
                # image data must exist if params is not provided.
                if DataKey.INPUT in original_data_keys:
                    inp = in_args[0]
                    # A video input shall be BCDHW while an image input shall be BCHW
                    if self.contains_video_sequential or self.contains_3d_augmentation:
                        if len(inp.shape) not in (3, 4, 5):
                            _raise_input_rank_error(inp.shape, self._video_or_volume_shapes())
                        _, out_shape = self.autofill_dim(inp, dim_range=(3, 5))
                    else:
                        _, out_shape = self.autofill_dim(inp, dim_range=(2, 4))
                    params = self.forward_parameters(out_shape)
                else:
                    raise ValueError("`params` must be provided whilst INPUT is not in data_keys.")

            # Validate only the options of data keys in this call; INPUT options also reach the matrix collection.
            present = {*original_data_keys, DataKey.INPUT}
            extra_args = {
                key: _validate_extra_args(self, value, params)
                for key, value in self.extra_args.items()
                if key in present
            }
            outputs: Union[torch.Tensor, List[DataType]] = in_args
            for param in params:
                module = self.get_submodule(param.name)
                outputs = self.transform_op.transform(*outputs, module=module, param=param, extra_args=extra_args)
                if len(self.transform_op.data_keys) == 1 or not isinstance(outputs, (list, tuple)):
                    # One data key can itself hold a mask list; keep it as one argument for the next child.
                    outputs = [outputs]
                self._update_image_sequence_matrix(
                    module,
                    param,
                    outputs[0],
                    extra_args=extra_args.get(DataKey.INPUT),
                    image_transformed=DataKey.INPUT in original_data_keys,
                )

            if input_first_order != list(range(len(input_first_order))):
                restore_order = [input_first_order.index(i) for i in range(len(input_first_order))]
                outputs = [outputs[i] for i in restore_order]
                self.transform_op.data_keys = original_data_keys

            outputs = self._arguments_postproc(args, outputs, data_keys=original_data_keys)
        finally:
            self.transform_op.data_keys = self.data_keys
        if not is_exporting():
            self._params = params

        if isinstance(original_keys, tuple):
            result = {k: v for v, k in zip(outputs, original_keys)}
            if invalid_data:
                result.update(invalid_data)
            return result

        if len(outputs) == 1 and isinstance(outputs, list):
            return outputs[0]

        return outputs

    def __call__(
        self,
        *inputs: Any,
        input_names_to_handle: Optional[List[Any]] = None,
        output_type: Literal["pt", "numpy", "pil"] = "pt",
        **kwargs: Any,
    ) -> Any:
        """Overwrite the __call__ function to handle various inputs.

        Arguments convert by data key, and only an image takes the image conversion. A mask given as a NumPy array,
        a PIL image or an image file path keeps its dtype and label values, palette indices included. Every mask
        must match the image's height and width, with a batch size of 1 or the image's. A single tensor mask
        (``(H, W)``, batch 1, or one ``(C, H, W)`` mask) is repeated to the image's batch, so every sample's own
        parameters apply to its copy and the output mask has the image's batch size; a 3D mask whose leading size
        equals the image batch is read as ``(B, H, W)``. Arguments converted from NumPy go to the container's device
        when it has parameters or buffers, as the image does.

        Args:
            inputs: Inputs to operate on.
            input_names_to_handle: List of input names to convert.
                If None, convert every tensor, NumPy array and PIL image argument, and load a string as an image
                path only if it is the first positional argument, or the value of an ``input`` or ``image`` key
                (``image_0`` too) in a dictionary input.
            output_type: Desired output type ('pt', 'numpy', or 'pil').
            kwargs: Additional arguments.

        Returns:
            Callable: Decorated function with converted input and output types.

        """
        # Wrap the forward method with the decorator
        if not self._disable_features:
            converted_inputs = inputs
            if len(inputs) == 1 and isinstance(inputs[0], dict):
                keys, data_keys, args, _ = self._preproc_dict_data(inputs[0])
                converted_dict = dict(inputs[0])
                for key, arg, data_key in zip(keys, args, data_keys):
                    # The key marks a string as an image path, so a missing file raises instead of passing through.
                    if data_key in _IMG_OPTIONS and (isinstance(arg, str) or self._is_valid_arg(arg)):
                        converted_dict[key] = self.to_tensor(arg)
                    else:
                        converted_dict[key] = self._convert_non_image(arg, data_key)
                converted_inputs = (converted_dict,)
            else:
                data_keys = self.transform_op.preproc_datakeys(kwargs.get("data_keys", self.data_keys))
                # Arguments beyond the data keys pass through unconverted, so ``forward`` still rejects the count.
                converted_inputs = tuple(
                    self._convert_non_image(arg, data_key) for arg, data_key in zip(inputs, data_keys)
                ) + tuple(inputs[len(data_keys) :])
            # TODO: Some more behaviour for AugmentationSequential needs to be revisited later
            # e.g. We convert only images, etc.
            self._check_output_type(output_type)
            non_images = [key.name for key in data_keys if key not in _IMG_OPTIONS and key not in _MSK_OPTIONS]
            if output_type != "pt" and non_images:
                # a box or keypoint tensor converted like an image (moved to channels-last, or made a PIL image) is
                # not a box any more, so only images and masks take the conversion
                raise ValueError(
                    f"output_type={output_type!r} converts images and masks only, and data_keys also hold "
                    f"{non_images}. Call with output_type='pt'."
                )
            # run the forward pass in tensor mode and convert the output to ``output_type`` only after the image
            # has been cached, so ``.show()`` / ``.save()`` never receive a NumPy array or PIL images
            tensor_output = self._call_converted(
                super(ImageSequential, self).__call__,
                converted_inputs,
                kwargs,
                input_names_to_handle,
                "pt",
                signature_source=self.forward,
            )

            in_data_keys: Optional[List[DataKey]]
            original_keys: Optional[Tuple[str, ...]] = None
            if len(inputs) == 1 and isinstance(inputs[0], dict):
                original_keys, in_data_keys, inputs, _invalid_data = self._preproc_dict_data(inputs[0])
            else:
                in_data_keys = kwargs.get("data_keys", self.data_keys)
            data_keys = self.transform_op.preproc_datakeys(in_data_keys)

            # cache a detached view of the augmented image for ``.show()`` / ``.save()``, which move it to the
            # CPU themselves, so the forward pass pays no device-to-host copy or sync
            image = self._select_output_image(tensor_output, data_keys, original_keys)
            if not is_exporting():
                self._output_image = image.detach() if isinstance(image, torch.Tensor) else image
            _output_image = (
                self._convert_dict_output(tensor_output, output_type, image)
                if isinstance(tensor_output, dict)
                else self._convert_positional_output(tensor_output, output_type, data_keys, image)
            )
        else:
            _output_image = super(ImageSequential, self).__call__(*inputs, **kwargs)
        return _output_image

    def _convert_positional_output(
        self, tensor_output: Any, output_type: str, data_keys: List[DataKey], image: Any
    ) -> Any:
        """Convert a positional forward output for ``output_type``, one value per data key.

        The outputs align with ``data_keys`` positionally; see :meth:`_convert_output_for_data_key`.
        """
        if isinstance(tensor_output, (list, tuple)) and len(tensor_output) == len(data_keys):
            converted = [
                self._convert_output_for_data_key(output, output_type, data_key, image)
                for output, data_key in zip(tensor_output, data_keys)
            ]
            return _rebuild_container(tensor_output, converted)
        return self._convert_output(tensor_output, output_type)

    def _convert_dict_output(self, tensor_output: Dict[str, Any], output_type: str, image: Any) -> Dict[str, Any]:
        """Convert a dict forward output for ``output_type``, keyed by its data keys.

        Only the values under recognized image or mask keys take the conversion: an unrecognized key holds a
        pass-through value the caller supplied, and moving it to channels-last (or making it a PIL image) is
        not what they passed in. See :meth:`_convert_output_for_data_key`.
        """
        valid_data_keys, invalid_keys = self._read_datakeys_from_dict(tuple(tensor_output.keys()))
        key_data_keys = dict(zip([k for k in tensor_output if k not in (invalid_keys or [])], valid_data_keys))
        return {
            key: self._convert_output_for_data_key(value, output_type, key_data_keys.get(key), image)
            for key, value in tensor_output.items()
        }

    def _convert_output_for_data_key(
        self, value: Any, output_type: str, data_key: Optional[DataKey], image: Any
    ) -> Any:
        """Convert one output value for ``output_type``.

        A mask converts like the image, to the NumPy layout the mask input reads back (:meth:`to_numpy`), or to
        one PIL image per sample. A 3D mask next to a batched image is read the way the input reads it: as
        ``(B, H, W)`` when its leading size is the image batch (a mask returned under ``keepdim=True``), so it gets
        its channel axis back and stays batch-first; any other 3D mask is one ``(C, H, W)`` mask.
        """
        if data_key is None:
            # An unrecognized key holds a pass-through value: there is no data key to convert it by.
            return value
        if (
            data_key in _MSK_OPTIONS
            and output_type != "pt"
            and isinstance(value, torch.Tensor)
            and value.dim() == 3
            and isinstance(image, torch.Tensor)
            and image.dim() == 4
            and value.shape[0] == image.shape[0]
        ):
            value = value.unsqueeze(1)
        return self._convert_output(value, output_type)

    def _convert_non_image(self, arg: Any, data_key: DataKey) -> Any:
        if data_key in _IMG_OPTIONS:
            return arg
        if data_key in _MSK_OPTIONS:
            # A PIL image or an image file converts like its NumPy array, so labels and palette indices are kept.
            if isinstance(arg, str) and self._is_valid_arg(arg):
                with Image.open(arg) as mask:
                    arg = np.array(mask)
            elif _is_pil_image(arg):
                arg = np.array(arg)
            if _is_numpy_array(arg):
                if not arg.dtype.isnative:  # torch.from_numpy rejects big-endian data, such as PIL's "I;16B" mode
                    arg = arg.astype(arg.dtype.newbyteorder("="))
                return self._to_module_device(image_to_tensor(arg))
            return arg
        if _is_numpy_array(arg):
            return self._to_module_device(torch.as_tensor(arg))
        return arg

    def _select_output_image(
        self, output: Any, data_keys: List[DataKey], original_keys: Optional[Tuple[str, ...]]
    ) -> Any:
        # ``forward`` returns the image itself, a list ordered like ``data_keys``, or a dict keyed like the input
        if DataKey.INPUT not in data_keys:
            return None
        idx = data_keys.index(DataKey.INPUT)
        if isinstance(output, dict):
            return output[original_keys[idx]]
        if len(data_keys) > 1 and isinstance(output, (list, tuple)):
            return output[idx]
        return output

    def _preproc_dict_data(
        self, data: Dict[str, DataType]
    ) -> Tuple[Tuple[str, ...], List[DataKey], Tuple[DataType, ...], Optional[Dict[str, Any]]]:
        if self.data_keys is not None:
            raise ValueError("If you are using a dictionary as input, the data_keys should be None.")

        keys = tuple(data.keys())
        data_keys, invalid_keys = self._read_datakeys_from_dict(keys)
        invalid_data = {i: data[i] for i in invalid_keys} if invalid_keys else None
        keys = tuple(k for k in keys if k not in invalid_keys) if invalid_keys else keys
        data_unpacked = tuple(data[k] for k in keys)

        return keys, data_keys, data_unpacked, invalid_data

    def _read_datakeys_from_dict(self, keys: Sequence[str]) -> Tuple[List[DataKey], Optional[List[str]]]:
        # Include aliases and prefer coordinate box names over their BBOX prefix.
        names = sorted(DataKey.__members__, key=len, reverse=True)

        def retrieve_key(key: str) -> DataKey:
            """Match a data-key name exactly or before an underscore/hyphen suffix."""
            upper_key = key.upper()
            for name in names:
                if upper_key == name or upper_key.startswith((name + "_", name + "-")):
                    return DataKey.get(name)
            raise ValueError(f"Unrecognized data dictionary key: {key}")

        valid_data_keys = []
        invalid_keys = []
        for k in keys:
            try:
                valid_data_keys.append(DataKey.get(retrieve_key(k)))
            except ValueError:
                invalid_keys.append(k)

        return valid_data_keys, invalid_keys

    def _preproc_mask(
        self, arg: MaskDataType, dtype: Optional[torch.dtype], image_batch: Optional[int] = None
    ) -> MaskDataType:
        # ``dtype`` is the calling image's working dtype, resolved by ``_arguments_preproc``; ``float32`` when the
        # call has no image and no earlier call recorded one. ``image_batch`` is the batch size of a ``(B, C, H, W)``
        # image in the call, ``None`` when there is none.
        working = dtype if dtype is not None else torch.float
        if isinstance(arg, list):
            # A list holds one mask per sample (see the class docstring); it is not broadcast.
            return [self._cast_mask(a, working) for a in arg]
        return self._broadcast_single_mask(self._cast_mask(arg, working), image_batch)

    @staticmethod
    def _cast_mask(mask: torch.Tensor, dtype: torch.dtype) -> torch.Tensor:
        """Convert masks without silently rounding integer class labels."""
        if not mask.is_floating_point():
            dtype = _normalize_to_float32_or_float64(dtype)
        converted = mask.to(dtype)
        # Smaller integer types (and bool) are exactly representable in float32. For wider types, even float64
        # cannot represent every int64 label, so check the actual round trip instead of a conservative bound.
        if mask.dtype in (torch.int32, torch.int64, torch.uint32, torch.uint64):
            limits = torch.iinfo(mask.dtype)
            # The exclusive upper bound is an exact power of two. limits.max itself can round up to that bound.
            # The minimum is exact too, so integer-to-float conversion cannot round below it. Replace overflow
            # with zero before casting back: an overflowing positive label cannot equal zero, and casting an
            # out-of-range float to an integer has undefined behavior even when it happens to match the input.
            safe = torch.where(converted < float(limits.max + 1), converted, 0.0)
            exact = (safe.to(mask.dtype) == mask).all()
            message = (
                f"Integer mask labels must be exactly representable in {dtype}. "
                "Use a float64 image where supported or remap labels to smaller integers."
            )
            _check_async(exact, message)
        return converted

    @staticmethod
    def _broadcast_single_mask(mask: torch.Tensor, image_batch: Optional[int]) -> torch.Tensor:
        """Repeat a single mask along the batch so that each image sample transforms its own copy.

        A mask that stands for "this mask for every image" is accepted by ``_validate_args_datakeys`` next to an
        image of batch ``B > 1``. Unrepeated, a child would transform it with the parameters of sample 0 only
        (flip, crop) or fail inside a per-sample warp (affine, perspective, ...), so it would not line up with
        images ``1..B-1``.

        The single-mask layouts are ``(H, W)``, ``(1, C, H, W)``, ``(1, H, W)`` and ``(C, H, W)``; an ``(H, W)``
        mask is read as ``(1, H, W)``, as a NumPy ``(H, W)`` mask is. A 3D mask is read like ``transform_tensor``
        reads it: as ``(B, H, W)`` when its leading size is the image batch (so it is left alone), otherwise as
        one ``(C, H, W)`` mask. A 5D ``(1, T, C, H, W)`` mask, or a 4D ``(1, T, H, W)`` one, next to a video, only
        expands dim 0; ``T`` is left alone.
        """
        if image_batch is None or image_batch == 1 or mask.ndim not in (2, 3, 4, 5):
            return mask
        if mask.ndim == 2:
            mask = mask[None]  # one (H, W) mask
        if mask.ndim == 3 and mask.shape[0] not in (1, image_batch):
            mask = mask[None]  # one multi-channel (C, H, W) mask
        elif mask.shape[0] != 1:
            return mask  # already one mask per image
        # ``contiguous`` materialises the copy: a stride-0 view would break in-place edits made by a child.
        return mask.expand(image_batch, *mask.shape[1:]).contiguous()

    @staticmethod
    def _batch_size_from_params(params: List[ParamItem]) -> Optional[int]:
        """Extract the replay batch size when no image is available.

        Args:
            params: Recorded parameter tree for the replayed augmentation call.

        Returns:
            The original batch size, or None if no batch size could be recovered.
        """

        def _read_batch_size(value: Any) -> Optional[int]:
            """Recursively read the original batch size stored in nested parameter metadata.

            Args:
                value: A nested replay parameter value produced by a sequential augmentation.

            Returns:
                The recovered batch size, or None when no batch metadata is present.
            """
            if isinstance(value, ParamItem):
                return _read_batch_size(value.data)
            if isinstance(value, list):
                for item in value:
                    batch = _read_batch_size(item)
                    if batch is not None:
                        return batch
                return None
            if isinstance(value, dict):
                video_batch = value.get("video_batch_size")
                if video_batch is not None:
                    return int(torch.as_tensor(video_batch).reshape(-1)[0].item())
                forward_input_shape = value.get("forward_input_shape")
                if forward_input_shape is not None:
                    return int(torch.as_tensor(forward_input_shape).reshape(-1)[0].item())
            return None

        for item in params:
            batch = _read_batch_size(item)
            if batch is not None:
                return batch
        return None

    def _postproc_mask(self, arg: MaskDataType, like: MaskDataType) -> MaskDataType:
        # Each mask output goes back to the dtype of its own argument, per element for a list. A single shared
        # dtype would cast every mask to whichever mask came last: an integer semantic mask followed by a boolean
        # one came back boolean, and its labels collapsed to ``True``.
        if isinstance(arg, list):
            likes = like if isinstance(like, list) else [like] * len(arg)
            return [a.to(ref.dtype) for a, ref in zip(arg, likes)]
        ref = like[0] if isinstance(like, list) else like
        return arg.to(ref.dtype)

    def _preproc_boxes(self, arg: DataType, dcate: DataKey) -> Boxes:
        if DataKey.get(dcate) in [DataKey.BBOX]:
            mode = "vertices_plus"
        elif DataKey.get(dcate) in [DataKey.BBOX_XYXY]:
            mode = "xyxy_plus"
        elif DataKey.get(dcate) in [DataKey.BBOX_XYWH]:
            mode = "xywh"
        else:
            raise ValueError(f"Unsupported mode `{DataKey.get(dcate).name}`.")
        if isinstance(arg, Boxes):
            return arg
        if self.contains_video_sequential:
            arg = cast(torch.Tensor, arg)
            return VideoBoxes.from_tensor(arg)
        if self.contains_3d_augmentation:
            raise NotImplementedError("3D box handlers are not yet supported.")
        arg = cast(torch.Tensor, arg)
        return Boxes.from_tensor(arg, mode=mode)

    def _postproc_boxes(
        self, in_arg: DataType, out_arg: Boxes, dcate: DataKey
    ) -> Union[torch.Tensor, List[torch.Tensor], Boxes]:
        if DataKey.get(dcate) in [DataKey.BBOX]:
            mode = "vertices_plus"
        elif DataKey.get(dcate) in [DataKey.BBOX_XYXY]:
            mode = "xyxy_plus"
        elif DataKey.get(dcate) in [DataKey.BBOX_XYWH]:
            mode = "xywh"
        else:
            raise ValueError(f"Unsupported mode `{DataKey.get(dcate).name}`.")

        # TODO: handle 3d scenarios
        if isinstance(in_arg, Boxes):
            return out_arg
        if isinstance(in_arg, torch.Tensor) and not isinstance(out_arg, VideoBoxes):
            # A dense input stays dense; padding added by an augmentation (e.g. RandomMosaic) is exported as zeros.
            return _boxes_to_padded_tensor(out_arg, mode)

        return out_arg.to_tensor(mode=mode)

    def _preproc_keypoints(self, arg: DataType, dcate: DataKey) -> Keypoints:
        dtype = None

        if self.contains_video_sequential:
            if isinstance(arg, VideoKeypoints):
                return arg
            if isinstance(arg, Keypoints):
                raise TypeError(
                    "A VideoSequential pipeline needs VideoKeypoints or a (B, T, N, 2) tensor for its keypoints, which"
                    " carry the number of frames per video. Got Keypoints."
                )
            arg = cast(Union[torch.Tensor, List[torch.Tensor]], arg)
            if isinstance(arg, list):
                if not torch.is_floating_point(arg[0]):
                    dtype = arg[0].dtype
                    arg = [a.float() for a in arg]
            elif not torch.is_floating_point(arg):
                dtype = arg.dtype
                arg = arg.float()
            video_result = VideoKeypoints.from_tensor(arg)
            return video_result.type(dtype) if dtype else video_result
        if self.contains_3d_augmentation:
            raise NotImplementedError("3D keypoint handlers are not yet supported.")
        if isinstance(arg, Keypoints):
            return arg
        arg = cast(torch.Tensor, arg)
        if not torch.is_floating_point(arg):
            dtype = arg.dtype
            arg = arg.float()
        # TODO: Add List[torch.Tensor] in the future.
        result = Keypoints.from_tensor(arg)
        return result.type(dtype) if dtype else result

    def _postproc_keypoint(
        self, in_arg: DataType, out_arg: Keypoints, dcate: DataKey
    ) -> Union[torch.Tensor, List[torch.Tensor], Keypoints]:
        if isinstance(in_arg, Keypoints):
            return out_arg

        return out_arg.to_tensor()
