7. Isovalues - Segment,Contour,Threshold,IsoLabel

Four modules, Segment, Contour, Threshold, and IsoLabel provide a general isovalue visualization capability for scalar fields in 1D, 2D and 3D domains. This capability includes contour line, color filled contour, continuous tone, isosurface, vector surface and dot surface generation. All isovalue modules accept curvilinear, rectilinear and uniform computational cell arrays. However, each module is designed to produce isovalue displays on only a certain subset of cell topologies. The Segment module accepts 1D topologies (line), the Contour module accepts 2D topologies (triangle and quadrilateral) and the Threshold module accepts 3D topologies (tetrahedron, pyramid, wedge and hexahedron). All isovalue modules produce at least two types of isovalue displays; a discrete representation of an isovalue such as a contour line or isosurface, and a continuous representation of the region between discrete isovalues such as a color filled contour plot or so-called fringe plot. The number of isovalues generated by an isovalue module is determined by the number of levels defined in the Levels object set as an attribute object.

Each isovalue module may be requested to perform a data interpolation function while generating an isovalue display. For example, the Threshold module can interpolate all components of a stress tensor to an isosurface of a given scalar field. Any isovalue module which has been put into the data interpolation mode invokes the "data" drawing functions rather than the attribute and graphics primitive drawing functions. This allows isovalue regions such as isosurfaces to be used as sampling planes to produce displays such as contour plots on arbitrary cutting planes. Data interpolation is activated in any isovalue module by setting a DataInt object as an attribute object.

The IsoLabel module is specifically designed to be used with the Contour module to generate contour line labeling. It operates by storing the line primitives generated by Contour and performing a global analysis to generate appropriately sized and positioned labels for the individual contour lines.

Table of Contents

7.1 1D Domains - Segment

Represent isovalues of scalar fields along lines. Geometry is input as individual polylines. No special functions are provided for rectilinear or uniform polylines. Isovalue displays may be generated as color filled line segments between isovalue intersections or as points at isovalue intersections. Color may be mapped to the scalar field magnitude. The methods associated with a Segment object are the following.

Begin and end an instance of an object, return object error flag

*vis_SegmentBegin        - create an instance of a Segment object
vis_SegmentEnd           - destroy an instance of a Segment object
vis_SegmentError         - return Segment object error flag

Operations

vis_SegmentComputeGrad   - compute gradients of a scalar field
vis_SegmentCurv          - draw isovalues along a polyline
vis_SegmentGetExit       - get isovalue intersection information
vis_SegmentPolyLineData  - draw isovalues on PolyLineData primitive
vis_SegmentSetContinuous - set continuous line mode
vis_SegmentSetObject     - set pointers to attribute objects.
vis_SegmentSetTopology   - set input cell topology
vis_SegmentTrav          - traverse and draw a group of element edges.

Instance a Segment object using vis_SegmentBegin. Set attribute objects using vis_SegmentSetObject. The current edge topology is specified using vis_SegmentSetTopology. Draw isovalues on edges using vis_SegmentCurv. The convenience routine, vis_SegmentTrav, will traverse and draw isovalues on a group of element edges.

Table of Contents

7.2 Attribute Objects

A Segment object uses DrawFun, Levels, ColorMap and VisContext objects to define attributes required to generate a segment visualization. The color of points may be mapped to scalar field magnitude. All line segments drawn between isovalue intersections are color mapped to scalar field magnitude. Use a DataInt object to activate data interpolation. Use a IsoClip object to activate isosurface clipping. If model traversal is performed using vis_EdgeTrav, then a GridFun object is required and an IdTran object is optional for specifying entity color. A Segment object uses the following VisContext components.

Color: Point color if color not mapped to field value. Accent color.
Draw: Flag to call graphics attribute and graphics primitive drawing functions.
Flags: OR the following flags: VIS_ISOVALACCENT marks the isovalue intersection with a point using the visualization context Color value. if IsoValType is VIS_ISOVALFRINGE or VIS_ISOVALTONE. VIS_CYLINDERCAP generates disk-like caps at the ends of edges drawn with a LineStyle of VIS_CYLINDER.
Frequency: Frequency with which segment points are labelled. If Frequency = 0, segment points are not labelled, Frequency = 1 labels every segment point, Frequency = 2 labels every other segment point, etc. Labels are single characters in the following sequence of 36 characters 1, 2, ..., 9, 0, a, ...,z. Labeling occurs only if IsoValType is VIS_ISOVALPOINT
IsoValInterp: Interpolation method.
IsoValType: One of the following segment types: VIS_ISOVALPOINT draws discrete points at isovalue intersections; VIS_ISOVALFRINGE draws constant color line segments between isovalue intersections; VIS_ISOVALTONE draws continuous color line segments between isovalue intersections; VIS_ISOVALGOURAUD draws continuous color line segments between segment point locations. Isovalue intersections are not isolated.
LineWidth: Line width of line segments
LineStyle: Line style of line segments
MapColor: Flag to map point color to field value, Color is ignored.
PointSize: Point size used for points
PrimType: Primitive type output
Refinement: Level of refinement
Shade: Attribute to determine the type of polygon normals generated.
Shrink: Shrink factor used during model traversal only
ShrinkType: Shrink type used during model traversal only
Size: Unit line width of cylindrical line style.

The Segment object calls the following grid functions set in the GridFun attribute object.

Coords
ElemNode
Number
Topology

Figure 7-1 illustrates segment fringes of displacement in which a wide cylindrical line style has been used on the "free" edges of the finite element model and a unit width, solid line style has been used on the interior edges.

Figure 7-1, Segment Fringes

Table of Contents

7.3 Function Descriptions

The currently available Segment functions are described in detail in this section.

Table of Contents , Segment

NAME

*vis_SegmentBegin - create an instance of a Segment object

C SPECIFICATION

vis_Segment *vis_SegmentBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Segment object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Segment object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. The cell topology is set to a line element, ie. a simple straight line defined by two endpoints.

Destroy an instance of a Segment object using

     void vis_SegmentEnd (vis_Segment *segment)

Return the current value of a Segment object error flag using

     Vint vis_SegmentError (vis_Segment *segment)

Table of Contents , Segment

NAME

vis_SegmentComputeGrad - compute gradients of a scalar field

C SPECIFICATION

void vis_SegmentComputeGrad (vis_Segment *segment,
                             Vfloat s[],
                             Vfloat x[][3],
                             Vint nflag,
                             Vfloat v[][3])

INPUT ARGUMENTS

segment      Pointer to Segment object.
s            Array of scalar field values.
x            Array of locations.
nflag        Normalize flag

OUTPUT ARGUMENTS

v            Array of gradients

DESCRIPTION

Compute gradients, v, of the scalar field, s, at the point locations, x. An option is provided to normalize the computed gradient vectors. The gradient vectors will be tangent to the edge at the point locations, x.

Table of Contents , Segment

NAME

vis_SegmentCurv - draw isovalues along a polyline

C SPECIFICATION

void vis_SegmentCurv (vis_Segment *segment,
                      Vfloat s[], 
                      Vfloat x[][3])

INPUT ARGUMENTS

segment      Pointer to Segment object.
s            Array of scalar field values.
x            Array of locations.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_NULLOBJECT is generated if no DrawFun or VisContext attribute objects are set.

DESCRIPTION

Draw isovalues of scalar field s along a polyline with point locations x. Data value interpolation, if requested, is performed.

Table of Contents , Segment

NAME

vis_SegmentGetExit - get isovalue intersection information

C SPECIFICATION

void vis_SegmentGetExit (vis_Segment *segment,
                         Vfloat s[],
                         Vint *flag)

INPUT ARGUMENTS

segment      Pointer to Segment object.
s            Array of scalar field values.

OUTPUT ARGUMENTS

flag         Edge flag intersected by isovalues

DESCRIPTION

Get isovalue intersection information for scalar field values s. If there are no isovalue intersections flag is zero. If isovalue intersections occur, then flag = 1.

Table of Contents , Segment

NAME

vis_SegmentPolyLineData - draw isovalues on PolyLineData primitive

C SPECIFICATION

void vis_SegmentPolyLineData (vis_Segment *segment,
                             Vint polylinetype,
                             Vint npts,
                             Vfloat x[][3],
                             Vint nrws, Vfloat d[])

INPUT ARGUMENTS

segment      Pointer to Segment object.
polygontype  Type of polygline to draw
npts         Number of vertices in polyline primitive
x            Vertex world coordinates
nrws         Number of values in d vector, must be 1.
d            Array of scalar field values.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_NULLOBJECT is generated if no DrawFun or VisContext attribute objects are set. VIS_ERROR_VALUE is generated if nrws is not equal to 1.

DESCRIPTION

Draw isovalues of scalar field d over a PolyLineData graphics primitive. This function has the same prototype as the PolyLineData drawing function. Use this function to draw the output from a Contour object which is performing data interpolation for generating a edge contour plot on a cutting line.

Table of Contents , Segment

NAME

vis_SegmentSetContinuous - set continuous line mode

C SPECIFICATION

void vis_SegmentSetContinuous (vis_Segment *segment,
                               Vint flag)

INPUT ARGUMENTS

segment      Pointer to Segment object.
flag         Flag for beginning of new continuous line
             =VIS_ON           Starts continuous line mode
             =VIS_OFF          Terminates continuous line mode

OUTPUT ARGUMENTS

None

ERRORS

None

DESCRIPTION

Indicate the start of a new continuous line. When in continuous line mode, successive lines drawn with vis_SegmentCurv or vis_SegmentPolyLineData with VIS_CYLINDER line style will have their end curves matched for a continuous cylindrical display. A new call with flag set to VIS_ON indicates the start of a new continuous line and terminates any previously continuous line. If flag is set to VIS_OFF the continuous line mode is terminated. Default value for flag is VIS_OFF.

Table of Contents , Segment

NAME

vis_SegmentSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_SegmentSetObject (vis_Segment *segment,
                           Vint objecttype,
                           Vobject *object)

INPUT ARGUMENTS

segment      Pointer to Segment object.
objecttype   The name of the object type to be set.
             =VIS_COLORMAP           ColorMap object
             =VIS_DATAINT            DataInt object
             =VGL_DRAWFUN            DrawFun object
             =VIS_GRIDFUN            GridFun object
             =VIS_IDTRAN_COLOR       IdTran color map index object
             =VIS_IDTRAN_DATAINDEX   IdTran data index object
             =VIS_ISOCLIP            IsoClip object
             =VIS_LEVELS             Levels object
             =VIS_VISCONTEXT         VisContext object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. If an IsoClip attribute object is set then isosurface clipping is activated. To deactivate isosurface clipping, set a NULL IsoClip object pointer. If a DataInt object is set then data interpolation is activated. To deactivate data interpolation, set a NULL DataInt object pointer. The GridFun and IdTran objects are only used by vis_SegmentTrav.

Table of Contents , Segment

NAME

vis_SegmentSetTopology - set cell topology

C SPECIFICATION

void vis_SegmentSetTopology (vis_Segment *segment,
                             Vint shape,
                             Vint maxi)

INPUT ARGUMENTS

segment      Pointer to Segment object.
shape        Cell shape parameter
             =VIS_SHAPELINE          Line
maxi         Topology parameter

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if a maxi less than 0 or equal to 1 is input. VIS_ERROR_ENUM is generated if an improper shape is input.

DESCRIPTION

Set cell topology. All subsequent draw and computation methods assume lines of this topology. See section VisTools, Computational Cells for a description of element topology conventions.

Table of Contents , Segment

NAME

vis_SegmentTrav - traverse and draw a group of element edges.

C SPECIFICATION

void vis_SegmentTrav (vis_Segment *segment,
                      vis_State *state,
                      vis_Group *group)

INPUT ARGUMENTS

segment      Pointer to Segment object.
state        Pointer to State object of node or element node scalars
group        Pointer to Group object of element edges.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_NULLOBJECT is generated if a DrawFun or GridFun attribute object has not been set. VIS_ERROR_NULLOBJECT is generated if the input State or Group object is NULL.

DESCRIPTION

Traverse and draw isovalues of a scalar field contained in state on a group of element edges specified in group.

If color mapping is turned off, the isovalues are drawn with the constant color specified in the visualization context unless an IdTran attribute object is set which contains a color map index for each element. If a VIS_IDTRAN_DATAINDEX IdTran attribute object has been set then a DataIndex drawing function is called with the value contained in the IdTran object prior to drawing the edges for an element.

The underlying model information is accessed using the GridFun attribute object. Set the GridFun and IdTran objects using vis_SegmentSetObject. The visualization contexts Shrink and ShrinkType can be used to control shrink.

Table of Contents

7.4 2D Domains - Contour

Represent isovalues of scalar fields on triangular and quadrilateral cells. Isovalue displays may be generated as discrete contour lines or color filled surfaces between contour lines. Color may be mapped to the scalar field magnitude.

The Contour module may be asked to return the contour levels intersecting each exterior edge of a cell. This information may be used to track individual contour lines from cell to cell. For example, a single contour line may be tracked over a surface without searching every cell by using the contour exit edges and cell adjacency information provided by the application. The methods associated with a Contour object are the following.

Begin and end an instance of an object, return object error flag

*vis_ContourBegin        - create an instance of a Contour object
vis_ContourEnd           - destroy an instance of a Contour object
vis_ContourError         - return Contour object error flag

Operations

vis_ContourComputeGrad   - compute gradients of a scalar field
vis_ContourComputeNorm   - compute normals to curvilinear surface
vis_ContourCurv          - draw isovalues on a curvilinear surface
vis_ContourGetExit       - get isovalue intersection information
vis_ContourPolygonData   - draw isovalues on PolygonData primitive
vis_ContourSetObject     - set pointers to attribute objects.
vis_ContourSetTopology   - set input cell topology
vis_ContourTrav          - traverse and draw a group of element faces.

Instance a Contour object using vis_ContourBegin. Set attribute objects using vis_ContourSetObject. The current face topology is specified using vis_ContourSetTopology. Draw isovalues on faces using vis_ContourCurv. The convenience routine, vis_ContourTrav, will traverse and draw isovalues on a group of element faces.

Table of Contents

7.5 Attribute Objects

A Contour object uses DrawFun, Levels, ColorMap, TransMap and VisContext objects to define attributes required to generate a contour visualization. The color of contour lines may be mapped to scalar field magnitude. All color filled contours drawn between contour lines are color mapped to scalar field magnitude. If a TransMap attribute object is not set any specified constant transparency or transparency mapping is ignored. Use a DataInt object to activate data interpolation. Use a IsoClip object to activate isosurface clipping. If model traversal is performed using vis_ContourTrav, then a GridFun object is required and IdTran objects are optional for specifying entity color and transparency. A Contour object uses the following VisContext components.

Color: Contour color if color not mapped to field value. Accent color.
Draw: Flag to call graphics attribute and graphics primitive drawing functions.
Flags: OR the following flags: VIS_ISOVALACCENT marks the isovalue intersection with a contour line using the visualization context Color value. if IsoValType is VIS_ISOVALFRINGE or VIS_ISOVALTONE.
Frequency: Frequency with which contour lines are labelled. If Frequency = 0, contour lines are not labelled, Frequency = 1 labels every contour line, Frequency = 2 labels every other contour line, etc. Labels are single characters in the following sequence of 36 characters 1, 2, ..., 9, 0, a, ...,z. Labeling occurs only if IsoValType is VIS_ISOVALLINE
IsoValInterp: Interpolation method.
IsoValType: One of the following contour types: VIS_ISOVALLINE draws discrete contour lines at isovalue intersections; VIS_ISOVALFRINGE draws constant color filled surfaces between contour lines; Any area falling below the first level is given the constant color associated with level zero. VIS_ISOVALTONE draws continuous color filled surfaces between contour lines. Any area falling below the first level is given the constant color associated with level zero. VIS_ISOVALGOURAUD draws elements or cells with RGB colors mapped to scalar field values at point locations. Isovalue intersections are not isolated. Any vertex falling below the first level is given the color associated with level zero. VIS_ISOVALTEXTURE draws elements or cells with one-dimensional texture coordinates mapped to scalar field values at point locations. The texture coordinates in the interval [0.,1.] are mapped linearly to the minimum and maximum values set in the Levels attribute object. Use vis_LevelsSetMinMax to set the scalar field extremes. The function vis_ColorMapLevelsGetColors may be useful in generating the texture map associated with the texture coordinates. Isovalue intersections are not isolated.
LineWidth: Line width of line contours
LineStyle: Line style of line contours
MapColor: Flag to map contour line color to field value, Color is ignored.
MapTrans: Flag to map transparency of color filled surfaces to field value, Transparency is ignored.
PointSize: Point size multiplier
Refinement: Level of refinement
Reflect: Flag to reverse sense of output polygons. This flag is useful to contour the bottom face of shell elements.
Shade: Attribute to determine the type of polygon normals generated.
Shrink: Shrink factor used during model traversal only
ShrinkType: Shrink type used during model traversal only
Size: Unit line width of cylindrical line style.
Transparency: Color filled surface transparency if transparency not mapped to field value.

The Contour object calls the following grid functions set in the GridFun attribute object.

Coords
ElemNode
Number
Topology

Figure 7-2 illustrates fringes and contours of displacement on the external faces of a finite element model.

Figure 7-2, Fringes and Contours on External Faces

Figure 7-3 illustrates contours of displacement on all internal and external faces. Notice that this technique yields a wire frame isosurface representation.

Figure 7-3, Contours on all Faces

Table of Contents

7.6 Function Descriptions

The currently available Contour functions are described in detail in this section.

Table of Contents , Contour

NAME

*vis_ContourBegin - create an instance of a Contour object

C SPECIFICATION

vis_Contour *vis_ContourBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Contour object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Contour object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. The cell topology is set to a 4 noded quadrilateral element.

Destroy an instance of a Contour object using

     void vis_ContourEnd (vis_Contour *contour)

Return the current value of a Contour object error flag using

     Vint vis_ContourError (vis_Contour *contour)

Table of Contents , Contour

NAME

vis_ContourComputeGrad - compute gradients of a scalar field

C SPECIFICATION

void vis_ContourComputeGrad (vis_Contour *contour,
                             Vfloat s[],
                             Vfloat x[][3],
                             Vint nflag,
                             Vfloat v[][3])

INPUT ARGUMENTS

contour      Pointer to Contour object.
s            Array of scalar field values.
x            Array of locations.
nflag        Normalize flag

OUTPUT ARGUMENTS

v            Array of gradients

DESCRIPTION

Table of Contents , Contour

NAME

vis_ContourComputeNorm - compute normals to curvilinear face

C SPECIFICATION

void vis_ContourComputeNorm (vis_Contour *contour,
                             Vfloat x[][3],
                             Vfloat v[][3])

INPUT ARGUMENTS

contour      Pointer to Contour object.
x            Array of locations.

OUTPUT ARGUMENTS

v            Array of normal vectors at each point.

DESCRIPTION

Compute normals to a curvilinear face. The normal vectors, v, are computed at point locations, x.

Table of Contents , Contour

NAME

vis_ContourCurv - draw isovalues on a curvilinear surface

C SPECIFICATION

void vis_ContourCurv (vis_Contour *contour,
                      Vfloat s[], 
                      Vfloat x[][3],
                      Vint vflag,
                      Vfloat v[][3])

INPUT ARGUMENTS

contour      Pointer to Contour object.
s            Array of scalar field values.
x            Array of locations.
vflag        User supplied face normal flag
             =VIS_NODATA             No normals provided
             =VIS_VERTEXDATA         Vertex normals are provided
v            Array of user supplied normals

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_NULLOBJECT is generated if no DrawFun or VisContext attribute objects are set.

DESCRIPTION

Draw isovalues of scalar field s over a surface with point locations x and optional normals v. Data value interpolation, if requested, is performed. If normals are not supplied by the user, this function will calculate them if the Shade visualization context is set to VIS_VERTEXSHADE.

Table of Contents , Contour

NAME

vis_ContourGetExit - get isovalue intersection information

C SPECIFICATION

void vis_ContourGetExit (vis_Contour *contour,
                         Vfloat s[],
                         Vint *flags)

INPUT ARGUMENTS

contour      Pointer to Contour object.
s            Array of scalar field values.

OUTPUT ARGUMENTS

flags        Bit flags of edges intersected by isovalues

DESCRIPTION

Get isovalue intersection information. If there are no isovalue intersections then flags = 0. If isovalue intersections occur, then the bits in flags are set to the intersected edges.

Table of Contents , Contour

NAME

vis_ContourPolygonData - draw isovalues on PolygonData primitive

C SPECIFICATION

void vis_ContourPolygonData (vis_Contour *contour,
                             Vint polygontype,
                             Vint npts,
                             Vfloat x[][3],
                             Vint nrws, Vfloat d[],
                             Vint vflag, Vfloat v[])

INPUT ARGUMENTS

contour      Pointer to Contour object.
polygontype  Type of polygon to draw
npts         Number of vertices in polygon primitive
x            Vertex world coordinates
nrws         Number of values in d vector, must be 1.
d            Array of scalar field values.
vflag        Normal vector and vertex texture coordinate flag.
v            Normal vectors and texture coordinates.  Normal vectors for
             each facet or vertex appear first followed by texture
             coordinates for each vertex.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_NULLOBJECT is generated if no DrawFun or VisContext attribute objects are set. VIS_ERROR_VALUE is generated if nrws is not equal to 1.

DESCRIPTION

Draw isovalues of scalar field d over a PolygonData graphics primitive. This function has the same prototype as the PolygonData drawing function. Use this function to draw the output from a Threshold object which is performing data interpolation for generating a contour plot on a cutting plane.

Table of Contents , Contour

NAME

vis_ContourSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_ContourSetObject (vis_Contour *contour,
                           Vint objecttype,
                           Vobject *object)

INPUT ARGUMENTS

contour      Pointer to Contour object.
objecttype   The name of the object type to be set.
             =VIS_COLORMAP           ColorMap object
             =VIS_DATAINT            DataInt object
             =VGL_DRAWFUN            DrawFun object
             =VIS_GRIDFUN            GridFun object
             =VIS_IDTRAN_COLOR       IdTran color map index object
             =VIS_IDTRAN_DATAINDEX   IdTran data index object
             =VIS_IDTRAN_TRANS       IdTran transparency map index object
             =VIS_ISOCLIP            IsoClip object
             =VIS_LEVELS             Levels object
             =VIS_TRANSMAP           TransMap object
             =VIS_VISCONTEXT         VisContext object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Table of Contents , Contour

NAME

vis_ContourSetTopology - set cell topology

C SPECIFICATION

void vis_ContourSetTopology (vis_Contour *contour,
                             Vint shape,
                             Vint maxi, 
                             Vint maxj)

INPUT ARGUMENTS

contour      Pointer to Contour object.
shape        Shape parameter
             =VIS_SHAPETRI           Triangle
             =VIS_SHAPEQUAD          Quadrilateral
             =VIS_SHAPEPOLYGON       Polygon
maxi         Topology parameters
maxj

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if a maxi or maxj less than 0 or equal to 1 is input. VIS_ERROR_ENUM is generated if an improper shape is input.

DESCRIPTION

Set cell topology. All subsequent draw and computation methods, assume cells of this topology. Refinement is only to Serendipity and Lagrange finite element topologies and polygon shapes. See section VisTools, Computational Cells for a description of element topology conventions.

Table of Contents , Contour

NAME

vis_ContourTrav - traverse and draw a group of element faces.

C SPECIFICATION

void vis_ContourTrav (vis_Contour *contour,
                      vis_State *state,
                      vis_Group *group,
                      vis_ElemDat *elemdat)

INPUT ARGUMENTS

contour      Pointer to Contour object.
state        Pointer to State object of node or element node scalars
group        Pointer to Group object of element faces.
elemdat      Pointer to ElemDat object of element face normals.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_NULLOBJECT is generated if a DrawFun or GridFun attribute object has not been set. VIS_ERROR_NULLOBJECT is generated if the input State or Group object is NULL.

DESCRIPTION

Traverse and draw isovalues of a scalar field contained in state on a group of element faces specified in group with optional normals specified by elemdat. If the elemdat object is NULL this function will calculate face normals if the Shade visualization context is set to VIS_VERTEXSHADE.

The underlying model information is accessed using the GridFun attribute object. Set the GridFun and IdTran objects using vis_ContourSetObject. The visualization contexts Shrink and ShrinkType can be used to control shrink.

Table of Contents

7.7 3D Domains - Threshold

Represent isovalues of scalar fields within tetrahedra, pyramids, wedges and hexahedra. Isovalue displays may be generated as discrete isosurfaces or color filled volumes between isosurfaces. Color may be mapped to the scalar field magnitude. The Threshold module may be asked to return the threshold levels intersecting each exterior face of the cell. Use this information to track individual threshold surfaces throughout a volume. The methods associated with a Threshold object are the following.

Begin and end an instance of an object, return object error flag

*vis_ThresholdBegin      - create an instance of a Threshold object
vis_ThresholdEnd         - destroy an instance of a Threshold object
vis_ThresholdError       - return Threshold object error flag

Operations

vis_ThresholdComputeGrad - compute gradients of a scalar field
vis_ThresholdCurv        - draw isovalues within a curvilinear volume
vis_ThresholdGetExit     - get isovalue intersection information
vis_ThresholdSetElemNode - set input polyhedral cell connectivity
vis_ThresholdSetObject   - set pointers to attribute objects.
vis_ThresholdSetParami   - set parameters for visualization
vis_ThresholdSetTopology - set input cell topology
vis_ThresholdTrav        - traverse and draw a group of elements

Instance a Threshold object using vis_ThresholdBegin. Set attribute objects using vis_ThresholdSetObject. The current cell topology is specified using vis_ThresholdSetTopology. If the current cell topology is polyhedral, ie VIS_SHAPEPOLYHED, it is recommended for performance reasons that the polyhedral node connectivity be entered using vis_ThresholdSetElemNode and the use of it toggled using vis_ThresholdSetParami.

Draw isovalues in cells using vis_ThresholdCurv. The convenience routine, vis_ThresholdTrav, will traverse and draw isovalues in a group of cells.

Table of Contents

7.8 Attribute Objects

A Threshold object uses DrawFun, Levels, ColorMap, TransMap and VisContext objects to define attributes required to generate a threshold visualization. The color of isosurfaces may be mapped to scalar field magnitude. All color filled volumes drawn between isosurfaces are color mapped to scalar field magnitude. If a TransMap attribute object is not set any specified constant transparency or transparency mapping is ignored. Use a DataInt object to activate data interpolation. Use a IsoClip object to activate isosurface clipping. If model traversal is performed using vis_ThresholdTrav, then a GridFun object is required and IdTran objects are optional for specifying entity color and transparency. A Threshold object uses the following VisContext components.

Color: Threshold color if color not mapped to field value.
Draw: Flag to call graphics attribute and graphics primitive drawing functions.
Flags: OR the following flags: VIS_CREATEPOLYHEDRON generates polyhedral graphics primitives rather than the default polypoint primitives for IsoValType set to VIS_ISOVALFRINGE, VIS_ISOVALTONE and VIS_ISOVALGOURAUD.
IsoValInterp: Interpolation method.
IsoValType: One of the following threshold types: VIS_ISOVALSURFACE draws discrete isosurfaces at isovalue intersections; VIS_ISOVALFRINGE draws filled volumes with clouds of constant colored points at constant densities between isosurfaces. VIS_ISOVALTONE and VIS_ISOVALGOURAUD draw filled volumes with clouds of varying colored points at varying densities between isosurfaces.
MapColor: Flag to map isosurface color to field value, Color is ignored.
MapTrans: Flag to map transparency of isosurfaces or color filled volumes to field value, Transparency is ignored.
PointSize: Point size used for points
Refinement: Level of refinement
Shade: Attribute to determine the type of polygon normals generated.
Shrink: Shrink factor used during model traversal only
ShrinkType: Shrink type used during model traversal only
Size: For IsoValType of VIS_ISOVALFRINGE, VIS_ISOVALTONE or VIS_ISOVALGOURAUD this value represents the spacing of points associated with a transparency of 0.
Transparency: Color filled surface or volume transparency if transparency not mapped to field value.

The Threshold object calls the following grid functions set in the GridFun attribute object.

Coords
ElemNode
Number
Topology

Figure 7-4 illustrates isosurfaces of displacement. The feature edges of the finite element model are also drawn for reference.

Figure 7-4, Isosurfaces

Table of Contents

7.9 Function Descriptions

The currently available Threshold functions are described in detail in this section.

Table of Contents , Threshold

NAME

*vis_ThresholdBegin - create an instance of a Threshold object

C SPECIFICATION

vis_Threshold *vis_ThresholdBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Threshold object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Threshold object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. The cell topology is set to a 8 noded hexahedral element.

Destroy an instance of a Threshold object using

     void vis_ThresholdEnd (vis_Threshold *threshold)

Return the current value of a Threshold object error flag using

     Vint vis_ThresholdError (vis_Threshold *threshold)

Table of Contents , Threshold

NAME

vis_ThresholdComputeGrad - compute gradients of a scalar field

C SPECIFICATION

void vis_ThresholdComputeGrad (vis_Threshold *threshold,
                               Vfloat s[],
                               Vfloat x[][3],
                               Vint nflag,
                               Vfloat v[][3])

INPUT ARGUMENTS

threshold    Pointer to Threshold object.
s            Array of scalar field values.
x            Array of locations.
nflag        Normalize flag

OUTPUT ARGUMENTS

v            Array of gradients

DESCRIPTION

Compute gradients, v, of the scalar field, s, at the point locations, x. An option is provided to normalize the computed gradient vectors. These normalized gradients may be used to implement gradient shading of isosurfaces.

Table of Contents , Threshold

NAME

vis_ThresholdCurv - draw isovalues within a curvilinear volume

C SPECIFICATION

void vis_ThresholdCurv (vis_Threshold *threshold,
                        Vfloat s[], 
                        Vfloat x[][3],
                        Vint vflag,
                        Vfloat v[][3])

INPUT ARGUMENTS

threshold    Pointer to Threshold object.
s            Array of scalar field values.
x            Array of locations.
vflag        User supplied normalized field gradient flag
             =VIS_NODATA             No gradients provided
             =VIS_VERTEXDATA         Vertex gradients are provided
v            Array of user supplied normalized gradients

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_NULLOBJECT is generated if no DrawFun or VisContext attribute objects are set.

DESCRIPTION

Draw isovalues of scalar field s within a volume with point locations x and optional gradients v. Data value interpolation, if requested, is performed. If normalized gradients are not supplied by the user, this function will calculate them if the Shade visualization context is set to VIS_VERTEXSHADE.

Table of Contents , Threshold

NAME

vis_ThresholdGetExit - get isovalue intersection information

C SPECIFICATION

void vis_ThresholdGetExit (vis_Threshold *threshold,
                           Vfloat s[],
                           Vint *flags)

INPUT ARGUMENTS

threshold    Pointer to Threshold object.
s            Array of scalar field values.

OUTPUT ARGUMENTS

flags        Bit flags of faces intersected by isovalues

DESCRIPTION

Get isovalue intersection information. If there are no isovalue intersections then flags = 0. If isovalue intersections occur, then the bits in flags are set to the intersected faces.

Table of Contents , Threshold

NAME

vis_ThresholdSetElemNode - set input polyhedral cell connectivity

C SPECIFICATION

void vis_ThresholdSetElemNode (vis_Threshold *threshold,
                               Vint ix[])

INPUT ARGUMENTS

threshold    Pointer to Threshold object.
ix           Element connectivity

OUTPUT ARGUMENTS

None

DESCRIPTION

Set polyhedral element connectivity. This information is currently only required for element shape VIS_SHAPEPOLYHED. The use of polyhedral connectivity is optional and is toggled using vis_ThresholdSetParami.

Table of Contents , Threshold

NAME

vis_ThresholdSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_ThresholdSetObject (vis_Threshold *threshold,
                             Vint objecttype,
                             Vobject *object)

INPUT ARGUMENTS

threshold    Pointer to Threshold object.
objecttype   The name of the object type to be set.
             =VIS_COLORMAP           ColorMap object
             =VIS_DATAINT            DataInt object
             =VGL_DRAWFUN            DrawFun object
             =VIS_GRIDFUN            GridFun object
             =VIS_IDTRAN_COLOR       IdTran color map index object
             =VIS_IDTRAN_DATAINDEX   IdTran data index object
             =VIS_IDTRAN_TRANS       IdTran transparency map index object
             =VIS_ISOCLIP            IsoClip object
             =VIS_LEVELS             Levels object
             =VIS_TRANSMAP           TransMap object
             =VIS_VISCONTEXT         VisContext object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Table of Contents , Threshold

NAME

vis_ThresholdSetParami - set parameters for visualization

C SPECIFICATION

void vis_ThresholdSetParami (vis_Threshold *threshold,
                             Vint ptype,
                             Vint iparam)

INPUT ARGUMENTS

threshold    Pointer to Threshold object.
ptype        Parameter type to set.
             =THRESHOLD_USERELEMNODE  Enable using polyhedral connectivity
iparam       Specifies the integer value that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify parameters for controlling visualization. The parameter THRESHOLD_USERELEMNODE is used to enable the use of the user specified polyhedral connectivity using vis_ThresholdSetElemNode. By default, THRESHOLD_USERELEMNODE is off.

Table of Contents , Threshold

NAME

vis_ThresholdSetTopology - set cell topology

C SPECIFICATION

void vis_ThresholdSetTopology (vis_Threshold *threshold,
                               Vint shape,
                               Vint maxi, 
                               Vint maxj, 
                               Vint maxk)

INPUT ARGUMENTS

threshold    Pointer to Threshold object.
shape        Cell shape parameter
             =VIS_SHAPETET           Tetrahedron
             =VIS_SHAPEPYR           Pyramid
             =VIS_SHAPEWED           Wedge
             =VIS_SHAPEHEX           Hexahedron
             =VIS_SHAPEPOLYHED       Polyhedron
maxi         Topology parameters
maxj         
maxk

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if a maxi, maxj or maxk less than 0 or equal to 1 is input. VIS_ERROR_ENUM is generated if an improper shape is input.

DESCRIPTION

Set cell topology. All subsequent draw and computation methods assume cells of this topology. Refinement is only applied to Serendipity and Lagrange finite element topologies and polyhedron shapes. See section VisTools, Computational Cells for a description of element topology conventions.

Table of Contents , Threshold

NAME

vis_ThresholdTrav - traverse and draw a group of cells

C SPECIFICATION

void vis_ThresholdTrav (vis_Threshold *threshold,
                        vis_State *state,
                        vis_Group *group,
                        vis_State *statev)

INPUT ARGUMENTS

threshold    Pointer to Threshold object.
state        Pointer to State object of node or element node scalars
group        Pointer to Group object of elements, element faces or edges
             If NULL, then all elements are assumed.
statev       Pointer to State object of node or element node normalized
             gradient vectors.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_NULLOBJECT is generated if a DrawFun or GridFun attribute object has not been set. VIS_ERROR_NULLOBJECT is generated if the input State object is NULL.

DESCRIPTION

Traverse and draw isovalues of a scalar field contained in state in a group of cells specified in group with optional normalized gradients specified by statev. Only elements which have a shape accepted by vis_ThresholdSetTopology are processed. If the statev object is NULL this function will calculate element node normalized gradients if the Shade visualization context is set to VIS_VERTEXSHADE.

The underlying model information is accessed using the GridFun attribute object. Set the GridFun and IdTran objects using vis_ThresholdSetObject. The visualization contexts Shrink and ShrinkType can be used to control shrink.

Table of Contents

7.10 2D Contour Line Labeling - IsoLabel

Add labels to isolines generated by Contour. These labels are positioned on the screen based on device or world coordinate spacing intervals. Labels can be oriented along the isolines or horizontally, and can take the color of the lines at their point of insertion or their own color. Labels can also be added at specific isovalue frequencies to avoid overloading the image. The methods associated with a IsoLabel object are the following.

Begin and end an instance of an object, return object error flag

*vis_IsoLabelBegin        - create an instance of a IsoLabel object
vis_IsoLabelEnd           - destroy an instance of a IsoLabel object
vis_IsoLabelError         - return IsoLabel object error flag

Operations

vis_IsoLabelReset         - clear the contents
vis_IsoLabelSetObject     - set pointers to attribute objects
vis_IsoLabelSetParam      - set parameters
vis_IsoLabelDraw          - draw labels

Instance a IsoLabel object using vis_IsoLabelBegin. Set attribute objects using vis_IsoLabelSetObject. Set integer or floating point control parameters using vis_IsoLabelSetParami and vis_IsoLabelSetParamf, respectively.

The IsoLabel module is designed to accumulate contour segment information from the Contour module and use this to generate a set of labels which will annotate each of the isovalue lines which are represented by the contour segments. As part of this process, IsoLabel will geometrically merge all the contour segments into a set of isovalue line strips. Then it will perform a label positioning analysis for each contour line strip and optionally ensure that they are non-overlapping from the current graphics view.

In order to capture contour segment information the IsoLabel object must be installed in a Contour object using vis_ContourSetObject. The current cached contour segments of the IsoLabel object should be erased using vis_IsoLabelReset. All contour segments must then be generated by the Contour object in the usual way. The IsoLabel object will cache contour segment information during this process. The labels are not generated until vis_IsoLabelDraw is called. If the label positioning is graphics view dependent then the graphics output from IsoLabel should not, in general, be retained but instead drawn in immediate mode. The VisContext module is used to pass the current graphics modelview, projection and viewport to IsoLabel.

Table of Contents

7.11 Attribute Objects

A IsoLabel object uses DrawFun, Levels, ColorMap, and VisContext objects to define attributes required to generate labels. The label color may be mapped to scalar field magnitude, or it may have a constant color. A IsoLabel object uses the following VisContext components.

Color: Label color if color not mapped to field value.
DeviceOffset: Offset of bottom middle label position display from anchor
DeviceSize: Approximate distance between labels in device coordinates
DistTol: Tolerance in world coordinates used to merge isolines
Flags: Only one flag is currently supported: VIS_BACKPLANEFLIP used to orient labels from left to right.
Format: Format to be used in label
MapColor: Flag to map label color to field value. x=VIS_MAPCOLOR_NONE Uses Color =VIS_MAPCOLOR_CONSTANT Uses constant color between levels =VIS_MAPCOLOR_SMOOTH Interpolates color between levels
Position: Positions the label relative to the location it is drawn.
PointSize: If Spot is flagged, indicates the point size to be drawn
ProjMatrix: Projection matrix, used with device sizing
Size: Approximate distance between labels in world coordinates
SizeType: Specify either world coordinate sizing or device sizing
Spot: Flags whether to draw a point at the label's anchor location
TextBox: Width and height of a single raster text character in pixels
Viewport: Viewport limits, used with device sizing
XfmMatrix: Modelview matrix, used with device sizing

Table of Contents

7.12 Function Descriptions

The currently available IsoLabel functions are described in detail in this section.

Table of Contents , IsoLabel

NAME

*vis_IsoLabelBegin - create an instance of a IsoLabel object

C SPECIFICATION

vis_IsoLabel *vis_IsoLabelBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created IsoLabel object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a IsoLabel object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. The cell topology is set to a 4 noded quadrilateral element.

Destroy an instance of a IsoLabel object using

     void vis_IsoLabelEnd (vis_IsoLabel *isolabel)

Return the current value of a IsoLabel object error flag using

     Vint vis_IsoLabelError (vis_IsoLabel *isolabel)

Table of Contents , IsoLabel

NAME

vis_IsoLabelDraw - draw the labels

C SPECIFICATION

void vis_IsoLabelLabels (vis_IsoLabel *isolabel)

INPUT ARGUMENTS

isolabel     Pointer to IsoLabel object.

OUTPUT ARGUMENTS

NONE

DESCRIPTION

Draws the labels to the VGL_DRAWFUN object or, if ISOLABEL_DATA is enabled, sends the label information to a call to vgl_DrawFunPolyPointData for the user to draw the label with a custom function.

Table of Contents , IsoLabel

NAME

vis_IsoLabelReset - clear the contents

C SPECIFICATION

void vis_IsoLabelReset (vis_IsoLabel *isolabel)

INPUT ARGUMENTS

isolabel     Pointer to IsoLabel object.

OUTPUT ARGUMENTS

NONE

DESCRIPTION

Clear the information accumulated from the Contour object.

Table of Contents , IsoLabel

NAME

vis_IsoLabelSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_IsoLabelSetObject (vis_IsoLabel *isolabel,
                           Vint objecttype,
                           Vobject *object)

INPUT ARGUMENTS

isolabel     Pointer to IsoLabel object.
objecttype   The name of the object type to be set.
             =VIS_COLORMAP           ColorMap object
             =VGL_DRAWFUN            DrawFun object
             =VIS_LEVELS             Levels object
             =VIS_VISCONTEXT         VisContext object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. A ColorMap object is only required if the VisContext attribute MapColor is set to either VIS_MAPCOLOR_CONSTANT or VIS_MAPCOLOR_SMOOTH. The Levels object is used for color map interpolation, line frequency of labels being drawn, or for the labels being displayed - the latter if the integer parameter ISOLABEL_LABELUSELEVELS is set to SYS_ON.

Table of Contents , IsoLabel

NAME

vis_IsoLabelSetParam - set parameters

C SPECIFICATION

void vis_IsoLabelSetParamf (vis_IsoLabel *trace,
                            Vint ptype,
                            Vfloat fparam)
void vis_IsoLabelSetParami (vis_IsoLabel *trace,
                            Vint ptype,
                            Vint iparam)

INPUT ARGUMENTS

isolabel     Pointer to IsoLabel object.
ptype        Parameter type to set.
             =ISOLABEL_TEXTPLANE         Toggle orientable raster font
             =ISOLABEL_DATA              Toggle vgl_DrawFunPolyPointData
             =ISOLABEL_LABELUSELEVELS    Toggle Levels labels
             =ISOLABEL_LINEFREQUENCY     Frequency of labelled lines
             =ISOLABEL_OVERLAP           Toggle non-overlapping labels
             =ISOLABEL_CURVFRAC          Curvature tolerance
fparam       Specifies the float value that ptype will be set to.
iparam       Specifies the integer value that ptype will be set to.

OUTPUT ARGUMENTS

NONE

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify parameters for controlling the positioning of labels.

The parameter ISOLABEL_TEXTPLANE toggles the generation of a vgl_DrawFunTextPlane primitive. The text plane will be oriented tangent to each segment. This primitive can be used to orient subsequent text drawing. By default ISOLABEL_TEXTPLANE is set to SYS_OFF.

The parameter ISOLABEL_DATA to toggle between drawing the labels or calling vgl_DrawFunPolyPointData for each label to be drawn. If disabled vgl_DrawFunTextDC is called for each label, if enabled vgl_DrawFunPolyPointData is called for each label. This function allows users to draw their own custom labels. If vgl_DrawFunPolyPointData is called, then nrws is set to 1: and the data is the value to be displayed. By default ISOLABEL_DATA is set to SYS_OFF.

The parameter ISOLABEL_LABELUSELEVELS is used to specify that the labels are to be drawn using the text labels contained in the Levels attribute. In this case, if a text label has been defined in the Levels attribute object at a particular level it will replace the normal value label drawn for that level. By default ISOLABEL_LABELUSELEVELS is set to SYS_OFF.

The parameter ISOLABEL_LINEFREQUENCY is used to specify the frequency, in value space, at which labels are drawn on lines. Set to zero to draw labels on every line. If set to a non-zero value, then the lowest-valued label drawn refers to this entry in the Levels object, followed by 2*n, 3*n, etc. Defaults to 0.

The parameter ISOLABEL_OVERLAP is used to toggle the display of overlapping labels. If disabled and if two labels are determined to be overlapping, then the value further from the lowest and highest isovalues defined in Levels is removed. These labels are considered more important. By default ISOLABEL_OVERLAP is set to SYS_OFF.

Segments obtained from the Contour module are internally merged into strips. Spacing between labels is determined on each strip based on either the VisContext parameters Size or DeviceSize.

The parameter ISOLABEL_CURVFRAC is used to specify a fraction of a reference curvature which limits the placement of labels. The reason for this being that strips of rapidly varying orientation can lead to bad positioning for labels particularly if ISOLABEL_TEXTPLANE is enabled. This effect can be reduced by specifying a fraction of maximum curvature allowed on a segment to be used to place a label. The reference curvature is defined as the reciprocal of the world coordinate extent of all contour segments. By default ISOLABEL_CURVFRAC is set to .05 or 5 percent.