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.

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.

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.

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.

../../_images/vistools-iso1.gif

Figure 7-1, Segment Fringes

7.3. Function Descriptions

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

vis_Segment *vis_SegmentBegin(void)

create an instance of a Segment object

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)

Returns:

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

void vis_SegmentEnd(vis_Segment *p)

destroy an instance of a Segment object

See vis_SegmentBegin()

Vint vis_SegmentError(vis_Segment *p)

return the current value of a Segment object error flag

See vis_SegmentBegin()

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

set pointers to attribute objects

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().

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Segment object.

  • objecttype – The name of the object type to be set. 

    x=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.

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

set cell topology

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

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.

Parameters:

  • p – Pointer to Segment object.

  • shape – Cell shape parameter 

    x=VIS_SHAPELINE          Line

  • maxi – Topology parameter

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

get isovalue intersection information

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.

Parameters:

  • p – Pointer to Segment object.

  • s – Array of scalar field values.

  • flag – [out] Edge flag intersected by isovalues

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

draw isovalues along a polyline

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

Errors

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

Parameters:

  • p – Pointer to Segment object.

  • s – Array of scalar field values.

  • x – Array of locations.

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

draw isovalues on PolyLineData primitive

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.

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.

Parameters:

  • p – 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.

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

compute gradients of a scalar field

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.

Parameters:

  • p – Pointer to Segment object.

  • s – Array of scalar field values.

  • x – Array of locations.

  • nflag – Normalize flag

  • v – [out] Array of gradients

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

traverse and draw a group of element edges.

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.

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.

Parameters:

  • p – Pointer to Segment object.

  • state – Pointer to State object of node or element node scalars

  • group – Pointer to Group object of element edges.

void vis_SegmentSetContinuous(vis_Segment *p, Vint flag)

set continuous line mode

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.

Parameters:

  • p – Pointer to Segment object.

  • flag – Flag for beginning of new continuous line 

    x=VIS_ON           Starts continuous line mode
 =VIS_OFF          Terminates continuous line mode

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.

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.

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.

../../_images/vistools-iso2.gif

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.

../../_images/vistools-iso3.gif

Figure 7-3, Contours on all Faces

7.6. Function Descriptions

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

vis_Contour *vis_ContourBegin(void)

create an instance of a Contour object

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)

Returns:

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

void vis_ContourEnd(vis_Contour *p)

destroy an instance of a Contour object

See vis_ContourBegin()

Vint vis_ContourError(vis_Contour *p)

return the current value of a Contour object error flag

See vis_ContourBegin()

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

set pointers to attribute objects

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_ContourTrav().

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Contour object.

  • objecttype – The name of the object type to be set. 

    x=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.

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

set cell topology

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 Computational Cells for a description of element topology conventions.

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.

Parameters:

  • p – Pointer to Contour object.

  • shape – Shape parameter 

    x=VIS_SHAPETRI           Triangle
 =VIS_SHAPEQUAD          Quadrilateral
 =VIS_SHAPEPOLYGON       Polygon

  • maxi – Topology parameter

  • maxj – Topology parameter

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

get isovalue intersection information

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.

Parameters:

  • p – Pointer to Contour object.

  • s – Array of scalar field values.

  • flags – [out] Bit flags of edges intersected by isovalues

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

draw isovalues on a curvilinear surface

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.

Errors

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

Parameters:

  • p – Pointer to Contour object.

  • s – Array of scalar field values.

  • x – Array of locations.

  • vflag – User supplied face normal flag 

    x=VIS_NODATA             No normals provided
 =VIS_VERTEXDATA         Vertex normals are provided

  • v – Array of user supplied normals

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

draw isovalues on PolygonData primitive

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.

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.

Parameters:

  • p – 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.

  • vtflag – 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.

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

compute normals to curvilinear face

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

Parameters:

  • p – Pointer to Contour object.

  • x – Array of locations.

  • v – [out] Array of normal vectors at each point.

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

compute gradients of a scalar field

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 face at the point locations, x.

Parameters:

  • p – Pointer to Contour object.

  • s – Array of scalar field values.

  • x – Array of locations.

  • nflag – Normalize flag

  • v – [out] Array of gradients

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

traverse and draw a group of element faces.

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.

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 faces for an element.

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.

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.

Parameters:

  • p – 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.

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.

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.

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.

../../_images/vistools-iso4.gif

Figure 7-4, Isosurfaces

7.9. Function Descriptions

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

vis_Threshold *vis_ThresholdBegin(void)

create an instance of a Threshold object

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)

Returns:

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

void vis_ThresholdEnd(vis_Threshold *p)

destroy an instance of a Threshold object

See vis_ThresholdBegin()

Vint vis_ThresholdError(vis_Threshold *p)

return the current value of a Threshold object error flag

See vis_ThresholdBegin()

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

set parameters for visualization

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.

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

  • p – Pointer to Threshold object. 

    x=THRESHOLD_USERELEMNODE  Enable using polyhedral connectivity

  • ptype – Parameter type to set.

  • iparam – Specifies the integer value that ptype will be set to.

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

set pointers to attribute objects

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_ThresholdTrav().

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Threshold object

  • objecttype – The name of the object type to be set 

    x=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.

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

set cell topology

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 Computational Cells for a description of element topology conventions.

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.

Parameters:

  • p – Pointer to Threshold object.

  • shape – Cell shape parameter 

    x=VIS_SHAPETET           Tetrahedron
 =VIS_SHAPEPYR           Pyramid
 =VIS_SHAPEWED           Wedge
 =VIS_SHAPEHEX           Hexahedron
 =VIS_SHAPEPOLYHED       Polyhedron

  • maxi – Topology parameter

  • maxj – Topology parameter

  • maxk – Topology parameter

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

set input polyhedral cell connectivity

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().

Parameters:

  • p – Pointer to Threshold object.

  • ix – Element connectivity

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

get isovalue intersection information

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.

Parameters:

  • p – Pointer to Threshold object.

  • s – Array of scalar field values.

  • flags – [out] Bit flags of faces intersected by isovalues

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

draw isovalues within a curvilinear volume

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.

Errors

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

Parameters:

  • p – Pointer to Threshold object.

  • s – Array of scalar field values.

  • x – Array of locations.

  • vflag – User supplied normalized field gradient flag 

    x=VIS_NODATA             No gradients provided
 =VIS_VERTEXDATA         Vertex gradients are provided

  • v – Array of user supplied normalized gradients

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

compute gradients of a scalar field

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.

Parameters:

  • p – Pointer to Threshold object.

  • s – Array of scalar field values.

  • x – Array of locations.

  • nflag – Normalize flag

  • v – [out] Array of gradients

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

traverse and draw a group of cells

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.

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 element.

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.

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.

Parameters:

  • p – 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.

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.

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.

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

7.12. Function Descriptions

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

vis_IsoLabel *vis_IsoLabelBegin(void)

create an instance of an IsoLabel object

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)

Returns:

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

void vis_IsoLabelEnd(vis_IsoLabel *p)

destroy an instance of an IsoLabel object

See vis_IsoLabelBegin()

Vint vis_IsoLabelError(vis_IsoLabel *p)

return the current value of an IsoLabel object error flag

See vis_IsoLabelBegin()

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

set pointers to attribute objects

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.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to IsoLabel object.

  • objecttype – The name of the object type to be set. 

    x=VIS_COLORMAP           ColorMap object
 =VGL_DRAWFUN            DrawFun object
 =VIS_LEVELS             Levels object
 =VIS_VISCONTEXT         VisContext object

  • object – Pointer to the object to be set.

void vis_IsoLabelDraw(vis_IsoLabel *p)

draw the labels

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.

Parameters:

p – Pointer to IsoLabel object.

void vis_IsoLabelReset(vis_IsoLabel *p)

clear the contents

Clear the information accumulated from the Contour object.

Parameters:

p – Pointer to IsoLabel object.

void vis_IsoLabelSetParami(vis_IsoLabel *p, Vint type, Vint value)

set parameters

See vis_IsoLabelSetParamf()

void vis_IsoLabelSetParamf(vis_IsoLabel *p, Vint ptype, Vfloat fparam)

set parameters

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 labe vgl_DrawFunPolyPointData() for each label to be drawn. If disabled vgl_DrawFunTextDC() is called for each label, if ena vgl_DrawFunPolyPointData() is called for each label. This function allows users to draw their own custom labels. If vgl_DrawFunPolyPointD() called, then nrws is set to 1: and the data is the value to be 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 a object at a particular level it will replace the normal value la 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 e 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, 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, further from the lowest and highest isovalues defined in Levels These labels are considered more important. By default ISOLABEL_OVERLAP is set to SYS_OFF.

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

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

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

  • p – Pointer to IsoLabel object.

  • ptype – Parameter type to set. 

    x=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 value that ptype will be set to.