code: import warnings
  
  import numpy as np
  
  from ...utils.colormaps import AVAILABLE_COLORMAPS
  from ...utils.events import Event
  from ...utils.translations import trans
  from ..base import Layer
  from ..intensity_mixin import IntensityVisualizationMixin
  from ..utils.layer_utils import calc_data_range
  from ._surface_constants import Shading
  from .normals import SurfaceNormals
  from .wireframe import SurfaceWireframe
  
  
  # Mixin must come before Layer
  class Surface(IntensityVisualizationMixin, Layer):
      """
      Surface layer renders meshes onto the canvas.
  
      Parameters
      ----------
      data : 2-tuple or 3-tuple of array
          The first element of the tuple is an (N, D) array of vertices of
          mesh triangles. The second is an (M, 3) array of int of indices
          of the mesh triangles. The optional third element is the
          (K0, ..., KL, N) array of values used to color vertices where the
          additional L dimensions are used to color the same mesh with
          different values. If not provided, it defaults to ones.
      colormap : str, napari.utils.Colormap, tuple, dict
          Colormap to use for luminance images. If a string must be the name
          of a supported colormap from vispy or matplotlib. If a tuple the
          first value must be a string to assign as a name to a colormap and
          the second item must be a Colormap. If a dict the key must be a
          string to assign as a name to a colormap and the value must be a
          Colormap.
      contrast_limits : list (2,)
          Color limits to be used for determining the colormap bounds for
          luminance images. If not passed is calculated as the min and max of
          the image.
      gamma : float
          Gamma correction for determining colormap linearity. Defaults to 1.
      name : str
          Name of the layer.
      metadata : dict
          Layer metadata.
      scale : tuple of float
          Scale factors for the layer.
      translate : tuple of float
          Translation values for the layer.
      rotate : float, 3-tuple of float, or n-D array.
          If a float convert into a 2D rotation matrix using that value as an
          angle. If 3-tuple convert into a 3D rotation matrix, using a yaw,
          pitch, roll convention. Otherwise assume an nD rotation. Angles are
          assumed to be in degrees. They can be converted from radians with
          np.degrees if needed.
      shear : 1-D array or n-D array
          Either a vector of upper triangular values, or an nD shear matrix with
          ones along the main diagonal.
      affine : n-D array or napari.utils.transforms.Affine
          (N+1, N+1) affine transformation matrix in homogeneous coordinates.
          The first (N, N) entries correspond to a linear transform and
          the final column is a length N translation vector and a 1 or a napari
          `Affine` transform object. Applied as an extra transform on top of the
          provided scale, rotate, and shear values.
      opacity : float
          Opacity of the layer visual, between 0.0 and 1.0.
      blending : str
          One of a list of preset blending modes that determines how RGB and
          alpha values of the layer visual get mixed. Allowed values are
          {'opaque', 'translucent', and 'additive'}.
      shading : str, Shading
          One of a list of preset shading modes that determine the lighting model
          using when rendering the surface in 3D.
  
          * ``Shading.NONE``
            Corresponds to ``shading='none'``.
          * ``Shading.FLAT``
            Corresponds to ``shading='flat'``.
          * ``Shading.SMOOTH``
            Corresponds to ``shading='smooth'``.
      visible : bool
          Whether the layer visual is currently being displayed.
      cache : bool
          Whether slices of out-of-core datasets should be cached upon retrieval.
          Currently, this only applies to dask arrays.
      wireframe : dict or SurfaceWireframe
          Whether and how to display the edges of the surface mesh with a wireframe.
      normals : dict or SurfaceNormals
          Whether and how to display the face and vertex normals of the surface mesh.
  
      Attributes
      ----------
      data : 3-tuple of array
          The first element of the tuple is an (N, D) array of vertices of
          mesh triangles. The second is an (M, 3) array of int of indices
          of the mesh triangles. The third element is the (K0, ..., KL, N)
          array of values used to color vertices where the additional L
          dimensions are used to color the same mesh with different values.
      vertices : (N, D) array
          Vertices of mesh triangles.
      faces : (M, 3) array of int
          Indices of mesh triangles.
      vertex_values : (K0, ..., KL, N) array
          Values used to color vertices.
      colormap : str, napari.utils.Colormap, tuple, dict
          Colormap to use for luminance images. If a string must be the name
          of a supported colormap from vispy or matplotlib. If a tuple the
          first value must be a string to assign as a name to a colormap and
          the second item must be a Colormap. If a dict the key must be a
          string to assign as a name to a colormap and the value must be a
          Colormap.
      contrast_limits : list (2,)
          Color limits to be used for determining the colormap bounds for
          luminance images. If not passed is calculated as the min and max of
          the image.
      shading: str
          One of a list of preset shading modes that determine the lighting model
          using when rendering the surface.
  
          * ``'none'``
          * ``'flat'``
          * ``'smooth'``
      gamma : float
          Gamma correction for determining colormap linearity.
      wireframe : SurfaceWireframe
          Whether and how to display the edges of the surface mesh with a wireframe.
      normals : SurfaceNormals
          Whether and how to display the face and vertex normals of the surface mesh.
  
  
      Notes
      -----
      _data_view : (M, 2) or (M, 3) array
          The coordinates of the vertices given the viewed dimensions.
      _view_faces : (P, 3) array
          The integer indices of the vertices that form the triangles
          in the currently viewed slice.
      _colorbar : array
          Colorbar for current colormap.
      """
  
      _colormaps = AVAILABLE_COLORMAPS
  
      def __init__(
          self,
          data,
          *,
          colormap='gray',
          contrast_limits=None,
          gamma=1,
          name=None,
          metadata=None,
          scale=None,
          translate=None,
          rotate=None,
          shear=None,
          affine=None,
          opacity=1,
          blending='translucent',
          shading='flat',
          visible=True,
          cache=True,
          experimental_clipping_planes=None,
          wireframe=None,
          normals=None,
      ):
  
          ndim = data[0].shape[1]
  
          super().__init__(
              data,
              ndim,
              name=name,
              metadata=metadata,
              scale=scale,
              translate=translate,
              rotate=rotate,
              shear=shear,
              affine=affine,
              opacity=opacity,
              blending=blending,
              visible=visible,
              cache=cache,
              experimental_clipping_planes=experimental_clipping_planes,
          )
  
          self.events.add(
              interpolation=Event,
              rendering=Event,
              shading=Event,
          )
  
          # assign mesh data and establish default behavior
          if len(data) not in (2, 3):
              raise ValueError(
                  trans._(
                      'Surface data tuple must be 2 or 3, specifying verictes, faces, and optionally vertex values, instead got length {length}.',
                      deferred=True,
                      length=len(data),
                  )
              )
          self._vertices = data[0]
          self._faces = data[1]
          if len(data) == 3:
              self._vertex_values = data[2]
          else:
              self._vertex_values = np.ones(len(self._vertices))
  
          # Set contrast_limits and colormaps
          self._gamma = gamma
          if contrast_limits is None:
              self._contrast_limits_range = calc_data_range(self._vertex_values)
          else:
              self._contrast_limits_range = contrast_limits
          self._contrast_limits = tuple(self._contrast_limits_range)
          self.colormap = colormap
          self.contrast_limits = self._contrast_limits
  
          # Data containing vectors in the currently viewed slice
          self._data_view = np.zeros((0, self._ndisplay))
          self._view_faces = np.zeros((0, 3))
          self._view_vertex_values = []
  
          # Trigger generation of view slice and thumbnail
          self._update_dims()
  
          # Shading mode
          self._shading = shading
  
          self.wireframe = wireframe or SurfaceWireframe()
          self.normals = normals or SurfaceNormals()
  
      def _calc_data_range(self, mode='data'):
          return calc_data_range(self.vertex_values)
  
      @property
      def dtype(self):
          return self.vertex_values.dtype
  
      @property
      def data(self):
          return (self.vertices, self.faces, self.vertex_values)
  
      @data.setter
      def data(self, data):
          if len(data) not in (2, 3):
              raise ValueError(
                  trans._(
                      'Surface data tuple must be 2 or 3, specifying vertices, faces, and optionally vertex values, instead got length {data_length}.',
                      deferred=True,
                      data_length=len(data),
                  )
              )
          self._vertices = data[0]
          self._faces = data[1]
          if len(data) == 3:
              self._vertex_values = data[2]
          else:
              self._vertex_values = np.ones(len(self._vertices))
  
          self._update_dims()
          self.events.data(value=self.data)
          if self._keep_auto_contrast:
              self.reset_contrast_limits()
  
      @property
      def vertices(self):
          return self._vertices
  
      @vertices.setter
      def vertices(self, vertices):
          """Array of vertices of mesh triangles."""
  
          self._vertices = vertices
  
          self._update_dims()
          self.refresh()
          self.events.data(value=self.data)
          self._set_editable()
  
      @property
      def vertex_values(self) -> np.ndarray:
          return self._vertex_values
  
      @vertex_values.setter
      def vertex_values(self, vertex_values: np.ndarray):
          """Array of values used to color vertices.."""
  
          self._vertex_values = vertex_values
  
          self.refresh()
          self.events.data(value=self.data)
          self._set_editable()
  
      @property
      def faces(self) -> np.ndarray:
          return self._faces
  
      @faces.setter
      def faces(self, faces: np.ndarray):
          """Array of indices of mesh triangles.."""
  
          self.faces = faces
  
          self.refresh()
          self.events.data(value=self.data)
          self._set_editable()
  
      def _get_ndim(self):
          """Determine number of dimensions of the layer."""
          return self.vertices.shape[1] + (self.vertex_values.ndim - 1)
  
      @property
      def _extent_data(self) -> np.ndarray:
          """Extent of layer in data coordinates.
  
          Returns
          -------
          extent_data : array, shape (2, D)
          """
          if len(self.vertices) == 0:
              extrema = np.full((2, self.ndim), np.nan)
          else:
              maxs = np.max(self.vertices, axis=0)
              mins = np.min(self.vertices, axis=0)
  
              # The full dimensionality and shape of the layer is determined by
              # the number of additional vertex value dimensions and the
              # dimensionality of the vertices themselves
              if self.vertex_values.ndim > 1:
                  mins = [0] * (self.vertex_values.ndim - 1) + list(mins)
                  maxs = list(self.vertex_values.shape[:-1]) + list(maxs)
              extrema = np.vstack([mins, maxs])
          return extrema
  
      @property
      def shading(self):
          return str(self._shading)
  
      @shading.setter
      def shading(self, shading):
          if isinstance(shading, Shading):
              self._shading = shading
          else:
              self._shading = Shading(shading)
          self.events.shading(value=self._shading)
  
      def _get_state(self):
          """Get dictionary of layer state.
  
          Returns
          -------
          state : dict
              Dictionary of layer state.
          """
          state = self._get_base_state()
          state.update(
              {
                  'colormap': self.colormap.name,
                  'contrast_limits': self.contrast_limits,
                  'gamma': self.gamma,
                  'shading': self.shading,
                  'data': self.data,
                  'wireframe': self.wireframe.dict(),
                  'normals': self.normals.dict(),
              }
          )
          return state
  
      def _set_view_slice(self):
          """Sets the view given the indices to slice with."""
          N, vertex_ndim = self.vertices.shape
          values_ndim = self.vertex_values.ndim - 1
  
          # Take vertex_values dimensionality into account if more than one value
          # is provided per vertex.
          if values_ndim > 0:
              # Get indices for axes corresponding to values dimensions
              values_indices = self._slice_indices[:-vertex_ndim]
              values = self.vertex_values[values_indices]
              if values.ndim > 1:
                  warnings.warn(
                      trans._(
                          "Assigning multiple values per vertex after slicing is not allowed. All dimensions corresponding to vertex_values must be non-displayed dimensions. Data will not be visible.",
                          deferred=True,
                      )
                  )
                  self._data_view = np.zeros((0, self._ndisplay))
                  self._view_faces = np.zeros((0, 3))
                  self._view_vertex_values = []
                  return
  
              self._view_vertex_values = values
              # Determine which axes of the vertices data are being displayed
              # and not displayed, ignoring the additional dimensions
              # corresponding to the vertex_values.
              indices = np.array(self._slice_indices[-vertex_ndim:])
              disp = [
                  d
                  for d in np.subtract(self._dims_displayed, values_ndim)
                  if d >= 0
              ]
              not_disp = [
                  d
                  for d in np.subtract(self._dims_not_displayed, values_ndim)
                  if d >= 0
              ]
          else:
              self._view_vertex_values = self.vertex_values
              indices = np.array(self._slice_indices)
              not_disp = list(self._dims_not_displayed)
              disp = list(self._dims_displayed)
  
          self._data_view = self.vertices[:, disp]
          if len(self.vertices) == 0:
              self._view_faces = np.zeros((0, 3))
          elif vertex_ndim > self._ndisplay:
              vertices = self.vertices[:, not_disp].astype('int')
              triangles = vertices[self.faces]
              matches = np.all(triangles == indices[not_disp], axis=(1, 2))
              matches = np.where(matches)[0]
              if len(matches) == 0:
                  self._view_faces = np.zeros((0, 3))
              else:
                  self._view_faces = self.faces[matches]
          else:
              self._view_faces = self.faces
  
          if self._keep_auto_contrast:
              self.reset_contrast_limits()
  
      def _update_thumbnail(self):
          """Update thumbnail with current surface."""
          pass
  
      def _get_value(self, position):
          """Value of the data at a position in data coordinates.
  
          Parameters
          ----------
          position : tuple
              Position in data coordinates.
  
          Returns
          -------
          value : None
              Value of the data at the coord.
          """
          return None
  
apis: numpy.vstack numpy.zeros numpy.subtract numpy.max numpy.all numpy.min numpy.array numpy.where numpy.full