ProvidedFilters.tex

% -*- latex -*-

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

\index{filter|(}

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

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

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


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

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

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

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

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

The \textcode{Execute} method returns a \vtkmfilter{ResultField} object,
which contains the state of the execution and the data generated. A
\textidentifier{ResultField} object has the following methods.

\begin{description}
\item[\textcode{IsValid}] Returns a \textcode{bool} value specifying
  whether the execution completed successfully. If \textcode{true}, then
  the execution was successful and the data stored in the
  \textidentifier{ResultField} is valid. If \textcode{false}, then the
  execution failed.
\item[\textcode{GetDataSet}] Returns a \textidentifier{DataSet} containing
  the results of the execution. The data set returned is a shallow copy of
  the input data with the generated field added.
\item[\textcode{GetField}] Returns the field information in a
  \vtkmcont{Field} object. Field objects are described in
  Section~\ref{sec:DataSets:Fields}.
\item[\textcode{FieldAs}] Given a \vtkmcont{ArrayHandle} object, allocates
  the array and copies the generated field data into it.
\end{description}

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

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

\subsection{Cell Average}

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

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

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

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

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

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

\subsection{Point Average}

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

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

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

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

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

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

\subsection{Point Elevation}

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

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

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

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

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

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

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

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


\section{Data Set Filters}

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

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

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

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

The \textcode{Execute} method returns a \vtkmfilter{ResultDataSet} object,
which contains the state of the execution and the data generated. A
\textidentifier{ResultDataSet} object has the following methods.

\begin{description}
\item[\textcode{IsValid}] Returns a \textcode{bool} value specifying
  whether the execution completed successfully. If \textcode{true}, then
  the execution was successful and the data stored in the
  \textidentifier{ResultField} is valid. If \textcode{false}, then the
  execution failed.
\item[\textcode{GetDataSet}] Returns a \textidentifier{DataSet} containing
  the results of the execution.
\end{description}

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

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

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

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

\subsection{Clean Grid}

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

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

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

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

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

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

\subsection{External Faces}

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

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

\begin{commonerrors}
  The current implementation of the external faces filter only supports
  tetrahedron cell cells. Future versions will support general 3D cell
  shapes. \fix{Remove this when the code is updated.}
\end{commonerrors}

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

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

\subsection{Vertex Clustering}

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

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

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

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

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

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


\section{Data Set and Field Filters}

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

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

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

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

The \textcode{Execute} method returns a \vtkmfilter{ResultDataSet} object,
which contains the state of the execution and the data generated. A
\textidentifier{ResultDataSet} object has the following methods.

\begin{description}
\item[\textcode{IsValid}] Returns a \textcode{bool} value specifying
  whether the execution completed successfully. If \textcode{true}, then
  the execution was successful and the data stored in the
  \textidentifier{ResultField} is valid. If \textcode{false}, then the
  execution failed.
\item[\textcode{GetDataSet}] Returns a \textidentifier{DataSet} containing
  the results of the execution.
\end{description}

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

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

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

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

\subsection{Marching Cubes}

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

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

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

\begin{description}
\item[\textcode{SetIsoValue}] Provide the value on which to extract the
  contour. The contour will be the surface where the field (provided to
  \textcode{Execute}) is equal to this value.
\item[\textcode{GetIsoValue}] Retrieve the currently set iso value.
\item[\textcode{SetMergeDuplicatePoints}] Sets a Boolean flag to determine
  whether coincident points in the data set should be merged. Because the
  Marching Cubes filter (like all filters in VTK-m) runs in parallel,
  parallel threads can (and often do) create duplicate versions of points.
  When this flag is set to true, a secondary operation will find all
  duplicated points and combine them together.
\item[\textcode{GetMergeDuplicatePoints}] Returns the merge duplicate
  points flag.
\item[\textcode{SetGenerateNormals}] Sets a Boolean flag to determine
  whether to generate normal vectors for the surface. Normals are used in
  shading calculations during rendering and can make the surface appear
  more smooth. Generated normals are based on the gradient of the field
  being contoured.
\item[\textcode{GetGenerateNormals}] Returns the generate normals flag.
\end{description}

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

\subsection{Threshold}

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

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

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

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

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

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


\index{filter|)}