9. Annotation - Axis, Billboard, Dimension, Font, Glyph, Tess, Triad

The annotation modules Axis, Font and Glyph are designed to complement the other modules in VisTools by providing a convenient means of generating stroked text, various 3D glyphs (arrows, markers, etc.) and labelled and titled axes for building graphs. The Billboard module is meant to provide a screen oriented rectangular area for displaying 2D text and graphics. Billboards are useful for displaying quantitative information about individual entities such as finite elements or nodes. The Dimension module is designed to draw a number of standard dimensioning annotations such as linear and radial dimensioning, leader lines, etc. The Triad module may be used to draw representations of Cartesian, cylindrical, spherical and toroidal coordinate systems in various styles.

9.1. Annotated Axes - Axis

Use Axis to generate labelled and titled axes. The primary use of axes is to build a quantitative frame for 2D and 3D graphs. However axes are also useful for drawing “rulers” in 3D space for measuring distances between objects etc. The functions associated with a Axis object are the following.

Instance an Axis object using vis_AxisBegin(). Once an Axis object is instanced, set the attribute objects using vis_AxisSetObject() and set display parameters using vis_AxisSetParami(). The axis orientation is specified using vis_AxisSetPlane().

Each axis visualization entity is composed of up to three separately drawn parts - the path, plane and projection, drawn using vis_AxisPath(), vis_AxisPlane() and vis_AxisProjection() respectively. The terms path, plane and projection simply refer to the 3 orthogonal directions of the axis orientation direction cosine matrix. This orientation matrix is defined in a manner similar to that used for defining orientations in the Font module. The path is the primary axis direction. When the path component of the axis is drawn, the axis itself as well as titles, labels and intermediate tic marks are generated. The extension of the grid lines, which pass through the labelled points of the axis, into orthogonal planes is done by drawing the plane and projection components. For example, for a conventional XY graph, two axes and their associated plane components are required to generate the X and Y axes and the intersecting grid lines in the XY plane. A three dimensional XYZ graph would require three axes and the grid lines corresponding to the plane and projection components for each axis. Axis visualization entities are not subject to isosurface clipping.

By default all axis titles and numeric labels are drawn using a stroked font. The use of a stroked font as opposed to a raster font for drawing titles and labels may be toggled on or off using vis_AxisSetParami() with the parameter AXIS_STROKEFONT.

9.2. Attribute Objects

An Axis object uses DrawFun, Levels, VisContext, ColorMap and TransMap objects to define attributes required to generate an axis visualization entity. A Levels object is used to define the values along the axis at which labelled grid lines are to be placed. A discrete labelled grid line is generated at each level in the Levels attribute object. An Axis object requires a VisContext object for the axis and the fonts used for labelling and titling. If a TransMap attribute object is not set any specified constant transparency is ignored. An Axis object uses the following VisContext components.

AColor

Label color

Color

Plane fill color

DataIndex

Draw Levels object map index flag. If enabled, then the level number map index is
drawn as a DataIndex before any primitives associated with the
level are drawn.

Fill

Plane fill flag

Flags

VIS_BACKPLANEFLIP flips the labels and titles if the normal to
the character plane is pointing away from the viewer. This option
requires the current modelview matrix.

Format

Format of axis labels. If VIS_XFORMAT is used, the mantissa of
the label value is displayed. The exponent which has been factored
from each label value on the axis is displayed beneath the final
label on the axis.

Frequency

Number of intermediate tic marks between labelled grid points

LineWidth

Line width of axis

LineStyle

Line style of axis

MinorColor

Title and subtitle color

MinorLineWidth

Line width of grid lines

MinorLineStyle

Line style of grid lines

MinorSize

Size of axis title. The subtitle and axis labels are scaled from the
title size.

Size

Unit line width of cylindrical line style

TextBox

Text box size for positioning raster font titles and labels

Transparency

Fill plane transparency

XfmMatrix

Modelview matrix, used with back plane flip

XColor

Axis color

YColor

Color of grid lines in plane

ZColor

Color of grid lines along projection

Figure 9-1 illustrates an axis system. The axis path extends from left to right. The path component of the axis is drawn as a line with a title and subtitle lying below the axis in the axis plane. Seven equally spaced points are labelled along the axis. Intermediate tic marks are placed between the labels. The plane component of the axis consists of seven vertical lines drawn through the labelled points in the positive direction in the axis plane. The projection component of the axis consists of seven lines drawn “out of the paper”, orthogonal to the axis plane.

../../_images/vistools-anno1.gif

Figure 9-1, Axis Path, Plane and Projection

9.3. Function Descriptions

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

vis_Axis *vis_AxisBegin(void)

create an instance of an Axis object

Create an instance of a Axis 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 path, plane and projection directions are along the x, y and z global coordinate axes respectively. The axis sense is right handed.

Destroy an instance of a Axis object using 

void vis_AxisEnd (vis_Axis *axis)

Return the current value of a Axis object error flag using 

Vint vis_AxisError (vis_Axis *axis)

Returns:

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

void vis_AxisEnd(vis_Axis *p)

destroy an instance of a Axis object

See vis_AxisBegin()

Vint vis_AxisError(vis_Axis *p)

return the current value of a Axis object error

See vis_AxisBegin()

void vis_AxisSetObject(vis_Axis *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

Set a pointer to an attribute object. All the attribute objects are mandatory for all drawing methods.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Axis object.

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

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

  • object – Pointer to the object to be set.

void vis_AxisSetPlane(vis_Axis *p, Vfloat path[3], Vfloat plane[3])

set axis orientation

Set axis orientation. The path and plane vectors need not be normalized or orthogonal. The axis plane is formed perpendicular to the axis path in the plane defined by the path and plane vectors. The path and plane vectors can not be parallel.

Get path and plane as output arguments using 

void vis_AxisGetPlane (vis_Axis *axis,
                       Vfloat path[3],
                       Vfloat plane[3])

Errors

VIS_ERROR_COMPUTE is generated if path and plane do not define a unique orientation plane.

Parameters:

  • p – Pointer to Axis object.

  • path – Vector in direction of axis path.

  • plane – Vector in direction of axis plane.

void vis_AxisSetParami(vis_Axis *p, Vint ptype, Vint iparam)

set axis display parameters

Specify the drawing of the first label on the axis path. This may disabled to prevent spatial collisions of grid labels on 3D graphs. By default AXIS_FIRSTLABEL is set to on.

The labels may be drawn using the text labels contained in the Levels attribute object by enabling the AXIS_LABELUSELEVELS parameter. By default AXIS_LABELUSELEVELS is set to off.

Specify the drawing of the first grid line on axis plane and projections. This grid line normally coincides in space with the axes of orthogonal axes. By default AXIS_FIRSTGRID is set to off.

Specify the drawing of the last grid line on axis plane and projections. By default AXIS_LASTGRID is set to on.

Specify the drawing of an axis at the end of the axis plane. If this parameter is enabled it is a good idea to disable AXIS_LASTGRID when drawing the plane and projection or orthogonal axes. By default AXIS_PLANEEND is set to off.

Set rotation of axis labels using AXIS_ROTATELABEL. The label may be rotated by +90. degrees using AXIS_ROTATELABEL_PLUS90. and by -90. degrees using AXIS_ROTATELABEL_MINUS90. By default AXIS_ROTATELABEL is set to XIS_ROTATELABEL_NONE.

Set axis sense. By default AXIS_SENSE is set to off.

Set short grid line flag. If this flag is enabled short grid lines are drawn on the axis plane and projection. Plane fill, if specified, is always drawn to fill the entire plane. By default AXIS_SHORTGRID is set to off.

Toggle the use of a stroked font as opposed to a raster font for drawing titles and labels. By default AXIS_STROKEFONT is set to VIS_ON.

Errors

VIS_ERROR_ENUM is generated if an improper type is specified.

Parameters:

  • p – Pointer to Axis object.

  • ptype – Type of display parameter to set 

    x=AXIS_FIRSTLABEL         Draw first axis label
 =AXIS_FIRSTGRID          Draw first grid line on the axis
                          plane and projection
 =AXIS_LABELUSELEVELS     Toggle Levels labels.
 =AXIS_LASTGRID           Draw last grid line on the axis
                          plane and projection
 =AXIS_PLANEEND           Draw axis at end of axis plane
 =AXIS_ROTATELABEL        Rotate label + or - 90 degrees
 =AXIS_SENSE              Set left handedness of axis
 =AXIS_SHORTGRID          Specify short grid lines on the axis
                          plane and projection
 =AXIS_STROKEFONT         Toggle use of stroked font labels.

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

    x=VIS_OFF                   Turn parameter off
 =VIS_ON                    Turn parameter on
 =AXIS_ROTATELABEL_NONE     Do not rotate label
 =AXIS_ROTATELABEL_PLUS90   Rotate label +90 degrees
 =AXIS_ROTATELABEL_MINUS90  Rotate label -90 degrees

void vis_AxisGetPlane(vis_Axis *p, Vfloat path[3], Vfloat plane[3])

get axis orientation

See vis_AxisSetPlane()

void vis_AxisPath(vis_Axis *p, Vfloat x[3], Vfloat length, Vchar *title, Vchar *subtitle)

draw axis path

Draw an axis with its origin at x projecting a distance length along the axis path. The axis is labelled at the locations specified by the Levels attribute object. Tic marks are drawn between labelled points. A title and subtitle are drawn immediately below the axis.

Parameters:

  • p – Pointer to Axis object.

  • x – Origin of axis

  • length – Length of axis along path

  • title – Axis title

  • subtitle – Axis subtitle

void vis_AxisPlane(vis_Axis *p, Vfloat x[3], Vfloat length, Vfloat lengthy, Vchar *title, Vchar *subtitle)

draw grid lines and plane fill in plane

Draw grid lines in axis plane with its origin at x projecting a distance length along the axis path and a distance lengthy along the axis plane. The extent of the axis plane is defined by the distances length and lengthy. The axis plane is filled at this time if requested. A title and subtitle are drawn immediately above the end of the grid lines in the axis plane.

Parameters:

  • p – Pointer to Axis object.

  • x – Origin of axis

  • length – Length of axis along path

  • lengthy – Length of grid lines along plane

  • title – Axis title

  • subtitle – Axis subtitle

void vis_AxisProjection(vis_Axis *p, Vfloat x[3], Vfloat length, Vfloat lengthz, Vchar *title, Vchar *subtitle)

draw grid lines along projection

Draw grid lines along axis projection with its origin at x projecting a distance length along the axis path and a distance lengthz along the axis projection. A title and subtitle are drawn immediately below the end of the grid lines along the axis projection.

Parameters:

  • p – Pointer to Axis object.

  • x – Origin of axis

  • length – Length of axis along path

  • lengthz – Length of grid lines along projection

  • title – Axis title

  • subtitle – Axis subtitle

9.4. Billboard Displays - Billboard

Use Billboard for displaying 2D text and graphics in a screen oriented rectangular area. A billboard can be used to display information particular to a specific entity such as finite element properties, or any information which must remain readable such as a graph legend or customized color bar.

A Billboard object allows you to insert items (text, lines, points, polygons, etc.) and spacing information in a manner similar to a typewriter, in which one adds a series of text, from the top down, separated by spaces and newlines. A Billboard object will automatically adjust its width and height so that it encloses the items contained in it.

The Billboard object employs a 2D coordinate system based on a the size of a text box. The dimensions of the text box are defined in the visualization context TextBox. A single character (e.g., ‘a’) will have the width and height of one text box. The dimensions of geometric items (e.g., lines, polygons, rectangles, etc.) are specified in terms of a text box. Therefore, the string “abcd” and a line of length 4.0 will have the same length. Positive x and y is to the right and up, respectively.

The placement of items within the billboard is performed using a current (x, y) position stored in the Billboard object. Initially, the current position is at the top left of the billboard. When an item is added, it is placed at the current position within the billboard. The current position is then automatically incremented in x, depending on the item. For example, adding the text string “stress” will increment the current x position by six units; adding a line of width 2.5 will increment the current x position by 2.5 units. Adding spaces and incrementing the current y position must be done explicitly.

Billboard visualization entities are not subject to isosurface clipping.

The functions associated with a Billboard object are the following.

Since the Billboard module uses “DC” style drawing functions to perform all drawing, it is suggested to disable lighting before drawing a billboard with vis_BillboardDraw(). This will ensure that the billboard is drawn in base colors without any lighting effects.

9.5. Attribute Objects

A Billboard object uses DrawFun, VisContext, ColorMap and TransMap objects to define attributes required to generate a billboard visualization entity.

A Billboard object requires a VisContext object for the billboard background and border colors and transparency. It is also used to define the size of a text box used for positioning items.

If a TransMap attribute object is not set then transparency is ignored.

A Billboard object uses the following VisContext components.

AColor

Border color

BColor

Border shadow color (for bevels)

CColor

Border highlight color (for bevels)

Color

Background rectangle fill color

DeviceOffset

Offset of attachment point position from specified anchor point in
device coordinates

LineWidth

Line width of border

MinorColor

Offset vector color

Position

Attachment point position on billboard

TextBox

Text box size for positioning items

Transparency

Background rectangle transparency

A Billboard object references the following DrawFun functions.

vgl_DrawFunLineStyle
vgl_DrawFunLineWidth
vgl_DrawFunPointSize
vgl_DrawFunPolygonDC
vgl_DrawFunPolyLineDC
vgl_DrawFunPolyPointDC
vgl_DrawFunTextDC

Figure 9-2 illustrates a simple billboard that could be used to display summary information about a specific finite element. The billboard is always drawn screen oriented (perpendicular to the viewer) and anchored at a 3D world coordinate. This allows it to be anchored in 3D to the entity which it describes.

../../_images/vistools-anno2.gif

Figure 9-2, Simple Billboard for Element Information

9.6. Function Descriptions

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

vis_Billboard *vis_BillboardBegin(void)

create an instance of a Billboard object

Create an instance of a Billboard object. Memory is allocated for the object’s private data and the pointer to the data is returned. By default all attribute object pointers are NULL.

Destroy an instance of a Billboard object using 

void vis_BillboardEnd (vis_Billboard *billboard)

Return the current value of a Billboard object error flag using 

Vint vis_BillboardError (vis_Billboard *billboard)

Returns:

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

void vis_BillboardEnd(vis_Billboard *p)

destroy an instance of a Billboard object

See vis_BillboardBegin()

Vint vis_BillboardError(vis_Billboard *p)

return the current value of a Billboard object error flag

See vis_BillboardBegin()

void vis_BillboardSetObject(vis_Billboard *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

Set a pointer to an attribute object. The DrawFun, VisContext and ColorMap attribute objects are mandatory. The TransMap attribute object is optional.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Billboard object.

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

    x=VGL_DRAWFUN            DrawFun object
 =VIS_VISCONTEXT         VisContext object
 =VIS_COLORMAP           ColorMap object
 =VIS_TRANSMAP           TransMap object

  • object – Pointer to the object to be set.

void vis_BillboardSetParami(vis_Billboard *p, Vint ptype, Vint iparam)

set display parameters

Specify the addition of bevels for drawing the billboard border. By default BILLBOARD_BEVEL is set to on.

Specify the drawing of an arrow from the billboard position to its anchor point. The vector is drawn only if the billboard has a nonzero offset from the anchor point specified by the DeviceOffset visualization context. By default BILLBOARD_OFFSET_VECTOR is set to off.

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

  • p – Pointer to Billboard object.

  • ptype – Type of display parameter to set 

    x=BILLBOARD_BEVEL         Draw billboard with bevels
 =BILLBOARD_OFFSET_VECTOR Draw billboard with location vector

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

    x=VIS_OFF                 Turn parameter off
 =VIS_ON                  Turn parameter on

void vis_BillboardSetItemParami(vis_Billboard *p, Vint ptype, Vint iparam)

set item integer parameters

Specify the color used to draw items. The color value is an index for a color map object. By default BILLBOARD_COLOR is set to one.

Specify the point size used to draw a point item. By default BILLBOARD_POINT_SIZE is set to one.

Specify the line width used to draw line, rule, and polyline items. By default BILLBOARD_LINE_WIDTH is set to one.

Specify the line style used to draw line, rule, and polyline items. By default BILLBOARD_LINE_STYLE is set to VIS_SOLID.

Specify the rule style used to draw a rule item. By default BILLBOARD_RULE_STYLE is set to BILLBOARD_RULE_STYLE_NONE.

Specify the transparency used to draw items. The transparency value is an index for a transparency map object. By default BILLBOARD_TRANSPARENCY is set to one.

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

  • p – Pointer to Billboard object.

  • ptype – Type of current item display parameter to set 

    x=BILLBOARD_COLOR         Set the item color
 =BILLBOARD_POINT_SIZE    Set the point size for point items
 =BILLBOARD_LINE_WIDTH    Set the line width for
                          line, rule, and polyline items
 =BILLBOARD_LINE_STYLE    Set the line style for
                          line, rule, and polyline items
 =BILLBOARD_RULE_BEVEL    Draw rule with bevels
 =BILLBOARD_SHADOW_COLOR  Set the shadow color for
                          beveled rules.
 =BILLBOARD_TRANSPARENCY  Set the item transparency

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

    x=VIS_OFF                 Turn parameter off
 =VIS_ON                  Turn parameter on
 =VIS_SOLID               Solid line style
 =VIS_DASHDASH            Dashed line style
 =VIS_DOTDOT              Dotted line style
 =VIS_DOTDASH             Dotted/dashed line style

void vis_BillboardSetItemParamfv(vis_Billboard *p, Vint ptype, Vfloat fparam[])

set item float vector parameters

Specify the current positional offset of an item. The offset is added to the position of an item when it is drawn. The offset is specified in multiples of a text box. By default BILLBOARD_OFFSET is set to (0.0, 0.0).

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

  • p – Pointer to Billboard object

  • ptype – Type of parameter to set 

    =BILLBOARD_OFFSET        Offset of an item

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

void vis_BillboardLineItem(vis_Billboard *p, Vfloat length)

add a line item

Add a line item of length length to a Billboard object. The line is drawn from the current (x,y) position to the right. The current x position is incremented by the length of the line.

Parameters:

  • p – Pointer to Billboard object

  • length – Length of the line

void vis_BillboardPointItem(vis_Billboard *p)

add a point item

Add a point item to a Billboard object. The point is drawn at the current (x,y) position. The current x position is incremented by 1.

Parameters:

p – Pointer to Billboard object

void vis_BillboardPolygonItem(vis_Billboard *p, Vint npts, Vfloat pts[][2], Vint fill)

add a polygon item

Add a polygon item to a billboard. The polygon points are offsets relative to the current (x,y) position. Positive offsets are to the right and up; negative to the left and down. The current x position is incremented by the maximum x coordinate value in the pts array.

Errors

SYS_ERROR_VALUE is generated if npts = 0.

Parameters:

  • p – Pointer to Billboard object

  • npts – Number of points defining the polygon

  • pts – Points defining the polygon

  • fill – Flag specifying a filled polygon

void vis_BillboardRuleItem(vis_Billboard *p)

add a rule item

Add a rule item to a billboard. The width of the rule will equal the width of the billboard and will be centered in the text box at the current y position. A new line is automatically generated and the current x position is set to 0.0 (left).

Parameters:

p – Pointer to Billboard object

void vis_BillboardRectangleItem(vis_Billboard *p, Vfloat width, Vfloat height, Vint solid)

add a rectangle item

Add a rectangle item to a billboard of width width and height height. The rectangle is drawn up and to the right with its bottom left corner at the current (x,y) position. The current x position is incremented by the width of the rectangle.

Parameters:

  • p – Pointer to Billboard object

  • width – Width of the rectangle

  • height – Height of the rectangle

  • solid – Flag specifying a solid rectangle

void vis_BillboardTextItemtv(vis_Billboard *p, Vtchar *str)

add a text item

See vis_BillboardTextItem()

void vis_BillboardTextItem(vis_Billboard *p, Vchar *text)

add a text item

Add a text item to a billboard. The text is drawn with its bottom left corner at the current (x,y) position. The current x position is incremented by the number of characters in text

. If the string ends in a newline character (i.e., ‘

’) then a new line is automatically generated and the current x position is set to 0.0.

Parameters:

  • p – Pointer to Billboard object

  • text – Text string

void vis_BillboardTitleItemtv(vis_Billboard *p, Vtchar *str)

add a title item

See vis_BillboardTitleItem()

void vis_BillboardTitleItem(vis_Billboard *p, Vchar *title)

add a title item

Add a title item to a billboard. The title is centered in x in the billboard at the current y position. A new line is automatically generated and the current x position is set to 0.0 (left).

Parameters:

  • p – Pointer to Billboard object

  • title – Title string

void vis_BillboardNewLine(vis_Billboard *p, Vfloat nlines)

increment the current y position

Increment the current y position by nlines * (text box height). The current x position is set to 0.0.

Errors

SYS_ERROR_VALUE is generated if nlines < 0.

Parameters:

  • p – Pointer to Billboard object

  • nlines – Number of lines to increment

void vis_BillboardSpace(vis_Billboard *p, Vfloat nspaces)

increment the current x position

Increment the current x position by nspaces * (text box width).

Parameters:

  • p – Pointer to Billboard object

  • nspaces – Number of spaces to increment

void vis_BillboardDraw(vis_Billboard *p, Vfloat x[3])

display the contents of a billboard

Display the contents of a Billboard object at the specified location in world coordinates.

Parameters:

  • p – Pointer to Billboard object

  • x – World coordinate anchor point

void vis_BillboardErase(vis_Billboard *p)

erase all items

Erase all items. The current x position is set to 0.0 (left) and the current y position is set to the top of the billboard.

Parameters:

p – Pointer to Billboard object

9.7. Dimensioning - Dimension

Use Dimension to display dimensioning and annotation information for 2D or 3D objects. Dimensioning can be used to display the numeric dimensions such as length, width, height, distance, radius, etc. of geometric features

The Dimension object employs a local coordinate system embedded in 3D space called the dimension plane to define the placement of the dimensioning lines and text. The orientation of the dimension plane is defined by a pair of 3D vectors. The x’,y’,z’ axes of local coordinate system define the “horizontal”, “vertical” and “indepth” directions of the dimensioning annotation.

There are two basic types of dimensioning annotation, linear dimensions and leader lines. A linear dimension is used to label the straight line distance between two points. It consists of two extension lines, a dimension line, a label and in some cases a leader line. The extension lines are lines drawn from the two points which define a straight line feature to the position of the dimension line and label. The dimension line is drawn perpendicular to the extension lines and defines the straight line distance between the two points. A linear dimension can be oriented to be horizontal, vertical, in depth or aligned with the angle of a feature.

A leader line is used to dimension specific features (e.g., holes) and consists of a line pointing to the feature and a label. A special type of leader termed a radius leader line can be used to dimension the radius of a circular feature.

The following functions are associated with a Dimension object.

Instance a Dimension object using vis_DimensionBegin(). Once a Dimension object is instanced, set the attribute objects using vis_DimensionSetObject() and set display parameters using vis_DimensionSetParami() and vis_DimensionSetParamf(). Dimension lines, leader lines and labels are drawn with respect to a local coordinate system specified by vis_DimensionSetPlane(). The local x’, y’, z’ axes define the horizontal, vertical and depth directions. Linear dimensions are drawn using vis_DimensionLinear() and leader lines are drawn using vis_DimensionLeader() and vis_DimensionRadius(). An angular dimension may be drawn using vis_DimensionAngular().

All linear dimension annotation drawn using vis_DimensionLinear() uses two points to define the feature to be dimensioned and a single point for positioning the dimensioning label. The dimension line is drawn through the label point parallel to an axis of the local coordinate system (horizontal, vertical or depth axis) or parallel to the line between the feature points. Extension lines are drawn from the feature points to the dimension line. The extension lines are constructed to be perpendicular to the dimension line. The label may be drawn horizontally or aligned to the dimension line. The dimension label is positioned along the dimension line in different ways depending upon user options and whether it is located inside or outside of the extension lines. The user may specify that the label be automatically placed by calling vis_DimensionSetParami() with the DIMENSION_LABEL_AUTO parameter enabled. In this case the label is centered exactly between the extension lines if its original input location is between the extension lines and it is positioned at a user specified offset from an extension line if its original input location is outside the extension lines. If the automatic placement option is not enabled the label is placed exactly at the original input location. The use of a stroked font as opposed to a raster font for drawing labels may be toggled on or off using the parameter DIMENSION_STROKEFONT. Figure 9-3a illustrates a linear dimension annotation aligned (drawn parallel) to the line between the feature points and centered between the extension lines.

../../_images/vistools-anno3a.gif

Figure 9-3a, Linear Dimension Annotation

The functions vis_DimensionLeader() and vis_DimensionRadius() are used to draw leader lines. The first point input to leader line drawing is the attachment point. This point specifies the location of the tip of the arrow of the leader annotation. The leader line angles from the attachment point to the vertical position of the label, the leader line is then continued horizontally to the label. Figure 9-3b illustrates a simple leader with a label.

../../_images/vistools-anno3b.gif

Figure 9-3b, Leader with Label

In the case of the radius style leader drawn using vis_DimensionRadius(), the leader line from the attachment point passes through a specified center point to the vertical position of the label. Figure 9-3c illustrates a radius leader with a label and center mark.

../../_images/vistools-anno3c.gif

Figure 9-3c, Radius Leader with Label and Center Mark

All angular dimension annotation drawn using vis_DimensionAngular() uses three points to define the feature to be dimensioned and a single point for positioning the dimensioning label. The dimension line is an arc drawn through the label point at a constant radius from a given center point. Extension lines are drawn from the center point through the feature points The length of the extension lines is the maximum distance of a feature point from the center point. The label may be drawn horizontally or aligned to the dimension line arc. In a manner similar to the placement of label in a linear dimension. Figure 9-3d illustrates an angular dimension annotation orthogonal to the arc between the feature points and centered between the extension lines.

../../_images/vistools-anno3d.gif

Figure 9-3d, Angular Dimension Annotation

9.8. Attribute Objects

A Dimension object uses ColorMap, DrawFun and VisContext objects to define attributes required to generate a dimension visualization entity. A Dimension object requires a VisContext object for line color, width and style, font size and color for labels, and arrow head attributes. A Dimension object uses the following VisContext components.

Angle

Half angle in degrees of an arrow head

Color

Leader, dimension and extension lines color

Fill

Arrow head fill flag

Flags

VIS_BACKPLANEFLIP flips a label if the normal to the dimension
plane is pointing away from the viewer. This option requires the
current modelview matrix. VIS_VECTORNOCAP draws arrow heads
without a cap. VIS_VECTORNOHEAD draws all arrows without heads.

LineWidth

Line width for all extension, leader and dimension lines.

LineStyle

Line style for all leader and dimension lines.

MinorColor

Label color

MinorLineWidth

Label line width

MinorLineStyle

Line style for all extension lines.

MinorSize

Size of arrow head

Ratio

Arrow head slant ratio

Refinement

Arrow head refinement

Shade

Arrow head shading

Size

Text size for labels

VectorType

Arrow head type

XfmMatrix

Modelview matrix, used with back plane flip

A Dimension object references the following DrawFun functions.

vgl_DrawFunColor
vgl_DrawFunColorIndex
vgl_DrawFunLineStyle
vgl_DrawFunLineWidth
vgl_DrawFunPolyLine
vgl_DrawFunTrans
vgl_DrawFunTransIndex

9.9. Function Descriptions

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

vis_Dimension *vis_DimensionBegin(void)

create an instance of a Dimension object

Create an instance of a Dimension 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 dimension plane is oriented with the x and y global coordinate axes.

Destroy an instance of a Dimension object using 

void vis_DimensionEnd (vis_Dimension *dimension)

Return the current value of a Dimension object error flag using 

Vint vis_DimensionError (vis_Dimension *dimension)

Returns:

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

void vis_DimensionEnd(vis_Dimension *p)

destroy an instance of a Dimension object

See vis_DimensionBegin()

Vint vis_DimensionError(vis_Dimension *p)

return the current value of a Dimension object error flag

See vis_DimensionBegin()

void vis_DimensionSetObject(vis_Dimension *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

Set a pointer to an attribute object.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Dimension object.

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

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

  • object – Pointer to the object to be set.

void vis_DimensionSetParami(vis_Dimension *p, Vint rtype, Vint iparam)

set dimension display parameters

The parameter DIMENSION_ANGLE_LOCK specifies that a leader line is constrained to make a specified angle from its attachment point to the vertical position of its label. The angle is specified using vis_DimensionSetParamf() with the parameter DIMENSION_ANGLE. By default DIMENSION_ANGLE_LOCK is set to VIS_OFF.

The parameter DIMENSION_CENTER_MARK indicates whether the center mark of radius leader lines are to be drawn with a cross. By default DIMENSION_CENTER_MARK is set to VIS_ON.

The parameter DIMENSION_EXTENSIONLINES toggles the drawing of linear dimension extension lines. By default DIMENSION_EXTENSIONLINES is set to VIS_ON.

The parameter DIMENSION_LABEL_ALIGN specifies the alignment of the label. DIMENSION_HORIZONTAL will orient the label parallel to the local x’ axis, DIMENSION_ALIGNED will orient the label parallel with the dimension line, and DIMENSION_ORTHOGONAL will orient the label at a right angle with the dimension line. By default DIMENSION_LABEL_ALIGN is set to DIMENSION_HORIZONTAL.

The parameter DIMENSION_LABEL_AUTO specifies the automatic placement of labels. Normally, labels are placed at the location specified when defining a dimension. If DIMENSION_LABEL_AUTO is enabled then labels are placed at an offset from the dimensioning lines. The offset is specified using vis_DimensionSetParamf() with the parameter DIMENSION_OFFSET. If the label is between the extension lines it is centered. All labels placed drawing leaders with vis_DimensionLeader() and vis_DimensionRadius() are constrained to be a horizontal distance DIMENSION_OFFSET from the angled leader line. By default DIMENSION_LABEL_AUTO is set to VIS_ON.

The parameter DIMENSION_LABEL_POSITION specifies the position on the label that linear dimension labels will be anchored. A position of VIS_LEFT will anchor the label at its left extent. A position of VIS_RIGHT will anchor the label at its right extent. By default DIMENSION_LABEL_POSITION is set to VIS_CENTER.

The parameter DIMENSION_LINEAR_ALIGN specifies the orientation of linear dimensions with respect to the local coordinate system. DIMENSION_VERTICAL will orient the dimension line parallel to the local y’ axis; DIMENSION_HORIZONTAL will orient it parallel to the local x’ axis; DIMENSION_INDEPTH will orient it parallel to the local z’ axis; DIMENSION_ALIGNED will orient it parallel with the line between the two feature delineation points. By default DIMENSION_LINEAR_ALIGN is set to DIMENSION_HORIZONTAL.

The parameter DIMENSION_INSIDE specifies that linear dimension lines will be drawn on the inside of the extension lines. By default DIMENSION_INSIDE is set to VIS_ON.

The parameters DIMENSION_NOHEAD_FIRST and DIMENSION_NOHEAD_SECOND are designed to control the drawing of arrow heads on linear dimension lines. By default DIMENSION_NOHEAD_FIRST and DIMENSION_NOHEAD_SECOND are set to VIS_OFF. Note that all arrow heads are disabled if the visualization context VIS_VECTORNOHEAD flag is enabled.

Toggle the use of a stroked font as opposed to a raster font for drawing labels. By default DIMENSION_STROKEFONT is set to VIS_ON.

Errors

VIS_ERROR_ENUM is generated if an improper rtype is specified.

Parameters:

  • p – Pointer to Dimension object.

  • rtype – Type of display parameter to set 

    x=DIMENSION_ANGLE_LOCK     Constrain angle of leader lines
 =DIMENSION_CENTER_MARK    Mark center point of radius leader
 =DIMENSION_EXTENSIONLINES Toggle drawing of extension lines
 =DIMENSION_LABEL_ALIGN    Label alignment
 =DIMENSION_LABEL_AUTO     Place label at specified offset
 =DIMENSION_LABEL_POSITION Anchor label at specified position
 =DIMENSION_INSIDE         Place dimension lines on inside of
                           extension lines
 =DIMENSION_LINEAR_ALIGN   Linear dimension alignment
 =DIMENSION_NOHEAD_FIRST   No head on first arrow
 =DIMENSION_NOHEAD_SECOND  No head on second arrow
 =DIMENSION_STROKEFONT     Toggle use of stroked font labels.

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

    x=VIS_OFF                Turn parameter off
 =VIS_ON                 Turn parameter on
 =DIMENSION_HORIZONTAL   Orient horizontally
 =DIMENSION_VERTICAL     Orient vertically
 =DIMENSION_INDEPTH      Orient in depth
 =DIMENSION_ALIGNED      Align in line
 =DIMENSION_ORTHOGONAL   Align orthogonally
 =VIS_CENTER             Anchor label at label center
 =VIS_RIGHT              Anchor label at label right
 =VIS_LEFT               Anchor label at label left

void vis_DimensionSetParamf(vis_Dimension *p, Vint ptype, Vfloat fparam)

set dimension display parameters

The parameter DIMENSION_ANGLE specifies the angle in degrees that the leader line is constrained to make from its attachment point to the vertical position of its label. This angle is used only if DIMENSION_ANGLE_LOCK is enabled using vis_DimensionSetParami(). By default DIMENSION_ANGLE is set to 45.0 degrees.

The parameter DIMENSION_GAP specifies gap of extension lines from feature locations in world coordinates. By default DIMENSION_GAP is set to 0.0.

The parameter DIMENSION_LABEL_ANGLE specifies an additional angle of rotation to be applied to labels. By default DIMENSION_LABEL_ANGLE is set to 0.0.

The parameter DIMENSION_OFFSET specifies the length of certain segments of leader lines and dimension lines. If DIMENSION_LABEL_AUTO is enabled using vis_DimensionSetParami() then the length of the horizontal segment of a leader line drawn using vis_DimensionLeader() or vis_DimensionRadius() is constrained to be DIMENSION_OFFSET. Any leader lines outside extension lines drawn using vis_DimensionLinear() or vis_DimensionAngular() are constrained to be of length DIMENSION_OFFSET. By default DIMENSION_OFFSET is set to 1.0.

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

  • p – Pointer to Dimension object.

  • ptype – Type of display parameter to set 

    x=DIMENSION_ANGLE          Angle of leader lines
 =DIMENSION_GAP            Extension line gap
 =DIMENSION_LABEL_ANGLE    Angle of label
 =DIMENSION_OFFSET         Length of horizontal leader

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

void vis_DimensionSetPlane(vis_Dimension *p, Vfloat right[3], Vfloat up[3])

set dimension plane

Set dimension plane. The dimension plane is specified as the plane formed by the right and up vectors. The right vector defines the x’ direction. The y’ direction lies in the dimension plane perpendicular to x’. The normal to the dimension plane defines the z’ axis. The right and up vectors need not be normalized or orthogonal but they cannot be parallel. By default the right vector is (1.,0.,0.) and the up vector is (0.,1.,0.).

Get right and up as output arguments using 

void vis_DimensionGetPlane (vis_Dimension *dimension,
                            Vfloat right[3],
                            Vfloat up[3])

Errors

VIS_ERROR_COMPUTE is generated if right and up do not define a unique dimension plane.

Parameters:

  • p – Pointer to Dimension object

  • right – Vector in direction of dimension local x’ axis.

  • up – Vector in direction of dimension local y’ axis.

void vis_DimensionGetPlane(vis_Dimension *p, Vfloat right[3], Vfloat up[3])

get dimension plane

See vis_DimensionSetPlane()

void vis_DimensionLeader(vis_Dimension *p, Vfloat x[3], Vfloat xlabel[3], Vchar *label)

draw a leader dimension

Draw a leader line pointing to x. A line will be drawn angled from fpt to a vertical position defined by xlabel. A horizontal line is drawn from the angled leader line to the position of the label. The angle made by the leader line with respect to the horizontal direction may be constrained to be a specified angle by setting the angle using vis_DimensionSetParamf() with parameter DIMENSION_ANGLE and then enabling the angle constrain using vis_DimensionSetParami() with parameter DIMENSION_ANGLE_LOCK. The position of x relative to xlabel determines how the horizontal segment of the leader line is drawn, left or right. If DIMENSION_LABEL_AUTO is enabled then label will be drawn a fixed offset, DIMENSION_OFFSET, specified using vis_DimensionSetParamf() from the angled leader line otherwise the label will be drawn at xlabel.

Parameters:

  • p – Pointer to Dimension object.

  • x – Feature location

  • xlabel – Label location

  • label – Label

void vis_DimensionLinear(vis_Dimension *p, Vfloat x1[3], Vfloat x2[3], Vfloat xlabel[3], Vchar *label)

draw a linear dimension

Draw a linear dimension with extension lines originating from x1 and x2 and extending to the position defined by xlabel. The position of xlabel relative to the extension lines determines where the label is drawn: to the left, right or in the center of the extension lines.

If xlabel is to the left or right of the extension lines and DIMENSION_LABEL_AUTO is on then label will be drawn a fixed distance to the left or right from the extension lines, otherwise the label will be drawn at xlabel. If xlabel is inside the extension lines then label will be drawn centered.

If DIMENSION_LINEAR_ALIGN is set to DIMENSION_HORIZONTAL then the dimension line will be drawn passing through the point xlabel parallel to the dimension plane x’ axis; if it is set to DIMENSION_VERTICAL it will be drawn parallel to the y’ axis; if it is set to DIMENSION_INDEPTH it will be drawn parallel to the z’ axis; if it is set to DIMENSION_ALIGNED then it will be drawn parallel to the two feature delineation points x1 and x2.

Parameters:

  • p – Pointer to Dimension object.

  • x1 – First feature location

  • x2 – Second feature location

  • xlabel – Dimension line location

  • label – Label

void vis_DimensionAngular(vis_Dimension *p, Vfloat x1[3], Vfloat x2[3], Vfloat xcenter[3], Vfloat xlabel[3], Vchar *label)

draw angular dimension

Draw an angular dimension with two extension lines originating from xcenter passing through x1 and x2. The length of the extension lines is computed as the maximum distance of either x1 or x2 from xcenter.

The position of xlabel relative to the extension lines determines where the label is drawn: to the left, right or in the center of the extension lines. If xlabel is to the left or right of the extension lines and DIMENSION_LABEL_AUTO is on then label will be drawn a fixed distance to the left or right from the extension lines, otherwise the label will be drawn at xlabel. If xlabel is inside the extension lines then label will be drawn centered.

Parameters:

  • p – Pointer to Dimension object.

  • x1 – First feature location

  • x2 – Second feature location

  • xcenter – Center of circle

  • xlabel – Dimension line location

  • label – Label

void vis_DimensionRadius(vis_Dimension *p, Vfloat x[3], Vfloat xcenter[3], Vfloat xlabel[3], Vchar *label)

draw a circle radius leader line dimension

Draw a circle radius leader line pointing to x and marking the center of a circle of radius |fpt - xcenter|. A line will be drawn from x though xlabel to a vertical position defined by xlabel. A cross will be drawn at xcenter. If DIMENSION_LABEL_AUTO is enabled then label will be drawn a fixed offset, DIMENSION_OFFSET, specified using vis_DimensionSetParamf() from the angled leader line otherwise the label will be drawn at lpt.

Errors

VIS_ERROR_COMPUTE is generated if the center of the circle, xcenter is coincident with the feature location, x.

Parameters:

  • p – Pointer to Dimension object.

  • x – Feature location

  • xcenter – Center of circle

  • xlabel – Label location

  • label – Label

9.10. Stroked Text - Font

Use Font to generate stroked text positioned and oriented in 3D space. A full set of text transformations are available including 3D extrusion. Extrusion allows light source shaded 3D text to be generated. A Font object, when first created, contains a built-in constant space font. A selection of other fonts may be established in a Font object by reading one of the font description files provided with VisTools. Font visualization entities are not subject to isosurface clipping. The functions associated with a Font object are the following.

Instance a Font object using vis_FontBegin(). Once a Font object is instanced, set the attribute objects using vis_FontSetObject() and set display parameters using vis_FontSetParami() and vis_FontSetParamf(). Text is drawn in a plane parallel to the plane specified by vis_FontSetPlane(). A text string is drawn at a given point in the font represented by the Font object using vis_FontText(). The length of a text string may be returned using vis_FontLength().

9.11. Attribute Objects

A Font object uses DrawFun, VisContext, ColorMap and TransMap objects to define attributes to generate a font visualization entity. A DrawFun object is required but VisContext, ColorMap and TransMap objects are optional. A Font object uses the following VisContext components.

Color

Text color

DeviceSize

Size of character in device coordinates

Flags

VIS_BACKPLANEFLIP flips the text string if the normal to the
character plane is pointing away from the viewer. This option
requires the current modelview matrix.

LineWidth

Line width of text

LineStyle

Line style of text

Position

Text string alignment. The alignment specifies the anchor point of
the text string relative to the text string extent.

ProjMatrix

Projection matrix, used with device sizing

Shade

Flag to apply light source shading

Size

Size of character in world coordinates

SizeType

Specify either world coordinate or device coordinate sizing

Transparency

Text extrusion transparency

Viewport

Viewport limits, used with device sizing

XfmMatrix

Modelview matrix, used with device sizing and back plane flip

If the VisContext attribute object pointer is NULL, then stroked text is generated without referencing the VisContext, ColorMap and TransMap objects. No attribute drawing functions are invoked, all text is drawn with line and vertex shaded polygon graphics primitives assuming the current color, line width, line style and transparency.

Figure 9-4 illustrates a number of font styles.

../../_images/vistools-anno4.gif

Figure 9-4, Font Styles

9.12. Function Descriptions

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

vis_Font *vis_FontBegin(void)

create an instance of a Font object

Create an instance of a Font 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. Font path and plane are oriented along the global coordinate x and y axes. Font direction is VIS_RIGHT and font alignment is VIS_LEFT and VIS_BOTTOM.

Destroy an instance of a Font object using 

void vis_FontEnd (vis_Font *font)

Return the current value of a Font object error flag using 

Vint vis_FontError (vis_Font *font)

Returns:

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

void vis_FontEnd(vis_Font *p)

destroy an instance of a Font object

See vis_FontBegin()

Vint vis_FontError(vis_Font *p)

return the current value of a Font object error flag

See vis_FontBegin()

void vis_FontSetObject(vis_Font *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

Set a pointer to an attribute object.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Font object.

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

    x=VGL_DRAWFUN            DrawFun object
 =VIS_VISCONTEXT         VisContext object
 =VIS_COLORMAP           ColorMap object
 =VIS_TRANSMAP           TransMap object

  • object – Pointer to the object to be set.

void vis_FontSetPlane(vis_Font *p, Vfloat path[3], Vfloat plane[3])

set font orientation

Set font orientation plane. The path and plane vectors need not be normalized or orthogonal but they can not be parallel. The font orientation plane is formed as the plane defined by the path and plane vectors. Text is drawn at a specified anchor point using vis_FontText(). The text is drawn in a plane passing through the anchor point parallel to the orientation plane. By default the path vector is (1.,0.,0.) and the plane vector is (0.,1.,0.).

Get path and plane as output arguments using 

void vis_FontGetPlane (vis_Font *font,
                       Vfloat path[3],
                       Vfloat plane[3])

Errors

VIS_ERROR_COMPUTE is generated if path and plane do not define a unique orientation plane.

Parameters:

  • p – Pointer to Font object.

  • path – Vector in direction of font path.

  • plane – Vector in direction of font plane.

void vis_FontSetParamf(vis_Font *p, Vint rtype, Vfloat fparam)

set font display parameters

Set font rotation angle. The rotation angle is in the character plane and provides a convenient means of rotating the character direction without changing the overall orientation. The text is rotated about the anchor point input using vis_FontText(). By default FONT_ANGLE is set to 0.

Set text string direction relative to font path. By default FONT_DIRECTION is set to VIS_RIGHT.

Set font expansion factor. The expansion factor scales the width of each character such that the character height to width aspect ratio is changed. An expansion factor less then unity contracts the width of a character, a factor greater than unity increases the width. The expansion factor also applies to the amount of space between characters. By default FONT_EXPANSION is set to 1.

Set the distance that stroked text characters are to be extruded. The extrusion distance is normal to the font plane. Font extrusion results in a shaded 3D text string. By default FONT_EXTRUSION is set to 0.

Set the slant of stroked text characters. A slant of unity results in characters italicized at a 45 degree angle. A slant of zero results in no slant. By default FONT_SLANT is set to 0.

Set the spacing of stroked text characters. The character spacing inserts additional space between characters within a text string without changing the character size. By default FONT_SPACING is set to 0.

Errors

  • VIS_ERROR_ENUM is generated if an improper rtype is specified.

  • VIS_ERROR_ENUM is generated if an improper FONT_DIRECTION parameter

Parameters:

  • p – Pointer to Font object.

  • rtype – Type of display parameter to set 

    x=FONT_ANGLE              Set text string rotation angle
 =FONT_DIRECTION          Set text string direction
 =FONT_EXPANSION          Set text string expansion factor
 =FONT_EXTRUSION          Set text string extrusion distance
 =FONT_SLANT              Set font character slant
 =FONT_SPACING            Set font character spacing

  • fparam – Specifies the integer value that rtype will be set to. 

    x=VIS_LEFT                Direction to left
 =VIS_RIGHT               Direction to right
 =VIS_TOP                 Direction to top
 =VIS_BOTTOM              Direction to bottom

void vis_FontSetParami(vis_Font *p, Vint type, Vint iparam)

set font display parameters

See vis_FontSetParamf()

void vis_FontGetPlane(vis_Font *p, Vfloat path[3], Vfloat plane[3])

get font orientation

See vis_FontSetPlane()

void vis_FontLoad(vis_Font *p, Vint ifont)

read a font description file

Load a built-in stroked font description. Since all the available fonts are memory resident, font loading is not a time consuming operation.

Errors

VIS_ERROR_ENUM is generated if an improper ifont is specified.

Parameters:

  • p – Pointer to Font object.

  • ifont – Stroked font type to load 

    x=FONT_STANDARD          Default fixed width font
 =FONT_GREEK             Greek letters
 =FONT_ITALICS           Italics
 =FONT_ROMAN1            Roman
 =FONT_ROMAN2            Roman
 =FONT_BOLDSCRIPT        Bold script
 =FONT_FILLROMAN1        Outlined roman
 =FONT_FILLROMAN2        Outlined roman
 =FONT_GOTHIC            Gothic
 =FONT_SCRIPT            Script
 =FONT_UNCIAL            Interesting

void vis_FontText(vis_Font *p, Vfloat x[3], const Vchar *string)

draw font text string

Draw a text string anchored at x.

Parameters:

  • p – Pointer to Font object.

  • x – Anchor point of text string

  • string – Text string

void vis_FontLength(vis_Font *p, const Vchar *text, Vfloat *length)

compute length of text string

Compute the length of a text string.

Parameters:

  • p – Pointer to Font object.

  • text – Text string

  • length – [out] Length of text string

9.13. Markers and Glyphs - Glyph

Use Glyph to generate a variety of 2D and 3D icons from simple filled rectangles to 3D ellipsoids. Glyph objects are used extensively by other modules in VisTools to draw markers, cylindrical line styles, etc. Glyph visualization entities are not subject to isosurface clipping. The functions associated with a Glyph object are the following.

Instance a Glyph object using vis_GlyphBegin(). Once a Glyph object is instanced, set the attribute objects using vis_GlyphSetObject(). All glyphs are oriented to a direction cosine matrix in 3D space. By default the direction cosine matrix is aligned with the global coordinate system. Use vis_GlyphSetOrientTriad(), vis_GlyphSetOrientZ() or vis_GlyphSetOrientXY() to set the current orientation.

The following convention for the direction cosine matrices of a local coordinate system is used. 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

where y’x, for example, is the global x coordinate of the y’ unit vector.

9.14. Segmented Glyphs

The segmented glyphs are explicitly designed to facilitate drawing the segmented analytic surface types defined by the ABAQUS finite element program. The ASurf object contains the analytic surface types. The segment types include a line, circular arc and parabolic line. All segmented glyph functions contain a glyph origin, segment type and 2 or 3 local coordinate pairs depending upon the segment type. The local coordinates are in the glyph local system and are in either the local x,y or local x,z depending on the type of glyph to be drawn. Segment types are as follows. The order of the points is exactly as they are ordered using ASurf query functions.

  • GLYPH_SEG_LINE, is a 2 point line.

  • GLYPH_SEG_ARC, is a 3 point circular arc. First endpoint, center point, last endpoint. The arc is drawn between the endpoints with the smallest angle.

  • GLYPH_SEG_PARAB, is a parabolic line defined by 3 points. First endpoint, midpoint, last endpoint.

Segments may be drawn as lines in the local x,y plane passing through the spcecified origin using vis_GlyphSegment(), extruded as a ruled surface along the local z axis using vis_GlyphSegmentRule() or revolved around the local z axis using vis_GlyphSegmentRev().

9.15. Attribute Objects

A Glyph object uses DrawFun, VisContext, ColorMap and TransMap objects to define attributes to generate a glyph visualization entity. A DrawFun object is required but VisContext, ColorMap and TransMap objects are optional. A Glyph object uses the following VisContext components.

Color

Glyph color

LineWidth

Line width of glyph line primitives

LineStyle

Line style of glyph line primitives

Refinement

Level of refinement for drawing curved lines and surfaces. As a
general rule a value of 0 draws curves with 8 subdivisions. A
value of 1 or greater uses 16 subdivisions. A value less than
zero uses 4 subdivisions.

Shade

Flag to apply light source shading

Transparency

Transparency of glyph polygon primitives

If the VisContext attribute object pointer is NULL, then stroked glyphs are generated without referencing the VisContext, ColorMap and TransMap objects. No attribute drawing functions are invoked, all glyphs are drawn with line and flat shaded polygon graphics primitives assuming the current color, line width, line style and transparency. Zero level refinement is assumed.

9.16. Function Descriptions

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

vis_Glyph *vis_GlyphBegin(void)

create an instance of a Glyph object

Create an instance of a Glyph 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. Glyph orientation is along the global coordinate axes. Refinement is zero level.

Destroy an instance of a Glyph object using 

void vis_GlyphEnd (vis_Glyph *glyph)

Return the current value of a Glyph object error flag using 

Vint vis_GlyphError (vis_Glyph *glyph)

Returns:

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

void vis_GlyphEnd(vis_Glyph *p)

destroy an instance of a Glyph object

See vis_GlyphBegin()

Vint vis_GlyphError(vis_Glyph *p)

return the current value of a Glyph object error flag

See vis_GlyphBegin()

void vis_GlyphSetObject(vis_Glyph *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

Set a pointer to an attribute object.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Glyph object.

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

  • object – Pointer to the object to be set.

void vis_GlyphSetOrientXY(vis_Glyph *p, Vfloat vx[3], Vfloat vy[3])

set glyph orientation in x,y directions

Set glyph orientation x and y axes. The input vectors, vx and vy, need not be unit vectors or perpendicular. The local x axis lies along vx, the local y axis is perpendicular to x lying in the plane defined by vx and vy, the local z axis is constructed to be perpendicular to the x and y axes.

Parameters:

  • p – Pointer to Glyph object.

  • vx – Vector of local x axis.

  • vy – Vector defining the half plane of the local y axis.

void vis_GlyphSetOrientZ(vis_Glyph *p, Vfloat vz[3])

set glyph orientation in z direction

Set glyph orientation z axis. The input vector, vz, need not be a unit vector. The local x and y axes are computed internally to be orthonormal to the z axis. This function is useful for orienting glyphs such as vectors which have symmetry about the z axis.

Parameters:

  • p – Pointer to Glyph object.

  • vz – Vector of local z axis.

void vis_GlyphSetOrientTriad(vis_Glyph *p, Vfloat tm[3][3])

set glyph orientation to global axes

Set glyph orientation to global axis.

Get tm as an output argument using 

void vis_GlyphGetOrientTriad (vis_Glyph *glyph,
                              Vfloat tm[3][3])

Parameters:

  • p – Pointer to Glyph object.

  • tm – Direction cosine matrix of glyph orientation.

void vis_GlyphGetOrientTriad(vis_Glyph *p, Vfloat tm[3][3])

get glyph orientation to global axes

See vis_GlyphSetOrientTriad()

void vis_GlyphSphere(vis_Glyph *p, Vfloat x[3], Vfloat r, Vint fill)

draw a sphere

Draw a sphere centered at x with radius r.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of center of sphere

  • r – Radius of sphere

  • fill – Fill flag 

    =VIS_OFF      Do not fill
=VIS_ON       Fill

void vis_GlyphCircle(vis_Glyph *p, Vfloat x[3], Vfloat r, Vfloat off, Vint fill)

draw a circle in a plane

Draw a circle in the x,y plane centered at x. The circle may be optionally filled.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of centroid of circle

  • r – Radius of circle

  • off – Offset of circle center along z axis.

  • fill – Fill flag 

    =VIS_OFF      Do not fill
=VIS_ON       Fill

void vis_GlyphDisk(vis_Glyph *p, Vfloat x[3], Vfloat r, Vfloat h, Vfloat off, Vint fill)

draw disk

Draw a disk with the center of the base of the disk anchored at x and aligned so that the height direction is along the z axis of the orientation triad. This primitive is much like vis_GlyphCylinder() except that the ends are capped.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of base of disk

  • r – Radius of disk

  • h – Height of disk

  • off – Offset of disk base along z axis.

  • fill – Fill flag 

    =VIS_OFF      Do not fill
=VIS_ON       Fill

void vis_GlyphCone(vis_Glyph *p, Vfloat x[3], Vfloat r, Vfloat h, Vfloat off, Vint fill)

draw a cone

Draw a cone with the center of the base anchored at x and aligned so that the height direction is along the z axis of the orientation triad.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of base of cone

  • r – Radius of base of cone

  • h – Height of cone

  • off – Offset of cone base along z axis.

  • fill – Fill flag 

    =VIS_OFF      Do not fill
=VIS_ON       Fill

void vis_GlyphCylinder(vis_Glyph *p, Vfloat x[3], Vfloat r, Vfloat h, Vfloat off, Vint fill)

draw a cylinder

Draw a cylinder with the center of one end, the base, anchored at x and aligned so that the height direction is along the z axis of the orientation triad.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of base of cylinder

  • r – Radius of cylinder

  • h – Height of cylinder

  • off – Offset of cylinder base along z axis.

  • fill – Fill flag 

    =VIS_OFF      Do not fill
=VIS_ON       Fill box

void vis_GlyphConicalFrustum(vis_Glyph *p, Vfloat x[3], Vfloat r1, Vfloat r2, Vfloat h, Vfloat off, Vint fill)

draw a conical frustum

Draw a conical frustum with the base anchored at x and aligned so that the height direction is along the z axis of the orientation triad.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of base of conical frustum

  • r1 – Radius of base of conical frustum

  • r2 – Radius of top of conical frustum

  • h – Height of conical frustum

  • off – Offset of base of conical frustum along z axis.

  • fill – Fill flag 

    =VIS_OFF      Do not fill
=VIS_ON       Fill box

void vis_GlyphArrow2D(vis_Glyph *p, Vfloat x[3], Vfloat l, Vfloat r, Vfloat h, Vfloat off, Vint head, Vint tail, Vint fill, Vint push, Vint cap)

draw arrows

Draw arrows. The tip of the head of the arrow is anchored at x. Arrows are oriented along the z axis of the orientation triad. 2D arrows are drawn with a planar head and a simple line tail. The head is drawn in the x,z plane defined by the orientation triad. 2D, 3D mixed arrows are drawn with a 3D conical head and a simple line tail. If the refinement for a mixed 2D, 3D arrow is -1 then the head is drawn as a tetrahedron. 3D arrows are drawn with cylindrical shafts and conical heads.

If an offset, off, is specified then the anchor point is moved a distance off along the shaft of the arrow from the arrow tip. Double headed arrows may be generated by setting head = 2. Arrows are oriented along the z axis of the orientation triad. If the push flag is set, the arrow head is drawn to appear to “push” the vector tail.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of tip of arrow.

  • l – Length of arrow

  • r – Radius of head of arrow

  • h – Height of head of arrow

  • off – Offset of arrow tip from x along z axis

  • head – Number of arrow heads.

  • tail – Arrow tail flag 

    =VIS_OFF      Do not display tail
=VIS_ON       Display tail

  • fill – Arrow head fill flag 

    =VIS_OFF      Do not fill arrow head
=VIS_ON       Fill arrow head

  • push – Arrow head push flag 

    =VIS_OFF      Do not draw arrow head in push style
=VIS_ON       Draw arrow head in push style

  • cap – Arrow head cap flag 

    =VIS_OFF      Do not cap arrow head
=VIS_ON       Cap arrow head

void vis_GlyphArrow2D3D(vis_Glyph *p, Vfloat x[3], Vfloat l, Vfloat r, Vfloat h, Vfloat off, Vint head, Vint tail, Vint fill, Vint push, Vint cap)

draw arrows

See vis_GlyphArrow2D()

void vis_GlyphArrow3D(vis_Glyph *p, Vfloat x[3], Vfloat l, Vfloat r, Vfloat h, Vfloat off, Vint head, Vint tail, Vint fill, Vint push, Vint cap)

draw arrows

See vis_GlyphArrow2D()

void vis_GlyphBox(vis_Glyph *p, Vfloat x[3], Vfloat sx, Vfloat sy, Vfloat sz, Vint fill)

draw a box

Draw a box in space centered at x. The box may be optionally filled.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of centroid of box

  • sx – Length in x direction

  • sy – Length in y direction

  • sz – Length in z direction

  • fill – Fill flag 

    =VIS_OFF      Do not fill
=VIS_ON       Fill box

void vis_GlyphEllipsoid(vis_Glyph *p, Vfloat x[3], Vfloat sx, Vfloat sy, Vfloat sz)

draw an ellipsoid

Draw an ellipse centered at x. The ellipse is drawn with filled polygons.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of centroid of ellipse

  • sx – Length in x direction

  • sy – Length in y direction

  • sz – Length in z direction

void vis_GlyphRectangle(vis_Glyph *p, Vfloat x[3], Vfloat w, Vfloat h, Vfloat off, Vint fill)

draw a rectangle

Draw a rectangle centered at x. The rectangle is oriented in the x,y plane, the width is in the x direction and the height is in the y direction. The rectangle may be drawn either as an outlined or a filled rectangle.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of center of rectangle

  • w – Width of rectangle

  • h – Height of rectangle

  • off – Offset of rectangle along z axis.

  • fill – Fill flag 

    =VIS_OFF      Do not fill
=VIS_ON       Fill

void vis_GlyphSegment(vis_Glyph *p, Vfloat x[3], Vint type, Vfloat xy[][2])

draw line segments

Draw various line segments. The segment local coordinates are in the x,y plane of the glyph orientation with origin at x.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of segment local system origin.

  • type – Segment type 

    x=GLYPH_SEG_LINE         Line segment
 =GLYPH_SEG_ARC          Circlar arc segment
 =GLYPH_SEG_PARAB        Parabolic line segment

  • xy – Segment local coordinates.

void vis_GlyphSegmentRule(vis_Glyph *p, Vfloat x[3], Vfloat dp, Vfloat dn, Vint type, Vfloat xy[][2])

draw ruled segments

Draw various ruled line segments. The segment local coordinates are in the x,y plane of the glyph orientation with origin at x. The segment is ruled by distances dp and dn along the glyph z orientation. The output graphics primitives always contain vertex normals.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of segment local system origin.

  • dp – Distance in the positive z local direction.

  • dn – Distance in the negative z local direction.

  • type – Segment type 

    x=GLYPH_SEG_LINE         Line segment
 =GLYPH_SEG_ARC          Circlar arc segment
 =GLYPH_SEG_PARAB        Parabolic line segment

  • xy – Segment local coordinates.

void vis_GlyphSegmentRev(vis_Glyph *p, Vfloat x[3], Vfloat angle, Vint type, Vfloat xy[][2])

draw revolved segments

Draw various revolved line segments. The segment local coordinates are in the x,z plane of the glyph orientation with origin at x. The segment is revolved by angle angle about the z orientation with the angle origin along the local x axis. The output graphics primitives always contain vertex normals.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of segment local system origin.

  • angle – Angle in degrees to revolve about the local z axis.

  • type – Segment type 

    x=GLYPH_SEG_LINE         Line segment
 =GLYPH_SEG_ARC          Circlar arc segment
 =GLYPH_SEG_PARAB        Parabolic line segment

  • xy – Segment local coordinates.

void vis_GlyphTriaxis(vis_Glyph *p, Vfloat x[3], Vfloat sx, Vfloat sy, Vfloat sz, Vfloat off)

draw triaxis

Draw a triaxis centered at x. A triaxis consists of 3 axes, represented as lines, drawn along the x, y and z directions. The lengths of the axes in each direction are given by sx, sy and sz respectively. If an axis length is input as zero it is not drawn.

Parameters:

  • p – Pointer to Glyph object.

  • x – Coordinate location of center of triaxis

  • sx – Axis length in x direction

  • sy – Axis length in y direction

  • sz – Axis length in z direction

  • off – Offset of triaxis along z axis.

9.17. Tesselation Tools - Tess

Use Tess to draw a tesselation of a two-dimensional region delineated by possibly overlapping arcs and segments. Arcs are first tesselated into segments whose size is controlled by VisContextSetSizeType prior to generating a tesselation of the area. The functions associated with a Tess object are the following.

Instance a Tess object using vis_TessBegin(). Once a Tess object is instanced, set the attribute objects using vis_TessSetObject(), and the drawing parameters with either vis_TessSetParami() and vis_TessSetParamd(). Use vis_TessDef() to indicate the creating of a new region. Points are added with vis_TessSetPoint(), straight lines with vis_TessSetLine(), and arcs with vis_TessSetArc(). All lines and arcs are oriented such that if one defines a local x direction as going from the first to the second point on the curve, and with the z direction going towards the observer, then the region of interest is in the local y direction.

Arcs are tesselated into segments whose size can be defined either in world or in device coordinates. The size type is set in the VisContext object using VisContextSetSizeType.

All input points, lines and arcs are tested for intersection. The intersection tolerance is specified using vis_TessSetParamd() with parameter TESS_INTERTOL. Lines and arcs are divided and points are inserted where intersections occur. Coincident points are merged. Unconnected points are tested for intersection with lines and arcs. All points are included in the final tessellation.

All point locations are 3D world coordinates. All intersection and tesselation calculations are performed in a plane specified by a normal vector input using vis_TessSetNormal(). By default the normal is a vector pointing in the positive z-coordinate direction.

The function vis_TessDraw() performs the actual tesselation of the input geometry. This operation is subject to failure if the input geometry is not closed or there are very small features. Use vis_TessGetInteger() to query for tesselation information to see if a subsequent vis_TessDraw() operation was successful. The function vis_TessWrite() is provided to write a complete description of the defined input geometry to a file. The primary use of this file is to encapsulate cases in which the Tess module fails in some respect. This output file can then be made available to Tech Soft 3D for failure diagnosis of Tess tesselation algorithms.

9.18. Attribute Objects

A Tess object uses DrawFun, VisContext, ColorMap and TransMap objects to define attributes to generate a tesselation visualization entity. DrawFun and VisContext objects are required but ColorMap and TransMap objects are optional. A Tess object uses the following VisContext components.

Color

Polygon color

DeviceSize

Length of arc segment in device coordinates.

MinorColor

Edge color

LineWidth

Line width of line primitives

LineStyle

Line style of line primitives

Fill

Polygon display flag

Edge

Polygon edge display flag

ProjMatrix

Projection matrix, used with device sizing

Size

Length of arc segment 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

Trans

Transparency flag

If the ColorMap attribute object pointer is NULL, then it is assumed that vgl_DrawFunColor() has been called prior to vis_TessDraw().

9.19. Function Descriptions

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

vis_Tess *vis_TessBegin(void)

create an instance of a Tess object

Create an instance of a Tess 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 Tess object using 

void vis_TessEnd (vis_Tess *tess)

Return the current value of a Tess object error flag using 

Vint vis_TessError (vis_Tess *tess)

Returns:

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

void vis_TessEnd(vis_Tess *p)

destroy an instance of a Tess object

See vis_TessBegin()

Vint vis_TessError(vis_Tess *p)

return the current value of a Tess object error flag

See vis_TessBegin()

void vis_TessDef(vis_Tess *p, Vint npts, Vint nlines)

clear object and set new initial parameters

Use TessDef to clear an existing Tess module of its contents and to define initial parameters for a new tesselation. npts and nlines are estimates for the number of points and lines to be set. These values can be exceeded with SetPoint, SetLine, and SetArc.

Parameters:

  • p – Pointer to Tess object.

  • npts – Initial value for number of points

  • nlines – Initial value for number of lines and arcs

void vis_TessSetParamd(vis_Tess *p, Vint type, Vdouble paramd)

set tesselation double precision parameters.

Set tesselation floating point controlling parameters.

Use TESS_INTERTOL to specify the tolerance used to compute intersections of lines and arcs. Defaults to 2.e-7.

Errors

VIS_ERROR_ENUM is generated if an improper type is specified.

Parameters:

  • p – Pointer to Tess object.

  • type – Parameter type 

    x=TESS_INTERTOL          Tolerance for curve intersection

  • paramd – Parameter value

void vis_TessSetParami(vis_Tess *p, Vint type, Vint parami)

set tesselation integer parameters.

The parameter TESS_EDGE controls which edges are displayed if the Edge parameter in VisContext is turned on. TESS_EDGE_ALL displays all generated edges; TESS_EDGE_BOUND displays all geometry-related edges. These include the original line segments, as well as the tesselation of arcs. TESS_EDGE_OUTLINE displays edges that are present in only a single polygon and delineate the region of interest from empty space; and TESS_EDGE_INPUT displays the original input curves. In this case, arcs are displayed as two segments, as arcs are defined through three points. TESS_EDGE_DANGLING draws only those edges which are not on or in the interior of a closed loop of line segments. By Default TESS_EDGE is set to TESS_EDGE_OUTLINE.

Errors

VIS_ERROR_ENUM is generated if either an improper type or an improper parami are specified.

Parameters:

  • p – Pointer to Tess object.

  • type – Parameter type 

    x=TESS_EDGE              Type of edge to be drawn

  • parami – Parameter value 

    x=TESS_EDGE_ALL          Display all generated edges
 =TESS_EDGE_BOUND        Display all tesselated boundaries
 =TESS_EDGE_INPUT        Display the input curves
 =TESS_EDGE_DANGLING     Display dangling edges only
 =TESS_EDGE_OUTLINE      Display only the region's outline

void vis_TessSetObject(vis_Tess *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

Set a pointer to an attribute object.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Tess object.

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

    x=VGL_DRAWFUN            DrawFun object
 =VIS_VISCONTEXT         VisContext object
 =VIS_COLORMAP           ColorMap object
 =VIS_TRANSMAP           TransMap object

  • object – Pointer to the object to be set.

void vis_TessGetInteger(vis_Tess *p, Vint type, Vint iparams[])

get integer tesselation information

Query for integer tesselation information. If the number of unrecovered edges is non-zero, then the input geometry has a set of very small features which cause a numerical problem. If the number of drawn triangles is zero, then the input geometry is not closed.

Errors

VIS_ERROR_ENUM is generated if an improper type is specified.

Parameters:

  • p – Pointer to Tess object.

  • type – Type of integer information to query 

    x=TESS_NUMUNREC          Number of unrecovered edges
 =TESS_NUMDRAWTRI        Number of triangles drawn
 =TESS_NUMDRAWEDGE       Number of edges drawn

  • iparams – [out] Returned integer information

void vis_TessSetPointdv(vis_Tess *p, Vint id, Vdouble x[3])

draw a cone

Specifies a point to be used by lines and arcs.

Parameters:

  • p – Pointer to Tess object.

  • id – Point id

  • x – Point coordinates.

void vis_TessSetPoint(vis_Tess *p, Vint id, Vfloat x[3])

draw a cone

Specifies a point to be used by lines and arcs.

Parameters:

  • p – Pointer to Tess object.

  • id – Point id

  • x – Point coordinates.

void vis_TessSetLine(vis_Tess *p, Vint id, Vint ix[2])

input a straight line

Specifies a straight segment for the tesselation. Lines and arcs share the same id space.

Parameters:

  • p – Pointer to Tess object.

  • id – Line id

  • ix – Array with the line’s two end points.

void vis_TessSetArc(vis_Tess *p, Vint id, Vint ix[3])

input an arc

Specifies an arc defined by three consecutive points along the arc. The arc is defined from the first point to the third point, passing through the second point. The final tesselation will always contain these three points. Lines and arcs share the same id space.

Parameters:

  • p – Pointer to Tess object.

  • id – Arc id

  • ix – Array with 3 points defining the arc

void vis_TessWrite(vis_Tess *p, Vint type, const Vchar file[])

write input geometry to file

Write a geometry description to a file. The contents of the file is intended for internal use only. This function should be called immediately before vis_TessDraw(). This file can then be transmitted to Visual Kinematics for debugging purposes. It is suggested that a file extension of .tes be used for ASCII files and .btes be used for BINARY files.

Errors

  • SYS_ERROR_ENUM is generated if an improper type is specified.

  • SYS_ERROR_FILE is generated if the file can not be opened.

  • SYS_ERROR_OPERATION is generated if the input surface has not been defined.

Parameters:

  • p – Pointer to Tess object.

  • type – File type 

    x=SYS_ASCII              ASCII format
 =SYS_BINARY             Binary format

  • file – File path

void vis_TessRead(vis_Tess *p, Vint type, const Vchar path[])

read input geometry from file

Read a geometry description from a file which has been previously written by vis_TessWrite(). The format of the file is not published and is intended for internal use only.

Errors

  • SYS_ERROR_ENUM is generated if an improper type is specified.

  • SYS_ERROR_FILE is generated if the file can not be opened.

  • SYS_ERROR_FORMAT is generated if the file contents are not correctly formatted.

Parameters:

  • p – Pointer to Tess object.

  • type – File type 

    x=SYS_ASCII              ASCII format
 =SYS_BINARY             Binary format

  • path – File path

void vis_TessSetNormal(vis_Tess *p, Vfloat v[])

set normal to tesselation plane

Specifies a point to be used by lines and arcs.

Parameters:

  • p – Pointer to Tess object.

  • v – Normal vector to tesselation plane

void vis_TessSetNormaldv(vis_Tess *p, Vdouble vn[])

set normal to tesselation plane

Specifies a point to be used by lines and arcs.

Parameters:

  • p – Pointer to Tess object.

  • vn – Normal vector to tesselation plane

void vis_TessDraw(vis_Tess *p)

draw a tesselation

Draw a tesselation using the geometry defined by points, lines, and arcs. Use vis_TessGetInteger() to test for any failures to generate graphics primitives from the input geometry.

Errors

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

Parameters:

p – Pointer to Tess object.

9.20. Coordinate System Triads - Triad

The Triad module is designed to draw Cartesian, cylindrical, spherical and toroidal coordinate system icons. The CoordSys object contains coordinate system definitions. A coordinate system icon consists of three orthogonal vectors representing the orientation of the coordinate system. As an option, additional details may be drawn to illustrate the shape of the coordinate system or the radius and angle conventions of cylindrical, spherical and toroidal systems. All labelling is optional and may be performed using stroke or raster fonts. The methods associated with a Triad object are the following.

Instance a Triad object using vis_TriadBegin(). Once a Triad object is instanced, set the attribute objects using vis_TriadSetObject() and set display parameters using vis_TriadSetParami(). The triad icon is drawn using vis_TriadDraw().

Coordinate systems are drawn given an origin and orientation relative to the world coordinate system. The orientation is specified by a direction cosine matrix which defines a local x’,y’,z’ rectangular system in world coordinate space. The coordinate system to be drawn by Triad is aligned to the x’,y’,z’ system. A Cartesian system is a rectangular coordinate system characterized by coordinates x’,y’,z’. A cylindrical system is characterized by coordinates r,theta,z’ where theta is the angle about the z’ axis (positive x’ toward positive y’). An alternate definition of a cylindrical system is available in which theta is the angle about the z’ axis (positive y’ toward positive x’). A spherical system is characterized by coordinates r,theta,phi where theta is the angle about the z’ axis (positive x’ toward positive y’) and phi is the angle about the x’ axis (positive y’ toward positive z’). An alternate definition of a spherical system is available (for specific support of NASTRAN spherical coordinate systems) in which theta is the angle about the negative x’ axis (positive z’ toward positive y’) and phi is the angle about the z’ axis (positive x’ toward positive y’). A toroidal system is characterized by the radius of the torus and coordinates r,theta,phi where theta is the angle about the z’ axis (positive x’ toward positive y’) and phi is the angle about the x’ axis (positive y’ toward positive z’).

The triad display is parameterized in part by the parameters set using vis_TriadSetParami(). The basic triad icon consists of three orthogonal vectors showing the orientation axes of the coordinate system. The axes are labeled with X,Y,Z, R,T,Z or R,T,P depending upon whether the coordinate system is Cartesian, cylindrical, spherical or toroidal.

The radius and angle conventions of cylindrical, spherical and toroidal systems may be displayed by setting the parameter TRIAD_DETAIL on. If detail is on, then the orientation axes are labeled as X,Y,Z regardless of coordinate system type. In addition a portion of a filled box, cylinder or sphere may be drawn in the first octant of the triad if TRIAD_SHAPE is set on.

The use of a stroked font as opposed to a raster font for drawing labels may be toggled on or off using the parameter TRIAD_STROKEFONT. The display of labels may be toggled on or off using the parameter TRIAD_LABELS.

The result of drawing triads in various styles are illustrated in Figures 9-5.

../../_images/vistools-anno5a.gif

Figure 9-5a, Basic Triads

../../_images/vistools-anno5b.gif

Figure 9-5b, Triads with Detail and Stroked Font

../../_images/vistools-anno5c.gif

Figure 9-5c, Triads with Detail, Shape and Raster Font

9.21. Attribute Objects

A Triad object uses a DrawFun, ColorMap, TransMap and VisContext objects to define attributes required to generate a triad icon. All attribute objects are set using vis_TriadSetObject(). The ColorMap object is required to define all colors used to draw the triad. The TransMap object is optional and is used only for drawing the triad shape with transparency.

The VisContext attribute object is required for all drawing. The following VisContext components are used.

AColor

Color of X (or R) orientation vector label.

BColor

Color of Y (or T) orientation vector label.

CColor

Color of Z (or P) orientation vector label.

Color

Color of detail labels.

Flags

OR the following flags: VIS_VECTORNOHEAD inhibits the drawing of
the head of the orientation axes vectors.

LineStyle

Line style of line drawn vectors.

LineWidth

Line width of line drawn vectors.

MinorColor

Color of detail axes and shape.

MinorLineStyle

Line style of detail axes.

MinorLineWidth

Line width of detail axes.

MinorSize

Size of detail axes and shape.

Size

Size of orientation vector axes.

Trans

Transparency of filled shape.

XColor

Color of X (or R) orientation vector axis.

YColor

Color of Y (or T) orientation vector axis.

ZColor

Color of Z (or P) orientation vector axis.

The Triad object calls the following drawing functions set in the DrawFun attribute object.

Color
ColorIndex

Only if ColorMap object type is COLORMAP_PSEUDOCOLOR.

LineStyle
LineWidth
Polygon
PolyLine
PolyPointDC

Only if raster font labels are drawn

Text

Only if raster font labels are drawn

Trans
TransIndex

Only if TransMap object type is TRANSMAP_INDEX.

9.22. Function Descriptions

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

vis_Triad *vis_TriadBegin(void)

create an instance of a Triad object

Create an instance of a Triad 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, Detail display is off, label drawing is on, shape display is off and stroked fonts are off.

Destroy an instance of a Triad object using 

void vis_TriadEnd (vis_Triad *triad)

Return the current value of a Triad object error flag using 

Vint vis_TriadError (vis_Triad *triad)

Returns:

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

void vis_TriadEnd(vis_Triad *p)

destroy an instance of a Triad object

See vis_TriadBegin()

Vint vis_TriadError(vis_Triad *p)

return the current value of a Triad object error flag

See vis_TriadBegin()

void vis_TriadSetObject(vis_Triad *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

Set a pointer to an attribute object.

Get object as an output argument using 

void vis_TriadGetObject (vis_Triad *triad,
                         Vint objecttype,
                         Vobject **object)

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters:

  • p – Pointer to Triad object.

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

    x=VGL_DRAWFUN            DrawFun object
 =VIS_COLORMAP           ColorMap object
 =VIS_TRANSMAP           TransMap object
 =VIS_VISCONTEXT         VisContext object

  • object – Pointer to the object to be set.

void vis_TriadSetParami(vis_Triad *p, Vint type, Vint iparam)

set display parameters

Toggle the display of coordinate system detail which illustrates the radius and angle conventions of cylindrical, spherical and toroidal coordinate system. By default TRIAD_DETAIL is set to VIS_OFF.

Toggle the display of all labels. By default TRIAD_LABELS is set to VIS_ON.

Toggle the display of coordinate system shape. The shape consists of a portion of a filled box, cylinder, sphere or torus drawn in the first octant of the triad for Cartesian, cylindrical, spherical or toroidal systems respectively. An additional condition for shape drawing is TRIAD_DETAIL must be on. By default TRIAD_SHAPE is set to VIS_OFF.

Toggle the use of a stroked font as opposed to a raster font for drawing labels. By default TRIAD_STROKEFONT is set to VIS_OFF.

Errors

VIS_ERROR_ENUM is generated if an improper type is specified.

Parameters:

  • p – Pointer to Triad object.

  • type – Type of display parameter to set 

    x=TRIAD_DETAIL            Toggle display of detail showing
                          radius and angle conventions.
 =TRIAD_LABELS            Toggle display of all labels.
 =TRIAD_SHAPE             Toggle display of filled shape
 =TRIAD_STROKEFONT        Toggle use of stroked font labels.

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

    x=VIS_ON                  Enable
 =VIS_OFF                 Disable

void vis_TriadDraw(vis_Triad *p, Vint type, Vfloat x[3], Vfloat tm[3][3])

draw a coordinate system triad

Draw a triad representing a coordinate system of type, with the origin at x and orientation tm.

Errors

  • VIS_ERROR_ENUM is generated if an improper type is specified.

  • VIS_ERROR_NULLOBJECT is generated if DrawFun, ColorMap and VisContext attribute objects are not set.

Parameters:

  • p – Pointer to Triad object.

  • type – Coordinate system type. 

    x=SYS_CARTESIAN          Cartesian system
 =SYS_CYLINDRICAL        Cylindrical system
 =SYS_CYLINDRICAL_ALT    Cylindrical alternate system
 =SYS_SPHERICAL          Spherical system
 =SYS_SPHERICAL_ALT      Spherical alternate system
 =SYS_TOROIDAL           Toroidal system

  • x – Origin of triad icon.

  • tm – Direction cosine matrix of triad orientation.