% -*- 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[\classmember{Execute}]
  Takes a data set, executes the filter on a device, and returns a data set that contains the result.
\item[\classmember{SetFieldsToPass}/\classmember{GetFieldsToPass}]
  Specifies which fields to pass from input to output.
  By default all fields are passed.
  See Section~\ref{sec:FilterPassingFields} for more details.
\item[\classmember{SetRuntimeDeviceTracker}/\classmember{GetRuntimeDeviceTracker}]
  Specifies which devices to use during execution.
  Runtime device trackers are described in Section~\ref{sec:RuntimeDeviceTracker}.
}


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

\newcommand{\commonfieldfiltermethods}{
\item[\classmember{SetActiveField}/\classmember{GetActiveFieldName}]
  Specifies the name of the field to use as input.
\item[\classmember{SetUseCoordinateSystemAsField}/\classmember{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[\classmember{SetActiveCoordinateSystem}/\classmember{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[\classmember{SetOutputFieldName}/\classmember{GetOutputFieldName}]
  Specifies the name of the output field generated.
  \commonfiltermethods
}

\newcommand{\commoncellfieldfiltermethods}{
\item[\classmember{SetActiveCellSetIndex}/\classmember{GetActiveCellSetIndex}]
  Specifies the index for the cell set to use from the data set provided to the \classmember{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{SetActiveField} method.
The argument to \classmember{SetActiveField} is a string that names this input field.
Alternatively, you can call the \classmember{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{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{Execute} method.
When calling \classmember{Execute} a \vtkmcont{DataSet} or \vtkmcont{MultiBlock} object with the input data is provided as an argument.
The \classmember{Execute} method returns a \textidentifier{DataSet} or \textidentifier{MultiBlock} object (matching the type of the input to \classmember{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{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{SetOutputFieldName} method.

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

\begin{description}
	\item[\classmember{SetCartesianToCylindrical}] This method specifies a transformation from cartesian to cylindrical coordinates.
	\item[\classmember{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{SetOutputFieldName} method.

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

\begin{description}
	\item[\classmember{SetCartesianToSpherical}] This method specifies a transformation from cartesian to spherical coordinates.
	\item[\classmember{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{SetPrimaryField}/\classmember{GetPrimaryFieldName}]
  Specifies the name of the field to use as input for the primary (first) value of the cross product.
\item[\classmember{SetUseCoordinateSystemAsPrimaryField}/\classmember{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{SetPrimaryCoordinateSystem}/\classmember{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{SetSecondaryField}/\classmember{GetSecondaryFieldName}]
  Specifies the name of the field to use as input for the secondary (second) value of the cross product.
\item[\classmember{SetUseCoordinateSystemAsSecondaryField}/\classmember{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{SetSecondaryCoordinateSystem}/\classmember{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{SetOutputFieldName}/\classmember{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{SetPrimaryField}/\classmember{GetPrimaryFieldName}]
  Specifies the name of the field to use as input for the primary (first) value of the dot product.
\item[\classmember{SetUseCoordinateSystemAsPrimaryField}/\classmember{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{SetPrimaryCoordinateSystem}/\classmember{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{SetSecondaryField}/\classmember{GetSecondaryFieldName}]
  Specifies the name of the field to use as input for the secondary (second) value of the dot product.
\item[\classmember{SetUseCoordinateSystemAsSecondaryField}/\classmember{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{SetSecondaryCoordinateSystem}/\classmember{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{SetOutputFieldName}/\classmember{GetOutputFieldName}]
  Specifies the name of the output field generated.
  \commonfiltermethods
\end{description}

\index{dot product|)}

\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{SetColorTable}/\classmember{GetColorTable}]
  Specifies the \vtkmcont{ColorTable} object to use to map field values to colors.
\item[\classmember{SetMappingMode}/\classmember{GetMappingMode}]
  Specifies the input mapping mode.
  The value is one of the \classmember{SCALAR}, \classmember{MAGNITUDE}, or \classmember{COMPONENT} selectors described previously.
\item[\classmember{SetMappingToScalar}]
  Sets the input mapping mode to scalar.
  Shortcut for \classmember{SetMappingMode}\textcode{(}\vtkmfilter{FieldToColors}[SCALAR]\textcode{)}.
\item[\classmember{SetMappingToMagnitude}]
  Sets the input mapping mode to vector.
  Shortcut for \classmember{SetMappingMode}\textcode{(}\vtkmfilter{FieldToColors}[MAGNITUDE]\textcode{)}.
\item[\classmember{SetMappingToComponent}]
  Sets the input mapping mode to component.
  Shortcut for \classmember{SetMappingMode}\textcode{(}\vtkmfilter{FieldToColors}[COMPONENT]\textcode{)}.
\item[\classmember{IsMappingScalar}]
  Returns true if the input mapping mode is scalar (\classmember[FieldToColors]{SCALAR}).
\item[\classmember{IsMappingMagnitude}]
  Returns true if the input mapping mode is magnitude (\classmember[FieldToColors]{MAGNITUDE}).
\item[\classmember{IsMappingComponent}]
  Returns true if the input mapping mode is component (\classmember[FieldToColors]{COMPONENT}).
\item[\classmember{SetMappingComponent}/\classmember{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{COMPONENT}.
\item[\classmember{SetOutputMode}/\classmember{GetOutputMode}]
  Specifies the output representation of colors.
  The value is one of the \classmember{RGB} or \classmember{RGBA} selectors described previously.
\item[\classmember{SetOutputToRGB}]
  Sets the output representation to 8-bit RGB.
  Shortcut for \classmember{SetOutputMode}\textcode{(}\vtkmfilter{FieldToColors}[RGB]\textcode{)}.
\item[\classmember{SetOutputToRGBA}]
  Sets the output representation to 8-bit RGBA.
  Shortcut for \classmember{SetOutputMode}\textcode{(}\vtkmfilter{FieldToColors}[RGBA]\textcode{)}.
\item[\classmember{IsOutputRGB}]
  Returns true if the output representation is 8-bit RGB (\classmember[FieldToColors]{RGB}).
\item[\classmember{IsOutputRGBA}]
  Returns true if the output representation is 8-bit RGBA (\classmember[FieldToColors]{RGBA}).
\item[\classmember{SetNumberOfSamplingPoints}/\classmember{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{SetComputePointGradient} method.
The default name for the output fields is ``Gradients'', but that can be
overriden as always using the \classmember{SetOutputFieldName} method.

\textidentifier{Gradients} provides the following methods.

\begin{description}
\item[\classmember{SetComputePointGradient}/\classmember{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{SetComputeDivergence}/\classmember{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{SetDivergenceName}.
  The field will be a cell field unless \classmember{ComputePointGradient} is enabled.
  The input array must have 3 components in order to compute this.
  The default is off.
\item[\classmember{SetComputeVorticity}/\classmember{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{SetVorticityName}.
  The field will be a cell field unless \classmember{ComputePointGradient} is enabled.
  The input array must have 3 components in order to compute this.
  The default is off.
\item[\classmember{SetComputeQCriterion}/\classmember{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{SetQCriterionName}.
  The field will be a cell field unless \classmember{ComputePointGradient} is enabled.
  The input array must have 3 components in order to compute this.
  The default is off.
\item[\classmember{SetComputeGradient}/\classmember{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{SetColumnMajorOrdering}/\classmember{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{SetComputeGradient} is enabled.
\item[\classmember{SetDivergenceName}/\classmember{GetDivergenceName}]
  Specifies the output cell normals field name.
  The default is ``Divergence''.
\item[\classmember{SetVorticityName}/\classmember{GetVorticityName}]
  Specifies the output Vorticity field name.
  The default is ``Vorticity''
\item[\classmember{SetQCriterionName}/\classmember{GetQCriterionName}]
  Specifies the output Q-Criterion field name.
  The default is ``QCriterion''.
  \commoncellfieldfiltermethods
\end{description}

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

\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{SetOutputFieldName} method.

In addition the standard \classmember{SetOutputFieldName} and \classmember{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{SetOutputFieldName} method.

\textidentifier{PointElevation} provides the following methods.

\begin{description}
\item[\classmember{SetLowPoint}/\classmember{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{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{SetOutputFieldName} method.

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

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

\textidentifier{SurfaceNormals} provides the following methods.

\begin{description}
\item[\classmember{SetGenerateCellNormals}/\classmember{GetGenerateCellNormals}]
  Specifies whether the cell normals should be generated.
\item[\classmember{SetGeneratePointNormals}/\classmember{GetGeneratePointNormals}]
  Specifies whether the point normals should be generated.
\item[\classmember{SetNormalizeCellNormals}/\classmember{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{SetCellNormalsName}/\classmember{GetCellNormalsName}]
  Specifies the output cell normals field name.
\item[\classmember{SetPointNormalsName}/\classmember{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{SetActiveField} method.
The default name for the output field is ``magnitude'', but that can be overridden as always using the \classmember{SetOutputFieldName} method.

\textidentifier{VectorMagnitude} provides the following methods.

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

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


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


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

\newcommand{\commondatasetfiltermethods}{
\item[\classmember{SetActiveCellSetIndex}/\classmember{GetActiveCellSetIndex}]
  Specifies the index for the cell set to use from the data set provided to the \classmember{Execute} method.
  The default index is 0, which is the first cell set.
\item[\classmember{SetActiveCoordinateSystem}/\classmember{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{SetActiveCellSetIndex}.
Likewise, \classmember{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{Execute} method.
When calling \classmember{Execute} a \vtkmcont{DataSet} or \vtkmcont{MultiBlock} object with the input data is provided as an argument.
The \classmember{Execute} method returns a \textidentifier{DataSet} or \textidentifier{MultiBlock} object (matching the type of the input to \classmember{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\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}

\textidentifier{CleanGrid} provides the following methods.

\begin{description}
\item[\classmember{SetCompactPointFields}/\classmember{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.
  If false, then the output coordinate systems will be a shallow copy of the input coordinate systems.
  \commondatasetfiltermethods
\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.

\textidentifier{ExternalFaces} provides the following methods.

\begin{description}
\item[\classmember{SetCompactPoints}/\classmember{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{SetPassPolyData}/\classmember{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{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{SetNumberOfDivisions}/\classmember{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[\classmember{SetActiveField}/\classmember{GetActiveFieldName}]
  Specifies the name of the field to use as input.
\item[\classmember{SetUseCoordinateSystemAsField}/\classmember{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[\classmember{SetActiveCoordinateSystem}/\classmember{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[\classmember{SetActiveCellSetIndex}/\classmember{GetActiveCellSetIndex}]
  Specifies the index for the cell set to use from the data set provided to the \classmember{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{SetActiveField} method.
The argument to \classmember{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{SetActiveCellSetIndex}.
Likewise, \classmember{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{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{Execute} method.
When calling \classmember{Execute} a \vtkmcont{DataSet} or \vtkmcont{MultiBlock} object with the input data is provided as an argument.
The \classmember{Execute} method returns a \textidentifier{DataSet} or \textidentifier{MultiBlock} object (matching the type of the input to \classmember{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{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.

\textidentifier{MarchingCubes} provides the following methods.

\begin{description}
\item[\classmember{SetIsoValue}/\classmember{GetIsoValue}]
  Specifies the value on which to extract the contour.
  The contour will be the surface where the field (provided to \classmember{Execute}) is equal to this value.
\item[\classmember{SetMergeDuplicatePoints}/\classmember{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{SetGenerateNormals}/\classmember{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{SetComputeFastNormalsForStructured}/\classmember{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{SetComputeFastNormalsForUnstructured}/\classmember{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{SetNormalArrayName}/\classmember{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}

\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{Execute}) is not between a
range of values.

\textidentifier{Threshold} provides the following methods.

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

\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{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{SetActiveField} takes the name of the field as an argument.
However, \classmember{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{SetUseCoordinateSystemAsField} method with a true flag.
Since a \textidentifier{DataSet} can have multiple coordinate systems, you can select the desired coordinate system with \classmember{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{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{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{SetFieldsToPass}.

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

Or you can provide a list of fields to pass by giving \classmember{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{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|)}
