MeshGlyph Class

The MeshGlyph class provides visualization for UGRID-style unstructured mesh data using matplotlib triangulation. It supports face-centered and node-centered plotting, wireframe rendering, all 6 color scale types, and time-series animation.

Class Documentation

cleopatra.glyphs.gridded.mesh_glyph.MeshGlyph

Bases: GeoMixin, Glyph

Visualization class for unstructured mesh data.

Wraps matplotlib's triangulation-based rendering to plot data on UGRID-style unstructured meshes (triangles, quads, mixed polygons). Handles fan triangulation for mixed meshes and maps face-centered values to individual triangles.

Parameters:

Name	Type	Description	Default
node_x	ndarray	1D array of node x-coordinates (n_nodes,).	required
node_y	ndarray	1D array of node y-coordinates (n_nodes,).	required
face_node_connectivity	ndarray	2D array of node indices per face (n_faces, max_nodes_per_face). Use fill_value to pad rows for faces with fewer nodes.	required
fill_value	int	Padding value in face_node_connectivity for mixed meshes. Default is -1.	-1
edge_node_connectivity	ndarray | None	2D array of node indices per edge (n_edges, 2). If provided, used for efficient wireframe rendering. If None, edges are derived from face connectivity. Default is None.	None

Attributes:

Name	Type	Description
node_x	ndarray	Node x-coordinates.
node_y	ndarray	Node y-coordinates.
n_faces	int	Number of faces in the mesh.
n_nodes	int	Number of nodes in the mesh.
n_edges	int	Number of edges (0 if edge connectivity not provided).
contour_labels		The inline contour-label Text artists from the most recent plot(location="node", filled=False, labels=True), or None when labelling was not requested (the default, and for tripcolor/tricontourf). A labelled line tricontour with no isolines (e.g. a constant-value field) yields an empty list.

Examples:

• Create a MeshGlyph and inspect its topology:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5])
  >>> node_y = np.array([0.0, 0.0, 1.0])
  >>> faces = np.array([[0, 1, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> mg.n_faces
  1
  >>> mg.n_nodes
  3
  

Source code in src/cleopatra/glyphs/gridded/mesh_glyph.py

class MeshGlyph(GeoMixin, Glyph):
    """Visualization class for unstructured mesh data.

    Wraps matplotlib's triangulation-based rendering to plot data on
    UGRID-style unstructured meshes (triangles, quads, mixed polygons).
    Handles fan triangulation for mixed meshes and maps face-centered
    values to individual triangles.

    Args:
        node_x: 1D array of node x-coordinates (n_nodes,).
        node_y: 1D array of node y-coordinates (n_nodes,).
        face_node_connectivity: 2D array of node indices per face
            (n_faces, max_nodes_per_face). Use `fill_value` to pad
            rows for faces with fewer nodes.
        fill_value: Padding value in `face_node_connectivity` for
            mixed meshes. Default is -1.
        edge_node_connectivity: 2D array of node indices per edge
            (n_edges, 2). If provided, used for efficient wireframe
            rendering. If None, edges are derived from face
            connectivity. Default is None.

    Attributes:
        node_x: Node x-coordinates.
        node_y: Node y-coordinates.
        n_faces: Number of faces in the mesh.
        n_nodes: Number of nodes in the mesh.
        n_edges: Number of edges (0 if edge connectivity not provided).
        contour_labels: The inline contour-label `Text` artists from the
            most recent `plot(location="node", filled=False, labels=True)`,
            or `None` when labelling was not requested (the default, and
            for `tripcolor`/`tricontourf`). A labelled line tricontour with
            no isolines (e.g. a constant-value field) yields an empty list.

    Examples:
        - Create a MeshGlyph and inspect its topology:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5])
            >>> node_y = np.array([0.0, 0.0, 1.0])
            >>> faces = np.array([[0, 1, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> mg.n_faces
            1
            >>> mg.n_nodes
            3

            ```
    """

    #: Option keys this glyph accepts (see `Glyph.option_keys`/`filter_kwargs`).
    DEFAULT_OPTIONS = MESH_DEFAULT_OPTIONS

    def __init__(
        self,
        node_x: np.ndarray,
        node_y: np.ndarray,
        face_node_connectivity: np.ndarray,
        fill_value: int = -1,
        edge_node_connectivity: np.ndarray | None = None,
        fig=None,
        ax=None,
        **kwargs,
    ):
        """Build a mesh glyph from a node/face topology.

        Args:
            node_x: 1-D node x (or longitude) coordinates.
            node_y: 1-D node y (or latitude) coordinates, paired with `node_x`.
            face_node_connectivity: `(n_faces, max_nodes)` node indices per
                face, padded with `fill_value` for faces with fewer nodes.
            fill_value: Padding value in `face_node_connectivity`. Default -1.
            edge_node_connectivity: Optional `(n_edges, 2)` node indices per
                edge, used by the wireframe render. Default None.
            fig: Pre-existing figure to bind. Default None. Passing `fig`
                alone (no `ax`) draws into that figure — its first axes, or
                a fresh one if it has none.
            ax: Pre-existing axes to bind. Default None.
            data_style: Grouped `style` / `hillshade` options applied at
                construction, e.g. `data_style=DataStyle(hillshade=True)`.
                These are rejected as loose keywords, so the group is how they
                are set here rather than on every `plot()` call; the value is
                sticky across later calls (`plot()` restores it whenever the
                call itself does not set one). Default None.
            **kwargs: Override any key in `MESH_DEFAULT_OPTIONS`.

        Raises:
            ValueError: If the topology arrays are inconsistent, or if a
                keyword argument is not a `MESH_DEFAULT_OPTIONS` key.
        """
        super().__init__(default_options=MESH_DEFAULT_OPTIONS, fig=fig, ax=ax, **kwargs)
        self._node_x = np.asarray(node_x, dtype=np.float64)
        self._node_y = np.asarray(node_y, dtype=np.float64)
        self._face_nodes = np.asarray(face_node_connectivity, dtype=np.intp)
        self._fill_value = fill_value
        self._edge_nodes = (
            np.asarray(edge_node_connectivity, dtype=np.intp)
            if edge_node_connectivity is not None
            else None
        )

        if self._node_x.ndim != 1:
            raise ValueError(f"node_x must be 1D, got {self._node_x.ndim}D.")
        if self._node_x.shape != self._node_y.shape:
            raise ValueError(
                f"node_x and node_y must have the same shape, "
                f"got {self._node_x.shape} and {self._node_y.shape}."
            )
        if self._face_nodes.ndim != 2:
            raise ValueError(
                f"face_node_connectivity must be 2D, got {self._face_nodes.ndim}D."
            )
        valid_indices = self._face_nodes[self._face_nodes != self._fill_value]
        if len(valid_indices) > 0:
            if valid_indices.min() < 0 or valid_indices.max() >= self.n_nodes:
                raise ValueError(
                    f"face_node_connectivity indices must be in "
                    f"[0, {self.n_nodes}), got range "
                    f"[{valid_indices.min()}, {valid_indices.max()}]."
                )
        if self._edge_nodes is not None:
            if self._edge_nodes.ndim != 2 or self._edge_nodes.shape[1] != 2:
                raise ValueError(
                    f"edge_node_connectivity must have shape (n_edges, 2), "
                    f"got {self._edge_nodes.shape}."
                )

        self._cached_triangulation: mtri.Triangulation | None = None
        self._cached_tri_array: np.ndarray | None = None
        self._cached_nodes_per_face: np.ndarray | None = None
        self._cached_face_centroids: np.ndarray | None = None
        #: Delegate `VectorGlyph` from the most recent `plot_vector_field`
        #: call; `None` before the first. Each call builds a fresh delegate
        #: (which owns its own arrow artists), so this reference is what lets
        #: a composed re-render clear the previous call's arrows instead of
        #: stacking a second field on top.
        self._vector_field_glyph: VectorGlyph | None = None
        self._cbar: Colorbar | None = None
        #: Colour-mapped artist from the most recent `plot` call (the
        #: `tripcolor`/`tricontour(f)` mappable); `None` before first render.
        self.im: Any = None
        #: Per-frame time-label `Text` artist from the most recent
        #: `animate` call, if any; `None` before any `animate` call.
        self._day_text = None
        #: Inline contour-label `Text` artists from the most recent
        #: `plot(location="node", filled=False, labels=True)`, or `None`
        #: when labelling was not requested (the default, and for
        #: `tripcolor`/`tricontourf`); an empty list when the line
        #: tricontour has no isolines.
        self.contour_labels = None
        #: `hillshade` set at construction. `plot()` resets `default_options`
        #: to the class defaults on each call, so this is restored there when
        #: `hillshade` is not overridden at `plot()` time -- keeping the option
        #: honoured at construction, consistent with `ArrayGlyph`/`KDEGlyph`.
        self._construct_hillshade = self.default_options.get("hillshade", False)
        #: The sticky `style` preset. `plot()` resets `default_options` each
        #: call, so this tracks the current preset (updated whenever `plot()` /
        #: `apply_style` passes `style`, including `None` to clear) and is
        #: restored after the reset -- so a style survives a later plain
        #: `plot(data)` (sticky + clearable, like `ArrayGlyph`).
        self._style_state = self.default_options.get("style")
        #: `(host_axes, pre-steal bounds)` captured when the most recent
        #: composed `plot_vector_field` drew its own colorbar, else `None`.
        #: On a multi-axes figure `create_color_bar` takes matplotlib's
        #: `make_axes` path, whose `Colorbar.remove()` never hands the stolen
        #: layout space back -- so when a composed re-render clears the
        #: previous overlay bar, the host is restored from this record or
        #: repeated re-renders would shrink it monotonically.
        self._vector_host_bounds: tuple[Any, Any] | None = None
        #: Sticky `projection` preset (like `_style_state`): restored after the
        #: `plot()` options reset so a constructor-time `projection=` survives a
        #: later plain `plot(data)`.
        self._projection_state = self.default_options.get("projection")
        #: Last `(data, location)` rendered, so `apply_style` can restyle in
        #: place without the caller re-supplying the mesh data.
        self._last_data: np.ndarray | None = None
        self._last_location = "face"

    @property
    def node_x(self) -> np.ndarray:
        """Node x-coordinates.

        Returns:
            np.ndarray: 1D float array of node x-coordinates, in node
                order (length ``n_nodes``).

        Examples:
            - Read back the x-coordinates and pick out a single node:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5]),
                ...     np.array([0.0, 0.0, 1.0]),
                ...     np.array([[0, 1, 2]]),
                ... )
                >>> mg.node_x
                array([0. , 1. , 0.5])
                >>> float(mg.node_x[1])
                1.0

                ```
        """
        return self._node_x

    @property
    def node_y(self) -> np.ndarray:
        """Node y-coordinates.

        Returns:
            np.ndarray: 1D float array of node y-coordinates, in node
                order (length ``n_nodes``).

        Examples:
            - Read back the y-coordinates and take their maximum:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5]),
                ...     np.array([0.0, 0.0, 1.0]),
                ...     np.array([[0, 1, 2]]),
                ... )
                >>> mg.node_y
                array([0., 0., 1.])
                >>> float(mg.node_y.max())
                1.0

                ```
        """
        return self._node_y

    @property
    def n_faces(self) -> int:
        """Number of faces in the mesh.

        Returns:
            int: Count of faces (rows of the face-node connectivity),
                regardless of how many nodes each face has.

        Examples:
            - A two-face mesh reports two faces, one row per face:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5, 1.5]),
                ...     np.array([0.0, 0.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 2], [1, 3, 2]]),
                ... )
                >>> mg.n_faces
                2

                ```
        """
        return int(self._face_nodes.shape[0])

    @property
    def n_nodes(self) -> int:
        """Number of nodes in the mesh.

        Returns:
            int: Count of nodes, i.e. the length of the coordinate
                arrays ``node_x``/``node_y``.

        Examples:
            - The node count matches the coordinate array length:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5, 1.5]),
                ...     np.array([0.0, 0.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 2], [1, 3, 2]]),
                ... )
                >>> mg.n_nodes
                4

                ```
        """
        return len(self._node_x)

    @property
    def n_edges(self) -> int:
        """Number of edges (0 if edge connectivity not provided).

        Edges are only counted when explicit ``edge_node_connectivity``
        was supplied at construction; otherwise this is 0 even though the
        mesh has implicit polygon edges (which ``plot_outline`` derives on
        demand).

        Returns:
            int: Number of rows in ``edge_node_connectivity``, or 0 when
                no edge connectivity was given.

        Examples:
            - Without explicit edges the count is 0:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5]),
                ...     np.array([0.0, 0.0, 1.0]),
                ...     np.array([[0, 1, 2]]),
                ... )
                >>> mg.n_edges
                0

                ```
            - Supplying ``edge_node_connectivity`` makes the count match
                the number of edge rows:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 1.0, 0.0]),
                ...     np.array([0.0, 0.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 2, 3]]),
                ...     edge_node_connectivity=np.array(
                ...         [[0, 1], [1, 2], [2, 3], [3, 0]]
                ...     ),
                ... )
                >>> mg.n_edges
                4

                ```
        """
        return self._edge_nodes.shape[0] if self._edge_nodes is not None else 0

    @property
    def nodes_per_face(self) -> np.ndarray:
        """Number of valid nodes per face (excluding fill values).

        Returns:
            np.ndarray: 1D integer array of length n_faces.

        Examples:
            - Pure triangular mesh returns all 3s:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5, 1.5]),
                ...     np.array([0.0, 0.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 2], [1, 3, 2]]),
                ... )
                >>> mg.nodes_per_face
                array([3, 3])

                ```
            - Mixed mesh with quads and triangles:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 2.0, 0.0, 1.0, 2.0]),
                ...     np.array([0.0, 0.0, 0.0, 1.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 4, 3], [1, 2, 5, -1]]),
                ...     fill_value=-1,
                ... )
                >>> mg.nodes_per_face
                array([4, 3])

                ```
        """
        if self._cached_nodes_per_face is None:
            self._cached_nodes_per_face = np.sum(
                self._face_nodes != self._fill_value, axis=1
            ).astype(np.intp)
        return self._cached_nodes_per_face

    @property
    def face_centroids(self) -> np.ndarray:
        """Face centroids: the mean of each face's valid node coordinates.

        The centroid is the arithmetic mean of the face's valid (non-fill)
        vertices -- the vertex centroid, not the area centroid. For the
        convex, well-shaped cells of a typical UGRID mesh the two are close,
        and the vertex centroid is what `plot_vector_field` anchors
        face-located arrows at. A face with no valid nodes yields a NaN row.

        Returns:
            np.ndarray: `(n_faces, 2)` float array of `(x, y)` centroids, in
                face order.

        Examples:
            - The centroid of a triangle is the mean of its three vertices:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5]),
                ...     np.array([0.0, 0.0, 1.0]),
                ...     np.array([[0, 1, 2]]),
                ... )
                >>> mg.face_centroids
                array([[0.5       , 0.33333333]])

                ```
            - A mixed mesh averages only each face's valid nodes:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 2.0, 0.0, 1.0, 2.0]),
                ...     np.array([0.0, 0.0, 0.0, 1.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 4, 3], [1, 2, 5, -1]]),
                ...     fill_value=-1,
                ... )
                >>> mg.face_centroids
                array([[0.5       , 0.5       ],
                       [1.66666667, 0.33333333]])

                ```

        See Also:
            plot_vector_field: Anchors face-located `(u, v)` arrows at these
                centroids.
            nodes_per_face: The per-face valid-node counts the mean divides by.
        """
        if self._cached_face_centroids is None:
            valid = self._face_nodes != self._fill_value
            safe_idx = np.where(valid, self._face_nodes, 0)
            counts = self.nodes_per_face.astype(np.float64)
            with np.errstate(invalid="ignore", divide="ignore"):
                cx = np.where(valid, self._node_x[safe_idx], 0.0).sum(axis=1) / counts
                cy = np.where(valid, self._node_y[safe_idx], 0.0).sum(axis=1) / counts
            self._cached_face_centroids = np.column_stack([cx, cy])
        return self._cached_face_centroids

    @property
    def triangulation(self) -> mtri.Triangulation:
        """Matplotlib Triangulation built via fan decomposition.

        Each face with N valid nodes is decomposed into (N-2)
        triangles by fanning from the first vertex. Faces with
        fewer than 3 valid nodes are skipped.

        Returns:
            matplotlib.tri.Triangulation: Triangulation ready for
                tripcolor/tricontourf.

        Raises:
            ValueError: If no faces have 3 or more valid nodes.

        Examples:
            - Build a triangulation and check its shape:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5]),
                ...     np.array([0.0, 0.0, 1.0]),
                ...     np.array([[0, 1, 2]]),
                ... )
                >>> tri = mg.triangulation
                >>> tri.triangles.shape
                (1, 3)

                ```
        """
        if self._cached_triangulation is None:
            tri_array = self._fan_triangles()
            self._cached_triangulation = mtri.Triangulation(
                self._node_x, self._node_y, tri_array
            )
        return self._cached_triangulation

    def _fan_triangles(self) -> np.ndarray:
        """Compute fan triangulation for mixed-element meshes.

        Each face with N valid nodes is decomposed into (N-2) triangles
        using fan decomposition from the first vertex. Pure-triangle
        meshes use a fast path that returns the connectivity directly.

        Returns:
            np.ndarray: (n_triangles, 3) array of node indices.

        Raises:
            ValueError: If no valid triangles can be formed.

        Examples:
            - A single quad fans into two triangles from its first vertex:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 1.0, 0.0]),
                ...     np.array([0.0, 0.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 2, 3]]),
                ... )
                >>> mg._fan_triangles()
                array([[0, 1, 2],
                       [0, 2, 3]])

                ```
            - A mixed mesh (quad + triangle) keeps faces in order; the
                quad's two triangles come first, then the triangle:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 2.0, 0.0, 1.0]),
                ...     np.array([0.0, 0.0, 0.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 4, 3], [1, 2, 4, -1]]),
                ...     fill_value=-1,
                ... )
                >>> mg._fan_triangles()
                array([[0, 1, 4],
                       [0, 4, 3],
                       [1, 2, 4]])

                ```
        """
        if self._cached_tri_array is not None:
            return self._cached_tri_array

        counts = self.nodes_per_face

        if not np.any(counts >= 3):
            raise ValueError("Cannot create triangulation: no faces with 3+ nodes.")

        if self._face_nodes.shape[1] == 3 and np.all(counts == 3):
            self._cached_tri_array = self._face_nodes.copy()
            return self._cached_tri_array

        flat_nodes = self._face_nodes[self._face_nodes != self._fill_value]
        face_start = np.cumsum(counts) - counts

        # A face with c valid nodes produces (c - 2) fan triangles.
        valid = counts >= 3
        base = np.repeat(face_start[valid], counts[valid] - 2)
        t = self._grouped_arange(counts[valid] - 2)

        # Triangle (v0, v_{t+1}, v_{t+2}) fanning from each face's first vertex.
        first = flat_nodes[base]
        second = flat_nodes[base + 1 + t]
        third = flat_nodes[base + 2 + t]

        self._cached_tri_array = np.stack([first, second, third], axis=1)
        return self._cached_tri_array

    @staticmethod
    def _grouped_arange(sizes: np.ndarray) -> np.ndarray:
        """Concatenated per-group ranges: ``[0..s0-1, 0..s1-1, ...]``.

        Vectorized equivalent of
        ``np.concatenate([np.arange(s) for s in sizes])``. Zero-size groups
        contribute nothing and are handled correctly.

        Args:
            sizes: 1D array of non-negative group sizes.

        Returns:
            np.ndarray: 1D intp array of length ``sizes.sum()``.

        Examples:
            - Each group ``i`` contributes the range ``0..sizes[i]-1``,
                concatenated in order:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> MeshGlyph._grouped_arange(np.array([2, 3, 1]))
                array([0, 1, 0, 1, 2, 0])

                ```
            - Zero-size groups contribute nothing and do not shift the
                counter of later groups:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> MeshGlyph._grouped_arange(np.array([2, 0, 3]))
                array([0, 1, 0, 1, 2])

                ```
        """
        sizes = np.asarray(sizes, dtype=np.intp)
        total = int(sizes.sum())
        if total == 0:
            return np.empty(0, dtype=np.intp)
        group_start = np.cumsum(sizes) - sizes
        return np.asarray(
            np.arange(total, dtype=np.intp) - np.repeat(group_start, sizes)
        )

    def _map_face_to_triangle_values(self, face_values: np.ndarray) -> np.ndarray:
        """Map per-face values to per-triangle values.

        Each original face may produce multiple triangles via fan
        decomposition. All triangles from the same face receive
        the same data value.

        Args:
            face_values: 1D array of values, one per face.

        Returns:
            np.ndarray: 1D array of values, one per triangle.

        Examples:
            - Quad face produces 2 triangles with the same value:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 1.0, 0.0]),
                ...     np.array([0.0, 0.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 2, 3]]),
                ... )
                >>> mg._map_face_to_triangle_values(np.array([42.0]))
                array([42., 42.])

                ```
        """
        counts = self.nodes_per_face
        valid = counts >= 3
        return np.repeat(face_values[valid], counts[valid] - 2)

    def _validate_location_and_data(self, data: np.ndarray, location: str) -> None:
        """Validate location string and data length."""
        if location not in ("face", "node"):
            raise ValueError(
                f"Plotting not supported for location='{location}'. "
                f"Use 'face' or 'node'."
            )
        expected = self.n_faces if location == "face" else self.n_nodes
        if len(data) != expected:
            raise ValueError(
                f"data length ({len(data)}) does not match n_{location}s ({expected})."
            )

    def _apply_projection(self) -> None:
        """Reproject the mesh onto the `projection` preset and frame the axes.

        Replaces the cached triangulation with one on the reprojected (e.g.
        orthographic-globe) node coordinates -- far-hemisphere triangles masked
        -- and draws the globe boundary + graticule. Must run after the axes is
        cleared and before the mesh is drawn, so the render uses the reprojected
        triangulation.

        Owns the projection frame's lifecycle: every call first removes the
        boundary/graticule drawn on a previous render (they are not
        `_mark_render_artists`-tracked, so a replot would otherwise stack a
        duplicate frame). When `projection` is cleared to a falsy value, it drops
        the reprojected triangulation cache so the `triangulation` property
        rebuilds the flat mesh, and -- if a globe frame was present -- restores
        the flat axes view (the globe froze the limits/axis-off), otherwise a
        `plot(projection=None)` after a globe would silently render the flat mesh
        into a frozen, axis-off view as an invisible speck.
        """
        had_frame = _clear_projection_frame(self.ax)
        projection = self.default_options.get("projection")
        if not projection_draws_frame(projection):
            self._cached_triangulation = None
            if had_frame:
                _restore_flat_axes(
                    self.ax,
                    float(self._node_x.min()),
                    float(self._node_x.max()),
                    float(self._node_y.min()),
                    float(self._node_y.max()),
                    aspect="equal",
                )
            return
        before = set(map(id, self.ax.patches)) | set(map(id, self.ax.lines))
        self._cached_triangulation = apply_projection_style_mesh(
            self.ax,
            self._node_x,
            self._node_y,
            self._fan_triangles(),
            style=cast(Any, projection),
        )
        _stash_projection_frame(
            self.ax,
            [a for a in (*self.ax.patches, *self.ax.lines) if id(a) not in before],
        )

    def _render_mesh(
        self,
        ax,
        data: np.ndarray,
        location: str,
        edgecolor: str = "none",
        norm=None,
        filled: bool = True,
        **render_kwargs,
    ):
        """Render mesh data on axes and return the mappable.

        Args:
            ax: Matplotlib axes.
            data: 1D data array.
            location: `"face"` or `"node"`.
            edgecolor: Edge color for face rendering.
            norm: Color normalization.
            filled: For node data, whether to draw filled contours
                (`tricontourf`, the default) or line contours
                (`tricontour`). Ignored for face data, which always uses
                `tripcolor`.
            **render_kwargs: Passed to tripcolor, tricontourf, or
                tricontour.

        Returns:
            ScalarMappable: The tripcolor, tricontourf, or tricontour
                result.
        """
        tri = self.triangulation
        cmap = resolve_colormap(self.default_options["cmap"])
        vmin = self.default_options["vmin"]
        vmax = self.default_options["vmax"]

        if location == "face":
            tri_values = self._map_face_to_triangle_values(data)
            kw: dict[str, Any] = {"cmap": cmap, "edgecolors": edgecolor}
            if norm is not None:
                kw["norm"] = norm
            else:
                kw["vmin"] = vmin
                kw["vmax"] = vmax
            kw.update(render_kwargs)
            return ax.tripcolor(tri, facecolors=tri_values, **kw)

        levels = self.default_options["levels"]
        contour_kw: dict[str, Any] = {
            "cmap": cmap,
            "levels": 20 if levels is None else levels,
        }
        if norm is not None:
            contour_kw["norm"] = norm
        else:
            if vmin is not None:
                contour_kw["vmin"] = vmin
            if vmax is not None:
                contour_kw["vmax"] = vmax
        contour_kw.update(render_kwargs)
        if filled:
            return ax.tricontourf(tri, data, **contour_kw)
        return ax.tricontour(tri, data, **contour_kw)

    def _render_shaded_relief(
        self,
        ax: Any,
        data: np.ndarray,
        edgecolor: str,
        norm: Any,
        hillshade: dict[str, Any],
        **render_kwargs: Any,
    ) -> Any:
        """Render the mesh as a relief-shaded terrain surface (node elevation).

        Colours each triangle by its mean node elevation, then blends the
        triangle-normal hillshade into those colours via
        `cleopatra.glyphs.base.hillshade.shade_faces`, so a wide-range terrain mesh reads
        by form. The returned `tripcolor` mappable keeps its cmap/norm, so the
        colorbar spans the **node** elevation range (`vmin`/`vmax` from the
        per-node `data`). Note that faces are coloured by each triangle's
        *mean* node elevation, whose range is narrower than the node range on
        any mesh with within-triangle variation, so the colorbar's extreme
        colours may not appear on the surface — the bar reflects the input
        data range, not the drawn per-face means. Requires node-centered
        `data` (the surface's per-node elevation).

        Note:
            Hillshade is intended for native (flat) coordinates. Under
            `projection="globe"` the triangulation is in orthographic **metres**
            (~1e6) while elevations stay in metres (~1e3), so the surface reads
            as nearly flat in the xy frame and the relief washes out. Combine
            hillshade with the plain (flat) mesh, not the globe.

        Args:
            ax: Axes to draw on.
            data: Node-centered elevation (one value per mesh node).
            edgecolor: Triangle edge colour.
            norm: Colour normalization, or `None` to use `vmin`/`vmax`.
            hillshade: Resolved hillshade settings.
            **render_kwargs: Forwarded to `tripcolor`.

        Returns:
            The `tripcolor` mappable, with per-face colours set to the shaded
            RGBA.
        """
        tri = self.triangulation
        z_nodes = np.asarray(data, dtype=float)
        tri_faces = tri.triangles
        tri_z = z_nodes[tri_faces].mean(axis=1)

        kw: dict[str, Any] = {
            "cmap": resolve_colormap(self.default_options["cmap"]),
            "edgecolors": edgecolor,
        }
        if norm is not None:
            kw["norm"] = norm
        else:
            kw["vmin"] = self.default_options["vmin"]
            kw["vmax"] = self.default_options["vmax"]
        kw.update(render_kwargs)
        tpc = ax.tripcolor(tri, facecolors=tri_z, **kw)

        node_xy = np.column_stack([tri.x, tri.y])
        base_rgba = tpc.to_rgba(tri_z)
        shaded = shade_faces(node_xy, tri_faces, z_nodes, base_rgba, **hillshade)
        nan_faces = ~np.isfinite(z_nodes[tri_faces]).all(axis=1)
        shaded[nan_faces] = 0.0
        tpc.set_array(None)
        tpc.set_alpha(None)
        tpc.set_facecolor(shaded)
        return tpc

    @property
    def style(self) -> str | None:
        """Name of the `DATA_STYLES` preset currently applied, or `None`.

        Reads back the preset set via the `style` constructor kwarg, a
        `plot(style=...)` call, or `apply_style`.
        """
        return self.default_options.get("style")

    def apply_style(
        self, style: str, data: np.ndarray | None = None, **kwargs: Any
    ) -> tuple[plt.Figure, plt.Axes]:
        """Apply a `DATA_STYLES` preset by name, re-rendering the mesh in place.

        A discoverable wrapper over `plot(style=...)` for restyling an
        already-built glyph. It redraws **in place** on the glyph's own axes
        (taking full ownership -- do not use on a shared axes), or on a fresh
        figure if the glyph was never plotted or its figure was closed. It
        reuses the last-plotted mesh data (and location) so the caller need not
        re-supply it; pass `data=` when the glyph has not been plotted yet. The
        applied style is **sticky** (survives a later plain `plot(data)`);
        `plot(data, style=None)` clears it. Extra keyword arguments (e.g.
        `location`, `hillshade`, `edgecolor`) are forwarded to `plot`.

        Args:
            style: A `cleopatra.styling.colors.DATA_STYLES` preset name.
            data: Mesh data to render; defaults to the last-plotted data.
            **kwargs: Forwarded to `plot` (e.g. `location`, `hillshade`).

        Returns:
            tuple[Figure, Axes]: The figure and axes drawn on.

        Raises:
            ValueError: If `style` is unknown (raised by `plot`), or no data is
                available (never plotted and none passed).
        """
        resolve_single_layer_style(style)
        if data is None:
            data = self._last_data
            if data is None:
                raise ValueError(
                    "apply_style needs mesh data: call plot(data, ...) first, "
                    "or pass data= explicitly."
                )
        location = kwargs.pop("location", self._last_location)
        self._reset_axes_for_restyle()
        # Fold style (and an optional forwarded hillshade) into the grouped
        # data_style object; leaving hillshade unset keeps any sticky value.
        if "hillshade" in kwargs:
            data_style = DataStyle.for_apply_style(
                style, hillshade=kwargs.pop("hillshade")
            )
        else:
            data_style = DataStyle.for_apply_style(style)
        return self.plot(
            data, location=location, ax=self.ax, data_style=data_style, **kwargs
        )

    def plot(
        self,
        data: np.ndarray,
        location: str = "face",
        ax: Any = None,
        edgecolor: str = "none",
        colorbar: bool | ColorBar | None = None,
        title: str | None = None,
        filled: bool = True,
        color: ColorScaling | None = None,
        contour: Contour | None = None,
        data_style: DataStyle | None = None,
        compose: bool = False,
        **kwargs: Any,
    ) -> tuple[plt.Figure, plt.Axes]:
        """Plot mesh data using matplotlib triangulation.

        For face-centered data, uses `tripcolor` where each triangle
        is colored by the value of its parent face. For node-centered
        data, uses `tricontourf` for smooth interpolated filled
        contours, or `tricontour` for line contours when
        `filled=False`.

        Supports all 6 color scale types from `default_options`:
        linear, power, sym-lognorm, lognorm, boundary-norm, and midpoint.

        Args:
            data: 1D data array. Length must match face count
                (location="face") or node count (location="node").
            location: Mesh element location: `"face"` or `"node"`.
                Default is `"face"`.
            ax: Axes to plot on. If None, resolution priority is the axes
                bound at construction > an axes derived from a figure bound
                at construction (its first axes, or a fresh one) > a new
                figure/axes.
            edgecolor: Edge color for face rendering. Default is
                `"none"`.
            colorbar: Draw a colorbar. `None` (default) draws one for a normal
                render but suppresses it under `compose=True` (an overlay's
                colorbar would re-lay-out the host axes); `True` or a typed
                `ColorBar` spec (placement / caption / sizing) always draws one,
                even composing; `False` suppresses it.
            title: Plot title. Overrides `default_options["title"]`.
            filled: For node data, draw filled contours (`tricontourf`,
                the default) or line contours (`tricontour`) when
                `False`. Ignored for face data. Default is True.
            color: Colour-scale group object
                (`cleopatra.styling.scaling.ColorScaling`), e.g.
                `ColorScaling.power(gamma=0.7)`. Replaces the loose
                `color_scale` / `gamma` / `line_threshold` / `line_scale` /
                `bounds` / `midpoint` keywords.
            contour: Discretisation / inline-label group object
                (`cleopatra.styling.params.Contour`). `Contour(levels=N)`
                discretises the colour norm and sets the node line/filled
                contour count (default 20 when unset);
                `Contour(labels=True, label_kw=...)` draws inline numeric
                labels via `ax.clabel` on a line tricontour
                (`location="node"`, `filled=False`) and stores the `Text`
                artists on `self.contour_labels` -- a no-op for `tripcolor`
                (face data) and `tricontourf`. Replaces the loose `levels`
                / `labels` / `label_kw` keywords.
            data_style: Named-preset / relief-shading group object
                (`cleopatra.styling.params.DataStyle`), e.g.
                `DataStyle(style="dem", hillshade=True)`. Replaces the
                loose `style` / `hillshade` keywords.
            compose: Draw *over* whatever is already on `ax` instead of
                replacing it, by default `False`. `False` clears every glyph's
                prior artists from the axes first (the replace-don't-orphan
                default); `True` clears only this glyph's own prior artists, so
                a mesh can be layered onto a host raster / another glyph -- the
                same opt-in `ArrayGlyph` and `VectorGlyph` expose. A composed
                overlay still applies any framing you pass explicitly
                (`title=`, `xlabel=`, …) and its own aspect, but leaves the
                host's existing title / ticks / labels and colorbar untouched
                when you pass none.
            **kwargs: Construction-time-style overrides for the non-grouped
                `default_options` (`cmap`, `vmin`, `vmax`, `title_size`,
                `figsize`, …). The loose `ticks_spacing` / `cbar_*` keys
                still work, but prefer `colorbar=ColorBar(...)`.
                The colour-scale, discretisation/label, and
                preset/relief options moved onto the `color=` / `contour=` /
                `data_style=` group objects above; passing any of them as a
                loose keyword now raises.

                Every call rebuilds `default_options` from
                `MESH_DEFAULT_OPTIONS`, so an option passed here applies to
                this render only and does not leak into the next one. The
                axis-styling keys (`xlabel`, `ylabel`, their font sizes, the
                tick label sizes and `grid_alpha`) are the exception: those
                given to the constructor are carried back across the reset, so
                `MeshGlyph(..., xlabel="x")` keeps labelling every render. A key
                passed here wins over the constructor's for this call.

                One relief option is honoured **only** for node data
                (`location="node"`):

                - `hillshade` (bool | dict, default `False`): render the
                  mesh as a relief-shaded terrain surface. Each triangle is
                  coloured by its *mean* node elevation and blended with a
                  triangle-normal hillshade. The colorbar spans the **node**
                  elevation range, so — because faces use per-triangle means
                  — its extreme colours may not appear on the surface; the
                  bar reflects the input data range, not the drawn per-face
                  colours. Faces touching a non-finite (nodata) node render
                  transparent. Passing `hillshade` with `location="face"`
                  raises `ValueError`.

                A data-style preset option:

                - `style` (str, default `None`): name of a
                  `cleopatra.styling.colors.DATA_STYLES` preset (valid names:
                  `sorted(cleopatra.styling.colors.DATA_STYLES)`). A continuous preset
                  overrides the cmap + norm (and composes with `hillshade`); a
                  categorical preset builds a discrete colormap, masks
                  out-of-range codes transparent, and draws a legend instead of
                  the colorbar. Takes precedence over `cmap`/`color_scale`.

        Returns:
            tuple[Figure, Axes]: The matplotlib Figure and Axes objects.
                When no axes exist, a new figure is created. Call
                `plt.close(fig)` after saving to avoid memory leaks
                in batch processing.

        Raises:
            ValueError: If `location` is not `"face"` or `"node"`,
                or if `data` length does not match the expected mesh
                dimension.

        Examples:
            - Plot face-centered data:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> fig, ax = mg.plot(np.array([1.0, 2.0]))

                ```
            - Plot node-centered data:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> fig, ax = mg.plot(
                ...     np.array([0.0, 1.0, 2.0, 3.0]),
                ...     location="node",
                ... )

                ```
            - Plot node-centered data as line contours
                (`tricontour`) instead of filled:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> fig, ax = mg.plot(
                ...     np.array([0.0, 1.0, 2.0, 3.0]),
                ...     location="node",
                ...     filled=False,
                ... )

                ```
            - Label the line tricontours inline (`labels=True`); the
                `Text` artists are exposed on `glyph.contour_labels`:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> fig, ax = mg.plot(
                ...     np.array([0.0, 1.0, 2.0, 3.0]),
                ...     location="node",
                ...     filled=False,
                ...     contour=Contour(labels=True, label_kw={"fmt": "%.1f"}),
                ... )
                >>> isinstance(mg.contour_labels, list)
                True

                ```
            - Plot with power color scale:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> fig, ax = mg.plot(
                ...     np.array([1.0, 2.0]),
                ...     color=ColorScaling.power(gamma=0.5),
                ...     cmap="coolwarm",
                ... )

                ```
        """
        self._validate_location_and_data(data, location)

        if np.all(np.isnan(data)):
            raise ValueError("data is entirely NaN, cannot determine color range.")

        self._default_options = MESH_DEFAULT_OPTIONS.copy()

        render_kwargs: dict[str, Any] = {}
        option_kwargs: dict[str, Any] = {}
        for key, val in kwargs.items():
            if key in self.default_options:
                option_kwargs[key] = val
            else:
                render_kwargs[key] = val
        self._merge_kwargs(option_kwargs)
        self._restore_construction_axis_style(option_kwargs)
        self._merge_group_params(color, contour, data_style)
        resolved_colorbar = (
            _resolve_colorbar(colorbar) if isinstance(colorbar, ColorBar) else {}
        )
        self.default_options.update(resolved_colorbar)
        # A composed overlay's colorbar takes space from the host axes and
        # re-lays it out, so composing defaults the colorbar off; only an
        # explicit request (colorbar=True or a ColorBar spec) still draws one.
        # Outside compose the historical default holds: draw unless colorbar is
        # False. Same contract as ArrayGlyph / VectorGlyph, but hand-rolled
        # rather than delegated to Glyph._draws_own_colorbar: mesh never plumbs
        # colorbar= into default_options["add_colorbar"] (which that helper reads,
        # defaulting True), so delegating would draw for colorbar=False outside
        # compose. Keep this in sync with _draws_own_colorbar if the contract
        # changes.
        if colorbar is False:
            draw_colorbar = False
        elif compose:
            draw_colorbar = colorbar is not None
        else:
            draw_colorbar = True

        # `style`/`hillshade` now arrive via the `data_style` group object;
        # detect whether this call provided each so the sticky-state logic
        # (a preset persists across later plain plots) still applies.
        ds_opts = data_style.to_options() if data_style is not None else {}
        if "hillshade" not in ds_opts:
            self.default_options["hillshade"] = self._construct_hillshade
        if "style" in ds_opts:
            new_style = self.default_options["style"]
            if new_style is not None:
                try:
                    resolve_single_layer_style(new_style)
                except ValueError:
                    self.default_options["style"] = self._style_state
                    raise
            self._style_state = new_style
        else:
            self.default_options["style"] = self._style_state
        if "projection" in option_kwargs:
            self._projection_state = self.default_options["projection"]
        else:
            self.default_options["projection"] = self._projection_state

        self._last_data = (
            np.ma.copy(data) if np.ma.isMaskedArray(data) else np.array(data, copy=True)
        )
        self._last_location = location

        if "vmin" not in option_kwargs:
            self.default_options["vmin"] = float(np.nanmin(data))
        if "vmax" not in option_kwargs:
            self.default_options["vmax"] = float(np.nanmax(data))
        self._vmin = self.default_options["vmin"]
        self._vmax = self.default_options["vmax"]

        if (
            "ticks_spacing" not in option_kwargs
            and "ticks_spacing" not in resolved_colorbar
        ):
            spacing = (self._vmax - self._vmin) / 10
            self.default_options["ticks_spacing"] = max(spacing, 1e-10)
        self.ticks_spacing = self.default_options["ticks_spacing"]

        if title is not None:
            self.default_options["title"] = title

        if ax is not None:
            self.ax = ax
            self.fig = ax.get_figure()
        elif self.fig is None:
            self.fig, self.ax = self.create_figure_axes()
        elif self.ax is None:
            # A figure was bound without an axes: draw into the caller's figure
            # (its first axes, or a fresh one) rather than leaving self.ax None.
            self.ax = self.fig.axes[0] if self.fig.axes else self.fig.add_subplot(111)

        ticks = self.get_ticks()
        norm, cbar_kw = self._create_norm_and_cbar_kw(ticks)

        style = self.default_options.get("style")
        style_legend = None
        if style is not None:
            _, cfg = resolve_single_layer_style(style)
            data_f = np.asarray(data, dtype=float)
            categories = cfg.get("categories")
            if categories is not None:
                cats = sorted(categories, key=lambda c: c[0])
                cat_values = np.array([float(c[0]) for c in cats])
                cat_colors = [c[1] for c in cats]
                cat_labels = [c[2] for c in cats]
                self.default_options["cmap"] = ListedColormap(cat_colors)
                norm = BoundaryNorm(
                    category_boundaries(list(cat_values)), len(cat_colors)
                )
                data = np.where(np.isin(data_f, cat_values), data_f, np.nan)
                colorbar = False
                # A categorical preset draws a discrete legend, never a
                # colorbar. `draw_colorbar` was resolved before the preset was
                # known, so clear it here too (not just `colorbar`).
                draw_colorbar = False
                self.default_options["hillshade"] = False
                style_legend = (cat_colors, cat_labels, cfg["label"])
                if location == "node":
                    warnings.warn(
                        "a categorical data-style preset with location='node' "
                        "interpolates discrete class codes via tricontourf; use "
                        "location='face' for correct per-cell class colours.",
                        stacklevel=2,
                    )
            else:
                self.default_options["cmap"] = cfg["cmap"]
                norm, _, _ = resolve_style_norm(data_f, cfg)
                cbar_kw.pop("ticks", None)

        self.contour_labels = None

        hillshade = resolve_hillshade(self.default_options.get("hillshade"))
        if hillshade is not None:
            if location != "node":
                raise ValueError(
                    "hillshade needs node-centered elevation; pass location='node'"
                )
            _clear_prior_render_artists(self.ax, self, compose=compose)
            self.im = None
            self._cbar = None
            self._apply_projection()
            tpc = self._render_shaded_relief(
                self.ax, data, edgecolor, norm, hillshade, **render_kwargs
            )
        else:
            _clear_prior_render_artists(self.ax, self, compose=compose)
            self.im = None
            self._cbar = None
            self._apply_projection()
            tpc = self._render_mesh(
                self.ax,
                data,
                location,
                edgecolor=edgecolor,
                norm=norm,
                filled=filled,
                **render_kwargs,
            )
        self.im = tpc

        if (
            location == "node"
            and not filled
            and hillshade is None
            and self.default_options.get("labels")
        ):
            label_kw = {
                "inline": True,
                "fontsize": 8,
                "fmt": "%g",
                **(self.default_options.get("label_kw") or {}),
            }
            self.contour_labels = self.ax.clabel(tpc, **label_kw)

        if draw_colorbar:
            self._cbar = self.create_color_bar(self.ax, tpc, cbar_kw)

        if style_legend is not None:
            cat_colors, cat_labels, cat_title = style_legend
            disjoint_legend(
                self.ax, cat_colors, cat_labels, title=cat_title, loc="upper right"
            )

        # Honour an explicit title/axis-style even when composing, as ArrayGlyph
        # does: the default title is None, and _apply_axis_style applies only
        # explicitly-passed options, so a bare overlay leaves the host framing
        # untouched while an explicit title=/xlabel=/... is still applied.
        if self.default_options["title"]:
            self.ax.set_title(
                self.default_options["title"],
                fontsize=self.default_options["title_size"],
            )
        self._apply_axis_style(self.ax)
        self.ax.set_aspect("equal")

        _mark_render_artists(self.ax, self, self._cbar, self.im)
        return self.fig, self.ax

    def animate(
        self,
        data: np.ndarray | list[np.ndarray],
        time: list[Any],
        location: str = "face",
        edgecolor: str = "none",
        interval: int = 200,
        text_loc: list | None = None,
        colorbar: bool | ColorBar | None = None,
        color: ColorScaling | None = None,
        contour: Contour | None = None,
        data_style: DataStyle | None = None,
        compose: bool = False,
        **kwargs: Any,
    ) -> FuncAnimation:
        """Create an animation from time-varying mesh data.

        Iterates over the first dimension of `data` (or elements of a
        list), rendering each frame on the fixed mesh topology.

        Args:
            data: Sequence of data arrays. If a 2D ndarray of shape
                `(n_frames, n_elements)`, each row is one frame.
                If a list, each element is a 1D array for one frame.
            time: Labels for each frame (timestamps, strings, etc.).
                Length must match the number of frames.
            location: `"face"` or `"node"`. Default is `"face"`.
            edgecolor: Edge color for face rendering. Default is
                `"none"`.
            interval: Milliseconds between frames. Default is 200.
            text_loc: `[x, y]` position for the time label text.
                Default is `[0.1, 0.2]`.
            colorbar: Draw a colorbar. `None` (default) draws one for a normal
                render but suppresses it under `compose=True` (an overlay's
                colorbar would re-lay-out the host axes); `True` or a typed
                `ColorBar` spec (placement / caption / sizing) always draws one,
                even composing; `False` suppresses it.
            compose: Draw *over* whatever is already on the axes instead of
                replacing it, by default `False`. `True` clears only this glyph's
                own prior artists, so the animation layers onto existing content;
                explicit framing (`title=`, `xlabel=`, …) is still applied while
                the host's existing framing is left intact, and `tight_layout` is
                skipped so the host layout is preserved (see `plot`).
            **kwargs: Override any key in `default_options` (cmap,
                vmin, vmax, color_scale, gamma, midpoint, figsize,
                title, etc.). The loose `ticks_spacing` / `cbar_*` keys
                still work, but prefer `colorbar=ColorBar(...)`.
                As in `plot`, the call rebuilds `default_options` from
                `MESH_DEFAULT_OPTIONS` first, so an option passed here applies
                to this animation only -- except the axis-styling keys
                (`xlabel`, `ylabel`, their font sizes, the tick label sizes and
                `grid_alpha`), whose construction-time values are carried back
                across the reset unless this call passes the same key.

        Returns:
            FuncAnimation: The animation object. Use
                `save_animation()` to export.

        Raises:
            ValueError: If `data` frames don't match mesh topology
                or `time` length doesn't match frame count.

        Notes:
            An animation draws no inline contour labels, so this clears
            `contour_labels` back to `None`; any label artists left by a
            previous `plot(filled=False, labels=True)` call do not leak
            into the animation state.

        Examples:
            - Animate face data over 3 time steps:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> frames = np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
                >>> anim = mg.animate(frames, time=["t0", "t1", "t2"])

                ```
        """
        if text_loc is None:
            text_loc = [0.1, 0.2]

        if isinstance(data, np.ndarray) and data.ndim == 2:
            frames = [data[i] for i in range(data.shape[0])]
        else:
            frames = list(data)

        n_frames = len(frames)
        if len(time) != n_frames:
            raise ValueError(
                f"time length ({len(time)}) does not match frame count ({n_frames})."
            )
        expected = self.n_faces if location == "face" else self.n_nodes
        for i, frame in enumerate(frames):
            if len(frame) != expected:
                raise ValueError(
                    f"Frame {i}: data length ({len(frame)}) does not "
                    f"match n_{location}s ({expected})."
                )

        self._default_options = MESH_DEFAULT_OPTIONS.copy()
        self._merge_kwargs(kwargs)
        self._restore_construction_axis_style(kwargs)
        self._merge_group_params(color, contour, data_style)
        resolved_colorbar = (
            _resolve_colorbar(colorbar) if isinstance(colorbar, ColorBar) else {}
        )
        self.default_options.update(resolved_colorbar)

        if "vmin" not in kwargs:
            global_min = min(float(np.nanmin(f)) for f in frames)
            self.default_options["vmin"] = global_min
        if "vmax" not in kwargs:
            global_max = max(float(np.nanmax(f)) for f in frames)
            self.default_options["vmax"] = global_max
        self._vmin = self.default_options["vmin"]
        self._vmax = self.default_options["vmax"]

        if "ticks_spacing" not in kwargs and "ticks_spacing" not in resolved_colorbar:
            spacing = (self._vmax - self._vmin) / 10
            self.default_options["ticks_spacing"] = max(spacing, 1e-10)
        self.ticks_spacing = self.default_options["ticks_spacing"]

        if self.fig is None:
            self.fig, self.ax = self.create_figure_axes()
        elif self.ax is None:
            # A figure was bound without an axes: draw into the caller's figure.
            self.ax = self.fig.axes[0] if self.fig.axes else self.fig.add_subplot(111)
        fig, ax = self.fig, self.ax

        ticks = self.get_ticks()
        norm, cbar_kw = self._create_norm_and_cbar_kw(ticks)

        self.contour_labels = None

        _clear_prior_render_artists(ax, self, compose=compose)
        self.im = None
        self._cbar = None

        tpc = self._render_mesh(
            ax,
            frames[0],
            location,
            edgecolor=edgecolor,
            norm=norm,
        )
        self.im = tpc
        # See plot: a composed overlay's colorbar re-lays out the host, so
        # composing defaults it off; an explicit request still draws one.
        if colorbar is False:
            draw_colorbar = False
        elif compose:
            draw_colorbar = colorbar is not None
        else:
            draw_colorbar = True
        if draw_colorbar:
            self._cbar = self.create_color_bar(ax, tpc, cbar_kw)

        # See plot: an explicit title/axis-style is honoured even when composing;
        # a bare overlay leaves the host framing intact (default title is None,
        # _apply_axis_style applies only explicitly-passed options).
        if self.default_options["title"]:
            ax.set_title(
                self.default_options["title"],
                fontsize=self.default_options["title_size"],
            )
        self._apply_axis_style(ax)
        ax.set_aspect("equal")

        day_text = ax.text(
            text_loc[0],
            text_loc[1],
            " ",
            fontsize=self.default_options["cbar_label_size"],
            transform=ax.transAxes,
        )
        self._day_text = day_text

        current_mappable = [tpc]
        _mark_render_artists(ax, self, self._cbar, self.im, self._day_text)

        def _update(i):
            """Update the plot for frame i."""
            prev = current_mappable[0]
            if hasattr(prev, "collections"):
                for coll in prev.collections:
                    coll.remove()
            elif hasattr(prev, "remove"):
                prev.remove()
            current_mappable[0] = self._render_mesh(
                ax,
                frames[i],
                location,
                edgecolor=edgecolor,
                norm=norm,
            )
            day_text.set_text(str(time[i]))
            self.im = current_mappable[0]
            _mark_render_artists(ax, self, self._cbar, self.im, self._day_text)

        if not compose:
            plt.tight_layout()
        anim = FuncAnimation(
            fig,
            _update,
            frames=n_frames,
            interval=interval,
            blit=False,
        )
        self._anim = anim
        return anim

    def plot_outline(
        self,
        ax: Any = None,
        color: str = "black",
        linewidth: float = 0.3,
        figsize: tuple[int, int] = (10, 8),
        compose: bool = False,
        **kwargs: Any,
    ) -> tuple[plt.Figure, plt.Axes]:
        """Plot mesh edges as a wireframe.

        Uses `matplotlib.collections.LineCollection` for efficient
        rendering of thousands of edges.

        Args:
            ax: Axes to plot on. If None, uses stored axes or creates
                new.
            color: Edge color. Default is `"black"`.
            linewidth: Edge line width. Default is `0.3`.
            figsize: Figure size in inches. Default is `(10, 8)`.
            compose: Draw *over* whatever is already on `ax` instead of
                replacing it, by default `False`. `True` clears only this
                glyph's own prior artists, so the wireframe overlays existing
                content (see `plot`).
            **kwargs: Additional keyword arguments passed to
                `LineCollection`.

        Returns:
            tuple[Figure, Axes]: The matplotlib Figure and Axes objects.
                When `ax` is None, a new figure is created. Call
                `plt.close(fig)` after saving to avoid memory leaks
                in batch processing.

        Notes:
            An outline carries no scalar mapping, so this resets `self.im`
            to None (clearing any colour-mapped artist left by a prior
            `plot()` call).

        Examples:
            - Render a triangular mesh wireframe:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5]),
                ...     np.array([0.0, 0.0, 1.0]),
                ...     np.array([[0, 1, 2]]),
                ... )
                >>> fig, ax = mg.plot_outline(color="blue")

                ```
        """
        if ax is not None:
            self.ax = ax
            self.fig = ax.get_figure()
        elif self.fig is None:
            self.fig, self.ax = plt.subplots(1, 1, figsize=figsize)

        _clear_prior_render_artists(self.ax, self, compose=compose)
        self.im = None
        self._cbar = None

        segments = self._build_edge_segments()

        lc = mcoll.LineCollection(
            list(segments), colors=color, linewidths=linewidth, **kwargs
        )
        self.ax.add_collection(lc)
        self.ax.autoscale()
        self.ax.set_aspect("equal")

        _mark_render_artists(self.ax, self, lc)

        return self.fig, self.ax

    def _validate_vector_field(
        self,
        kind: str,
        location: str,
        u: np.ndarray,
        v: np.ndarray,
        thin: int | None,
        kwargs: dict[str, Any],
    ) -> tuple[np.ndarray, np.ndarray, int]:
        """Run every documented `plot_vector_field` rejection up front.

        Hoists the delegate-side validations (thin, the cmap name, the
        all-NaN magnitude case that `Glyph._resolve_limits` rejects only when
        `vmin`/`vmax` are unpinned) next to the mesh-side ones, so every
        rejection in the method's Raises section fires before any glyph
        state, figure, or artist is touched.

        Args:
            kind: The requested vector kind.
            location: `"face"` or `"node"`.
            u: Raw x-components as passed by the caller.
            v: Raw y-components, same length and location as `u`.
            thin: The decimation step, or `None` for all elements.
            kwargs: The loose option overrides headed for the delegate.

        Returns:
            tuple[np.ndarray, np.ndarray, int]: `u` and `v` as 1D float64
                arrays, and the resolved thinning step (`1` for `None`).

        Raises:
            ValueError: Per the `plot_vector_field` Raises contract.
        """
        if kind not in MESH_VECTOR_KINDS:
            if kind == "streamplot":
                raise ValueError(
                    "kind='streamplot' is not supported on an unstructured "
                    "mesh: streamline tracing needs a regular grid. Resample "
                    "the field to a grid and use "
                    "cleopatra.glyphs.gridded.vector_glyph.VectorGlyph."
                )
            raise ValueError(
                f"unknown vector kind {kind!r}; expected one of "
                f"{', '.join(MESH_VECTOR_KINDS)}."
            )
        u = np.asarray(u, dtype=np.float64)
        v = np.asarray(v, dtype=np.float64)
        if u.ndim != 1 or v.ndim != 1:
            raise ValueError(f"u and v must be 1D, got {u.ndim}D and {v.ndim}D.")
        if u.shape != v.shape:
            raise ValueError(
                f"u and v must have the same shape, got {u.shape} and {v.shape}."
            )
        # v mirrors u's shape, so validating u validates both.
        self._validate_location_and_data(u, location)
        # The delegate's own strict check only sees **kwargs headed for its
        # options dict; a key naming one of its constructor parameters (fig)
        # would silently bind instead of raising, abandoning the caller's
        # figure. Enforce the documented unknown-keys-raise contract here.
        unknown = set(kwargs) - VectorGlyph.option_keys()
        if unknown:
            raise ValueError(
                f"plot_vector_field got unknown option(s): "
                f"{', '.join(sorted(unknown))}. Valid keys are the VectorGlyph "
                f"options; bind a figure via ax= or at construction instead."
            )
        if "density" in kwargs:
            # density only affects streamplot, which this method refuses, so
            # accepting it would be a silent no-op (the delegate warns about
            # the mirrored thin-on-streamplot case for the same reason).
            raise ValueError(
                "density only affects kind='streamplot', which an "
                "unstructured mesh does not support; use thin= to control "
                "arrow density."
            )
        thin_value = 1 if thin is None else thin
        _validate_thin(thin_value, kind)
        if "cmap" in kwargs:
            resolve_colormap(kwargs["cmap"])
        if kwargs.get("vmin") is None or kwargs.get("vmax") is None:
            if not np.isfinite(np.hypot(u, v)).any():
                raise ValueError(
                    "Cannot determine vmin/vmax: no finite values. Pass "
                    "explicit vmin/vmax, or components with at least one "
                    "finite entry."
                )
        return u, v, thin_value

    def _resolve_vector_target_ax(self, ax: Any) -> Any:
        """Resolve the axes a vector render should draw on, without binding it.

        `self.fig`/`self.ax` are committed only after the delegate renders
        (see `_finish_vector_render`), so a failure between resolution and
        render never leaves the glyph rebound to a target it never drew on.

        Args:
            ax: The caller's explicit axes, or `None`.

        Returns:
            The target axes, or `None` when the delegate should create the
            figure/axes itself (honouring a `figsize=` in its options).
        """
        if ax is not None:
            return ax
        if self.ax is not None:
            return self.ax
        if self.fig is not None:
            # A figure was bound without an axes: draw into the caller's
            # figure (its first axes, or a fresh one), as `plot` does. Runs
            # after validation, so a rejected call adds no stray axes.
            return self.fig.axes[0] if self.fig.axes else self.fig.add_subplot(111)
        return None

    def _clear_previous_vector_field(self) -> None:
        """Drop the previous composed vector render's artists and layout steal.

        Each `plot_vector_field` call builds a fresh delegate that owns its
        own arrow artists, so a composed re-render removes the previous
        call's arrows itself -- on the previous delegate's own axes, since
        the glyph tracks a single current field that replaces across axes.
        The overlay colorbar's layout steal is undone from
        `_vector_host_bounds`, because on a multi-axes figure the bar was
        created through matplotlib's `make_axes` path, whose
        `Colorbar.remove()` gives no layout space back.
        """
        prev = self._vector_field_glyph
        if prev is None or prev.ax is None:
            return
        _clear_prior_render_artists(prev.ax, prev, compose=True)
        # host axes == prev.ax by construction: the pair is stored together
        # with the delegate in _finish_vector_render.
        if self._vector_host_bounds is not None:
            host_ax, host_bounds = self._vector_host_bounds
            host_ax.set_position(host_bounds)

    def _finish_vector_render(
        self,
        delegate: VectorGlyph,
        fig: Any,
        ax_out: Any,
        compose: bool,
        pre_bounds: Any,
    ) -> None:
        """Commit glyph state after a successful vector render.

        A replacing render additionally undoes a projection frame a previous
        `plot(..., projection=...)` left behind -- the frame and its frozen,
        axis-off view are tracked separately from the glyph artist registry,
        and a vector render is a non-projection render, so it restores the
        flat view exactly as `plot` does when the projection is cleared --
        and resets `im`/`_cbar`, whose artists the replacing render just
        removed (the same reset `plot_outline` performs).

        Args:
            delegate: The `VectorGlyph` that just rendered.
            fig: The figure the delegate drew into.
            ax_out: The axes the delegate drew on.
            compose: Whether this was a composed (overlay) render.
            pre_bounds: The host's position captured before the render, kept
                on `_vector_host_bounds` when the composed overlay drew its
                own colorbar so the next clear can undo the layout steal.
        """
        if not compose:
            if _clear_projection_frame(ax_out):
                _restore_flat_axes(
                    ax_out,
                    float(self._node_x.min()),
                    float(self._node_x.max()),
                    float(self._node_y.min()),
                    float(self._node_y.max()),
                    aspect="equal",
                )
            self.im = None
            self._cbar = None
        self._vector_field_glyph = delegate
        self._vector_host_bounds = (
            (ax_out, pre_bounds)
            if compose and delegate.cbar is not None and pre_bounds is not None
            else None
        )
        self.fig, self.ax = fig, ax_out
        ax_out.set_aspect("equal")

    def plot_vector_field(
        self,
        u: np.ndarray,
        v: np.ndarray,
        *,
        kind: str = "quiver",
        thin: int | None = None,
        location: str = "face",
        ax: Any = None,
        title: str | None = None,
        colorbar: bool | ColorBar | None = None,
        color: ColorScaling | None = None,
        contour: Contour | None = None,
        classify: Classify | None = None,
        compose: bool = False,
        **kwargs: Any,
    ) -> tuple[plt.Figure, plt.Axes, Any]:
        """Plot a `(u, v)` vector field anchored on the mesh.

        Face-located components (`location="face"`) draw one arrow per face,
        anchored at the face's vertex centroid (`face_centroids`); node-located
        components anchor at the nodes themselves. Rendering delegates to
        `cleopatra.glyphs.gridded.vector_glyph.VectorGlyph`, so the arrows are
        coloured by the vector magnitude `hypot(u, v)` through the shared
        scalar-mapping pipeline, with the same colorbar behaviour.

        The field is drawn in the mesh's native (flat) coordinates: a
        `projection` preset applied by `plot` reprojects only the mesh render,
        so combine a vector field with the plain mesh, not the globe. A
        *replacing* render (`compose=False`) after a globe `plot` therefore
        removes the globe frame and restores the flat view -- the same
        contract as `plot` with the projection cleared -- while a composed
        overlay leaves the host frame untouched.

        Args:
            u: 1D x-components, one per face (`location="face"`) or per node
                (`location="node"`).
            v: 1D y-components, same length and location as `u`.
            kind: `"quiver"` (arrows, the default) or `"barbs"`.
                `"streamplot"` is refused: streamline tracing needs a regular
                grid, which an unstructured mesh does not have -- resample the
                field to a grid and use `VectorGlyph` directly instead.
            thin: Draw every `thin`-th element so a large mesh stays legible;
                `None` (the default) draws them all. Must be a positive
                integer.
            location: Mesh element location the components live on:
                `"face"` (the default) anchors one arrow per face at its
                vertex centroid (`face_centroids`); `"node"` anchors one
                arrow per node at the node coordinates.
            ax: Axes to draw on. If None, resolution priority is the axes
                bound at construction or by a previous render > an axes
                derived from a figure bound at construction > a new
                figure/axes created by the delegate (honouring a `figsize=`
                passed through `**kwargs`).
            title: Plot title, applied by the delegate.
            colorbar: Draw the magnitude colorbar. `None` (default) leaves
                the decision to the delegate's contract: on for a standalone
                render, off under `compose=True`; `True` or a typed `ColorBar`
                spec (placement / caption / sizing) always draws one, even
                composing; `False` suppresses it -- the same contract as
                `plot`.
            color: Colour-scale group object
                (`cleopatra.styling.scaling.ColorScaling`) applied to the
                magnitude, e.g. `ColorScaling.power(gamma=0.5)` -- the same
                grouped parameter `plot` and `VectorGlyph.plot` take.
            contour: Discretisation group object
                (`cleopatra.styling.params.Contour`); `Contour(levels=N)`
                discretises the magnitude colour norm.
            classify: Classification group object
                (`cleopatra.styling.params.Classify`) for scheme-based
                magnitude classes, forwarded to the delegate unchanged.
            compose: Draw *over* whatever is already on the axes instead of
                replacing it, by default `False`. `True` keeps the host
                layers -- a filled `plot` render, a `plot_outline` wireframe,
                or `add_tiles`/`add_relief` backdrops -- and layers the arrows
                on top. The glyph tracks a single current field, so a
                repeated composed call replaces the previous call's arrows
                (and the colorbar they brought, if any -- ask for a new one
                with `colorbar=True`) even when they live on another axes.
                `False` keeps the replace-don't-orphan default every glyph
                render has: the axes is cleared of all glyph artists first.
                Either way the render applies the mesh convention of an equal
                axes aspect, including to a foreign host it composes onto --
                the same "a composed overlay still applies its own aspect"
                contract `plot` documents.
            **kwargs: Overrides for the delegate `VectorGlyph`'s options
                (`cmap`, `vmin`, `vmax`, `scale`, `cbar_label`, `figsize`,
                ...). An unknown key raises `ValueError`.

        Returns:
            tuple[Figure, Axes, Any]: The figure, the axes, and the `Quiver`
                or `Barbs` mappable (e.g. for `Axes.quiverkey`). Under
                `compose=True` the mesh's own `im` (the scalar mappable from
                `plot`) is left untouched; a replacing render clears the mesh
                artists from the axes and resets `im` and the colorbar
                reference to `None`, as `plot_outline` does.

        Raises:
            ValueError: If `kind` is not `"quiver"`/`"barbs"` (including the
                explicit `"streamplot"` refusal), `location` is not
                `"face"`/`"node"`, `u`/`v` are not 1D of equal length matching
                the location's element count, `thin` is not a positive
                integer, a `**kwargs` key is not a `VectorGlyph` option,
                `density` is passed (a streamplot-only option -- use `thin=`),
                or the magnitude has no finite values while `vmin`/`vmax` are
                not both given. A rejected call raises before anything is
                touched: the existing render -- mesh, arrows, and colorbars
                alike -- and the glyph's bound figure/axes all survive
                unchanged.

        Examples:
            - Arrows at the face centroids of a two-triangle mesh:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> fig, ax, im = mg.plot_vector_field(
                ...     np.array([0.3, -0.2]), np.array([0.1, 0.4])
                ... )
                >>> im.N
                2

                ```
            - Compose the field over a filled mesh render; the host layers
                and colorbar stay, and the arrows bring no second colorbar:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> fig, ax = mg.plot(np.array([1.0, 2.0]))
                >>> n_axes = len(fig.axes)
                >>> fig2, ax2, im = mg.plot_vector_field(
                ...     np.array([0.3, -0.2]), np.array([0.1, 0.4]), compose=True
                ... )
                >>> ax2 is ax and len(fig2.axes) == n_axes
                True

                ```
            - Node-located components as wind barbs:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> fig, ax, im = mg.plot_vector_field(
                ...     np.full(4, 5.0), np.zeros(4), kind="barbs", location="node"
                ... )
                >>> float(im.get_array().max())
                5.0

                ```
            - A grouped colour scale applies a non-linear magnitude norm:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> from cleopatra.styling.scaling import ColorScaling
                >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
                >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
                >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
                >>> mg = MeshGlyph(node_x, node_y, faces)
                >>> fig, ax, im = mg.plot_vector_field(
                ...     np.array([0.3, -0.2]),
                ...     np.array([0.1, 0.4]),
                ...     color=ColorScaling.power(gamma=0.5),
                ... )
                >>> im.norm.gamma
                0.5

                ```
            - `streamplot` is refused with an actionable message:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5]),
                ...     np.array([0.0, 0.0, 1.0]),
                ...     np.array([[0, 1, 2]]),
                ... )
                >>> mg.plot_vector_field(np.array([1.0]), np.array([1.0]),
                ...                      kind="streamplot")
                Traceback (most recent call last):
                    ...
                ValueError: kind='streamplot' is not supported on an unstructured mesh: ...

                ```

        See Also:
            cleopatra.glyphs.gridded.vector_glyph.VectorGlyph: The delegate
                that renders the arrows/barbs and owns the `thin`/colorbar
                machinery; use it directly for gridded fields (including
                `streamplot`).
            face_centroids: The anchors used for face-located components.
            plot: The scalar mesh render a field is typically composed over.
        """
        u, v, thin_value = self._validate_vector_field(
            kind, location, u, v, thin, kwargs
        )

        if location == "face":
            centroids = self.face_centroids
            anchor_x, anchor_y = centroids[:, 0], centroids[:, 1]
        else:
            anchor_x, anchor_y = self._node_x, self._node_y

        target_ax = self._resolve_vector_target_ax(ax)

        # The delegate is constructed before the previous-arrows clear: the
        # constructor is its last validation surface (e.g. the grouped-kwarg
        # redirects), and it must reject while the previous arrows are still
        # intact. The clear itself runs BEFORE the new render so the old
        # overlay colorbar gives its layout space back before the new one
        # takes its own.
        delegate = VectorGlyph(anchor_x, anchor_y, u, v, thin=thin_value, **kwargs)
        if compose:
            self._clear_previous_vector_field()
        pre_bounds = (
            target_ax.get_position().frozen() if target_ax is not None else None
        )
        fig, ax_out, im = delegate.plot(
            kind=kind,
            ax=target_ax,
            title=title,
            colorbar=colorbar,
            color=color,
            contour=contour,
            classify=classify,
            compose=compose,
        )
        self._finish_vector_render(delegate, fig, ax_out, compose, pre_bounds)
        return fig, ax_out, im

    def _build_edge_segments(self) -> np.ndarray:
        """Build line segments for wireframe rendering.

        Uses edge_node_connectivity if available, otherwise derives the
        unique polygon edges from face_node_connectivity by walking each
        face boundary (with wrap-around) and deduplicating undirected
        edges via a sort. Both paths are fully vectorized.

        Returns:
            np.ndarray: Array of shape (n_segments, 2, 2) where each
                segment is `[[x1, y1], [x2, y2]]`. Returns an empty
                array with shape (0, 2, 2) if no edges can be derived.

        Examples:
            - A single triangle yields its three boundary segments, and the
                first segment connects the two lowest-indexed nodes:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5]),
                ...     np.array([0.0, 0.0, 1.0]),
                ...     np.array([[0, 1, 2]]),
                ... )
                >>> segs = mg._build_edge_segments()
                >>> segs.shape
                (3, 2, 2)
                >>> segs[0]
                array([[0., 0.],
                       [1., 0.]])

                ```
            - An edge shared by two faces is emitted only once, so two
                triangles sharing one edge produce five segments, not six:
                ```python
                >>> import numpy as np
                >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
                >>> mg = MeshGlyph(
                ...     np.array([0.0, 1.0, 0.5, 1.5]),
                ...     np.array([0.0, 0.0, 1.0, 1.0]),
                ...     np.array([[0, 1, 2], [1, 3, 2]]),
                ... )
                >>> mg._build_edge_segments().shape
                (5, 2, 2)

                ```
        """
        if self._edge_nodes is not None:
            n1 = self._edge_nodes[:, 0]
            n2 = self._edge_nodes[:, 1]
            starts = np.column_stack([self._node_x[n1], self._node_y[n1]])
            ends = np.column_stack([self._node_x[n2], self._node_y[n2]])
            return np.stack([starts, ends], axis=1)

        counts = self.nodes_per_face
        flat_nodes = self._face_nodes[self._face_nodes != self._fill_value]
        if flat_nodes.size == 0:
            return np.empty((0, 2, 2), dtype=np.float64)

        face_start = np.cumsum(counts) - counts
        next_pos = np.arange(flat_nodes.size, dtype=np.intp) + 1
        nonempty = counts >= 1
        last_pos = face_start[nonempty] + counts[nonempty] - 1
        next_pos[last_pos] = face_start[nonempty]

        a = flat_nodes
        b = flat_nodes[next_pos]
        n_nodes = np.int64(self.n_nodes)
        lo = np.minimum(a, b).astype(np.int64)
        hi = np.maximum(a, b).astype(np.int64)
        sorted_keys = np.sort(lo * n_nodes + hi)
        keys = sorted_keys[
            np.concatenate(([True], sorted_keys[1:] != sorted_keys[:-1]))
        ]
        n1, n2 = keys // n_nodes, keys % n_nodes
        starts = np.column_stack([self._node_x[n1], self._node_y[n1]])
        ends = np.column_stack([self._node_x[n2], self._node_y[n2]])
        return np.stack([starts, ends], axis=1)

face_centroids property

Face centroids: the mean of each face's valid node coordinates.

The centroid is the arithmetic mean of the face's valid (non-fill) vertices -- the vertex centroid, not the area centroid. For the convex, well-shaped cells of a typical UGRID mesh the two are close, and the vertex centroid is what plot_vector_field anchors face-located arrows at. A face with no valid nodes yields a NaN row.

Returns:

Type	Description
ndarray	np.ndarray: (n_faces, 2) float array of (x, y) centroids, in face order.

Examples:

• The centroid of a triangle is the mean of its three vertices:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5]),
  ...     np.array([0.0, 0.0, 1.0]),
  ...     np.array([[0, 1, 2]]),
  ... )
  >>> mg.face_centroids
  array([[0.5       , 0.33333333]])
  

• A mixed mesh averages only each face's valid nodes:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 2.0, 0.0, 1.0, 2.0]),
  ...     np.array([0.0, 0.0, 0.0, 1.0, 1.0, 1.0]),
  ...     np.array([[0, 1, 4, 3], [1, 2, 5, -1]]),
  ...     fill_value=-1,
  ... )
  >>> mg.face_centroids
  array([[0.5       , 0.5       ],
         [1.66666667, 0.33333333]])
  

See Also

plot_vector_field: Anchors face-located (u, v) arrows at these centroids. nodes_per_face: The per-face valid-node counts the mean divides by.

n_edges property

Number of edges (0 if edge connectivity not provided).

Edges are only counted when explicit edge_node_connectivity was supplied at construction; otherwise this is 0 even though the mesh has implicit polygon edges (which plot_outline derives on demand).

Returns:

Name	Type	Description
int	int	Number of rows in edge_node_connectivity, or 0 when no edge connectivity was given.

Examples:

• Without explicit edges the count is 0:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5]),
  ...     np.array([0.0, 0.0, 1.0]),
  ...     np.array([[0, 1, 2]]),
  ... )
  >>> mg.n_edges
  0
  

• Supplying edge_node_connectivity makes the count match the number of edge rows:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 1.0, 0.0]),
  ...     np.array([0.0, 0.0, 1.0, 1.0]),
  ...     np.array([[0, 1, 2, 3]]),
  ...     edge_node_connectivity=np.array(
  ...         [[0, 1], [1, 2], [2, 3], [3, 0]]
  ...     ),
  ... )
  >>> mg.n_edges
  4
  

n_faces property

Number of faces in the mesh.

Returns:

Name	Type	Description
int	int	Count of faces (rows of the face-node connectivity), regardless of how many nodes each face has.

Examples:

• A two-face mesh reports two faces, one row per face:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5, 1.5]),
  ...     np.array([0.0, 0.0, 1.0, 1.0]),
  ...     np.array([[0, 1, 2], [1, 3, 2]]),
  ... )
  >>> mg.n_faces
  2
  

n_nodes property

Number of nodes in the mesh.

Returns:

Name	Type	Description
int	int	Count of nodes, i.e. the length of the coordinate arrays node_x/node_y.

Examples:

• The node count matches the coordinate array length:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5, 1.5]),
  ...     np.array([0.0, 0.0, 1.0, 1.0]),
  ...     np.array([[0, 1, 2], [1, 3, 2]]),
  ... )
  >>> mg.n_nodes
  4
  

node_x property

Node x-coordinates.

Returns:

Type	Description
ndarray	np.ndarray: 1D float array of node x-coordinates, in node order (length n_nodes).

Examples:

• Read back the x-coordinates and pick out a single node:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5]),
  ...     np.array([0.0, 0.0, 1.0]),
  ...     np.array([[0, 1, 2]]),
  ... )
  >>> mg.node_x
  array([0. , 1. , 0.5])
  >>> float(mg.node_x[1])
  1.0
  

node_y property

Node y-coordinates.

Returns:

Type	Description
ndarray	np.ndarray: 1D float array of node y-coordinates, in node order (length n_nodes).

Examples:

• Read back the y-coordinates and take their maximum:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5]),
  ...     np.array([0.0, 0.0, 1.0]),
  ...     np.array([[0, 1, 2]]),
  ... )
  >>> mg.node_y
  array([0., 0., 1.])
  >>> float(mg.node_y.max())
  1.0
  

nodes_per_face property

Number of valid nodes per face (excluding fill values).

Returns:

Type	Description
ndarray	np.ndarray: 1D integer array of length n_faces.

Examples:

• Pure triangular mesh returns all 3s:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5, 1.5]),
  ...     np.array([0.0, 0.0, 1.0, 1.0]),
  ...     np.array([[0, 1, 2], [1, 3, 2]]),
  ... )
  >>> mg.nodes_per_face
  array([3, 3])
  

• Mixed mesh with quads and triangles:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 2.0, 0.0, 1.0, 2.0]),
  ...     np.array([0.0, 0.0, 0.0, 1.0, 1.0, 1.0]),
  ...     np.array([[0, 1, 4, 3], [1, 2, 5, -1]]),
  ...     fill_value=-1,
  ... )
  >>> mg.nodes_per_face
  array([4, 3])
  

style property

Name of the DATA_STYLES preset currently applied, or None.

Reads back the preset set via the style constructor kwarg, a plot(style=...) call, or apply_style.

triangulation property

Matplotlib Triangulation built via fan decomposition.

Each face with N valid nodes is decomposed into (N-2) triangles by fanning from the first vertex. Faces with fewer than 3 valid nodes are skipped.

Returns:

Type	Description
Triangulation	matplotlib.tri.Triangulation: Triangulation ready for tripcolor/tricontourf.

Raises:

Type	Description
ValueError	If no faces have 3 or more valid nodes.

Examples:

• Build a triangulation and check its shape:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5]),
  ...     np.array([0.0, 0.0, 1.0]),
  ...     np.array([[0, 1, 2]]),
  ... )
  >>> tri = mg.triangulation
  >>> tri.triangles.shape
  (1, 3)
  

__init__(node_x, node_y, face_node_connectivity, fill_value=-1, edge_node_connectivity=None, fig=None, ax=None, **kwargs)

Build a mesh glyph from a node/face topology.

Parameters:

Name	Type	Description	Default
node_x	ndarray	1-D node x (or longitude) coordinates.	required
node_y	ndarray	1-D node y (or latitude) coordinates, paired with node_x.	required
face_node_connectivity	ndarray	(n_faces, max_nodes) node indices per face, padded with fill_value for faces with fewer nodes.	required
fill_value	int	Padding value in face_node_connectivity. Default -1.	-1
edge_node_connectivity	ndarray | None	Optional (n_edges, 2) node indices per edge, used by the wireframe render. Default None.	None
fig		Pre-existing figure to bind. Default None. Passing fig alone (no ax) draws into that figure — its first axes, or a fresh one if it has none.	None
ax		Pre-existing axes to bind. Default None.	None
data_style		Grouped style / hillshade options applied at construction, e.g. data_style=DataStyle(hillshade=True). These are rejected as loose keywords, so the group is how they are set here rather than on every plot() call; the value is sticky across later calls (plot() restores it whenever the call itself does not set one). Default None.	required
**kwargs		Override any key in MESH_DEFAULT_OPTIONS.	{}

Raises:

Type	Description
ValueError	If the topology arrays are inconsistent, or if a keyword argument is not a MESH_DEFAULT_OPTIONS key.

Source code in src/cleopatra/glyphs/gridded/mesh_glyph.py

def __init__(
    self,
    node_x: np.ndarray,
    node_y: np.ndarray,
    face_node_connectivity: np.ndarray,
    fill_value: int = -1,
    edge_node_connectivity: np.ndarray | None = None,
    fig=None,
    ax=None,
    **kwargs,
):
    """Build a mesh glyph from a node/face topology.

    Args:
        node_x: 1-D node x (or longitude) coordinates.
        node_y: 1-D node y (or latitude) coordinates, paired with `node_x`.
        face_node_connectivity: `(n_faces, max_nodes)` node indices per
            face, padded with `fill_value` for faces with fewer nodes.
        fill_value: Padding value in `face_node_connectivity`. Default -1.
        edge_node_connectivity: Optional `(n_edges, 2)` node indices per
            edge, used by the wireframe render. Default None.
        fig: Pre-existing figure to bind. Default None. Passing `fig`
            alone (no `ax`) draws into that figure — its first axes, or
            a fresh one if it has none.
        ax: Pre-existing axes to bind. Default None.
        data_style: Grouped `style` / `hillshade` options applied at
            construction, e.g. `data_style=DataStyle(hillshade=True)`.
            These are rejected as loose keywords, so the group is how they
            are set here rather than on every `plot()` call; the value is
            sticky across later calls (`plot()` restores it whenever the
            call itself does not set one). Default None.
        **kwargs: Override any key in `MESH_DEFAULT_OPTIONS`.

    Raises:
        ValueError: If the topology arrays are inconsistent, or if a
            keyword argument is not a `MESH_DEFAULT_OPTIONS` key.
    """
    super().__init__(default_options=MESH_DEFAULT_OPTIONS, fig=fig, ax=ax, **kwargs)
    self._node_x = np.asarray(node_x, dtype=np.float64)
    self._node_y = np.asarray(node_y, dtype=np.float64)
    self._face_nodes = np.asarray(face_node_connectivity, dtype=np.intp)
    self._fill_value = fill_value
    self._edge_nodes = (
        np.asarray(edge_node_connectivity, dtype=np.intp)
        if edge_node_connectivity is not None
        else None
    )

    if self._node_x.ndim != 1:
        raise ValueError(f"node_x must be 1D, got {self._node_x.ndim}D.")
    if self._node_x.shape != self._node_y.shape:
        raise ValueError(
            f"node_x and node_y must have the same shape, "
            f"got {self._node_x.shape} and {self._node_y.shape}."
        )
    if self._face_nodes.ndim != 2:
        raise ValueError(
            f"face_node_connectivity must be 2D, got {self._face_nodes.ndim}D."
        )
    valid_indices = self._face_nodes[self._face_nodes != self._fill_value]
    if len(valid_indices) > 0:
        if valid_indices.min() < 0 or valid_indices.max() >= self.n_nodes:
            raise ValueError(
                f"face_node_connectivity indices must be in "
                f"[0, {self.n_nodes}), got range "
                f"[{valid_indices.min()}, {valid_indices.max()}]."
            )
    if self._edge_nodes is not None:
        if self._edge_nodes.ndim != 2 or self._edge_nodes.shape[1] != 2:
            raise ValueError(
                f"edge_node_connectivity must have shape (n_edges, 2), "
                f"got {self._edge_nodes.shape}."
            )

    self._cached_triangulation: mtri.Triangulation | None = None
    self._cached_tri_array: np.ndarray | None = None
    self._cached_nodes_per_face: np.ndarray | None = None
    self._cached_face_centroids: np.ndarray | None = None
    #: Delegate `VectorGlyph` from the most recent `plot_vector_field`
    #: call; `None` before the first. Each call builds a fresh delegate
    #: (which owns its own arrow artists), so this reference is what lets
    #: a composed re-render clear the previous call's arrows instead of
    #: stacking a second field on top.
    self._vector_field_glyph: VectorGlyph | None = None
    self._cbar: Colorbar | None = None
    #: Colour-mapped artist from the most recent `plot` call (the
    #: `tripcolor`/`tricontour(f)` mappable); `None` before first render.
    self.im: Any = None
    #: Per-frame time-label `Text` artist from the most recent
    #: `animate` call, if any; `None` before any `animate` call.
    self._day_text = None
    #: Inline contour-label `Text` artists from the most recent
    #: `plot(location="node", filled=False, labels=True)`, or `None`
    #: when labelling was not requested (the default, and for
    #: `tripcolor`/`tricontourf`); an empty list when the line
    #: tricontour has no isolines.
    self.contour_labels = None
    #: `hillshade` set at construction. `plot()` resets `default_options`
    #: to the class defaults on each call, so this is restored there when
    #: `hillshade` is not overridden at `plot()` time -- keeping the option
    #: honoured at construction, consistent with `ArrayGlyph`/`KDEGlyph`.
    self._construct_hillshade = self.default_options.get("hillshade", False)
    #: The sticky `style` preset. `plot()` resets `default_options` each
    #: call, so this tracks the current preset (updated whenever `plot()` /
    #: `apply_style` passes `style`, including `None` to clear) and is
    #: restored after the reset -- so a style survives a later plain
    #: `plot(data)` (sticky + clearable, like `ArrayGlyph`).
    self._style_state = self.default_options.get("style")
    #: `(host_axes, pre-steal bounds)` captured when the most recent
    #: composed `plot_vector_field` drew its own colorbar, else `None`.
    #: On a multi-axes figure `create_color_bar` takes matplotlib's
    #: `make_axes` path, whose `Colorbar.remove()` never hands the stolen
    #: layout space back -- so when a composed re-render clears the
    #: previous overlay bar, the host is restored from this record or
    #: repeated re-renders would shrink it monotonically.
    self._vector_host_bounds: tuple[Any, Any] | None = None
    #: Sticky `projection` preset (like `_style_state`): restored after the
    #: `plot()` options reset so a constructor-time `projection=` survives a
    #: later plain `plot(data)`.
    self._projection_state = self.default_options.get("projection")
    #: Last `(data, location)` rendered, so `apply_style` can restyle in
    #: place without the caller re-supplying the mesh data.
    self._last_data: np.ndarray | None = None
    self._last_location = "face"

animate(data, time, location='face', edgecolor='none', interval=200, text_loc=None, colorbar=None, color=None, contour=None, data_style=None, compose=False, **kwargs)

Create an animation from time-varying mesh data.

Iterates over the first dimension of data (or elements of a list), rendering each frame on the fixed mesh topology.

Parameters:

Name	Type	Description	Default
data	ndarray | list[ndarray]	Sequence of data arrays. If a 2D ndarray of shape (n_frames, n_elements), each row is one frame. If a list, each element is a 1D array for one frame.	required
time	list[Any]	Labels for each frame (timestamps, strings, etc.). Length must match the number of frames.	required
location	str	"face" or "node". Default is "face".	'face'
edgecolor	str	Edge color for face rendering. Default is "none".	'none'
interval	int	Milliseconds between frames. Default is 200.	200
text_loc	list | None	[x, y] position for the time label text. Default is [0.1, 0.2].	None
colorbar	bool | ColorBar | None	Draw a colorbar. None (default) draws one for a normal render but suppresses it under compose=True (an overlay's colorbar would re-lay-out the host axes); True or a typed ColorBar spec (placement / caption / sizing) always draws one, even composing; False suppresses it.	None
compose	bool	Draw over whatever is already on the axes instead of replacing it, by default False. True clears only this glyph's own prior artists, so the animation layers onto existing content; explicit framing (title=, xlabel=, …) is still applied while the host's existing framing is left intact, and tight_layout is skipped so the host layout is preserved (see plot).	False
**kwargs	Any	Override any key in default_options (cmap, vmin, vmax, color_scale, gamma, midpoint, figsize, title, etc.). The loose ticks_spacing / cbar_* keys still work, but prefer colorbar=ColorBar(...). As in plot, the call rebuilds default_options from MESH_DEFAULT_OPTIONS first, so an option passed here applies to this animation only -- except the axis-styling keys (xlabel, ylabel, their font sizes, the tick label sizes and grid_alpha), whose construction-time values are carried back across the reset unless this call passes the same key.	{}

Returns:

Name	Type	Description
FuncAnimation	FuncAnimation	The animation object. Use save_animation() to export.

Raises:

Type	Description
ValueError	If data frames don't match mesh topology or time length doesn't match frame count.

Notes

An animation draws no inline contour labels, so this clears contour_labels back to None; any label artists left by a previous plot(filled=False, labels=True) call do not leak into the animation state.

Examples:

• Animate face data over 3 time steps:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> frames = np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
  >>> anim = mg.animate(frames, time=["t0", "t1", "t2"])
  

Source code in src/cleopatra/glyphs/gridded/mesh_glyph.py

def animate(
    self,
    data: np.ndarray | list[np.ndarray],
    time: list[Any],
    location: str = "face",
    edgecolor: str = "none",
    interval: int = 200,
    text_loc: list | None = None,
    colorbar: bool | ColorBar | None = None,
    color: ColorScaling | None = None,
    contour: Contour | None = None,
    data_style: DataStyle | None = None,
    compose: bool = False,
    **kwargs: Any,
) -> FuncAnimation:
    """Create an animation from time-varying mesh data.

    Iterates over the first dimension of `data` (or elements of a
    list), rendering each frame on the fixed mesh topology.

    Args:
        data: Sequence of data arrays. If a 2D ndarray of shape
            `(n_frames, n_elements)`, each row is one frame.
            If a list, each element is a 1D array for one frame.
        time: Labels for each frame (timestamps, strings, etc.).
            Length must match the number of frames.
        location: `"face"` or `"node"`. Default is `"face"`.
        edgecolor: Edge color for face rendering. Default is
            `"none"`.
        interval: Milliseconds between frames. Default is 200.
        text_loc: `[x, y]` position for the time label text.
            Default is `[0.1, 0.2]`.
        colorbar: Draw a colorbar. `None` (default) draws one for a normal
            render but suppresses it under `compose=True` (an overlay's
            colorbar would re-lay-out the host axes); `True` or a typed
            `ColorBar` spec (placement / caption / sizing) always draws one,
            even composing; `False` suppresses it.
        compose: Draw *over* whatever is already on the axes instead of
            replacing it, by default `False`. `True` clears only this glyph's
            own prior artists, so the animation layers onto existing content;
            explicit framing (`title=`, `xlabel=`, …) is still applied while
            the host's existing framing is left intact, and `tight_layout` is
            skipped so the host layout is preserved (see `plot`).
        **kwargs: Override any key in `default_options` (cmap,
            vmin, vmax, color_scale, gamma, midpoint, figsize,
            title, etc.). The loose `ticks_spacing` / `cbar_*` keys
            still work, but prefer `colorbar=ColorBar(...)`.
            As in `plot`, the call rebuilds `default_options` from
            `MESH_DEFAULT_OPTIONS` first, so an option passed here applies
            to this animation only -- except the axis-styling keys
            (`xlabel`, `ylabel`, their font sizes, the tick label sizes and
            `grid_alpha`), whose construction-time values are carried back
            across the reset unless this call passes the same key.

    Returns:
        FuncAnimation: The animation object. Use
            `save_animation()` to export.

    Raises:
        ValueError: If `data` frames don't match mesh topology
            or `time` length doesn't match frame count.

    Notes:
        An animation draws no inline contour labels, so this clears
        `contour_labels` back to `None`; any label artists left by a
        previous `plot(filled=False, labels=True)` call do not leak
        into the animation state.

    Examples:
        - Animate face data over 3 time steps:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> frames = np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
            >>> anim = mg.animate(frames, time=["t0", "t1", "t2"])

            ```
    """
    if text_loc is None:
        text_loc = [0.1, 0.2]

    if isinstance(data, np.ndarray) and data.ndim == 2:
        frames = [data[i] for i in range(data.shape[0])]
    else:
        frames = list(data)

    n_frames = len(frames)
    if len(time) != n_frames:
        raise ValueError(
            f"time length ({len(time)}) does not match frame count ({n_frames})."
        )
    expected = self.n_faces if location == "face" else self.n_nodes
    for i, frame in enumerate(frames):
        if len(frame) != expected:
            raise ValueError(
                f"Frame {i}: data length ({len(frame)}) does not "
                f"match n_{location}s ({expected})."
            )

    self._default_options = MESH_DEFAULT_OPTIONS.copy()
    self._merge_kwargs(kwargs)
    self._restore_construction_axis_style(kwargs)
    self._merge_group_params(color, contour, data_style)
    resolved_colorbar = (
        _resolve_colorbar(colorbar) if isinstance(colorbar, ColorBar) else {}
    )
    self.default_options.update(resolved_colorbar)

    if "vmin" not in kwargs:
        global_min = min(float(np.nanmin(f)) for f in frames)
        self.default_options["vmin"] = global_min
    if "vmax" not in kwargs:
        global_max = max(float(np.nanmax(f)) for f in frames)
        self.default_options["vmax"] = global_max
    self._vmin = self.default_options["vmin"]
    self._vmax = self.default_options["vmax"]

    if "ticks_spacing" not in kwargs and "ticks_spacing" not in resolved_colorbar:
        spacing = (self._vmax - self._vmin) / 10
        self.default_options["ticks_spacing"] = max(spacing, 1e-10)
    self.ticks_spacing = self.default_options["ticks_spacing"]

    if self.fig is None:
        self.fig, self.ax = self.create_figure_axes()
    elif self.ax is None:
        # A figure was bound without an axes: draw into the caller's figure.
        self.ax = self.fig.axes[0] if self.fig.axes else self.fig.add_subplot(111)
    fig, ax = self.fig, self.ax

    ticks = self.get_ticks()
    norm, cbar_kw = self._create_norm_and_cbar_kw(ticks)

    self.contour_labels = None

    _clear_prior_render_artists(ax, self, compose=compose)
    self.im = None
    self._cbar = None

    tpc = self._render_mesh(
        ax,
        frames[0],
        location,
        edgecolor=edgecolor,
        norm=norm,
    )
    self.im = tpc
    # See plot: a composed overlay's colorbar re-lays out the host, so
    # composing defaults it off; an explicit request still draws one.
    if colorbar is False:
        draw_colorbar = False
    elif compose:
        draw_colorbar = colorbar is not None
    else:
        draw_colorbar = True
    if draw_colorbar:
        self._cbar = self.create_color_bar(ax, tpc, cbar_kw)

    # See plot: an explicit title/axis-style is honoured even when composing;
    # a bare overlay leaves the host framing intact (default title is None,
    # _apply_axis_style applies only explicitly-passed options).
    if self.default_options["title"]:
        ax.set_title(
            self.default_options["title"],
            fontsize=self.default_options["title_size"],
        )
    self._apply_axis_style(ax)
    ax.set_aspect("equal")

    day_text = ax.text(
        text_loc[0],
        text_loc[1],
        " ",
        fontsize=self.default_options["cbar_label_size"],
        transform=ax.transAxes,
    )
    self._day_text = day_text

    current_mappable = [tpc]
    _mark_render_artists(ax, self, self._cbar, self.im, self._day_text)

    def _update(i):
        """Update the plot for frame i."""
        prev = current_mappable[0]
        if hasattr(prev, "collections"):
            for coll in prev.collections:
                coll.remove()
        elif hasattr(prev, "remove"):
            prev.remove()
        current_mappable[0] = self._render_mesh(
            ax,
            frames[i],
            location,
            edgecolor=edgecolor,
            norm=norm,
        )
        day_text.set_text(str(time[i]))
        self.im = current_mappable[0]
        _mark_render_artists(ax, self, self._cbar, self.im, self._day_text)

    if not compose:
        plt.tight_layout()
    anim = FuncAnimation(
        fig,
        _update,
        frames=n_frames,
        interval=interval,
        blit=False,
    )
    self._anim = anim
    return anim

apply_style(style, data=None, **kwargs)

Apply a DATA_STYLES preset by name, re-rendering the mesh in place.

A discoverable wrapper over plot(style=...) for restyling an already-built glyph. It redraws in place on the glyph's own axes (taking full ownership -- do not use on a shared axes), or on a fresh figure if the glyph was never plotted or its figure was closed. It reuses the last-plotted mesh data (and location) so the caller need not re-supply it; pass data= when the glyph has not been plotted yet. The applied style is sticky (survives a later plain plot(data)); plot(data, style=None) clears it. Extra keyword arguments (e.g. location, hillshade, edgecolor) are forwarded to plot.

Parameters:

Name	Type	Description	Default
style	str	A cleopatra.styling.colors.DATA_STYLES preset name.	required
data	ndarray | None	Mesh data to render; defaults to the last-plotted data.	None
**kwargs	Any	Forwarded to plot (e.g. location, hillshade).	{}

Returns:

Type	Description
tuple[Figure, Axes]	tuple[Figure, Axes]: The figure and axes drawn on.

Raises:

Type	Description
ValueError	If style is unknown (raised by plot), or no data is available (never plotted and none passed).

Source code in src/cleopatra/glyphs/gridded/mesh_glyph.py

def apply_style(
    self, style: str, data: np.ndarray | None = None, **kwargs: Any
) -> tuple[plt.Figure, plt.Axes]:
    """Apply a `DATA_STYLES` preset by name, re-rendering the mesh in place.

    A discoverable wrapper over `plot(style=...)` for restyling an
    already-built glyph. It redraws **in place** on the glyph's own axes
    (taking full ownership -- do not use on a shared axes), or on a fresh
    figure if the glyph was never plotted or its figure was closed. It
    reuses the last-plotted mesh data (and location) so the caller need not
    re-supply it; pass `data=` when the glyph has not been plotted yet. The
    applied style is **sticky** (survives a later plain `plot(data)`);
    `plot(data, style=None)` clears it. Extra keyword arguments (e.g.
    `location`, `hillshade`, `edgecolor`) are forwarded to `plot`.

    Args:
        style: A `cleopatra.styling.colors.DATA_STYLES` preset name.
        data: Mesh data to render; defaults to the last-plotted data.
        **kwargs: Forwarded to `plot` (e.g. `location`, `hillshade`).

    Returns:
        tuple[Figure, Axes]: The figure and axes drawn on.

    Raises:
        ValueError: If `style` is unknown (raised by `plot`), or no data is
            available (never plotted and none passed).
    """
    resolve_single_layer_style(style)
    if data is None:
        data = self._last_data
        if data is None:
            raise ValueError(
                "apply_style needs mesh data: call plot(data, ...) first, "
                "or pass data= explicitly."
            )
    location = kwargs.pop("location", self._last_location)
    self._reset_axes_for_restyle()
    # Fold style (and an optional forwarded hillshade) into the grouped
    # data_style object; leaving hillshade unset keeps any sticky value.
    if "hillshade" in kwargs:
        data_style = DataStyle.for_apply_style(
            style, hillshade=kwargs.pop("hillshade")
        )
    else:
        data_style = DataStyle.for_apply_style(style)
    return self.plot(
        data, location=location, ax=self.ax, data_style=data_style, **kwargs
    )

plot(data, location='face', ax=None, edgecolor='none', colorbar=None, title=None, filled=True, color=None, contour=None, data_style=None, compose=False, **kwargs)

Plot mesh data using matplotlib triangulation.

For face-centered data, uses tripcolor where each triangle is colored by the value of its parent face. For node-centered data, uses tricontourf for smooth interpolated filled contours, or tricontour for line contours when filled=False.

Supports all 6 color scale types from default_options: linear, power, sym-lognorm, lognorm, boundary-norm, and midpoint.

Parameters:

Name	Type	Description	Default
data	ndarray	1D data array. Length must match face count (location="face") or node count (location="node").	required
location	str	Mesh element location: "face" or "node". Default is "face".	'face'
ax	Any	Axes to plot on. If None, resolution priority is the axes bound at construction > an axes derived from a figure bound at construction (its first axes, or a fresh one) > a new figure/axes.	None
edgecolor	str	Edge color for face rendering. Default is "none".	'none'
colorbar	bool | ColorBar | None	Draw a colorbar. None (default) draws one for a normal render but suppresses it under compose=True (an overlay's colorbar would re-lay-out the host axes); True or a typed ColorBar spec (placement / caption / sizing) always draws one, even composing; False suppresses it.	None
title	str | None	Plot title. Overrides default_options["title"].	None
filled	bool	For node data, draw filled contours (tricontourf, the default) or line contours (tricontour) when False. Ignored for face data. Default is True.	True
color	ColorScaling | None	Colour-scale group object (cleopatra.styling.scaling.ColorScaling), e.g. ColorScaling.power(gamma=0.7). Replaces the loose color_scale / gamma / line_threshold / line_scale / bounds / midpoint keywords.	None
contour	Contour | None	Discretisation / inline-label group object (cleopatra.styling.params.Contour). Contour(levels=N) discretises the colour norm and sets the node line/filled contour count (default 20 when unset); Contour(labels=True, label_kw=...) draws inline numeric labels via ax.clabel on a line tricontour (location="node", filled=False) and stores the Text artists on self.contour_labels -- a no-op for tripcolor (face data) and tricontourf. Replaces the loose levels / labels / label_kw keywords.	None
data_style	DataStyle | None	Named-preset / relief-shading group object (cleopatra.styling.params.DataStyle), e.g. DataStyle(style="dem", hillshade=True). Replaces the loose style / hillshade keywords.	None
compose	bool	Draw over whatever is already on ax instead of replacing it, by default False. False clears every glyph's prior artists from the axes first (the replace-don't-orphan default); True clears only this glyph's own prior artists, so a mesh can be layered onto a host raster / another glyph -- the same opt-in ArrayGlyph and VectorGlyph expose. A composed overlay still applies any framing you pass explicitly (title=, xlabel=, …) and its own aspect, but leaves the host's existing title / ticks / labels and colorbar untouched when you pass none.	False
**kwargs	Any	Construction-time-style overrides for the non-grouped default_options (cmap, vmin, vmax, title_size, figsize, …). The loose ticks_spacing / cbar_* keys still work, but prefer colorbar=ColorBar(...). The colour-scale, discretisation/label, and preset/relief options moved onto the color= / contour= / data_style= group objects above; passing any of them as a loose keyword now raises. Every call rebuilds default_options from MESH_DEFAULT_OPTIONS, so an option passed here applies to this render only and does not leak into the next one. The axis-styling keys (xlabel, ylabel, their font sizes, the tick label sizes and grid_alpha) are the exception: those given to the constructor are carried back across the reset, so MeshGlyph(..., xlabel="x") keeps labelling every render. A key passed here wins over the constructor's for this call. One relief option is honoured only for node data (location="node"): hillshade (bool | dict, default False): render the mesh as a relief-shaded terrain surface. Each triangle is coloured by its mean node elevation and blended with a triangle-normal hillshade. The colorbar spans the node elevation range, so — because faces use per-triangle means — its extreme colours may not appear on the surface; the bar reflects the input data range, not the drawn per-face colours. Faces touching a non-finite (nodata) node render transparent. Passing hillshade with location="face" raises ValueError. A data-style preset option: style (str, default None): name of a cleopatra.styling.colors.DATA_STYLES preset (valid names: sorted(cleopatra.styling.colors.DATA_STYLES)). A continuous preset overrides the cmap + norm (and composes with hillshade); a categorical preset builds a discrete colormap, masks out-of-range codes transparent, and draws a legend instead of the colorbar. Takes precedence over cmap/color_scale.	{}

Returns:

Type	Description
tuple[Figure, Axes]	tuple[Figure, Axes]: The matplotlib Figure and Axes objects. When no axes exist, a new figure is created. Call plt.close(fig) after saving to avoid memory leaks in batch processing.

Raises:

Type	Description
ValueError	If location is not "face" or "node", or if data length does not match the expected mesh dimension.

Examples:

• Plot face-centered data:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> fig, ax = mg.plot(np.array([1.0, 2.0]))
  

• Plot node-centered data:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> fig, ax = mg.plot(
  ...     np.array([0.0, 1.0, 2.0, 3.0]),
  ...     location="node",
  ... )
  

• Plot node-centered data as line contours (tricontour) instead of filled:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> fig, ax = mg.plot(
  ...     np.array([0.0, 1.0, 2.0, 3.0]),
  ...     location="node",
  ...     filled=False,
  ... )
  

• Label the line tricontours inline (labels=True); the Text artists are exposed on glyph.contour_labels:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> fig, ax = mg.plot(
  ...     np.array([0.0, 1.0, 2.0, 3.0]),
  ...     location="node",
  ...     filled=False,
  ...     contour=Contour(labels=True, label_kw={"fmt": "%.1f"}),
  ... )
  >>> isinstance(mg.contour_labels, list)
  True
  

• Plot with power color scale:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> fig, ax = mg.plot(
  ...     np.array([1.0, 2.0]),
  ...     color=ColorScaling.power(gamma=0.5),
  ...     cmap="coolwarm",
  ... )
  

Source code in src/cleopatra/glyphs/gridded/mesh_glyph.py

def plot(
    self,
    data: np.ndarray,
    location: str = "face",
    ax: Any = None,
    edgecolor: str = "none",
    colorbar: bool | ColorBar | None = None,
    title: str | None = None,
    filled: bool = True,
    color: ColorScaling | None = None,
    contour: Contour | None = None,
    data_style: DataStyle | None = None,
    compose: bool = False,
    **kwargs: Any,
) -> tuple[plt.Figure, plt.Axes]:
    """Plot mesh data using matplotlib triangulation.

    For face-centered data, uses `tripcolor` where each triangle
    is colored by the value of its parent face. For node-centered
    data, uses `tricontourf` for smooth interpolated filled
    contours, or `tricontour` for line contours when
    `filled=False`.

    Supports all 6 color scale types from `default_options`:
    linear, power, sym-lognorm, lognorm, boundary-norm, and midpoint.

    Args:
        data: 1D data array. Length must match face count
            (location="face") or node count (location="node").
        location: Mesh element location: `"face"` or `"node"`.
            Default is `"face"`.
        ax: Axes to plot on. If None, resolution priority is the axes
            bound at construction > an axes derived from a figure bound
            at construction (its first axes, or a fresh one) > a new
            figure/axes.
        edgecolor: Edge color for face rendering. Default is
            `"none"`.
        colorbar: Draw a colorbar. `None` (default) draws one for a normal
            render but suppresses it under `compose=True` (an overlay's
            colorbar would re-lay-out the host axes); `True` or a typed
            `ColorBar` spec (placement / caption / sizing) always draws one,
            even composing; `False` suppresses it.
        title: Plot title. Overrides `default_options["title"]`.
        filled: For node data, draw filled contours (`tricontourf`,
            the default) or line contours (`tricontour`) when
            `False`. Ignored for face data. Default is True.
        color: Colour-scale group object
            (`cleopatra.styling.scaling.ColorScaling`), e.g.
            `ColorScaling.power(gamma=0.7)`. Replaces the loose
            `color_scale` / `gamma` / `line_threshold` / `line_scale` /
            `bounds` / `midpoint` keywords.
        contour: Discretisation / inline-label group object
            (`cleopatra.styling.params.Contour`). `Contour(levels=N)`
            discretises the colour norm and sets the node line/filled
            contour count (default 20 when unset);
            `Contour(labels=True, label_kw=...)` draws inline numeric
            labels via `ax.clabel` on a line tricontour
            (`location="node"`, `filled=False`) and stores the `Text`
            artists on `self.contour_labels` -- a no-op for `tripcolor`
            (face data) and `tricontourf`. Replaces the loose `levels`
            / `labels` / `label_kw` keywords.
        data_style: Named-preset / relief-shading group object
            (`cleopatra.styling.params.DataStyle`), e.g.
            `DataStyle(style="dem", hillshade=True)`. Replaces the
            loose `style` / `hillshade` keywords.
        compose: Draw *over* whatever is already on `ax` instead of
            replacing it, by default `False`. `False` clears every glyph's
            prior artists from the axes first (the replace-don't-orphan
            default); `True` clears only this glyph's own prior artists, so
            a mesh can be layered onto a host raster / another glyph -- the
            same opt-in `ArrayGlyph` and `VectorGlyph` expose. A composed
            overlay still applies any framing you pass explicitly
            (`title=`, `xlabel=`, …) and its own aspect, but leaves the
            host's existing title / ticks / labels and colorbar untouched
            when you pass none.
        **kwargs: Construction-time-style overrides for the non-grouped
            `default_options` (`cmap`, `vmin`, `vmax`, `title_size`,
            `figsize`, …). The loose `ticks_spacing` / `cbar_*` keys
            still work, but prefer `colorbar=ColorBar(...)`.
            The colour-scale, discretisation/label, and
            preset/relief options moved onto the `color=` / `contour=` /
            `data_style=` group objects above; passing any of them as a
            loose keyword now raises.

            Every call rebuilds `default_options` from
            `MESH_DEFAULT_OPTIONS`, so an option passed here applies to
            this render only and does not leak into the next one. The
            axis-styling keys (`xlabel`, `ylabel`, their font sizes, the
            tick label sizes and `grid_alpha`) are the exception: those
            given to the constructor are carried back across the reset, so
            `MeshGlyph(..., xlabel="x")` keeps labelling every render. A key
            passed here wins over the constructor's for this call.

            One relief option is honoured **only** for node data
            (`location="node"`):

            - `hillshade` (bool | dict, default `False`): render the
              mesh as a relief-shaded terrain surface. Each triangle is
              coloured by its *mean* node elevation and blended with a
              triangle-normal hillshade. The colorbar spans the **node**
              elevation range, so — because faces use per-triangle means
              — its extreme colours may not appear on the surface; the
              bar reflects the input data range, not the drawn per-face
              colours. Faces touching a non-finite (nodata) node render
              transparent. Passing `hillshade` with `location="face"`
              raises `ValueError`.

            A data-style preset option:

            - `style` (str, default `None`): name of a
              `cleopatra.styling.colors.DATA_STYLES` preset (valid names:
              `sorted(cleopatra.styling.colors.DATA_STYLES)`). A continuous preset
              overrides the cmap + norm (and composes with `hillshade`); a
              categorical preset builds a discrete colormap, masks
              out-of-range codes transparent, and draws a legend instead of
              the colorbar. Takes precedence over `cmap`/`color_scale`.

    Returns:
        tuple[Figure, Axes]: The matplotlib Figure and Axes objects.
            When no axes exist, a new figure is created. Call
            `plt.close(fig)` after saving to avoid memory leaks
            in batch processing.

    Raises:
        ValueError: If `location` is not `"face"` or `"node"`,
            or if `data` length does not match the expected mesh
            dimension.

    Examples:
        - Plot face-centered data:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> fig, ax = mg.plot(np.array([1.0, 2.0]))

            ```
        - Plot node-centered data:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> fig, ax = mg.plot(
            ...     np.array([0.0, 1.0, 2.0, 3.0]),
            ...     location="node",
            ... )

            ```
        - Plot node-centered data as line contours
            (`tricontour`) instead of filled:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> fig, ax = mg.plot(
            ...     np.array([0.0, 1.0, 2.0, 3.0]),
            ...     location="node",
            ...     filled=False,
            ... )

            ```
        - Label the line tricontours inline (`labels=True`); the
            `Text` artists are exposed on `glyph.contour_labels`:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> fig, ax = mg.plot(
            ...     np.array([0.0, 1.0, 2.0, 3.0]),
            ...     location="node",
            ...     filled=False,
            ...     contour=Contour(labels=True, label_kw={"fmt": "%.1f"}),
            ... )
            >>> isinstance(mg.contour_labels, list)
            True

            ```
        - Plot with power color scale:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> fig, ax = mg.plot(
            ...     np.array([1.0, 2.0]),
            ...     color=ColorScaling.power(gamma=0.5),
            ...     cmap="coolwarm",
            ... )

            ```
    """
    self._validate_location_and_data(data, location)

    if np.all(np.isnan(data)):
        raise ValueError("data is entirely NaN, cannot determine color range.")

    self._default_options = MESH_DEFAULT_OPTIONS.copy()

    render_kwargs: dict[str, Any] = {}
    option_kwargs: dict[str, Any] = {}
    for key, val in kwargs.items():
        if key in self.default_options:
            option_kwargs[key] = val
        else:
            render_kwargs[key] = val
    self._merge_kwargs(option_kwargs)
    self._restore_construction_axis_style(option_kwargs)
    self._merge_group_params(color, contour, data_style)
    resolved_colorbar = (
        _resolve_colorbar(colorbar) if isinstance(colorbar, ColorBar) else {}
    )
    self.default_options.update(resolved_colorbar)
    # A composed overlay's colorbar takes space from the host axes and
    # re-lays it out, so composing defaults the colorbar off; only an
    # explicit request (colorbar=True or a ColorBar spec) still draws one.
    # Outside compose the historical default holds: draw unless colorbar is
    # False. Same contract as ArrayGlyph / VectorGlyph, but hand-rolled
    # rather than delegated to Glyph._draws_own_colorbar: mesh never plumbs
    # colorbar= into default_options["add_colorbar"] (which that helper reads,
    # defaulting True), so delegating would draw for colorbar=False outside
    # compose. Keep this in sync with _draws_own_colorbar if the contract
    # changes.
    if colorbar is False:
        draw_colorbar = False
    elif compose:
        draw_colorbar = colorbar is not None
    else:
        draw_colorbar = True

    # `style`/`hillshade` now arrive via the `data_style` group object;
    # detect whether this call provided each so the sticky-state logic
    # (a preset persists across later plain plots) still applies.
    ds_opts = data_style.to_options() if data_style is not None else {}
    if "hillshade" not in ds_opts:
        self.default_options["hillshade"] = self._construct_hillshade
    if "style" in ds_opts:
        new_style = self.default_options["style"]
        if new_style is not None:
            try:
                resolve_single_layer_style(new_style)
            except ValueError:
                self.default_options["style"] = self._style_state
                raise
        self._style_state = new_style
    else:
        self.default_options["style"] = self._style_state
    if "projection" in option_kwargs:
        self._projection_state = self.default_options["projection"]
    else:
        self.default_options["projection"] = self._projection_state

    self._last_data = (
        np.ma.copy(data) if np.ma.isMaskedArray(data) else np.array(data, copy=True)
    )
    self._last_location = location

    if "vmin" not in option_kwargs:
        self.default_options["vmin"] = float(np.nanmin(data))
    if "vmax" not in option_kwargs:
        self.default_options["vmax"] = float(np.nanmax(data))
    self._vmin = self.default_options["vmin"]
    self._vmax = self.default_options["vmax"]

    if (
        "ticks_spacing" not in option_kwargs
        and "ticks_spacing" not in resolved_colorbar
    ):
        spacing = (self._vmax - self._vmin) / 10
        self.default_options["ticks_spacing"] = max(spacing, 1e-10)
    self.ticks_spacing = self.default_options["ticks_spacing"]

    if title is not None:
        self.default_options["title"] = title

    if ax is not None:
        self.ax = ax
        self.fig = ax.get_figure()
    elif self.fig is None:
        self.fig, self.ax = self.create_figure_axes()
    elif self.ax is None:
        # A figure was bound without an axes: draw into the caller's figure
        # (its first axes, or a fresh one) rather than leaving self.ax None.
        self.ax = self.fig.axes[0] if self.fig.axes else self.fig.add_subplot(111)

    ticks = self.get_ticks()
    norm, cbar_kw = self._create_norm_and_cbar_kw(ticks)

    style = self.default_options.get("style")
    style_legend = None
    if style is not None:
        _, cfg = resolve_single_layer_style(style)
        data_f = np.asarray(data, dtype=float)
        categories = cfg.get("categories")
        if categories is not None:
            cats = sorted(categories, key=lambda c: c[0])
            cat_values = np.array([float(c[0]) for c in cats])
            cat_colors = [c[1] for c in cats]
            cat_labels = [c[2] for c in cats]
            self.default_options["cmap"] = ListedColormap(cat_colors)
            norm = BoundaryNorm(
                category_boundaries(list(cat_values)), len(cat_colors)
            )
            data = np.where(np.isin(data_f, cat_values), data_f, np.nan)
            colorbar = False
            # A categorical preset draws a discrete legend, never a
            # colorbar. `draw_colorbar` was resolved before the preset was
            # known, so clear it here too (not just `colorbar`).
            draw_colorbar = False
            self.default_options["hillshade"] = False
            style_legend = (cat_colors, cat_labels, cfg["label"])
            if location == "node":
                warnings.warn(
                    "a categorical data-style preset with location='node' "
                    "interpolates discrete class codes via tricontourf; use "
                    "location='face' for correct per-cell class colours.",
                    stacklevel=2,
                )
        else:
            self.default_options["cmap"] = cfg["cmap"]
            norm, _, _ = resolve_style_norm(data_f, cfg)
            cbar_kw.pop("ticks", None)

    self.contour_labels = None

    hillshade = resolve_hillshade(self.default_options.get("hillshade"))
    if hillshade is not None:
        if location != "node":
            raise ValueError(
                "hillshade needs node-centered elevation; pass location='node'"
            )
        _clear_prior_render_artists(self.ax, self, compose=compose)
        self.im = None
        self._cbar = None
        self._apply_projection()
        tpc = self._render_shaded_relief(
            self.ax, data, edgecolor, norm, hillshade, **render_kwargs
        )
    else:
        _clear_prior_render_artists(self.ax, self, compose=compose)
        self.im = None
        self._cbar = None
        self._apply_projection()
        tpc = self._render_mesh(
            self.ax,
            data,
            location,
            edgecolor=edgecolor,
            norm=norm,
            filled=filled,
            **render_kwargs,
        )
    self.im = tpc

    if (
        location == "node"
        and not filled
        and hillshade is None
        and self.default_options.get("labels")
    ):
        label_kw = {
            "inline": True,
            "fontsize": 8,
            "fmt": "%g",
            **(self.default_options.get("label_kw") or {}),
        }
        self.contour_labels = self.ax.clabel(tpc, **label_kw)

    if draw_colorbar:
        self._cbar = self.create_color_bar(self.ax, tpc, cbar_kw)

    if style_legend is not None:
        cat_colors, cat_labels, cat_title = style_legend
        disjoint_legend(
            self.ax, cat_colors, cat_labels, title=cat_title, loc="upper right"
        )

    # Honour an explicit title/axis-style even when composing, as ArrayGlyph
    # does: the default title is None, and _apply_axis_style applies only
    # explicitly-passed options, so a bare overlay leaves the host framing
    # untouched while an explicit title=/xlabel=/... is still applied.
    if self.default_options["title"]:
        self.ax.set_title(
            self.default_options["title"],
            fontsize=self.default_options["title_size"],
        )
    self._apply_axis_style(self.ax)
    self.ax.set_aspect("equal")

    _mark_render_artists(self.ax, self, self._cbar, self.im)
    return self.fig, self.ax

plot_outline(ax=None, color='black', linewidth=0.3, figsize=(10, 8), compose=False, **kwargs)

Plot mesh edges as a wireframe.

Uses matplotlib.collections.LineCollection for efficient rendering of thousands of edges.

Parameters:

Name	Type	Description	Default
ax	Any	Axes to plot on. If None, uses stored axes or creates new.	None
color	str	Edge color. Default is "black".	'black'
linewidth	float	Edge line width. Default is 0.3.	0.3
figsize	tuple[int, int]	Figure size in inches. Default is (10, 8).	(10, 8)
compose	bool	Draw over whatever is already on ax instead of replacing it, by default False. True clears only this glyph's own prior artists, so the wireframe overlays existing content (see plot).	False
**kwargs	Any	Additional keyword arguments passed to LineCollection.	{}

Returns:

Type	Description
tuple[Figure, Axes]	tuple[Figure, Axes]: The matplotlib Figure and Axes objects. When ax is None, a new figure is created. Call plt.close(fig) after saving to avoid memory leaks in batch processing.

Notes

An outline carries no scalar mapping, so this resets self.im to None (clearing any colour-mapped artist left by a prior plot() call).

Examples:

• Render a triangular mesh wireframe:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5]),
  ...     np.array([0.0, 0.0, 1.0]),
  ...     np.array([[0, 1, 2]]),
  ... )
  >>> fig, ax = mg.plot_outline(color="blue")
  

Source code in src/cleopatra/glyphs/gridded/mesh_glyph.py

def plot_outline(
    self,
    ax: Any = None,
    color: str = "black",
    linewidth: float = 0.3,
    figsize: tuple[int, int] = (10, 8),
    compose: bool = False,
    **kwargs: Any,
) -> tuple[plt.Figure, plt.Axes]:
    """Plot mesh edges as a wireframe.

    Uses `matplotlib.collections.LineCollection` for efficient
    rendering of thousands of edges.

    Args:
        ax: Axes to plot on. If None, uses stored axes or creates
            new.
        color: Edge color. Default is `"black"`.
        linewidth: Edge line width. Default is `0.3`.
        figsize: Figure size in inches. Default is `(10, 8)`.
        compose: Draw *over* whatever is already on `ax` instead of
            replacing it, by default `False`. `True` clears only this
            glyph's own prior artists, so the wireframe overlays existing
            content (see `plot`).
        **kwargs: Additional keyword arguments passed to
            `LineCollection`.

    Returns:
        tuple[Figure, Axes]: The matplotlib Figure and Axes objects.
            When `ax` is None, a new figure is created. Call
            `plt.close(fig)` after saving to avoid memory leaks
            in batch processing.

    Notes:
        An outline carries no scalar mapping, so this resets `self.im`
        to None (clearing any colour-mapped artist left by a prior
        `plot()` call).

    Examples:
        - Render a triangular mesh wireframe:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> mg = MeshGlyph(
            ...     np.array([0.0, 1.0, 0.5]),
            ...     np.array([0.0, 0.0, 1.0]),
            ...     np.array([[0, 1, 2]]),
            ... )
            >>> fig, ax = mg.plot_outline(color="blue")

            ```
    """
    if ax is not None:
        self.ax = ax
        self.fig = ax.get_figure()
    elif self.fig is None:
        self.fig, self.ax = plt.subplots(1, 1, figsize=figsize)

    _clear_prior_render_artists(self.ax, self, compose=compose)
    self.im = None
    self._cbar = None

    segments = self._build_edge_segments()

    lc = mcoll.LineCollection(
        list(segments), colors=color, linewidths=linewidth, **kwargs
    )
    self.ax.add_collection(lc)
    self.ax.autoscale()
    self.ax.set_aspect("equal")

    _mark_render_artists(self.ax, self, lc)

    return self.fig, self.ax

plot_vector_field(u, v, *, kind='quiver', thin=None, location='face', ax=None, title=None, colorbar=None, color=None, contour=None, classify=None, compose=False, **kwargs)

Plot a (u, v) vector field anchored on the mesh.

Face-located components (location="face") draw one arrow per face, anchored at the face's vertex centroid (face_centroids); node-located components anchor at the nodes themselves. Rendering delegates to cleopatra.glyphs.gridded.vector_glyph.VectorGlyph, so the arrows are coloured by the vector magnitude hypot(u, v) through the shared scalar-mapping pipeline, with the same colorbar behaviour.

The field is drawn in the mesh's native (flat) coordinates: a projection preset applied by plot reprojects only the mesh render, so combine a vector field with the plain mesh, not the globe. A replacing render (compose=False) after a globe plot therefore removes the globe frame and restores the flat view -- the same contract as plot with the projection cleared -- while a composed overlay leaves the host frame untouched.

Parameters:

Name	Type	Description	Default
u	ndarray	1D x-components, one per face (location="face") or per node (location="node").	required
v	ndarray	1D y-components, same length and location as u.	required
kind	str	"quiver" (arrows, the default) or "barbs". "streamplot" is refused: streamline tracing needs a regular grid, which an unstructured mesh does not have -- resample the field to a grid and use VectorGlyph directly instead.	'quiver'
thin	int | None	Draw every thin-th element so a large mesh stays legible; None (the default) draws them all. Must be a positive integer.	None
location	str	Mesh element location the components live on: "face" (the default) anchors one arrow per face at its vertex centroid (face_centroids); "node" anchors one arrow per node at the node coordinates.	'face'
ax	Any	Axes to draw on. If None, resolution priority is the axes bound at construction or by a previous render > an axes derived from a figure bound at construction > a new figure/axes created by the delegate (honouring a figsize= passed through **kwargs).	None
title	str | None	Plot title, applied by the delegate.	None
colorbar	bool | ColorBar | None	Draw the magnitude colorbar. None (default) leaves the decision to the delegate's contract: on for a standalone render, off under compose=True; True or a typed ColorBar spec (placement / caption / sizing) always draws one, even composing; False suppresses it -- the same contract as plot.	None
color	ColorScaling | None	Colour-scale group object (cleopatra.styling.scaling.ColorScaling) applied to the magnitude, e.g. ColorScaling.power(gamma=0.5) -- the same grouped parameter plot and VectorGlyph.plot take.	None
contour	Contour | None	Discretisation group object (cleopatra.styling.params.Contour); Contour(levels=N) discretises the magnitude colour norm.	None
classify	Classify | None	Classification group object (cleopatra.styling.params.Classify) for scheme-based magnitude classes, forwarded to the delegate unchanged.	None
compose	bool	Draw over whatever is already on the axes instead of replacing it, by default False. True keeps the host layers -- a filled plot render, a plot_outline wireframe, or add_tiles/add_relief backdrops -- and layers the arrows on top. The glyph tracks a single current field, so a repeated composed call replaces the previous call's arrows (and the colorbar they brought, if any -- ask for a new one with colorbar=True) even when they live on another axes. False keeps the replace-don't-orphan default every glyph render has: the axes is cleared of all glyph artists first. Either way the render applies the mesh convention of an equal axes aspect, including to a foreign host it composes onto -- the same "a composed overlay still applies its own aspect" contract plot documents.	False
**kwargs	Any	Overrides for the delegate VectorGlyph's options (cmap, vmin, vmax, scale, cbar_label, figsize, ...). An unknown key raises ValueError.	{}

Returns:

Type	Description
tuple[Figure, Axes, Any]	tuple[Figure, Axes, Any]: The figure, the axes, and the Quiver or Barbs mappable (e.g. for Axes.quiverkey). Under compose=True the mesh's own im (the scalar mappable from plot) is left untouched; a replacing render clears the mesh artists from the axes and resets im and the colorbar reference to None, as plot_outline does.

Raises:

Type

Description

ValueError

If kind is not "quiver"/"barbs" (including the explicit "streamplot" refusal), location is not "face"/"node", u/v are not 1D of equal length matching the location's element count, thin is not a positive integer, a **kwargs key is not a VectorGlyph option, density is passed (a streamplot-only option -- use thin=), or the magnitude has no finite values while vmin/vmax are not both given. A rejected call raises before anything is touched: the existing render -- mesh, arrows, and colorbars alike -- and the glyph's bound figure/axes all survive unchanged.

Examples:

• Arrows at the face centroids of a two-triangle mesh:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> fig, ax, im = mg.plot_vector_field(
  ...     np.array([0.3, -0.2]), np.array([0.1, 0.4])
  ... )
  >>> im.N
  2
  

• Compose the field over a filled mesh render; the host layers and colorbar stay, and the arrows bring no second colorbar:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> fig, ax = mg.plot(np.array([1.0, 2.0]))
  >>> n_axes = len(fig.axes)
  >>> fig2, ax2, im = mg.plot_vector_field(
  ...     np.array([0.3, -0.2]), np.array([0.1, 0.4]), compose=True
  ... )
  >>> ax2 is ax and len(fig2.axes) == n_axes
  True
  

• Node-located components as wind barbs:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> fig, ax, im = mg.plot_vector_field(
  ...     np.full(4, 5.0), np.zeros(4), kind="barbs", location="node"
  ... )
  >>> float(im.get_array().max())
  5.0
  

• A grouped colour scale applies a non-linear magnitude norm:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> from cleopatra.styling.scaling import ColorScaling
  >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
  >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
  >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
  >>> mg = MeshGlyph(node_x, node_y, faces)
  >>> fig, ax, im = mg.plot_vector_field(
  ...     np.array([0.3, -0.2]),
  ...     np.array([0.1, 0.4]),
  ...     color=ColorScaling.power(gamma=0.5),
  ... )
  >>> im.norm.gamma
  0.5
  

• streamplot is refused with an actionable message:

  >>> import numpy as np
  >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
  >>> mg = MeshGlyph(
  ...     np.array([0.0, 1.0, 0.5]),
  ...     np.array([0.0, 0.0, 1.0]),
  ...     np.array([[0, 1, 2]]),
  ... )
  >>> mg.plot_vector_field(np.array([1.0]), np.array([1.0]),
  ...                      kind="streamplot")
  Traceback (most recent call last):
      ...
  ValueError: kind='streamplot' is not supported on an unstructured mesh: ...
  

See Also

cleopatra.glyphs.gridded.vector_glyph.VectorGlyph: The delegate that renders the arrows/barbs and owns the thin/colorbar machinery; use it directly for gridded fields (including streamplot). face_centroids: The anchors used for face-located components. plot: The scalar mesh render a field is typically composed over.

Source code in src/cleopatra/glyphs/gridded/mesh_glyph.py

def plot_vector_field(
    self,
    u: np.ndarray,
    v: np.ndarray,
    *,
    kind: str = "quiver",
    thin: int | None = None,
    location: str = "face",
    ax: Any = None,
    title: str | None = None,
    colorbar: bool | ColorBar | None = None,
    color: ColorScaling | None = None,
    contour: Contour | None = None,
    classify: Classify | None = None,
    compose: bool = False,
    **kwargs: Any,
) -> tuple[plt.Figure, plt.Axes, Any]:
    """Plot a `(u, v)` vector field anchored on the mesh.

    Face-located components (`location="face"`) draw one arrow per face,
    anchored at the face's vertex centroid (`face_centroids`); node-located
    components anchor at the nodes themselves. Rendering delegates to
    `cleopatra.glyphs.gridded.vector_glyph.VectorGlyph`, so the arrows are
    coloured by the vector magnitude `hypot(u, v)` through the shared
    scalar-mapping pipeline, with the same colorbar behaviour.

    The field is drawn in the mesh's native (flat) coordinates: a
    `projection` preset applied by `plot` reprojects only the mesh render,
    so combine a vector field with the plain mesh, not the globe. A
    *replacing* render (`compose=False`) after a globe `plot` therefore
    removes the globe frame and restores the flat view -- the same
    contract as `plot` with the projection cleared -- while a composed
    overlay leaves the host frame untouched.

    Args:
        u: 1D x-components, one per face (`location="face"`) or per node
            (`location="node"`).
        v: 1D y-components, same length and location as `u`.
        kind: `"quiver"` (arrows, the default) or `"barbs"`.
            `"streamplot"` is refused: streamline tracing needs a regular
            grid, which an unstructured mesh does not have -- resample the
            field to a grid and use `VectorGlyph` directly instead.
        thin: Draw every `thin`-th element so a large mesh stays legible;
            `None` (the default) draws them all. Must be a positive
            integer.
        location: Mesh element location the components live on:
            `"face"` (the default) anchors one arrow per face at its
            vertex centroid (`face_centroids`); `"node"` anchors one
            arrow per node at the node coordinates.
        ax: Axes to draw on. If None, resolution priority is the axes
            bound at construction or by a previous render > an axes
            derived from a figure bound at construction > a new
            figure/axes created by the delegate (honouring a `figsize=`
            passed through `**kwargs`).
        title: Plot title, applied by the delegate.
        colorbar: Draw the magnitude colorbar. `None` (default) leaves
            the decision to the delegate's contract: on for a standalone
            render, off under `compose=True`; `True` or a typed `ColorBar`
            spec (placement / caption / sizing) always draws one, even
            composing; `False` suppresses it -- the same contract as
            `plot`.
        color: Colour-scale group object
            (`cleopatra.styling.scaling.ColorScaling`) applied to the
            magnitude, e.g. `ColorScaling.power(gamma=0.5)` -- the same
            grouped parameter `plot` and `VectorGlyph.plot` take.
        contour: Discretisation group object
            (`cleopatra.styling.params.Contour`); `Contour(levels=N)`
            discretises the magnitude colour norm.
        classify: Classification group object
            (`cleopatra.styling.params.Classify`) for scheme-based
            magnitude classes, forwarded to the delegate unchanged.
        compose: Draw *over* whatever is already on the axes instead of
            replacing it, by default `False`. `True` keeps the host
            layers -- a filled `plot` render, a `plot_outline` wireframe,
            or `add_tiles`/`add_relief` backdrops -- and layers the arrows
            on top. The glyph tracks a single current field, so a
            repeated composed call replaces the previous call's arrows
            (and the colorbar they brought, if any -- ask for a new one
            with `colorbar=True`) even when they live on another axes.
            `False` keeps the replace-don't-orphan default every glyph
            render has: the axes is cleared of all glyph artists first.
            Either way the render applies the mesh convention of an equal
            axes aspect, including to a foreign host it composes onto --
            the same "a composed overlay still applies its own aspect"
            contract `plot` documents.
        **kwargs: Overrides for the delegate `VectorGlyph`'s options
            (`cmap`, `vmin`, `vmax`, `scale`, `cbar_label`, `figsize`,
            ...). An unknown key raises `ValueError`.

    Returns:
        tuple[Figure, Axes, Any]: The figure, the axes, and the `Quiver`
            or `Barbs` mappable (e.g. for `Axes.quiverkey`). Under
            `compose=True` the mesh's own `im` (the scalar mappable from
            `plot`) is left untouched; a replacing render clears the mesh
            artists from the axes and resets `im` and the colorbar
            reference to `None`, as `plot_outline` does.

    Raises:
        ValueError: If `kind` is not `"quiver"`/`"barbs"` (including the
            explicit `"streamplot"` refusal), `location` is not
            `"face"`/`"node"`, `u`/`v` are not 1D of equal length matching
            the location's element count, `thin` is not a positive
            integer, a `**kwargs` key is not a `VectorGlyph` option,
            `density` is passed (a streamplot-only option -- use `thin=`),
            or the magnitude has no finite values while `vmin`/`vmax` are
            not both given. A rejected call raises before anything is
            touched: the existing render -- mesh, arrows, and colorbars
            alike -- and the glyph's bound figure/axes all survive
            unchanged.

    Examples:
        - Arrows at the face centroids of a two-triangle mesh:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> fig, ax, im = mg.plot_vector_field(
            ...     np.array([0.3, -0.2]), np.array([0.1, 0.4])
            ... )
            >>> im.N
            2

            ```
        - Compose the field over a filled mesh render; the host layers
            and colorbar stay, and the arrows bring no second colorbar:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> fig, ax = mg.plot(np.array([1.0, 2.0]))
            >>> n_axes = len(fig.axes)
            >>> fig2, ax2, im = mg.plot_vector_field(
            ...     np.array([0.3, -0.2]), np.array([0.1, 0.4]), compose=True
            ... )
            >>> ax2 is ax and len(fig2.axes) == n_axes
            True

            ```
        - Node-located components as wind barbs:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> fig, ax, im = mg.plot_vector_field(
            ...     np.full(4, 5.0), np.zeros(4), kind="barbs", location="node"
            ... )
            >>> float(im.get_array().max())
            5.0

            ```
        - A grouped colour scale applies a non-linear magnitude norm:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> from cleopatra.styling.scaling import ColorScaling
            >>> node_x = np.array([0.0, 1.0, 0.5, 1.5])
            >>> node_y = np.array([0.0, 0.0, 1.0, 1.0])
            >>> faces = np.array([[0, 1, 2], [1, 3, 2]])
            >>> mg = MeshGlyph(node_x, node_y, faces)
            >>> fig, ax, im = mg.plot_vector_field(
            ...     np.array([0.3, -0.2]),
            ...     np.array([0.1, 0.4]),
            ...     color=ColorScaling.power(gamma=0.5),
            ... )
            >>> im.norm.gamma
            0.5

            ```
        - `streamplot` is refused with an actionable message:
            ```python
            >>> import numpy as np
            >>> from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph
            >>> mg = MeshGlyph(
            ...     np.array([0.0, 1.0, 0.5]),
            ...     np.array([0.0, 0.0, 1.0]),
            ...     np.array([[0, 1, 2]]),
            ... )
            >>> mg.plot_vector_field(np.array([1.0]), np.array([1.0]),
            ...                      kind="streamplot")
            Traceback (most recent call last):
                ...
            ValueError: kind='streamplot' is not supported on an unstructured mesh: ...

            ```

    See Also:
        cleopatra.glyphs.gridded.vector_glyph.VectorGlyph: The delegate
            that renders the arrows/barbs and owns the `thin`/colorbar
            machinery; use it directly for gridded fields (including
            `streamplot`).
        face_centroids: The anchors used for face-located components.
        plot: The scalar mesh render a field is typically composed over.
    """
    u, v, thin_value = self._validate_vector_field(
        kind, location, u, v, thin, kwargs
    )

    if location == "face":
        centroids = self.face_centroids
        anchor_x, anchor_y = centroids[:, 0], centroids[:, 1]
    else:
        anchor_x, anchor_y = self._node_x, self._node_y

    target_ax = self._resolve_vector_target_ax(ax)

    # The delegate is constructed before the previous-arrows clear: the
    # constructor is its last validation surface (e.g. the grouped-kwarg
    # redirects), and it must reject while the previous arrows are still
    # intact. The clear itself runs BEFORE the new render so the old
    # overlay colorbar gives its layout space back before the new one
    # takes its own.
    delegate = VectorGlyph(anchor_x, anchor_y, u, v, thin=thin_value, **kwargs)
    if compose:
        self._clear_previous_vector_field()
    pre_bounds = (
        target_ax.get_position().frozen() if target_ax is not None else None
    )
    fig, ax_out, im = delegate.plot(
        kind=kind,
        ax=target_ax,
        title=title,
        colorbar=colorbar,
        color=color,
        contour=contour,
        classify=classify,
        compose=compose,
    )
    self._finish_vector_render(delegate, fig, ax_out, compose, pre_bounds)
    return fig, ax_out, im

Examples

Basic Face-Centered Plot

import numpy as np
import matplotlib.tri as mtri
from cleopatra.styling.colorbar import ColorBar
from cleopatra.glyphs.gridded.mesh_glyph import MeshGlyph

# Create a triangular mesh from random points
rng = np.random.default_rng(42)
node_x = rng.uniform(0, 10, 50)
node_y = rng.uniform(0, 8, 50)
tri = mtri.Triangulation(node_x, node_y)

mg = MeshGlyph(node_x, node_y, tri.triangles)

# Synthetic face data
cx = node_x[tri.triangles].mean(axis=1)
cy = node_y[tri.triangles].mean(axis=1)
face_data = np.sin(cx * 0.5) * np.cos(cy * 0.4) + 2

fig, ax = mg.plot(face_data, cmap="RdYlBu_r", title="Face-Centered Data")

Node-Centered Contour Plot

# Node data produces smooth interpolated contours
node_data = np.sin(node_x * 0.5) * np.cos(node_y * 0.4) * 3

fig, ax = mg.plot(
    node_data,
    location="node",
    cmap="terrain",
    levels=15,
    title="Node-Centered Contour",
)

Wireframe Outline

# Render mesh edges as a wireframe
fig, ax = mg.plot_outline(color="steelblue", linewidth=0.5)

Overlay Data with Wireframe

# Plot face data, then overlay wireframe on the same axes
mg2 = MeshGlyph(node_x, node_y, tri.triangles)
fig, ax = mg2.plot(face_data, cmap="Blues", title="Data + Wireframe")
mg2.plot_outline(color="black", linewidth=0.2)

Mixed-Element Mesh (Quads + Triangles)

# Mixed meshes use fill_value=-1 for padding
node_x = np.array([0, 1, 2, 0, 1, 2], dtype=float)
node_y = np.array([0, 0, 0, 1, 1, 1], dtype=float)
faces = np.array([
    [0, 1, 4, 3],   # quad
    [1, 2, 5, -1],  # triangle (padded with -1)
    [1, 5, 4, -1],  # triangle
])

mg = MeshGlyph(node_x, node_y, faces, fill_value=-1)
fig, ax = mg.plot(np.array([1.0, 2.0, 3.0]), edgecolor="black")

Color Scales

All color-scale types are chosen via the color=ColorScaling.… group object:

from cleopatra.styling.scaling import ColorScaling

mg = MeshGlyph(node_x, node_y, faces, fill_value=-1)

# Power scale (emphasize low values)
fig, ax = mg.plot(data, color=ColorScaling.power(gamma=0.3))

# Symmetrical log scale
fig, ax = mg.plot(data, color=ColorScaling.sym_log())

# Discrete boundary scale
fig, ax = mg.plot(data, color=ColorScaling.boundary(bounds=[0, 2, 4, 6]))

# Midpoint scale (split at a value)
fig, ax = mg.plot(data, color=ColorScaling.midpoint(at=3.0), cmap="RdBu_r")

Colorbar Customization

mg = MeshGlyph(node_x, node_y, faces, fill_value=-1)
fig, ax = mg.plot(
    data,
    colorbar=ColorBar(
        label="Water Depth [m]",
        orientation="horizontal",
        length=0.6,
        label_size=14,
    ),
)

Vector Field (Quiver / Barbs)

Render a 2-component vector field — e.g. depth-averaged velocities from a hydrodynamic model — anchored at the face centroids (location="face") or at the nodes (location="node"). Arrows are coloured by the vector magnitude, and thin= decimates a dense mesh so the field stays legible:

# standalone: arrows with a magnitude colorbar
fig, ax, im = mg.plot_vector_field(ucx, ucy, kind="quiver", thin=4)

# or composed over a filled mesh render
fig, ax = mg.plot(water_level)
fig, ax, im = mg.plot_vector_field(ucx, ucy, compose=True)

# wind barbs at the nodes
fig, ax, im = mg.plot_vector_field(u_node, v_node, kind="barbs", location="node")

streamplot is refused on an unstructured mesh (streamline tracing needs a regular grid) — resample the field to a grid and use VectorGlyph directly instead.

Animation

# Animate time-varying face data on a fixed mesh
mg = MeshGlyph(node_x, node_y, tri.triangles)

# frames: (n_timesteps, n_faces) array
frames = np.array([face_data * (1 + 0.2 * t) for t in range(10)])
time_labels = [f"t={t}" for t in range(10)]

anim = mg.animate(frames, time=time_labels, cmap="plasma", interval=300)
mg.save_animation("mesh_animation.gif", fps=3)

Explicit Edge Connectivity

When edge-node connectivity is available (e.g. from UGRID NetCDF files), pass it for faster wireframe rendering:

edges = np.array([[0, 1], [1, 2], [2, 3], [3, 0]])
mg = MeshGlyph(node_x, node_y, faces, edge_node_connectivity=edges)
fig, ax = mg.plot_outline()