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.

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.

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.
../../_images/vistools-disc1.gif

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.
../../_images/vistools-disc2.gif

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

5.3. Function Descriptions

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

vis_Mark *vis_MarkBegin(void)

create an instance of a Mark object

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)

Returns:

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

void vis_MarkEnd(vis_Mark *p)

destroy an instance of a Mark object

See vis_MarkBegin()

Vint vis_MarkError(vis_Mark *p)

return the current value of a Mark object error flag

See vis_MarkBegin()

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

set pointers to attribute objects

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

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Mark object

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

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

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

set component drawing masks

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[])

Parameters:

  • p – Pointer to Mark object.

  • mask – Vector of component drawing masks. 

    =VIS_OFF      Turn component drawing mask off
=VIS_ON       Turn component drawing mask on

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

get component drawing masks

See vis_MarkSetMask()

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

set user defined direction cosine matrix

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])

Parameters:

  • p – Pointer to Mark object.

  • tm – Direction cosine matrices indicating the coordinate system in which a vector or tensor is expressed.

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

get user defined direction cosine matrix

See vis_MarkSetDirCos()

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

set parameters for marker visualization

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.

Errors

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

Parameters:

  • p – Pointer to Mark object.

  • ptype – Parameter type to set. 

    x=MARK_DECAY              Set sizing decay parameter

  • fparam – Specifies the float value that ptype will be set to.

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

draw markers on PolyPointData primitive

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.

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.

Parameters:

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

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

draw markers

Draw scalar markers at npts points with scalar field s at locations x.

Errors

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

Parameters:

  • p – Pointer to Mark object.

  • npts – The number of points at which to draw scalar markers.

  • s – Array of npts scalar values.

  • x – Array of npts locations.

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

draw point markers

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.

Parameters:

  • p – Pointer to Mark object.

  • npts – The number of points at which to draw point markers

  • x – Array of npts locations.

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

compute point of intersection

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.

Parameters:

  • p – 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 for intersecting point)

  • ipt – [out] Index of point closest to intersecting point or line. 1 <= ipt <= npts

  • xr – [out] Coordinates of closest point marker.

  • xd – [out] Vector from xr to point or closest point on line

  • status – [out] Intersection status

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

compute point of intersection

See vis_MarkPntIntersectLine()

void vis_MarkPntTrav(vis_Mark *p, vis_Group *group)

traverse and draw a group of point markers

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.

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.

Parameters:

  • p – Pointer to Mark object.

  • group – Pointer to Group object of nodes or elements.

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

traverse and draw a group of markers

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.

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

void vis_MarkVector(vis_Mark *p, Vint npts, Vfloat v[][3], Vfloat x[][3])

draw markers

Draw vector markers at npts points with vector field v at locations x. The vector and tensor fields v 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.

Errors

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

Parameters:

  • p – Pointer to Mark object.

  • npts – The number of points at which to draw vector markers.

  • v – Array of npts vector field values.

  • x – Array of npts locations.

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

compute vector and tensor markers

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

Parameters:

  • p – Pointer to Mark object.

  • s – Array of vector or tensor field values at a point

  • x – Point location.

  • sc – [out] Array of computed vector or tensor field values at a point

  • xc – [out] Array of annotation locations.

void vis_MarkTensor(vis_Mark *p, Vint npts, Vfloat v[][6], Vfloat x[][3])

draw markers

Draw tensor markers at npts points with tensor field v at locations x. The vector and tensor fields v 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.

Errors

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

Parameters:

  • p – Pointer to Mark object.

  • npts – The number of points at which to draw tensor markers.

  • v – Array of npts tensor field values.

  • x – Array of npts locations.

void vis_MarkTensorCompute(vis_Mark *p, Vfloat v[6], Vfloat x[3], Vfloat vl[], Vfloat xl[][2][3])

compute tensor markers

See vis_MarkVectorCompute()

void vis_MarkTensorPrincipal(vis_Mark *p, Vfloat s[6], Vfloat pv[3], Vfloat tm[3][3])

compute tensor principal values

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.

Parameters:

  • p – Pointer to Mark object.

  • s – Array of tensor field values at a point

  • pv – [out] Array of computed principal values

  • tm – [out] Direction cosine matrices of principal directions

void vis_MarkTensorPrincipaldv(vis_Mark *p, Vdouble v[6], Vdouble pv[3], Vdouble tm[3][3])

compute tensor principal values

See vis_MarkTensorPrincipal()

void vis_MarkTensorMaxShear(vis_Mark *p, Vfloat s[6], Vfloat pv[6], Vfloat tm[3][3])

compute tensor max shear values

Compute the component tensor values and directions of a symmetric tensor, s in the direction of maximum shear. The 6 length vector pv 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.

Parameters:

  • p – Pointer to Mark object.

  • s – Array of tensor field values at a point

  • pv – [out] Array of computed principal values

  • tm – [out] Direction cosine matrices of principal directions

void vis_MarkTensorMaxSheardv(vis_Mark *p, Vdouble v[6], Vdouble msv[6], Vdouble tm[3][3])

compute tensor max shear values

See vis_MarkTensorMaxShear()

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

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
../../_images/vistools-disc3.gif

Figure 5-3, Scalar and Vector Values

../../_images/vistools-disc4.gif

Figure 5-4, Tensor Values

../../_images/vistools-disc5.gif

Figure 5-5, General Tensor Eigenvalues and Values

5.6. Function Descriptions

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

vis_Value *vis_ValueBegin(void)

create an instance of a Value object

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)

Returns:

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

void vis_ValueEnd(vis_Value *p)

destroy an instance of a Value object

See vis_ValueBegin()

Vint vis_ValueError(vis_Value *p)

return the current value of a Value object error flag

See vis_ValueBegin()

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

set pointers to attribute objects

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

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Value object.

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

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

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

draw values on PolyPointData primitive

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.

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.

Parameters:

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

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

draw values

Draw scalar values at npts points with scalar field s at locations x.

Errors

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

Parameters:

  • p – Pointer to Value object

  • npts – The number of points at which to draw scalar values.

  • s – Array of npts scalar field values.

  • x – Array of npts locations.

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

draw integer scalar values

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

Parameters:

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

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

traverse and draw a group of integer values

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.

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.

Parameters:

  • p – Pointer to Value object.

  • idtran – Pointer to IdTran object of node or element ids

  • group – Pointer to Group object of nodes or elements.

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

traverse and draw a group of values

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.

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

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

draw values

Draw vector values at npts points with vector field s at locations x.

Errors

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

Parameters:

  • p – Pointer to Value object

  • npts – The number of points at which to draw vector values

  • s – Array of npts vector field values.

  • x – Array of npts locations.

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

draw values

Draw tensor values at npts points with tensor field s at locations x.

Errors

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

Parameters:

  • p – Pointer to Value object

  • npts – The number of points at which to draw tensor values.

  • s – Array of npts tensor field values.

  • x – Array of npts locations.

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

draw values

Draw general tensor values at npts points with general tensor field s at locations x.

Errors

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

Parameters:

  • p – Pointer to Value object

  • npts – The number of points at which to draw general tensor values.

  • s – Array of npts general tensor field values.

  • x – Array of npts locations.