% -*- 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*{NewFilter}{Execute} method.
The \classmember*{NewFilter}{Execute} method takes a \vtkmcont{DataSet} and returns a new \textidentifier{DataSet}, which contains the modified data.
The \classmember*{NewFilter}{Execute} method can alternately take a \vtkmcont{PartitionedDataSet} object, which is a composite of \textidentifier{DataSet} objects.
In this case \classmember*{NewFilter}{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 procedure 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.
Filters in \VTKm are divided into a collection of modules, each with its own namespace and library.
This section is organized by each filter module, each of which contains one or more filters that are related to each other.

% 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 and the active coordinate system is used instead.
  }
  \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]
}

% Obsolete in new filter structure (use \commonfiltermethods)
\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]
}

% Obsolete in new filter structure (use \commonfieldfiltermethods)
\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{Cleaning Grids}

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

The \vtkmfilter[clean\_grid]{} module contains filters that resolve issues with mesh structure.
This could include finding and merging coincident points, removing degenerate cells, or converting the grid to a known type.

\subsubsection{Clean Grid}

\vtkmfilter[clean\_grid]{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[clean\_grid]{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.
\item[\textcode{SetActiveCoordinateSystem}/\textcode{GetActiveCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use when finding coincident points.
  The default index is 0, which is the first coordinate system.
  % Although technically clean grid is a "field filter", the only methods that have any effect deal with the active coordinate system. It's easier to just document that here then suppress unused methods in \commonfieldfiltermethods.
  \commonfiltermethods
\end{description}

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


\subsection{Connected Components}

\index{connected components|(}
\index{filter!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.

The \vtkmfilter[connected\_components]{} module contains filters that find groups of cells that are connected.
There are different ways to define what it means to be connected.
One way is to use the topological connections of the cells.
That is, two cells that share a point, edge, or face are connected.
Another way is to use a field that classifies each cell, and cells are only connected if they have the same classification.

\subsubsection{Cell Connectivity}

\index{connected components!cell|(}

The \vtkmfilter[connected\_components]{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''.

\textidentifier{CellSetConnectivity} provides the following methods.

\begin{description}
\item[\textcode{SetOutputFieldName}/\textcode{GetOutputFieldName}]
  Specifies the name of the output field generated.
  \commonfiltermethods
\end{description}

\index{connected components!cell|)}

\subsubsection{Classification Field on Image Data}

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

The \vtkmfilter[connected\_components]{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 26 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[UseCoordinateSystemAsField ActiveCoordinateSystem]
\end{description}

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

\index{filter!connected components|)}
\index{connected components|)}


\subsection{Contouring}
\label{sec:FilterContouring}

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

The \vtkmfilter[contour]{} module contains filters that extract regions that match some field or spatial criteria.
Unlike entity extraction filters (Section \ref{sec:FilterEntityExtraction}), the geometry will be clipped or sliced to extract the exact matching region.
(In contrast, entity extraction filters will pull unmodified points, edges, faces, or cells from the input.)

\subsubsection{Contour}
\label{sec:Isosurface}
\label{sec:Contour}

\index{filter!contour|(}
\index{filter!isosurface|(}
\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]{Contour}.

\textidentifier{Contour} provides the following methods.

\begin{description}
\item[\classmember*{Contour}{SetIsoValue}]
  Specifies the value on which to extract a contour.
  Multiple iso values can be specified at once.
  The first parameter to \classmember*{Contour}{SetIsoValue} is the index of the iso value (starting at index 0) and the second is the value to set.
  If only one iso value is needed, the index does not need to be specified.
\item[\classmember*{Contour}{GetIsoValue}]
  Returns the iso value for a given index.
\item[\classmember*{Contour}{SetNumberOfIsoValues}]
  Sets the number of iso values to create contours from.
  If the number of iso values is not specified, the number is automatically set to accommodate the largest index given to \classmember*{Contour}{SetIsoValue}.
\item[\classmember*{Contour}{GetNumberOfIsoValues}]
  Returns the number of iso values (and consequently the number of contours to be created).
\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.
  \commonfieldfiltermethods[OutputFieldName UseCoordinateSystemAsField]
\end{description}

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

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

\subsubsection{Slice}

A slice operation intersects a mesh with a surface.
The \vtkmfilter[contour]{Slice} filter uses a \vtkm{ImplicitFunctionGeneral} to specify an implicit surface to slice on.
A plane is a common thing to slice on, but other surfaces are available.
See Chapter \ref{chap:ImplicitFunctions} for information on implicit functions.

\textidentifier{Slice} provides the following methods.

\begin{description}
\item[\classmember*{Slice}{SetImplicitFunction}/\classmember*{Slice}{GetImplicitFunction}]
  Specifies the surface to intersect the input data as an implicit function.
  See Chapter \ref{chap:ImplicitFunctions} for documentation on implicit functions provided by \VTKm.
\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.
\item[\textcode{SetActiveCoordinateSystem}/\textcode{GetActiveCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use when computing normals and other geometric features.
  The default index is 0, which is the first coordinate system.
  \commonfiltermethods
\end{description}

\subsubsection{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[contour]{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 later.)

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}, which extracts only the surface of that iso-value.
\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.

  \commonfieldfiltermethods[UseCoordinateSystemAsField ActiveCoordinateSystem OutputFieldName]
\end{description}

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

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


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

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

The \vtkmfilter[contour]{ClipWithImplicitFunction} function takes an implicit function and removes all parts of the data that are inside (or outside) that function.
See Chapter \ref{chap:ImplicitFunctions} for more detail on how implicit functions are represented in \VTKm.
(A companion filter that discards a region of the data based on the value of a scalar field is described previously.)

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.
  See Chapter \ref{chap:ImplicitFunctions} for documentation on implicit functions provided by \VTKm.

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

\item[\textcode{SetActiveCoordinateSystem}/\textcode{GetActiveCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use when comparing spatial locations for the implicit function.
  The default index is 0, which is the first coordinate system.
  \commonfiltermethods

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

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


\subsection{Density Estimation}

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

Density estimation takes a collection of samples and estimates the density of the samples in each part of the domain (or estimate the probabilty that a sample would be at a location in the domain).
The domain of samples could be a physical space, such as with particle density, or in an abstract place, such as with a histogram.
The \vtkmfilter[density\_estimate]{} module contains filters that estimate density in a variety of ways.

\fix{Entropy, NDEntropy, and NDHistogram are not documented.}

\subsubsection{Histogram}

\index{histogram|(}
\index{density!histogram|(}

The \vtkmfilter[density\_estimate]{Histogram} filter computes a histogram of a given scalar field.
The histogram divides the range of the field into an even number of bins and counts the number of instances occur in each bin.

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 then the global range of the field is computed during filter execution and that range is used.
\item[\classmember*{Histogram}{SetNumberOfBins}/\classmember*{Histogram}{GetNumberOfBins}]
  Specifies the number of bins to divide the range.
  The range of data will be split evenly into this number of bins, and the number of items landing in each bin will be counted.
  The default number of bins is 10.
\item[\classmember*{Histogram}{GetBinDelta}]
  Get the size of each bin from the last computed field.
  This value is only valid after a call to \classmember*{NewFilter}{Execute}.
\item[\classmember*{Histogram}{GetComputedRange}]
  Get the range used during the last call to \classmember*{NewFilter}{Execute}.
  If \classmember*{Histogram}{SetRange} was called, then this range will be returned.
  Otherwise, the computed range is returned.
  This value is only valid after a call to \classmember*{NewFilter}{Execute}.
  \commonfieldfiltermethods[UseCoordinateSystemAsField ActiveCoordinateSystem]
\end{description}

\index{density!histogram|)}
\index{histogram|)}

\index{particle density|(}
\index{density!particle|(}

\subsubsection{Nearest Grid Point}

\index{nearest grid point|(}
\index{particle density!nearest grid point|(}
\index{density!particle!nearest grid point|(}

The \vtkmfilter[density\_estimate]{ParticleDensityNearestGridPoint} filter defines a 3D grid of bins.
It then takes from the input a collection of particles, identifies which bin each particle lies in, and sums some attribute from a field of the input (or the particles can simply be counted).
Once the sum of the attribute is computed for each grid cell, it is optionally divided by the volume of the cell.
Thus, the density will be computed as the units of the scalar field per the cubic units of the coordinate system.

This operation is helpful in the analysis of particle-based simulation where the data often requires \keyterm{conversion} or \keyterm{deposition} of particles' attributes, such as mass, to an overlaying mesh.
This allows further identification of regions of interest based on the spatial distribution of particles attributes, for example, high density regions could be considered as \keyterm{clusters} or \keyterm{halos} while low density regions could be considered as \keyterm{bubbles} or \keyterm{cavities} in the particle data.

Since there is no specific \textidentifier{CellSet} for particles in \VTKm, \textidentifier{ParticleDensityNearestGridPoint} treats the \textidentifier{CoordinateSystem} of the input \textidentifier{DataSet} as the positions of the particles while ignoring the details of the \textidentifier{CellSet}.
Particles are infinitesimal in size with finite mass (or other scalar attributes such as charge).
The filter estimates density by imposing a regular grid of bins.

\textidentifier{ParticleDensityNearestGridPoint} provides the following methods.

\begin{description}
\item[\classmember*{ParticleDensityNearestGridPoint}{SetActiveField}/\classmember*{ParticleDensityNearestGridPoint}{GetActiveFieldName}]
  Specify the particle attribute to be deposited.
\item[\classmember*{ParticleDensityNearestGridPoint}{SetDivideByVolume}/\classmember*{ParticleDensityNearestGridPoint}{GetDivideByVolume}]
  If you just want a sum of the attribute in each cell, turn off the DivideByVolume feature of this filter with \textcode{SetDivideByVolume(false)}.
\item[\classmember*{ParticleDensityNearestGridPoint}{SetComputeNumberDensity}/\classmember*{ParticleDensityNearestGridPoint}{GetComputeNumberDensity}]
  Simply count the number of particles in each cell instead of summing a field variable by calling \textcode{SetComputeNumberDensity(true)}.
\item[\classmember*{ParticleDensityNearestGridPoint}{SetDimension}/\classmember*{ParticleDensityNearestGridPoint}{GetDimension}]
  Specify the number of bins to estimate particles in with a \vtkm{Id3}.
  The numbers specify the number of \emph{bins} (i.e. cells in the output mesh) in each dimensions, not the number of points in the output mesh.
\item[\classmember*{ParticleDensityNearestGridPoint}{SetOrigin}/\classmember*{ParticleDensityNearestGridPoint}{GetOrigin}]
  Specify the minimum (lower-left) corner of the domain of density estimation.
\item[\classmember*{ParticleDensityNearestGridPoint}{SetSpacing}/\classmember*{ParticleDensityNearestGridPoint}{GetSpacing}]
  Specify the spacing of the grid points used to form the grid for density estimation.
  The size of each bin is equivalent to the spacing.
\item[\classmember*{ParticleDensityNearestGridPoint}{SetBounds}/\classmember*{ParticleDensityNearestGridPoint}{GetBounds}]
  Specify the domain of space to estimate point density as a \vtkm{Bounds} object.
  \classmember*{ParticleDensityNearestGridPoint}{SetDimension} must be called before the bounds are set.
  Calling \classmember*{ParticleDensityNearestGridPoint}{SetDimension} will change the ranges of the bounds.
\commonfieldfiltermethods[SetActiveField GetActiveField UseCoordinateSystemAsField FieldsToPass]
\end{description}

\index{density!particle!nearest grid point|)}
\index{particle density!nearest grid point|)}
\index{nearest grid point|)}

\subsubsection{Cloud in Cell}

\index{cloud in cell|(}
\index{particle density!cloud in cell|(}
\index{density!particle!cloud in cell|(}

The \vtkmfilter[density\_estimate]{ParticleDensityCloudInCell} filter defines a 3D grid of bins.
It then takes from the input a collection of particles, identifies which bin each particle lies in, and then redistributes each particle's attribute to the 8 vertices of the containing bin.
The filter then sums up all the contributions of particles for each vertex in the grid.
This contribution is either an attribute value from an input field or a simple count.
This creates a point centered density field.
Once the sum of the attribute is computed for each grid points, it is optionally divided by the volume of each cell.
Thus, the density will be computed as the units of the scalar field per the cubic units of the coordinate system.

This operation is helpful in the analysis of particle-based simulation where the data often requires \keyterm{conversion} or \keyterm{deposition} of particles' attributes, such as mass, to an overlaying mesh.
This allows further identification of regions of interest based on the spatial distribution of particles attributes, for example, high density regions could be considered as \keyterm{clusters} or \keyterm{halos} while low density regions could be considered as \keyterm{bubbles} or \keyterm{cavities} in the particle data.

Since there is no specific \textidentifier{CellSet} for particles in \VTKm, \textidentifier{ParticleDensityCloudInCell} treats the \textidentifier{CoordinateSystem} of the input \textidentifier{DataSet} as the positions of the particles while ignoring the details of the \textidentifier{CellSet}.
Particles are infinitesimal in size with finite mass (or other scalar attributes such as charge).
The filter estimates density by imposing a regular grid of bins.

\textidentifier{ParticleDensityCloudInCell} provides the following methods.

\begin{description}
\item[\classmember*{ParticleDensityCloudInCell}{SetActiveField}/\classmember*{ParticleDensityCloudInCell}{GetActiveFieldName}]
  Specify the particle attribute to be deposited.
\item[\classmember*{ParticleDensityCloudInCell}{SetDivideByVolume}/\classmember*{ParticleDensityCloudInCell}{GetDivideByVolume}]
  If you just want a sum of the attribute in each cell, turn off the DivideByVolume feature of this filter with \textcode{SetDivideByVolume(false)}.
\item[\classmember*{ParticleDensityCloudInCell}{SetComputeNumberDensity}/\classmember*{ParticleDensityCloudInCell}{GetComputeNumberDensity}]
  Simply count the number of particles in each cell instead of summing a field variable by calling \textcode{SetComputeNumberDensity(true)}.
\item[\classmember*{ParticleDensityCloudInCell}{SetDimension}/\classmember*{ParticleDensityCloudInCell}{GetDimension}]
  Specify the number of bins to estimate particles in with a \vtkm{Id3}.
  The numbers specify the number of \emph{bins} (i.e. cells in the output mesh) in each dimensions, not the number of points in the output mesh.
\item[\classmember*{ParticleDensityCloudInCell}{SetOrigin}/\classmember*{ParticleDensityCloudInCell}{GetOrigin}]
  Specify the minimum (lower-left) corner of the domain of density estimation.
\item[\classmember*{ParticleDensityCloudInCell}{SetSpacing}/\classmember*{ParticleDensityCloudInCell}{GetSpacing}]
  Specify the spacing of the grid points used to form the grid for density estimation.
  The size of each bin is equivalent to the spacing.
\item[\classmember*{ParticleDensityCloudInCell}{SetBounds}/\classmember*{ParticleDensityCloudInCell}{GetBounds}]
  Specify the domain of space to estimate point density as a \vtkm{Bounds} object.
  \classmember*{ParticleDensityCloudInCell}{SetDimension} must be called before the bounds are set.
  Calling \classmember*{ParticleDensityCloudInCell}{SetDimension} will change the ranges of the bounds.
\commonfieldfiltermethods[SetActiveField GetActiveField UseCoordinateSystemAsField FieldsToPass]
\end{description}

\index{density!particle!cloud in cell|)}
\index{particle density!cloud in cell|)}
\index{nearest grid point|)}

\index{density!particle|)}
\index{particle density|)}

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


\subsection{Entity Extraction}
\label{sec:FilterEntityExtraction}

\index{entity extraction|(}
\index{filter!entity extraction|(}

\VTKm contains a collection of filters that extract a portion of one \textidentifier{DataSet} and construct a new \textidentifier{DataSet} based on that portion of the geometry.
These filters are collected in the \vtkmfilter[entity\_extraction]{} module.

\subsubsection{External Faces}

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

\vtkmfilter[entity\_extraction]{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.'')
  \commonfiltermethods
\end{description}

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

\subsubsection{External Geometry}

\index{external geometry|(}
\index{entity extraction!external geometry|(}

The \vtkmfilter[entity\_extraction]{ExternalGeometry} filter extracts all of the cells in a \textidentifier{DataSet} that is inside or outside of an implicit function.
Implicit functions are described in Chapter \ref{chap:ImplicitFunctions}.
They define a function in 3D space that follow a geometric shape.
The inside of the implicit function is the region of negative values.

\textidentifier{ExternalGeometry} differs from \textidentifier{ClipWithImplicitFunction} in that the clip filter will subdivide boundary cells into new cells whereas this filter will not.
Thus, the output of \textidentifier{ExternalGeometry} will produce a more ``crinkly'' output.

\textidentifier{ExternalGeometry} provides the following methods.

\begin{description}
\item[\classmember*{ExternalGeometry}{SetImplicitFunction}/\classmember*{ExternalGeometry}{GetImplicitFunction}]
  Specifies the implicit function that specifies the region of space to extract geometry from.
\item[\classmember*{ExternalGeometry}{SetExtractInside}/\classmember*{ExternalGeometry}{GetExtractInside}]
  Specify whether to extract the geometry that is on the inside of the implicit function (where the function is less than 0) or the outside (where the function is greater than 0).
  This flag is true by default (i.e., the interior of the implicit function will be extracted).
\item[\classmember*{ExtractGeometry}{ExtractInsideOn}\classmember*{ExtractGeometry}{ExtractInsideOff}]
  Set the extract inside flag on (true) or off (false).
\item[\classmember*{ExtractGeometry}{SetExtractBoundaryCells}/\classmember*{ExtractGeometry}{GetExtractBoundaryCells}]
  The implicit function used to extract geometry is likely to intersect some of the cells of the input.
  If this flag is true, then any cells intersected by the implicit function are extracted and included in the output.
  This flag is false by default.
\item[\classmember*{ExtractGeometry}{ExtractBoundaryCellsOn}/\classmember*{ExtractGeometry}{ExtractBoundaryCellsOff}]
  Set the Extract boundary cells flag to on (true) or off (false).
\item[\classmember*{ExtractGeometry}{SetExtractOnlyBoundaryCells}/\classmember*{ExtractGeometry}{GetExtractOnlyBoundaryCells}]
  Specify whether to extract only the cells intersected by the implicit function (where the function equals 0).
  By default this flag is off.
\item[\classmember*{ExtractGeometry}{ExtractOnlyBoundaryCellsOn}/\classmember*{ExtractGeometry}{ExtractOnlyBoundaryCellsOff}]
  Set the extract only boundary cells flag to on (true) or off (false).
\item[\textcode{SetActiveCoordinateSystem}/\textcode{GetActiveCoordinateSystemIndex}]
  Specifies the index of which coordinate system to use for the positions of the geometry.
  The coordinate system should match that of the implicit function.
  \commonfiltermethods
\end{description}

\index{entity extraction!external geometry|)}
\index{external geometry|)}

\subsubsection{Extract Structured}

\index{extract structured|(}
\index{entity extraction!extract structured|(}

\vtkmfilter[entity\_extraction]{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{entity extraction!extract structured|)}
\index{extract|)}

\subsubsection{Ghost Cell Removal}

\index{ghost cell!remove|(}
\index{entity extraction!ghost cells|(}

\vtkmfilter[entity\_extraction]{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 explicit 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}.
  \commonfiltermethods
\item[\textcode{SetActiveField}/\textcode{GetActiveFieldName}]
  Specifies the name of the field to use as the ghost cell levels.
\end{description}

\index{entity extraction!ghost cells|)}
\index{ghost cell!remove|)}

\subsubsection{Threshold}
\label{sec:Threshold}

\index{entity extraction!threshold|(}
\index{threshold|(}

A threshold operation removes topology elements from a data set that do not meet a specified criterion.
The \vtkmfilter[entity\_extraction]{Threshold} filter removes all cells where the a field is 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.
\item[\classmember*{Threshold}{SetAllInRange}/\classmember*{Threshold}{GetAllInRange}]
  When thresholding on a point field, each cell must consider the multiple values associated with all incident points.
  When this flag is false (the default), the cell is passed if \emph{any} of the incident points matches the threshold criteria.
  When this flag is true, the cell is passed only if \emph{all} the incident points match the threshold criteria.
  \commonfieldfiltermethods
\end{description}

\index{threshold|)}
\index{entity extraction!threshold|)}

\index{filter!entity extraction|)}
\index{entity extraction|)}


\subsection{Field Conversion}

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

Field conversion modifies a field of a \textidentifier{DataSet} to have roughly equivalent values but with a different structure.
These filters allow the field to be used in places where they otherwise would not be applicable.

\subsubsection{Cell Average}

\index{cell average|(}
\index{average|(}
\index{field conversion!cell average|(}

\vtkmfilter[field\_conversion]{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*{NewFilterField}{SetOutputFieldName} method.

\textidentifier{CellAverage} provides the following methods.

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

\index{field conversion!cell average|)}
\index{average|)}
\index{cell average|)}

\subsubsection{Point Average}

\index{point average|(}
\index{average|(}
\index{field conversion!point average|(}

\vtkmfilter[field\_conversion]{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.

\textidentifier{PointAverage} provides the following methods.

\begin{description}
  \commonfieldfiltermethods[UseCoordinateSystemAsField ActiveCoordinateSystem]
\end{description}

\index{field conversion!point average|)}
\index{average|)}
\index{point average|)}

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


\subsection{Field Transform}

\index{field transform|(}

\VTKm provides multiple filters to convert fields through some mathematical relationship.

\subsubsection{Cylindrical Coordinate System Transform}

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

\vtkmfilter[field\_transform]{CylindricalCoordinateTransform} 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 output coordinate system will be set to the new computed coordinates.

\textidentifier{CylindricalCoordinateTransform} provides the following methods.

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

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

\subsubsection{Field to Colors}

\index{field to colors|(}
\index{field transform!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.
These input modes are contained in \classmember{FieldToColors}{InputMode}.
\begin{description}
\item[{\classmember{FieldToColors::InputMode}{Scalar}}]
  Treat the field as a scalar field.
  It is an error to provide a field of any type that cannot be directly converted to a basic floating point number (such as a vector).
\item[{\classmember{FieldToColors::InputMode}{Magnitude}}]
  Given a vector field, take the magnitude of each field value before looking it up in the color table.
\item[{\classmember{FieldToColors::InputMode}{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.
These output modes are contained in \classmember{FieldToColors}{OutputMode}.
\begin{description}
\item[{\classmember{FieldToColors::OutputMode}{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::OutputMode}{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::InputMode}{Scalar}, \classmember{FieldToColors::InputMode}{Magnitude}, or \classmember{FieldToColors::InputMode}{Component} selectors described previously.
\item[\classmember*{FieldToColors}{SetMappingToScalar}]
  Sets the input mapping mode to scalar.
  Shortcut for \classmember*{FieldToColors}{SetMappingMode}\textcode{(}\vtkmfilter{FieldToColors::InputMode}[Scalar]\textcode{)}.
\item[\classmember*{FieldToColors}{SetMappingToMagnitude}]
  Sets the input mapping mode to vector.
  Shortcut for \classmember*{FieldToColors}{SetMappingMode}\textcode{(}\vtkmfilter{FieldToColors::InputMode}[Magnitude]\textcode{)}.
\item[\classmember*{FieldToColors}{SetMappingToComponent}]
  Sets the input mapping mode to component.
  Shortcut for \classmember*{FieldToColors}{SetMappingMode}\textcode{(}\vtkmfilter{FieldToColors::InputMode}[Component]\textcode{)}.
\item[\classmember*{FieldToColors}{IsMappingScalar}]
  Returns true if the input mapping mode is scalar (\classmember{FieldToColors::InputMode}{Scalar}).
\item[\classmember*{FieldToColors}{IsMappingMagnitude}]
  Returns true if the input mapping mode is magnitude (\classmember{FieldToColors::InputMode}{Magnitude}).
\item[\classmember*{FieldToColors}{IsMappingComponent}]
  Returns true if the input mapping mode is component (\classmember{FieldToColors::InputMode}{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::InputMode}{Component}.
\item[\classmember*{FieldToColors}{SetOutputMode}/\classmember*{FieldToColors}{GetOutputMode}]
  Specifies the output representation of colors.
  The value is one of the \classmember{FieldToColors::OutputMode}{RGB} or \classmember{FieldToColors::OutputMode}{RGBA} selectors described previously.
\item[\classmember*{FieldToColors}{SetOutputToRGB}]
  Sets the output representation to 8-bit RGB.
  Shortcut for \classmember*{FieldToColors}{SetOutputMode}\textcode{(}\vtkmfilter{FieldToColors::OutputMode}[RGB]\textcode{)}.
\item[\classmember*{FieldToColors}{SetOutputToRGBA}]
  Sets the output representation to 8-bit RGBA.
  Shortcut for \classmember*{FieldToColors}{SetOutputMode}\textcode{(}\vtkmfilter{FieldToColors::OutputMode}[RGBA]\textcode{)}.
\item[\classmember*{FieldToColors}{IsOutputRGB}]
  Returns true if the output representation is 8-bit RGB (\classmember{FieldToColors::OutputMode}{RGB}).
\item[\classmember*{FieldToColors}{IsOutputRGBA}]
  Returns true if the output representation is 8-bit RGBA (\classmember{FieldToColors::OutputMode}{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 transform!field to colors|)}
\index{field to colors|)}

\subsubsection{Generate Ids}

\index{generate ids|(}
\index{field transform!generate ids|(}

\vtkmfilter[field\_transform]{GenerateIds} is a filter that creates point and/or id fields that mimic the identifier for the respective element.

\textidentifier{GenerateIds} provides the following methods.

\begin{description}
\item[\classmember*{GenerateIds}{SetPointFieldName}/\classmember*{GenerateIds}{GetPointFieldName}]
  Specify the name of the point id field generated.
  By default, this is set to ``pointids''.
\item[\classmember*{GenerateIds}{SetCellFieldName}/\classmember*{GenerateIds}{GetCellFieldName}]
  Specify the name of the cell id field generated.
  By default, this is set to ``cellids''.
\item[\classmember*{GenerateIds}{SetGeneratePointIds}/\classmember*{GenerateIds}{GetGeneratePointIds}]
  Specify whether to generate the the point id field.
  By default, this is true, meaning the field will be generated.
\item[\classmember*{GenerateIds}{SetGenerateCellIds}/\classmember*{GenerateIds}{GetGenerateCellIds}]
  Specify whether to generate the the cell id field.
  By default, this is true, meaning the field will be generated.
\item[\classmember*{GenerateIds}{SetUseFloat}/\classmember*{GenerateIds}{GetUseFloat}]
  Specify whether to generate fields of integers or floats.
  If true, the geneated fields will be of type \vtkm{FloatDefault}.
  If false, the default, the generated fields will be of type \vtkm{Id}.
\end{description}

\index{field transform!generate ids|)}
\index{generate ids|)}

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

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

\vtkmfilter[field\_transform]{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|)}

\subsubsection{Point Transform}

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

\vtkmfilter[field\_transform]{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 coordinate system in the output \textidentifier{DataSet} is replaced with the transformed point coordinates .
  \commonfieldfiltermethods
\end{description}

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

\subsubsection{Spherical Coordinate System Transform}

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

\vtkmfilter[field\_transform]{SphericalCoordinateTransform} 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 output coordinate system will be set to the new computed coordinates.

\textidentifier{CylindricalCoordinateTransform} provides the following methods.

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

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

\subsubsection{Warp Scalar}

\index{warp scalar|(}
\index{field transform!warp scalar|(}
\index{scalar|(}

\vtkmfilter[field\_transform]{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{field transform!warp scalar|)}
\index{warp scalar|)}

\subsubsection{Warp Vector}

\index{warp vector|(}
\index{field transform!warp vector|(}
\index{vector|(}

\vtkmfilter[field\_transform]{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{field transform!warp vector|)}
\index{warp vector|)}

\index{field transform|)}


\subsection{Geometry Refinement}

\index{geometry refinement|(}

Geometry refinement modifies the geometry of a \textidentifier{DataSet}.
It might add, change, or remove components of the structure, but the general representation will be the same.

\subsubsection{Split Sharp Edges}

\index{split sharp edges|(}
\index{geometry refinement!split sharp edges|(}

\vtkmfilter[geometry\_refinement]{SplitSharpEdges} splits sharp manifold edges where the feature angle between the adjacent surfaces are larger than a threshold value.
When an edge is split, it adds a new point to the coordinates and updates the connectivity of an adjacent surface.

For example, consider two adjacent triangles (0,1,2) and (2,1,3).
Edge (1,2) needs to be split.
Two new points 4 (duplication of point 1) and 5 (duplication of point 2) would be added and the later triangle's connectivity would be changed to (5,4,3).
By default, all old point's fields would be copied to the new point.

Note that ``split'' edges do not have space added between them.
They are still adjacent visually, but the topology becomes disconnectered there.
Splitting sharp edges is most useful to duplicate normal shading vectors to make a sharp shading effect.

\textidentifier{SplitSharpEdges} contains the following methods.

\begin{description}
\item[\classmember*{SplitSharpEdges}{SetFeatureAngle}/\classmember*{SplitSharpEdges}{GetFeatureAngle}]
  Specifies the angle, in degrees, to split edges.
  Any time the normal vectors to 2 adjacent polygons are greater than this angle, the points of this edge are duplicated.
  The default angle is 30 degrees.
  \commonfieldfiltermethods
\end{description}

\index{geometry refinement!split sharp edges|)}
\index{split sharp edges|)}

\subsubsection{Tetrahedralize}

\index{tetrahedralize|(}
\index{geometry refinement!tetrahedralize|(}

\vtkmfilter[geometry\_refinement]{Tetrahedralize} converts all the polyhedra in a \textidentifier{DataSet} into tetrahedra.

\textidentifier{Tetrahedralize} has the following methods.

\begin{description}
  \commonfiltermethods
\end{description}

\index{geometry refinement!tetrahedralize|)}
\index{tetrahedralize|)}

\subsubsection{Triangulate}

\index{triangulate|(}
\index{geometry refinement!triangulate|(}

\vtkmfilter[geometry\_refinement]{Triangulate} converts all the polyhedra in a \textidentifier{DataSet} into tetrahedra.

\textidentifier{Triangulate} has the following methods.

\begin{description}
  \commonfiltermethods
\end{description}

\index{geometry refinement!triangulate|)}
\index{triangulate|)}

\subsubsection{Tube}

\index{tube|(}
\index{geometry refinement!tube|(}

\vtkmfilter[geometry\_refinement]{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.
  \commonfiltermethods
\end{description}

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

\index{geometry refinement!tube|)}
\index{tube|)}

\subsubsection{Vertex Clustering}

\index{vertex clustering|(}
\index{surface simplification|(}
\index{geometry refinement!vertex clustering|(}

\vtkmfilter[vertex\_clustering]{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}.
  \commonfiltermethods
\end{description}

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

\index{geometry refinement!vertex clustering|)}
\index{surface simplification|)}
\index{vertex clustering|)}

\index{geometry refinement|)}


\subsection{Mesh Information}

\index{mesh information|(}

\VTKm provides several filters that derive information about the structure of the geometry.
This can be information about the shape of cells or their connections.

\subsubsection{Ghost Cell Classification}

\index{classify ghost cells|(}
\index{ghost cell!classify|(}
\index{mesh information!ghost cell classification|(}

\vtkmfilter[mesh\_info]{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}
  \commonfiltermethods
\end{description}

\index{mesh information!ghost cell classification|)}
\index{ghost cell!classify|)}
\index{classify ghost cells|)}


\subsubsection{Mesh Quality Metrics}
\label{sec:MeshQuality}

\index{mesh quality|(}
\index{mesh information!quality|(}

\vtkmfilter{MeshQuality} is a filter that can calculate various
metrics for evaluating mesh quality.
%
It generates a new field as output, based on the cells of an input data set.
%
The metrics for this filter come from the Verdict library, and
full mathematical descriptions for each metric can be found in the Verdict documentation.\footnote{\url{https://www.csimsoft.com/download?file=Documents/sand20071751.pdf}}

The following table lists
the supported mesh quality metrics.
%
The constructor for \vtkmfilter{MeshQuality}
takes an argument from the enum \vtkmfilter{CellMetric}, which specifies the
desired metric to calculate.
%
The possible values for the \textidentifier{CellMetric} enum are listed in the following table.
%
Also listed in the table is the default name for the field being created,
which can be overridden using the \classmember*{MeshQuality}{SetOutputFieldName} method.
%
Also, because most metrics only work on select types of cells,
the table specifies on which cell types each metric works
using the abbreviations ``Tri'' for triangles,
``Quad'' for quadrilaterals, ``Tet'' for tetrahedrons, ``Pyr'' for pyramids,
``Wed'' for wedges,
and ``Hex'' for hexahedrons.


\begin{longtable}{llll}

                         & Default     & Supported  &                   \\
    Constructor Argument & Output Name & Cell Types & Brief Description \\
    \midrule
\endhead

    \classmember{CellMetric}{Area} & area & Tri, Quad & Area of a 2D cell  \\[4ex]

    \classmember{CellMetric}{AspectGamma} & aspectGamma & Tet
          & Compare root-mean-square \\*
    & & & edge length to volume  \\[4ex]

    \classmember{CellMetric}{AspectRatio} & aspectRatio & Tri, Quad,
         &           Ratio involving longest edge \\*
    & & Tet, Hex & and circumradius  \\[4ex]

    \classmember{CellMetric}{Condition} & condition & Tri, Quad,
         & Condition number of  \\*
    & & Tet, Hex & weighted Jacobian matrix \\[4ex]

    \classmember{CellMetric}{DiagonalRatio} & diagonalRatio & Quad, Hex
         & Ratio of minimum and \\*
    & & & maximum diagonals \\[4ex]

    \classmember{CellMetric}{Dimension} & dimension & Hex & Designed specifically for  \\*
         & & & Sandia's Pronto code \\[4ex]

    \classmember{CellMetric}{Jacobian} & jacobian & Quad, Tet, & Minimum determinant of Jacobian \\*
    &          & Hex  & matrix, over corners and cell center \\[4ex]

    \classmember{CellMetric}{MaxAngle} & maxAngle & Tri, Quad
         & Maximum angle within cell, in degrees \\[4ex]

    \classmember{CellMetric}{MaxDiagonal} & maxDiagonal & Hex
         & Length of maximum diagonal in cell \\*
    & & & \\[4ex]

    \classmember{CellMetric}{MinAngle} & minAngle & Tri, Quad
         & Minimum angle within cell, in degrees \\[4ex]

    \classmember{CellMetric}{MinDiagonal} & minDiagonal & Hex
         & Length of minimum diagonal in cell \\*
    & & & \\[4ex]

    \classmember{CellMetric}{Oddy} & oddy & Quad, Hex
         & Maximum deviation of a metric tensor \\*
      & & & from an identity matrix, over all \\*
      & & & corners and cell center \\[4ex]

    \textidentifier{CellMetric}\textcode{::}- & relativeSize & Tri, Quad, & The ratio of the area/volume of  \\*
    \quad\classmember*{CellMetric}{RelativeSizeSquared} & Squared & Tet, Hex  & this cell compared to mesh average \\[4ex]

    \classmember{CellMetric}{ScaledJacobian} & scaledJacobian & Tri, Quad, & Derived from the Jacobian metric,  \\*
    & & Tet, Hex   & with normalization involving edge length \\[4ex]

    \classmember{CellMetric}{Shape} & shape & Tri, Quad, & Varies by shape type, including \\*
          &       & Tet, Hex   & incorporating Jacobian or Condition \\*
          & & & Consult Verdict manual \\[4ex]

    \classmember{CellMetric}{ShapeAndSize} & shapeAndSize & Tri, Quad, & Shape metric multiplied by \\*
    &              & Tet, Hex   & relative size squared metric\\[4ex]

    \classmember{CellMetric}{Shear} & shear & Quad, Hex & Min. value of Jacobian at each corner, \\*
                    & & & divided by length of  adjacent edges \\[4ex]

    \classmember{CellMetric}{Skew} & skew & Quad, Hex & Maximum angle between principle axes \\[4ex]

    \classmember{CellMetric}{Stretch} & stretch & Quad, Hex
         & Ratio of minimum edges and maximum  \\*
         & & & diagonal, normalized for unit cube \\[4ex]

    \classmember{CellMetric}{Taper} & taper & Quad & Maximum ratio of cross-derivative \\*
          & & & with associated principal axis \\[4ex]

    \classmember{CellMetric}{Volume} & volume & Tet, Pyr, & Volume of a 3D cell \\*
           &        & Wed, Hex & \\[4ex]

    \classmember{CellMetric}{Warpage} & warpage & Quad
         & Captures angles between diagonals \\
\end{longtable}

Finally, \textidentifier{MeshQuality} provides the following methods.

\begin{description}
  \commonfieldfiltermethods[ActiveField UseCoordinateSystemAsField ActiveCoordinateSystem]
\end{description}

\index{mesh information!quality|)}
\index{mesh quality|)}


\index{mesh information|)}


\subsection{Multi-Block}

\index{multi-block|(}

Data with multiple blocks are stored in \vtkmcont{PartitionedDataSet} objects.
Most \VTKm filters operate correctly on \textidentifier{PartitionedDataSet} just like they do with \textidentifier{DataSet}.
However, there are some filters that are designed with operations specific to multi-block datasets.

\subsubsection{AMR Arrays}

\index{AMR!arrays|(}
\index{multi-block!AMR arrays|(}

An AMR mesh is a \vtkmcont{PartitionedDataSet} with a special structure in the partitions.
Each partition has a \vtkmcont{CellSetStructured}.
The partitions form a hierarchy of grids where each level of the hierarchy refines the one above.

\textidentifier{PartitionedDataSet} does not explicitly store the structure of an AMR grid.
The \vtkmfilter{AmrArrays} filter determines the hierarchical structure of the AMR partitions and stores information about them in cell field arrays on each partition.
Cell fields with the following names are created for each partition.

\begin{description}
\item[vtkAmrLevel]%
  The AMR level at which the partition resides (with 0 being the most coarse level).
  All the values for a particular partition are set to the same value.
\item[vtkAmrIndex]%
  A unique identifier for each partition of a particular level.
  Each partition of the same level will have a unique index, but the indices will repeat across levels.
  All the values for a particular partition are set to the same value.
\item[vtkCompositeIndex]%
  A unique identifier for each partition.
  This index is the same as the index used for the partition in the containing \textidentifier{PartitionedDataSet}.
  All the values for a particular partition are set to the same value.
\item[vtkGhostType]%
  It is common for refinement levels in an AMR structure to overlap more coarse grids.
  In this case, the overlapped coarse cells have invalid data.
  The vtkGhostType field will track which cells are overlapped and should be ignored.
  This array will have a 0 value for all valid cells and a non-zero value for all invalid cells.
  (Specifically, if the bit specified by \classmember[vtkm]{CellClassification}{BLANKED} is set, then the cell is overlapped with a cell in a finer level.)
\end{description}

\begin{didyouknow}
  The names of these arrays (e.g. vtkAmrLevel) are chosen to be compatible with the equivalent arrays in VTK.
  This is why they use the prefix of ``vtk'' instead of ``vtkm''.
  Likewise, the flags used for vtkGhostType are compatible with VTK.
\end{didyouknow}

\textidentifier{AmrArrays} provides the following methods.

\begin{description}
  \commonfiltermethods
\end{description}

\index{multi-block!AMR arrays|)}
\index{AMR!arrays|)}

\index{multi-block|)}

\subsection{Vector Analysis}

\index{vector analysis|(}

\VTKm's vector analysis filters compute operations on fields related to vectors (usually in 3-space).

\subsubsection{Cross Product}

\index{cross product|(}
\index{vector analysis!cross product|(}

\vtkmfilter[cross\_product]{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{vector analysis!cross product|)}
\index{cross product|)}

\subsubsection{Dot Product}

\index{dot product|(}
\index{vector analysis!dot product|(}

\vtkmfilter[vector\_analysis]{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{vector analysis!dot product|)}
\index{dot product|)}

\subsubsection{Gradients}

\index{point gradients|(}
\index{cell gradients|(}
\index{gradients|(}
\index{vector analysis!gradients|(}

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

\textidentifier{Gradient} provides the following methods.

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

\index{vector analysis!gradients|)}
\index{point gradients|)}
\index{cell gradients|)}
\index{gradients|)}

\subsubsection{Surface Normals}

\index{surface normals|(}
\index{normals|(}
\index{vector analysis!surface normals|(}

\vtkmfilter[vector\_analysis]{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{vector analysis!surface normals|)}
\index{normals|)}
\index{surface normals|)}

\subsubsection{Vector Magnitude}

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

\vtkmfilter[vector\_analysis]{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{vector analysis!vector magnitude|)}
\index{magnitude|)}
\index{vector magnitude|)}

\index{vector analysis|)}

\subsection{ZFP Compression}

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

\vtkmfilter[zfp]{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[zfp]{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|)}



\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 field 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{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.
  The seeds are specified in an \textidentifier{ArrayHandle} containing \vtkm{Particle} objects.
\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 continuous surface 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.
  The seeds are specified in an \textidentifier{ArrayHandle} containing \vtkm{Particle} objects.
\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.
  The seeds are specified in an \textidentifier{ArrayHandle} containing \vtkm{Particle} objects.
\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|)}


\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*{NewFilterField}{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*{NewFilterField}{SetActiveField} takes the name of the field as an argument.
However, \classmember*{NewFilterField}{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}[Association::Any]}]
  Any field regardless of the association.
  (This is the default if no association is given.)
\item[{\vtkmcont{Field}[Association::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}[Association::Cells]}]
  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}[Association::WholeMesh]}]
  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 differentiable 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*{NewFilterField}{SetUseCoordinateSystemAsField} method with a true flag.
Since a \textidentifier{DataSet} can have multiple coordinate systems, you can select the desired coordinate system with \classmember*{NewFilterField}{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*{NewFilter}{SetFieldsToPass} methods of \vtkmfilter{NewFilter}.

There are multiple ways to to use \classmember{NewFilter}{SetFieldsToPass} to control what fields are passed.
If you want to turn off all fields so that none are passed, call \classmember*{NewFilter}{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*{NewFilter}{SetFieldsToPass}.

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

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

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

Ultimately, \classmember{NewFilter}{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{NewFilter}{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|)}
