code: def plot_surf_roi(
      surf_mesh,
      roi_map,
      bg_map=None,
      hemi="left",
      view="lateral",
      engine="matplotlib",
      avg_method="median",
      threshold=1e-14,
      alpha="auto",
      vmin=None,
      vmax=None,
      cmap="gist_ncar",
      cbar_tick_format="auto",
      bg_on_data=False,
      darkness=0.7,
      title=None,
      title_font_size=18,
      output_file=None,
      axes=None,
      figure=None,
      **kwargs,
  ):
      """Plot ROI on a surface :term:`mesh` with optional background.
  
      .. versionadded:: 0.3
  
      Parameters
      ----------
      surf_mesh : str or list of two numpy.ndarray or Mesh
          Surface :term:`mesh` geometry, can be a file (valid formats are
          .gii or Freesurfer specific files such as .orig, .pial,
          .sphere, .white, .inflated) or
          a list of two Numpy arrays, the first containing the x-y-z
          coordinates of the :term:`mesh` vertices,
          the second containing the indices
          (into coords) of the :term:`mesh` :term:`faces`,
          or a Mesh object with "coordinates" and "faces" attributes.
  
      roi_map : str or numpy.ndarray or list of numpy.ndarray
          ROI map to be displayed on the surface :term:`mesh`,
          can be a file
          (valid formats are .gii, .mgz, .nii, .nii.gz, or Freesurfer specific
          files such as .annot or .label), or
          a Numpy array with a value for each :term:`vertex` of the `surf_mesh`.
          The value at each vertex one inside the ROI and zero inside ROI, or an
          integer giving the label number for atlases.
  
      bg_map : str or numpy.ndarray, optional
          Background image to be plotted on the :term:`mesh` underneath
          the stat_map in greyscale, most likely a sulcal depth map for
          realistic shading.
          If the map contains values outside [0, 1], it will be
          rescaled such that all values are in [0, 1]. Otherwise,
          it will not be modified.
  
      %(hemi)s
      %(view)s
      engine : {'matplotlib', 'plotly'}, default='matplotlib'
  
          .. versionadded:: 0.9.0
  
          Selects which plotting engine will be used by ``plot_surf_roi``.
          Currently, only ``matplotlib`` and ``plotly`` are supported.
  
          .. note::
              To use the ``plotly`` engine you need to have
              ``plotly`` installed.
  
          .. note::
              To be able to save figures to disk with ``plotly`` engine
              you need to have ``kaleido`` installed.
  
          .. warning::
              The ``plotly`` engine is new and experimental.
              Please report bugs that you may encounter.
  
  
      %(avg_method)s
  
          .. note::
              This option is currently only implemented for the
              ``matplotlib`` engine.
  
          Default='median'.
  
      threshold : a number or None, default=1e-14
          Threshold regions that are labelled 0.
          If you want to use 0 as a label, set threshold to None.
      %(cmap)s
          Default='gist_ncar'.
      %(cbar_tick_format)s
          Default="auto" which defaults to integers format:
  
              - "%%i" for ``matplotlib`` engine.
              - "." for ``plotly`` engine.
  
          .. versionadded:: 0.7.1
  
      alpha : float or 'auto', default='auto'
          Alpha level of the :term:`mesh` (not the stat_map).
          If default, alpha will default to 0.5 when no bg_map is passed
          and to 1 if a bg_map is passed.
  
          .. note::
              This option is currently only implemented for the
              ``matplotlib`` engine.
  
      %(bg_on_data)s
  
      %(darkness)s
          Default=1.
  
          .. note::
              This option is currently only implemented for the
              ``matplotlib`` engine.
  
      %(title)s
      title_font_size : :obj:`int`, default=18
          Size of the title font.
  
          .. versionadded:: 0.9.0
  
      %(output_file)s
      axes : Axes instance or None, optional
          The axes instance to plot to. The projection must be '3d' (e.g.,
          `plt.subplots(subplot_kw={'projection': '3d'})`).
          If None, a new axes is created.
  
          .. note::
              This option is currently only implemented for the
              ``matplotlib`` engine.
  
      %(figure)s
  
          .. note::
              This option is currently only implemented for the
              ``matplotlib`` engine.
  
      kwargs : dict, optional
          Keyword arguments passed to :func:`nilearn.plotting.plot_surf`.
  
      See Also
      --------
      nilearn.datasets.fetch_surf_fsaverage: For surface data object to be
          used as background map for this plotting function.
  
      nilearn.plotting.plot_surf: For brain surface visualization.
  
      nilearn.surface.vol_to_surf : For info on the generation of surfaces.
  
      """
      # preload roi and mesh to determine vmin, vmax and give more useful error
      # messages in case of wrong inputs
  
      roi = load_surf_data(roi_map)
      idx_not_na = ~np.isnan(roi)
      if vmin is None:
          vmin = np.nanmin(roi)
      if vmax is None:
          vmax = 1 + np.nanmax(roi)
  
      mesh = load_surf_mesh(surf_mesh)
  
      if roi.ndim != 1:
          raise ValueError(
              "roi_map can only have one dimension but has "
              f"{roi.ndim} dimensions"
          )
      if roi.shape[0] != mesh[0].shape[0]:
          raise ValueError(
              "roi_map does not have the same number of vertices "
              "as the mesh. If you have a list of indices for the "
              "ROI you can convert them into a ROI map like this:\n"
              "roi_map = np.zeros(n_vertices)\n"
              "roi_map[roi_idx] = 1"
          )
      if (roi < 0).any():
          # TODO raise ValueError in release 0.13
          warn(
              (
                  "Negative values in roi_map will no longer be allowed in"
                  " Nilearn version 0.13"
              ),
              DeprecationWarning,
          )
      if not np.array_equal(
          roi[idx_not_na], roi[idx_not_na].astype(int)
      ):
          # TODO raise ValueError in release 0.13
          warn(
              (
                  "Non-integer values in roi_map will no longer be allowed in"
                  " Nilearn version 0.13"
              ),
              DeprecationWarning,
          )
  
      if cbar_tick_format == "auto":
          cbar_tick_format = "." if engine == "plotly" else "%i"
  
      display = plot_surf(
          mesh,
          surf_map=roi,
          bg_map=bg_map,
          hemi=hemi,
          view=view,
          engine=engine,
          avg_method=avg_method,
          threshold=threshold,
          cmap=cmap,
          cbar_tick_format=cbar_tick_format,
          alpha=alpha,
          bg_on_data=bg_on_data,
          darkness=darkness,
          vmin=vmin,
          vmax=vmax,
          title=title,
          title_font_size=title_font_size,
          output_file=output_file,
          axes=axes,
          figure=figure,
          **kwargs,
      )
  
      return display
  
imports: import itertools
  import math
  from collections.abc import Sequence
  from warnings import warn
  import matplotlib
  import matplotlib.pyplot
  import numpy
  from matplotlib import gridspec
  from matplotlib.cm import ScalarMappable
  from matplotlib.colorbar import make_axes
  from matplotlib.colors import LinearSegmentedColormap, Normalize, to_rgba
  from matplotlib.patches import Patch
  from mpl_toolkits.mplot3d.art3d import Poly3DCollection
  from nilearn import image, surface
  from nilearn._utils import check_niimg_3d, compare_version, fill_doc
  from nilearn._utils.helpers import is_kaleido_installed, is_plotly_installed
  from nilearn.plotting.cm import cold_hot, mix_colormaps
  from nilearn.plotting.displays._slicers import _get_cbar_ticks
  from nilearn.plotting.html_surface import get_vertexcolor
  from nilearn.plotting.img_plotting import get_colorbar_and_data_ranges
  from nilearn.plotting.js_plotting_utils import colorscale
  from nilearn.surface import load_surf_data, load_surf_mesh, vol_to_surf
  from nilearn.surface.surface import check_mesh
label_desc: Use image node_id 28 for calling a global function with example usage: plot_surf_roi(surf_mesh, roi_map, bg_map, hemi, view, engine, avg_method, threshold, alpha, vmin, vmax, cmap, cbar_tick_format, bg_on_data, darkness, title, title_font_size, output_file, axes, figure) and returns: display