OpenDX - Documentation
Full Contents QuickStart Guide User's Guide User's Reference
Previous Page Next Page Table of Contents Partial Table of Contents Index Search

Include

Category

Import and Export

Function

Includes data points in (or excludes them from) a data set.

Syntax



output = Include(data, min, max, exclude, cull, pointwise);

Inputs
Name Type Default Description
data field none the field from which to select points
min scalar or vector min of data minimum value to include
max scalar or vector max of data maximum value to include
exclude flag 0 0: include selected range
1: exclude selected range
cull flag 1 0: culled points marked invalid
1: culled points removed
pointwise flag 0 if 1, ignore connections when selecting points

Outputs
Name Type Description
output field the field with selected points

Functional Details

This module determines which points in a data set are to be treated as valid by other modules. It does so by removing or invalidating data values that fall within (or outside) a specified range, thereby including the remaining points in the set. If there are connections (or faces or polylines) in the field, and pointwise=0, then Include also removes all invalid connections (connections containing at least one invalid position) and all unreferenced positions (positions not referred to by any valid connection, face, or polyline element).

data

is the data field that the module operates on.

min  and  max

specify a range of data values whose function is determined by the exclude flag (see below).

exclude

specifies whether the values to be excluded from the data set lie within or outside the range defined by min and max.

  • 0: Removes or invalidates all elements or positions whose data values lie outside the specified range.
  • 1: Removes or invalidates all elements or positions whose data values lie within the specified range.

cull

specifies whether the excluded (culled) points are to be invalidated or actually removed from the data set.

  • 0: Returns the field with invalid positions and invalid connections, invalid faces, or invalid polylines components. Since it is unnecessary to remove invalid positions, connections, faces, or polylines, in order to have them treated as invalid by other modules, this is usually the preferred setting.

    If the module removes points from data with regular connections (e.g., cubes or quads), the connections become irregular.

  • 1: Returns the field with invalid positions and connections removed.

pointwise

if set to 1, the connections of data are removed before the points are selected.

See "Invalid Positions and Invalid Connections Components" in IBM Visualization Data Explorer User's Guide for further discussion of invalid data.
Note:If data is a vector field and min and max are:
  • scalars, then the module uses min and max to exclude points whose magnitudes fall inside (or outside) the limits.
  • vectors matching the shape of the data field, then only those vector values lying between the corresponding limits are retained.

    For example, if the data are 3-D vectors, the values retained are those for which minx <= datax <= maxx and miny <= datay <= maxy and minz <= dataz <= maxz are retained (assuming exclude = 0).

Components

Modifies the "data," "positions," and "connections" components and any components that depend on "positions" or "connections." Adds an "invalid positions," "invalid connections," or "invalid faces" component if cull is set to 0. Removes the "connections" component if pointwise is set to 1. All other components are propagated to the output.

Example

In the following example, the gradient of the electron density has been mapped onto an isosurface. The Include module removes all points whose data values are greater than 1.5.

electrondensity = Import("/usr/local/dx/samples/data/watermolecule");
electrondensity = Partition(electrondensity);
gradientdensity = Gradient(electrondensity);
maggradient = Compute("mag($0)", gradientdensity);
isosurface = Isosurface(electrondensity, 0.3);
mappediso = Map(isosurface, maggradient);
camera = AutoCamera(isosurface);
included = Include(mappediso, 0, 1.5);
Display(included, camera);

Including Data Points in a Data Field

Consider a field containing position-dependent data and a "connections" component. If pointwise=0, after invalidating positions with data values outside the specified range, Include invalidates all connections that reference (include) an invalid position, and finally invalidates all positions not referred to by any valid connection. That is, no connection elements that include any invalid data values are retained--because the result of interpolation within such a connection element is not defined. For example, the following grid has valid data points (x), invalid points (i), and quad connections.

x--------x--------i--------i--------x
|        |        |        |        |
|        |        |        |        |
|        |        |        |        |
x--------x--------i--------i--------x
|        |        |        |
|        |        |        |
|        |        |        |
x--------x--------x--------x
|        |        |        |
|        |        |        |
|        |        |        |
x--------x--------x--------x
The removal of invalid points leaves three invalid connection elements (the quads marked with "o") and two data positions that have no valid connection to any other data point:
x--------x--------                  x
|        |
|        |   o
|        |
x--------x--------                  x
|        |        |        |
|        |   o    |   o    |
|        |        |        |
x--------x--------x--------x
|        |        |        |
|        |        |        |
|        |        |        |
x--------x--------x--------x
The field returned by Include is represented by the grid shown below.
x--------x
|        |
|        |
|        |
x--------x
|        |
|        |
|        |
x--------x--------x--------x
|        |        |        |
|        |        |        |
|        |        |        |
x--------x--------x--------x

Example Visual Programs

GeneralImport1.net
Thunder_cellcentered.net
SIMPLE/Include.net

See Also

 Regrid


Full Contents QuickStart Guide User's Guide User's Reference

[ OpenDX Home at IBM | OpenDX.org ]