% -*- 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 described in Chapter\ref{chap:DataSet}.

\begin{didyouknow}
  The structure of filters in \VTKm 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, \VTKm 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 \VTKm.

Different filters will be used in different ways, but the basic operation of all filters is to instantiate the filter class, set the state parameters on the filter object, and then call the filter's \classmember*{Filter}{Execute} method.
The \classmember*{Filter}{Execute} method takes a \vtkmcont{DataSet} and returns a new \textidentifier{DataSet}, which contains the modified data.
The \classmember*{Filter}{Execute} method can alternately take a \vtkmcont{PartitionedDataSet} object, which is a composite of \textidentifier{DataSet} objects.
In this case \classmember*{Filter}{Execute} will return another \textidentifier{PartitionedDataSet} object.

The following example provides a simple demonstration of using a filter.
It specifically uses the point elevation filter to estimate the air pressure at each point based on its elevation.

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

We see that this example follows the previously described proceedure of constructing the filter (line \ref{ex:PointElevation.cxx:Construct}), setting the state parameters (lines \ref{ex:PointElevation.cxx:SetStateStart}--\ref{ex:PointElevation.cxx:SetStateEnd}), and finally executing the filter on a \textidentifier{DataSet} (line \ref{ex:PointElevation.cxx:Execute}).

Every \vtkmcont{DataSet} object contains a list of \index{field}\keyterm{fields}, which describe some numerical value associated with different parts of the data set in space.
Fields often represent physical properties such as temperature, pressure, or velocity.
Fields are identified with string names.
There are also special fields called coordinate systems that describe the location of points in space.
Field are mentioned here because they are often used as input data to the filter's operation and filters often generate new fields in the output.
This is the case in Example \ref{ex:PointElevation}.
In line \ref{ex:PointElevation.cxx:SetInputField} the coordinate system is set as the input field and in line \ref{ex:PointElevation.cxx:SetOutputField} the name to use for the generated output field is selected.

\section{Provided Filters}

\VTKm comes with the implementation of many filters.

% These commands are used in the bottom of a description environment used for methods on filters. All should provide whichever ones make the most sense. All these commands take an optional argument that has a list of methods to supress (i.e. _not_ document) for those that are not relevant to the filter or should be documented in a different way.

% This has the base methods available on all filters.
\NewDocumentCommand{\commonfiltermethods}{O{}}{
  \IfSubStr{#1}{Execute}{}{
  \item[\textcode{Execute}]
    Takes a data set, executes the filter on a device, and returns a data set that contains the result.
  }
  \IfSubStr{#1}{FieldsToPass}{}{
  \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.
  }
}

\NewDocumentCommand{\commonfieldfiltermethods}{O{}}{
  \IfSubStr{#1}{ActiveField}{}{
  \item[\textcode{SetActiveField}/\textcode{GetActiveFieldName}]
    Specifies the name of the field to use as input.
  }
  \IfSubStr{#1}{UseCoordinateSystemAsField}{}{
  \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.
  }
  \IfSubStr{#1}{ActiveCoordinateSystem}{}{
  \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.
  }
  \IfSubStr{#1}{OutputFieldName}{}{
  \item[\textcode{SetOutputFieldName}/\textcode{GetOutputFieldName}]
    Specifies the name of the output field generated.
  }
  \commonfiltermethods[#1]
}

\NewDocumentCommand{\commondatasetfiltermethods}{O{}}{
  \IfSubStr{#1}{ActiveCoordinateSystem}{}{
  \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[#1]
}

\NewDocumentCommand{\commondatasetwithfieldfiltermethods}{O{}}{
  \IfSubStr{#1}{ActiveField}{}{
  \item[\textcode{SetActiveField}/\textcode{GetActiveFieldName}]
    Specifies the name of the field to use as input.
  }
  \IfSubStr{#1}{UseCoordinateSystemAsField}{}{
  \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.
  }
  \IfSubStr{#1}{ActiveCoordinateSystem}{}{
  \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[#1]
}


\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}
  \commonfieldfiltermethods
\end{description}

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


\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 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{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.
See Chapter \ref{chap:ImplicitFunctions} for more detail.
\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{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}
  \commonfieldfiltermethods
\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}
  \commonfieldfiltermethods
\end{description}

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

\index{connected components|)}


\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 to 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.
  \commonfieldfiltermethods
\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.
  \commonfieldfiltermethods
\end{description}

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

\index{coordinate system transform|)}


\subsection{Contour}
\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}.
The contouring/isosurface algorithm is implemented by \vtkmfilter{Contour}.

\textidentifier{Contour} provides the following methods.

\begin{description}
\item[\classmember*{Contour}{SetIsoValue}/\classmember*{Contour}{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*{Contour}{SetMergeDuplicatePoints}/\classmember*{Contour}{GetMergeDuplicatePoints}]
  Specifies whether coincident points in the data set should be merged.
  Because the contour filter (like all filters in \VTKm) 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*{Contour}{SetGenerateNormals}/\classmember*{Contour}{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*{Contour}{SetComputeFastNormalsForStructured}/\classmember*{Contour}{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*{Contour}{SetComputeFastNormalsForUnstructured}/\classmember*{Contour}{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*{Contour}{SetNormalArrayName}/\classmember*{Contour}{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|)}

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


\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{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{Extract Structured}

\index{extract structured|(}
\index{extract|(}

\vtkmfilter{ExtractStructured} is a filter that extracts a volume of interest (VOI)
from a structured data set. In addition the filter is able to subsample the
VOI while doing the extraction.

The output of this filter is a structured dataset. The filter treats input
data of any topological dimension (i.e., point, line, plane, or volume) and
can generate output data of any topological dimension.

Typical applications of this filter are to extract a slice from a volume
for image processing, subsampling large volumes to reduce data size, or
extracting regions of a volume with interesting data.

\textidentifier{ExtractStructured} provides the following methods.

\begin{description}
\item[\classmember*{ExtractStructured}{SetVOI}/\classmember*{ExtractStructured}{GetVOI}]
  Specifies what volume of interest (VOI) should be extracted by the filter.
  By default the VOI is the entire input.
\item[\classmember*{ExtractStructured}{SetSampleRate}/\classmember*{ExtractStructured}{GetSampleRate}]
  Specifies the sample rate of the VOI. Supports sub-sampling on a per dimension basis.
\item[\classmember*{ExtractStructured}{SetIncludeBoundary}/\classmember*{ExtractStructured}{GetIncludeBoundary}]
  Specifies if the VOI is inclusive or exclusive on the boundary of the VOI.
  \commondatasetfiltermethods
\end{description}

\index{extract|)}
\index{extract structured|)}


\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{Vec3ui\_8} values.
\item[{\classmember{FieldToColors}{RGBA}}]
  Output colors are represented as RGBA values with each component represented by an unsigned byte.
  Specifically, these are \vtkm{Vec4ui\_8} 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{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{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}.
  \commondatasetfiltermethods
\end{description}

\index{ghost cell!remove|)}


\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 \VTKm 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''.
  \commonfieldfiltermethods
\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.
  \commonfieldfiltermethods
\end{description}

\index{histogram|)}


\subsection{Lagrangian Coherent Structures}

\index{LCS|see{lagrangian coherent structures}}
\index{finite time Lyapunov exponent|see{FTLE}}
\index{filter!lagrangian coherent structures|(}
\index{filter!FTLE|(}
\index{flow!lagrangian coherent structures|(}
\index{flow!FTLE|(}
\index{lagrangian coherent structures|(}
\index{FTLE|(}

Lagrangian coherent structures (LCS) are distinct structures present in a flow filed that have a major influence over nearby trajectories over some interval of time.
Some of these structures may be sources, sinks, saddles, or vortices in the flow field.
Identifying Lagrangian coherent structures is part of advanced flow analysis and is an important part of studying flow fields.
These structures can be studied by calculating the finite time Lyapunov exponent (FTLE) for a flow field at various locations, usually over a regular grid encompassing the entire flow field.
If the provided input dataset is structured, then by default the points in this dataset will be used as seeds for advection.

The \vtkmfilter{LagrangianStructures} filter is used to compute the FTLE of a flow field.
\textidentifier{LagrangianStructures} has the following methods.

\begin{description}
\item[\classmember*{LagrangianStructures}{SetStepSize}/\classmember*{LagrangianStructures}{GetStepSize}]
  Set or retrieve the step size for a single advection step for the particles used to calculate the FTLE.
\item[\classmember*{LagrangianStructures}{SetNumberOfSteps}/\classmember*{LagrangianStructures}{GetNumberOfSteps}]
  Set or retrieve the maximum number of steps a particle is allowed to traverse while calculating the FTLE field.
\item[\classmember*{LagrangianStructures}{SetAdvectionTime}/\classmember*{LagrangianStructures}{GetAdvectionTime}]
  Set or retrieve the time interval of advection.
  The FTLE field is calculated over some finite time, and the advection time determines that interval of time used.
\item[\classmember*{LagrangianStructures}{SetUseAuxiliaryGrid}/\classmember*{LagrangianStructures}{GetUseAuxiliaryGrid}]
  Set or retrieve the flag to use auxiliary grids.
  When this flag is off (the default), then the points of the mesh representing the vector field are advected and used for computing the FTLE.
  However, if the mesh is too coarse, the FTLE will likely be inaccurate.
  Or if the mesh is unstructured the FTLE may be less efficient to compute.
  When this flag is on, an auxiliary grid of uniformly spaced points is used for the FTLE computation.
\item[\classmember*{LagrangianStructures}{SetAuxiliaryGridDimensions}/\classmember*{LagrangianStructures}{GetAuxiliaryGridDimensions}]
  Set or retrieve the dimensions of the auxiliary grid for FTLE calculation.
  Seeds for advection will be placed along the points of this auxiliary grid.
  This option has no effect unless the UseAuxiliaryGrid option is on.
\item[\classmember*{LagrangianStructures}{SetUseFlowMapOutput}/\classmember*{LagrangianStructures}{GetUseFlowMapOutput}]
  Set or retrieve the flag to use flow maps instead of advection.
  If the start and end points for FTLE calculation are known already, advection is an unnecessary step.
  This flag allows users to bypass advection, and instead use a precalculated flow map.
  By default this option is off.
\item[\classmember*{LagrangianStructures}{SetFlowMapOutput}/\classmember*{LagrangianStructures}{GetFlowMapOutput}]
  Set or retrieve the array representing the flow map output to be used for FTLE calculation.
\item[\classmember*{LagrangianStructures}{SetOutputFieldName}/\classmember*{LagrangianStructures}{GetOutputFieldName}]
  Set or retrieve the name of the output field in the dataset returned by the \textidentifier{LagrangianStructures} filter.
  By default, the field will be names ``FTLE''.
  \commondatasetfiltermethods
\end{description}

\index{FTLE|)}
\index{lagrangian coherent structures|)}
\index{flow!FTLE|)}
\index{flow!lagrangian coherent structures|)}
\index{filter!FTLE|)}
\index{filter!lagrangian coherent structures|)}


\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}
  \commonfieldfiltermethods
\end{description}

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

\subsection{Point Elevation}
\label{sec:PointElevation}

\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.
By default, produced field replaces the coordinate system.

\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$0 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.
\item[\classmember*{PointTransform}{SetChangeCoordinateSystem}/\classmember*{PointTransform}{GetChangeCoordinateSystem}]
  When this flag is on, the default, the coordiante system in the output \textidentifier{DataSet} is replaced with the transformed point coordinates .
  \commonfieldfiltermethods
\end{description}

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


\subsection{Stream Tracing}

\index{filter!stream tracing|(}
\index{flow!stream tracing|(}
\index{stream tracing|(}

Stream tracing is a visualization technique used to characterize the structure of flow.
The flow itself is defined by a vector field of velocities.
Stream tracing works by following the path taken by the flow.
There are multiple ways in which to represent flow in this manner, and consequently \VTKm contains several filters that trace streams in different ways.


\subsubsection{Streamlines}

\index{filter!streamlines|(}
\index{flow!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.
  \commondatasetwithfieldfiltermethods
\end{description}

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

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


\subsubsection{Stream Surface}

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

A \keyterm{stream surface} is defined as a continous sourface that is everywhere tangent
to a specified vector field. \vtkmfilter{StreamSurface} computes a stream surface from a set of input
points and the vector field of the input data set. The stream surface is created by creating streamlines
from each input point and then connecting adjacent streamlines with a series of triangles.

\vtkmfilter{StreamSurface} provides the following methods.

\begin{description}
\item[\classmember*{StreamSurface}{SetSeeds}]
  Specifies the seed locations for the edge of the stream surface.
\item[\classmember*{StreamSurface}{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*{StreamSurface}{SetNumberOfSteps}]
  Specifies the number of integration steps to be performed on each seed.
  \commondatasetwithfieldfiltermethods
\end{description}

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

\index{streamsurface|)}
\index{flow!streamsurface|)}
\index{filter!streamsurface|)}


\subsubsection{Pathlines}

\index{filter!streamlines|(}
\index{flow!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.
  \commondatasetwithfieldfiltermethods
\end{description}

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

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

\index{stream tracing|)}
\index{flow!stream tracing|)}
\index{filter!stream tracing|)}


\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 point and cell normals may be oriented to a point outside of the manifold surface by setting the \index{surface normals!auto orient}\index{normals!auto orient}auto orient normals option (\classmember*{SurfaceNormals}{SetAutoOrientNormals}), or they may point inward by also setting \index{surface normals!flip}\index{normals!flip}flip normals (\classmember*{SurfaceNormals}{SetFlipNormals}) to true.
Triangle vertices will be wound counter-clockwise around the cell normals when the \index{surface normals!consistency}\index{normals!consistency}consistency option (\classmember*{SurfaceNormals}{SetConsistency}) is enabled.
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.
  This is off by default.
\item[\classmember*{SurfaceNormals}{SetGeneratePointNormals}/\classmember*{SurfaceNormals}{GetGeneratePointNormals}]
  Specifies whether the point normals should be generated.
  This is on by default.
\item[\classmember*{SurfaceNormals}{SetNormalizeCellNormals}/\classmember*{SurfaceNormals}{GetNormalizeCellNormals}]
  Specifies whether cell normals should be normalized (made unit length).
  This is on by default.
  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}{SetAutoOrientNormals}/\classmember*{SurfaceNormals}{GetAutoOrientNormals}]
  If true, any generated point and/or cell normals will be oriented to point outwards from the surface.
  This requires a closed manifold surface or else the behavior is undefined.
  This is off by default.
\item[\classmember*{SurfaceNormals}{SetFlipNormals}/\classmember*{SurfaceNormals}{GetFlipNormals}]
  When AutoOrientNormals is true, this option will reverse the point and cell normals to point inward.
  This is off by default.
\item[\classmember*{SurfaceNormals}{SetConsistency}/\classmember*{SurfaceNormals}{GetConsistency}]
  When GenerateCellNormals is true, this option will ensure that the triangle vertices in the output dataset are wound counter-clockwise around the generated cell normal.
  This only affects triangles.
  This is on by default.
\item[\classmember*{SurfaceNormals}{SetCellNormalsName}/\classmember*{SurfaceNormals}{GetCellNormalsName}]
  Specifies the output cell normals field name.
  If no cell or point normal name is specified, ``Normals'' is used.
\item[\classmember*{SurfaceNormals}{SetPointNormalsName}/\classmember*{SurfaceNormals}{GetPointNormalsName}]
  Specifies the output point normals field name.
  If no cell or point normal name is specified, ``Normals'' is used.
  \commonfieldfiltermethods
\end{description}

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


\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{Tube}

\index{tube|(}

\vtkmfilter{Tube} generates a tube around each line and polyline in the input data set.
The radius, number of sides, and end capping can be specified for each tube.
The orientation of the geometry of the tube are computed automatically using a heuristic to minimize
the twisting along the input data set.

\textidentifier{Tube} provides the following methods.

\begin{description}
\item[\classmember*{Tube}{SetRadius}]
  Specifies the radius of the tube.
\item[\classmember*{Tube}{SetNumberOfSides}]
  Specifies the number of sides for the tube geometry.
\item[\classmember*{Tube}{SetCapping}]
  Specifies if the ends of the tube should be capped.
  \commondatasetfiltermethods
\end{description}

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

\index{tube|)}


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

\textidentifier{VertexClustering} provides the following methods.

\begin{description}
\item[\classmember*{VertexClustering}{SetNumberOfDivisions}/\classmember*{VertexClustering}{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}

\vtkmlisting[ex:VertexClustering]{Using \textidentifier{VertexClustering}.}{VertexClustering.cxx}

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


\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).
  \commonfieldfiltermethods
\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).
  \commonfieldfiltermethods
\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|)}


\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|)}
