2.6. Running Filters

Filters are functional units that take data as input and write new data as output. Filters operate on vtkm::cont::DataSet objects, which are described in Chapter 2.4 (Data Sets).

Did You Know?

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.

VTK‑m comes with several filters ready for use. This chapter gives an overview of how to run the filters. Chapter 2.7 (Provided Filters) describes the common filters provided by VTK‑m. Later, Part 3 (Developing Algorithms) describes the necessary steps in creating new filters in VTK‑m.

2.6.1. Basic Filter Operation

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 vtkm::filter::Filter::Execute() method. It takes a vtkm::cont::DataSet and returns a new vtkm::cont::DataSet, which contains the modified data.

vtkm::cont::DataSet vtkm::filter::Filter::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.

The vtkm::filter::Filter::Execute() method can alternately take a vtkm::cont::PartitionedDataSet object, which is a composite of vtkm::cont::DataSet objects. In this case vtkm::filter::Filter::Execute() will return another vtkm::cont::PartitionedDataSet object.

vtkm::cont::PartitionedDataSet vtkm::filter::Filter::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.

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.

Example 2.19 Using vtkm::filter::field_transform::PointElevation to estiate air pressure.

VTKM_CONT
vtkm::cont::DataSet ComputeAirPressure(vtkm::cont::DataSet dataSet)
{
  vtkm::filter::field_transform::PointElevation elevationFilter;

  // Use the elevation filter to estimate atmospheric pressure based on the
  // height of the point coordinates. Atmospheric pressure is 101325 Pa at
  // sea level and drops about 12 Pa per meter.
  elevationFilter.SetLowPoint(0.0, 0.0, 0.0);
  elevationFilter.SetHighPoint(0.0, 0.0, 2000.0);
  elevationFilter.SetRange(101325.0, 77325.0);

  elevationFilter.SetUseCoordinateSystemAsField(true);

  elevationFilter.SetOutputFieldName("pressure");

  vtkm::cont::DataSet result = elevationFilter.Execute(dataSet);

  return result;
}

We see that this example follows the previously described procedure of constructing the filter (line 4), setting the state parameters (lines 9 – 15), and finally executing the filter on a vtkm::cont::DataSet (line 17).

Every vtkm::cont::DataSet object contains a list of 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 2.19. In line 13 the coordinate system is set as the input field and in line 15 the name to use for the generated output field is selected.

2.6.2. Advanced Field Management

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 filters provided by VTK‑m. For example, not all filters have a specified input field. But where possible, the interface to the filter objects is kept consistent.

2.6.2.1. Input Fields

Filters that take one or more fields as input have a common set of methods to set the “active” fields to operate on. They might also have custom methods to ease setting the appropriate fields, but these are the base methods.

inline void vtkm::filter::Filter::SetActiveField(const std::string &name, vtkm::cont::Field::Association association = vtkm::cont::Field::Association::Any)

Specifies a field to operate on.

The number of input fields (or whether the filter operates on input fields at all) is specific to each particular filter.

inline void vtkm::filter::Filter::SetActiveField(vtkm::IdComponent index, const std::string &name, vtkm::cont::Field::Association association = vtkm::cont::Field::Association::Any)

Specifies a field to operate on.

The number of input fields (or whether the filter operates on input fields at all) is specific to each particular filter.

inline const std::string &vtkm::filter::Filter::GetActiveFieldName(vtkm::IdComponent index = 0) const

Specifies a field to operate on.

The number of input fields (or whether the filter operates on input fields at all) is specific to each particular filter.

inline vtkm::cont::Field::Association vtkm::filter::Filter::GetActiveFieldAssociation(vtkm::IdComponent index = 0) const

Specifies a field to operate on.

The number of input fields (or whether the filter operates on input fields at all) is specific to each particular filter.

inline void vtkm::filter::Filter::SetActiveCoordinateSystem(vtkm::Id coord_idx)

Specifies the coordinate system index to make active to use when processing the input vtkm::cont::DataSet.

This is used primarily by the Filter to select the coordinate system to use as a field when UseCoordinateSystemAsField is true.

inline void vtkm::filter::Filter::SetActiveCoordinateSystem(vtkm::IdComponent index, vtkm::Id coord_idx)

Specifies the coordinate system index to make active to use when processing the input vtkm::cont::DataSet.

This is used primarily by the Filter to select the coordinate system to use as a field when UseCoordinateSystemAsField is true.

inline vtkm::Id vtkm::filter::Filter::GetActiveCoordinateSystemIndex(vtkm::IdComponent index = 0) const

Specifies the coordinate system index to make active to use when processing the input vtkm::cont::DataSet.

This is used primarily by the Filter to select the coordinate system to use as a field when UseCoordinateSystemAsField is true.

inline void vtkm::filter::Filter::SetUseCoordinateSystemAsField(bool val)

Specifies whether to use point coordinates as the input field.

When true, the values for the active field are ignored and the active coordinate system is used instead.

inline void vtkm::filter::Filter::SetUseCoordinateSystemAsField(vtkm::IdComponent index, bool val)

Specifies whether to use point coordinates as the input field.

When true, the values for the active field are ignored and the active coordinate system is used instead.

inline bool vtkm::filter::Filter::GetUseCoordinateSystemAsField(vtkm::IdComponent index = 0) const

Specifies whether to use point coordinates as the input field.

When true, the values for the active field are ignored and the active coordinate system is used instead.

inline vtkm::IdComponent vtkm::filter::Filter::GetNumberOfActiveFields() const

Return the number of active fields currently set.

The general interface to Filter allows a user to set an arbitrary number of active fields (indexed 0 and on). This method returns the number of active fields that are set. Note that the filter implementation is free to ignore any active fields it does not support. Also note that an active field can be set to be either a named field or a coordinate system.

The vtkm::filter::Filter::SetActiveField() method takes an optional argument that specifies which topological elements the field is associated with (such as points or cells). The vtkm::cont::Field::Association enumeration is used to select the field association.

Example 2.20 Setting a field’s active filter with an association.

  filter.SetActiveField("pointvar", vtkm::cont::Field::Association::Points);

Common Errors

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.

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 vtkm::cont::DataSet structure. (See Section 2.4.4 (Coordinate Systems) for details on coordinate systems.) You can use a coordinate system as the active scalars by calling the vtkm::filter::Filter::SetUseCoordinateSystemAsField() method with a true flag. Since a vtkm::cont::DataSet can have multiple coordinate systems, you can select the desired coordinate system with vtkm::filter::Filter::SetActiveCoordinateSystem(). (By default, the first coordinate system, index 0, will be used.)

Example 2.21 Setting the active coordinate system.

  filter.SetUseCoordinateSystemAsField(true);
  filter.SetActiveCoordinateSystem(1);

2.6.2.2. Passing Fields 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. 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 vtkm::filter::Filter::SetFieldsToPass() methods.

void vtkm::filter::Filter::SetFieldsToPass(vtkm::filter::FieldSelection &&fieldsToPass)

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.

inline const vtkm::filter::FieldSelection &vtkm::filter::Filter::GetFieldsToPass() const

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.

inline vtkm::filter::FieldSelection &vtkm::filter::Filter::GetFieldsToPass()

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.

There are multiple ways to to use vtkm::filter::Filter::SetFieldsToPass() to control what fields are passed. If you want to turn off all fields so that none are passed, call vtkm::filter::Filter::SetFieldsToPass() with vtkm::filter::FieldSelection::Mode::None.

Example 2.22 Turning off the passing of all fields when executing a filter.

    filter.SetFieldsToPass(vtkm::filter::FieldSelection::Mode::None);

If you want to pass one specific field, you can pass that field’s name to vtkm::filter::Filter::SetFieldsToPass().

inline void vtkm::filter::Filter::SetFieldsToPass(const std::string &fieldname, vtkm::filter::FieldSelection::Mode mode)

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.

void vtkm::filter::Filter::SetFieldsToPass(const std::string &fieldname, vtkm::cont::Field::Association association, vtkm::filter::FieldSelection::Mode mode = vtkm::filter::FieldSelection::Mode::Select)

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.

Example 2.23 Setting one field to pass by name.

    filter.SetFieldsToPass("pointvar");

Or you can provide a list of fields to pass by giving vtkm::filter::Filter::SetFieldsToPass() an initializer list of names.

void vtkm::filter::Filter::SetFieldsToPass(std::initializer_list<std::string> fields, vtkm::filter::FieldSelection::Mode mode = vtkm::filter::FieldSelection::Mode::Select)

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.

Example 2.24 Using a list of fields for a filter to pass.

    filter.SetFieldsToPass({ "pointvar", "cellvar" });

If you want to instead select a list of fields to not pass, you can add vtkm::filter::FieldSelection::Mode::Exclude as an argument to vtkm::filter::Filter::SetFieldsToPass().

Example 2.25 Excluding a list of fields for a filter to pass.

    filter.SetFieldsToPass({ "pointvar", "cellvar" },
                           vtkm::filter::FieldSelection::Mode::Exclude);

Ultimately, vtkm::filter::Filter::SetFieldsToPass() takes a vtkm::filter::FieldSelection object. You can create one directly to select (or exclude) specific fields and their associations.

class FieldSelection

A FieldSelection stores information about fields to map for input dataset to output when a filter is executed.

A FieldSelection object is passed to vtkm::filter::Filter::Execute to execute the filter and map selected fields. It is possible to easily construct FieldSelection that selects all or none of the input fields.

Unnamed Group

inline void AddField(const vtkm::cont::Field &inputField): Add fields to select or exclude. If no mode is specified, then the mode will follow that of GetMode().

inline void AddField(const vtkm::cont::Field &inputField, Mode mode): Add fields to select or exclude. If no mode is specified, then the mode will follow that of GetMode().

inline void AddField(const std::string &fieldName, vtkm::cont::Field::Association association = vtkm::cont::Field::Association::Any): Add fields to select or exclude. If no mode is specified, then the mode will follow that of GetMode().

inline void AddField(const std::string &fieldName, Mode mode): Add fields to select or exclude. If no mode is specified, then the mode will follow that of GetMode().

void AddField(const std::string &fieldName, vtkm::cont::Field::Association association, Mode mode): Add fields to select or exclude. If no mode is specified, then the mode will follow that of GetMode().

Unnamed Group

inline Mode GetFieldMode(const vtkm::cont::Field &inputField) const: Returns the mode for a particular field. If the field as been added with AddField (or another means), then this will return Select or Exclude. If the field has not been added, None will be returned.

Mode GetFieldMode(const std::string &fieldName, vtkm::cont::Field::Association association = vtkm::cont::Field::Association::Any) const: Returns the mode for a particular field. If the field as been added with AddField (or another means), then this will return Select or Exclude. If the field has not been added, None will be returned.

Public Functions

FieldSelection(const std::string &field, Mode mode = Mode::Select)

Use this constructor to create a field selection given a single field name.

FieldSelection("field_name");

FieldSelection(const char *field, Mode mode = Mode::Select)

Use this constructor to create a field selection given a single field name.

FieldSelection("field_name");

FieldSelection(const std::string &field, vtkm::cont::Field::Association association, Mode mode = Mode::Select)

Use this constructor to create a field selection given a single name and association.

FieldSelection("field_name", vtkm::cont::Field::Association::Points)

{cpp}

FieldSelection(std::initializer_list<std::string> fields, Mode mode = Mode::Select)

Use this constructor to create a field selection given the field names.

FieldSelection({"field_one", "field_two"});

FieldSelection(std::initializer_list<std::pair<std::string, vtkm::cont::Field::Association>> fields, Mode mode = Mode::Select)

Use this constructor create a field selection given the field names and associations e.g.

using pair_type = std::pair<std::string, vtkm::cont::Field::Association>;
FieldSelection({
     pair_type{"field_one", vtkm::cont::Field::Association::Points},
     pair_type{"field_two", vtkm::cont::Field::Association::Cells} });

FieldSelection(std::initializer_list<vtkm::Pair<std::string, vtkm::cont::Field::Association>> fields, Mode mode = Mode::Select)

Use this constructor create a field selection given the field names and associations e.g.

using pair_type = vtkm::Pair<std::string, vtkm::cont::Field::Association>;
FieldSelection({
     pair_type{"field_one", vtkm::cont::Field::Association::Points},
     pair_type{"field_two", vtkm::cont::Field::Association::Cells} });

inline bool IsFieldSelected(const vtkm::cont::Field &inputField) const: Returns true if the input field should be mapped to the output dataset.

inline bool HasField(const vtkm::cont::Field &inputField) const

Returns true if the input field has been added to this selection.

Note that depending on the mode of this selection, the result of HasField is not necessarily the same as IsFieldSelected. (If the mode is MODE_SELECT, then the result of the two will be the same.)

void ClearFields(): Clear all fields added using AddField.

Mode GetMode() const

Gets the mode of the field selection.

If Select mode is on, then only fields that have a Select mode are considered as selected. (All others are considered unselected.) Calling AddField in this mode will mark it as Select. If Exclude mode is on, then all fields are considered selected except those fields with an Exclude mode. Calling AddField in this mode will mark it as Exclude.

void SetMode(Mode val)

Sets the mode of the field selection.

If Select mode is on, then only fields that have a Select mode are considered as selected. (All others are considered unselected.) Calling AddField in this mode will mark it as Select. If Exclude mode is on, then all fields are considered selected except those fields with an Exclude mode. Calling AddField in this mode will mark it as Exclude.

If the mode is set to None, then the field modes are cleared and the overall mode is set to Select (meaning none of the fields are initially selected). If the mode is set to All, then the field modes are cleared and the overall mode is set to Exclude (meaning all of the fields are initially selected).

Example 2.26 Using vtkm::filter::FieldSelection to select cells to pass.

    vtkm::filter::FieldSelection fieldSelection;
    fieldSelection.AddField("scalars");
    fieldSelection.AddField("cellvar", vtkm::cont::Field::Association::Cells);

    filter.SetFieldsToPass(fieldSelection);

It is also possible to specify field attributions directly to vtkm::filter::Filter::SetFieldsToPass(). If you only have one field, you can just specify both the name and attribution. If you have multiple fields, you can provide an initializer list of std::pair or vtkm::Pair containing a std::string and a vtkm::cont::Field::Association. In either case, you can add an optional last argument of vtkm::filter::FieldSelection::Mode::Exclude to exclude the specified filters instead of selecting them.

void vtkm::filter::Filter::SetFieldsToPass(std::initializer_list<std::pair<std::string, vtkm::cont::Field::Association>> fields, vtkm::filter::FieldSelection::Mode mode = vtkm::filter::FieldSelection::Mode::Select)

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.

Example 2.27 Selecting one field and its association for a filter to pass.

    filter.SetFieldsToPass("pointvar", vtkm::cont::Field::Association::Points);

Example 2.28 Selecting a list of fields and their associations for a filter to pass.

    filter.SetFieldsToPass(
      { vtkm::make_Pair("pointvar", vtkm::cont::Field::Association::Points),
        vtkm::make_Pair("cellvar", vtkm::cont::Field::Association::Cells),
        vtkm::make_Pair("scalars", vtkm::cont::Field::Association::Any) });

Note that coordinate systems in a vtkm::cont::DataSet are simply links to point fields, and by default filters will pass coordinate systems regardless of the field selection flags. To prevent a filter from passing a coordinate system if its associated field is not selected, use the vtkm::filter::Filter::SetPassCoordinateSystems() method.

inline void vtkm::filter::Filter::SetPassCoordinateSystems(bool flag)

Specify whether to always pass coordinate systems.

vtkm::cont::CoordinateSystems in a DataSet are really just point fields marked as being a coordinate system. Thus, a coordinate system is passed if and only if the associated field is passed.

By default, the filter will pass all fields associated with a coordinate system regardless of the FieldsToPass marks the field as passing. If this option is set to false, then coordinate systems will only be passed if it is marked so by FieldsToPass.

inline bool vtkm::filter::Filter::GetPassCoordinateSystems() const

Specify whether to always pass coordinate systems.

vtkm::cont::CoordinateSystems in a DataSet are really just point fields marked as being a coordinate system. Thus, a coordinate system is passed if and only if the associated field is passed.

By default, the filter will pass all fields associated with a coordinate system regardless of the FieldsToPass marks the field as passing. If this option is set to false, then coordinate systems will only be passed if it is marked so by FieldsToPass.

Example 2.29 Turning off the automatic selection of fields associated with a vtkm::cont::DataSet’s coordinate system.

    filter.SetPassCoordinateSystems(false);

2.6.2.3. Output Field Names

Many filters will create fields of data. A common way to set the name of the output field is to use the vtkm::filter::Filter::SetOutputFieldName() method.

inline void vtkm::filter::Filter::SetOutputFieldName(const std::string &name)

Specifies the name of the output field generated.

Not all filters create an output field.

inline const std::string &vtkm::filter::Filter::GetOutputFieldName() const

Specifies the name of the output field generated.

Not all filters create an output field.

Most filters will have a default name to use for its generated fields. It is also common for filters to provide convenience methods to name the output fields.