| |
|
|
|
5
Macros
This chapter provides an introduction and comprehensive reference material for the Data Visualization Kit high level macros.
Note: Some of the macros described in this chapter are available only in the Developer Edition. Where this is the case, a line identifying this fact appears directly below the module name at the top of the page.
Visualization macros are macro objects that combine visualization base modules with UI objects in a structure that is convenient for building visualization networks and applications. Visualization macros have input/output ports and UI widgets that automatically appear on the Module Stack panel. You connect them using the Network Editor.
In Libraries.Main, the visualization macros are classified as follows:
Modules and macros that input data files from disk or create data. Geometries, for example, create objects such as slice planes, 2D and 3D axes, crosshairs, arrows, and diamonds, that are used by other modules to slice data, represent vector quantities, act as data probes, show data, and so forth.
Modules and macros that read data from disk are documented in this chapter.
Geometries are documented in Chapter 4, Geometries".
Modules and macros that primarily modify the field's Node_Data.
Modules that primarily modify the field's mesh.
Modules and macros that use the ip_Image data type for image processing. These are documented in Chapter 5, IP image processing macros".
Modules and macros that render data on the screen. These objects are part of the Graphics Display Kit, not the Data Visualization Kit. They are documented in the Graphics Display Kit manual.
Modules and macros that write data to disk files.
Visualization objects appear multiple times in a variety of places in the Libraries palette other than Main. To find them, use the Network Editor's Object Finder (see the User's Guide for details).
Most modules and macros report their status and their execution can be interrupted from the Module Stack Controls panel.
Most visualization modules and macros have sample networks that you can run showing how the object is properly connected within a network, and the kinds of effects it can produce on sample data.
Each reference page lists the sample networks that illustrate its use.
The examples are found in Libraries.Examples.Visualization in the Network Editor.
The reference pages for the modules include a path to the module. This path describes where you can locate the module in the network editor. Some modules belong to more than one library (for example, slice). To locate all paths to a particular module, use the Object Finder.
When determining which port on the icon corresponds to which documented item, remember that ports are documented from left to right. The first input port documented on the reference page is the leftmost port on the icon, the second input port documented is the second port from the left on the icon, and so on.
You can use a module or macro icon's Info panel to see the name and class of a port:
- With the cursor on the icon, press the right mouse button to activate the pulldown menu.
- Select Info. The first input port listed is the leftmost port on the icon, the second port listed is the second port from the left on the icon, and so on.
Visualization macros are defined in v/modules.v.
The Graphics Display Kit contains a GDmodes subobject called normals whose value specifies whether and how vertex normals are generated for Data Visualization Kit modules. The following table lists the allowed values for the normals subobject and their meanings:
GD_NORMALS_VERTEX is the default for most modules, and vertex normals are therefore generated.
However, for the following modules, the default setting is GD_NORMALS_NONE:
For more information on the GDmodes subobject, see Section 6.15, DefaultModes [page 6-51] in the Graphics Display Kit manual.
release massless particles into velocity field
advector releases a sample of zero mass particles into a field with a component that represents a velocity vector, for example, a fluid flow simulation. The particles have no initial direction or speed. The particles move through the velocity field according to the magnitude and direction of the vectors at the nodes in the volume. A forward differencing method is used to estimate the next position of each particle as a function of its current position and velocity (see the section labelled Algorithm on page 5-10).
Advection starts when you turn the Run toggle on. Advection for individual particles stops when one of the following conditions occurs:
- A particle exceeds the Max Segments value.
- The particle's velocity drops below the Min Velocity.
- The particle goes outside the field's bounds.
Advection of all particles stops when one of the following two conditions occurs:
The input is any mesh with Node_Data. The first component is used and must be a scalar or a two- or three-element velocity vector. You can use extract_component before this macro to get the component you want out of a multi-component field.
Any mesh whose coordinates represent the sample points. Meshes that are not unstructured are accepted, but a local unstructured version is generated during execution.
To create this sampling mesh you could use the plane object in Geometries.FPlane or the slice macro.
A Grid describing a glyph to represent the particles. This is simply a mesh describing the geometry of the glyph. Any mesh can be used (for example, that of a teapot), but for convenience you can use the Geometries objects to generate arrows or solid arrows, and so on
A port to connect to a user interface object that contains the macro's widgets. By default, it is connected to the default user interface object in the application in which the macro is instanced. (This default connection is not drawn.)
UIradioBoxLabel. A radio box to pick which of the input field's components to use as the velocity vector. The selection can be a one-, two-, or three-element vector. The default is the first (0th) component. If node data labels are present, they are displayed.
UIslider. An integer slider that sets the number of integration steps used within one grid "cell" to compute the streamline/particle path. The default is 2. The range is from 0 to 16.
UIslider. An integer slider that sets the total number of integration steps. When an individual particle exceeds this value, integration for it stops. The range is from 1 to 10000. The default is 256.
UIslider. An integer slider that sets the order of integration. Higher orders are more accurate, but execute more slowly. The default is 2. The range is from 1 to 4.
UIslider. A float slider. When a particle falls below this velocity, the integration process for that particle stops. The default is 0.00001. The range is from 0.0 to unbounded. You can use this to prevent wasted computation for particles barely moving, or even stationary (Min Velocity = 0).
UIradioBoxLabel. A radio box that controls whether particles are advected forward or backward from the starting sample points. The default is forward.
UIradioBoxLabel. A radio box that establishes how glyphs are rendered to represent the data values. (Glyphs are always colored by the magnitude of the data values in the component.) The choices are scalar, vector, or components:
Scale the glyph by the magnitude of the vector at that position. Also rotate the glyph in X, Y, (and Z) by the first, second, (and third) vector subcomponent values at that position. For example, a Cross3D in_probe would be rotated to reflect the vector values.
Scale the glyph in X, Y, (and Z) by the first, second, (and third) vector subcomponent values at that position. For example, a Cross3D in_probe's three lines would be individually scaled to match the vector values.
UItoggle. If off, the sizes of the glyphs are proportional to the data component values at each node. If on, all glyphs are the same size. The default is off.
UIslider. A float slider to adjust the sizes of the glyphs. The default is 1.00. The range is 0.0 to 100.00.
UIslider. A float. The time value along the original streamline continuum at which to start advection. (See DVadvect man page.) The default is 0.0.
UIslider. A float. The time value along the original streamline at which to halt advection of all particles. The default is 1.0.
UIslider. A float. The value by which to increment the time along the original streamline continuum for each advection step. The default is 0.2.
UIfieldTypein. An output only widget that displays the current time in the count from Start Time to End Time.
UItoggle. Starts or stops advection.
UItoggle. Reset Time to the value of Start Time.
UItoggle. When End Time is reached, start the advection again at Start Time.
The output is a new unstructured Mesh composed of the original mesh plus the meshes representing the particles. Its new Node_Data element's values represent the selected velocity component.
This output field is a new unstructured mesh of cell type Polyline that represents the streamlines. Its new Node_Data contains the selected element's velocity component. The output also contains a reference to the input field's xform.
This is a renderable version of the out_fld output field.
This is a renderable version of the out_fld1 output field.
advector uses precomputed streamlines (from DVstream) as particle paths. It integrates velocity along the streamlines to calculate the new position of the particles at each time step.
The streamlines are originally calculated using the Runge-Kutta method of specified order with adaptive time steps.
Libraries.Examples.Visualization.Advect
examples/advect.vrelease massless particles into Multi_Block velocity field
advect_multi_block releases a sample of zero mass particles into a field with a component that represents a velocity vector, for example, a fluid flow simulation. The particles move through the velocity field according to the magnitude and direction of the vectors at the nodes in the volume. A forward differencing method estimates the next position of each particle as a function of its current position and velocity (see "Algorithm" on page 5-15).
Advection starts when you turn the Run toggle on. Advection for an individual particle stops when one of the following conditions occurs:
- The particle exceeds the Max Segments value.
- The particle's velocity drops below the Min Velocity.
- The particle goes outside the field's bounds.
Advection of all particles stops when one of the following conditions occurs:
The input is a Multi_Block object. A Multi_Block object can be created with fields_to_mblock or Plot3D_Multi_Block. A Multi_Block object consists of an array of fields describing the data and some ancillary metadata. The first component of the fields' data is used and must be a scalar or a two- or three-element velocity vector. You can use mblock_to_fields, extract_component_ARR and fields_to_mblock before this macro to get the component you want from a multi-component Multi_Block.
Any mesh whose coordinates represent the sample points. Meshes that are not unstructured are accepted, but a local unstructured version is generated during execution.
To create this sampling mesh you could use the slice macro or the plane object in Geometries.FPlane.
A Grid describing a glyph to represent the particles. This is simply a mesh describing the geometry of the glyph. Any mesh can be used (for example, that of a teapot) but for convenience you can use the Geometries objects to generate arrows or solid arrows, and so on
A port to connect to a user interface object that contains the macro's widgets. By default, it is connected to the default user interface object in the application in which the macro is instanced. (This default connection is not drawn.)
UIslider. An integer slider that sets the number of integration steps used within one grid "cell" to compute the streamline/particle path. The default is 2. The range is from 0 to 16.
UIslider. An integer slider that sets the total number of integration steps. When an individual particle exceeds this value, integration for it stops. The range is from 1 to 10000. The default is 256.
UIslider. An integer slider that sets the order of integration. Higher orders are more accurate, but execute more slowly. The default is 2. The range is from 1 to 4.
UIslider. A float slider. When a particle falls below this velocity, the integration process for that particle stops. The default is 0.00001. The range is from 0.0 to unbounded. You can use this to prevent wasted computation for particles barely moving, or even stationary (Min Velocity = 0).
UIradioBoxLabel. A radio box that controls whether particles are advected forward (1) or backward (0) from the starting sample points. The default is forward.
UIradioBoxLabel. A radio box that establishes how glyphs are rendered to represent the data values. (Glyphs are always colored by the magnitude of the data values in the component.) The choices are:
Scale the glyph by the magnitude of the vector at that position. Also rotate the glyph in X, Y, (and Z) by the first, second, (and third) vector subcomponent values at that position. For example, a Cross3D in_probe would be rotated to reflect the vector values.
Scale the glyph in X, Y, (and Z) by the first, second, (and third) vector subcomponent values at that position. For example, a Cross3D in_probe's three lines would be individually scaled to match the vector values.
UItoggle. If off (0), the sizes of the glyphs are made proportional to the data component values at each node. If on (1), all glyphs are the same size. The default is off.
UIslider. A float slider to adjust the sizes of the glyphs. The default is 1.00. The range is 0.00 to 100.00.
UIslider. The time value along the original streamline continuum at which to start advection. (See DVadvect reference page.) The default is 0.0.
UIslider. The time value along the original streamline continuum at which to halt advection of all particles. The default is 1.0.
UIslider. The value by which to increment the time along the original streamline continuum for each advection step. The default is 0.2
UIfieldTypein. An output only widget that displays the current time in the count from Start Time to End Time.
UItoggle. Starts (1) or stops (0) advection.
UItoggle. Reset Time to the value of Start Time.
UItoggle. When End Time is reached, start the advection again at Start Time.
The output is a new unstructured Mesh composed of the original mesh plus the meshes representing the particles. Its new Node_Data element's values represent the selected velocity component.
This output field is a new unstructured mesh of cell type Polyline that represents the streamlines. Its new Node_Data contains the selected element's velocity component. The output also contains a reference to the input field's xform.
This is a renderable version of the out_fld output field.
This is a renderable version of the out_fld1 output field.
advect_multi_block uses precomputed streamlines (from DVstream) as particle paths. It integrates velocity along the streamlines to calculate the new position of the particles at each time step.
The streamlines are originally calculated using the Runge-Kutta method of specified order with adaptive time steps.
generate a bounding box of a 3D structured field
bounds generates lines and/or surfaces that indicate the bounding box of a 3D structured field. This is useful when you need to see the shape of an object and the structure of its mesh. For example, isosurface can produce a fairly cryptic shape floating without context in space, but when combined with bounds, you see the isosurface within its surrounding mesh.
The input field must contain any type of structured mesh (mesh type Mesh_Struct, Mesh_Unif or Mesh_Rect). Node_Data can be present, but is only used if you switch on Data.
A port to connect to a user interface object that contains the macro's widgets. By default, it is connected to the default user interface object in the application in which the macro is instanced. (This default connection is not drawn.)
UIradioBoxLabel. Selects which of the input field's components to send to the output, if Data is also turned on. The default is the first (0th) component. If node data labels are present, they are displayed.
UItoggle. When on, draws a wireframe around the perimeter extents of the mesh. The default is on.
UItoggle. When on, causes the Imin/Imax, Jmin/Jmax, Kmin/Kmax controls to produce a wireframe representation of the mesh grid at that plane. The default is off.
UItoggle. When on, causes the Imin/Imax, Jmin/Jmax, Kmin/Kmax controls to produce a solid face representing the location of that plane extent. The default is off.
UItoggle. When on, each of these switches displays the grid (Edges turned on) or plane (Faces turned on) on one of the six faces of the hull. Imin/Imax draw a mesh or face showing the 2D slice of field objects with the minimum/maximum index value in the first dimension. Jmin/Jmax draw a mesh or face showing the 2D slice of field objects with the minimum/maximum index in the second dimension. Kmin/Kmax control the third dimension. The default for all is off.
UItoggle. When on, makes bounds copy the selected component's Node_Data values at node points along the output mesh to the output field. Because the data is present, the bounds lines can be colored by the interpolated data values of the selected Node_Data component. Otherwise, the lines display as white in the renderer. The default is off.
The output field contains a new unstructured Mesh object with cell type Polyline (Edges selected) and/or Quad (Faces set) representing the bounds. If Data was selected, the output field also contains a Node_Data that is the selected component's values at nodes on the output mesh.
This is a renderable version of the output field.
Libraries.Examples.Vizualization.Crop
examples/crop.vproduce a Point mesh representing geometric centers of each cells
cell_centers module produces a mesh containing Point cell set, each point of which represents a geometrical center of a corresponding cell in the input mesh. The coordinates of cell centers are calculated by averaging coordinates of all the nodes of a cell. The number of nodes in the output mesh is equal to number of cells in the input mesh. If the input mesh contains Cell_Data it becomes a Node_Data in the output mesh with each node values equal to corresponding cell value. You can use this module to create a position mesh for the glyph module (see Section 5.45, glyph [page 5-105]).
The input must contain any type of mesh.
The output field contains a new mesh that consists of points representing geometrical centers of a corresponding cells in the input mesh.geoetric centers. It also may contain a Node_Data that corresponds to Cell_Data in the input mesh.
This is a renderable version of the output field.
Libraries.Examples.Visualization.Cylinder_Plot_Unif
examples/cyl_plot_unif.v