class_docstr: An internal class to manage filters/algorithms for polydata datasets.
class_docstr_tok: ["An","internal","class","to","manage","filters\/algorithms","for","polydata","datasets","."]
docstr: Merge this mesh with one or more datasets.
  
  .. note::
     The behavior of this filter varies from the
     :func:`PolyDataFilters.boolean_union` filter.  This filter
     does not attempt to create a manifold mesh and will include
     internal surfaces when two meshes overlap.
  
  .. note::
     The ``+`` operator between two meshes uses this filter with
     the default parameters. When the other mesh is also a
     :class:`pyvista.PolyData`, in-place merging via ``+=`` is
     similarly possible.
  
  .. versionchanged:: 0.39.0
      Before version ``0.39.0``, if all input datasets were of type :class:`pyvista.PolyData`,
      the VTK ``vtkAppendPolyDataFilter`` and ``vtkCleanPolyData`` filters were used to perform merging.
      Otherwise, :func:`DataSetFilters.merge`, which uses the VTK ``vtkAppendFilter`` filter,
      was called.
      To enhance performance and coherence with merging operations available for other datasets in pyvista,
      the merging operation has been delegated in ``0.39.0`` to :func:`DataSetFilters.merge` only,
      irrespectively of input datasets types.
      This induced that points ordering can be altered compared to previous pyvista versions when
      merging only PolyData together.
      To obtain similar results as before ``0.39.0`` for multiple PolyData, combine
      :func:`PolyDataFilters.append_polydata` and :func:`PolyDataFilters.clean`.
  
  .. seealso::
      :func:`PolyDataFilters.append_polydata`
  
  Parameters
  ----------
  dataset : pyvista.DataSet
      PyVista dataset to merge this mesh with.
  
  merge_points : bool, optional
      Merge equivalent points when ``True``.
  
  tolerance : float, default: 0.0
      The absolute tolerance to use to find coincident points when
      ``merge_points=True``.
  
  inplace : bool, default: False
      Updates grid inplace when ``True`` if the input type is a
      :class:`pyvista.PolyData`. For other input meshes the
      result is a :class:`pyvista.UnstructuredGrid` which makes
      in-place operation impossible.
  
  main_has_priority : bool, optional
      When this parameter is ``True`` and ``merge_points=True``,
      the arrays of the merging grids will be overwritten
      by the original main mesh.
  
  progress_bar : bool, default: False
      Display a progress bar to indicate progress.
  
  Returns
  -------
  pyvista.DataSet
      :class:`pyvista.PolyData` if ``dataset`` is a
      :class:`pyvista.PolyData`, otherwise a
      :class:`pyvista.UnstructuredGrid`.
  
  Examples
  --------
  >>> import pyvista as pv
  >>> sphere_a = pv.Sphere()
  >>> sphere_b = pv.Sphere(center=(0.5, 0, 0))
  >>> merged = sphere_a.merge(sphere_b)
  >>> merged.plot(style='wireframe', color='lightblue')
docstr_tok: ["Merge","this","mesh","with","one","or","more","datasets",".","..","note",":",":","The","behavior","of","this","filter","varies","from","the",":","func",":","`","PolyDataFilters.boolean_union","`","filter",".","This","filter","does","not","attempt","to","create","a","manifold","mesh","and","will","include","internal","surfaces","when","two","meshes","overlap",".","..","note",":",":","The","``","+","``","operator","between","two","meshes","uses","this","filter","with","the","default","parameters",".","When","the","other","mesh","is","also","a",":","class",":","`","pyvista.PolyData","`",",","in-place","merging","via","``","+=","``","is","similarly","possible",".","..","versionchanged",":",":","0.39.0","Before","version","``","0.39.0","``",",","if","all","input","datasets","were","of","type",":","class",":","`","pyvista.PolyData","`",",","the","VTK","``","vtkAppendPolyDataFilter","``","and","``","vtkCleanPolyData","``","filters","were","used","to","perform","merging",".","Otherwise",",",":","func",":","`","DataSetFilters.merge","`",",","which","uses","the","VTK","``","vtkAppendFilter","``","filter",",","was","called",".","To","enhance","performance","and","coherence","with","merging","operations","available","for","other","datasets","in","pyvista",",","the","merging","operation","has","been","delegated","in","``","0.39.0","``","to",":","func",":","`","DataSetFilters.merge","`","only",",","irrespectively","of","input","datasets","types",".","This","induced","that","points","ordering","can","be","altered","compared","to","previous","pyvista","versions","when","merging","only","PolyData","together",".","To","obtain","similar","results","as","before","``","0.39.0","``","for","multiple","PolyData",",","combine",":","func",":","`","PolyDataFilters.append_polydata","`","and",":","func",":","`","PolyDataFilters.clean","`",".","..","seealso",":",":",":","func",":","`","PolyDataFilters.append_polydata","`","Parameters","--","--","--","--","--","dataset",":","pyvista.DataSet","PyVista","dataset","to","merge","this","mesh","with",".","merge_points",":","bool",",","optional","Merge","equivalent","points","when","``","True","``",".","tolerance",":","float",",","default",":","0.0","The","absolute","tolerance","to","use","to","find","coincident","points","when","``","merge_points=True","``",".","inplace",":","bool",",","default",":","False","Updates","grid","inplace","when","``","True","``","if","the","input","type","is","a",":","class",":","`","pyvista.PolyData","`",".","For","other","input","meshes","the","result","is","a",":","class",":","`","pyvista.UnstructuredGrid","`","which","makes","in-place","operation","impossible",".","main_has_priority",":","bool",",","optional","When","this","parameter","is","``","True","``","and","``","merge_points=True","``",",","the","arrays","of","the","merging","grids","will","be","overwritten","by","the","original","main","mesh",".","progress_bar",":","bool",",","default",":","False","Display","a","progress","bar","to","indicate","progress",".","Returns","--","--","--","-","pyvista.DataSet",":","class",":","`","pyvista.PolyData","`","if","``","dataset","``","is","a",":","class",":","`","pyvista.PolyData","`",",","otherwise","a",":","class",":","`","pyvista.UnstructuredGrid","`",".","Examples","--","--","--","--",">",">",">","import","pyvista","as","pv",">",">",">","sphere_a","=","pv.Sphere","(",")",">",">",">","sphere_b","=","pv.Sphere","(","center=","(","0.5",",","0",",","0",")",")",">",">",">","merged","=","sphere_a.merge","(","sphere_b",")",">",">",">","merged.plot","(","style='wireframe","'",",","color='lightblue","'",")"]
code: def merge(
      self,
      dataset,
      merge_points=True,
      tolerance=0.0,
      inplace=False,
      main_has_priority=True,
      progress_bar=False,
  ):
      """Merge this mesh with one or more datasets.
  
      .. note::
         The behavior of this filter varies from the
         :func:`PolyDataFilters.boolean_union` filter.  This filter
         does not attempt to create a manifold mesh and will include
         internal surfaces when two meshes overlap.
  
      .. note::
         The ``+`` operator between two meshes uses this filter with
         the default parameters. When the other mesh is also a
         :class:`pyvista.PolyData`, in-place merging via ``+=`` is
         similarly possible.
  
      .. versionchanged:: 0.39.0
          Before version ``0.39.0``, if all input datasets were of type :class:`pyvista.PolyData`,
          the VTK ``vtkAppendPolyDataFilter`` and ``vtkCleanPolyData`` filters were used to perform merging.
          Otherwise, :func:`DataSetFilters.merge`, which uses the VTK ``vtkAppendFilter`` filter,
          was called.
          To enhance performance and coherence with merging operations available for other datasets in pyvista,
          the merging operation has been delegated in ``0.39.0`` to :func:`DataSetFilters.merge` only,
          irrespectively of input datasets types.
          This induced that points ordering can be altered compared to previous pyvista versions when
          merging only PolyData together.
          To obtain similar results as before ``0.39.0`` for multiple PolyData, combine
          :func:`PolyDataFilters.append_polydata` and :func:`PolyDataFilters.clean`.
  
      .. seealso::
          :func:`PolyDataFilters.append_polydata`
  
      Parameters
      ----------
      dataset : pyvista.DataSet
          PyVista dataset to merge this mesh with.
  
      merge_points : bool, optional
          Merge equivalent points when ``True``.
  
      tolerance : float, default: 0.0
          The absolute tolerance to use to find coincident points when
          ``merge_points=True``.
  
      inplace : bool, default: False
          Updates grid inplace when ``True`` if the input type is a
          :class:`pyvista.PolyData`. For other input meshes the
          result is a :class:`pyvista.UnstructuredGrid` which makes
          in-place operation impossible.
  
      main_has_priority : bool, optional
          When this parameter is ``True`` and ``merge_points=True``,
          the arrays of the merging grids will be overwritten
          by the original main mesh.
  
      progress_bar : bool, default: False
          Display a progress bar to indicate progress.
  
      Returns
      -------
      pyvista.DataSet
          :class:`pyvista.PolyData` if ``dataset`` is a
          :class:`pyvista.PolyData`, otherwise a
          :class:`pyvista.UnstructuredGrid`.
  
      Examples
      --------
      >>> import pyvista as pv
      >>> sphere_a = pv.Sphere()
      >>> sphere_b = pv.Sphere(center=(0.5, 0, 0))
      >>> merged = sphere_a.merge(sphere_b)
      >>> merged.plot(style='wireframe', color='lightblue')
  
      """
      # check if dataset or datasets are not polydata
      if isinstance(dataset, (list, tuple, pyvista.MultiBlock)):
          is_polydata = all(
              isinstance(data, pyvista.PolyData) for data in dataset
          )
      else:
          is_polydata = isinstance(dataset, pyvista.PolyData)
  
      if inplace and not is_polydata:
          raise TypeError(
              "In-place merge requires both input datasets to be PolyData."
          )
  
      merged = DataSetFilters.merge(
          self,
          dataset,
          merge_points=merge_points,
          tolerance=tolerance,
          main_has_priority=main_has_priority,
          inplace=False,
          progress_bar=progress_bar,
      )
  
      # convert back to a polydata if both inputs were polydata
      if is_polydata:
          # if either of the input datasets contained lines or strips, we
          # must use extract_geometry to ensure they get converted back
          # correctly. This incurrs a performance penalty, but is needed to
          # maintain data consistency.
          if isinstance(dataset, (list, tuple, pyvista.MultiBlock)):
              dataset_has_lines_strips = any(
                  ds.n_lines or ds.n_strips or ds.n_verts
                  for ds in dataset
              )
          else:
              dataset_has_lines_strips = (
                  dataset.n_lines or dataset.n_strips or dataset.n_verts
              )
  
          if (
              self.n_lines
              or self.n_strips
              or self.n_verts
              or dataset_has_lines_strips
          ):
              merged = merged.extract_geometry()
          else:
              polydata_merged = pyvista.PolyData(
                  merged.points,
                  faces=merged.cells,
                  n_faces=merged.n_cells,
                  deep=False,
              )
              # Calling update() will modify the active scalars in this specific
              # case. Store values to restore after updating.
              active_point_scalars_name = (
                  merged.point_data.active_scalars_name
              )
              active_cell_scalars_name = (
                  merged.cell_data.active_scalars_name
              )
  
              polydata_merged.point_data.update(merged.point_data)
              polydata_merged.cell_data.update(merged.cell_data)
              polydata_merged.field_data.update(merged.field_data)
  
              # restore active scalars
              polydata_merged.point_data.active_scalars_name = (
                  active_point_scalars_name
              )
              polydata_merged.cell_data.active_scalars_name = (
                  active_cell_scalars_name
              )
  
              merged = polydata_merged
  
      if inplace:
          self.deep_copy(merged)
          return self
  
      return merged
  
imports: import collections.abc
  import warnings
  import numpy
  import pyvista
  from pyvista.core import _vtk_core
  from pyvista.core.errors import MissingDataError, NotAllTrianglesError, PyVistaFutureWarning, VTKVersionError
  from pyvista.core.filters import _get_output, _update_alg
  from pyvista.core.filters.data_set import DataSetFilters
  from pyvista.core.utilities.arrays import FieldAssociation, get_array, get_array_association, set_default_active_scalars, vtk_id_list_to_array
  from pyvista.core.utilities.geometric_objects import NORMALS
  from pyvista.core.utilities.helpers import generate_plane, wrap
  from pyvista.core.utilities.misc import abstract_class, assert_empty_kwargs
label_desc: Use image node_id 9 for calling the PolyDataFilters obj's underlying member method code with example usage: obj.merge(dataset, merge_points, tolerance, inplace, main_has_priority, progress_bar) and returns: merged, self