Table of Contents

5. Discrete Markers and Values - Mark,Value

VisTools provides for the visualization of scalar, vector, tensor and general tensor fields at discrete points in space. This is done by either drawing a marker or icon representing the magnitude and direction (if applicable) of the field or by drawing the actual numerical values of the field at discrete locations in space. These two different representations are generated using Mark and Value objects respectively. The visualization entities produced by Mark and Value are subject to isosurface clipping.

Table of Contents

5.1 Markers - Mark

Draw markers or icons representing the magnitude and/or direction of scalar, vector or tensor fields at discrete points in space. Markers may be sized and colored depending upon the magnitude of the field at each point. The appearance and type of markers may be altered in a variety of ways depending upon requirements for visual impact or computational efficiency. Vector fields may be represented as either vector components or vector resultants. Tensor fields may be represented as individual direct and shear components, principal values or maximum shear values. See section VisTools, Mathematical Data Types for a description of ordering conventions for the components of vectors, tensors and general tensors. VisTools will automatically compute the principal vectors of tensor fields for tensor visualization. The methods associated with a Mark object are the following.

If isosurface clipping is active, markers are clipped only with respect to the point location of the marker. This means that a marker is either drawn completely or not at all. A marker is never partially clipped to an isosurface.

Table of Contents

5.2 Attribute Objects

A Mark object uses DrawFun, Levels, ColorMap, IsoClip and VisContext objects to define attributes required to generate a marker visualization entity. The DrawFun object is mandatory for all drawing methods. A Levels object is required if marker size or color are to be mapped to field value. The ColorMap object is optional. An IsoClip object is required if isosurface clipping is to be performed. If model traversal is performed using vis_MarkTrav or vis_MarkPntTrav, then a GridFun object is required. An IdTran object is optional for specifying entity color using vis_MarkPntTrav. Up to three VisContext objects are required to set the visualization context for drawing each of the basic field types - scalar, vector and tensor. Since a tensor marker is drawn using vector and tensor icons, both a vector and tensor VisContext must be set. It is possible, depending upon the variations required by the user, that a single VisContext may suffice for all three field types.

If size is mapped to field value, then the field value minimum and maximum set in the Levels object using vis_LevelsSetMinMax are used to compute the maximum absolute value of the field value which is mapped to maximum marker Size as specified by the VisContext attribute object. By default, the size is linearly mapped to field value.

   size = Size * field_value/maxabs_value
The function vis_MarkSetParamf may be used to set a decay factor to control the size mapping as shown below.
   size = Size * (field_value/absmax_value) ** decay
The markers may be sized to a world coordinate or device coordinate size. The type of sizing is specified by the SizeType visualization context component. If SizeType is set to VIS_SIZEDEVICE then the XfmMatrix, ProjMatrix and Viewport visualization context components should be set to reflect the current state of the underlying graphics device.

Scalar markers consist of a single 2D or 3D icon such as a triangle, square, tetrahedron or sphere. The size and/or color of a scalar marker may be mapped to the magnitude of a scalar quantity at a point. The size of a scalar marker is loosely defined as the "diameter" of the marker. Scalar markers are drawn centered on the point at which they are located.

A scalar marker is not drawn at a point if the marker size is mapped to field value and the scalar field value is zero. Figure 5-1 illustrates a flat shaded spherical scalar marker drawn with medium refinement. Scalar markers use the following scalar VisContext components. Point markers drawn with vis_MarkPnt are designed to mark points without reference to a field value.

Color
Marker color if color not mapped to field value.
DeviceSize
Diameter of marker in device coordinates.
DistTol
Distance tolerance used in intersection testing
Fill
Flag to fill scalar markers
MapColor
Flag to map marker color to field value, Color is ignored. Not used by point markers.
MapSize
Flag to map marker size to the magnitude of the scalar field value. Size is the marker size at the maximum magnitude of the scalar field value. Not used by point markers.
MarkerType
Marker type used for scalar and point marker.
Project
Viewplane projection flag for MarkerType VIS_METER
ProjMatrix
Projection matrix, used with device sizing
Refinement
Level of refinement
Size
Diameter of marker in world coordinates.
SizeType
Specify either world coordinate or device coordinate sizing
Viewport
Viewport limits, used with device sizing
XfmMatrix
Modelview matrix, used with device sizing
Vector markers are drawn as 2D or 3D arrows which represent the magnitude and direction of a vector quantity at a point. A vector quantity may be represented by a single resultant vector or by 3 individual, orthogonal vectors representing the magnitude and direction of each of the vector components. The size and color of the vector markers may be mapped to the magnitude of the vector or its individual components. By default the vector arrow is anchored by the head on the point at which it is located. An option is provided to anchor the vector by the tail. Other attributes of the vector may be altered as well such as drawing a double headed vector as opposed to a single headed vector, etc.

If marker size is mapped to field value, a component vector marker is not drawn at a point if the component field value is zero, a resultant vector marker is not drawn if the vector field magnitude is zero.

If vector components are drawn using a VectorType of VIS_VECTORLINE, by default the heads of each component vector in the x,y and z directions lie in the x-y, y-z and z-x planes respectively of the coordinate system in which they are defined. If the viewplane Project visualization component is set to VIS_ON, then the heads of each vector are drawn in the viewplane defined by the current modelview matrix. The viewplane is defined by the current modelview matrix visualization component, XfmMatrix.

Figure 5-1 illustrates a flat shaded cylindrical vector marker drawn with medium refinement. Vector markers use the following vector VisContext components.

Angle
The half angle in degrees spanned by a vector head.
Color
Vector resultant color if color not mapped to field value.
Component
Draw 3 vector component markers rather than a single vector resultant marker.
DeviceSize
Length of vector in device coordinates.
Fill
Flag to fill the heads of 2D vector markers
Flags
OR the following flags: VIS_VECTORDOUBLEHEAD draws a double headed vector; VIS_VECTORDOUBLEHEADPEN draws a double headed vector with the second vector penetrating the first vector; VIS_VECTORDOUBLEHEADADD adds a double headed vector to the end of the head of a single vector head. The net result is a triple headed vector. VIS_VECTORTAILREGISTER anchors the vector by the tail; VIS_VECTORTAIL draws the tail of the vector marker. VIS_VECTORNOHEAD inhibits the drawing of the head of the vector. VIS_VECTORPUSHHEAD positions the vector head behind the tail so that it appears to push the vector tail. VIS_VECTORROUND draws a round vector which are useful for representing rotational vectors such as moments.
MapColor
Flag to map vector color to field value, Color, XColor, YColor and ZColor are ignored.
MapSize
Flag to map marker size to the magnitude of the vector field value. Size is the vector length at the maximum magnitude of the vector field value.
Project
Viewplane projection flag for VectorType VIS_VECTORLINE
ProjMatrix
Projection matrix, used with device sizing
Ratio
The length of the vector head relative to the total length of the vector.
Refinement
Level of refinement
Shade
Attribute to determine the type of polygon normals generated.
Size
Length of vector.
SizeType
Specify either world coordinate sizing or device sizing
VectorType
Vector type used for vector marker.
Viewport
Viewport limits, used with device sizing
XfmMatrix
Modelview matrix, used with device sizing and viewplane projection.
XColor
Vector X component color if color not mapped to field value.
YColor
Vector Y component color if color not mapped to field value.
ZColor
Vector Z component color if color not mapped to field value.

Figure 5-1, Scalar and Vector Markers
Tensor markers are drawn as a composite of a cube or ellipsoid oriented to either the defining coordinate system, the principal axes, or directions of maximum shear of the tensor and a set of vector arrows which represent the individual direct (diagonal) and shear (off diagonal) components of the tensor. As a result of this composite representation, tensor markers use components of both the vector and tensor VisContext. Tensor markers use the following vector VisContext components.

Angle
The half angle in degrees spanned by a vector head.
DeviceSize
Length of vector in device coordinates.
Fill
Flag to fill the heads of 2D vector markers
MapColor
Flag to map vector color to field value, Color, XColor, YColor and ZColor are ignored.
MapSize
Flag to map vector marker size to the magnitude of the tensor principal values or component values. Size is the vector length at the maximum magnitude of the tensor field value.
ProjMatrix
Projection matrix, used with device sizing
Ratio
The length of the vector head relative to the total length of the vector.
Refinement
Level of refinement
Shade
Attribute to determine the type of polygon normals generated.
Size
Length of vector.
SizeType
Specify either world coordinate sizing or device sizing
VectorType
Vector type used for vector marker.
Viewport
Viewport limits, used with device sizing
XfmMatrix
Modelview matrix, used with device sizing.
XColor
Minimum principal or XX or XY component color if color not mapped to field value.
YColor
Middle principal or YY or YZ component color if color not mapped to field value.
ZColor
Maximum principal or ZZ or ZX component color if color not mapped to field value.
The cube or ellipsoid which is drawn as part of a tensor marker is termed the tensor box. The form of the tensor box is determined by the TensorType member of the tensor VisContext attribute object. A special case of the tensor box is the VIS_TENSORCROWSFEET representation in which the tensor box is not drawn but the shear arrows, if drawn, are directed on the bisector of the positive quadrant of the shear plane. This representation is designed to create the fewest graphics primitives. Options are provided to align the principal axes of the tensor box with either the axes of the defining coordinate system, the principal axes or the maximum shear directions of the tensor. The maximum shear directions are oriented such that the y direction is the mid principal value and the z direction is in the direction of maximum shear. If the tensor box size is mapped to tensor values the lengths of the principal axes of the tensor box are proportional to the magnitude of the appropriate tensor values. If the tensor components are drawn then the tensor box is aligned to the defining coordinate system and the tensor box lengths are proportional to the magnitude of the direct components of the tensor. If the tensor principal values are drawn then the tensor box is aligned to the principal axes of the tensor and the tensor box lengths are proportional to the magnitude of the principal values of the tensor. If the tensor maximum shear directions are drawn then the tensor box is aligned to the directions of maximum shear and the tensor box lengths are proportional to the magnitude of the direct components of the tensor.

If marker size is mapped to field value, a component tensor box is not drawn at a point if all the component field values are zero, a principal tensor box is not drawn if all the principal values are zero, component direct and shear arrows are not drawn if the component value is zero, and principal direct arrows are not drawn if the principal value is zero.

Figure 5-2 illustrates two types of tensor markers. The left marker uses an ellipsoid tensor box and is aligned to the principal directions of the tensor. The right marker is oriented to the axes of the defining coordinate system of the tensor and features vectors representing both the direct and shear components of the tensor. Tensor markers use the following tensor VisContext components.

DeviceSize
Diameter of tensor box in device coordinates.
Component
Draw tensor in defining coordinate system, principal directions or maximum shear directions.
Fill
Flag to fill the cube tensor box
Flags
OR the following flags: VIS_TENSORBOX draws the tensor box; VIS_TENSORDIRECT draws direct vector markers; VIS_TENSORSHEAR draws shear vector markers.
MapColor
Flag to map tensor box color to field value, Color, XColor, YColor and ZColor are ignored.
MapSize
Flag to map tensor box lengths to the magnitude of the tensor values. Size is the box length at the maximum magnitude of the tensor field value.
ProjMatrix
Projection matrix, used with device sizing
Shade
Attribute to determine the type of polygon normals generated.
Size
Diameter of tensor box.
SizeType
Specify either world coordinate sizing or device sizing
TensorType
Representation used for tensor box display
Viewport
Viewport limits, used with device sizing
XfmMatrix
Modelview matrix, used with device sizing.
XColor
Minimum principal or XX component color if color not mapped to field value.
YColor
Middle principal or YY component color if color not mapped to field value.
ZColor
Maximum principal or ZZ component color if color not mapped to field value.

Figure 5-2, Tensor Markers in Principal and Component Form
Table of Contents

5.3 Function Descriptions

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


Table of Contents , Mark

NAME

*vis_MarkBegin - create an instance of a Mark object

C SPECIFICATION

vis_Mark *vis_MarkBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a Mark 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 component drawing masks are all set to VIS_ON. The user defined direction cosine matrix is set to the identity matrix.

Destroy an instance of a Mark object using

     void vis_MarkEnd (vis_Mark *mark)

Return the current value of a Mark object error flag using

     Vint vis_MarkError (vis_Mark *mark)


Table of Contents , Mark

NAME

vis_MarkPnt - draw point markers

C SPECIFICATION

void vis_MarkPnt (vis_Mark *mark,
                  Vint npts,
                  Vfloat x[][3])

INPUT ARGUMENTS

mark         Pointer to Mark object.
npts         The number of points at which to draw point markers
x            Array of npts locations.

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw point markers at npts points at locations x. This method is useful for marking discrete nodes, finite element centroids, etc. The point markers are drawn using the scalar VisContext attribute object.


Table of Contents , Mark

NAME

vis_MarkPntIntersectLine,vis_MarkPntIntersectPoint - compute point of intersection

C SPECIFICATION

void vis_MarkPntIntersectLine (vis_Mark *mark,
                               Vint npts,
                               Vfloat x[][3],
                               Vfloat xl[2][3],
                               Vint *ipt,
                               Vfloat xr[3],
                               Vfloat xd[3],
                               Vint *status)

void vis_MarkPntIntersectPoint (vis_Mark *mark,
                                Vint npts,
                                Vfloat x[][3],
                                Vfloat xp[3],
                                Vint *ipt,
                                Vfloat xr[3],
                                Vfloat xd[3],
                                Vint *status)

INPUT ARGUMENTS

mark         Pointer to Mark object.
npts         The number of points at which to test point markers
x            Array of npts locations.
xl           End points of intersecting line
xp           Intersecting point

OUTPUT ARGUMENTS

ipt          Index of point closest to intersecting point or line.
             1 <= ipt <= npts
xr           Coordinates of closest point marker.
xd           Vector from xr to point or closest point on line
status       Intersection status

DESCRIPTION

Compute the closest of point markers defined by node point locations, x, to a line defined by end points, xl, or a point defined by xp. The index, ipt, and the coordinates, xr of the closest point on the tesselated marker to the input line or point are returned. The distance vector, xd, from xr to the input point or the closest point on the input line is returned.

The case that the magnitude of xd is zero implies that the intersecting point or line actually intersected the tesselated marker. This will generally only occur in the case of an intersecting line if the marker has been drawn in a 3D filled marker type. If more than one true point of intersection is determined, the point closest to the first endpoint of the intersecting line is returned.

The status variable is returned as unity if the length of vector xd is less than the DistTol element of the visualization context and zero otherwise.

Note that the basic intersection testing is performed on the graphics primitives used to represent the marker. This means, for example, that if a spherical marker type has been specified in the VisContext attribute object, then intersection testing will be performed using the graphics polygons which result from tesselating the marker into a sphere. In this way the intersection testing is performed upon the actual graphics primitives used to visually represent the marker on the graphics display.


Table of Contents , Mark

NAME

vis_MarkPntTrav - traverse and draw a group of point markers

C SPECIFICATION

void vis_MarkPntTrav (vis_Mark *mark,
                      vis_Group *group)

INPUT ARGUMENTS

mark         Pointer to Mark object.
group        Pointer to Group object of nodes or elements.

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 Group object is NULL.

DESCRIPTION

Traverse and draw point markers on a group of nodes or elements specified in group. If the input group is a node group then nodes are marked, if it is an element group then element centroids are marked. The point markers are drawn using the scalar VisContext attribute object. The underlying model information is accessed using the GridFun attribute object. If an IdTran color map index attribute object is set, then each marker is drawn in the color specified by the color map index.


Table of Contents , Mark

NAME

vis_MarkPolyPointData - draw markers on PolyPointData primitive

C SPECIFICATION

void vis_MarkPolyPointData (vis_Mark *mark,
                            Vint npts,
                            Vfloat x[][3],
                            Vint nrws, Vfloat d[])

INPUT ARGUMENTS

mark         Pointer to Mark object.
npts         Number of vertex points
x            Vertex world coordinates
nrws         Number of values in d vector
d            Array of 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, 3 or 6.

DESCRIPTION

Draw markers of scalar, vector or tensor field d over a PolyPointData graphics primitive. This function has the same prototype as the PolyLineData drawing function.


Table of Contents , Mark

NAME

vis_MarkSetMask - set component drawing masks

C SPECIFICATION

void vis_MarkSetMask (vis_Mark *mark,
                      Vint mask[])

INPUT ARGUMENTS

mark         Pointer to Mark object.
mask         Vector of component drawing masks.
             =VIS_OFF      Turn component drawing mask off
             =VIS_ON       Turn component drawing mask on

OUTPUT ARGUMENTS

None

DESCRIPTION

Set component drawing masks. In general the drawing of each component of a scalar, vector or tensor marker may switched on or off by setting the appropriate drawing mask.

For scalar markers, the first mask, mask[0], toggles the drawing of a scalar marker.

For vector markers, the first three masks, mask[0], mask[1] and mask[2], toggle the drawing of the x,y and z components respectively of a vector marker. The first mask, mask[0], toggles the drawing of a resultant vector marker.

For tensor markers, the first six masks, mask[0], through mask[5], toggle the drawing of the xx,yy,zz,xy,yz and zx components respectively of a tensor marker. The first three masks, mask[0], mask[1] and mask[2], toggle the drawing of the min,mid and max principal values respectively of a tensor marker. For tensor markers drawn in maximum shear directions, the first six masks mask[0], through mask[5], toggle the drawing of the xx,yy,zz,xy,yz and zx components respectively of a tensor marker. The maximum shear is the zx component. The yy component is the mid principal.

Get drawing mask as an output argument using

     void vis_MarkGetMask (vis_Mark *mark,
                           Vint mask[])


Table of Contents , Mark

NAME

vis_MarkSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_MarkSetObject (vis_Mark *mark,
                        Vint objecttype,
                        Vobject *object)

INPUT ARGUMENTS

mark         Pointer to Mark object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
             =VIS_COLORMAP           ColorMap 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 for all markers
             =VIS_VISCONTEXT_SCALAR  VisContext object for scalar markers
             =VIS_VISCONTEXT_VECTOR  VisContext object for vector markers
             =VIS_VISCONTEXT_TENSOR  VisContext object for tensor markers
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

The ColorMap object is optional. Set a pointer to an attribute object. The DrawFun attribute object is mandatory for all drawing methods. The Levels object needs only to be set if size or color are to be mapped to field value. The ColorMap object is optional. A Viscontext object must be set for each type of marker visualization, ie. scalar, vector and tensor. For tensor visualization both a vector and tensor VisContext must be set.

If an IsoClip attribute object is set then isosurface clipping is activated. To deactivate isosurface clipping, set a NULL IsoClip object pointer.

The GridFun object is only used by vis_MarkTrav and vis_MarkPntTrav. The IdTran object is only used by vis_MarkPntTrav.


Table of Contents , Mark

NAME

vis_MarkSetDirCos - set user defined direction cosine matrix

C SPECIFICATION

void vis_MarkSetDirCos (vis_Mark *mark,
                        Vfloat tm[3][3])

INPUT ARGUMENTS

mark         Pointer to Mark object.
tm           Direction cosine matrices indicating the
             coordinate system in which a vector or tensor is
             expressed.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set current user defined coordinate system. Any subsequent vector or tensor markers drawn with vis_MarkVector or vis_MarkTensor or computed with vis_MarkVectorCompute or vis_MarkTensorCompute are assumed to be expressed in the user defined coordinate system. By default the user defined coordinate system is aligned to the global coordinate system, ie. tm is an identity matrix.

Given that X',Y' and Z' are three orthonormal vectors indicating the direction of the local coordinate axes in the global coordinate system (x,y,z), then the direction cosine matrix, tm for this local coordinate system is defined as:

     tm[0][0] = X'x  tm[0][1] = X'y  tm[0][2] = X'z
     tm[1][0] = Y'x  tm[1][1] = Y'y  tm[1][2] = Y'z
     tm[2][0] = Z'x  tm[2][1] = Z'y  tm[2][2] = Z'z

Get drawing tm as an output argument using

     void vis_MarkGetDirCos (vis_Mark *mark,
                             Vfloat tm[3][3])


Table of Contents , Mark

NAME

vis_MarkSetParam - set parameters for marker visualization

C SPECIFICATION

void vis_MarkSetParamf (vis_Mark *mark,
                        Vint ptype,
                        Vfloat fparam)

INPUT ARGUMENTS

mark         Pointer to Mark object.
ptype        Parameter type to set.
             =MARK_DECAY              Set sizing decay parameter
fparam       Specifies the float value that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified. objects are set.

DESCRIPTION

Specify parameters for controlling marker visualization. The parameter MARK_DECAY is used to specify a decay factor for mapping marker scalar, vector and tensor quantities to marker size. By default the decay factor is unity which results in a linear mapping of marker size to field value.


Table of Contents , Mark

NAME

vis_MarkScalar,vis_MarkVector,vis_MarkTensor - draw markers

C SPECIFICATION

void vis_MarkScalar (vis_Mark *mark,
                     Vint npts,
                     Vfloat s[], 
                     Vfloat x[][3])

void vis_MarkVector (vis_Mark *mark,
                     Vint npts,
                     Vfloat s[][3], 
                     Vfloat x[][3])

void vis_MarkTensor (vis_Mark *mark,
                     Vint npts,
                     Vfloat s[][6], 
                     Vfloat x[][3])

INPUT ARGUMENTS

mark         Pointer to Mark object.
npts         The number of points at which to draw scalar, vector or
             tensor markers.
s            Array of npts scalar, vector or tensor field values.
x            Array of npts locations.

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

Draw scalar, vector or tensor markers at npts points with scalar, vector or tensor field s at locations x. The vector and tensor fields s are assumed to be expressed in the user defined coordinate system set by vis_MarkSetDirCos. By default the user coordinate system is defined by an identity matrix.


Table of Contents , Mark

NAME

vis_MarkVectorCompute,vis_MarkTensorCompute - compute vector and tensor markers

C SPECIFICATION

void vis_MarkVectorCompute (vis_Mark *mark,
                            Vfloat s[3], 
                            Vfloat x[3],
                            Vfloat sc[], 
                            Vfloat xc[][3])

void vis_MarkTensorCompute (vis_Mark *mark,
                            Vfloat s[6], 
                            Vfloat x[3],
                            Vfloat sc[], 
                            Vfloat xc[][2][3])

INPUT ARGUMENTS

mark         Pointer to Mark object.
s            Array of vector or tensor field values at a point
x            Point location.

OUTPUT ARGUMENTS

sc           Array of computed vector or tensor field values at a point
xc           Array of annotation locations.

DESCRIPTION

Compute the components, magnitude or principal values of a vector or tensor at a point. If components are computed, they are expressed in the global coordinate system. For vector markers, three values are returned for vector components and one value for vector resultants representing the vector magnitude. For tensor markers, six values are returned for tensor components and three values for tensor principal values representing the min, mid and max values respectively.

In addition compute the annotation location of each drawn vector of the vector or tensor marker. For example if components of a vector are displayed, there are three vectors drawn to represent each component of the vector. In this case three annotation locations are computed and returned in global coordinates in array xc. An annotation location is a suitable place to draw a value or any other annotation glyph which describes a vector component. For vector markers, three locations are returned for vector components and one value for vector resultants. For tensor markers, twelve locations are returned for tensor components (two times six component vectors), and six values for tensor principal values (two times three principal vectors).


Table of Contents , Mark

NAME

vis_MarkTensorPrincipal - compute tensor principal values

C SPECIFICATION

void vis_MarkTensorPrincipal (vis_Mark *mark,
                              Vfloat s[6],
                              Vfloat pv[3],
                              Vfloat tm[3][3])
                                                                           
void vis_MarkTensorPrincipaldv (vis_Mark *mark,
                                Vdouble s[6],
                                Vdouble pv[3],
                                Vdouble tm[3][3])

INPUT ARGUMENTS

mark         Pointer to Mark object.
s            Array of tensor field values at a point

OUTPUT ARGUMENTS

pv           Array of computed principal values
tm           Direction cosine matrices of principal directions

DESCRIPTION

Compute the principal values and directions of a symmetric tensor, s. The vector pv contains three values for tensor principal values representing the min, mid and max values respectively. The corresponding principal directions are returned in tm.


Table of Contents , Mark

NAME

vis_MarkTensorMaxShear - compute tensor max shear values

C SPECIFICATION

void vis_MarkTensorMaxShear (vis_Mark *mark,
                              Vfloat s[6],
                              Vfloat ms[6],
                              Vfloat tm[3][3])
                                                                           
void vis_MarkTensorMaxSheardv (vis_Mark *mark,
                                Vdouble s[6],
                                Vdouble ms[6],
                                Vdouble tm[3][3])

INPUT ARGUMENTS

mark         Pointer to Mark object.
s            Array of tensor field values at a point

OUTPUT ARGUMENTS

pv           Array of computed principal values
tm           Direction cosine matrices of principal directions

DESCRIPTION

Compute the component tensor values and directions of a symmetric tensor, s in the direction of maximum shear. The 6 length vector ms contains tensor component values in the directions of maximum shear. The maximum shear will be in ms[5] and ms[3] and ms[4] will be zero. The corresponding directions are returned in tm.


Table of Contents , Mark

NAME

vis_MarkTrav - traverse and draw a group of markers

C SPECIFICATION

void vis_MarkTrav (vis_Mark *mark,
                   vis_State *state,
                   vis_Group *group)

INPUT ARGUMENTS

mark         Pointer to Mark object.
state        Pointer to State object of node or element data
group        Pointer to Group object of nodes or elements.
             If NULL, then all nodes or elements are assumed.

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 markers of a data field contained in state on a group of nodes or elements specified in group. The type of entity, node or element, is determined by the parent type of the input state. If the parent type is node then nodes are marked, if it is element then element centroids are marked. The data type of the input state determines the type of marker to be drawn, scalar, vector or tensor.

If color mapping is turned off, the markers 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 entity. 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 markers for an entity.

The underlying model information is accessed using the GridFun attribute object.


Table of Contents

5.4 Values - Value

Draw numerical values of scalar, vector or tensor fields at discrete points in space. Value icons are generated using annotation text primitives with optional brackets and background to represent to component field values visually in a bracketed matrix format. VisTools will automatically compute the principal values of tensor fields or magnitude of vector fields. The methods associated with a Value object are the following.

If isosurface clipping is active, values are clipped only with respect to the point location of the value. This means that a value is either drawn completely or not at all. A value is never partially clipped by an isosurface.

Value displays may be drawn for scalar, vector, symmetric tensor or general tensor values in three dimensions. See section VisTools, Mathematical Data Types for a description of ordering conventions for the components of vectors, tensors and general tensors. The functions for drawing these values are vis_ValueScalar, vis_ValueVector, vis_ValueTensor and vis_ValueMatrix respectively. For vector values there is an option to draw the magnitude of the vector. For all tensor type values there is an option to draw the principal values as a column vector or the tensor component values in the directions of maximum shear. The maximum shear directions are oriented such that the y direction is the mid principal value and the z direction is in the direction of maximum For symmetric tensors the principal values are always real and are ordered from minimum to maximum value. For general tensors the eigenvalues may be all real or they may consist of a single real and a complex conjugate pair. If a complex conjugate pair exists, the first value of the column vector is the real part of the complex conjugate pair, the second value is the imaginary part followed by the letter "i" and the third value is the real eigenvalue.

Table of Contents

5.5 Attribute Objects

A Value object uses DrawFun, Levels, ColorMap, TransMap, IsoClip and VisContext objects to define attributes required to generate a value visualization entity. The DrawFun object is mandatory for all drawing methods. A ColorMap and TransMap objects are optional. A Levels object is required if value color is to be mapped to field value. An IsoClip object is required if isosurface clipping is to be performed. If model traversal is performed using vis_ValueTrav or vis_ValueIntTrav, then a GridFun object is required. An IdTran object is optional for specifying entity color using vis_ValueIntTrav.

Numerical values may be expressed in an integer, fixed floating point or scientific floating point format. Value displays are designed to remain perpendicular to the viewer while the value anchor point is positioned arbitrarily in 3D global coordinate space. The value display is anchored by its bottom left hand corner. A single VisContext object is required to set the visualization context for the values themselves, the brackets and the background components of the value display. Values are drawn in a bracket matrix format. The brackets are drawn in a constant color and line width using a solid line style. The background of the value display is drawn with a constant color and transparency. Figures 5-3, 5-4 and 5-5 illustrate scalar, vector, tensor and general tensor value displays with brackets. Note that in Figure 5-5 the eigenvalues of the general tensor contain a complex conjugate pair. The component values of the general tensor have been drawn using VIS_GFORMAT. The numerical values are drawn using the following value VisContext components.

AColor
Background color
Color
Value color if color not mapped to field value.
Component
Draw vector, tensor or general tensor component values or vector resultants or tensor principal values or tensor maximum shear values.
DeviceOffset
Offset of bottom left corner of value display from anchor point in device coordinates
Flags
OR the following flags: VIS_VALUEBRACKET draws the matrix brackets; VIS_VALUEBACK draws the matrix background.
Format
Value format
LineWidth
Linewidth of bracket
MapColor
Flag to map value color to field value, Color is ignored.
MinorColor
Bracket color
TextBox
Width and height of a single raster text character.
Transparency
Background transparency factor

Figure 5-3, Scalar and Vector Values

Figure 5-4, Tensor Values

Figure 5-5, General Tensor Eigenvalues and Values
Table of Contents

5.6 Function Descriptions

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


Table of Contents , Value

NAME

*vis_ValueBegin - create an instance of a Value object

C SPECIFICATION

vis_Value *vis_ValueBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a Value 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.

Destroy an instance of a Value object using

     void vis_ValueEnd (vis_Value *value)

Return the current value of a Value object error flag using

     Vint vis_ValueError (vis_Value *value)


Table of Contents , Value

NAME

vis_ValueInt - draw integer scalar values

C SPECIFICATION

void vis_ValueInt (vis_Value *value,
                   Vint npts,
                   Vint is[],
                   Vfloat x[][3])

INPUT ARGUMENTS

value        Pointer to Value object.
npts         The number of points at which to draw scalar values.
is           Array of npts integer scalar field values.
x            Array of npts locations.

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw integer scalar values at npts points with field is at locations x. This method is useful for drawing finite element and node identifiers.


Table of Contents , Value

NAME

vis_ValueIntTrav - traverse and draw a group of integer values

C SPECIFICATION

void vis_ValueIntTrav (vis_Value *value,
                       vis_IdTran *idtran,
                       vis_Group *group)

INPUT ARGUMENTS

value        Pointer to Value object.
idtran       Pointer to IdTran object of node or element ids
group        Pointer to Group object of nodes or elements.

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 Group object is NULL.

DESCRIPTION

Traverse and draw integer scalar values specified by idtran on a group of nodes or elements specified in group. If the input group is a node group then nodes are drawn, if it is an element group then element centroids are drawn. If the input idtran is NULL then the scalar value is the entity index, if idtran is not NULL then it contains the integer value to be drawn.

The underlying model information is accessed using the GridFun attribute object. If an IdTran color map index attribute object is set, then each value is drawn in the color specified by the color map index.


Table of Contents , Value

NAME

vis_ValueSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_ValueSetObject (vis_Value *value,
                         Vint objecttype,
                         Vobject *object)

INPUT ARGUMENTS

value        Pointer to Value object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
             =VIS_COLORMAP           ColorMap 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_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

Set a pointer to attribute objects. The DrawFun and VisContext attribute objects are mandatory for all drawing methods. The ColorMap and Transmap attribute objects are optional. The Levels object is required if value color is to be mapped to quantity value.

If an IsoClip attribute object is set then isosurface clipping is activated. To deactivate isosurface clipping, set a NULL IsoClip object pointer.

The GridFun object is only used by vis_ValueTrav and vis_ValueIntTrav. The IdTran object is only used by vis_ValueIntTrav.


Table of Contents , Value

NAME

vis_ValuePolyPointData - draw values on PolyPointData primitive

C SPECIFICATION

void vis_ValuePolyPointData (vis_Value *value,
                             Vint npts,
                             Vfloat x[][3],
                             Vint nrws, Vfloat d[])

INPUT ARGUMENTS

value        Pointer to Value object.
npts         Number of vertex points
x            Vertex world coordinates
nrws         Number of values in d vector
d            Array of 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, 3 or 6.

DESCRIPTION

Draw values of scalar, vector, tensor or general tensor field d over a PolyPointData graphics primitive. This function has the same prototype as the PolyLineData drawing function.


Table of Contents , Value

NAME

vis_ValueScalar,vis_ValueVector,vis_ValueTensor,vis_ValueMatrix - draw values

C SPECIFICATION

void vis_ValueScalar (vis_Value *value,
                      Vint npts,
                      Vfloat s[],
                      Vfloat x[][3])

void vis_ValueVector (vis_Value *value, 
                      Vint npts,
                      Vfloat s[][3],
                      Vfloat x[][3])

void vis_ValueTensor (vis_Value *value,
                      Vint npts,
                      Vfloat s[][6],
                      Vfloat x[][3])

void vis_ValueMatrix (vis_Value *value,
                      Vint npts,
                      Vfloat s[][9],
                      Vfloat x[][3])

INPUT ARGUMENTS

value        Pointer to Value object.
npts         The number of points at which to draw scalar, vector,
             tensor or general tensor values.
s            Array of npts scalar, vector, tensor or general tensor
             field values.
x            Array of npts locations.

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

Draw scalar, vector, tensor or general tensor values at npts points with scalar, vector, tensor or general tensor field s at locations x.


Table of Contents , Value

NAME

vis_ValueTrav - traverse and draw a group of values

C SPECIFICATION

void vis_ValueTrav (vis_Value *value,
                    vis_State *state,
                    vis_Group *group)

INPUT ARGUMENTS

value        Pointer to Value object.
state        Pointer to State object of node or element data
group        Pointer to Group object of nodes or elements.
             If NULL, then all nodes or elements are assumed.

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 values of a data field contained in state on a group of nodes or elements specified in group. The type of entity, node or element, is determined by the parent type of the input state. If the parent type is node then nodes are drawn, if it is element then element centroids are drawn. The data type of the input state determines the type of value to be drawn, scalar, vector, tensor or general tensor.

If color mapping is turned off, the values 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 entity. 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 values for an entity.

The underlying model information is accessed using the GridFun attribute object.