VTK-m  1.6
Public Types | Public Member Functions | Protected Attributes | Private Attributes | List of all members
vtkm::filter::Filter< Derived > Class Template Reference

base class for all filters. More...

#include <Filter.h>

Inheritance diagram for vtkm::filter::Filter< Derived >:
vtkm::filter::FilterDataSet< Derived > vtkm::filter::FilterDataSetWithField< Derived > vtkm::filter::FilterField< Derived >

Public Types

using SupportedTypes = VTKM_DEFAULT_TYPE_LIST
 Specify which subset of types a filter supports. More...
 
using AdditionalFieldStorage = vtkm::ListEmpty
 Specify which additional field storage to support. More...
 
using SupportedStructuredCellSets = VTKM_DEFAULT_CELL_SET_LIST_STRUCTURED
 Specify which structured cell sets to support. More...
 
using SupportedUnstructuredCellSets = VTKM_DEFAULT_CELL_SET_LIST_UNSTRUCTURED
 Specify which unstructured cell sets to support. More...
 
using SupportedCellSets = VTKM_DEFAULT_CELL_SET_LIST
 Specify which unstructured cell sets to support. More...
 

Public Member Functions

VTKM_CONT Filter ()
 
VTKM_CONT ~Filter ()
 
VTKM_CONT void SetFieldsToPass (const vtkm::filter::FieldSelection &fieldsToPass)
 Specify which fields get passed from input to output. More...
 
VTKM_CONT void SetFieldsToPass (const vtkm::filter::FieldSelection &fieldsToPass, vtkm::filter::FieldSelection::ModeEnum mode)
 
VTKM_CONT void SetFieldsToPass (const std::string &fieldname, vtkm::cont::Field::Association association, vtkm::filter::FieldSelection::ModeEnum mode=vtkm::filter::FieldSelection::MODE_SELECT)
 
const VTKM_CONT vtkm::filter::FieldSelectionGetFieldsToPass () const
 
VTKM_CONT vtkm::filter::FieldSelectionGetFieldsToPass ()
 
VTKM_CONT vtkm::cont::DataSet Execute (const vtkm::cont::DataSet &input)
 Executes the filter on the input and produces a result dataset. More...
 
template<typename DerivedPolicy >
VTKM_DEPRECATED(1.6, "Filter::Execute no longer guarantees policy modifications. " "Specify default types in CMake configuration instead.") VTKM_CONT vtkm VTKM_CONT vtkm::cont::PartitionedDataSet Execute (const vtkm::cont::PartitionedDataSet &input)
 Executes the filter on the input PartitionedDataSet and produces a result PartitionedDataSet. More...
 
template<typename DerivedPolicy >
VTKM_DEPRECATED(1.6, "Filter::Execute no longer guarantees policy modifications. " "Specify default types in CMake configuration instead.") VTKM_CONT vtkm VTKM_CONT void MapFieldsToPass (const vtkm::cont::DataSet &input, vtkm::cont::DataSet &output, vtkm::filter::PolicyBase< DerivedPolicy > policy)
 Map fields from input dataset to output. More...
 
void SetInvoker (vtkm::cont::Invoker inv)
 Specify the vtkm::cont::Invoker to be used to execute worklets by this filter instance. More...
 

Protected Attributes

vtkm::cont::Invoker Invoke
 

Private Attributes

vtkm::filter::FieldSelection FieldsToPass
 

Detailed Description

template<typename Derived>
class vtkm::filter::Filter< Derived >

base class for all filters.

This is the base class for all filters. To add a new filter, one can subclass this (or any of the existing subclasses e.g. FilterField, FilterDataSet, FilterDataSetWithField, etc. and implement relevant methods.

Usage

To execute a filter, one typically calls the auto result = filter.Execute(input). Typical usage is as follows:

// create the concrete subclass (e.g. MarchingCubes).
vtkm::filter::MarchingCubes marchingCubes;
// select fieds to map to the output, if different from default which is to
// map all input fields.
marchingCubes.SetFieldToPass({"var1", "var2"});
// execute the filter on vtkm::cont::DataSet.
vtkm::cont::DataSet dsInput = ...
auto outputDS = filter.Execute(dsInput);
// or, execute on a vtkm::cont::PartitionedDataSet
auto outputMB = filter.Execute(mbInput);

Execute methods take in the input DataSet or PartitionedDataSet to process and return the result. The type of the result is same as the input type, thus Execute(DataSet&) returns a DataSet while Execute(PartitionedDataSet&) returns a PartitionedDataSet.

The implementation for Execute(DataSet&) is merely provided for convenience. Internally, it creates a PartitionedDataSet with a single partition for the input and then forwards the call to Execute(PartitionedDataSet&). The method returns the first partition, if any, from the PartitionedDataSet returned by the forwarded call. If the PartitionedDataSet returned has more than 1 partition, then vtkm::cont::ErrorFilterExecution will be thrown.

Subclassing

Typically, one subclasses one of the immediate subclasses of this class such as FilterField, FilterDataSet, FilterDataSetWithField, etc. Those may impose additional constraints on the methods to implement in the subclasses. Here, we describes the things to consider when directly subclassing vtkm::filter::Filter.

PreExecute and PostExecute

Subclasses may provide implementations for either or both of the following methods.

template <typename DerivedPolicy>
void PreExecute(const vtkm::cont::PartitionedDataSet& input,
template <typename DerivedPolicy>
void PostExecute(const vtkm::cont::PartitionedDataSet& input, vtkm::cont::PartitionedDataSet& output

As the name suggests, these are called and the beginning and before the end of an Filter::Execute call. Most filters that don't need to handle PartitionedDataSet specially, e.g. clip, cut, iso-contour, need not worry about these methods or provide any implementation. If, however, your filter needs do to some initialization e.g. allocation buffers to accumulate results, or finalization e.g. reduce results across all partitions, then these methods provide convenient hooks for the same.

PrepareForExecution

A concrete subclass of Filter must provide PrepareForExecution implementation that provides the meat for the filter i.e. the implementation for the filter's data processing logic. There are two signatures available; which one to implement depends on the nature of the filter.

Let's consider simple filters that do not need to do anything special to handle PartitionedDataSet e.g. clip, contour, etc. These are the filters where executing the filter on a PartitionedDataSet simply means executing the filter on one partition at a time and packing the output for each iteration info the result PartitionedDataSet. For such filters, one must implement the following signature.

template <typename DerivedPolicy>
vtkm::cont::DataSet PrepareForExecution(
const vtkm::cont::DataSet& input,

The role of this method is to execute on the input dataset and generate the result and return it. If there are any errors, the subclass must throw an exception (e.g. vtkm::cont::ErrorFilterExecution).

In this case, the Filter superclass handles iterating over multiple partitions in the input PartitionedDataSet and calling PrepareForExecution iteratively.

The aforementioned approach is also suitable for filters that need special handling for PartitionedDataSets which can be modelled as PreExecute and PostExecute steps (e.g. vtkm::filter::Histogram).

For more complex filters, like streamlines, particle tracking, where the processing of PartitionedDataSets cannot be modelled as a reduction of the results, one can implement the following signature.

template <typename DerivedPolicy>
vtkm::cont::PartitionedDataSet PrepareForExecution(

The responsibility of this method is the same, except now the subclass is given full control over the execution, including any mapping of fields to output (described in next sub-section).

MapFieldOntoOutput

Subclasses may provide MapFieldOntoOutput method with the following signature:

template <typename DerivedPolicy>
VTKM_CONT bool MapFieldOntoOutput(vtkm::cont::DataSet& result,
const vtkm::cont::Field& field,

When present, this method will be called after each partition execution to map an input field from the corresponding input partition to the output partition.

Member Typedef Documentation

◆ AdditionalFieldStorage

template<typename Derived >
using vtkm::filter::Filter< Derived >::AdditionalFieldStorage = vtkm::ListEmpty

Specify which additional field storage to support.

When a filter gets a field value from a DataSet, it has to determine what type of storage the array has. Typically this is taken from the default storage types defined in DefaultTypes.h. In some cases it is useful to support additional types. For example, the filter might make sense to support ArrayHandleIndex or ArrayHandleConstant. If so, the storage of those additional types should be listed here.

◆ SupportedCellSets

template<typename Derived >
using vtkm::filter::Filter< Derived >::SupportedCellSets = VTKM_DEFAULT_CELL_SET_LIST

Specify which unstructured cell sets to support.

When a filter gets a cell set from a DataSet, it has to determine what type of concrete cell set it is. This provides a list of supported cell sets.

◆ SupportedStructuredCellSets

template<typename Derived >
using vtkm::filter::Filter< Derived >::SupportedStructuredCellSets = VTKM_DEFAULT_CELL_SET_LIST_STRUCTURED

Specify which structured cell sets to support.

When a filter gets a cell set from a DataSet, it has to determine what type of concrete cell set it is. This provides a list of supported structured cell sets.

◆ SupportedTypes

template<typename Derived >
using vtkm::filter::Filter< Derived >::SupportedTypes = VTKM_DEFAULT_TYPE_LIST

Specify which subset of types a filter supports.

A filter is able to state what subset of types it supports.

◆ SupportedUnstructuredCellSets

template<typename Derived >
using vtkm::filter::Filter< Derived >::SupportedUnstructuredCellSets = VTKM_DEFAULT_CELL_SET_LIST_UNSTRUCTURED

Specify which unstructured cell sets to support.

When a filter gets a cell set from a DataSet, it has to determine what type of concrete cell set it is. This provides a list of supported unstructured cell sets.

Constructor & Destructor Documentation

◆ Filter()

template<typename Derived >
VTKM_CONT vtkm::filter::Filter< Derived >::Filter ( )

◆ ~Filter()

template<typename Derived >
VTKM_CONT vtkm::filter::Filter< Derived >::~Filter ( )

Member Function Documentation

◆ Execute() [1/2]

template<typename Derived >
VTKM_CONT vtkm::cont::DataSet vtkm::filter::Filter< Derived >::Execute ( const vtkm::cont::DataSet input)

Executes the filter on the input and produces a result dataset.

On success, this the dataset produced. On error, vtkm::cont::ErrorExecution will be thrown.

◆ Execute() [2/2]

template<typename Derived >
template<typename DerivedPolicy >
VTKM_DEPRECATED (1.6, "Filter::Execute no longer guarantees policy modifications. " "Specify default types in CMake configuration instead.") VTKM_CONT vtkm VTKM_CONT vtkm::cont::PartitionedDataSet vtkm::filter::Filter< Derived >::Execute ( const vtkm::cont::PartitionedDataSet input)

Executes the filter on the input PartitionedDataSet and produces a result PartitionedDataSet.

On success, this the dataset produced. On error, vtkm::cont::ErrorExecution will be thrown.

◆ GetFieldsToPass() [1/2]

template<typename Derived >
VTKM_CONT vtkm::filter::FieldSelection& vtkm::filter::Filter< Derived >::GetFieldsToPass ( )
inline

◆ GetFieldsToPass() [2/2]

template<typename Derived >
const VTKM_CONT vtkm::filter::FieldSelection& vtkm::filter::Filter< Derived >::GetFieldsToPass ( ) const
inline

◆ MapFieldsToPass()

template<typename Derived >
template<typename DerivedPolicy >
VTKM_DEPRECATED (1.6, "Filter::Execute no longer guarantees policy modifications. " "Specify default types in CMake configuration instead.") VTKM_CONT vtkm VTKM_CONT void vtkm::filter::Filter< Derived >::MapFieldsToPass ( const vtkm::cont::DataSet input,
vtkm::cont::DataSet output,
vtkm::filter::PolicyBase< DerivedPolicy >  policy 
)

Map fields from input dataset to output.

This is not intended for external use. Subclasses of Filter, however, may use this method to map fields.

◆ SetFieldsToPass() [1/3]

template<typename Derived >
VTKM_CONT void vtkm::filter::Filter< Derived >::SetFieldsToPass ( const std::string &  fieldname,
vtkm::cont::Field::Association  association,
vtkm::filter::FieldSelection::ModeEnum  mode = vtkm::filter::FieldSelection::MODE_SELECT 
)
inline

◆ SetFieldsToPass() [2/3]

template<typename Derived >
VTKM_CONT void vtkm::filter::Filter< Derived >::SetFieldsToPass ( const vtkm::filter::FieldSelection fieldsToPass)
inline

Specify which fields get passed from input to output.

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. You can control which fields are passed (and equivalently which are not) with this parameter.

By default, all fields are passed during execution.

◆ SetFieldsToPass() [3/3]

template<typename Derived >
VTKM_CONT void vtkm::filter::Filter< Derived >::SetFieldsToPass ( const vtkm::filter::FieldSelection fieldsToPass,
vtkm::filter::FieldSelection::ModeEnum  mode 
)
inline

◆ SetInvoker()

template<typename Derived >
void vtkm::filter::Filter< Derived >::SetInvoker ( vtkm::cont::Invoker  inv)
inline

Specify the vtkm::cont::Invoker to be used to execute worklets by this filter instance.

Overriding the default allows callers to control which device adapters a filter uses.

Member Data Documentation

◆ FieldsToPass

template<typename Derived >
vtkm::filter::FieldSelection vtkm::filter::Filter< Derived >::FieldsToPass
private

◆ Invoke

template<typename Derived >
vtkm::cont::Invoker vtkm::filter::Filter< Derived >::Invoke
protected

The documentation for this class was generated from the following file:
vtkm::cont::DataSet
Definition: DataSet.h:28
vtkm::filter::PolicyBase
Definition: PolicyBase.h:33
vtkm::cont::Field
A Field encapsulates an array on some piece of the mesh, such as the points, a cell set,...
Definition: cont/Field.h:30
VTKM_CONT
#define VTKM_CONT
Definition: ExportMacros.h:57
vtkm::cont::PartitionedDataSet
Definition: PartitionedDataSet.h:25