code: def marching_cubes(
      volume,
      level=None,
      *,
      spacing=(1.0, 1.0, 1.0),
      gradient_direction="descent",
      step_size=1,
      allow_degenerate=True,
      method="lewiner",
      mask=None,
  ):
      """Marching cubes algorithm to find surfaces in 3d volumetric data.
  
      In contrast with Lorensen et al. approach [2]_, Lewiner et
      al. algorithm is faster, resolves ambiguities, and guarantees
      topologically correct results. Therefore, this algorithm generally
      a better choice.
  
      Parameters
      ----------
      volume : (M, N, P) ndarray
          Input data volume to find isosurfaces. Will internally be
          converted to float32 if necessary.
      level : float, optional
          Contour value to search for isosurfaces in `volume`. If not
          given or None, the average of the min and max of vol is used.
      spacing : length-3 tuple of floats, optional
          Voxel spacing in spatial dimensions corresponding to numpy array
          indexing dimensions (M, N, P) as in `volume`.
      gradient_direction : string, optional
          Controls if the mesh was generated from an isosurface with gradient
          descent toward objects of interest (the default), or the opposite,
          considering the *left-hand* rule.
          The two options are:
          * descent : Object was greater than exterior
          * ascent : Exterior was greater than object
      step_size : int, optional
          Step size in voxels. Default 1. Larger steps yield faster but
          coarser results. The result will always be topologically correct
          though.
      allow_degenerate : bool, optional
          Whether to allow degenerate (i.e. zero-area) triangles in the
          end-result. Default True. If False, degenerate triangles are
          removed, at the cost of making the algorithm slower.
      method: {'lewiner', 'lorensen'}, optional
          Whether the method of Lewiner et al. or Lorensen et al. will be used.
      mask : (M, N, P) array, optional
          Boolean array. The marching cube algorithm will be computed only on
          True elements. This will save computational time when interfaces
          are located within certain region of the volume M, N, P-e.g. the top
          half of the cube-and also allow to compute finite surfaces-i.e. open
          surfaces that do not end at the border of the cube.
  
      Returns
      -------
      verts : (V, 3) array
          Spatial coordinates for V unique mesh vertices. Coordinate order
          matches input `volume` (M, N, P). If ``allow_degenerate`` is set to
          True, then the presence of degenerate triangles in the mesh can make
          this array have duplicate vertices.
      faces : (F, 3) array
          Define triangular faces via referencing vertex indices from ``verts``.
          This algorithm specifically outputs triangles, so each face has
          exactly three indices.
      normals : (V, 3) array
          The normal direction at each vertex, as calculated from the
          data.
      values : (V,) array
          Gives a measure for the maximum value of the data in the local region
          near each vertex. This can be used by visualization tools to apply
          a colormap to the mesh.
  
      See Also
      --------
      skimage.measure.mesh_surface_area
      skimage.measure.find_contours
  
      Notes
      -----
      The algorithm [1]_ is an improved version of Chernyaev's Marching
      Cubes 33 algorithm. It is an efficient algorithm that relies on
      heavy use of lookup tables to handle the many different cases,
      keeping the algorithm relatively easy. This implementation is
      written in Cython, ported from Lewiner's C++ implementation.
  
      To quantify the area of an isosurface generated by this algorithm, pass
      verts and faces to `skimage.measure.mesh_surface_area`.
  
      Regarding visualization of algorithm output, to contour a volume
      named `myvolume` about the level 0.0, using the ``mayavi`` package::
  
        >>>
        >> from mayavi import mlab
        >> verts, faces, _, _ = marching_cubes(myvolume, 0.0)
        >> mlab.triangular_mesh([vert[0] for vert in verts],
                                [vert[1] for vert in verts],
                                [vert[2] for vert in verts],
                                faces)
        >> mlab.show()
  
      Similarly using the ``visvis`` package::
  
        >>>
        >> import visvis as vv
        >> verts, faces, normals, values = marching_cubes(myvolume, 0.0)
        >> vv.mesh(np.fliplr(verts), faces, normals, values)
        >> vv.use().Run()
  
      To reduce the number of triangles in the mesh for better performance,
      see this `example
      <https://docs.enthought.com/mayavi/mayavi/auto/example_julia_set_decimation.html#example-julia-set-decimation>`_
      using the ``mayavi`` package.
  
      References
      ----------
      .. [1] Thomas Lewiner, Helio Lopes, Antonio Wilson Vieira and Geovan
             Tavares. Efficient implementation of Marching Cubes' cases with
             topological guarantees. Journal of Graphics Tools 8(2)
             pp. 1-15 (december 2003).
             :DOI:`10.1080/10867651.2003.10487582`
      .. [2] Lorensen, William and Harvey E. Cline. Marching Cubes: A High
             Resolution 3D Surface Construction Algorithm. Computer Graphics
             (SIGGRAPH 87 Proceedings) 21(4) July 1987, p. 163-170).
             :DOI:`10.1145/37401.37422`
      """
      use_classic = False
      if method == "lorensen":
          use_classic = True
      elif method != "lewiner":
          raise ValueError(
              "method should be either 'lewiner' or 'lorensen'"
          )
      return _marching_cubes_lewiner(
          volume,
          level,
          spacing,
          gradient_direction,
          step_size,
          allow_degenerate,
          use_classic=use_classic,
          mask=mask,
      )
  
file_path: scikit-image/skimage/measure/_marching_cubes_lewiner.py
imports: import base64
  import numpy
  from .None import _marching_cubes_lewiner_luts
  from .None import _marching_cubes_lewiner_cy
label_desc: Use image node_id 1 for calling a global function with example usage: marching_cubes(volume, level) and returns: _marching_cubes_lewiner