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.