# 1. Introduction

The VisTools library from Visual Kinematics, Inc. is now part of the Tech Soft 3D portfolio. It is an object-based software development toolkit designed for use in creating visualization applications for science and engineering. As a visualization toolkit, VisTools is differentiated by its rich feature set, computational efficiency and modular, object-based architecture. VisTools is designed to impose few restrictions on the nature of the computational domain, or specific data structures used within a host application to maintain the computational grid and/or solution results. VisTools also separates the generation of visualization entities from the graphics subsystem. This allows application developers to integrate VisTools between their existing computational database and graphics device interface. The basic features of VisTools are summarized below:

Discrete scalar, vector or tensor field visualization as 2D or 3D icons or numerical values.

Isovalue display in 1D, 2D and 3D domains. This includes contour line, color filled contour, continuous tone, isosurface, vector surface, dot surface and cuberille generation.

Perform line, surface and volume integrations associated with the isovalue visualization modules. For example, VisTools is able to compute the area of an isosurface or the volume of material lying between sets of isosurfaces.

Unique isosurface clipping feature. Any type of visualization entity may be clipped to a set of arbitrary isosurfaces.

Streamline and streamribbon generation in 2D and 3D domains. Streamlines may be constrained to lie on a surface in 3D domains. Tangent curves may be produced in vector (velocity) or tensor (stress) fields.

All discrete visualization entities may be value mapped to size and/or color. All filled entities (eg. isosurfaces, color filled contours) may be value mapped to color and/or transparency.

Computational cells may be individual lines, triangles, quadrilaterals, tetrahedra, pyramids, pentahedra or hexahedra or regular meshes of the same cell type. General polygons and polyhedra are also supported. This allows VisTools to be applied to conventional finite element unstructured grids, polyhedral grids or higher order, p-element finite element grids and multiblock structured grids.

Normal vectors may be either automatically generated by VisTools or supplied by the user for light source shading. Both facet and vertex normals are supported.

Annotation features include 2D and 3D stroked fonts and an extensive glyph library of useful 2D and 3D parameterized shapes. Facilities for generating XY and XYZ graphs and drawing triads for Cartesian, cylindrical or spherical systems are included.

Automatic calculation of beam section properties for arbitrary cross sections. Automatic calculation of shell wall composite stiffness matrix for arbitrary laminated composites.

Object-based architecture, written in ANSI C with C++, FORTRAN, and C# language bindings.

Hardware and graphics device independence.

## 1.1. Module Summary

VisTools is designed to accept computational cells (eg. individual finite elements or blocks of a multiblock grid) and results data (eg. scalar, vector or tensor fields), perform a visualization function (eg. isosurface extraction or tensor icon generation) and produce displayable geometry (eg. colors, polylines and polygons). VisTools is meant to be integrated into existing visualization software systems such as finite element post processors and visual data analysis (VDA) systems with minimal impact upon established data structures and graphics subsystems. The modules currently delivered with VisTools may be divided into 4 categories: 1) visualization and computation, 2) attribute, 3) annotation and 4) drawing function.

Visualization and Computation

Mark

Scalar, vector or tensor field markers at points.

Value

Scalar, vector or tensor field values at points.

Segment

Isovalues along lines.

Contour

Contours on surfaces.

Threshold

Isosurface extraction within solids

Trace

Tangent curve generation on surfaces

Stream

Tangent curve generation within solids

Edge

Draw wireframe geometries

Face

Draw shaded surface geometries

Cell

Draw shaded solid geometries

ShellWall

Compute and draw shell wall properties

ShellElem

Draw shell elements

BeamSect

Compute and draw beam section properties

BeamElem

Draw beam elements

RigidElem

Draw rigid elements

MassElem

Draw mass elements

DiscElem

Draw spring and dashpot elements

GapElem

Draw gap elements

Attribute

Levels

Define discrete quantity levels

ColorMap

Define quantity level mapping to color

TransMap

Define quantity level mapping to transparency

VisContext

Define visualization attributes

IsoClip

Define clipping isosurface

DataInt

Define data interpolation arrays

Annotation

Axis

Draw annotated axes

Billboard

Draw extensible 2D lists or billboards

Font

Draw stroked 2D and 3D text

Glyph

Draw 2D and 3D markers and glyphs

Legend

Draw color and/or transparency mapping legends

Triad

Draw coordinate system triads.

Manipulators

HandleBox

Rectilinear box

PolyBox

Planar polygon

WorkPlane

Work plane

Drawing Function

DrawFun

Define drawing function pointers to graphics subsystem

The visualization and manipulator modules are the heart of VisTools. All other modules function to provide services and information to the visualization modules. Each instance of a module in VisTools is termed an object. Specifically, each instance of a visualization module is termed a visualization object. A visualization entity is defined as the displayable output from a visualization object. Examples of visualization entities are contour lines, tensor icons, isosurfaces, etc. Visualization objects produce graphics primitives which directly affect geometry such as line widths, points, polylines and polygons.

The manipulator modules are used to manage various types of clipping, selection and snapping icons. These modules, in general, produce graphics primitive geometry as well as clipping and transformation primitives. The manipulator modules are controlled by user interaction. The modules do not perform any specific graphics device queries, the user is responsible for implementing the user interaction and supplying device coordinates and gesture manner (drag, click, etc.) to the modules.

The attribute modules do not produce displayable geometry as such but are used primarily to provide containers for attributes which affect the appearance of visualization entities. An instance of an attribute module is called an attribute object. Attribute objects produce color and transparency graphics primitives.

The drawing function modules are designed to receive the graphics primitives produced by the visualization and attribute modules. The most straight-forward use of the drawing functions is to interface VisTools modules directly to a graphics subsystem. This involves making direct calls to set colors, line styles, etc. and draw various flavors of points, lines and polygons using a 3D graphics application programming interface (API).

Drawing functions may be used to perform specialized processing such as integrating complicated functions over the polygons comprising an isosurface. Drawing functions may also be developed which feed back output primitives (and field values which have been interpolated to the vertices of output primitives) as input to a visualization object. This allows VisTools to be used recursively to generate such displays as contour plots on arbitrary isosurfaces or tensor icons along the clipped edge of the face of a finite element. The drawing function module, DrawFun, is formally part of the VglTools graphics interface library. This module is delivered with VisTools as a support module.

## 1.2. Computational Cells

VisTools accepts a set of computational cell types which encompasses
most topologies in general use in science and engineering. Basic cell
primitives, referred to as **shape**, include the following:

**SYS_SHAPEPOINT**, point(s)**SYS_SHAPELINE**, line**SYS_SHAPETRI**, triangle**SYS_SHAPEQUAD**, quadrilateral**SYS_SHAPETET**, tetrahedron**SYS_SHAPEPYR**, pyramid**SYS_SHAPEWED**, pentahedron**SYS_SHAPEHEX**, hexahedron**SYS_SHAPEPOLYGON**, polygon**SYS_SHAPEPOLYHED**, polyhedron

As mentioned earlier there are two distinct forms for each cell topology 1) Serendipity finite elements which are characterized by only having nodes along element edges and 2) Lagrange finite elements and regular arrays of primitive cells. Polygons and polyhedra are special cases to be described below. These two representations allow VisTools to efficiently process low order finite elements as well as higher order elements, p-elements and multi block structured grids. The node connectivity conventions for Serendipity finite elements and Lagrange finite elements and arrays are different. Serendipity element connectivity follows a convention often used in the finite element analysis industry in which corner nodes are numbered first followed by nodes along the midsides of the element edges. For parabolic and cubic Serendipity elements the corner nodes are followed by nodes on the boundary edges in edge number order. Lagrange finite element or array connectivity follows an ordering used universally for multidimension arrays. Nodes are ordered in the “i” direction first, the “j” direction second and the “k” direction last. The number of nodes in each element direction, (i,j,k) are referred to as maxi, maxj and maxk. For example, a 27 node parabolic Lagrange 3D hexahedral solid element has maxi = maxj = maxk = 3. The general rules concerning maxi, maxj and maxk are outlined in the following paragraphs, some uncommon special cases are described later.

Lagrange connectivity allows for different numbers of nodes in each element direction. For example, a special form of a Lagrange solid element to model thick shells may contain 18 nodes with parabolic shape functions in the plane of the shell (“i” and “j” directions) and linear functions through the thickness of the shell (“k” direction). In this case maxi = maxj = 3, and maxk = 2.

Serendipity elements must have equal orders in the “i” and “j” directions. The “k” direction may be either linear or equal to the order given to the “i” and “j” directions. Utilizing this fact, the Serendipity connectivity convention is flagged by setting maxj = 0 (except for the case of missing midside nodes described below). This specifies that the order in the “j” direction is equal to the order given by maxi and a Serendipity connectivity convention is being used. If maxk = 0, then the order in the “k” direction is equal to the order given by maxi. For example a 20 node parabolic Serendipity 3D hexahedral solid element has maxi = 3, and maxj = 0 and maxk = 0. Optionally, maxk = 2 specifies linear shape functions in the “k” direction. For example, a 16 node Serendipity thick shell solid has maxi = 3, maxj = 0 and maxk = 2.

Serendipity and Lagrange finite elements are restricted to linear, parabolic and cubic forms. The shape functions for these types are explicitly supported. Array form is numbered identically to Lagrange form but for maxi, maxj or maxk exceeding 4, piecewise linear shape functions are used.

The node connectivities for each topology appear below with examples of Serendipity element form and Lagrange element or array form. The maxi, maxj and maxk values associated with each form are shown. Line connectivities are characterized by (maxi), triangle and quadrilateral connectivities by (maxi, maxj) and tetrahedral, pyramidal, pentahedral and hexahedral connectivities by (maxi, maxj, maxk).

As mentioned above, the quantities maxi, maxj and maxk are used to specify the number of nodes in each element direction. Given this general definition there are a number of conventions to distinguish between Serendipity and Lagrange numbering and some other important special cases.

maxi = 0, then the linear Serendipity form of the element is assumed and maxj = maxk = 0.

2 <= maxi <= 4, maxj = 0, and maxk = 0 then the element is a Serendipity element which is linear, parabolic or cubic in the i, j and k directions.

2 <= maxi <= 4, 2 <= maxj <= 4 and 2 <= maxk <= 4, then the element is a Lagrange element with maxi, maxj and maxk nodes in the i,j and k directions respectively.

2 <= maxi <= 4, maxj = 0, and 2 <= maxk <= 4. This is a special case of mixed Serendipity and Lagrange numbering for 3D pentahedral and hexahedral shapes in which the i and j directions are numbered first as a 2D Serendipity element then this numbering is repeated for each nodal plane in the k direction.

2 <= maxi <= 4, maxj = 1, and maxk = 0. This a special case for 2D triangle Lagrange shapes in which the i direction has maxi nodes with a single additional node at the triangle apex.

2 <= maxi <= 4, maxj = 0 or 2 <= maxj <= 4, and maxk = 1. This a special case for 3D tetrahedron and pyramid Serendipity or Lagrange element shapes in which the nodal pattern in the i and j directions is given by maxi and maxj with a single additional node at the tetrahedron or pyramid apex.

maxi = 3, maxj >= 2**16, maxk = 0. This is a special case of parabolic Serendipity elements with missing midside nodes. The lower 16 bits of maxj are zero, the upper 16 bits of maxj are used to flag missing midside nodes on element edges. The first bit of the upper 16 bits (ie bit 17) is set if the midside node on edge 1 is missing, bit 18 is set if the midside node on edge 2 is missing, etc. This convention is not used for line element shapes.

Examples of the mixed Serendipity and Lagrange numbering for pentahedral and hexahedral elements appear below. The i and j directions are numbered using a Serendipity connectivity convention. This numbering is then incremented in the k direction.

The polygon and polyhedron shapes have different interpretations for the
quantities maxi, maxj and maxk from the conventional shapes
described above. The quantity maxi indicates the total number of
points in the polygon or polyhedron. The quantities maxj and
maxk are used internally to indicate the number of edges and number
of faces respectively. The user is not required to enter the values of
maxj and maxk and may enter them as zeros. The connectivity
convention for polytype cells orders the connectivity of each face such
that the right hand rule sense of the connectivity points outward. In
addition, the first node of the connectivity of each face is repeated as
the last node in the face connectivity. The total number of points in
the polytype includes the nodes repeated due to this convention. Note
that the polytype representation requires a significantly larger number
of nodes in the connectivity than a conventional shape of similar
complexity. For example a linear hexahedron of shape **SYS_SHAPEHEX**
requires 8 nodes in the connectivity while the shape
**SYS_SHAPEPOLYHED** requires 30 total nodes (6 faces times 5 nodes per
face).

The connectivities for a polygon and polyhedra are shown below. Note that the starting node for each of the face connectivities is arbitrary and the order of the faces is arbitrary.

```
Polygon n1,n2,n3,n4,n5,n1
Polyhedron n1,n2,n3,n1, n2,n5,n6,n3,n2, n4,n7,n6,n5,n4, n1,n3,n7,n4,n1, n6,n7,n3,n6, n4,n5,n2,n1,n4
```

For the special cases of quadrilateral and hexahedral grids VisTools provides for 3 special cases of regular arrays (sometimes referred to as structured grids): curvilinear, rectilinear and uniform. Each case has the same topology while exploiting various degrees of uniformity in the physical mapping of the nodes in space. The 3 cases are illustrated below for a quadrilateral grid.

The motivation for providing these special cases is that the amount of data required to specify node locations is dramatically reduced in each case. For curvilinear grids, each node point is mapped to physical space by an explicitly supplied coordinate location. For a maxi by maxj by maxk grid, maxi * maxj * maxk node coordinates must be defined. Rectilinear grids are orthographic with variable spacing between lines of nodes. Rectilinear grids are defined by specifying the intersections of the grid lines with the corresponding coordinate axis in each spatial direction. For a maxi by maxj by maxk grid, maxi + maxj + maxk node coordinates must be defined. Uniform grids are orthographic with constant spacing between lines of nodes. Uniform grids are defined by specifying the bounding box of the grid, ie. two coordinates.

### 1.2.1. Edge and Face Numbering

VisTools occasionally requires the identification of a particular edge or face of a computational cell. For example, the Threshold module may be queried to return the faces of a 3D cell which are intersected by an isosurface. The edges and faces of a particular cell are specified by an edge or face index. The edges and faces are defined by the cell node indices. The node indices defining edges and faces for all primitive cell shapes are as follows assuming the low order Serendipity element connectivity convention.

```
triangle edge - nodes
1 1,2
2 2,3
3 3,1
quadrilateral edge - nodes
1 1,2
2 2,3
3 3,4
4 4,1
tetrahedron edge - nodes edge - nodes face - nodes
1 1,2 4 1,4 1 1,3,2
2 2,3 5 2,4 2 1,2,4
3 3,1 6 3,4 3 1,4,3
4 2,3,4
pyramid edge - nodes edge - nodes face - nodes
1 1,2 5 1,5 1 1,4,3,2
2 2,3 6 2,5 2 1,2,5
3 3,4 7 3,5 3 2,3,5
4 4,1 8 4,5 4 3,4,5
5 4,1,5
wedge edge - nodes edge - nodes face - nodes
1 1,2 7 1,4 1 1,3,2
2 2,3 8 2,5 2 4,5,6
3 3,1 9 3,6 3 1,2,5,4
4 4,5 4 1,4,6,3
5 5,6 5 2,3,6,5
6 6,4
hexahedron edge - nodes edge - nodes face - nodes
1 1,2 7 7,8 1 1,4,3,2
2 2,3 8 8,5 2 5,6,7,8
3 3,4 9 1,5 3 1,2,6,5
4 4,1 10 2,6 4 4,8,7,3
5 5,6 11 3,7 5 1,5,8,4
6 6,7 12 4,8 6 2,3,7,6
```

The edge and face definitions have a different set of node indices for the Lagrange finite element or array connectivity convention. However the edges and faces are configured on each cell topology in an identical manner.

### 1.2.2. Physical and Natural Coordinates

VisTools uses two coordinate systems to describe coordinate locations and field data and perform visualization computations, 1) physical coordinates and 2) natural coordinates.

Physical coordinates are expressed in a 3 dimensional Cartesian coordinate system. This coordinate system must be consistently used to express all domain coordinates and vector and tensor field data presented to VisTools functions. Point coordinates and other vectors are entered in VisTools as 3 components in the order (x,y,z). Symmetric tensors are entered as 6 components in the following order (xx,yy,zz,xy,yz,zx).

Natural coordinates are curvilinear coordinate systems which are used to define interpolation coefficients local to an individual cell or finite element. Natural coordinates are defined in an element topology dependent manner and are normalized within the element in some way. For example, the natural coordinates in a quadrilateral element (r,s) are normalized in the interval [-1,1]. For triangular elements, the natural coordinates (r,s) are related to the area coordinates (L1,L2,L3) in the interval [0,1].

For all shapes except polygon and polyhedron, the direction of the natural coordinates may be defined by the cell node indices at the end points of the cell edge which is “parallel” to the natural coordinate. The node indices are given assuming the low order Serendipity element connectivity convention.

For polygon and polyhedron shapes, the natural coordinates are relative to a triangular and tetrahedral decomposition of the shapes respectively. For polygons, the triangular decomposition is done from a point at the center of the polygon connecting all of the boundary nodes of the polygon. A polygon with N unique nodes will have N triangles. For polyhedra, the tetrahedral decomposition is done from a point at the center of the polyhedron connected a point at the center of each face with all nodes bounding the face. A polyhedron with N unique nodes will have N tetrahedra. The r,s and t coordinates are relative to one of the triangles or tetrahedra in the decomposition. The index (1-based) of the specific triangle or tetrahedron is added to the s natural coordinate.

```
line natural coordinates - normalization - nodes
r [-1,1] 1,2
triangle natural coordinates - normalization - nodes
r = L1 [0,1] 1,2
s = L2 [0,1] 1,3
quadrilateral natural coordinates - normalization - nodes
r [-1,1] 1,2
s [-1,1] 1,4
tetrahedron natural coordinates - normalization - nodes
r = L1 [0,1] 1,2
s = L2 [0,1] 1,3
t = L3 [0,1] 1,4
pyramid natural coordinates - normalization - nodes
r [-1,1] 1,2
s [-1,1] 1,4
t [-1,1] 1,5
wedge natural coordinates - normalization - nodes
r = L1 [0,1] 1,2
s = L2 [0,1] 1,3
t [-1,1] 1,4
hexahedron natural coordinates - normalization - nodes
r [-1,1] 1,2
s [-1,1] 1,4
t [-1,1] 1,5
polygon natural coordinates - normalization
r [0,1] radial
s [>=0] triangle index + local s
polyhedron natural coordinates - normalization
r [0,1] radial
s [>=0] tetrahedron index + local s
t [0,1] local t
```

## 1.3. Element Types

VisTools supports a wide variety of finite element types. The full
description of a particular finite element type requires information
about it basic type ie. solid, shell, beam, etc. and the specific
topology and order such as linear hexahedron, parabolic tetrahedron,
etc. For some specialized elements such as spot welds, there can be
additional information concerning the types of elements to which the
spot weld is connected. This additional information is referred to as
the end **A** and end **B** topology. VisTools begins by placing
elements into one of the following general type categories.

**SYS_ELEM_SOLID**, solid element**SYS_ELEM_SHELL**, shell element, in-plane stress, bending, shear**SYS_ELEM_MEMBRANE**, membrane element, in-plane stress only**SYS_ELEM_BEAM**, beam element, axial stress, bending, shear**SYS_ELEM_TRUSS**, truss element, axial stress only**SYS_ELEM_INFINITE**, infinite element**SYS_ELEM_GAP**, gap element, point contact**SYS_ELEM_JOINT**, joint element**SYS_ELEM_SPRINGDASHPOT**, spring and dashpot element**SYS_ELEM_RIGID**, rigid element**SYS_ELEM_CONSTRAINT**, constraint element, multipoint constraint**SYS_ELEM_PLOT**, plot element, visualization only**SYS_ELEM_MASS**, mass element**SYS_ELEM_INTER**, interface elements, distributed contact, boundary conditions**SYS_ELEM_SUPER**, superelements

Within each general category the element is further described by its specific type, topology , shape, and order , maxi, maxj, maxk. For most elements these parameters are sufficient to accurately characterize the element. For most general types there are several specific types which help to identify the element within the general type. The general types are described in more detail below with information concerning the applicable specific types, topologies and orders.

**SYS_ELEM_SOLID**, solid elements may be defined in either 2D or 3D
space. In 2D space the topology must be either triangle, quadrilateral
or polygonal. In 3D space the topology must be tetrahedron, pyramid,
pentahedron, hexahedron or polyhedral. The possible specific types are
as follows:

**SYS_SOLID_STAN**, standard solid element**SYS_SOLID_FLUID**, fluid solid element**SYS_SOLID_SHELL**, thick shell solid element

**SYS_ELEM_SHELL**, shell elements may be defined in either 2D or 3D
space. In 2D space the topology must be a line, in 3D space the topology
must be triangle or quadrilateral.

**SYS_ELEM_MEMBRANE**, membrane elements may be defined in either 2D or
3D space. In 2D space the topology must be a line, in 3D space the
topology must be triangle or quadrilateral. The possible specific types
are as follows:

**SYS_MEMBRANE_STAN**, standard membrane element**SYS_MEMBRANE_SHEAR**, shear panel element**SYS_MEMBRANE_FACE**, face element. A facet collocated with a face of a geometry tessellation

**SYS_ELEM_BEAM**, beam elements may be defined in either 2D or 3D
space. In 2D space the topology must be a point with maxi = 1. in 3D
space the topology must be line. The possible specific types are as
follows:

**SYS_BEAM_STAN**, standard beam element**SYS_BEAM_ROD**, axial-torsional element**SYS_BEAM_WELD**, weld element**SYS_BEAM_CBEND**, curved beam and pipe element

**SYS_ELEM_TRUSS**, truss elements may be defined in either 2D or 3D
space. In 2D space the topology must be a **SYS_SHAPEPOINT** with
maxi = 1. in 3D space the topology must be **SYS_SHAPELINE** The
possible specific types are as follows:

**SYS_TRUSS_STAN**, standard truss element**SYS_TRUSS_EDGE**, edge element. A segment collocated with an edge of a geometry tessellation.

**SYS_ELEM_SPRINGDASHPOT**, spring and dashpot elements are discrete
elements whose physical properties are not generally dependent upon an
integration over their spatial extent. The topology must be either
**SYS_SHAPEPOINT** or **SYS_SHAPELINE** and is independent of the
spatial dimension. This category of elements can be quite complicated
and as a result the end **A** and **B** topologies can be required in
some cases to identify the element. The possible specific types are as
follows:

**SYS_SPRINGDASHPOT_SCALAR**, scalar spring. The topology is**SYS_SHAPELINE**for a spring connecting two degrees of freedom and**SYS_SHAPEPOINT**for a spring connecting a degree of freedom to ground. The spring may also include a damper.**SYS_SPRINGDASHPOT_LINK**, line spring which generally connects translation and/or rotation freedoms in the direction between two nodes. The topology is**SYS_SHAPELINE**.**SYS_SPRINGDASHPOT_WELD**, spot weld spring which attempts to model the effect of a spot weld which, in general, smears its connections over the geometry of two opposing elements. If the topology is**SYS_SHAPELINE**, then maxi = 2 and the weld element connects two nodes. If the topology is**SYS_SHAPEPOINT**, then maxi => 2 and the weld element connects maxi nodes. The end**A**and**B**topologies determine how the nodes are connected to the adjacent elements. The nodes associated with the end**A**topology precede the nodes associated with the end**B**topology. The end topologies for a spoint (single node), lines, triangles and quadrilaterals are below. There are not defined constants for the case of a point topology with more than one node or line, triangle and quadrilateral topologies with maxi and/or maxj greater than 3. In general, end topologies are decoded as shown below:**SYS_TOPO_POINT1 - SYS_SHAPEPOINT**, maxi = 1**SYS_TOPO_LINE2 - SYS_SHAPELINE**, maxi = 2, maxj = 0**SYS_TOPO_LINE3 - SYS_SHAPELINE**, maxi = 3, maxj = 0**SYS_TOPO_TRI3 - SYS_SHAPETRI**, maxi = 2, maxj = 0**SYS_TOPO_TRI6SER - SYS_SHAPETRI**, maxi = 3, maxj = 0**SYS_TOPO_TRI6LAG - SYS_SHAPETRI**, maxi = 3, maxj = 3**SYS_TOPO_QUAD4SER - SYS_SHAPEQUAD**, maxi = 2, maxj = 0**SYS_TOPO_QUAD4LAG - SYS_SHAPEQUAD**, maxi = 2, maxj = 2**SYS_TOPO_QUAD8 - SYS_SHAPEQUAD**, maxi = 3, maxj = 0**SYS_TOPO_QUAD9 - SYS_SHAPEQUAD**, maxi = 3, maxj = 3shape = (topo >> 28) & 0x000fmaxi = (topo >> 16) & 0x0fffmaxj = (topo >> 8) & 0x00ffmaxk = (topo >> 0) & 0x00ff**SYS_SPRINGDASHPOT_BUSH**, bushing spring made up of separate translational and rotational springs with possible parallel dashpots connecting two nodes. The topology is**SYS_SHAPELINE**and maxi = 2.

**SYS_ELEM_RIGID**, rigid elements are used to enforce various types of
constraints. The elements are mathematically similar to constraint
elements, **SYS_ELEM_CONSTRAINT**, however their definition is not
abstract but is usually in terms of a physically understandable rigid
effect. The possible specific types are as follows:

**SYS_RIGID_KINE**, kinematic constraints provide a general tying of the translations and rotations of a node to the translations and rotations of a set of nodes. There are always exactly 6 independent degrees of freedom which must be capable of representing any general rigid body motion of the coupling nodes. The topology is**SYS_SHAPEPOINT**with maxi equal to the number of nodes involved in the constraint for “spoke” type topologies. The topology is**SYS_SHAPELINE**with maxi = 2 for rigid beams. The topology is**SYS_SHAPETRI**with maxi = 3 or**SYS_SHAPEQUAD**with maxi = 4 for rigid triangles and quadrilaterals.**SYS_RIGID_DIST**, distributing constraints provide a constraint to distribute force and moment at a point to forces at a set of coupling nodes. The coupling effectively constrains the rotation and translation at a point to the translations at the set of coupling nodes. This constraint is enforced in an average sense and therefore does not inhibit the relative deformation of the coupling nodes. The topology is**SYS_SHAPEPOINT**with maxi equal to the number of nodes involved in the constraint.**SYS_RIGID_LINK**, link constraints enforce a rigid link between two nodes involving translations only. The topology is**SYS_SHAPELINE**with maxi = 2.**SYS_RIGID_RBE3**, distributing constraint specifically models the NASTRAN RBE3 rigid element. The topology is**SYS_SHAPEPOINT**with maxi equal to the number of nodes involved in the constraint.**SYS_RIGID_SPLINE**, spline constraint specifically models the NASTRAN RSPLINE rigid element. The topology is**SYS_SHAPELINE**with maxi equal to the number of nodes involved in the constraint.**SYS_RIGID_JOINT**, coincident node joint constraint enforces identical movement of specified degrees of freedom between two coincident nodes. The topology is**SYS_SHAPEPOINT**with maxi = 2.

**SYS_ELEM_CONSTRAINT**, constraint elements are used to impose general
multipoint constraints. The topology is **SYS_SHAPEPOINT** and maxi
is equal to the number of degrees of freedom involved in the constraint
equation.

**SYS_ELEM_PLOT**, plot elements are used for visualization only and
have no physical properties. Their topologies and orders are general.
The possible specific types are as follows:

**SYS_PLOT_LOD0**, level of detail 0**SYS_PLOT_LOD1**, level of detail 1**SYS_PLOT_LOD2**, level of detail 2**SYS_PLOT_LOD3**, level of detail 3**SYS_PLOT_AERO**, Nastran AERO elements

**SYS_ELEM_MASS**, mass elements are discrete elements whose physical
properties are not generally dependent upon an integration over their
spatial extent. The topology must be either **SYS_SHAPEPOINT** or
**SYS_SHAPELINE** and is independent of the spatial dimension. The
possible specific types are as follows:

**SYS_MASS_SCALAR**, scalar mass. The topology is**SYS_SHAPELINE**for a mass connecting two degrees of freedom and**SYS_SHAPEPOINT**for a scalar concentrated mass.**SYS_MASS_LUMP**, lumped mass which generally involves translational mass and rotary inertia tensor defined in a local coordinate system. The mass is concentrated at a point. The topology is**SYS_SHAPEPOINT**and maxi = 1.**SYS_MASS_MATRIX**, lumped mass which is defined by a symmetric 6x6 matrix. The mass is concentrated at a point. The topology is**SYS_SHAPEPOINT**and maxi = 1.**SYS_MASS_VERTEX**, vertex element. A point collocated with a vertex in a geometry tessellation

## 1.4. Element Coordinate Systems

An element coordinate system is a Cartesian coordinate system oriented to the element geometry. Element coordinate systems are used in a number of ways depending upon the type of element. The most common use is a a coordinate system for the computation and output of stress and strain related quantities (heat flux and temperature gradient for thermal analysis, etc.). For some 1D and 0D elements such as beams, gaps and concentrated masses, the element coordinate system is used to define certain properties of the element such as cross section properties, slip directions and moment of inertia tensors.

Certain constraints are placed upon the orientation of the element coordinate system depending upon the element type. For surface elements such as shell elements, the local x’ and y’ axes are constrained to be tangent to the shell reference surface. The local z’ is normal to the surface. The orientation of the x’ and y’ axes in the tangent plane is determined by convention. The convention specifies the direction of the x’ axis. The y’ axis is then constructed to complete a right-handed Cartesian system. For line elements such as beam elements, the local x’ axis is constrained to be tangent to the beam axis. The local y’ and z’ axes are perpendicular to the beam axis. In a manner similar to surface elements, the orientation of the y’ and z’ axes in the plane perpendicular to the beam axis is determined by convention. The convention specifies the direction of the y’ axis. The z’ axis is then constructed to complete a right-handed Cartesian system. For full 3D solid elements, there are no constraints upon the orientation of the element local system and as a result it is generally aligned to the global coordinate system. For point elements such as concentrated mass elements, the element coordinate systems may be arbitrarily oriented in space and are either aligned to the global coordinate system or to a user specified Cartesian system.

A wide variety of element coordinate system conventions are in use in
the finite element industry. Many of them are used to resolve the
orientation issues in line and surface elements. In order to achieve
coverage of current industry practice, the following types are provided.
Where these element coordinate system types are used as options in
specific element modules such as VisTools ShellElem
or VfeTools **Shell3D**, a certain amount of additional data may be
required in addition to the element geometry. This is noted for each
type.

Global,

**SYS_ELEMSYS_GLOBAL**. The element coordinate system is aligned to the global axes. When this system is used for surface or line elements it is usually only for the purpose of expressing vector or tensor output quantities.Standard,

**SYS_ELEMSYS_STANDARD**. For volume elements the x’ axis is aligned to the element r natural coordinate direction. The y’ axis is perpendicular to x’ in the plane formed by the r and s natural coordinate directions. For surface elements the x’ axis is aligned to the element r natural coordinate direction. For line elements the y’ axis lies in the plane formed by the x’ axis and the global y axis unless the global y axis is 0.1 degree of being tangent to the x’ axis. In this case the y’ axis lies in the plane formed by the x’ axis and the global z axis.Position,

**SYS_ELEMSYS_POSITION**. For surface elements the x’ axis is in the direction of the projection on the surface of a line from the point on the surface to a specified point in space. For line elements the y’ axis lies in the plane formed by the line element axis and a line from the point on the line element axis to a specified point in space. The 3 global coordinates of the specified point must be provided as additional data.Vector,

**SYS_ELEMSYS_VECTOR**. For surface elements the x’ axis is in the direction of the projection on the surface of a specified vector anchored at the point on the surface. For line elements the y’ axis lies in the plane formed by the line element axis and a specified vector anchored at the point on the line element axis. For 2D volume elements the x’ axis is in the direction of the projection on the x, y plane of a specified vector anchored at the point on the plane. The y’ axis is perpendicular to x’ in the plane. The 3 components of the specified vector in global coordinates must be provided as additional data.Vectors at Element Nodes,

**SYS_ELEMSYS_VECTORELEMNODE**. For surface elements the x’ axis is in the direction of the projection on the surface of a vector anchored at the point on the surface which has been interpolated from vectors specified at the element nodes, For line elements the y’ axis lies in the plane formed by the line element axis and a vector anchored at the point on the line element axis which has been interpolated from vectors specified at the element nodes, The 3 components of the specified vector in global coordinates at each element node must be provided as additional data.Global Project,

**SYS_ELEMSYS_GLOBALPROJECT**. This standard is designed explicitly for support of the conventions for surface elements used in ABAQUS. The default local x’ axis is the projection of the global x onto the surface. If the global x axis is within 0.1 degree of the normal to the surface, the local x’ direction is the projection of the global z axis onto the surface. For line elements the z’ axis is constructed to be approximately parallel to the negative global z axis. If the global z axis is within 0.1 degree of the x’ axis the local z’ direction is parallel to the global x axis.Centroid,

**SYS_ELEMSYS_CENTROID**. This standard is designed to orient the element coordinate system with the directions of the natural coordinates at the centroid of the element. The local x’ axis is along the direction of the first natural coordinate. The local z axis is normal to the plane formed by the cross product of the first and second natural coordinate directions. The y axis is formed as the cross product of the local z and x axes and as a result will lie in the plane formed by the first and second natural coordinate directions.Bisector,

**SYS_ELEMSYS_BISECTOR**. This standard is designed explicitly for support of the conventions for surface elements used in MSC/NASTRAN and is named for the particular method used for the CQUAD4 shell element. For line elements the convention is the same as the Standard convention.Nastran Shell,

**SYS_ELEMSYS_NASTRANSHELL**. This standard is designed explicitly for material coordinate system support for classic CTRIA6 and CQUAD8 shell elements used in NASTRAN. The convention is similar to**SYS_ELEMSYS_STANDARD**with a specified angle (in degrees) rotation is applied to the computed direction. The specified angle in degrees, followed by two zeros must be provided as additional data. An additional angle, specific to CQUAD8, is computed internally.Bidiagonal,

**SYS_ELEMSYS_BIDIAGONAL**. This standard is designed explicitly for material coordinate system support of the conventions for surface elements used in SAMCEF.First Edge,

**SYS_ELEMSYS_FIRSTEDGE**. This standard is designed explicitly for support of the conventions for surface and line elements used in ANSYS. For surface elements the x’ axis is the projection onto the surface of the vector directed from the first corner node to the second corner node. For line elements the y’ axis lies in the global x, y plane. For the case that the element x’ axis is parallel to the global z axis (or within a .01 percent slope of it), the y’ axis is oriented parallel to the global y axis.First Edge plus angle,

**SYS_ELEMSYS_FIRSTEDGEANGLE**. This standard is designed explicitly for material coordinate system support of the conventions for surface elements used in NASTRAN. A specified angle (in degrees) rotation is applied to the direction computed by**SYS_ELEMSYS_FIRSTEDGE**. The angle in degrees, followed by two zeros must be provided as additional data.Mid Edge,

**SYS_ELEMSYS_MIDEDGE**. This standard is designed explicitly for support of the convention for quadrilateral surface elements used by ESI. The x’ axis is the projection onto the surface of the vector directed from the midpoint of the fourth edge to the midpoint of the second edge. The normal to the surface element is the normal to x’ and a vector directed from the midpoint of the first edge to the midpoint of the third edge. The y’ axis is constructed orthogonal to the surface normal the x’ axis.Mid Point,

**SYS_ELEMSYS_MIDPOINT**. This standard is designed explicitly for support of the conventions for surface elements used in Altair/Radioss and is named for the particular method used for the linear triangle and quadrilateral shell elements. The local system is constructed by creating a vector which bisects the vectors connecting the midpoints of the first and third edges with the fourth and second edges. The vector then bisects the x’ and y’ axies of the local coordinate system.Global Closest,

**SYS_ELEMSYS_GLOBALCLOSEST**. For surface elements the x’ axis is in the direction of the projection on the surface of the closest global axis. For line elements the y’ axis lies in the plane formed by the line element axis and the closest global axis to the plane perpendicular to the line element axis.Cylindrical system,

**SYS_ELEMSYS_CYLINDRICAL**. This system is designed for support of cylindrical system orientation. The axis of the cylindrical system is specified by two point coordinates and is directed from the first point to the second. The origin of the system is positioned at the first point. For point elements and 3D volume elements the x’ axis at a point is in the radial direction of the point, the y’ axis is the tangential direction and the z’ axis is the axis of the cylindrical system. For surface elements the x’ axis is the projection of the radial direction on the surface. For line elements the y’ axis lies in the plane formed by the radial direction and the axis of the line. The 3 components of the first point followed by the 3 components of the second point in global coordinates must be provided as additional data.Spherical system,

**SYS_ELEMSYS_SPHERICAL**. This system is designed for support of spherical system orientations. The axis of the spherical system is specified by two point coordinates and is directed from the first point to the second. The origin of the spherical system is positioned at the first point For point elements and 3D volume elements the x’ axis at a point is in the radial direction of the point, the y’ axis is the tangential direction and the z’ axis is the azimuthal axis. The tangential axis is about the axis of the spherical system. For surface elements the x’ axis is the projection of the radial direction on the surface. For line elements the y’ axis lies in the plane formed by the radial direction and the axis of the line. The 3 components of the first point followed by the 3 components of the second point in global coordinates must be provided as additional data.Spherical system alternate,

**SYS_ELEMSYS_SPHERICAL_ALT**. This system is designed for support of spherical system orientations used by NASTRAN. The axis of the spherical system is specified by two point coordinates and is directed from the first point to the second. The origin of the spherical system is positioned at the first point For point elements and 3D volume elements the x’ axis at a point is in the radial direction of the point, the y’ axis is the azimuthal direction and the z’ axis is the tangential axis. The tangential axis is about the axis of the spherical system. For surface elements the x’ axis is the projection of the radial direction on the surface. For line elements the y’ axis lies in the plane formed by the radial direction and the axis of the line. The 3 components of the first point followed by the 3 components of the second point in global coordinates must be provided as additional data.Rotation Angle Vector,

**SYS_ELEMSYS_ROTANG**. The element coordinate system is explicitly specified by a single rotation angle vector relative to the global coordinate system. The rotation angle vector is computed using the Rodriques formula. The magnitude of the rotation angle vector is the amount of rotation about the vector in degrees. The 3 components of the rotation angle vector must be provided as additional data.Rotation Angle Vectors at Element Nodes,

**SYS_ELEMSYS_ROTANGELEMNODE**. The element coordinate system is explicitly specified by a rotation angle vector relative to the global coordinate system at each element node. The rotation angle vector is computed using the Rodriques formula. The magnitude of the rotation angle vector is the amount of rotation about the vector in degrees. The associated vector or tensor quantities are also output at each element node. The 3 components of the rotation angle vector at each element node must be provided as additional data.Cylindrical system alternate,

**SYS_ELEMSYS_CYLINDRICAL_ALT**. This system is designed to support of cylindrical system orientations used by NASTRAN CBEND element. For line elements, the x’ axis at a point is the radial direction of the point, the z’ axis is the axis of the cylindrical system and y’ axis is the tangential direction. The 3 components of the radial vector at the first node of the element specified in global coordinates must be provided as additional data.Unknown system,

**SYS_ELEMSYS_UNKNOWN**. This system is designed to support an element system which is not completely known. For volume elements the system is identical to**SYS_ELEMSYS_GLOBAL**. For surface elements the system is identical to**SYS_ELEMSYS_STANDARD**. For line elements the system is identical to**SYS_ELEMSYS_STANDARD**. For point elements the system is identical to**SYS_ELEMSYS_GLOBAL**.

## 1.5. Mathematical Data Types

CeetronSAM provides many methods to manipulate and visualize mathematical data types such as scalars, vectors, symmetric tensors and general tensors. The following ordering conventions are used for the components of vector, v, tensor, t, and general tensor, g, data types.

Vector v (x, y, z)

```
v[0] = x
v[1] = y
v[2] = z
```

Tensor t (xx, yy, zz, xy, yz, zx)

```
t[0] = xx
t[1] = yy
t[2] = zz
t[3] = xy
t[4] = yz
t[5] = zx
```

General Tensor g (xx, xy, xz, yx, yy, yz, zx, zy, zz)

```
g[0] = xx g[1] = xy g[2] = xz
g[3] = yx g[4] = yy g[5] = yz
g[6] = zx g[7] = zy g[8] = zz
```

There are specializations of symmetric tensors for the finite element stress resultants and strain-curvatures of shell and beam type elements.

```
s[0] = Nxx e[0] = Exx
s[1] = Nyy e[1] = Eyy
s[2] = Nxy e[2] = Exy
s[3] = Mxx e[3] = Kxx
s[4] = Myy e[4] = Kyy
s[5] = Mxy e[5] = Kxy
s[6] = Qxz e[6] = Txz
s[7] = Qyz e[7] = Tyz
```

```
s[0] = Nxx e[0] = Exx
s[1] = Myy e[1] = Kyy
s[2] = Mzz e[2] = Kzz
s[3] = Torque e[3] = Twist
s[4] = Qxy e[4] = Txy
s[5] = Qzx e[5] = Tzx
```

The representation of the coordinate systems in which these quantities are expressed, where applicable, requires support for direction cosine matrices and their equivalent compact representation as rotation angle vectors.

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[3][3] 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.

The rotation angle vector, ra, can be used as a compact representation of a direction cosine matrix. It is the generalization of an infinitesimal rotation vector to finite rotations.

## 1.6. Complex Numbers

A number of VisTools modules are designed to store and manipulate complex numbers. A consistent set of functions are implemented across these modules to control how the real and imaginary parts of the complex data are to be set and queried from the modules. The modules which are currently designed to handle complex numbers are the loading and constraint modules, LCase and RCase and the results modules, RedMat, State, History and ElemDat.

For example, the RCase module function
`vis_RCaseSetComplexMode()`

is used to specify which component(s) of a complex value, (real and/or
imaginary), are to be set or queried by the functions
`vis_RCaseSetSPC()`

and `vis_RCaseSPC()`

respectively. By default the complex mode value is **SYS_COMPLEX_REAL**,
that is, the set and query functions only expect a real number or the
real part of a complex number. Both the real and imaginary parts can be
queried by setting the complex mode **SYS_COMPLEX_REALIMAGINARY**. If
only the imaginary part of a complex number is to be set or queried use
**SYS_COMPLEX_IMAGINARY**. If at any time the complex mode is set to
**SYS_COMPLEX_IMAGINARY** or **SYS_COMPLEX_REALIMAGINARY** the module
will, in general, contain complex data. The function
`vis_RCaseGetComplex()`

can be used to determine if the module does contain complex data. The
function `vis_RCaseGetComplexMode()`

will return the current complex mode. All of the modules listed above
contain identical functions to set/get the complex mode and query for
the existence of complex data.

There is not a special data type given complex numbers. The real and imaginary parts are represented as two consecutive real numbers. For example, setting the 3 components of a double precision real vector would be 3 consecutive double precision numbers representing the x, y, z components of the vector. The equivalent complex vector would require 6 double precision numbers representing the x,x(i), y,y(i), z,z(i) values of the vector.

## 1.7. Compiling and Linking a VisTools Application

To use VisTools on a particular computer platform, the VisTools source must be compiled and linked to an application. Either the object files may be used directly or they may be installed in an object library archive so that the loader may selectively relocate only the objects which are required. VisTools is written in ANSI C. It is suggested to use the highest level of serial optimization options available on the C compiler.

VisTools is platform independent and as a result no user defined C
preprocessor directives are required to compile VisTools on any
supported platform. However it is suggested that during the development
cycle that the source be conditionally compiled with error checking by
defining **VKI_CHECK_ERRS** as described in **base** library.

For example, on SGI systems, create a directory **SGI** under **lib** to
hold the final **CeetronSAM.a** archive file. Then from the
**CeetronSAM/src/legacy/vis** directory compile using

```
cc -c -O2 -I.. *.c
```

creating **.o** files in the **vis** directory. To place the object
files in an archive file issue

```
ar rs ../../lib/SGI/CeetronSAM.a *.o
```

The object files may be deleted after the **CeetronSAM.a** archive is
successfully created. To compile the **vgl** source, change directory to
**CeetronSAM/src/legacy/vgl** and compile using

```
cc -c -O2 -I.. *.c
```

creating **.o** files in the **vgl** directory. If you have a complete
VglTools installation, compile using the instructions in the VglTools
Programmer Manual. To add these objects to the previously created
**CeetronSAM.a** archive issue

```
ar rs ../../lib/SGI/CeetronSAM.a *.o
```

To compile the **base** source, change directory to
**CeetronSAM/src/sam/base** and compile using

```
cc -c -O2 *.c
```

creating **.o** files in the **base** directory. To add these objects to
the previously created **CeetronSAM.a** archive issue

```
ar rs ../../lib/SGI/CeetronSAM.a *.o
```

Again object files may deleted at this time. At this point the
**CeetronSAM.a** archive contains all **vis**, **vgl** and **base**
objects. Place the **CeetronSAM.a** archive immediately before the
graphics subsystem libraries in the load line. A **CeetronSAM.a** archive
must be built for each computer platform using the methodology outlined
above.

## 1.8. Attribute Objects, Data Interpolation, Isovalue Clipping and Topology

The visualization modules share many common features with respect to the use of attribute objects and setting the current computational grid topology. Generally the visualization modules in each category such as isovalue extraction, tangent curve generation, geometry rendering, feature extraction, etc are further divided by dimension. For example, the Segment, Contour and Threshold isovalue extraction modules are designed to extract isovalues in 1D, 2D and 3D computational cells respectively.

Each visualization module is designed to accept attribute objects which
will affect the appearance of the generated graphics primitives. All
attribute objects are set in the visualization objects using a similar
function (SetObject). For example, for the Contour
object, use `vis_ContourSetObject()`

.
The attribute object, VisContext,
is the basic container for the myriad settings such as line width, point
size, size scaling, etc. which affect the appearance of generated
graphics primitives. The ColorMap and
TransMap objects along with the Levels
object associate or map color and transparency to data value. The
DataInt
object specifies data quantities to be mapped to an output graphics
primitive in the same way that color or transparency are mapped to a
primitive. This object is useful, for example, for generating contours
of a data field onto the isosurfaces of another data field. The
IsoClip
object specifies a data field used as an isosurface for clipping
graphics primitives. Use this object along with the
Threshold
object to generate a “clipped and capped” display.

The exact nature of the computational cell topology to be processed by
each visualization module is also set using a similarly named function
(SetTopology). For example, for the Contour object, use
`vis_ContourSetTopology()`

.
The polyhedral cell topology, in particular, requires additional
topological information in the form of the polyhedral node connectivity
for efficient rendering. The function (SetElemNode) is designed to input
this information. For example, for the Threshold
object, use `vis_ThresholdSetElemNode()`

.
Only the 3D visualization modules support and, in some cases, require
the polyhedral node connectivity.

## 1.9. A First Program - C Version

As an example of a simple VisTools application the following program
draws isosurfaces through a unit cube of data. The attribute modules
used are the VisContext, Levels,
ColorMap and TransMap
modules, the visualization module is Threshold.
The DrawFun
module contains the callback functions which the
Threshold
module uses to output the generated graphics primitives. First, a
DrawFun
object is instanced. Rather than outputting the displayable geometry to
a graphics device, the built-in “print” drawing functions are used.
These functions are set up internally in the
DrawFun object using the function
`vgl_DrawFunAPI()`

.

The attribute objects are instanced and are set up to draw isosurfaces
at 3 evenly spaced levels with red, green and blue assigned to each
discrete data level respectively. The attribute objects and drawing
function object are then registered with the Threshold
object using the function `vis_ThresholdSetObject()`

.
The actual graphics primitives are generated which represent the
isosurfaces through the hexahedron by the function
`vis_ThresholdCurv()`

.
Finally all objects are deleted.

```
#include "legacy/vgl/vgl.h"
#include "sam/vis/vis.h"
#include "legacy/vis/vislegacy.h"
#include "sam/base/license.h"
#include "sam/CEETRON_SAM_license.h"
static Vfloat xhex[8][3] = {{0., 0., 0.}, {1., 0., 0.}, {1., 1., 0.}, {0., 1., 0.},
{0., 0., 1.}, {1., 0., 1.}, {1., 1., 1.}, {0., 1., 1.}};
static Vfloat shex[8] = {0., 1., 1., 0., 1., 2., 2., 1.};
static Vfloat rgb[4][3] = {{.2f, .2f, .2f}, {1., 0., 0.}, {0., 1., 0.}, {0., 0., 1.}};
/*----------------------------------------------------------------------
Generate isosurfaces in a hexahedron
----------------------------------------------------------------------*/
int
main()
{
vgl_DrawFun* df;
vis_VisContext* vc;
vis_Levels* levels;
vis_ColorMap* cmap;
vis_TransMap* tmap;
vis_Threshold* threshold;
Vint nlevels;
vsy_LicenseValidate(CEETRON_SAM_LICENSE);
/* create draw function object */
df = vgl_DrawFunBegin();
/* set built in print functions */
vgl_DrawFunAPI(df, DRAWFUN_APIPRINT);
/* vis context and set attributes */
vc = vis_VisContextBegin();
vis_VisContextSetIsoValType(vc, VIS_ISOVALSURFACE);
/* levels, set three evenly spaced levels */
levels = vis_LevelsBegin();
nlevels = 3;
vis_LevelsDef(levels, LEVELS_LINEAR, nlevels);
vis_LevelsSetMinMax(levels, 0., 2.);
vis_LevelsGenerate(levels, LEVELS_PADENDS);
/* color map */
cmap = vis_ColorMapBegin();
vis_ColorMapSetType(cmap, COLORMAP_TRUECOLOR);
vis_ColorMapSetRGB(cmap, nlevels + 1, 0, rgb);
/* transparency map */
tmap = vis_TransMapBegin();
/* create threshold object and set objects */
threshold = vis_ThresholdBegin();
vis_ThresholdSetObject(threshold, VGL_DRAWFUN, df);
vis_ThresholdSetObject(threshold, VIS_VISCONTEXT, vc);
vis_ThresholdSetObject(threshold, VIS_LEVELS, levels);
vis_ThresholdSetObject(threshold, VIS_COLORMAP, cmap);
vis_ThresholdSetObject(threshold, VIS_TRANSMAP, tmap);
/* draw threshold surfaces */
vis_ThresholdCurv(threshold, shex, xhex, VIS_NODATA, NULL);
/* free all objects */
vgl_DrawFunEnd(df);
vis_VisContextEnd(vc);
vis_LevelsEnd(levels);
vis_ColorMapEnd(cmap);
vis_TransMapEnd(tmap);
vis_ThresholdEnd(threshold);
return 0;
}
```

The output of this example program appears below. Note that a constant transparency is set and then three isosurfaces are output, each isosurface consists of a RGB color and two triangular polygons.

```
Trans
transp 0.000000
Color
c 1.000000 0.000000 0.000000
Polygon
type 0
npts 3
x 0.500000 0.000000 0.000000
x 0.500000 1.000000 0.000000
x 0.000000 1.000000 0.500000
vflag 1
v 0.707107 0.000000 0.707107
Polygon
type 0
npts 3
x 0.000000 1.000000 0.500000
x 0.000000 0.000000 0.500000
x 0.500000 0.000000 0.000000
vflag 1
v 0.707107 0.000000 0.707107
Color
c 0.000000 1.000000 0.000000
Polygon
type 0
npts 3
x 1.000000 0.000000 0.000000
x 1.000000 1.000000 0.000000
x 0.000000 1.000000 1.000000
vflag 1
v 0.707107 0.000000 0.707107
Polygon
type 0
npts 3
x 0.000000 1.000000 1.000000
x 0.000000 0.000000 1.000000
x 1.000000 0.000000 0.000000
vflag 1
v 0.707107 0.000000 0.707107
Color
c 0.000000 0.000000 1.000000
Polygon
type 0
npts 3
x 1.000000 1.000000 0.500000
x 0.500000 1.000000 1.000000
x 0.500000 0.000000 1.000000
vflag 1
v 0.707107 0.000000 0.707107
Polygon
type 0
npts 3
x 0.500000 0.000000 1.000000
x 1.000000 0.000000 0.500000
x 1.000000 1.000000 0.500000
vflag 1
v 0.707107 0.000000 0.707107
```

## 1.10. A First Program - C++ Version

The following program is a listing of the C++ version of the same “A First Program” listed above which used C language bindings.

```
#include "sam/base/base.h"
#include "legacy/vgl/vgl.h"
#include "sam/vis/vis.h"
static Vfloat xhex[8][3] = {{0., 0., 0.}, {1., 0., 0.}, {1., 1., 0.}, {0., 1., 0.},
{0., 0., 1.}, {1., 0., 1.}, {1., 1., 1.}, {0., 1., 1.}};
static Vfloat shex[8] = {0., 1., 1., 0., 1., 2., 2., 1.};
static Vfloat rgb[4][3] = {{.2, .2, .2}, {1., 0., 0.}, {0., 1., 0.}, {0., 0., 1.}};
/*----------------------------------------------------------------------
Generate isosurfaces in a hexahedron
----------------------------------------------------------------------*/
int
main()
{
vgl_DrawFun* df;
vis_VisContext* vc;
vis_Levels* levels;
vis_ColorMap* cmap;
vis_TransMap* tmap;
vis_Threshold* threshold;
Vint nlevels;
/* create draw function object */
df = new vgl_DrawFun;
/* set built in print functions */
df->API(DRAWFUN_APIPRINT);
/* vis context and set attributes */
vc = new vis_VisContext;
vc->SetIsoValType(VIS_ISOVALSURFACE);
/* levels, set three evenly spaced levels */
levels = new vis_Levels;
nlevels = 3;
levels->Def(LEVELS_LINEAR, nlevels);
levels->SetMinMax(0., 2.);
levels->Generate(LEVELS_PADENDS);
/* color map */
cmap = new vis_ColorMap;
cmap->SetType(COLORMAP_TRUECOLOR);
cmap->SetRGB(nlevels + 1, 0, rgb);
/* transparency map */
tmap = new vis_TransMap;
/* create threshold object and set objects */
threshold = new vis_Threshold;
threshold->SetObject(VGL_DRAWFUN, df);
threshold->SetObject(VIS_VISCONTEXT, vc);
threshold->SetObject(VIS_LEVELS, levels);
threshold->SetObject(VIS_COLORMAP, cmap);
threshold->SetObject(VIS_TRANSMAP, tmap);
/* draw threshold surfaces */
threshold->Curv(shex, xhex, VIS_NODATA, NULL);
/* free all objects */
delete df;
delete vc;
delete levels;
delete cmap;
delete tmap;
delete threshold;
return 0;
}
```

## 1.11. A First Program - FORTRAN Version

The following program is a listing of the FORTRAN version of the same “A First Program” listed above which used C language bindings.

```
C-----------------------------------------------------------------------
C Generate isosurfaces in a hexahedron
C-----------------------------------------------------------------------
PROGRAM INTRO1F
INCLUDE 'base/fortran/base.inc'
INCLUDE 'vgl/fortran/vgl.inc'
INCLUDE 'vis/fortran/vis.inc'
REAL XHEX(3,8), SHEX(8), RGB(3,4)
DATA XHEX /
$ 0.,0.,0., 1.,0.,0., 1.,1.,0., 0.,1.,0.,
$ 0.,0.,1., 1.,0.,1., 1.,1.,1., 0.,1.,1. /
DATA SHEX /
$ 0., 1., 1., 0.,
$ 1., 2., 2., 1. /
DATA RGB /
$ .2,.2,.2, 1.,0.,0., 0.,1.,0., 0.,0.,1. /
C
DOUBLE PRECISION DF,VC,LEVELS,CMAP,TMAP,THRESHOLD
INTEGER NLEVELS
C
C create draw function object
C
CALL VGLF_DRAWFUNBEGIN(DF)
C
C set built in print functions
C
CALL VGLF_DRAWFUNAPI(DF,DRAWFUN_APIPRINT)
C
C vis context and set attributes
C
CALL VISF_VISCONTEXTBEGIN(VC)
CALL VISF_VISCONTEXTSETISOVALTYPE (VC,VIS_ISOVALSURFACE)
C
C levels, set three evenly spaced levels
C
CALL VISF_LEVELSBEGIN(LEVELS)
NLEVELS = 3
CALL VISF_LEVELSDEF (LEVELS,LEVELS_LINEAR,NLEVELS)
CALL VISF_LEVELSSETMINMAX (LEVELS,0.,2.)
CALL VISF_LEVELSGENERATE (LEVELS,LEVELS_PADENDS)
C
C color map
C
CALL VISF_COLORMAPBEGIN(CMAP)
CALL VISF_COLORMAPSETTYPE (CMAP,COLORMAP_TRUECOLOR)
CALL VISF_COLORMAPSETRGB (CMAP,NLEVELS+1,0,RGB)
C
C transparency map
C
CALL VISF_TRANSMAPBEGIN(TMAP)
C
C create threshold object and set objects
C
CALL VISF_THRESHOLDBEGIN(THRESHOLD)
CALL VISF_THRESHOLDSETOBJECT (THRESHOLD,VGL_DRAWFUN,DF)
CALL VISF_THRESHOLDSETOBJECT (THRESHOLD,VIS_VISCONTEXT,VC)
CALL VISF_THRESHOLDSETOBJECT (THRESHOLD,VIS_LEVELS,LEVELS)
CALL VISF_THRESHOLDSETOBJECT (THRESHOLD,VIS_COLORMAP,CMAP)
CALL VISF_THRESHOLDSETOBJECT (THRESHOLD,VIS_TRANSMAP,TMAP)
C
C draw threshold surfaces
C
CALL VISF_THRESHOLDCURV (THRESHOLD,SHEX,XHEX,VIS_NODATA,0)
C
C free all objects
C
CALL VGLF_DRAWFUNEND (DF)
CALL VISF_VISCONTEXTEND (VC)
CALL VISF_LEVELSEND (LEVELS)
CALL VISF_COLORMAPEND (CMAP)
CALL VISF_TRANSMAPEND (TMAP)
CALL VISF_THRESHOLDEND (THRESHOLD)
C
END
```

## 1.12. A First Program - C# Version

The following program is a listing of the C# version of the same “A First Program” listed above which used C language bindings.

```
using System;
using System.Runtime.InteropServices;
using System.Reflection;
using System.Text;
using DevTools;
public class intro1 {
public static float [] xhex = {
0.0F,0.0F,0.0F, 1.0F,0.0F,0.0F, 1.0F,1.0F,0.0F, 0.0F,1.0F,0.0F,
0.0F,0.0F,1.0F, 1.0F,0.0F,1.0F, 1.0F,1.0F,1.0F, 0.0F,1.0F,1.0F };
public static float [] shex = {
0.0F, 1.0F, 1.0F, 0.0F,
1.0F, 2.0F, 2.0F, 1.0F };
public static float [] rgb = {
0.2F,0.2F,0.2F, 1.0F,0.0F,0.0F, 0.0F,1.0F,0.0F, 0.0F,0.0F,1.0F };
/*----------------------------------------------------------------------
Generate isosurfaces in a hexahedron
----------------------------------------------------------------------*/
public static void Main() {
IntPtr df;
IntPtr vc;
IntPtr levels;
IntPtr cmap;
IntPtr tmap;
IntPtr threshold;
int nlevels;
/* create draw function object */
df = vgl.DrawFunBegin();
/* set built in print functions */
vgl.DrawFunAPI (df,vgl.DRAWFUN_APIPRINT);
/* vis context and set attributes */
vc = vis.VisContextBegin ();
vis.VisContextSetIsoValType (vc,vis.VIS_ISOVALSURFACE);
/* levels, set three evenly spaced levels */
levels = vis.LevelsBegin ();
nlevels = 3;
vis.LevelsDef (levels,vis.LEVELS_LINEAR,nlevels);
vis.LevelsSetMinMax (levels,0.0F,2.0F);
vis.LevelsGenerate (levels,vis.LEVELS_PADENDS);
/* color map */
cmap = vis.ColorMapBegin ();
vis.ColorMapSetType (cmap,vis.COLORMAP_TRUECOLOR);
vis.ColorMapSetRGB (cmap,nlevels+1,0,rgb);
/* transparency map */
tmap = vis.TransMapBegin ();
/* create threshold object and set objects */
threshold = vis.ThresholdBegin ();
vis.ThresholdSetObject (threshold,vgl.VGL_DRAWFUN,df);
vis.ThresholdSetObject (threshold,vis.VIS_VISCONTEXT,vc);
vis.ThresholdSetObject (threshold,vis.VIS_LEVELS,levels);
vis.ThresholdSetObject (threshold,vis.VIS_COLORMAP,cmap);
vis.ThresholdSetObject (threshold,vis.VIS_TRANSMAP,tmap);
/* draw threshold surfaces */
vis.ThresholdCurv (threshold,shex,xhex,vis.VIS_NODATA,null);
/* free all objects */
vgl.DrawFunEnd (df);
vis.VisContextEnd (vc);
vis.LevelsEnd (levels);
vis.ColorMapEnd (cmap);
vis.TransMapEnd (tmap);
vis.ThresholdEnd (threshold);
}
}
```