1. Introduction

The VisTools library from Visual Kinematics, Inc. 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).

../../_images/vistools-intro1.gif

Figure 1-1, Line connectivity, Linear (2) and Parabolic (3)

../../_images/vistools-intro2.gif

Figure 1-2, Triangle connectivity, Serendipity Linear (2,0) and Parabolic (3,0), Lagrange Parabolic (3,3)

../../_images/vistools-intro3.gif

Figure 1-3, Quadrilateral connectivity, Serendipity Linear (2,0) and Parabolic (3,0), Lagrange Parabolic (3,3)

../../_images/vistools-intro4.gif

Figure 1-4, Tetrahedron connectivity, Serendipity Linear (2,0,0) and Parabolic (3,0,0), Lagrange Parabolic (3,3,3)

../../_images/vistools-intro5.gif

Figure 1-5, Pyramid connectivity, Serendipity Linear (2,0,0) and Parabolic (3,0,0), Lagrange Parabolic (3,3,3)

../../_images/vistools-intro6.gif

Figure 1-6, Wedge connectivity, Serendipity Linear (2,0,0) and Parabolic (3,0,0)

../../_images/vistools-intro6a.gif

Figure 1-6a, Wedge connectivity, Lagrange Parabolic (3,3,3)

../../_images/vistools-intro7.gif

Figure 1-7, Hexahedron connectivity, Serendipity Linear (2,0,0) and Parabolic (3,0,0)

../../_images/vistools-intro7a.gif

Figure 1-7a, Hexahedron connectivity, Lagrange Parabolic (3,3,3)

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.

../../_images/vistools-intro7b.gif

Figure 1-7b, Pentahedral connectivity, (3,0,3), Hexahedral connectivity, (2,0,3)

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

Figure 1-7c, Polygon connectivity, (6,5,1), Polyhedron connectivity, (28,11,6)

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.

../../_images/vistools-intro8.gif

Figure 1-8, Curvilinear, Rectilinear and Uniform grids

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_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 = 3

    shape = (topo >> 28) & 0x000f
    maxi = (topo >> 16) & 0x0fff
    maxj = (topo >> 8) & 0x00ff
    maxk = (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.

  • 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

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

Shell stress resultants s (Nxx, Nyy, Nxy, Mxx, Myy, Mxy, Qxz, Qyz)
Shell strain curvatures e (Exx, Eyy, Exy, Kxx, Kyy, Kxy, Txz, Tyz)
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
../../_images/vfetools-prop1.gif

Figure 1-9, Sign Conventions for Shell Stress Resultants

Beam stress resultants s (Nxx, Myy, Mzz, Torque, Qxy, Qzx)
Beam strain curvatures e (Exx, Kyy, Kzz, Twist, Txy, Tzx)
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
../../_images/vfetools-prop2.gif

Figure 1-9, Sign Conventions for Beam Stress Resultants

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 devtools.a archive file. Then from the devtools/src/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/devtools.a *.o

The object files may be deleted after the devtools.a archive is successfully created. To compile the vgl source, change directory to devtools/src/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 devtools.a archive issue

ar rs ../../lib/SGI/devtools.a *.o

To compile the base source, change directory to devtools/src/base and compile using

cc -c -O2 *.c

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

ar rs ../../lib/SGI/devtools.a *.o

Again object files may deleted at this time. At this point the devtools.a archive contains all vis, vgl and base objects. Place the devtools.a archive immediately before the graphics subsystem libraries in the load line. A devtools.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 "vgl/vgl.h"
#include "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 = 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 "base/base.h"
#include "vgl/vgl.h"
#include "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);
   }
}