# 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.
#

"""Deform images elastically by a smoothed displacement field, as in Simard et al.

Which function to use:

- A displacement field from your own noise, smoothed by a Gaussian and scaled per axis: :func:`elastic_transform2d`.
- For random elastic deformations in an augmentation pipeline, use :class:`~kornia.augmentation.RandomElasticTransform`;
  for a smooth deformation set by control points, :func:`~kornia.geometry.transform.warp_image_tps`; to sample an
  image at per-pixel coordinates of your own, :func:`~kornia.geometry.transform.remap`.
"""

from typing import Tuple, Union

import torch
import torch.nn.functional as F

from kornia.core.check import KORNIA_CHECK_IS_TENSOR, KORNIA_CHECK_SHAPE
from kornia.core.ops import _device_literal
from kornia.core.utils import (
    _autocast_disabled,
    _convolution_outside_autocast,
    _samples_half_in_float32,
    _torch_grid_sample,
)
from kornia.filters import filter2d_separable
from kornia.filters.kernels import get_gaussian_kernel1d

__all__ = ["elastic_transform2d"]


def elastic_transform2d(
    image: torch.Tensor,
    noise: torch.Tensor,
    kernel_size: Tuple[int, int] = (63, 63),
    sigma: Union[Tuple[float, float], torch.Tensor] = (32.0, 32.0),
    alpha: Union[Tuple[float, float], torch.Tensor] = (1.0, 1.0),
    align_corners: bool = False,
    mode: str = "bilinear",
    padding_mode: str = "zeros",
) -> torch.Tensor:
    r"""Deform images by a displacement field smoothed from noise, as described in :cite:`Simard2003BestPF`.

    ``out = elastic_transform2d(image, noise)`` takes images ``(B, C, H, W)`` and a noise field ``(B, 2, H, W)``,
    smooths each channel of the noise with a Gaussian of ``kernel_size`` and ``sigma``, scales it by ``alpha`` and
    returns the ``(B, C, H, W)`` images sampled at the displaced pixels. The displacements are in the normalized
    :math:`[-1, 1]` coordinates of ``grid_sample``: an x displacement of 1 moves a sample by :math:`W / 2` pixels at the
    default ``align_corners=False`` and by :math:`(W - 1) / 2` at ``True``, and a y displacement likewise by the
    height. One Gaussian and one ``alpha`` serve the whole batch. For random fields in an augmentation pipeline, use
    :class:`~kornia.augmentation.RandomElasticTransform`; for a smooth warp set by control points,
    :func:`~kornia.geometry.transform.warp_image_tps`.

    .. image:: _static/img/elastic_transform2d.png

    Convention:
        - a ``float16``/``bfloat16`` image with a noise field of its dtype builds its grid and samples in ``float32`` on
          every device and returns the input dtype: a half-precision grid is off by half a pixel or more at 256 px
        - image: ``(B, C, H, W)``; ``noise``: ``(B, 2, H, W)`` with
          channel 0 the x- and channel 1 the y-displacement of the sampling
          grid (positive x-noise shifts image content left)
        - displacements are smoothed with a Gaussian (``kernel_size``,
          ``sigma``) and scaled by ``alpha``; ``kernel_size`` and ``sigma`` are ``(y, x)`` pairs, but ``alpha`` is
          ``(x, y)``
        - align_corners: ``False`` by default (the matrix warps default to ``True``); zero
          ``noise`` is an identity under either setting
        - coordinates displaced outside the image are filled by ``padding_mode`` as in ``grid_sample``:
          zeros, the edge value, or the reflected image
        - a caller's autocast region does not change the displacement field or the grid, and the result stays in the
          dtype of ``image``. Under ``torch.compile`` on MPS it still changes the field: a convolution under the guard
          raises there, so the smoothing runs in the region's dtype

    Args:
        image: Input image to be transformed with shape ``(B, C, H, W)``.
        noise: Noise image used to spatially transform the input image. Same
          resolution as the input image with shape ``(B, 2, H, W)``. The coordinates order
          it is expected to be in x-y.
        kernel_size: the size of the Gaussian kernel, in the y and x directions, respectively; both odd.
        sigma: The standard deviation of the Gaussian in the y and x directions,
          respectively, as a pair or a ``(2,)`` tensor. Larger sigma results in smaller pixel displacements.
        alpha : The scaling factor that controls the intensity of the deformation
          in the x and y directions, respectively, as a pair or a ``(2,)`` tensor.
        align_corners: Interpolation flag used by ``grid_sample``.
        mode: Interpolation mode used by ``grid_sample``. Either ``'bilinear'`` or ``'nearest'``.
        padding_mode: The padding used by ``grid_sample``. Either ``'zeros'``, ``'border'`` or ``'reflection'``.

    Returns:
        the elastically transformed input image with shape ``(B, C, H, W)``.

    See Also:
        - :class:`~kornia.augmentation.RandomElasticTransform`: draws uniform noise in :math:`[-1, 1]` for each call and
          applies it with probability ``p``, in an augmentation pipeline.
        - :func:`~kornia.geometry.transform.warp_image_tps`: a smooth deformation set by control-point pairs.
        - :func:`~kornia.geometry.transform.remap`: samples an image at per-pixel coordinates given directly.

    Example:
        >>> image = torch.rand(1, 3, 5, 5)
        >>> noise = torch.rand(1, 2, 5, 5, requires_grad=True)
        >>> image_hat = elastic_transform2d(image, noise, (3, 3))
        >>> image_hat.mean().backward()

        >>> image = torch.rand(1, 3, 5, 5)
        >>> noise = torch.rand(1, 2, 5, 5)
        >>> sigma = torch.tensor([4., 4.], requires_grad=True)
        >>> image_hat = elastic_transform2d(image, noise, (3, 3), sigma)
        >>> image_hat.mean().backward()

        >>> image = torch.rand(1, 3, 5, 5)
        >>> noise = torch.rand(1, 2, 5, 5)
        >>> alpha = torch.tensor([16., 32.], requires_grad=True)
        >>> image_hat = elastic_transform2d(image, noise, (3, 3), alpha=alpha)
        >>> image_hat.mean().backward()

    """
    KORNIA_CHECK_IS_TENSOR(image)
    KORNIA_CHECK_IS_TENSOR(noise)
    KORNIA_CHECK_SHAPE(image, ["B", "C", "H", "W"])
    KORNIA_CHECK_SHAPE(noise, ["B", "C", "H", "W"])

    # A half image and field are warped in float32: a half-precision sampling grid is off by half a pixel or more.
    out_dtype = image.dtype
    if _samples_half_in_float32(image) and noise.dtype == image.dtype:
        image, noise = image.float(), noise.float()
        if isinstance(sigma, torch.Tensor) and _samples_half_in_float32(sigma):
            sigma = sigma.float()
        if isinstance(alpha, torch.Tensor) and _samples_half_in_float32(alpha):
            alpha = alpha.float()

    device, dtype = image.device, image.dtype

    # Normalise sigma to a (B, 2) = (sigma_y, sigma_x) tensor, matching get_gaussian_kernel2d.
    # Python numbers are filled on the device: ``torch.tensor(..., device=cuda)`` copies from the host and waits for
    # every queued kernel. The values round from the same numbers either way.
    if isinstance(sigma, torch.Tensor):
        sigma = sigma.expand(2)[None, ...]
    elif all(isinstance(s, (int, float)) for s in sigma):
        sigma = _device_literal([sigma], device=device, dtype=dtype)
    else:
        sigma = torch.tensor([sigma], device=device, dtype=dtype)
    ksize_y, ksize_x = kernel_size
    sigma_y, sigma_x = sigma[:, 0, None], sigma[:, 1, None]

    # The Gaussian used to smooth the displacement field is separable, so filter with two 1-D
    # passes rather than a full (ksize_y x ksize_x) 2-D convolution: numerically identical up to
    # float-accumulation order (~1e-7) and ~30-60x cheaper for the default (63, 63) kernel.
    kernel_1d_x = get_gaussian_kernel1d(ksize_x, sigma_x, device=device, dtype=dtype)
    kernel_1d_y = get_gaussian_kernel1d(ksize_y, sigma_y, device=device, dtype=dtype)

    if isinstance(alpha, torch.Tensor):
        alpha_x = alpha[0]
        alpha_y = alpha[1]
    elif all(isinstance(a, (int, float)) for a in alpha):
        alpha_x = _device_literal(alpha[0], device=device, dtype=dtype)
        alpha_y = _device_literal(alpha[1], device=device, dtype=dtype)
    else:
        alpha_x = torch.tensor(alpha[0], device=device, dtype=dtype)
        alpha_y = torch.tensor(alpha[1], device=device, dtype=dtype)

    # Convolve over the random displacement matrix and scale by 'alpha'.
    # The field and the identity grid below are sampling positions: a caller's autocast region would round them to half
    # precision, 0.018 off on a [0, 1] image in bfloat16, and the result would still come back in its dtype (#6601).
    # Compiled on MPS the guard is skipped: a convolution in it raises there (see _convolution_outside_autocast).
    with _convolution_outside_autocast(device.type):
        disp_x = filter2d_separable(noise[:, :1], kernel_1d_x, kernel_1d_y, border_type="constant") * alpha_x
        disp_y = filter2d_separable(noise[:, 1:], kernel_1d_x, kernel_1d_y, border_type="constant") * alpha_y

        # torch.stack and F.normalize displacement
        disp = torch.cat([disp_x, disp_y], 1).permute(0, 2, 3, 1)

    # Warp image based on displacement matrix. ``create_meshgrid`` uses the
    # corner-aligned coordinate convention, while ``grid_sample`` interprets
    # normalized coordinates according to ``align_corners``. Build the identity
    # grid with the same convention as the sampler so that zero displacement is
    # an identity transform for both values of ``align_corners``.
    _, _, h, w = image.shape
    # CPU does not implement ``affine_grid`` for half or bfloat16 tensors. Generate those
    # coordinate grids in float32 and narrow once; the grid must still match the image dtype
    # before it is passed to ``grid_sample``.
    grid_dtype = torch.float32 if image.dtype in (torch.float16, torch.bfloat16) else image.dtype
    identity = torch.eye(2, 3, device=image.device, dtype=grid_dtype).unsqueeze(0)
    with _autocast_disabled(device.type):
        grid = F.affine_grid(identity, [1, 1, h, w], align_corners=align_corners)
    grid = grid.to(image.dtype)
    # Autocast reconciles a field of another half or float32 dtype; the result stays in the image dtype.
    return _torch_grid_sample(image, grid + disp, align_corners=align_corners, mode=mode, padding_mode=padding_mode).to(
        out_dtype
    )
