% -*- latex -*-

\chapter{Provided Filters}
\label{chap:ProvidedFilters}

\index{filter|(}

Filters are functional units that take data as input and write new data as
output. Filters operate on \vtkmcont{DataSet} objects, which are introduced
with the file I/O operations in Chapter~\ref{chap:FileIO} and are described in
more detail in Chapter~\ref{chap:DataSet}. For now we treat
\textidentifier{DataSet} mostly as an opaque object that can be passed
around readers, writers, filters, and rendering units.

\begin{didyouknow}
  The structure of filters in VTK-m is significantly simpler than their
  counterparts in VTK. VTK filters are arranged in a dataflow network
  (a.k.a. a visualization pipeline) and execution management is handled
  automatically. In contrast, VTK-m filters are simple imperative units,
  which are simply called with input data and return output data.
\end{didyouknow}

\VTKm comes with several filters ready for use, and in this chapter we will give a brief overview of these filters.
All \VTKm filters are currently defined in the \vtkmfilter{} namespace.
We group filters based on the type of operation that they do and the shared interfaces that they have.
Later Part~\ref{part:Developing} describes the necessary steps in creating new filters in VTK-m.


\section{Filter Results}
\label{sec:FilterResults}

\index{results|(}
\index{filter!results|(}

When you execute a filter, it returns a \vtkmfilter{Result} object.
The \textidentifier{Result} object contains information about whether the execution was successful and provides the resulting data.
A \textidentifier{Result} object has the following methods.

\begin{description}
\item[\textcode{IsValid}]
  Returns a \textcode{bool} value specifying whether the filter has successfully executed.
\item[\textcode{IsDataSetValid}]
  Returns a \textcode{bool} value specifying whether the filter has produced a data set object.
  If \textcode{true}, then the execution was successful and the data stored in this \textidentifier{Result} is valid.
  If \textcode{false}, then the execution failed, and any attempt at retrieving data from the \textidentifier{Result} will result in an error.
\item[\textcode{GetDataSet}]
  Returns a \textidentifier{DataSet} containing the results of the execution.
  Often, the data set returned is a shallow copy of the input data with the generated data added.
\item[\textcode{IsFieldValid}]
  Returns a \textcode{bool} value specifying whether the filter has succeeded has provided a field that was added to the data.
  Some types of filters, such as the ones documented in Section~\ref{sec:ProvidedFieldFilters}, generate a new field on the data.
  If this is \textcode{true}, then field data is available in addition to the \textidentifier{DataSet}.
\item[\textcode{GetField}]
  Returns the field information in a \vtkmcont{Field} object.
  Field objects are described in Section~\ref{sec:DataSets:Fields}.
  This field is automatically added to the \textidentifier{DataSet} that can be retrieved with \textcode{GetDataSet}, but sometimes it is useful to get the field array independently.
  Not all filters return field information.
  Use \textcode{IsFieldValid} to see if the field data are available.
\item[\textcode{FieldAs}]
  Given a \vtkmcont{ArrayHandle} object, allocates the array and copies the generated field data into it.
  This field is automatically added to the \textidentifier{DataSet} that can be retrieved with \textcode{GetDataSet}, but sometimes it is useful to get the field array independently.
  Not all filters return field information.
  Use \textcode{IsFieldValid} to see if the field data are available.
  \textcode{FieldAs} returns a \textcode{bool} that is set to \textcode{false} rather than throwing an error when the operation fails.
\end{description}

\index{filter!results|)}
\index{results|)}


\section{Field Filters}
\label{sec:ProvidedFieldFilters}

\index{filter!field|(}
\index{field filter|(}

Every \vtkmcont{DataSet} object contains a list of \index{field}
\keyterm{fields}. A field describes some numerical value associated with
different parts of the data set in space. Fields often represent physical
properties such as temperature, pressure, or velocity. \keyterm{Field
  filters} are a class of filters that generate a new field. These new
fields are typically derived from one or more existing fields or point
coordinates on the data set. For example, mass, volume, and density are
interrelated, and any one can be derived from the other two.

All field filters contain an \textcode{Execute} method that takes two
arguments. The first argument is a \vtkmcont{DataSet} object with the input
data. The second argument specifies the field from which to derive a new
field. The field can be specified as either a string naming a field in the
input \textidentifier{DataSet} object, as a \vtkmcont{Field} object, or as
a coordinate system (typically retrived from a \textidentifier{DataSet}
object with the \textcode{GetCoordianteSystem} method). See Sections
\ref{sec:DataSets:Fields} and \ref{sec:DataSets:CoordinateSystems} for more
information on fields and coordinate systems, respectively.

Field filters often need more information than just a data set and a field.
Any additional information is provided using methods in the filter class
that changes the state. These methods are called before \textcode{Execute}.
One such method that all field filters have is
\textcode{SetOutputFieldName}, which specifies the name assigned to the
generated field. If not specified, then the filter will use a default name.

The \textcode{Execute} method returns a \vtkmfilter{Result} object, which contains the state of the execution and the data generated.
\textidentifier{Result} is documented in Section~\ref{sec:FilterResults}.

The following example provides a simple demonstration of using a field
filter. It specifically uses the point elevation filter, which is one of
the field filters.

\vtkmlisting[ex:PointElevation]{Using \textidentifier{PointElevation}, which is a field filter.}{PointElevation.cxx}

\subsection{Cell Average}

\index{cell average|(}
\index{average|(}

\vtkmfilter{CellAverage} is the cell average filter. It will take a data
set with a collection of cells and a field defined on the points of the
data set and create a new field defined on the cells. The values of this
new derived field are computed by averaging the values of the input field
at all the incident points. This is a simple way to convert a point field
to a cell field. Both the input data set and the input field are specified
as arguments to the \textcode{Execute} method.

The default name for the output cell field is the same name as the input
point field. The name can be overridden using the
\textcode{SetOutputFieldName} method.

In addition the standard \textcode{SetOutputFieldName} and
\textcode{Execute} methods, \textidentifier{CellAverage} provides the
following methods.

\begin{description}
\item[\textcode{SetActiveCellSetIndex}] Sets the index for the cell set to use
  from the \textidentifier{DataSet} provided to the \textcode{Execute}
  method. The default index is 0, which is the first cell set. If you want
  to set the active cell set by name, you can use the
  \textidentifier{GetCellSetIndex} method on the \textidentifier{DataSet}
  object that will be used with \textcode{Execute}.
\item[\textcode{GetActiveCellSetIndex}] Returns the index to be used when
  getting a cell set from the \textidentifier{DataSet} passed to
  \textcode{Execute}. Set with \textcode{SetActiveCellSetIndex}.
\end{description}

\index{average|}
\index{cell average|)}

\subsection{Point Average}

\index{point average|(}
\index{average|(}

\vtkmfilter{PointAverage} is the point average filter.
It will take a data set with a collection of cells and a field defined on the cells of the data set and create a new field defined on the points.
The values of this new derived field are computed by averaging the values of the input field at all the incident cells.
This is a simple way to convert a cell field to a point field.
Both the input data set and the input field are specified as arguments to the \textcode{Execute} method.

The default name for the output cell field is the same name as the input point field.
The name can be overridden using the \textcode{SetOutputFieldName} method.

In addition the standard \textcode{SetOutputFieldName} and \textcode{Execute} methods, \textidentifier{PointAverage} provides the following methods.

\begin{description}
\item[\textcode{SetActiveCellSetIndex}]
  Sets the index for the cell set to use from the \textidentifier{DataSet} provided to the \textcode{Execute} method.
  The default index is 0, which is the first cell set.
  If you want to set the active cell set by name, you can use the \textidentifier{GetCellSetIndex} method on the \textidentifier{DataSet} object that will be used with \textcode{Execute}.
\item[\textcode{GetActiveCellSetIndex}]
  Returns the index to be used when getting a cell set from the \textidentifier{DataSet} passed to \textcode{Execute}.
  Set with \textcode{SetActiveCellSetIndex}.
\end{description}

\index{average|}
\index{point average|)}

\subsection{Point Elevation}

\index{point elevation|(}
\index{elevation|(}

\vtkmfilter{PointElevation} computes the ``elevation'' of a field of point
coordinates in space. The filter will take a data set and a field of 3
dimensional vectors and compute the distance along a line defined by a low
point and a high point. Any point in the plane touching the low point and
perpendicular to the line is set to the minimum range value in the
elevation whereas any point in the plane touching the high point and
perpendicular to the line is set to the maximum range value. All other
values are interpolated linearly between these two planes. This filter is
commonly used to compute the elevation of points in some direction, but can
be repurposed for a variety of measures.

The input field (or coordinate system) is specified as the second argument
to the \textcode{Execute} method. A \vtkmcont{DataSet} that is expected to
contain the field is also given but is otherwise unused.
Example~\ref{ex:PointElevation} gives a demonstration of the elevation
filter.

The default name for the output field is ``elevation'', but that can be
overridden using the \textcode{SetOutputFieldName} method.

In addition to the standard \textcode{SetOutputFieldName} and
\textcode{Execute} methods, \textidentifier{PointElevation} provides the
following methods.

\begin{description}
\item[\textcode{SetLowPoint}/\textcode{SetHighPoint}] This pair of methods
  is used to set the low and high points, respectively, of the elevation.
  Each method takes three floating point numbers specifying the $x$, $y$,
  and $z$ components of the low or high point.
\item[\textcode{SetRange}] Sets the range of values to use for the output
  field. This method takes two floating point numbers specifying the low
  and high values, respectively.
\end{description}

\index{elevation|)}
\index{point elevation|)}

\subsection{Surface Normals}

\index{surface normals|(}
\index{normals|(}

\vtkmfilter{SurfaceNormals} computes the surface normals of a polygonal data
set at its points and/or cells. The filter takes a data set as input and by
default, uses the active coordinate system to compute the normals. Optionally,
a coordinate system or a point field of 3d vectors can be explicitly provided
to the \textcode{Execute} method.
The cell normals are computed based on each cell's winding order using vector
cross-product. For non-polygonal cells, a zeroed vector is assigned.
The point normals are computed by averaging the cell normals of the
incident cells of each point.

The default name for the output fields is ``Normals'', but that can be
overriden using the \textcode{SetCellNormalsName} and
\textcode{SetPointNormalsName} methods.

In addition to the standard field filters methods,
\textidentifier{SurfaceNormals} provides the following methods.

\begin{description}
\item[\textcode{SetGenerateCellNormals}/\textcode{GetGenerateCellNormals}]
  These methods can be used to set/get the flag to specify if the cell normals
  should be generated.
\item[\textcode{SetGeneratePointNormals}/\textcode{GetGeneratePointNormals}]
  These methods can be used to set/get the flag to specify if the point normals
  should be generated.
\item[\textcode{SetCellNormalsName}/\textcode{GetCellNormalsName}]
  These methods can be used to set/get the output cell normals field name.
\item[\textcode{SetPointNormalsName}/\textcode{GetPointNormalsName}]
  These methods can be used to set/get the output point normals field name.
\end{description}

\index{normals|)}
\index{surface normals|)}

\subsection{Gradients}

\index{point gradients|(}
\index{cell gradients|(}
\index{gradients|(}

\vtkmfilter{Gradients} computes the gradient of a point based input field for
every element in the input data set. The gradient computation can either generate
cell center based gradients which are fast but less accurate, or more accurate but slower
point based gradients.
The default for the filter is output as cell centered gradients, but can be
changed by using the \textcode{SetComputePointGradient} method.
The default name for the output fields is ``Gradients'', but that can be
overriden using the \textcode{SetOutputFieldName} method.

In addition to the standard field filters methods,
\textidentifier{Gradients} provides the following methods.

\begin{description}
\item[\textcode{SetComputePointGradient}/\textcode{GetComputePointGradient}]
  These methods can be used to change if we are computing point of cell based
  gradients. The output field(s) of this filter will be point based if this
  is enabled.
 \item[\textcode{SetComputeDivergence}/\textcode{GetComputeDivergence}]
  These methods can be used to set/get the flag to specify if the divergence
  filed will be generated. By default the name of the array will be ``Divergence''
  but can be changed by using \textcode{SetDivergenceName}. The field will be a
  cell field unless \textcode{ComputePointGradient} is enabled. The input array
  must have 3 components in order to compute this. The default is off.
\item[\textcode{SetComputeVorticity}/\textcode{GetComputeVorticity}]
  These methods can be used to set/get the flag to specify if the vorticity
  filed will be generated. By default the name of the array will be ``Vorticity''
  but can be changed by using \textcode{SetVorticityName}. The field will be a
  cell field unless \textcode{ComputePointGradient} is enabled. The input array
  must have 3 components in order to compute this. The default is off.
\item[\textcode{SetComputeQCriterion}/\textcode{GetComputeQCriterion}]
  These methods can be used to set/get the flag to specify if the Q-Criterion
  filed will be generated. By default the name of the array will be ``QCriterion''
  but can be changed by using \textcode{SetQCriterionName}. The field will be a
  cell field unless \textcode{ComputePointGradient} is enabled. The input array
  must have 3 components in order to compute this. The default is off.
\item[\textcode{SetComputeGradient}/\textcode{GetComputeGradient}]
  These methods control the ability to write out the actual gradient field.
  When processing fields that have 3 components it is desirable to compute
  information such as Divergence, Vorticity, or Q-Criterion without incurring
  the cost of also having to write out the 3x3 gradient result. 
  The default is on.
\item[\textcode{SetColumnMajorOrdering}/\textcode{SetRowMajorOrdering}]
  When processing input fields that have 3 components, the output will be a
  a 3x3 gradient. By default VTK-m outputs all matrix like arrays in Row Major
  ordering (C-Ordering). When integrating with libraries like VTK or with 
  FORTRAN codes which use Column Major ordering.
  The default is Row Major.
  This setting is only relevant for 3 component input fields when
  \textcode{SetComputeGradient} is enabled.
\item[\textcode{SetDivergenceName}/\textcode{GetDivergenceName}]
  These methods can be used to set/get the output cell normals field name. The
  default is ``Divergence''.
\item[\textcode{SetVorticityName}/\textcode{GetVorticityName}]
  These methods can be used to set/get the output Vorticity field name. The 
  default is ``Vorticity''
\item[\textcode{SetQCriterionName}/\textcode{GetQCriterionName}]
  These methods can be used to set/get the output Q-Criterion field name. The
  default is ``QCriterion''.
\end{description}
  
\index{point gradients|)}
\index{cell gradients|)}
\index{gradients|)}


\subsection{Cross Product}

\index{cross product|(}

\vtkmfilter{CrossProduct} computes the cross product of two vector fields for every element
in the input data set.
The cross product filter computes (PrimaryField $\times$ SecondaryField),
where the PrimaryField is specified as an argument in the invocation of the filter,
and the SecondaryVariable is specified with a method call on the filter.
The cross product computation works for both point and cell centered
vector fields.

In addition to the standard field filters methods,
\textidentifier{CrossProduct} provides the following methods.

\begin{description}
\item[\textcode{SetSecondaryField}]
  This method is used to set the secondary vector field used in the cross
  product computation.
\end{description}
  
\index{cross product|)}

\subsection{Dot Product}

\index{dot product|(}

\vtkmfilter{DotProduct} computes the dot product of two vector fields for every element
in the input data set.
The cross product filter computes (PrimaryField $\cdot$ SecondaryField),
where the PrimaryField is specified as an argument in the invocation of the filter,
and the SecondaryVariable is specified with a method call on the filter.
The dot product computation works for both point and cell centered
vector fields.

In addition to the standard field filters methods,
\textidentifier{DotProduct} provides the following methods.

\begin{description}
\item[\textcode{SetSecondaryFieldName}]  
  This method is used to set the secondary vector field used in the dot
  product computation.
\end{description}
  
\index{dot product|)}


\index{field filter|)}
\index{filter!field|)}


\section{Data Set Filters}
\label{sec:ProvidedDataSetFilters}

\index{filter!data set|(}
\index{data set filter|(}

\keyterm{Data set filters} are a class of filters that generate a new data
set with a new topology. This new topology is typically derived from an
existing data set. For example, a data set can be significantly altered by
adding, removing, or replacing cells.

All data set filters contain an \textcode{Execute} method that takes one
argument: a \vtkmcont{DataSet} object with the input data.

Some data set filters need more information that just a data set when
executing. Any additional information is provided using methods in the
filter class that changes the state. These methods are called before
\textcode{Execute}. One such method that all data set filters have is
\textcode{SetActiveCellSetIndex}, which selects which cell set in the input
\textidentifier{DataSet} to operate on. Likewise,
\textcode{SetActiveCoordinateSystem} selects which coordinate system to
operate on. By default, the filter will operate on the first cell set and
coordinate system. (See Sections \ref{sec:DataSets:CellSets} and
\ref{sec:DataSets:CoordinateSystems} for more information about cell sets
and coordinate systems, respectively.)

The \textcode{Execute} method returns a \vtkmfilter{Result} object, which contains the state of the execution and the data generated.
\textidentifier{Result} is documented in Section~\ref{sec:FilterResults}.

Because the new data set is derived from existing data, it can often
inherit field information from the original data. All data set filters also
contain a \textcode{MapFieldOntoOutput} method to map fields from the
output to the input. This method takes two arguments. The first argument is
the \textidentifier{Result} object returned from the last call to
\textcode{Execute}. The second argument is a \vtkmcont{Field} object that
comes from the input. \textcode{MapFieldOntoOutput} returns a
\textcode{bool} that is true if the field was successfully mapped and added
to the output data set in the \textidentifier{Result} object.

\begin{commonerrors}
  Not all data set filters support the mapping of all input fields to the
  output. If the mapping is not supported, \textcode{MapFieldOntoOutput}
  will simply return false.
\end{commonerrors}

The following example provides a simple demonstration of using a data set
filter. It specifically uses the vertex clustering filter, which is one of
the data set filters.

\vtkmlisting[ex:VertexClustering]{Using \textidentifier{VertexClustering},
  which is a data set filter.}{VertexClustering.cxx}

\subsection{Clean Grid}

\index{clean grid|(}
\index{data set!clean|(}

\vtkmfilter{CleanGrid} is a filter that converts a cell set to an explicit representation and potentially removes redundant or unused data.
It does this by iterating over all cells in the data set, and for each one creating the explicit cell representation that is stored in the output.
(Explicit cell sets are described in Section~\ref{sec:ExplicitCellSets}.)
One benefit of using \textidentifier{CleanGrid} is that it can optionally remove unused points\fix{ and combine coincident points when implemented}.
Another benefit is that the resulting cell set will be of a known specific type.

\begin{commonerrors}
  The result of \vtkmfilter{CleanGrid} is not necessarily smaller, memory-wise, than its input.
  For example, ``cleaning'' a data set with a structured topology will actually result in a data set that requires much more memory to store an explicit topology.
\end{commonerrors}

In addition to the standard \textcode{Execute},
\textcode{MapFieldOntoOutput}, and other methods,
\textidentifier{CleanGrid} provides the following methods.

\begin{description}
\item[\textcode{SetCompactPointFields}]
  Sets a Boolean flag that determines whether unused points are removed from the output.
  If true (the default), then the output data set will have a new coordinate system containing only those points being used by the cell set, and the indices of the cells will be adjusted to the new ordering of points.
  If false, then the output coordinate systems will be a shallow copy of the input coordinate systems.
\item[\textcode{GetCompactPointFields}]
  Returns the Boolean flag set in the latest call to \textcode{SetCompactPointFields}.
\end{description}

\index{data set!clean|)}
\index{clean grid|)}

\subsection{External Faces}

\index{external faces|(}
\index{face!external|(}

\vtkmfilter{ExternalFaces} is a filter that extracts all the external faces
from a polyhedral data set. An external face is any face that is on the
boundary of a mesh. Thus, if there is a hole in a volume, the boundary of
that hole will be considered external. More formally, an external face is
one that belongs to only one cell in a mesh.

The external faces filter has no extra methods beyond the base methods of
data set filters (such as \textcode{Execute} and
\textcode{MapFieldOntoOutput}) because it requires no further metadata for
its operations.

\index{face!external|)}
\index{external faces|)}

\subsection{Vertex Clustering}

\index{vertex clustering|(}
\index{surface simplification|(}

\vtkmfilter{VertexClustering} is a filter that simplifies a polygonal mesh.
It does so by dividing space into a uniform grid of bin and then merges
together all points located in the same bin. The smaller the dimensions of
this binning grid, the fewer polygons will be in the output cells and the
coarser the representation. This surface simplification is an important
operation to support \index{level of detail}\index{LOD}level of detail (LOD)
rendering in visualization applications. Example~\ref{ex:VertexClustering}
provides a demonstration of the vertex clustering filter.

In addition to the standard \textcode{Execute},
\textcode{MapFieldOntoOutput}, and other methods,
\textidentifier{VertexClustering} provides the following methods.

\begin{description}
\item[\textcode{SetNumberOfDivisions}] Set the dimensions of the uniform
  grid that establishes the bins used for clustering. Setting smaller
  numbers of dimensions produces a smaller output, but with a coarser
  representation of the surface. The dimensions are provided as a
  \vtkm{Id3}.
\item[\textcode{GetNumberOfDimensions}] Returns the number of dimensions
  used for binning. The dimensions are returned as a \vtkm{Id3}.
\end{description}

\index{surface simplification|}
\index{vertex clustering|)}

\index{data set filter|)}
\index{filter!data set|)}


\section{Data Set with Field Filters}
\label{sec:ProvidedDataSetWithFieldFilters}

\index{filter!data set with field|(}
\index{data set with filter|(}

\keyterm{Data set with field filters} are a class of filters that generate a
new data set with a new topology. This new topology is derived from an
existing data set and at least one of the fields in the data set. For
example, a field might determine how each cell is culled, clipped, or
sliced.

All data set with field filters contain an \textcode{Execute} method that
takes two arguments. The first argument is a \vtkmcont{DataSet} object with
the input data. The second argument specifies the field from which to
derive a new field. The field can be specified as either a string naming a
field in the input \textidentifier{DataSet} object, as a \vtkmcont{Field}
object, or as a coordinate system (typically retrieved from a
\textidentifier{DataSet} object with the \textcode{GetCoordianteSystem}
method). See Sections \ref{sec:DataSets:Fields} and
\ref{sec:DataSets:CoordinateSystems} for more information on fields and
coordinate systems, respectively.

Some data set filters need more information that just a data set when
executing. Any additional information is provided using methods in the
filter class that changes the state. These methods are called before
\textcode{Execute}. One such method that all data set filters have is
\textcode{SetActiveCellSetIndex}, which selects which cell set in the input
\textidentifier{DataSet} to operate on. Likewise,
\textcode{SetActiveCoordinateSystem} selects which coordinate system to
operate on. By default, the filter will operate on the first cell set and
coordinate system. (See Sections \ref{sec:DataSets:CellSets} and
\ref{sec:DataSets:CoordinateSystems} for more information about cell sets
and coordinate systems, respectively.)

The \textcode{Execute} method returns a \vtkmfilter{Result} object, which contains the state of the execution and the data generated.
\textidentifier{Result} is documented in Section~\ref{sec:FilterResults}.

Because the new data set is derived from existing data, it can often
inherit field information from the original data. All data set filters also
contain a \textcode{MapFieldOntoOutput} method to map fields from the
output to the input. This method takes two arguments. The first argument is
the \textidentifier{Result} object returned from the last call to
\textcode{Execute}. The second argument is a \vtkmcont{Field} object that
comes from the input. \textcode{MapFieldOntoOutput} returns a
\textcode{bool} that is true if the field was successfully mapped and added
to the output data set in the \textidentifier{Result} object.

\begin{commonerrors}
  Not all data set filters support the mapping of all input fields to the
  output. If the mapping is not supported, \textcode{MapFieldOntoOutput}
  will simply return false.
\end{commonerrors}

The following example provides a simple demonstration of using a data set
with field filter. It specifically uses the Marching Cubes filter, which is
one of the data set with field filters.

\vtkmlisting[ex:MarchingCubes]{Using \textidentifier{MarchingCubes},
  which is a data set with field filter.}{MarchingCubes.cxx}

\subsection{Marching Cubes}

\index{filter!Marching Cubes|(}
\index{filter!contour|(}
\index{filter!isosurface|(}
\index{Marching Cubes|(}
\index{contour|(}
\index{isosurface|(}

\keyterm{Contouring} is one of the most fundamental filters in scientific
visualization. A contour is the locus where a field is equal to a
particular value. A topographic map showing curves of various elevations
often used when hiking in hilly regions is an example of contours of an
elevation field in 2 dimensions. Extended to 3 dimensions, a contour gives
a surface. Thus, a contour is often called an \keyterm{isosurface}.
Marching Cubes is a well know algorithm for computing contours and is
implemented by \vtkmfilter{MarchingCubes}. Example~\ref{ex:MarchingCubes}
provides a demonstration of the Marching Cubes filter.

In addition to the standard \textcode{Execute},
\textcode{MapFieldOntoOutput}, and other methods,
\textidentifier{MarchingCubes} provides the following methods.

\begin{description}
\item[\textcode{SetIsoValue}] Provide the value on which to extract the
  contour. The contour will be the surface where the field (provided to
  \textcode{Execute}) is equal to this value.
\item[\textcode{GetIsoValue}] Retrieve the currently set iso value.
\item[\textcode{SetMergeDuplicatePoints}] Sets a Boolean flag to determine
  whether coincident points in the data set should be merged. Because the
  Marching Cubes filter (like all filters in VTK-m) runs in parallel,
  parallel threads can (and often do) create duplicate versions of points.
  When this flag is set to true, a secondary operation will find all
  duplicated points and combine them together.
\item[\textcode{GetMergeDuplicatePoints}] Returns the merge duplicate
  points flag.
\item[\textcode{SetGenerateNormals}] Sets a Boolean flag to determine
  whether to generate normal vectors for the surface. Normals are used in
  shading calculations during rendering and can make the surface appear
  more smooth. By default, the generated normals are based on the gradient
  of the field being contoured and can be quite expensive to compute. A faster
  method is available that computes the normals based on the faces of the
  isosurface mesh, but the normals do not look as good as the gradient based
  normals. Fast normals can be enabled using the flags described bellow.
\item[\textcode{GetGenerateNormals}] Returns the generate normals flag.
\item[\textcode{SetComputeFastNormalsForStructured}] Sets a Boolean flag to
  use the fast method of normals computation for Structured datasets. This
  is only valid if the generate normals flag is set.
\item[\textcode{GetComputeFastNormalsForStructured}] Returns the value of
  the \textcode{ComputeFastNormalsForStructured} flag.
\item[\textcode{SetComputeFastNormalsForUnstructured}] Sets a Boolean flag to
  use the fast method of normals computation for unstructured datasets. This
  is only valid if the generate normals flag is set.
\item[\textcode{GetComputeFastNormalsForUnstructured}] Returns the value of
  the \textcode{ComputeFastNormalsForUnstructured} flag.
\end{description}

\index{isosurface|)}
\index{contour|)}
\index{Marching Cubes|)}
\index{filter!isosurface|)}
\index{filter!contour|)}
\index{filter!Marching Cubes|)}

\subsection{Threshold}

\index{filter!threshold|(}
\index{threshold|(}

A threshold operation removes topology elements from a data set that do not
meet a specified criterion. The \vtkmfilter{Threshold} filter removes all
cells where the field (provided to \textcode{Execute}) is not between a
range of values.

In addition to the standard \textcode{Execute},
\textcode{MapFieldOntoOutput}, and other methods,
\textidentifier{Threshold} provides the following methods.

\begin{description}
\item[\textcode{SetLowerThreshold}] Sets the lower scalar value. Any cells
  where the scalar field is less than this value are removed.
\item[\textcode{SetUpperThreshold}] Sets the upper scalar value. Any cells
  where the scalar field is more than this value are removed.
\item[\textcode{GetLowerThreshold}] Returns the lower threshold value.
\item[\textcode{GetUpperThreshold}] Returns the upper threshold value.
\end{description}

\index{threshold|)}
\index{filter!threshold|)}

\subsection{Streamlines}

\index{filter!streamlines|(}
\index{streamlines|(}

\keyterm{Streamlines} are a powerful technique for the visualization of flow fields.
A streamline is a curve that is parallel to the velocity vector of the flow field.
Individual streamlines are computed from an initial point location (seed) using a numerical
method to integrate the point through the flow field.

In addition to the standard \textcode{Execute} method,
\vtkmfilter{Streamline} provides the following methods.


\begin{description}
\item[\textcode{SetSeeds}] Set the seed locations for the streamlines.
\item[\textcode{SetStepSize}] Set the step size used for the numerical integrator ($4^{th}$ order Runge-Kutta method)
  to integrate the seed locations through the flow field.
\item[\textcode{SetNumberOfSteps}] Set the number of integration steps to be performed on each streamline.
\end{description}

\vtkmlisting[ex:Streamlines]{Using \textidentifier{Streamline}, which is a data set with field filter.}{Streamlines.cxx}


\index{streamlines|)}
\index{filter!streamline|)}

\index{data set with filter|)}
\index{filter!data set with field|)}


\index{filter|)}
