"""Contains the pyvista.Cell class."""

from __future__ import annotations

from typing import TYPE_CHECKING
from typing import cast
import warnings

import numpy as np

import pyvista
from pyvista._deprecate_positional_args import _deprecate_positional_args

from . import _vtk_core as _vtk
from ._typing_core import BoundsTuple
from .celltype import CellType
from .dataobject import DataObject
from .errors import CellSizeError
from .errors import PyVistaDeprecationWarning
from .utilities.cells import numpy_to_idarr
from .utilities.misc import _BoundsSizeMixin
from .utilities.misc import _NoNewAttrMixin

if TYPE_CHECKING:
    from typing import Any

    from typing_extensions import Self

    from pyvista import UnstructuredGrid

    from ._typing_core import CellsLike
    from ._typing_core import MatrixLike
    from ._typing_core import NumpyArray


def _get_vtk_id_type() -> type[np.int32 | np.int64]:
    """Return the numpy datatype responding to :vtk:`vtkIdTypeArray`."""
    VTK_ID_TYPE_SIZE = _vtk.vtkIdTypeArray().GetDataTypeSize()
    if VTK_ID_TYPE_SIZE == 4:
        return np.int32
    elif VTK_ID_TYPE_SIZE == 8:
        return np.int64
    return np.int32


class Cell(_BoundsSizeMixin, DataObject, _vtk.vtkGenericCell):
    """Wrapping of :vtk:`vtkCell`.

    This class provides the capability to access a given cell topology and can
    be useful when walking through a cell's individual faces or investigating
    cell properties.

    Parameters
    ----------
    vtk_cell : :vtk:`vtkCell`, optional
        The vtk object to wrap as Cell, that must be of :vtk:`vtkCell` type.

    cell_type : int, optional
        VTK cell type. Determined from ``vtk_cell`` if not input.

    deep : bool, default: False
        Perform a deep copy of the original cell.

    Notes
    -----
    Accessing individual cells from a :class:`pyvista.DataSet` using this class
    will be much slower than accessing bulk data from the
    :attr:`pyvista.PolyData.faces` or :attr:`pyvista.UnstructuredGrid.cells` attributes.

    Also note that the cell object is a deep copy of the original cell and
    is unassociated with the original cell. Changing any data of
    that cell (for example, :attr:`pyvista.Cell.points`) will not change the original dataset.

    Examples
    --------
    Get the 0-th cell from a :class:`pyvista.PolyData`.

    >>> import pyvista as pv
    >>> mesh = pv.Sphere()
    >>> cell = mesh.get_cell(0)
    >>> cell  # doctest: +SKIP
    Cell (0x7fa760075a10)
      Type:       <CellType.TRIANGLE: 5>
      Linear:     True
      Dimension:  2
      N Points:   3
      N Faces:    0
      N Edges:    3
      X Bounds:   -5.406e-02, -5.551e-17
      Y Bounds:   0.000e+00, 1.124e-02
      Z Bounds:   -5.000e-01, -4.971e-01

    Get the 0-th cell from a :class:`pyvista.UnstructuredGrid`.

    >>> from pyvista import examples
    >>> mesh = examples.load_hexbeam()
    >>> cell = mesh.get_cell(0)
    >>> cell  # doctest: +SKIP
    Cell (0x7fdc71a3c210)
      Type:       <CellType.HEXAHEDRON: 12>
      Linear:     True
      Dimension:  3
      N Points:   8
      N Faces:    6
      N Edges:    12
      X Bounds:   0.000e+00, 5.000e-01
      Y Bounds:   0.000e+00, 5.000e-01
      Z Bounds:   0.000e+00, 5.000e-01

    """

    @_deprecate_positional_args(allowed=['vtk_cell', 'cell_type'])
    def __init__(
        self: Self,
        vtk_cell: _vtk.vtkCell | None = None,
        cell_type: CellType | None = None,
        deep: bool = False,  # noqa: FBT001, FBT002
    ) -> None:
        """Initialize the cell."""
        super().__init__()
        if vtk_cell is not None:
            if not isinstance(vtk_cell, _vtk.vtkCell):
                msg = f'`vtk_cell` must be a vtkCell, not {type(vtk_cell)}'  # type: ignore[unreachable]
                raise TypeError(msg)
            # cell type must be set first before deep or shallow copy
            if cell_type is None:
                self.SetCellType(vtk_cell.GetCellType())
            else:
                self.SetCellType(cell_type)

            if deep:
                self.DeepCopy(vtk_cell)
            else:
                self.ShallowCopy(vtk_cell)

    @property
    def type(self: Self) -> CellType:
        """Get the cell type from the enum :class:`pyvista.CellType`.

        Returns
        -------
        pyvista.CellType
            Type of cell.

        Examples
        --------
        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.get_cell(0).type
        <CellType.TRIANGLE: 5>

        """
        return CellType(self.GetCellType())

    @property
    def is_linear(self: Self) -> bool:
        """Return if the cell is linear.

        Returns
        -------
        bool
            If the cell is linear.

        Examples
        --------
        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.get_cell(0).is_linear
        True

        """
        return bool(self.IsLinear())

    def plot(self: Self, **kwargs) -> None:
        """Plot this cell.

        Parameters
        ----------
        **kwargs : dict, optional
            See :func:`pyvista.plot` for a description of the optional keyword
            arguments.

        Examples
        --------
        >>> from pyvista import examples
        >>> mesh = examples.load_hexbeam()
        >>> cell = mesh.get_cell(0)
        >>> cell.plot()

        """
        self.cast_to_unstructured_grid().plot(**kwargs)

    def cast_to_polydata(self: Self) -> pyvista.PolyData:
        """Cast this cell to PolyData.

        Can only be used for 0D, 1D, or 2D cells.

        Returns
        -------
        pyvista.PolyData
            This cell cast to a :class:`pyvista.PolyData`.

        Examples
        --------
        >>> from pyvista import examples
        >>> mesh = examples.load_sphere()
        >>> cell = mesh.get_cell(0)
        >>> grid = cell.cast_to_polydata()
        >>> grid  # doctest: +SKIP
        PolyData (0x7f09ae437b80)
          N Cells:    1
          N Points:   3
          N Strips:   0
           X Bounds:   0.000e+00, 1.000e+01
          Y Bounds:   0.000e+00, 2.500e+01
          Z Bounds:   -1.270e+02, -1.250e+02
          N Arrays:   0

        """
        cells = [len(self.point_ids), *list(range(len(self.point_ids)))]
        if self.dimension == 0:
            return pyvista.PolyData(self.points.copy(), verts=cells)
        if self.dimension == 1:
            return pyvista.PolyData(self.points.copy(), lines=cells)
        if self.dimension == 2:
            if self.type == CellType.TRIANGLE_STRIP:
                return pyvista.PolyData(self.points.copy(), strips=cells)
            else:
                return pyvista.PolyData(self.points.copy(), faces=cells)
        else:
            msg = f'3D cells cannot be cast to PolyData: got cell type {self.type}'
            raise ValueError(msg)

    def cast_to_unstructured_grid(self: Self) -> UnstructuredGrid:
        """Cast this cell to an unstructured grid.

        Returns
        -------
        pyvista.UnstructuredGrid
            This cell cast to a :class:`pyvista.UnstructuredGrid`.

        Examples
        --------
        >>> from pyvista import examples
        >>> mesh = examples.load_hexbeam()
        >>> cell = mesh.get_cell(0)
        >>> grid = cell.cast_to_unstructured_grid()
        >>> grid  # doctest: +SKIP
        UnstructuredGrid (0x7f9383619540)
          N Cells:      1
          N Points:     8
          X Bounds:     0.000e+00, 5.000e-01
          Y Bounds:     0.000e+00, 5.000e-01
          Z Bounds:     0.000e+00, 5.000e-01
          N Arrays:     0

        """
        if self.type == CellType.POLYHEDRON:
            # construct from faces
            cell_ids = [self.n_faces]
            for face in self.faces:
                cell_ids.append(len(face.point_ids))
                cell_ids.extend(self.point_ids.index(i) for i in face.point_ids)
            cell_ids.insert(0, len(cell_ids))
        else:
            cell_ids = [len(self.point_ids), *list(range(len(self.point_ids)))]
        return pyvista.UnstructuredGrid(
            cell_ids,
            [int(self.type)],
            self.points.copy(),
        )

    @property
    def dimension(self: Self) -> int:
        """Return the cell dimension.

        This returns the dimensionality of the cell. For example, 1 for an edge,
        2 for a triangle, and 3 for a tetrahedron.

        Returns
        -------
        int
            The cell dimension.

        Examples
        --------
        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.get_cell(0).dimension
        2

        """
        return self.GetCellDimension()

    @property
    def n_points(self: Self) -> int:
        """Get the number of points composing the cell.

        Returns
        -------
        int
            The number of points.

        Examples
        --------
        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.get_cell(0).n_points
        3

        """
        return self.GetNumberOfPoints()

    @property
    def n_faces(self: Self) -> int:
        """Get the number of faces composing the cell.

        Returns
        -------
        int
            The number of faces.

        Examples
        --------
        >>> from pyvista.examples.cells import Tetrahedron
        >>> mesh = Tetrahedron()
        >>> mesh.get_cell(0).n_faces
        4

        """
        return self.GetNumberOfFaces()

    @property
    def n_edges(self: Self) -> int:
        """Get the number of edges composing the cell.

        Returns
        -------
        int
            The number of edges composing the cell.

        Examples
        --------
        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.get_cell(0).n_edges
        3

        """
        return self.GetNumberOfEdges()

    @property
    def point_ids(self: Self) -> list[int]:
        """Get the point IDs composing the cell.

        Returns
        -------
        list[int]
            The point IDs composing the cell.

        Examples
        --------
        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.get_cell(0).point_ids
        [2, 30, 0]

        """
        point_ids = self.GetPointIds()
        return [point_ids.GetId(i) for i in range(point_ids.GetNumberOfIds())]

    @property
    def points(self: Self) -> NumpyArray[float]:
        """Get the point coordinates of the cell.

        Returns
        -------
        np.ndarray
            The point coordinates of the cell.

        Examples
        --------
        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.get_cell(0).points
        array([[0.05405951, 0.        , 0.49706897],
               [0.05287818, 0.0112396 , 0.49706897],
               [0.        , 0.        , 0.5       ]])

        """
        return _vtk.vtk_to_numpy(self.GetPoints().GetData())

    def get_edge(self: Self, index: int) -> Cell:
        """Get the i-th edge composing the cell.

        Parameters
        ----------
        index : int
            Edge ID.

        Returns
        -------
        pyvista.Cell
            Edge given by ``index``.

        Examples
        --------
        Extract a single edge from a face and output the IDs of the edge
        points.

        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> cell = mesh.get_cell(0)
        >>> edge = cell.get_edge(0)
        >>> edge.point_ids
        [2, 30]

        """
        if index + 1 > self.n_edges:
            msg = f'Invalid index {index} for a cell with {self.n_edges} edges.'
            raise IndexError(msg)

        # must deep copy here as multiple sequental calls to GetEdge overwrite
        # the underlying pointer
        return Cell(self.GetEdge(index), deep=True)  # type: ignore[abstract]

    @property
    def edges(self: Self) -> list[Cell]:
        """Return a list of edges composing the cell.

        Returns
        -------
        list[Cell]
            A list of edges composing the cell.

        Examples
        --------
        >>> from pyvista.examples.cells import Hexahedron
        >>> mesh = Hexahedron()
        >>> cell = mesh.get_cell(0)
        >>> edges = cell.edges
        >>> len(edges)
        12

        """
        return [self.get_edge(i) for i in range(self.n_edges)]

    @property
    def faces(self: Self) -> list[Cell]:
        """Return a list of faces composing the cell.

        Returns
        -------
        list[Cell]
            A list of faces composing the cell.

        Examples
        --------
        >>> from pyvista.examples.cells import Tetrahedron
        >>> mesh = Tetrahedron()
        >>> cell = mesh.get_cell(0)
        >>> faces = cell.faces
        >>> len(faces)
        4

        """
        return [self.get_face(i) for i in range(self.n_faces)]

    def get_face(self: Self, index: int) -> Cell:
        """Get the i-th face composing the cell.

        Parameters
        ----------
        index : int
            Face ID.

        Returns
        -------
        pyvista.Cell
            Face given by ``index``.

        Examples
        --------
        Return the face IDs composing the first face of an example tetrahedron.

        >>> from pyvista.examples.cells import Tetrahedron
        >>> mesh = Tetrahedron()
        >>> cell = mesh.get_cell(0)
        >>> face = cell.get_face(0)
        >>> face.point_ids
        [0, 1, 3]

        """
        # must deep copy here as sequental calls overwrite the underlying pointer
        if index + 1 > self.n_faces:
            msg = f'Invalid index {index} for a cell with {self.n_faces} faces.'
            raise IndexError(msg)

        # must deep copy here as multiple sequental calls to GetFace overwrite
        # the underlying pointer
        cell = self.GetFace(index)
        return Cell(cell, deep=True, cell_type=cast('CellType', cell.GetCellType()))  # type: ignore[abstract]

    @property
    def bounds(self: Self) -> BoundsTuple:
        """Get the cell bounds in ``(x_min, x_max, y_min, y_max, z_min, z_max)``.

        Returns
        -------
        BoundsTuple
            The cell bounds in ``(x_min, x_max, y_min, y_max, z_min, z_max)``.

        Examples
        --------
        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.get_cell(0).bounds
        BoundsTuple(x_min = 0.0,
                    x_max = 0.05405950918793678,
                    y_min = 0.0,
                    y_max = 0.011239604093134403,
                    z_min = 0.49706897139549255,
                    z_max = 0.5)

        """
        return BoundsTuple(*self.GetBounds())

    @property
    def center(self: Self) -> tuple[float, float, float]:
        """Get the center of the cell.

        Uses parametric coordinate center to determine x-y-z center.

        Returns
        -------
        tuple[float, float, float]
            The center of the cell.

        Examples
        --------
        >>> import pyvista as pv
        >>> mesh = pv.Sphere()
        >>> mesh.get_cell(0).center
        (0.03564589594801267, 0.0037465346977114677, 0.49804598093032837)

        """
        para_center = [0.0, 0.0, 0.0]
        sub_id = self.GetParametricCenter(para_center)
        # EvaluateLocation requires mutable sub_id
        sub_id = _vtk.mutable(sub_id)  # type: ignore[assignment]
        # center and weights are returned from EvaluateLocation
        center = [0.0, 0.0, 0.0]
        weights = [0.0] * self.n_points
        self.EvaluateLocation(sub_id, para_center, center, weights)
        return cast('tuple[float, float, float]', tuple(center))

    def _get_attrs(self: Self) -> list[tuple[str, Any, str]]:
        """Return the representation methods (internal helper)."""
        attrs = []
        attrs.append(('Type', repr(self.type), '{}' * len(repr(self.type))))
        attrs.append(('Linear', self.is_linear, '{}'))  # type: ignore[arg-type]
        attrs.append(('Dimension', self.dimension, '{}'))  # type: ignore[arg-type]
        attrs.append(('N Points', self.n_points, '{}'))  # type: ignore[arg-type]
        attrs.append(('N Faces', self.n_faces, '{}'))  # type: ignore[arg-type]
        attrs.append(('N Edges', self.n_edges, '{}'))  # type: ignore[arg-type]
        bds = self.bounds
        fmt = f'{pyvista.FLOAT_FORMAT}, {pyvista.FLOAT_FORMAT}'
        attrs.append(('X Bounds', (bds[0], bds[1]), fmt))  # type: ignore[arg-type]
        attrs.append(('Y Bounds', (bds[2], bds[3]), fmt))  # type: ignore[arg-type]
        attrs.append(('Z Bounds', (bds[4], bds[5]), fmt))  # type: ignore[arg-type]

        return attrs

    def __repr__(self: Self) -> str:
        """Return the object representation."""
        return self.head(display=False, html=False)

    def __str__(self: Self) -> str:
        """Return the object string representation."""
        return self.head(display=False, html=False)

    @_deprecate_positional_args
    def copy(self: Self, deep: bool = True) -> Self:  # noqa: FBT001, FBT002
        """Return a copy of the cell.

        Parameters
        ----------
        deep : bool, optional
            When ``True`` makes a full copy of the cell.  When ``False``,
            performs a shallow copy where the new cell still references the
            original cell.

        Returns
        -------
        pyvista.Cell
            Deep or shallow copy of the cell.

        Examples
        --------
        Create a deep copy of the cell and demonstrate it is deep.

        >>> from pyvista.examples.cells import Tetrahedron
        >>> mesh = Tetrahedron()
        >>> cell = mesh.get_cell(0)
        >>> deep_cell = cell.copy(deep=True)
        >>> deep_cell.points[:] = 0
        >>> cell != deep_cell
        True

        Create a shallow copy of the cell and demonstrate it is shallow.

        >>> shallow_cell = cell.copy(deep=False)
        >>> shallow_cell.points[:] = 0
        >>> cell == shallow_cell
        True

        """
        return type(self)(self, deep=deep)


class CellArray(
    _NoNewAttrMixin,
    _vtk.DisableVtkSnakeCase,
    _vtk.vtkPyVistaOverride,
    _vtk.vtkCellArray,
):
    """PyVista wrapping of :vtk:`vtkCellArray`.

    Provides convenience functions to simplify creating a CellArray from
    a numpy array or list.

    .. deprecated:: 0.44.0
       The parameters ``n_cells`` and ``deep`` are deprecated and no longer used.

    Parameters
    ----------
    cells : np.ndarray or list, optional
        Import an array of data with the legacy :vtk:`vtkCellArray` layout, e.g.
        ``{ n0, p0_0, p0_1, ..., p0_n, n1, p1_0, p1_1, ..., p1_n, ... }``
        Where n0 is the number of points in cell 0, and pX_Y is the Y'th
        point in cell X.

    n_cells : int, optional
        The number of cells.

    deep : bool, default: False
        Perform a deep copy of the original cell.

    Examples
    --------
    Create a cell array containing two triangles from the traditional interleaved format

    >>> from pyvista.core.cell import CellArray
    >>> cellarr = CellArray([3, 0, 1, 2, 3, 3, 4, 5])

    Create a cell array containing two triangles from separate offsets and connectivity arrays

    >>> from pyvista.core.cell import CellArray
    >>> offsets = [0, 3, 6]
    >>> connectivity = [0, 1, 2, 3, 4, 5]
    >>> cellarr = CellArray.from_arrays(offsets, connectivity)

    """

    @_deprecate_positional_args(allowed=['cells'])
    def __init__(
        self: Self,
        cells: CellsLike | None = None,
        n_cells: int | None = None,
        deep: bool | None = None,  # noqa: FBT001
    ) -> None:
        """Initialize a :vtk:`vtkCellArray`."""
        super().__init__()
        self.__offsets: _vtk.vtkIdTypeArray | None = None
        self.__connectivity: _vtk.vtkIdTypeArray | None = None
        if cells is not None:
            self.cells = cells

        # deprecated 0.44.0, convert to error in 0.47.0, remove 0.48.0
        for k, v in (('n_cells', n_cells), ('deep', deep)):
            if v is not None:
                warnings.warn(
                    f'`CellArray parameter `{k}` is deprecated and no longer used.',
                    PyVistaDeprecationWarning,
                )

    @property
    def cells(self: Self) -> NumpyArray[int]:
        """Return a numpy array of the cells.

        Returns
        -------
        np.ndarray
            A numpy array of the cells.

        """
        cells = _vtk.vtkIdTypeArray()
        self.ExportLegacyFormat(cells)
        return _vtk.vtk_to_numpy(cells)

    @cells.setter
    def cells(self: Self, cells: CellsLike) -> None:
        cells = np.asarray(cells)
        vtk_idarr = numpy_to_idarr(cells, deep=False, return_ind=False)
        self.ImportLegacyFormat(vtk_idarr)
        imported_size = self.GetNumberOfConnectivityEntries()

        # https://github.com/pyvista/pyvista/pull/5404
        if imported_size != cells.size:
            msg = (
                f'Cell array size is invalid. Size ({cells.size}) does not'
                f' match expected size ({imported_size}). This is likely'
                ' due to invalid connectivity array.'
            )
            raise CellSizeError(msg)
        self.__offsets = self.__connectivity = None

    @property
    def n_cells(self: Self) -> int:
        """Return the number of cells.

        Returns
        -------
        int
            The number of cells.

        """
        return self.GetNumberOfCells()

    @property
    def connectivity_array(self: Self) -> NumpyArray[int]:
        """Return the array with the point ids that define the cells' connectivity.

        Returns
        -------
        np.ndarray
            Array with the point ids that define the cells' connectivity.

        """
        return _get_connectivity_array(self)

    @property
    def offset_array(self: Self) -> NumpyArray[int]:
        """Return the array used to store cell offsets.

        Returns
        -------
        np.ndarray
            Array used to store cell offsets.

        """
        return _get_offset_array(self)

    def _set_data(
        self: Self,
        offsets: MatrixLike[int],
        connectivity: MatrixLike[int],
        *,
        deep: bool = False,
    ) -> None:
        """Set the offsets and connectivity arrays."""
        vtk_offsets = numpy_to_idarr(offsets, deep=deep)
        vtk_connectivity = numpy_to_idarr(connectivity, deep=deep)
        self.SetData(vtk_offsets, vtk_connectivity)

        # Because vtkCellArray doesn't take ownership of the arrays, it's possible for them to get
        # garbage collected. Keep a reference to them for safety
        self.__offsets = vtk_offsets
        self.__connectivity = vtk_connectivity

    @staticmethod
    @_deprecate_positional_args(allowed=['offsets', 'connectivity'])
    def from_arrays(
        offsets: MatrixLike[int],
        connectivity: MatrixLike[int],
        deep: bool = False,  # noqa: FBT001, FBT002
    ) -> CellArray:
        """Construct a CellArray from offsets and connectivity arrays.

        Parameters
        ----------
        offsets : MatrixLike[int]
            Offsets array of length `n_cells + 1`.

        connectivity : MatrixLike[int]
            Connectivity array.

        deep : bool, default: False
            Whether to deep copy the array data into the vtk arrays.

        Returns
        -------
        CellArray
            Constructed CellArray.

        """
        cellarr = CellArray()
        cellarr._set_data(offsets, connectivity, deep=deep)
        return cellarr

    @property
    def regular_cells(self: Self) -> NumpyArray[int]:
        """Return a (n_cells, cell_size)-shaped array of point indices for equal-sized faces.

        Returns
        -------
        numpy.ndarray
            Array of face indices of shape (n_cells, cell_size).

        Notes
        -----
        This property does not validate that the cells are all
        actually the same size. If they're not, this property may either
        raise a `ValueError` or silently return an incorrect array.

        """
        return _get_regular_cells(self)

    @classmethod
    @_deprecate_positional_args(allowed=['cells'])
    def from_regular_cells(
        cls: type[CellArray],
        cells: MatrixLike[int],
        deep: bool = False,  # noqa: FBT001, FBT002
    ) -> pyvista.CellArray:
        """Construct a ``CellArray`` from a (n_cells, cell_size) array of cell indices.

        Parameters
        ----------
        cells : numpy.ndarray or list[list[int]]
            Cell array of shape (n_cells, cell_size) where all cells have the same `cell_size`.

        deep : bool, default: False
            Whether to deep copy the cell array data into the vtk connectivity array.

        Returns
        -------
        pyvista.CellArray
            Constructed ``CellArray``.

        """
        cells = np.asarray(cells, dtype=pyvista.ID_TYPE)
        n_cells, cell_size = cells.shape
        offsets = cell_size * np.arange(n_cells + 1, dtype=pyvista.ID_TYPE)
        cellarr = cls()
        cellarr._set_data(offsets, cells, deep=deep)
        return cellarr

    @classmethod
    def from_irregular_cells(cls: type[CellArray], cells: MatrixLike[int]) -> pyvista.CellArray:
        """Construct a ``CellArray`` from a (n_cells, cell_size) array of cell indices.

        Parameters
        ----------
        cells : numpy.ndarray or list[list[int]]
            Cell array of shape (n_cells, cell_size) where all cells have the same `cell_size`.

        Returns
        -------
        pyvista.CellArray
            Constructed ``CellArray``.

        """
        offsets = np.cumsum([len(c) for c in cells])
        offsets = np.concatenate([[0], offsets], dtype=pyvista.ID_TYPE)
        connectivity = np.concatenate(cells, dtype=pyvista.ID_TYPE)
        return cls.from_arrays(offsets, connectivity)  # type: ignore[arg-type]


# The following methods would be much nicer bound to CellArray,
# but then they wouldn't be available on bare vtkCellArrays. In the future,
# consider using vtkCellArray.override decorator, so they're all automatically
# returned as CellArrays


def _get_connectivity_array(cellarr: _vtk.vtkCellArray) -> NumpyArray[int]:
    """Return the array with the point ids that define the cells' connectivity."""
    return _vtk.vtk_to_numpy(cellarr.GetConnectivityArray())


def _get_offset_array(cellarr: _vtk.vtkCellArray) -> NumpyArray[int]:
    """Return the array used to store cell offsets."""
    return _vtk.vtk_to_numpy(cellarr.GetOffsetsArray())


def _get_regular_cells(cellarr: _vtk.vtkCellArray) -> NumpyArray[int]:
    """Return a (n_cells, cell_size)-shaped array of point indices for equal-sized faces."""
    cells = _get_connectivity_array(cellarr)
    if len(cells) == 0:
        return cells

    offsets = _get_offset_array(cellarr)
    cell_size = offsets[1] - offsets[0]
    return cells.reshape(-1, cell_size)


def _get_irregular_cells(cellarr: _vtk.vtkCellArray) -> tuple[NumpyArray[int], ...]:
    """Return a tuple of length n_cells of each cell's point indices."""
    cells = _get_connectivity_array(cellarr)
    if len(cells) == 0:
        return ()

    offsets = _get_offset_array(cellarr)
    return tuple(np.split(cells, offsets[1:-1]))