"""Sub-classes for :vtk:`vtkRectilinearGrid` and :vtk:`vtkImageData`."""

from __future__ import annotations

from collections.abc import Sequence
from functools import wraps
from pathlib import Path
from typing import TYPE_CHECKING
from typing import Any
from typing import ClassVar
from typing import Literal
from typing import cast
import warnings

import numpy as np

import pyvista
from pyvista._deprecate_positional_args import _deprecate_positional_args
from pyvista.core import _validation

if TYPE_CHECKING:
    from typing_extensions import Self

    from pyvista import StructuredGrid
    from pyvista import UnstructuredGrid
    from pyvista import pyvista_ndarray
    from pyvista.core._typing_core import MatrixLike
    from pyvista.core._typing_core import NumpyArray
    from pyvista.core._typing_core import RotationLike
    from pyvista.core._typing_core import TransformLike
    from pyvista.core._typing_core import VectorLike


from . import _vtk_core as _vtk
from .dataset import DataSet
from .filters import ImageDataFilters
from .filters import RectilinearGridFilters
from .filters import _get_output
from .utilities.arrays import array_from_vtkmatrix
from .utilities.arrays import convert_array
from .utilities.arrays import raise_has_duplicates
from .utilities.arrays import vtkmatrix_from_array
from .utilities.misc import abstract_class


@abstract_class
class Grid(DataSet):
    """A class full of common methods for non-pointset grids."""

    @property
    def dimensions(self: Self) -> tuple[int, int, int]:
        """Return the grid's dimensions.

        These are effectively the number of points along each of the
        three dataset axes.

        Returns
        -------
        tuple[int]
            Dimensions of the grid.

        Examples
        --------
        Create a uniform grid with dimensions ``(1, 2, 3)``.

        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(2, 3, 4))
        >>> grid.dimensions
        (2, 3, 4)
        >>> grid.plot(show_edges=True)

        Set the dimensions to ``(3, 4, 5)``

        >>> grid.dimensions = (3, 4, 5)
        >>> grid.plot(show_edges=True)

        """
        return self.GetDimensions()

    @dimensions.setter
    def dimensions(self: Self, dims: VectorLike[int]) -> None:
        self.SetDimensions(*dims)
        self.Modified()

    def _get_attrs(self: Self) -> list[tuple[str, Any, str]]:
        """Return the representation methods (internal helper)."""
        attrs = DataSet._get_attrs(self)
        attrs.append(('Dimensions', self.dimensions, '{:d}, {:d}, {:d}'))
        return attrs

    @property
    def dimensionality(self: Self) -> int:
        """Return the dimensionality of the grid.

        Returns
        -------
        int
            The grid dimensionality.

        Examples
        --------
        Get the dimensionality of a 2D uniform grid.

        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(1, 2, 3))
        >>> grid.dimensionality
        2

        Get the dimensionality of a 3D uniform grid.

        >>> grid = pv.ImageData(dimensions=(2, 3, 4))
        >>> grid.dimensionality
        3

        """
        dims = np.asarray(self.dimensions)
        return int(3 - (dims == 1).sum())


class RectilinearGrid(Grid, RectilinearGridFilters, _vtk.vtkRectilinearGrid):
    """Dataset with variable spacing in the three coordinate directions.

    Can be initialized in several ways:

    * Create empty grid
    * Initialize from a :vtk:`vtkRectilinearGrid` object
    * Initialize directly from the point arrays

    Parameters
    ----------
    uinput : str, pathlib.Path, :vtk:`vtkRectilinearGrid`, numpy.ndarray, optional
        Filename, dataset, or array to initialize the rectilinear grid from. If a
        filename is passed, pyvista will attempt to load it as a
        :class:`RectilinearGrid`. If passed a :vtk:`vtkRectilinearGrid`, it
        will be wrapped. If a :class:`numpy.ndarray` is passed, this will be
        loaded as the x range.

    y : numpy.ndarray, optional
        Coordinates of the points in y direction. If this is passed, ``uinput``
        must be a :class:`numpy.ndarray`.

    z : numpy.ndarray, optional
        Coordinates of the points in z direction. If this is passed, ``uinput``
        and ``y`` must be a :class:`numpy.ndarray`.

    check_duplicates : bool, optional
        Check for duplications in any arrays that are passed. Defaults to
        ``False``. If ``True``, an error is raised if there are any duplicate
        values in any of the array-valued input arguments.

    deep : bool, optional
        Whether to deep copy a :vtk:`vtkRectilinearGrid` object.
        Default is ``False``.  Keyword only.

    Examples
    --------
    >>> import pyvista as pv
    >>> import vtk
    >>> import numpy as np

    Create an empty grid.

    >>> grid = pv.RectilinearGrid()

    Initialize from a :vtk:`vtkRectilinearGrid` object

    >>> vtkgrid = vtk.vtkRectilinearGrid()
    >>> grid = pv.RectilinearGrid(vtkgrid)

    Create from NumPy arrays.

    >>> xrng = np.arange(-10, 10, 2)
    >>> yrng = np.arange(-10, 10, 5)
    >>> zrng = np.arange(-10, 10, 1)
    >>> grid = pv.RectilinearGrid(xrng, yrng, zrng)
    >>> grid.plot(show_edges=True)

    """

    _WRITERS: ClassVar[
        dict[
            str,
            type[_vtk.vtkRectilinearGridWriter | _vtk.vtkXMLRectilinearGridWriter],
        ]
    ] = {  # type: ignore[assignment]
        '.vtk': _vtk.vtkRectilinearGridWriter,
        '.vtr': _vtk.vtkXMLRectilinearGridWriter,
    }

    def __init__(
        self: Self,
        *args,
        check_duplicates: bool = False,
        deep: bool = False,
        **kwargs,
    ) -> None:  # numpydoc ignore=PR01,RT01
        """Initialize the rectilinear grid."""
        super().__init__(**kwargs)

        if len(args) == 1:
            if isinstance(args[0], _vtk.vtkRectilinearGrid):
                if deep:
                    self.deep_copy(args[0])
                else:
                    self.shallow_copy(args[0])
            elif isinstance(args[0], (str, Path)):
                self._from_file(args[0], **kwargs)
            elif isinstance(args[0], (np.ndarray, Sequence)):
                self._from_arrays(
                    x=np.asanyarray(args[0]),
                    y=None,  # type: ignore[arg-type]
                    z=None,  # type: ignore[arg-type]
                    check_duplicates=check_duplicates,
                )
            else:
                msg = f'Type ({type(args[0])}) not understood by `RectilinearGrid`'
                raise TypeError(msg)

        elif len(args) == 3 or len(args) == 2:
            arg0_is_arr = isinstance(args[0], (np.ndarray, Sequence))
            arg1_is_arr = isinstance(args[1], (np.ndarray, Sequence))
            arg2_is_arr = isinstance(args[2], (np.ndarray, Sequence)) if len(args) == 3 else False

            if all([arg0_is_arr, arg1_is_arr, arg2_is_arr]):
                self._from_arrays(
                    x=np.asanyarray(args[0]),
                    y=np.asanyarray(args[1]),
                    z=np.asanyarray(args[2]),  # type: ignore[misc]
                    check_duplicates=check_duplicates,
                )
            elif all([arg0_is_arr, arg1_is_arr]):
                self._from_arrays(
                    x=np.asanyarray(args[0]),
                    y=np.asanyarray(args[1]),
                    z=None,  # type: ignore[arg-type]
                    check_duplicates=check_duplicates,
                )
            else:
                msg = 'Arguments not understood by `RectilinearGrid`.'
                raise TypeError(msg)

    def __repr__(self: Self) -> str:
        """Return the default representation."""
        return DataSet.__repr__(self)

    def __str__(self: Self) -> str:
        """Return the str representation."""
        return DataSet.__str__(self)

    def _update_dimensions(self: Self) -> None:
        """Update the dimensions if coordinates have changed."""
        self.SetDimensions(len(self.x), len(self.y), len(self.z))

    def _from_arrays(
        self: Self,
        *,
        x: NumpyArray[float],
        y: NumpyArray[float],
        z: NumpyArray[float],
        check_duplicates: bool = False,
    ) -> None:
        """Create VTK rectilinear grid directly from numpy arrays.

        Each array gives the uniques coordinates of the mesh along each axial
        direction. To help ensure you are using this correctly, we take the unique
        values of each argument.

        Parameters
        ----------
        x : numpy.ndarray
            Coordinates of the points in x direction.

        y : numpy.ndarray
            Coordinates of the points in y direction.

        z : numpy.ndarray
            Coordinates of the points in z direction.

        check_duplicates : bool, optional
            Check for duplications in any arrays that are passed.

        """
        # Set the coordinates along each axial direction
        # Must at least be an x array
        if check_duplicates:
            raise_has_duplicates(x)

        # edges are shown as triangles if x is not floating point
        if not np.issubdtype(x.dtype, np.floating):
            x = x.astype(float)
        self.SetXCoordinates(convert_array(x.ravel()))
        if y is not None:
            if check_duplicates:
                raise_has_duplicates(y)
            if not np.issubdtype(y.dtype, np.floating):
                y = y.astype(float)
            self.SetYCoordinates(convert_array(y.ravel()))
        if z is not None:
            if check_duplicates:
                raise_has_duplicates(z)
            if not np.issubdtype(z.dtype, np.floating):
                z = z.astype(float)
            self.SetZCoordinates(convert_array(z.ravel()))
        # Ensure dimensions are properly set
        self._update_dimensions()

    @property
    def meshgrid(
        self: Self,
    ) -> tuple[NumpyArray[float], NumpyArray[float], NumpyArray[float]]:
        """Return a meshgrid of numpy arrays for this mesh.

        This simply returns a :func:`numpy.meshgrid` of the
        coordinates for this mesh in ``ij`` indexing. These are a copy
        of the points of this mesh.

        Returns
        -------
        tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]
            Tuple of numpy arrays representing the points of this mesh.

        """
        # Converting to tuple needed to be consistent type across numpy version
        # Remove when support is dropped for numpy 1.x
        # We also know this is 3-length so make it so in typing
        out = tuple(np.meshgrid(self.x, self.y, self.z, indexing='ij'))
        # Python 3.8 does not allow subscripting tuple, but only used for type checking
        if TYPE_CHECKING:
            out = cast('tuple[NumpyArray[float], NumpyArray[float], NumpyArray[float]]', out)
        return out

    @property  # type: ignore[override]
    def points(self: Self) -> NumpyArray[float]:
        """Return a copy of the points as an ``(n, 3)`` numpy array.

        Returns
        -------
        numpy.ndarray
            Array of points.

        Notes
        -----
        Points of a :class:`pyvista.RectilinearGrid` cannot be
        set. Set point coordinates with :attr:`RectilinearGrid.x`,
        :attr:`RectilinearGrid.y`, or :attr:`RectilinearGrid.z`.

        Examples
        --------
        >>> import numpy as np
        >>> import pyvista as pv
        >>> xrng = np.arange(-10, 10, 10, dtype=float)
        >>> yrng = np.arange(-10, 10, 10, dtype=float)
        >>> zrng = np.arange(-10, 10, 10, dtype=float)
        >>> grid = pv.RectilinearGrid(xrng, yrng, zrng)
        >>> grid.points
        array([[-10., -10., -10.],
               [  0., -10., -10.],
               [-10.,   0., -10.],
               [  0.,   0., -10.],
               [-10., -10.,   0.],
               [  0., -10.,   0.],
               [-10.,   0.,   0.],
               [  0.,   0.,   0.]])

        """
        if pyvista.vtk_version_info >= (9, 4, 0):
            return convert_array(self.GetPoints().GetData())

        xx, yy, zz = self.meshgrid
        return np.c_[xx.ravel(order='F'), yy.ravel(order='F'), zz.ravel(order='F')]

    @points.setter
    def points(
        self: Self,
        points: MatrixLike[float] | _vtk.vtkPoints,  # noqa: ARG002
    ) -> None:  # numpydoc ignore=PR01
        """Raise an AttributeError.

        This setter overrides the base class's setter to ensure a user
        does not attempt to set them.
        """
        msg = (
            'The points cannot be set. The points of '
            '`RectilinearGrid` are defined in each axial direction. Please '
            'use the `x`, `y`, and `z` setters individually.'
        )
        raise AttributeError(msg)

    @property
    def x(self: Self) -> NumpyArray[float]:
        """Return or set the coordinates along the X-direction.

        Returns
        -------
        numpy.ndarray
            Array of points along the X-direction.

        Examples
        --------
        Return the x coordinates of a RectilinearGrid.

        >>> import numpy as np
        >>> import pyvista as pv
        >>> xrng = np.arange(-10, 10, 10, dtype=float)
        >>> yrng = np.arange(-10, 10, 10, dtype=float)
        >>> zrng = np.arange(-10, 10, 10, dtype=float)
        >>> grid = pv.RectilinearGrid(xrng, yrng, zrng)
        >>> grid.x
        array([-10.,   0.])

        Set the x coordinates of a RectilinearGrid.

        >>> grid.x = [-10.0, 0.0, 10.0]
        >>> grid.x
        array([-10.,   0.,  10.])

        """
        return convert_array(self.GetXCoordinates())

    @x.setter
    def x(self: Self, coords: VectorLike[float]) -> None:
        self.SetXCoordinates(convert_array(coords))
        self._update_dimensions()
        self.Modified()

    @property
    def y(self: Self) -> NumpyArray[float]:
        """Return or set the coordinates along the Y-direction.

        Returns
        -------
        numpy.ndarray
            Array of points along the Y-direction.

        Examples
        --------
        Return the y coordinates of a RectilinearGrid.

        >>> import numpy as np
        >>> import pyvista as pv
        >>> xrng = np.arange(-10, 10, 10, dtype=float)
        >>> yrng = np.arange(-10, 10, 10, dtype=float)
        >>> zrng = np.arange(-10, 10, 10, dtype=float)
        >>> grid = pv.RectilinearGrid(xrng, yrng, zrng)
        >>> grid.y
        array([-10.,   0.])

        Set the y coordinates of a RectilinearGrid.

        >>> grid.y = [-10.0, 0.0, 10.0]
        >>> grid.y
        array([-10.,   0.,  10.])

        """
        return convert_array(self.GetYCoordinates())

    @y.setter
    def y(self: Self, coords: VectorLike[float]) -> None:
        self.SetYCoordinates(convert_array(coords))
        self._update_dimensions()
        self.Modified()

    @property
    def z(self: Self) -> NumpyArray[float]:
        """Return or set the coordinates along the Z-direction.

        Returns
        -------
        numpy.ndarray
            Array of points along the Z-direction.

        Examples
        --------
        Return the z coordinates of a RectilinearGrid.

        >>> import numpy as np
        >>> import pyvista as pv
        >>> xrng = np.arange(-10, 10, 10, dtype=float)
        >>> yrng = np.arange(-10, 10, 10, dtype=float)
        >>> zrng = np.arange(-10, 10, 10, dtype=float)
        >>> grid = pv.RectilinearGrid(xrng, yrng, zrng)
        >>> grid.z
        array([-10.,   0.])

        Set the z coordinates of a RectilinearGrid.

        >>> grid.z = [-10.0, 0.0, 10.0]
        >>> grid.z
        array([-10.,   0.,  10.])

        """
        return convert_array(self.GetZCoordinates())

    @z.setter
    def z(self: Self, coords: VectorLike[float]) -> None:
        self.SetZCoordinates(convert_array(coords))
        self._update_dimensions()
        self.Modified()

    @Grid.dimensions.setter  # type: ignore[attr-defined]
    def dimensions(self: Self, _dims: VectorLike[int]) -> None:
        """Set Dimensions.

        Parameters
        ----------
        _dims : sequence
            Ignored dimensions.

        """
        msg = (
            'The dimensions of a `RectilinearGrid` are implicitly defined and thus cannot be set.'
        )
        raise AttributeError(msg)

    def cast_to_structured_grid(self: Self) -> StructuredGrid:
        """Cast this rectilinear grid to a structured grid.

        Returns
        -------
        pyvista.StructuredGrid
            This grid as a structured grid.

        """
        alg = _vtk.vtkRectilinearGridToPointSet()
        alg.SetInputData(self)
        alg.Update()
        return _get_output(alg)


class ImageData(Grid, ImageDataFilters, _vtk.vtkImageData):
    """Models datasets with uniform spacing in the three coordinate directions.

    Can be initialized in one of several ways:

    - Create empty grid
    - Initialize from a :vtk:`vtkImageData` object
    - Initialize based on dimensions, cell spacing, and origin.

    .. versionchanged:: 0.33.0
        First argument must now be either a path or
        :vtk:`vtkImageData`. Use keyword arguments to specify the
        dimensions, spacing, and origin of the uniform grid.

    .. versionchanged:: 0.37.0
        The ``dims`` parameter has been renamed to ``dimensions``.

    Parameters
    ----------
    uinput : str | :vtk:`vtkImageData` | ImageData, optional
        Filename or dataset to initialize the uniform grid from.  If
        set, remainder of arguments are ignored.

    dimensions : sequence[int], optional
        :attr:`dimensions` of the uniform grid.

    spacing : sequence[float], default: (1.0, 1.0, 1.0)
        :attr:`spacing` of the uniform grid in each dimension. Must be positive.

    origin : sequence[float], default: (0.0, 0.0, 0.0)
        :attr:`origin` of the uniform grid.

    deep : bool, default: False
        Whether to deep copy a :vtk:`vtkImageData` object. Keyword only.

    direction_matrix : RotationLike, optional
        The :attr:`direction_matrix` is a 3x3 matrix which controls the orientation of
        the image data.

        .. versionadded:: 0.45

    offset : int | VectorLike[int], default: (0, 0, 0)
        The offset defines the minimum :attr:`extent` of the image. Offset values
        can be positive or negative. In physical space, the offset is relative
        to the image's :attr:`origin`.

        .. versionadded:: 0.45

    See Also
    --------
    :ref:`create_uniform_grid_example`

    Examples
    --------
    Create an empty ImageData.

    >>> import pyvista as pv
    >>> grid = pv.ImageData()

    Initialize from a :vtk:`vtkImageData` object.

    >>> import vtk
    >>> vtkgrid = vtk.vtkImageData()
    >>> grid = pv.ImageData(vtkgrid)

    Initialize using just the grid dimensions and default
    spacing and origin. These must be keyword arguments.

    >>> grid = pv.ImageData(dimensions=(10, 10, 10))

    Initialize using dimensions and spacing.

    >>> grid = pv.ImageData(
    ...     dimensions=(10, 10, 10),
    ...     spacing=(2, 1, 5),
    ... )

    Initialize using dimensions, spacing, and an origin.

    >>> grid = pv.ImageData(
    ...     dimensions=(10, 10, 10),
    ...     spacing=(2, 1, 5),
    ...     origin=(10, 35, 50),
    ... )

    Initialize from another ImageData.

    >>> grid = pv.ImageData(
    ...     dimensions=(10, 10, 10),
    ...     spacing=(2, 1, 5),
    ...     origin=(10, 35, 50),
    ... )
    >>> grid_from_grid = pv.ImageData(grid)
    >>> grid_from_grid == grid
    True

    """

    _WRITERS: ClassVar[dict[str, type[_vtk.vtkDataSetWriter | _vtk.vtkXMLImageDataWriter]]] = {  # type: ignore[assignment]
        '.vtk': _vtk.vtkDataSetWriter,
        '.vti': _vtk.vtkXMLImageDataWriter,
    }

    @_deprecate_positional_args(allowed=['uinput'])
    def __init__(  # noqa: PLR0917
        self: Self,
        uinput: ImageData | str | Path | None = None,
        dimensions: VectorLike[int] | None = None,
        spacing: VectorLike[float] = (1.0, 1.0, 1.0),
        origin: VectorLike[float] = (0.0, 0.0, 0.0),
        deep: bool = False,  # noqa: FBT001, FBT002
        direction_matrix: RotationLike | None = None,
        offset: int | VectorLike[int] | None = None,
    ) -> None:
        """Initialize the uniform grid."""
        super().__init__()

        # first argument must be either vtkImageData or a path
        if uinput is not None:
            if isinstance(uinput, _vtk.vtkImageData):
                if deep:
                    self.deep_copy(uinput)
                else:
                    self.shallow_copy(uinput)
            elif isinstance(uinput, (str, Path)):
                self._from_file(uinput)
            else:
                msg = (  # type: ignore[unreachable]
                    'First argument, ``uinput`` must be either ``vtkImageData`` '
                    f'or a path, not {type(uinput)}.  Use keyword arguments to '
                    'specify dimensions, spacing, and origin. For example:\n\n'
                    '    >>> grid = pv.ImageData(\n'
                    '    ...     dimensions=(10, 10, 10),\n'
                    '    ...     spacing=(2, 1, 5),\n'
                    '    ...     origin=(10, 35, 50),\n'
                    '    ... )\n'
                )
                raise TypeError(msg)
        else:
            if dimensions is not None:
                self.dimensions = dimensions
            self.origin = origin
            self.spacing = spacing
            if direction_matrix is not None:
                self.direction_matrix = direction_matrix
            if offset is not None:
                self.offset = offset

    def __repr__(self: Self) -> str:
        """Return the default representation."""
        return DataSet.__repr__(self)

    def __str__(self: Self) -> str:
        """Return the default str representation."""
        return DataSet.__str__(self)

    def __getitem__(  # type: ignore[override]
        self, key: tuple[str, Literal['cell', 'point', 'field']] | str | tuple[int, int, int]
    ) -> ImageData | pyvista_ndarray:
        """Search for a data array or slice with IJK indexing."""
        # Return point, cell, or field data
        if isinstance(key, str) or (
            isinstance(key, tuple) and len(key) > 0 and isinstance(key[0], str)  # type: ignore[redundant-expr]
        ):
            return super().__getitem__(key)
        return self.extract_subset(self._compute_voi_from_index(key), rebase_coordinates=False)

    def _compute_voi_from_index(
        self,
        indices: tuple[
            int | slice | tuple[int, int],
            int | slice | tuple[int, int],
            int | slice | tuple[int, int],
        ],
        *,
        index_mode: Literal['extent', 'dimensions'] = 'dimensions',
        strict_index: bool = False,
    ) -> NumpyArray[int]:
        """Compute VOI extents from indexing values."""
        _validation.check_contains(
            ['extent', 'dimensions'], must_contain=index_mode, name='index_mode'
        )
        if not (isinstance(indices, tuple) and len(indices) == 3):  # type: ignore[redundant-expr]
            msg = 'Exactly 3 slices must be specified, one for each IJK-coordinate axis.'  # type: ignore[unreachable]
            raise IndexError(msg)

        dims = self.dimensions
        extent = self.extent
        voi = list(extent)

        for axis, slicer in enumerate(indices):
            _validation.check_instance(slicer, (int, tuple, list, slice), name='index')

            offset = extent[axis * 2]
            index_offset = 0 if index_mode == 'extent' else offset

            if isinstance(slicer, (list, tuple)):
                rng = _validation.validate_array(
                    slicer, must_have_dtype=int, must_have_length=2, to_list=True
                )
                slicer = slice(*rng)  # noqa: PLW2901

            if isinstance(slicer, slice):
                start = slicer.start if slicer.start is not None else 0
                stop = slicer.stop if slicer.stop is not None else dims[axis]
                step = slicer.step
                if step not in (None, 1):
                    msg = 'Only contiguous slices with step=1 are supported.'
                    raise ValueError(msg)

                # Handle negative indices
                if start < 0:
                    start += dims[axis]
                if stop < 0:
                    stop += dims[axis]

            else:  # isinstance(slicer, int)
                min_allowed = offset - dims[axis] - index_offset
                max_allowed = min_allowed + dims[axis] * 2 - 1
                if slicer < min_allowed or slicer > max_allowed:
                    msg = (
                        f'index {slicer} is out of bounds for axis {axis} with size {dims[axis]}.'
                        f'\nValid range of valid index values (inclusive) is '
                        f'[{min_allowed}, {max_allowed}].'
                    )
                    raise IndexError(msg)
                if slicer < 0:
                    slicer += dims[axis]  # noqa: PLW2901
                start = slicer
                stop = start + 1

            voi[axis * 2] = index_offset + start
            voi[axis * 2 + 1] = index_offset + stop - 1

        clipped = pyvista.ImageDataFilters._clip_extent(voi, clip_to=self.extent)
        if strict_index and (
            any(min_ < clp for min_, clp in zip(voi[::2], clipped[::2]))
            or any(max_ > clp for max_, clp in zip(voi[1::2], clipped[1::2]))
        ):
            msg = (
                f'The requested volume of interest {tuple(voi)} '
                f"is outside the input's extent {extent}."
            )
            raise IndexError(msg)
        return clipped

    @property  # type: ignore[override]
    def points(self: Self) -> NumpyArray[float]:
        """Build a copy of the implicitly defined points as a numpy array.

        Returns
        -------
        numpy.ndarray
            Array of points representing the image data.

        Notes
        -----
        The ``points`` for a :class:`pyvista.ImageData` cannot be set.

        Examples
        --------
        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(2, 2, 2))
        >>> grid.points
        array([[0., 0., 0.],
               [1., 0., 0.],
               [0., 1., 0.],
               [1., 1., 0.],
               [0., 0., 1.],
               [1., 0., 1.],
               [0., 1., 1.],
               [1., 1., 1.]])

        """
        if pyvista.vtk_version_info >= (9, 4, 0):
            return convert_array(self.GetPoints().GetData())

        # Handle empty case
        if not all(self.dimensions):
            return np.zeros((0, 3))

        # Get grid dimensions
        nx, ny, nz = self.dimensions
        nx -= 1
        ny -= 1
        nz -= 1
        # get the points and convert to spacings
        dx, dy, dz = self.spacing
        # Now make the cell arrays
        ox, oy, oz = np.array(self.origin) + self.extent[::2] * np.array([dx, dy, dz])
        x = np.insert(np.cumsum(np.full(nx, dx)), 0, 0.0) + ox
        y = np.insert(np.cumsum(np.full(ny, dy)), 0, 0.0) + oy
        z = np.insert(np.cumsum(np.full(nz, dz)), 0, 0.0) + oz
        xx, yy, zz = np.meshgrid(x, y, z, indexing='ij')
        points = np.c_[xx.ravel(order='F'), yy.ravel(order='F'), zz.ravel(order='F')]

        direction = self.direction_matrix
        if not np.array_equal(direction, np.eye(3)):
            return (
                pyvista.Transform().rotate(direction, point=self.origin).apply(points, copy=False)
            )
        return points

    @points.setter
    def points(
        self: Self,
        points: MatrixLike[float] | _vtk.vtkPoints,  # noqa: ARG002
    ) -> None:  # numpydoc ignore=PR01
        """Points cannot be set.

        This setter overrides the base class's setter to ensure a user does not
        attempt to set them. See https://github.com/pyvista/pyvista/issues/713.

        """
        msg = (
            'The points cannot be set. The points of '
            '`ImageData`/`vtkImageData` are implicitly defined by the '
            '`origin`, `spacing`, and `dimensions` of the grid.'
        )
        raise AttributeError(msg)

    @property
    def x(self: Self) -> NumpyArray[float]:  # numpydoc ignore=RT01
        """Return all the X points.

        Examples
        --------
        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(2, 2, 2))
        >>> grid.x
        array([0., 1., 0., 1., 0., 1., 0., 1.])

        """
        return self.points[:, 0]

    @property
    def y(self: Self) -> NumpyArray[float]:  # numpydoc ignore=RT01
        """Return all the Y points.

        Examples
        --------
        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(2, 2, 2))
        >>> grid.y
        array([0., 0., 1., 1., 0., 0., 1., 1.])

        """
        return self.points[:, 1]

    @property
    def z(self: Self) -> NumpyArray[float]:  # numpydoc ignore=RT01
        """Return all the Z points.

        Examples
        --------
        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(2, 2, 2))
        >>> grid.z
        array([0., 0., 0., 0., 1., 1., 1., 1.])

        """
        return self.points[:, 2]

    @property
    def origin(self: Self) -> tuple[float]:  # numpydoc ignore=RT01
        """Return the origin of the grid (bottom southwest corner).

        Examples
        --------
        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(5, 5, 5))
        >>> grid.origin
        (0.0, 0.0, 0.0)

        Show how the origin is in the bottom "southwest" corner of the
        ImageData.

        >>> pl = pv.Plotter()
        >>> _ = pl.add_mesh(grid, show_edges=True)
        >>> _ = pl.add_axes_at_origin(ylabel=None)
        >>> pl.camera_position = 'xz'
        >>> pl.show()

        Set the origin to ``(1, 1, 1)`` and show how this shifts the
        ImageData.

        >>> grid.origin = (1, 1, 1)
        >>> pl = pv.Plotter()
        >>> _ = pl.add_mesh(grid, show_edges=True)
        >>> _ = pl.add_axes_at_origin(ylabel=None)
        >>> pl.camera_position = 'xz'
        >>> pl.show()

        """
        return self.GetOrigin()  # type: ignore[return-value]

    @origin.setter
    def origin(self: Self, origin: VectorLike[float]) -> None:
        self.SetOrigin(*origin)
        self.Modified()

    @property
    def spacing(self: Self) -> tuple[float, float, float]:  # numpydoc ignore=RT01
        """Return or set the spacing for each axial direction.

        Notes
        -----
        Spacing must be non-negative. While VTK accepts negative
        spacing, this results in unexpected behavior. See:
        https://github.com/pyvista/pyvista/issues/1967

        Examples
        --------
        Create a 5 x 5 x 5 uniform grid.

        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(5, 5, 5))
        >>> grid.spacing
        (1.0, 1.0, 1.0)
        >>> grid.plot(show_edges=True)

        Modify the spacing to ``(1, 2, 3)``

        >>> grid.spacing = (1, 2, 3)
        >>> grid.plot(show_edges=True)

        """
        return self.GetSpacing()

    @spacing.setter
    def spacing(self: Self, spacing: VectorLike[float]) -> None:
        spacing_ = _validation.validate_array3(
            spacing, must_be_in_range=[0, float('inf')], name='spacing'
        )
        self.SetSpacing(*spacing_)
        self.Modified()

    def _get_attrs(self: Self) -> list[tuple[str, Any, str]]:
        """Return the representation methods (internal helper)."""
        attrs = Grid._get_attrs(self)
        fmt = '{}, {}, {}'.format(*[pyvista.FLOAT_FORMAT] * 3)
        attrs.append(('Spacing', self.spacing, fmt))
        return attrs

    def cast_to_structured_grid(self: Self) -> StructuredGrid:
        """Cast this uniform grid to a structured grid.

        Returns
        -------
        pyvista.StructuredGrid
            This grid as a structured grid.

        """
        alg = _vtk.vtkImageToStructuredGrid()
        alg.SetInputData(self)
        alg.Update()
        return _get_output(alg)

    def cast_to_rectilinear_grid(self: Self) -> RectilinearGrid:
        """Cast this uniform grid to a rectilinear grid.

        Returns
        -------
        pyvista.RectilinearGrid
            This uniform grid as a rectilinear grid.

        """
        rectilinear_coords = self._generate_rectilinear_coords()
        grid = pyvista.RectilinearGrid(*rectilinear_coords)
        grid.point_data.update(self.point_data)
        grid.cell_data.update(self.cell_data)
        grid.field_data.update(self.field_data)
        grid.copy_meta_from(self, deep=True)
        return grid

    def _generate_rectilinear_coords(
        self: Self,
    ) -> list[NumpyArray[float]]:
        """Generate rectilinear coordinates (internal helper).

        Returns
        -------
        list[NumpyArray[float]]
            Rectilinear coordinates over the three dimensions.

        """
        dims = self.dimensions
        spacing = self.spacing
        origin = self.origin
        offset = self.offset
        direction = self.direction_matrix

        # Off-axis rotation is not supported by RectilinearGrid
        if np.allclose(np.abs(direction), np.eye(3)):
            sign = np.diagonal(direction)
        else:
            sign = np.array((1.0, 1.0, 1.0))
            msg = (
                'The direction matrix is not a diagonal matrix and cannot be used when casting to '
                'RectilinearGrid.\nThe direction is ignored. Consider casting to StructuredGrid '
                'instead.'
            )
            warnings.warn(msg, RuntimeWarning)

        # Use linspace to avoid rounding error accumulation
        ijk = [np.linspace(offset[i], offset[i] + dims[i] - 1, dims[i]) for i in range(3)]
        return [ijk[axis] * spacing[axis] * sign[axis] + origin[axis] for axis in range(3)]

    @property
    def extent(
        self: Self,
    ) -> tuple[int, int, int, int, int, int]:  # numpydoc ignore=RT01
        """Return or set the extent of the ImageData.

        The extent is simply the first and last indices for each of the three axes.
        It encodes information about the image's :attr:`offset` and :attr:`dimensions`.

        Examples
        --------
        Create a ``ImageData`` and show its extent.

        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(10, 10, 10))
        >>> grid.extent
        (0, 9, 0, 9, 0, 9)

        >>> grid.extent = (2, 5, 2, 5, 2, 5)
        >>> grid.extent
        (2, 5, 2, 5, 2, 5)

        Note how this also modifies the grid's :attr:`offset`, :attr:`dimensions`,
        and :attr:`bounds`. Since we use default spacing of 1 here, the bounds
        match the extent exactly.

        >>> grid.offset
        (2, 2, 2)

        >>> grid.dimensions
        (4, 4, 4)

        >>> grid.bounds
        BoundsTuple(x_min = 2.0,
                    x_max = 5.0,
                    y_min = 2.0,
                    y_max = 5.0,
                    z_min = 2.0,
                    z_max = 5.0)

        """
        return self.GetExtent()

    @extent.setter
    def extent(self: Self, new_extent: VectorLike[int]) -> None:
        new_extent_ = _validation.validate_arrayN(
            new_extent,
            must_be_integer=True,
            must_have_length=6,
            to_list=True,
            dtype_out=int,
        )
        self.SetExtent(new_extent_)

    @property
    def offset(self: Self) -> tuple[int, int, int]:  # numpydoc ignore=RT01
        """Return or set the index offset of the ImageData.

        The offset is simply the first indices for each of the three axes
        and defines the minimum :attr:`extent` of the image. Offset values
        can be positive or negative. In physical space, the offset is relative
        to the image's :attr:`origin`.

        .. versionadded:: 0.45

        Examples
        --------
        Create a ``ImageData`` and show that the offset is zeros by default.

        >>> import pyvista as pv
        >>> grid = pv.ImageData(dimensions=(10, 10, 10))
        >>> grid.offset
        (0, 0, 0)

        The offset defines the minimum extent.

        >>> grid.extent
        (0, 9, 0, 9, 0, 9)

        Set the offset to a new value for all axes.

        >>> grid.offset = 2
        >>> grid.offset
        (2, 2, 2)

        Show the extent again. Note how all values have increased by the offset value.

        >>> grid.extent
        (2, 11, 2, 11, 2, 11)

        Set the offset for each axis separately and show the extent again.

        >>> grid.offset = (-1, -2, -3)
        >>> grid.extent
        (-1, 8, -2, 7, -3, 6)

        """
        return self.extent[::2]

    @offset.setter
    def offset(self: Self, offset: int | VectorLike[int]) -> None:
        offset_ = _validation.validate_array3(
            offset, broadcast=True, must_be_integer=True, dtype_out=int
        )
        dims = self.dimensions
        self.extent = (
            offset_[0],
            offset_[0] + dims[0] - 1,
            offset_[1],
            offset_[1] + dims[1] - 1,
            offset_[2],
            offset_[2] + dims[2] - 1,
        )

    @wraps(RectilinearGridFilters.to_tetrahedra)  # type:ignore[has-type]
    def to_tetrahedra(
        self: Self, *args, **kwargs
    ) -> UnstructuredGrid:  # numpydoc ignore=PR01,RT01
        """Cast to a rectangular grid and then convert to tetrahedra."""
        return self.cast_to_rectilinear_grid().to_tetrahedra(*args, **kwargs)

    @property
    def direction_matrix(self: Self) -> NumpyArray[float]:
        """Set or get the direction matrix.

        The direction matrix is a 3x3 matrix which controls the orientation of the
        image data.

        .. versionadded:: 0.45

        Returns
        -------
        np.ndarray
            Direction matrix as a 3x3 NumPy array.

        """
        return array_from_vtkmatrix(self.GetDirectionMatrix())

    @direction_matrix.setter
    def direction_matrix(self: Self, matrix: RotationLike) -> None:
        self.SetDirectionMatrix(vtkmatrix_from_array(_validation.validate_transform3x3(matrix)))

    @property
    def index_to_physical_matrix(self: Self) -> NumpyArray[float]:
        """Return or set 4x4 matrix to transform index space (ijk) to physical space (xyz).

        .. note::
            Setting this property modifies the object's :class:`~pyvista.ImageData.origin`,
            :class:`~pyvista.ImageData.spacing`, and :class:`~pyvista.ImageData.direction_matrix`
            properties.

        .. versionadded:: 0.45

        Returns
        -------
        np.ndarray
            4x4 transformation matrix.

        """
        return array_from_vtkmatrix(self.GetIndexToPhysicalMatrix())

    @index_to_physical_matrix.setter
    def index_to_physical_matrix(
        self: Self, matrix: TransformLike
    ) -> None:  # numpydoc ignore=GL08
        T, R, N, S, K = pyvista.Transform(matrix).decompose()
        if not np.allclose(K, np.eye(3)):
            warnings.warn(
                'The transformation matrix has a shear component which has been removed. \n'
                'Shear is not supported when setting `ImageData` `index_to_physical_matrix`.'
            )

        self.origin = T
        self.direction_matrix = R * N
        self.spacing = S

    @property
    def physical_to_index_matrix(self: Self) -> NumpyArray[float]:
        """Return or set 4x4 matrix to transform from physical space (xyz) to index space (ijk).

        .. note::
            Setting this property modifies the object's :class:`~pyvista.ImageData.origin`,
            :class:`~pyvista.ImageData.spacing`, and :class:`~pyvista.ImageData.direction_matrix`
            properties.

        .. versionadded:: 0.45

        Returns
        -------
        np.ndarray
            4x4 transformation matrix.

        """
        return array_from_vtkmatrix(self.GetPhysicalToIndexMatrix())

    @physical_to_index_matrix.setter
    def physical_to_index_matrix(
        self: Self, matrix: TransformLike
    ) -> None:  # numpydoc ignore=GL08
        self.index_to_physical_matrix = pyvista.Transform(matrix).inverse_matrix