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: Create a ribbon of the lines in this dataset.
  
  .. note::
     If there are no lines in the input dataset, then the output
     will be an empty :class:`pyvista.PolyData` mesh.
  
  Parameters
  ----------
  width : float, optional
      Set the "half" width of the ribbon. If the width is
      allowed to vary, this is the minimum width. The default is
      10% the length.
  
  scalars : str, optional
      String name of the scalars array to use to vary the ribbon
      width.  This is only used if a scalars array is specified.
  
  angle : float, optional
      Angle in degrees of the offset angle of the ribbon from
      the line normal. The default is 0.0.
  
  factor : float, optional
      Set the maximum ribbon width in terms of a multiple of the
      minimum width. The default is 2.0.
  
  normal : sequence[float], optional
      Normal to use as default.
  
  tcoords : bool, str, optional
      If ``True``, generate texture coordinates along the
      ribbon. This can also be specified to generate the texture
      coordinates with either ``'length'`` or ``'normalized'``.
  
  preference : str, optional
      The field preference when searching for the scalars array by
      name.
  
  progress_bar : bool, default: False
      Display a progress bar to indicate progress.
  
  Returns
  -------
  pyvista.PolyData
      Ribbon mesh.  Empty if there are no lines in the input dataset.
  
  Examples
  --------
  Convert a line to a ribbon and plot it.
  
  >>> import numpy as np
  >>> import pyvista as pv
  >>> n = 1000
  >>> theta = np.linspace(-10 * np.pi, 10 * np.pi, n)
  >>> z = np.linspace(-2, 2, n)
  >>> r = z**2 + 1
  >>> x = r * np.sin(theta)
  >>> y = r * np.cos(theta)
  >>> points = np.column_stack((x, y, z))
  >>> pdata = pv.PolyData(points)
  >>> pdata.lines = np.hstack((n, range(n)))
  >>> pdata['distance'] = range(n)
  >>> ribbon = pdata.ribbon(width=0.2)
  >>> ribbon.plot(show_scalar_bar=False)
docstr_tok: ["Create","a","ribbon","of","the","lines","in","this","dataset",".","..","note",":",":","If","there","are","no","lines","in","the","input","dataset",",","then","the","output","will","be","an","empty",":","class",":","`","pyvista.PolyData","`","mesh",".","Parameters","--","--","--","--","--","width",":","float",",","optional","Set","the","``","half","''","width","of","the","ribbon",".","If","the","width","is","allowed","to","vary",",","this","is","the","minimum","width",".","The","default","is","10","%","the","length",".","scalars",":","str",",","optional","String","name","of","the","scalars","array","to","use","to","vary","the","ribbon","width",".","This","is","only","used","if","a","scalars","array","is","specified",".","angle",":","float",",","optional","Angle","in","degrees","of","the","offset","angle","of","the","ribbon","from","the","line","normal",".","The","default","is","0.0.","factor",":","float",",","optional","Set","the","maximum","ribbon","width","in","terms","of","a","multiple","of","the","minimum","width",".","The","default","is","2.0.","normal",":","sequence","[","float","]",",","optional","Normal","to","use","as","default",".","tcoords",":","bool",",","str",",","optional","If","``","True","``",",","generate","texture","coordinates","along","the","ribbon",".","This","can","also","be","specified","to","generate","the","texture","coordinates","with","either","``","'length","'","``","or","``","'normalized","'","``",".","preference",":","str",",","optional","The","field","preference","when","searching","for","the","scalars","array","by","name",".","progress_bar",":","bool",",","default",":","False","Display","a","progress","bar","to","indicate","progress",".","Returns","--","--","--","-","pyvista.PolyData","Ribbon","mesh",".","Empty","if","there","are","no","lines","in","the","input","dataset",".","Examples","--","--","--","--","Convert","a","line","to","a","ribbon","and","plot","it",".",">",">",">","import","numpy","as","np",">",">",">","import","pyvista","as","pv",">",">",">","n","=","1000",">",">",">","theta","=","np.linspace","(","-10","*","np.pi",",","10","*","np.pi",",","n",")",">",">",">","z","=","np.linspace","(","-2",",","2",",","n",")",">",">",">","r","=","z","*","*","2","+","1",">",">",">","x","=","r","*","np.sin","(","theta",")",">",">",">","y","=","r","*","np.cos","(","theta",")",">",">",">","points","=","np.column_stack","(","(","x",",","y",",","z",")",")",">",">",">","pdata","=","pv.PolyData","(","points",")",">",">",">","pdata.lines","=","np.hstack","(","(","n",",","range","(","n",")",")",")",">",">",">","pdata","[","'distance","'","]","=","range","(","n",")",">",">",">","ribbon","=","pdata.ribbon","(","width=0.2",")",">",">",">","ribbon.plot","(","show_scalar_bar=False",")"]
code: def ribbon(
      self,
      width=None,
      scalars=None,
      angle=0.0,
      factor=2.0,
      normal=None,
      tcoords=False,
      preference="points",
      progress_bar=False,
  ):
      """Create a ribbon of the lines in this dataset.
  
      .. note::
         If there are no lines in the input dataset, then the output
         will be an empty :class:`pyvista.PolyData` mesh.
  
      Parameters
      ----------
      width : float, optional
          Set the "half" width of the ribbon. If the width is
          allowed to vary, this is the minimum width. The default is
          10% the length.
  
      scalars : str, optional
          String name of the scalars array to use to vary the ribbon
          width.  This is only used if a scalars array is specified.
  
      angle : float, optional
          Angle in degrees of the offset angle of the ribbon from
          the line normal. The default is 0.0.
  
      factor : float, optional
          Set the maximum ribbon width in terms of a multiple of the
          minimum width. The default is 2.0.
  
      normal : sequence[float], optional
          Normal to use as default.
  
      tcoords : bool, str, optional
          If ``True``, generate texture coordinates along the
          ribbon. This can also be specified to generate the texture
          coordinates with either ``'length'`` or ``'normalized'``.
  
      preference : str, optional
          The field preference when searching for the scalars array by
          name.
  
      progress_bar : bool, default: False
          Display a progress bar to indicate progress.
  
      Returns
      -------
      pyvista.PolyData
          Ribbon mesh.  Empty if there are no lines in the input dataset.
  
      Examples
      --------
      Convert a line to a ribbon and plot it.
  
      >>> import numpy as np
      >>> import pyvista as pv
      >>> n = 1000
      >>> theta = np.linspace(-10 * np.pi, 10 * np.pi, n)
      >>> z = np.linspace(-2, 2, n)
      >>> r = z**2 + 1
      >>> x = r * np.sin(theta)
      >>> y = r * np.cos(theta)
      >>> points = np.column_stack((x, y, z))
      >>> pdata = pv.PolyData(points)
      >>> pdata.lines = np.hstack((n, range(n)))
      >>> pdata['distance'] = range(n)
      >>> ribbon = pdata.ribbon(width=0.2)
      >>> ribbon.plot(show_scalar_bar=False)
  
      """
      if scalars is not None:
          field = get_array_association(
              self, scalars, preference=preference
          )
      if width is None:
          width = self.length * 0.1
      alg = _vtk.vtkRibbonFilter()
      alg.SetInputDataObject(self)
      alg.SetWidth(width)
      if normal is not None:
          alg.SetUseDefaultNormal(True)
          alg.SetDefaultNormal(normal)
      alg.SetAngle(angle)
      if scalars is not None:
          alg.SetVaryWidth(True)
          alg.SetInputArrayToProcess(
              0, 0, 0, field.value, scalars
          )  # args: (idx, port, connection, field, name)
          alg.SetWidthFactor(factor)
      else:
          alg.SetVaryWidth(False)
      if tcoords:
          alg.SetGenerateTCoords(True)
          if isinstance(tcoords, str):
              if tcoords.lower() == "length":
                  alg.SetGenerateTCoordsToUseLength()
              elif tcoords.lower() == "normalized":
                  alg.SetGenerateTCoordsToNormalizedLength()
          else:
              alg.SetGenerateTCoordsToUseLength()
      else:
          alg.SetGenerateTCoordsToOff()
      _update_alg(alg, progress_bar, "Creating a Ribbon")
      return _get_output(alg)
  
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 36 for calling the PolyDataFilters obj's underlying member method code with example usage: obj.ribbon(width, scalars, angle, factor, normal, tcoords, preference, progress_bar) and returns: _get_output