Pipelines

Pipelines allow users to compose filters that transform the published input data into new meshes. This is where users specify typical geometric transforms (e.g., clipping and slicing), field based transforms (e.g., threshold and contour), etc. The resulting data from each Pipeline can be used as input to Scenes or Extracts. Each pipeline contains one or more filters that transform the published mesh data. When more than one filter is specified, each successive filter consumes the result of the previous filter, and filters are executed in the order in which they are declared.

The code below shows the declaration of two pipelines. The first applies a contour filter to extract two isosurfaces of the scalar field noise. The second pipeline applies a threshold filter to screen the noise field, and then a clip filter to extract the intersection of what remains from the threshold with a sphere.

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "contour";
// filter parameters
conduit::Node contour_params;
contour_params["field"] = "noise";
contour_params["iso_values"] = {0.0, 0.5};
pipelines["pl1/f1/params"] = contour_params;

// pipeline 2
pipelines["pl2/f1/type"] = "threshold";
// filter parameters
conduit::Node thresh_params;
thresh_params["field"]  = "noise";
thresh_params["min_value"] = 0.0;
thresh_params["max_value"] = 0.5;
pipelines["pl2/f1/params"] = thresh_params;

pipelines["pl2/f2/type"]   = "clip";
// filter parameters
conduit::Node clip_params;
clip_params["topology"] = "mesh";
clip_params["sphere/center/x"] = 0.0;
clip_params["sphere/center/y"] = 0.0;
clip_params["sphere/center/z"] = 0.0;
clip_params["sphere/radius"]   = .1;
pipelines["pl2/f2/params/"] = clip_params;

Ascent and VTK-h are under heavy development and features are being added rapidly. As we stand up the infrastructure necessary to support a wide variety filter we created the following filters for the alpha release:

  • Contour
  • Threshold
  • Slice
  • Three Slice
  • Clip
  • Clip by field
  • Isovolume
  • Vector magnitude

In the following section we provide brief descriptions and code examples of the supported filters. For complete code examples, please consult the unit tests located in src/tests/ascent..

Filters

Our filter API consists of the type of filter and the parameters associated with the filter in the general form:

{
  "type"   : "filter_name",
  "params":
  {
    "string_param" : "string",
    "double_param" : 2.0
  }
}

In c++, the equivalent declarations would be as follows:

conduit::Node filter;
filter["type"] = "filter_name";
filter["params/string_param"] = "string";
filter["params/double_param"] = 2.0;

Included Filters

Contour

The contour filter evaluates a node-centered scalar field for all points at a given iso-value. This results in a surface if the iso-value is within the scalar field. iso_vals can contain a single double or an array of doubles. Additionally, instead of specifying exact iso-values, a number of ‘levels’ can be entered. In this case, iso-values will be created evenly spaced through the scalar range. For example, if the scalar range is [0.0, 1.0] and ‘levels’ is set to 3, then the iso-values (0.25, 0.5, 0.75) will be created. The code below provides examples creating a pipeline using all three methods:

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "contour";
// filter knobs
conduit::Node &contour_params = pipelines["pl1/f1/params"];
contour_params["field"] = "braid";
contour_params["iso_values"] = -0.4;
conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "contour";
// filter knobs
conduit::Node &contour_params = pipelines["pl1/f1/params"];
contour_params["field"] = "braid";
double iso_vals[3] = {-0.4, 0.2, 0.4};
contour_params["iso_values"].set_external(iso_vals,3);
../_images/contour.png

Fig. 8 An example image of multiple contours produced using the previous code sample.

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "contour";
// filter knobs
conduit::Node &contour_params = pipelines["pl1/f1/params"];
contour_params["field"] = "braid";
contour_params["levels"] = 5;
../_images/contour_levels.png

Fig. 9 An example of creating five evenly spaced iso-values through a scalar field.

Figure 8 shows an image produced from mulitple contours. All contour examples are located in the test in the file contour test.

Threshold

The threshold filter removes cells that are not contained within a specified scalar range.

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "threshold";
// filter knobs
conduit::Node &thresh_params = pipelines["pl1/f1/params"];
thresh_params["field"] = "braid";
thresh_params["min_value"] = -0.2;
thresh_params["max_value"] = 0.2;
../_images/threshold.png

Fig. 10 An example image of the threshold filter using the previous code sample.

Figure 10 shows an image produced from a threshold filter. The full example is located in the file threshold test.

Slice

The slice filter extracts a 2d plane from a 3d data set. The plane is defined by a point (on the plane) and a normal vector (not required to be nomalized).

conduit::Node pipelines;
pipelines["pl1/f1/type"] = "slice";
// filter knobs
conduit::Node &slice_params = pipelines["pl1/f1/params"];
slice_params["point/x"] = 0.f;
slice_params["point/y"] = 0.f;
slice_params["point/z"] = 0.f;

slice_params["normal/x"] = 0.f;
slice_params["normal/y"] = 0.f;
slice_params["normal/z"] = 1.f;
../_images/slice.png

Fig. 11 An example image of the slice filter on a zone-centered variable using the previous code sample.

Figure 11 shows an image produced from the slice filter. The full example is located in the file slice test.

Three Slice

The three slice filter slices 3d data sets using three axis-aligned slice planes and leaves the resulting planes in 3d where they can all be viewed at the same time. Three slice is meant primarily for quick visual exploration of 3D data where the internal features cannot be readily observed from the outside.

The slice planes will automatically placed at the center of the data sets spatial extents. Optionally, offsets for each plane can be specified. Offsets for each axis are specified by a floating point value in the range [-1.0, 1.0], where -1.0 places the plane at the minimum spatial extent on the axis, 1.0 places the plane at the maximum spatial extent on the axis, and 0.0 places the plane at the center of the spatial extent. By default, all three offsets are 0.0.

conduit::Node pipelines;
pipelines["pl1/f1/type"] = "3slice";
../_images/three_slice.png

Fig. 12 An example image of the three slice filter on a zone-centered variable using the previous code sample with automatic slice plane placement.

conduit::Node pipelines;
pipelines["pl1/f1/type"] = "3slice";

// filter knobs (all these are optional)
conduit::Node &slice_params = pipelines["pl1/f1/params"];
slice_params["x_offset"] = 1.f;   // largest value on the x-axis
slice_params["y_offset"] = 0.f;   // middle of the y-axis
slice_params["z_offset"] = -1.f;  // smalles value of the z-axis
../_images/three_slice2.png

Fig. 13 An example image of the three slice filter on a zone-centered variable using the previous code sample with user specified offsets for each axis.

Figures 12 and 13 show an images produced from the three slice filter. The full example is located in the file slice test.

Clip

The clip filter removes cells from the specified topology using implicit functions. By default, only the area outside of the implicit function remains, but the clip can be inverted. There are three implicit functions that clip can use: sphere, box, and plane.

// define a clip by a sphere
conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "clip";
// filter knobs
conduit::Node &clip_params = pipelines["pl1/f1/params"];
clip_params["topology"] = "mesh";
clip_params["sphere/radius"] = 11.;
clip_params["sphere/center/x"] = 0.;
clip_params["sphere/center/y"] = 0.;
clip_params["sphere/center/z"] = 0.;
../_images/clip.png

Fig. 14 An example image of the clip filter using the previous code sample. The data set is a cube with extents from (-10, -10, -10) to (10, 10, 10), and the code removes a sphere centered at the origin with a radius of 11.

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "clip";
// filter knobs
conduit::Node &clip_params = pipelines["pl1/f1/params"];
clip_params["topology"] = "mesh";
clip_params["invert"] = "true";
clip_params["sphere/radius"] = 11.;
clip_params["sphere/center/x"] = 0.;
clip_params["sphere/center/y"] = 0.;
clip_params["sphere/center/z"] = 0.;
../_images/clip_inverted.png

Fig. 15 An example of the same sphere clip, but in this case, the clip is inverted.

// define a clip by a box
conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "clip";
// filter knobs
conduit::Node &clip_params = pipelines["pl1/f1/params"];
clip_params["topology"] = "mesh";
clip_params["box/min/x"] = 0.;
clip_params["box/min/y"] = 0.;
clip_params["box/min/z"] = 0.;
clip_params["box/max/x"] = 10.01; // <=
clip_params["box/max/y"] = 10.01;
clip_params["box/max/z"] = 10.01;
../_images/box_clip.png

Fig. 16 A box clip of the same data set that removes the octant on the positive x, y, and z axes.

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "clip";
// filter knobs
conduit::Node &clip_params = pipelines["pl1/f1/params"];
clip_params["topology"] = "mesh";
clip_params["plane/point/x"] = 0.;
clip_params["plane/point/y"] = 0.;
clip_params["plane/point/z"] = 0.;
clip_params["plane/normal/x"] = 1.;
clip_params["plane/normal/y"] = 0.;
clip_params["plane/normal/z"] = 0;
../_images/clip_plane.png

Fig. 17 Clipping by a plane defined by a point on the plane and the plane normal.

Figures 14, 15, 16, and 17 show an images produced from the clip filter. All of the clip examples are located in the file clip test.

Clip By Field

The clip by field filter removes cells from the specified topology using the values in a scalar field. By default, all values below the clip value are removed from the data set. As with clip by implicit function, the clip can be inverted.

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "clip_with_field";
// filter knobs
conduit::Node &clip_params = pipelines["pl1/f1/params"];
clip_params["field"] = "braid";
clip_params["clip_value"] = 0.;
../_images/clip_field.png

Fig. 18 An example of clipping all values below 0 in a data set.

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "clip_with_field";
// filter knobs
conduit::Node &clip_params = pipelines["pl1/f1/params"];
clip_params["field"] = "braid";
clip_params["invert"] = "true";
clip_params["clip_value"] = 0.;
../_images/clip_field_inverted.png

Fig. 19 An example of clipping all values above 0 in a data set.

IsoVolume

IsoVolume is a filter that clips a data set based on a minimum and maximum value in a scalar field. All value outside of the minminum and maximum values are removed from the data set.

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "iso_volume";
// filter knobs
conduit::Node &clip_params = pipelines["pl1/f1/params"];
clip_params["field"] = "braid";
clip_params["min_value"] = 5.;
clip_params["max_value"] = 10.;
../_images/iso_volume.png

Fig. 20 An example of creating a iso-volume of values between 5.0 and 10.0.

Vector Magnitude

Vecotr magnitude creates a new field on the data set representing the magitude of a vector variable. The only parameters are the input vector field name and the name of the new field.

conduit::Node pipelines;
// pipeline 1
pipelines["pl1/f1/type"] = "vector_magnitude";
// filter knobs (all these are optional)
conduit::Node &params = pipelines["pl1/f1/params"];
params["field"] = "vel";         // name of the vector field
params["output_name"] = "mag";   // name of the output field
../_images/vector_magnitude.png

Fig. 21 An example of creating a pseudocolor plot of vector magnitude