% -*- latex -*-

\chapter{Running Filters}
\label{chap:RunningFilters}

\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.

\newcommand{\commonfiltermethods}{
\item[\textcode{Execute}]
  Takes a data set, executes the filter on a device, and returns a data set that contains the result.
\item[\textcode{SetFieldsToPass}/\textcode{GetFieldsToPass}]
  Specifies which fields to pass from input to output.
  By default all fields are passed.
  See Section~\ref{sec:FilterPassingFields} for more details.
}


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

\newcommand{\commonfieldfiltermethods}{
\item[\textcode{SetActiveField}/\textcode{GetActiveFieldName}]
  Specifies the name of the field to use as input.
\item[\textcode{SetUseCoordinateSystemAsField}/\textcode{GetUseCoordinateSystemAsField}]
  Specifies a Boolean flag that determines whether to use point coordinates as the input field.
  Set to false by default.
  When true, the values for the active field are ignored.
\item[\textcode{SetActiveCoordinateSystem}/\textcode{GetActiveCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use as the input field.
  The default index is 0, which is the first coordinate system.
\item[\textcode{SetOutputFieldName}/\textcode{GetOutputFieldName}]
  Specifies the name of the output field generated.
  \commonfiltermethods
}

\newcommand{\commoncellfieldfiltermethods}{
\item[\textcode{SetActiveCellSetIndex}/\textcode{GetActiveCellSetIndex}]
  Specifies the index for the cell set to use from the data set provided to the \textcode{Execute} method.
  The default index is 0, which is the first cell set.
  \commonfieldfiltermethods
}

\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.

Before a filter is run, it is important to set up the state of the filter object to the parameters of the algorithm.
The state parameters will vary from one filter to the next, but one state parameter that all field filters share is the ``active'' field for the operation.
The active field is set with a call to the \classmember*{FilterField}{SetActiveField} method.
The argument to \classmember*{FilterField}{SetActiveField} is a string that names this input field.
Alternatively, you can call the \classmember*{FilterField}{SetUseCoordinateSystemAsField} with an argument of \textcode{true} to use the point coordinates as the input field rather than a specified field.
See Sections \ref{sec:DataSets:Fields} and \ref{sec:DataSets:CoordinateSystems} for more information on fields and coordinate systems, respectively.
Finally, \classmember*{FilterField}{SetOutputFieldName}, specifies the name assigned to the generated field.
If not specified, then the filter will use a default name.

All field filters contain an \classmember*{FilterField}{Execute} method.
When calling \classmember*{FilterField}{Execute} a \vtkmcont{DataSet} or \vtkmcont{MultiBlock} object with the input data is provided as an argument.
The \classmember*{FilterField}{Execute} method returns a \textidentifier{DataSet} or \textidentifier{MultiBlock} object (matching the type of the input to \classmember*{FilterField}{Execute}), which contains the data generated.

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.

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

\textidentifier{CellAverage} provides the following methods.

\begin{description}
  \commoncellfieldfiltermethods
\end{description}

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


\subsection{Coordinate System Transforms}

\index{coordinate system transform|(}

\VTKm provides multiple filters to translate between different coordiante systems.

\subsubsection{Cylindrical Coordinate System Transform}

\index{cylindrical coordinate system transform|(}
\index{coordinate system transform!cylindrical|(}

\vtkmfilter{CylindricalCoordinateSystemTransform} is a coordinate system transformation filter.
The filter will take a data set and transform the points of the coordinate system. By default,
the filter will transform the coordinates from a cartesian coordinate system to a cylindrical coordinate system.
The order for cylindrical coordinates is $(R,\theta, Z)$


The default name for the output field is ``cylindricalCoordinateSystemTransform'', but that can be
overridden as always using the \classmember*{FilterField}{SetOutputFieldName} method.

In addition the standard \classmember*{FilterField}{SetOutputFieldName} and \classmember*{FilterField}{Execute} methods, \textidentifier{CylindricalCoordinateSystemTransform} provides the following methods.

\begin{description}
\item[\classmember*{CylindricalCoordinateSystemTransform}{SetCartesianToCylindrical}]
  This method specifies a transformation from cartesian to cylindrical coordinates.
\item[\classmember*{CylindricalCoordinateSystemTransform}{SetCylindricalToCartesian}]
  This method specifies a transformation from cylindrical to cartesian coordinates.
  \commoncellfieldfiltermethods
\end{description}

\index{coordinate system transform!cylindrical|)}
\index{cylindrical coordinate system transform|)}

\subsubsection{Spherical Coordinate System Transform}

\index{spherical coordinate system transform|(}
\index{coordinate system transform!spherical|(}

\vtkmfilter{SphericalCoordinateSystemTransform} is a coordinate system transformation filter.
The filter will take a data set and transform the points of the coordinate system. By default,
the filter will transform the coordinates from a cartesian coordinate system to a spherical coordinate system.
The order for spherical coordinates is $(R,\theta, \phi)$

The default name for the output field is ``sphericalCoordinateSystemTransform'', but that can be
overridden as always using the \classmember*{FilterField}{SetOutputFieldName} method.

In addition the standard \classmember*{FilterField}{SetOutputFieldName} and \classmember*{FilterField}{Execute} methods, \textidentifier{CylindricalCoordinateSystemTransform} provides the following methods.

\begin{description}
\item[\classmember*{CylindricalCoordinateSystemTransform}{SetCartesianToSpherical}]
  This method specifies a transformation from cartesian to spherical coordinates.
\item[\classmember*{CylindricalCoordinateSystemTransform}{SetSphericalToCartesian}]
  This method specifies a transformation from spherical to cartesian coordinates.
  \commoncellfieldfiltermethods
\end{description}

\index{coordinate system transform!spherical|)}
\index{cylindrical coordinate system transform|)}

\index{coordinate system transform|)}


\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 both the primary and secondary field are specified using methods on the \textidentifier{CrossProduct} class.
The cross product computation works for both point and cell centered vector fields.

\textidentifier{CrossProduct} provides the following methods.

\begin{description}
\item[\classmember*{CrossProduct}{SetPrimaryField}/\classmember*{CrossProduct}{GetPrimaryFieldName}]
  Specifies the name of the field to use as input for the primary (first) value of the cross product.
\item[\classmember*{CrossProduct}{SetUseCoordinateSystemAsPrimaryField}/\classmember*{CrossProduct}{GetUseCoordinateSystemAsPrimaryField}]
  Specifies a Boolean flag that determines whether to use point coordinates as the primary input field.
  Set to false by default.
  When true, the name for the primary field is ignored.
\item[\classmember*{CrossProduct}{SetPrimaryCoordinateSystem}/\classmember*{CrossProduct}{GetPrimaryCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use as the primary input field.
  The default index is 0, which is the first coordinate system.
\item[\classmember*{CrossProduct}{SetSecondaryField}/\classmember*{CrossProduct}{GetSecondaryFieldName}]
  Specifies the name of the field to use as input for the secondary (second) value of the cross product.
\item[\classmember*{CrossProduct}{SetUseCoordinateSystemAsSecondaryField}/\classmember*{CrossProduct}{GetUseCoordinateSystemAsSecondaryField}]
  Specifies a Boolean flag that determines whether to use point coordinates as the secondary input field.
  Set to false by default.
  When true, the name for the secondary field is ignored.
\item[\classmember*{CrossProduct}{SetSecondaryCoordinateSystem}/\classmember*{CrossProduct}{GetSecondaryCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use as the secondary input field.
  The default index is 0, which is the first coordinate system.
\item[\classmember*{CrossProduct}{SetOutputFieldName}/\classmember*{CrossProduct}{GetOutputFieldName}]
  Specifies the name of the output field generated.
  \commonfiltermethods
\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 dot product filter computes (PrimaryField $\cdot$ SecondaryField), where both the primary and secondary field are specified using methods on the \textidentifier{DotProduct} class.
The dot product computation works for both point and cell centered vector fields.

\textidentifier{DotProduct} provides the following methods.

\begin{description}
\item[\classmember*{DotProduct}{SetPrimaryField}/\classmember*{DotProduct}{GetPrimaryFieldName}]
  Specifies the name of the field to use as input for the primary (first) value of the dot product.
\item[\classmember*{DotProduct}{SetUseCoordinateSystemAsPrimaryField}/\classmember*{DotProduct}{GetUseCoordinateSystemAsPrimaryField}]
  Specifies a Boolean flag that determines whether to use point coordinates as the primary input field.
  Set to false by default.
  When true, the name for the primary field is ignored.
\item[\classmember*{DotProduct}{SetPrimaryCoordinateSystem}/\classmember*{DotProduct}{GetPrimaryCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use as the primary input field.
  The default index is 0, which is the first coordinate system.
\item[\classmember*{DotProduct}{SetSecondaryField}/\classmember*{DotProduct}{GetSecondaryFieldName}]
  Specifies the name of the field to use as input for the secondary (second) value of the dot product.
\item[\classmember*{DotProduct}{SetUseCoordinateSystemAsSecondaryField}/\classmember*{DotProduct}{GetUseCoordinateSystemAsSecondaryField}]
  Specifies a Boolean flag that determines whether to use point coordinates as the secondary input field.
  Set to false by default.
  When true, the name for the secondary field is ignored.
\item[\classmember*{DotProduct}{SetSecondaryCoordinateSystem}/\classmember*{DotProduct}{GetSecondaryCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use as the secondary input field.
  The default index is 0, which is the first coordinate system.
\item[\classmember*{DotProduct}{SetOutputFieldName}/\classmember*{DotProduct}{GetOutputFieldName}]
  Specifies the name of the output field generated.
  \commonfiltermethods
\end{description}

\index{dot product|)}

\subsection{Connected Components}

\index{connected components|(}

Connected components in a mesh are groups of mesh elements that are connected together in some way.
For example, if two cells are neighbors, then they are in the same component.
Likewise, a cell is also in the same component as its neighbor's neighbors as well as their neighbors and so on.
Connected components help identify when features in a simulation fragment or meld.

\VTKm provides two types of connected components filters.
The first filter follows topological connections to find cells that are literally connected together.
The second filter takes a structured cell set and a field that classifies each cell and finds connected components where all the cells have the same field value.

\subsubsection{Cell Connectivity}

\index{connected components!cell|(}

The \vtkmfilter{CellSetConnectivity} filter finds groups of cells that are connected together through their topology.
Two cells are considered connected if they share an edge.
\textidentifier{CellSetConnectivity} identifies some number of components and assigns each component a unique integer.

The result of the filter is a cell field of type \vtkm{Id}.
Each entry in the cell field will be a number that identifies to which component the cell belongs.
By default, this output cell field is named ``component''.
Although an input field can be specified, it is ignored.

\textidentifier{CellSetConnectivity} provides the following methods.

\begin{description}
  \commoncellfieldfiltermethods
\end{description}

\index{connected components!cell|)}

\subsubsection{Image Field}

\index{connected components!image|(}
\index{connected components!field|(}

The \vtkmfilter{ImageConnectivity} filter finds groups of points that have the same field value and are connected together through their topology.
Any point is considered to be connected to its Moore neighborhood: 8 neighboring points for 2D and 27 neighboring points for 3D.
As the name implies, \textidentifier{ImageConnectivity} only works on data with a structured cell set.
You will get an error if you use any other type of cell set.

The active field passed to the filter must be associated with the points.

The result of the filter is a point field of type \vtkm{Id}.
Each entry in the point field will be a number that identifies to which component the cell belongs.
By default, this output point field is named ``component''.

\textidentifier{ImageConnectivity} provides the following methods.

\begin{description}
  \commoncellfieldfiltermethods
\end{description}

\index{connected components!field|)}
\index{connected components!image|)}

\index{connected components|)}

\subsection{Field to Colors}

\index{field to colors|(}

\vtkmfilter{FieldToColors} takes a field in a data set, looks up each value in a color table, and writes the resulting colors to a new field.
The color to be used for each field value is specified using a \vtkmcont{ColorTable} object.
\textidentifier{ColorTable} objects are also used with \VTKm's rendering module and are described in Section~\ref{sec:ColorTables}.

\textidentifier{FieldToColors} has three modes it can use to select how it should treat the input field.
\begin{description}
\item[{\classmember{FieldToColors}{SCALAR}}]
  Treat the field as a scalar field.
  It is an error to a field of any type that cannot be directly converted to a basic floating point number (such as a vector).
\item[{\classmember{FieldToColors}{MAGNITUDE}}]
  Given a vector field, take the magnitude of each field value before looking it up in the color table.
\item[{\classmember{FieldToColors}{COMPONENT}}]
  Select a particular component of the vectors in a field to map to colors.
\end{description}

Additionally, \textidentifier{FieldToColors} has different modes in which it can represent colors in its output.
\begin{description}
\item[{\classmember{FieldToColors}{RGB}}]
  Output colors are represented as RGB values with each component represented by an unsigned byte.
  Specifically, these are \vtkm{Vec}\tparams{\vtkm{UInt8},3} values.
\item[{\classmember{FieldToColors}{RGBA}}]
  Output colors are represented as RGBA values with each component represented by an unsigned byte.
  Specifically, these are \vtkm{Vec}\tparams{\vtkm{UInt8},4} values.
\end{description}

\textidentifier{FieldToColors} provides the following methods.

\begin{description}
\item[\classmember*{FieldToColors}{SetColorTable}/\classmember*{FieldToColors}{GetColorTable}]
  Specifies the \vtkmcont{ColorTable} object to use to map field values to colors.
\item[\classmember*{FieldToColors}{SetMappingMode}/\classmember*{FieldToColors}{GetMappingMode}]
  Specifies the input mapping mode.
  The value is one of the \classmember{FieldToColors}{SCALAR}, \classmember{FieldToColors}{MAGNITUDE}, or \classmember{FieldToColors}{COMPONENT} selectors described previously.
\item[\classmember*{FieldToColors}{SetMappingToScalar}]
  Sets the input mapping mode to scalar.
  Shortcut for \classmember*{FieldToColors}{SetMappingMode}\textcode{(}\vtkmfilter{FieldToColors}[SCALAR]\textcode{)}.
\item[\classmember*{FieldToColors}{SetMappingToMagnitude}]
  Sets the input mapping mode to vector.
  Shortcut for \classmember*{FieldToColors}{SetMappingMode}\textcode{(}\vtkmfilter{FieldToColors}[MAGNITUDE]\textcode{)}.
\item[\classmember*{FieldToColors}{SetMappingToComponent}]
  Sets the input mapping mode to component.
  Shortcut for \classmember*{FieldToColors}{SetMappingMode}\textcode{(}\vtkmfilter{FieldToColors}[COMPONENT]\textcode{)}.
\item[\classmember*{FieldToColors}{IsMappingScalar}]
  Returns true if the input mapping mode is scalar (\classmember*{FieldToColors}{FieldToColors}{SCALAR}).
\item[\classmember*{FieldToColors}{IsMappingMagnitude}]
  Returns true if the input mapping mode is magnitude (\classmember{FieldToColors}{MAGNITUDE}).
\item[\classmember*{FieldToColors}{IsMappingComponent}]
  Returns true if the input mapping mode is component (\classmember{FieldToColors}{COMPONENT}).
\item[\classmember*{FieldToColors}{SetMappingComponent}/\classmember*{FieldToColors}{GetMappingComponent}]
  Specifies the component of the vector to use in the mapping.
  This only has an effect if the input mapping mode is set to \classmember{FieldToColors}{COMPONENT}.
\item[\classmember*{FieldToColors}{SetOutputMode}/\classmember*{FieldToColors}{GetOutputMode}]
  Specifies the output representation of colors.
  The value is one of the \classmember{FieldToColors}{RGB} or \classmember{FieldToColors}{RGBA} selectors described previously.
\item[\classmember*{FieldToColors}{SetOutputToRGB}]
  Sets the output representation to 8-bit RGB.
  Shortcut for \classmember*{FieldToColors}{SetOutputMode}\textcode{(}\vtkmfilter{FieldToColors}[RGB]\textcode{)}.
\item[\classmember*{FieldToColors}{SetOutputToRGBA}]
  Sets the output representation to 8-bit RGBA.
  Shortcut for \classmember*{FieldToColors}{SetOutputMode}\textcode{(}\vtkmfilter{FieldToColors}[RGBA]\textcode{)}.
\item[\classmember*{FieldToColors}{IsOutputRGB}]
  Returns true if the output representation is 8-bit RGB (\classmember{FieldToColors}{RGB}).
\item[\classmember*{FieldToColors}{IsOutputRGBA}]
  Returns true if the output representation is 8-bit RGBA (\classmember{FieldToColors}{RGBA}).
\item[\classmember*{FieldToColors}{SetNumberOfSamplingPoints}/\classmember*{FieldToColors}{GetNumberOfSamplingPoints}]
  Specifies how many samples to use when looking up color values.
  The implementation of \textidentifier{FieldToColors} first builds an array of color samples to quickly look up colors for particular values.
  The size of this lookup array can be adjusted with this parameter.
  By default, an array of 256 colors is used.
  \commonfieldfiltermethods
\end{description}

\index{field to colors|)}

\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 \classmember*{Gradients}{SetComputePointGradient} method.
The default name for the output fields is ``Gradients'', but that can be
overriden as always using the \classmember*{Gradients}{SetOutputFieldName} method.

\textidentifier{Gradients} provides the following methods.

\begin{description}
\item[\classmember*{Gradients}{SetComputePointGradient}/\classmember*{Gradients}{GetComputePointGradient}]
  Specifies whether we are computing point or cell based gradients.
  The output field(s) of this filter will be point based if this is enabled.
\item[\classmember*{Gradients}{SetComputeDivergence}/\classmember*{Gradients}{GetComputeDivergence}]
  Specifies whether the divergence field will be generated.
  By default the name of the array will be ``Divergence'' but can be changed by using \classmember*{Gradients}{SetDivergenceName}.
  The field will be a cell field unless \classmember*{Gradients}{ComputePointGradient} is enabled.
  The input array must have 3 components in order to compute this.
  The default is off.
\item[\classmember*{Gradients}{SetComputeVorticity}/\classmember*{Gradients}{GetComputeVorticity}]
  Specifies whether the vorticity field will be generated.
  By default the name of the array will be ``Vorticity'' but can be changed by using \classmember*{Gradients}{SetVorticityName}.
  The field will be a cell field unless \classmember*{Gradients}{ComputePointGradient} is enabled.
  The input array must have 3 components in order to compute this.
  The default is off.
\item[\classmember*{Gradients}{SetComputeQCriterion}/\classmember*{Gradients}{GetComputeQCriterion}]
  Specifies whether the Q-Criterion field will be generated.
  By default the name of the array will be ``QCriterion'' but can be changed by using \classmember*{Gradients}{SetQCriterionName}.
  The field will be a cell field unless \classmember*{Gradients}{ComputePointGradient} is enabled.
  The input array must have 3 components in order to compute this.
  The default is off.
\item[\classmember*{Gradients}{SetComputeGradient}/\classmember*{Gradients}{GetComputeGradient}]
  Specifies whether the actual gradient field is written to the output.
  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[\classmember*{Gradients}{SetColumnMajorOrdering}/\classmember*{Gradients}{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).
  The ordering can be changed when integrating with libraries like VTK or with FORTRAN codes that use Column Major ordering.
  The default is Row Major.
  This setting is only relevant for 3 component input fields when \classmember*{Gradients}{SetComputeGradient} is enabled.
\item[\classmember*{Gradients}{SetDivergenceName}/\classmember*{Gradients}{GetDivergenceName}]
  Specifies the output cell normals field name.
  The default is ``Divergence''.
\item[\classmember*{Gradients}{SetVorticityName}/\classmember*{Gradients}{GetVorticityName}]
  Specifies the output Vorticity field name.
  The default is ``Vorticity''
\item[\classmember*{Gradients}{SetQCriterionName}/\classmember*{Gradients}{GetQCriterionName}]
  Specifies the output Q-Criterion field name.
  The default is ``QCriterion''.
  \commoncellfieldfiltermethods
\end{description}

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


\subsection{Histogram}

\index{histogram|(}

\vtkmfilter{Histogram} computes a histogram of a given field.

The default number of bins in the output histogram is 10, but that
can be overridden using the \classmember*{Histogram}{SetNumberOfBins} method.

The default name for the output fields is ``histogram''.
The name can be overridden as always using the \classmember*{Histogram}{SetOutputFieldName} method.

\textidentifier{Histogram} provides the following methods.

\begin{description}
\item[\classmember*{Histogram}{SetRange}/\classmember*{Histogram}{GetRange}]
  Specifies an explicit range to use to generate the histogram. If no range is set the fields global range is used.
\item[\classmember*{Histogram}{GetBinDelta}]
  Get the size of each bin from the last computed field.
\item[\classmember*{Histogram}{GetComputedRange}]
  Get the computed local range of the histogram from the last computed field.
  \commoncellfieldfiltermethods
\end{description}

\index{histogram|)}


\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.

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

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

\begin{description}
  \commoncellfieldfiltermethods
\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.
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 as always using the \classmember*{PointElevation}{SetOutputFieldName} method.

\textidentifier{PointElevation} provides the following methods.

\begin{description}
\item[\classmember*{PointElevation}{SetLowPoint}/\classmember*{PointElevation}{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[\classmember*{PointElevation}{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.
  \commonfieldfiltermethods
\end{description}

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


\subsection{Point Transform}

\index{point transform|(}
\index{transform|(}

\vtkmfilter{PointTransform} is the point transform filter.
The filter will take a data set and a field of 3 dimensional vectors and perform the specified point transform operation. Multiple point transformations can be accomplished by subsequent calls to the filter and specifying the result of the previous transform as the input field.

The default name for the output field is ``transform'', but that can be
overridden as always using the \classmember*{PointTransform}{SetOutputFieldName} method.

In addition the standard \classmember*{PointTransform}{SetOutputFieldName} and \classmember*{PointTransform}{Execute} methods, \textidentifier{PointTransform} provides the following methods.

\begin{description}
	\item[\classmember*{PointTransform}{SetTranslation}] This method translates, or moves, each point in the input field by a given direction. This method takes either a three component vector of floats, or the $x$, $y$, $z$ translation values separately.
	\item[\classmember*{PointTransform}{SetRotation}] This method is used to rotate the input field about a given axis. This method takes a single floating point number to specify the degrees of rotation and either a vector representing the rotation axis, or the $x$, $y$, $z$ axis components separately.
	\item[\classmember*{PointTransform}{SetRotationX}] This method is used to rotate the input field about the X axis. This method takes a single floating point number to specify the degrees of rotation.
	\item[\classmember*{PointTransform}{SetRotationY}] This method is used to rotate the input field about the Y axis. This method takes a single floating point number to specify the degrees of rotation.
	\item[\classmember*{PointTransform}{SetRotationZ}] This method is used to rotate the input field about the Z axis. This method takes a single floating point number to specify the degrees of rotation.
	\item[\classmember*{PointTransform}{SetScale}] This method is used to scale the input field. This method takes either a single float to scale each vector component of the field equally, or the $x$, $y$, $z$ scaling values as separate floats, or a three component vector.
	\item[\classmember*{PointTransform}{SetTransform}] This is a generic transform method. This method takes a $4x4$ matrix and applies this to the input field.
	\commoncellfieldfiltermethods
\end{description}

\index{transform|)}
\index{point transform|)}


\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 \classmember*{SurfaceNormals}{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
overridden using the \classmember*{SurfaceNormals}{SetCellNormalsName} and
\classmember*{SurfaceNormals}{SetPointNormalsName} methods.
The filter will also respect the name in \classmember*{SurfaceNormals}{SetOutputFieldName} if neither of the others are set.

\textidentifier{SurfaceNormals} provides the following methods.

\begin{description}
\item[\classmember*{SurfaceNormals}{SetGenerateCellNormals}/\classmember*{SurfaceNormals}{GetGenerateCellNormals}]
  Specifies whether the cell normals should be generated.
\item[\classmember*{SurfaceNormals}{SetGeneratePointNormals}/\classmember*{SurfaceNormals}{GetGeneratePointNormals}]
  Specifies whether the point normals should be generated.
\item[\classmember*{SurfaceNormals}{SetNormalizeCellNormals}/\classmember*{SurfaceNormals}{GetNormalizeCellNormals}]
  Specifies whether cell normals should be normalized (made unit length).
  Default value is true.
  The intended use case of this flag is for faster, approximate point normals generation by skipping the normalization of the face normals.
  Note that when set to false, the result cell normals will not be unit length normals and the point normals will be different.
\item[\classmember*{SurfaceNormals}{SetCellNormalsName}/\classmember*{SurfaceNormals}{GetCellNormalsName}]
  Specifies the output cell normals field name.
\item[\classmember*{SurfaceNormals}{SetPointNormalsName}/\classmember*{SurfaceNormals}{GetPointNormalsName}]
  Specifies the output point normals field name.
  \commoncellfieldfiltermethods
\end{description}

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

\subsection{Vector Magnitude}

\index{vector magnitude|(}
\index{magnitude|(}

\vtkmfilter{VectorMagnitude} takes a field comprising vectors and computes the magnitude for each vector.
The vector field is selected as usual with the \classmember*{VectorMagnitude}{SetActiveField} method.
The default name for the output field is ``magnitude'', but that can be overridden as always using the \classmember*{VectorMagnitude}{SetOutputFieldName} method.

\textidentifier{VectorMagnitude} provides the following methods.

\begin{description}
  \commonfieldfiltermethods
\end{description}

\index{magnitude|)}
\index{vector magnitude|)}


\subsection{Warp Scalar}

\index{warp scalar|(}
\index{scalar|(}

\vtkmfilter{WarpScalar} is a specialized point transformation filter.
The filter transforms points by moving them based on a scalar field and a constant scale factor.
This filter is useful for creating carpet plots.

The \textidentifier{WarpScalar} filter will take a data set, a normal field, a scalar field, and a constant scale factor.
The coordinates will be scaled based on the scalar field and the scale factor.
If no explicit normal field is provided the filter will search for a field named ``normal''.
If no explicit scalar field is provided the filter will search for a field named ``scalarfactor''.

The default name for the output field is ``warpscalar'', but that can be overridden as always using the \classmember*{WarpScalar}{SetOutputFieldName} method.

In addition to the standard \classmember*{WarpScalar}{SetOutputFieldName} and \classmember*{WarpScalar}{Execute} methods, \textidentifier{WarpScalar} provides the following methods.

\begin{description}
\item[\classmember*{WarpScalar}{SetNormalField}]
  This method allows the user to select the name of the normal field.
  The normal field is the $B$ field in the warp equation of $A + B \times scaleAmount \times scalarFactor$ (where $A$ is the original position of the point).
\item[\classmember*{WarpScalar}{SetScalarFactorField}]
  This method allows the user to select the name of the scale factor field.
  The scale factor field is the $scalarFactor$ field in the warp equation of $A + B \times scaleAmount \times scalarFactor$ (where $A$ is the original position of the point).
  \commoncellfieldfiltermethods
\end{description}

\index{scalar|)}
\index{warp scalar|)}

\subsection{Warp Vector}

\index{warp vector|(}
\index{vector|(}

\vtkmfilter{WarpVector} is a specialized point transformation filter.
The filter transforms points by moving them based on a vector field and a constant scale factor.
This filter can be used to highlight interesting features such as flow or deformations.

The \textidentifier{WarpScalar} filter will take a data set, a vector field, and a constant scale factor.
The coordinates will be scaled based on the vector field and the scale factor.
If no explicit vector field is provided the filter will search for a field named ``normal''.

The default name for the output field is ``warpvector'', but that can be
overridden as always using the \classmember*{WarpVector}{SetOutputFieldName} method.

In addition the standard \classmember*{WarpVector}{SetOutputFieldName} and \classmember*{WarpVector}{Execute} methods, \textidentifier{WarpVector} provides the following methods.

\begin{description}
\item[\classmember*{WarpVector}{SetVectorField}]
  This method allows the user to select the name of the vector field.
  The vector field is the $B$ field in the warp equation of $A + B$ (where $A$ is the original position of the point).
  \commoncellfieldfiltermethods
\end{description}

\index{vector|)}
\index{warp vector|)}


\subsection{ZFP Compression}

\index{zfp!compression|(}
\index{compression!zfp|(}

\vtkmfilter{ZFPCompressor} takes a 1D, 2D, or 3D field and compresses the
values using the compression algorithm ZFP. The field is selected as usual
with the \classmember*{ZFPCompressor}{SetActiveField} method. The rate of compression is
set using \classmember*{ZFPCompressor}{SetRate}. The default name for the output field is
``compressed''

\textidentifier{ZFPCompressor} provides the following methods:

\begin{description}
\item[\classmember*{ZFPCompressor}{SetRate}/\classmember*{ZFPCompressor}{GetRate}]
  Specifies the rate of compression.
\item[\classmember*{ZFPCompressor}{SetActiveField}/\classmember*{ZFPCompressor}{GetActiveFieldName}]
  Specifies the name of the field to use as input.

  \commonfieldfiltermethods
\end{description}

\index{compression!zfp|)}
\index{zfp!compression|)}

\index{zfp!decompression|(}
\index{decompression!zfp|(}

\vtkmfilter{ZFPDecompressor} takes a field of compressed values and decompresses into scalar values using the compression algorithm ZFP.
The field is selected as usual with the \classmember*{ZFPDecompressor}{SetActiveField} method.
The rate of compression is set using \classmember*{ZFPDecompressor}{SetRate}.
The default name for the output field is ``decompressed''

\textidentifier{ZFPDecompressor} provides the following methods:

\begin{description}
\item[\classmember*{ZFPDecompressor}{SetRate}]
  Specifies the rate of compression.
\item[\classmember*{ZFPDecompressor}{SetActiveField}/\classmember*{ZFPDecompressor}{GetActiveFieldName}]
  Specifies the name of the field to use as input.

  \commonfieldfiltermethods
\end{description}

\index{decompression!zfp|)}
\index{zfp!decompression|)}

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

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

\newcommand{\commondatasetfiltermethods}{
\item[\textcode{SetActiveCellSetIndex}/\textcode{GetActiveCellSetIndex}]
  Specifies the index for the cell set to use from the data set provided to the \textcode{Execute} method.
  The default index is 0, which is the first cell set.
\item[\textcode{SetActiveCoordinateSystem}/\textcode{GetActiveCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use as when computing spatial locations in the mesh.
  The default index is 0, which is the first coordinate system.
  \commonfiltermethods
}

\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.

Before a filter is run, it is important to set up the state of the filter object to the parameters of the algorithm.
The state parameters will vary from one filter to the next, but one state parameter that all data set filters share is the ``active'' cell set for the operation.
The active cell set is set with a call to the \classmember*{FilterDataSet}{SetActiveCellSetIndex}.
Likewise, \classmember*{FilterDataSet}{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.)

All data set filters contain an \classmember*{FilterDataSet}{Execute} method.
When calling \classmember*{FilterDataSet}{Execute} a \vtkmcont{DataSet} or \vtkmcont{MultiBlock} object with the input data is provided as an argument.
The \classmember*{FilterDataSet}{Execute} method returns a \textidentifier{DataSet} or \textidentifier{MultiBlock} object (matching the type of the input to \classmember*{FilterDataSet}{Execute}), which contains the data generated.

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 and combine coincident points.
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}

\textidentifier{CleanGrid} provides the following methods.

\begin{description}
\item[\classmember*{CleanGrid}{SetCompactPointFields}/\classmember*{CleanGrid}{GetCompactPointFields}]
  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.
\item[\classmember*{CleanGrid}{SetMergePoints}/\classmember*{CleanGrid}{GetMergePoints}]
  Sets a Boolean flag that determines whether points coincident in space are merged into a single point.
  If true (the default), then the output data set will have a new coordinate system containing containing only points that are unique in space, and the indices of the cells will be adjusted to the new set of points.
  The tolerance parameters control the proximity used for points to be considered coincident.
\item[\classmember*{CleanGrid}{SetTolerance}/\classmember*{CleanGrid}{GetTolerance}]
  Defines the tolerance used when determining whether two points are considered coincident.
  Because floating point parameters have limited precision, point coordinates that are essentially the same might not be bit-wise exactly the same.
  Thus, the \textidentifier{CleanGrid} filter has the ability to find and merge points that are close but perhaps not exact.
  The default tolerance is $10^{-6}$.
\item[\classmember*{CleanGrid}{SetToleranceIsAbsolute}/\classmember*{CleanGrid}{GetToleranceIsAbsolute}]
  Sets a Boolean flag that determines whether the tolerance parameter should be considered relative to the size of the data set.
  If false (the default), then the tolerance is multiplied by the length of the diagonal of the bounds of the data being processed.
  If true, then the tolerance value is used as is.
\item[\classmember*{CleanGrid}{SetRemoveDegenerateCells}\classmember*{CleanGrid}{GetRemoveDegenerateCells}]
  Sets a Boolean flag that determines whether degenerate cells should be removed.
  If true (the default), then the \textidentifier{CleanGrid} filter will look for repeated points in cells and, if the repeated points cause the cell to drop dimensionality, the cell is removed.
  This is particularly useful when point merging is on as this operation can create degenerate cells.
\item[\classmember*{CleanGrid}{SetFastMerge}/\classmember*{CleanGrid}{GetFastMerge}]
  Sets a Boolean flag that determines whether to use a faster but less accurate method for finding coincident points.
  If true (the default), some corners are cut when computing coincident points.
  This will make the point merge step go faster but the tolerance will not be strictly followed.
  If false, then extra steps will be taken to ensure that all points within tolerance are merged and that only points within tolerance are merged.
  This flag has no effect if point merging is off.
  \commondatasetfiltermethods
\end{description}

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

\subsection{Clip with Implicit Function}
\label{sec:ClipWithImplicitFunction}

\index{clip!implicit function|(}
\index{implicit function!clip|(}

Clipping is an operation that removes regions from the data set based on a user-provided value or function.
The \vtkmfilter{ClipWithImplicitFunction} takes an implicit function as an argument.
\VTKm's implicit functions\fix{, described in detail in Section [AddReferece],} are simple objects that take 3D spatial coordinates and return a field value that often describes a shape.
\textidentifier{ClipWithImplicitFunction} discards regions of the original data set according to the values of the implicit function.
(A companion filter that discards a region of the data based on the value of a scalar field is described in Section \ref{sec:ClipWithField}.)

The result of \textidentifier{ClipWithImplicitFunction} is a volume.
If a cell has its vertices positioned all outside the implicit function, then it will be discarded entirely.
Likewise, if a cell its vertices all inside the implicit function, then it will be retained in its entirety.
If a cell has some vertices inside the implicit function and some outside, then the cell will be split into the portions inside (which will be retained) and the portions outside (which will be discarded).

\textidentifier{ClipWithImplicitFunction} provides the following methods.

\begin{description}
\item[\classmember*{ClipWithImplicitFunction}{SetImplicitFunction}\classmember*{ClipWithImplicitFunction}{GetImplicitFunction}]
  Specifies the implicit function to be used to perform the clip operation.
  The filter does not directly take a \vtkm{ImplicitFunction} but rather an \textidentifier{ImplicitFunction} wrapped inside of a \vtkmcont{ImplicitFunctionHandle}.
  The \textidentifier{ImplicitFunctionHandle} manages the use of the virtual methods in \textidentifier{ImplicitFunction} on different devices, which may be using different memory spaces or require different processor instructions.
  An \textidentifier{ImplicitFunctionHandle} is easily created with the \vtkmcont{make\_ImplicitFunctionHandle} function.

\item[\classmember*{ClipWithImplicitFunction}{SetInvertClip}]
  Specifies whether the result of the clip filter should be inverted.
  If set to false (the default), all regions where the implicit function is negative will be removed.
  If set to true, all regions where the implicit function is positive will be removed.

  \commondatasetfiltermethods
\end{description}

In the example provided below the \vtkm{Sphere} implicit function is used.
This function evaluates to a negative value if points from the original dataset occur within the sphere, evaluates to 0 if the points occur on the surface of the sphere, and evaluates to a positive value if the points occur outside the sphere.

\vtkmlisting{Using \textidentifier{ClipWithImplicitFunction}.}{ClipWithImplicitFunction.cxx}

\index{implicit function!clip|)}
\index{clip!implicit function|)}

\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.

\textidentifier{ExternalFaces} provides the following methods.

\begin{description}
\item[\classmember*{ExternalFaces}{SetCompactPoints}/\classmember*{ExternalFaces}{GetCompactPoints}]
  Specifies whether point fields should be compacted.
  If on, the filter will remove from the output all points that are not used in the resulting surface.
  If off (the default), unused points will remain listed in the topology, but point fields and coordinate systems will be shallow-copied to the output.
\item[\classmember*{ExternalFaces}{SetPassPolyData}/\classmember*{ExternalFaces}{GetPassPolyData}]
  Specifies how polygonal data (polygons, lines, and vertices) will be handled.
  If on (the default), these cells will be passed to the output.
  If off, these cells will be removed from the output.
  (Because they have less than 3 topological dimensions, they are not considered to have any ``faces.'')
  \commondatasetfiltermethods
\end{description}

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

\subsection{Ghost Cell Classification}

\index{classify ghost cells|(}
\index{ghost cell!classify|(}

\vtkmfilter{GhostCellClassify} adds a cell centered field to the input data set that marks each cell as either \classmember[vtkm]{CellClassification}{NORMAL} or \classmember[vtkm]{CellClassification}{GHOST}.
The outer layer of cells are marked as \classmember*{CellClassification}{GHOST}, and the remainder are marked as *{CellClassification}{NORMAL}.
This filter only supports uniform and rectilinear data sets.
The default field is ``vtkmGhostCells''.

\textidentifier{GhostCellClassify} provides the following methods.

\begin{description}
  \commonfieldfiltermethods
\end{description}

\index{ghost cell!classify|)}
\index{classify ghost cells|)}

\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.

\textidentifier{VertexClustering} provides the following methods.

\begin{description}
\item[\classmember*{ExternalFaces}{SetNumberOfDivisions}/\classmember*{ExternalFaces}{GetNumberOfDimensions}]
  Specifies 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}.
  \commondatasetfiltermethods
\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}

\newcommand{\commondatasetwithfieldfiltermethods}{
\item[\textcode{SetActiveField}/\textcode{GetActiveFieldName}]
  Specifies the name of the field to use as input.
\item[\textcode{SetUseCoordinateSystemAsField}/\textcode{GetUseCoordinateSystemAsField}]
  Specifies a Boolean flag that determines whether to use point coordinates as the input field.
  Set to false by default.
  When true, the values for the active field are ignored.
\item[\textcode{SetActiveCoordinateSystem}/\textcode{GetActiveCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use as when computing spatial locations in the mesh.
  The default index is 0, which is the first coordinate system.
\item[\textcode{SetActiveCellSetIndex}/\textcode{GetActiveCellSetIndex}]
  Specifies the index for the cell set to use from the data set provided to the \textcode{Execute} method.
  The default index is 0, which is the first cell set.
  \commonfiltermethods
}

\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.

Before a filter is run, it is important to set up the state of the filter object to the parameters of the algorithm.
The state parameters will vary from one filter to the next, but one state parameter that all data set with field filters share is the ``active'' field for the operation.
The active field is set with a call to the \classmember*{FilterDataSetWithField}{SetActiveField} method.
The argument to \classmember*{FilterDataSetWithField}{SetActiveField} is a string that names this input field.
Another state parameters all data set with field filters share is the ``active'' cell set for the operation.
The active cell set is set with a call to the \classmember*{FilterDataSetWithField}{SetActiveCellSetIndex}.
Likewise, \classmember*{FilterDataSetWithField}{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.)
Finally, \classmember*{FilterDataSetWithField}{SetOutputFieldName}, specifies the name assigned to the generated field.
If not specified, then the filter will use a default name.

All data set with field filters contain an \classmember*{FilterDataSetWithField}{Execute} method.
When calling \classmember*{FilterDataSetWithField}{Execute} a \vtkmcont{DataSet} or \vtkmcont{MultiBlock} object with the input data is provided as an argument.
The \classmember*{FilterDataSetWithField}{Execute} method returns a \textidentifier{DataSet} or \textidentifier{MultiBlock} object (matching the type of the input to \classmember*{FilterDataSetWithField}{Execute}), which contains the data generated.

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{Clip with Field}
\label{sec:ClipWithField}

\index{clip!field|(}
\index{isovolume|(}

Clipping is an operation that removes regions from the data set based on a user-provided value or function.
The \vtkmfilter{ClipWithField} filter takes a clip value as an argument and removes regions where a named scalar field is below (or above) that value.
(A companion filter that discards a region of the data based on an implicit function is described in Section \ref{sec:ClipWithImplicitFunction}.)

The result of \textidentifier{ClipWithField} is a volume.
If a cell has field values at its vertices that are all below the specified value, then it will be discarded entirely.
Likewise, if a cell has field values at its vertices that are all above the specified value, then it will be retained in its entirety.
If a cell has some vertices with field values below the specified value and some above, then the cell will be split into the portions above the value (which will be retained) and the portions below the value (which will be discarded).

This operation is sometimes called an \keyterm{isovolume} because it extracts the volume of a mesh that is inside the iso-region of a scalar.
This is in contrast to an \keyterm{isosurface} (also known as a \keyterm{contour}), which extracts only the surface of that iso-value.
(See Section \ref{sec:Isosurface} for extracting an isosurface.)
\textidentifier{ClipWithField} is also similar to a threshold operation, which extracts cells based on the value of field.
The difference is that threshold will either keep or remove entire cells based on the field values whereas clip with carve cells that straddle the valid regions.
(See section \ref{sec:Threshold} for threshold extraction.)

\textidentifier{ClipWithField} provides the following methods.

\begin{description}
\item[\classmember*{ClipWithField}{SetClipValue}/\classmember*{ClipWithField}{GetClipValue}]
  Specifies the field value for the clip operation.
  Regions where the active field is less than this value are clipped away from each input cell.

\item[\classmember*{ClipWithField}{SetInvertClip}]
  Specifies if the result for the clip filter should be inverted.
  If set to false (the default), regions where the active field is less than the specified clip value are removed.
  If set to true, regions where the active field is more than the specified clip value are removed.

  \commondatasetwithfieldfiltermethods
\end{description}

\vtkmlisting{Using \textidentifier{ClipWithField}.}{ClipWithField.cxx}

\index{isovolume|)}
\index{clip!field|)}

\subsection{Ghost Cell Removal}

\index{ghost cell!remove|(}

\vtkmfilter{GhostCellRemove} is a filter that is used to remove cells from a data set according to a
cell centered field that is provided to the filter. The default field used for removal is ``vtkmGhostCells''.
The field is of type \vtkm{UInt8}, and represents a bit-field to classify each cell.
By default, if the input is a structured data set the filter will attempt to output a structured data set.
If this is not possible, an explict data set is produced. The field specified for cell removal is not passed
to the output.

\textidentifier{GhostCellRemove} provides the following methods.

\begin{description}
\item[\classmember*{GhostCellRemove}{RemoveAllGhost}]
  Remove all cells where the value is a ghost cell (i.e. \classmember[vtkm]{CellClassification}{GHOST}).
\item[\classmember*{GhostCellRemove}{RemoveByType}]
  Remove cells specified by the \vtkm{UInt8} using a bitwise ``and'' operation with the type field.
  The values in \vtkm{CellClassification} can be combined with a logical ``or'' operation to specify the type.
  Current values of \vtkm{CellClassification} include: \classmember*{CellClassification}{NORMAL}, \classmember*{CellClassification}{GHOST}, and \classmember*{CellClassification}{INVALID}.
\item[\classmember*{GhostCellRemove}{ConvertOutputToUnstructured}]
  Return an explict data set.
  \commondatasetfiltermethods
\end{description}

\index{ghost cell!remove|)}

\subsection{Marching Cubes}
\label{sec:Isosurface}
\label{sec:Contour}

\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.

\textidentifier{MarchingCubes} provides the following methods.

\begin{description}
\item[\classmember*{ClipWithField}{SetIsoValue}/\classmember*{ClipWithField}{GetIsoValue}]
  Specifies 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[\classmember*{ClipWithField}{SetMergeDuplicatePoints}/\classmember*{ClipWithField}{GetMergeDuplicatePoints}]
  Specifies 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[\classmember*{ClipWithField}{SetGenerateNormals}/\classmember*{ClipWithField}{GetGenerateNormals}]
  Specifies 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[\classmember*{ClipWithField}{SetComputeFastNormalsForStructured}/\classmember*{ClipWithField}{GetComputeFastNormalsForStructured}]
  Specifies whether to use the fast method of normals computation for Structured data sets.
  This is only valid if the generate normals flag is set.
\item[\classmember*{ClipWithField}{SetComputeFastNormalsForUnstructured}/\classmember*{ClipWithField}{GetComputeFastNormalsForUnstructured}]
  Specifies whether to use the fast method of normals computation for unstructured data sets.
  This is only valid if the generate normals flag is set.
\item[\classmember*{ClipWithField}{SetNormalArrayName}/\classmember*{ClipWithField}{GetNormalArrayName}]
  Specifies the name used for the normals field if it is being created.
  \commondatasetwithfieldfiltermethods
\end{description}

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

\subsection{Threshold}
\label{sec: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 \classmember*{Threshold}{Execute}) is not between a
range of values.

Note that \textidentifier{Threshold} either passes an entire cell or discards an entire cell.
This can consequently lead to jagged surfaces at the interface of the threshold caused by the shape of cells that jut inside or outside the removed region.
See Section~\ref{sec:ClipWithField} for a clipping filter that will clip off a smooth region of the mesh.

\textidentifier{Threshold} provides the following methods.

\begin{description}
\item[\classmember*{Threshold}{SetLowerThreshold}/\classmember*{Threshold}{GetLowerThreshold}]
  Specifies the lower scalar value.
  Any cells where the scalar field is less than this value are removed.
\item[\classmember*{Threshold}{SetUpperThreshold}\classmember*{Threshold}{GetUpperThreshold}]
  Specifies the upper scalar value.
  Any cells where the scalar field is more than this value are removed.
  \commondatasetwithfieldfiltermethods
\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.

\vtkmfilter{Streamline} provides the following methods.

\begin{description}
\item[\classmember*{Streamline}{SetSeeds}]
  Specifies the seed locations for the streamlines.
  Each seed is advected in the vector field to generate one streamline for each seed.
\item[\classmember*{Streamline}{SetStepSize}]
  Specifies the step size used for the numerical integrator ($4^{\mathrm{th}}$ order Runge-Kutta method) to integrate the seed locations through the flow field.
\item[\classmember*{Streamline}{SetNumberOfSteps}]
  Specifies 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|)}

\subsection{Pathlines}

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

\keyterm{Pathlines} are the analog to Streamlines for time varying vector fields.
Individual pathlines are computed from an initial point location (seed) using a numerical
method to integrate the point through the flow field. This filter requires two data sets as input.
The data set passed into the filter is termed ``Previous'' and the ``Next'' data set is specified
to the filter using a method.

\vtkmfilter{Pathline} provides the following methods.

\begin{description}
\item[\classmember*{Pathline}{SetPreviousTime}]
  Specifies time value for the input data set.
\item[\classmember*{Pathline}{SetNextTime}]
  Specifies time value for the next data set.
\item[\classmember*{Pathline}{SetNextDataSet}]
  Specifies the data set for the next time step.
\item[\classmember*{Pathline}{SetSeeds}]
  Specifies the seed locations for the pathlines.
  Each seed is advected in the vector field to generate one streamline for each seed.
\item[\classmember*{Pathlines}{SetStepSize}]
  Specifies the step size used for the numerical integrator ($4^{\mathrm{th}}$ order Runge-Kutta method) to integrate the seed locations through the flow field.
\item[\classmember*{Pathline}{SetNumberOfSteps}]
  Specifies the number of integration steps to be performed on each pathline.
\end{description}

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

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

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


\section{Advanced Field Management}
\label{sec:AdvancedFieldManagement}

\index{filter!fields|(}

Most filters work with fields as inputs and outputs to their algorithms.
Although in the previous discussions of the filters we have seen examples of specifying fields, these examples have been kept brief in the interest of clarity.
In this section we revisit how filters manage fields and provide more detailed documentation of the controls.

Note that not all of the discussion in this section applies to all the aforementioned filters.
For example, not all filters have a specified input field.
But where possible, the interface to the filter objects is kept consistent.

\subsection{Input Fields}
\label{sec:FilterInputFields}

\index{filter!fields!input|(}
\index{filter!input fields|(}

Many of \VTKm's filters have a method named \classmember*{FilterField}{SetActiveField}, which selects a field in the input data to use as the data for the filter's algorithm.
We have already seen how \classmember*{FilterField}{SetActiveField} takes the name of the field as an argument.
However, \classmember*{FilterField}{SetActiveField} also takes an optional second argument that specifies which topological elements the field is associated with (such as points or cells).
If specified, this argument is one of the following.
\begin{description}
\item[{\vtkmcont{Field}[ASSOC\_ANY]}]
  Any field regardless of the association.
  (This is the default if no association is given.)
\item[{\vtkmcont{Field}[ASSOC\_POINTS]}]
  A field that applies to points.
  There is a separate field value attached to each point.
  Point fields usually represent samples of continuous data that can be reinterpolated through cells.
  Physical properties such as temperature, pressure, density, velocity, etc. are usually best represented in point fields.
  Data that deals with the points of the topology, such as displacement vectors, are also appropriate for point data.
\item[{\vtkmcont{Field}[ASSOC\_CELL\_SET]}]
  A field that applies to cells.
  There is a separate field value attached to each cell in a cell set.
  Cell fields usually represent values from an integration over the finite cells of the mesh.
  Integrated values like mass or volume are best represented in cell fields.
  Statistics about each cell like strain or cell quality are also appropriate for cell data.
\item[{\vtkmcont{Field}[ASSOC\_WHOLE\_MESH]}]
  A ``global'' field that applies to the whole mesh.
  These often contain summary or annotation information.
  An example of a whole mesh field could be the volume that the mesh covers.
\end{description}

\vtkmlisting{Setting a field's active filter with an association.}{SetActiveFieldWithAssociation.cxx}

\begin{commonerrors}
  It is possible to have two fields with the same name that are only differentiatable by the association.
  That is, you could have a point field and a cell field with different data but the same name.
  Thus, it is best practice to specify the field association when possible.
  Likewise, it is poor practice to have two fields with the same name, particularly if the data are not equivalent in some way.
  It is often the case that fields are selected without an association.
\end{commonerrors}

It is also possible to set the active scalar field as a coordinate system of the data.
A coordinate system essentially provides the spatial location of the points of the data and they have a special place in the \vtkmcont{DataSet} structure.
(See Section~\ref{sec:DataSets:CoordinateSystems} for details on coordinate systems.)
You can use a coordinate system as the active scalars by calling the \classmember*{FilterField}{SetUseCoordinateSystemAsField} method with a true flag.
Since a \textidentifier{DataSet} can have multiple coordinate systems, you can select the desired coordinate system with \classmember*{FilterField}{SetActiveCoordinateSystem}.
(By default, the first coordinate system will be used.)

\fix{Example of setting the active coordinate system.}

\index{filter!input fields|)}
\index{filter!fields!input|)}

\subsection{Passing Fields from Input to Output}
\label{sec:FilterPassingFields}

\index{filter!fields!passing|(}
\index{filter!passing fields|(}

After a filter successfully executes and returns a new data set, fields are mapped from input to output.
Depending on what operation the filter does, this could be a simple shallow copy of an array, or it could be a computed operation.
By default, the filter will automatically pass all fields from input to output (performing whatever transformations are necessary).
You can control which fields are passed (and equivalently which are not) with the \classmember*{Filter}{SetFieldsToPass} methods of \vtkmfilter{Filter}.

There are multiple ways to to use \classmember{Filter}{SetFieldsToPass} to control what fields are passed.
If you want to turn off all fields so that none are passed, call \classmember*{Filter}{SetFieldsToPass} with \vtkmfilter{FieldSelection}[MODE\_NONE].

\vtkmlisting{Turning off the passing of all fields when executing a filter.}{PassNoFields.cxx}

If you want to pass one specific field, you can pass that field's name to \classmember*{Filter}{SetFieldsToPass}.

\vtkmlisting{Setting one field to pass by name.}{PassOneField.cxx}

Or you can provide a list of fields to pass by giving \classmember*{Filter}{SetFieldsToPass} an initializer list of names.

\vtkmlisting{Using a list of fields for a filter to pass.}{PassListOfFields.cxx}

If you want to instead select a list of fields to \emph{not} pass, you can add \vtkmfilter{FieldSelection}[MODE\_EXCLUDE] as an argument to \classmember*{Filter}{SetFieldsToPass}.

\vtkmlisting{Excluding a list of fields for a filter to pass.}{PassExcludeFields.cxx}

Ultimately, \classmember{Filter}{SetFieldsToPass} takes a \vtkmfilter{FieldSelection} object.
You can create one directly to select (or exclude) specific fields and their associations.

\vtkmlisting{Using \protect\vtkmfilter{FieldSelection}.}{FieldSelection.cxx}

It is also possible to specify field attributions directly to \classmember{Filter}{SetFieldsToPass}.
If you only have one field, you can just specify both the name and attribution.
If you have multiple fields, you can provide an initializer list of \textcode{std::pair} or \vtkm{Pair} containing a \textcode{std::string} and a \vtkmcont{Field}[AssociationEnum].
In either case, you can add an optional last argument of \vtkmfilter{FieldSelection}[MODE\_EXCLUDE] to exclude the specified filters instead of selecting them.

\vtkmlisting{Selecting one field and its association for a filter to pass.}{PassFieldAndAssociation.cxx}

\vtkmlisting{Selecting a list of fields and their associations for a filter to pass.}{PassListOfFieldsAndAssociations.cxx}

\index{filter!passing fields|)}
\index{filter!fields!passing|)}

\index{filter!fields|)}


\index{filter|)}
