Table of Contents

8. Tangent Curve Generation - Trace,Stream

The Trace and Stream modules support the generation of tangent curves to vector and tensor fields in 2D and 3D domains respectively. Tangent curves, also called streamlines, are everywhere tangent to a vector field. The calculation of streamlines involves integrating the vector field over some integration parameter. For fluid flow analysis, the vector field is the fluid velocity, the integration parameter is time and the resulting tangent line can be interpreted as the motion of a massless particle in a steady velocity field. Other possible vector fields include the gradient of a scalar field, a force field, or the principal vectors of a tensor field. VisTools directly supports the special case of computing the principal vectors of a tensor field. This feature is useful in generating "stress trajectories" or "principal load paths" in stress fields.

Tangent curve generation is central to all of the options provided for visualizing field information within the basic streamline motif. Stream ribbons and stream tubes and combinations of the two are provided to visualize the local streamwise vorticity and crossflow divergence of a vector field along the tangent curve. For the special case of tensor fields, the principal vectors orthogonal to the tangent direction may be used to develop a stream box or stream ellipse.

The Trace and Stream modules may be requested to perform a data interpolation function while generating a tangent curve. For example, the Stream module can interpolate a scalar field along a calculated streamline. Any tangent curve module which has been put into the data interpolation mode invokes "data" drawing functions rather than the graphics attribute and primitive drawing functions. This allows tangent curves to be used to sample other field variables to produce displays such as streamlines colored with density or temperature. In data interpolation mode, the value of the integration parameter (eg. time) is always passed as an additional row in the interpolated data vector. Data interpolation is activated in any tangent curve module by setting a DataInt object as an attribute object.

Table of Contents

8.1 2D Domains - Trace

Use Trace to generate tangent curves in 2D domains. The 2D domain may be embedded in 3D space, such as a surface in 3D space. The vector or tensor fields are defined in 3D, the local projection of the vector or tensor field onto the 2D surface is used for tangent curve generation. Tangent curves on surfaces are useful for generating "oil streaks" on surfaces in velocity fields and "stress directors" on shell elements in stress tensor fields. The functions associated with a Trace object are the following.

The functions associated with the Trace module are similar to those provided with the Stream module. Please see the Stream module for discussions of function usage.

Table of Contents

8.2 Attribute Objects

A Trace object uses DrawFun, Levels, VisContext, ColorMap and TransMap objects to define attributes to generate a stream visualization entity. A Trace object uses the same VisContext components as the Stream module. If a TransMap attribute object is not set any specified constant transparency or transparency mapping is ignored. Use a DataInt object to activate data interpolation. Please see Attribute Objects under Stream The following restrictions apply to the Trace module.

StreamType
The stream types VIS_STREAMLINE, VIS_STREAMBOX and VIS_STREAMELLIPSE are supported. Stream types VIS_STREAMRIBBON, VIS_STREAMTUBE and VIS_STREAMTWIST are not supported.
Table of Contents

8.3 Function Descriptions

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

Table of Contents , Trace

NAME

*vis_TraceBegin - create an instance of an Trace object

C SPECIFICATION

vis_Trace *vis_TraceBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an Trace object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. The cell topology is set to a 4 noded quadrilateral element. The initial streamline position is set to a natural coordinate of (0,0). The initial orientation vector is (1,0,0) and the initial time is set to zero.

Destroy an instance of a Trace object using 

     void vis_TraceEnd (vis_Trace *trace)

Return the current value of a Trace object error flag using 

     Vint vis_TraceError (vis_Trace *trace)

Table of Contents , Trace

NAME

vis_TraceComputeCoord - compute physical from natural coordinates

C SPECIFICATION

void vis_TraceComputeCoord (vis_Trace *trace,
                            Vfloat x[][3],
                            Vfloat r[2], 
                            Vfloat xcoord[3])

INPUT ARGUMENTS

trace        Pointer to Trace object.
x            Array of point locations defining domain
r            Natural coordinates

OUTPUT ARGUMENTS

xcoord       Physical coordinates

DESCRIPTION

Compute the physical coordinates of a point from its natural coordinates. The point locations of the domain are assumed to be a curvilinear domain.

Table of Contents , Trace

NAME

vis_TraceConvertCoord - compute natural from physical coordinates

C SPECIFICATION

void vis_TraceConvertCoord (vis_Trace *trace,
                            Vfloat x[][3],
                            Vfloat xcoord[3],
                            Vfloat r[2])

INPUT ARGUMENTS

trace        Pointer to Trace object.
x            Array of point locations defining domain
xcoord       Physical coordinates

OUTPUT ARGUMENTS

r            Natural coordinates

DESCRIPTION

Compute the natural coordinates of a point from its physical coordinates. The point locations of the domain are assumed to be a curvilinear domain.

The calculation of natural coordinates from physical coordinates is the inverse operation performed by vis_TraceComputeCoord and is much more computationally intensive than the calculation of physical coordinates from natural coordinates. Note that this operation may fail for highly distorted or inverted elements. Use the function vis_TraceGetConvert to get the conversion error flag.

Table of Contents , Trace

NAME

vis_TraceCurv - compute streamline on a curvilinear surface

C SPECIFICATION

void vis_TraceCurv (vis_Trace *trace,
                    Vint rank,
                    Vfloat s[],
                    Vfloat x[][3])

INPUT ARGUMENTS

trace        Pointer to Trace object.
rank         Type of field data, either vector or tensor
             =VIS_VECTOR             Vector field
             =VIS_TENSOR             Tensor field
s            Array of vector or tensor field values
x            Array of point locations defining domain

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper rank is specified.

DESCRIPTION

Compute a streamline on a curvilinear surface in field s at point locations x. Use vis_TraceSetEnter to specify the world or natural coordinates at which to start streamline integration.

Table of Contents , Trace

NAME

vis_TraceGetConvert - get coordinate conversion error flag

C SPECIFICATION

void vis_TraceGetConvert (vis_Trace *trace,
                          Vint *convertflag)

INPUT ARGUMENTS

trace        Pointer to Trace object.

OUTPUT ARGUMENTS

convertflag  Current vis_TraceConvertCoord function error flag.
             =VIS_OFF         No conversion error
             =VIS_ON          Conversion error

DESCRIPTION

Get the conversion error flag of the previous call to vis_TraceConvertCoord.

Table of Contents , Trace

NAME

vis_TraceGetExit - get terminal state of streamline integration

C SPECIFICATION

void vis_TraceGetExit (vis_Trace *trace,
                       Vint iop,
                       Vint *status, 
                       Vint *edgenumber,
                       Vfloat xr[3],
                       Vfloat v[3], Vfloat w[3],
                       Vfloat *t)

INPUT ARGUMENTS

trace        Pointer to Trace object.
iop          World coordinate flag
             =0            Natural coordinates
             =1            World coordinates

OUTPUT ARGUMENTS

status       Integration termination status
             =VIS_STREAMZERO         Vector field zero internal to cell
             =VIS_STREAMCOMPUTE      Inverted or degenerate cell
             =VIS_STREAMEXIT         Streamline exited cell at edge
             =VIS_STREAMBRANCH       Streamline branched internal to cell
             =VIS_STREAMMAXSTEPS     Streamline required more than fixed
                                     maximum number of time steps.
             =VIS_STREAMMAXEXCEEDED  Streamline exceeded max time or cells
edgenumber   Edge number of cell through which streamline exited.  If
             the streamline terminated internal to the cell then
             the edge number is set to zero.
xr           Termination position of stream in world or natural coordinates
v, w         Termination orientation vectors
t            Termination time

DESCRIPTION

Get the termination conditions of streamline integration. This function will return undefined information if a previous call to vis_TraceCurv has not been made. The terminal streamline position is specified in world or natural coordinates. In the case of natural coordinates only the first two components of xr are returned. The orientation vectors, v and w, are only meaningful for stream types VIS_STREAMBOX and VIS_STREAMELLIPSE. For these stream types, v and w are in the directions of the minimum and middle principal vectors, scaled to the principal values.

A termination status of VIS_STREAMBRANCH can only occur as a result of streamline generation in a tensor field. A termination status of VIS_STREAMMAXEXCEEDED indicates that either the TRACE_MAXCELL parameter set using vis_TraceSetParami or the TRACE_MAXTIME parameter set using vis_TraceSetParamf have been exceeded.

Table of Contents , Trace

NAME

vis_TraceSetContinuous - set continuous line mode

C SPECIFICATION

void vis_TraceSetContinuous (vis_Trace *trace,
                             Vint flag)

INPUT ARGUMENTS

trace        Pointer to Trace object.
flag         Flag for beginning of new continuous line
             =VIS_ON           Starts continuous line mode
             =VIS_OFF          Terminates continuous line mode

OUTPUT ARGUMENTS

None

ERRORS

None

DESCRIPTION

Indicate the start of a new continuous line. When in continuous line mode, successive lines drawn with vis_TraceCurv with VIS_CYLINDER line style will have their end curves matched for a continuous cylindrical display. A new call with flag set to VIS_ON indicates the start of a new continuous line and terminates any previously continuous line. If flag is set to VIS_OFF the continuous line mode is terminated. Default value for flag is VIS_OFF.

Table of Contents , Trace

NAME

vis_TraceSetEdgeFlag - set wall edges

C SPECIFICATION

void vis_TraceSetEdgeFlag (vis_Trace *trace,
                           Vint flag)

INPUT ARGUMENTS

trace        Pointer to Trace object.
flag         Element edge bit flags to indicate wall edges.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set edge flag. The flag argument contains bit flags indicating which edges are to be considered to be wall edges. A wall edge is an edge which should have zero velocity and stream lines should not penetrate. The velocity field normal to the indicated walls is attenutated as the stream line approaches the walls while the tangent velocity field remains unchanged. The default edge flag is 0.

Table of Contents , Trace

NAME

vis_TraceSetEnter - set initial conditions for streamline integration

C SPECIFICATION

void vis_TraceSetEnter (vis_Trace *trace,
                        Vint iop,
                        Vfloat xr[3],
                        Vfloat v[3], Vfloat w[3],
                        Vfloat t)

INPUT ARGUMENTS

trace        Pointer to Trace object.
iop          World coordinate flag
             =0            Natural coordinates
             =1            World coordinates
xr           Initial position of stream in world or natural coordinates
v, w         Initial orientation vectors
t            Initial time

OUTPUT ARGUMENTS

None

DESCRIPTION

Set the initial conditions for streamline integration. The initial streamline position is specified in either world or natural coordinates. In the case of natural coordinates only the first two components of xr are used. The initial orientation vectors, v and w are currently ignored for all stream types.

Table of Contents , Trace

NAME

vis_TraceSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_TraceSetObject (tvis_Trace *trace,
                         Vint objecttype,
                         Vobject *object)

INPUT ARGUMENTS

trace         Pointer to Trace object.
objecttype   The name of the object type to be set.
             =VIS_COLORMAP           ColorMap object
             =VIS_DATAINT            DataInt object
             =VGL_DRAWFUN            DrawFun object
             =VIS_LEVELS             Levels object
             =VIS_TRANSMAP           TransMap object
             =VIS_VISCONTEXT         VisContext object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. If a DataInt object is set then data interpolation is activated. To deactivate data interpolation, set a NULL DataInt object pointer.

Table of Contents , Trace

NAME

vis_TraceSetParam - set parameters for streamline integration

C SPECIFICATION

void vis_TraceSetParamf (vis_Trace *trace,
                         Vint ptype,
                         Vfloat fparam)
void vis_TraceSetParami (vis_Trace *trace,
                         Vint ptype,
                         Vint iparam)

INPUT ARGUMENTS

trace         Pointer to Trace object.
ptype        Parameter type to set.
             =TRACE_MAXCELL           Maximum number of cells
             =TRACE_MAXTIME           Maximum time
             =TRACE_ZEROMAG           Zero velocity magnitude
fparam       Specifies the float value that ptype will be set to.
iparam       Specifies the integer value that ptype will be set to.

OUTPUT ARGUMENTS

none

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify parameters for controlling streamline integration. The parameters TRACE_MAXCELL, TRACE_MAXTIME and TRACE_ZEROMAG specify streamline termination parameters and are useful for stopping streamlines which get caught in recirculation or stagnation zones. Any number of termination parameters may be in effect. A streamline is terminated if any active termination parameter is exceeded.

The parameter TRACE_MAXCELL is the maximum number of cells which a streamline traverses in a single call to vis_TraceCurv. Setting TRACE_MAXCELL to zero turns off the use of maximum cells to terminate streamline integration. If this parameter is exceeded, the exit status returned by vis_TraceGetExit is set to VIS_STREAMMAXEXCEEDED. By default TRACE_MAXCELL is set to TRACE_MAXSTEPS (2048)

The parameter TRACE_MAXTIME is the maximum time which a streamline can reach. This parameter is set using vis_TraceSetEnter and returned using vis_TraceGetExit. Setting TRACE_MAXTIME to zero turns off the use of time to terminate streamline integration. If this parameter is exceeded, the exit status returned by vis_TraceGetExit is set to VIS_STREAMMAXEXCEEDED. By default TRACE_MAXTIME is 0.

The parameter TRACE_ZEROMAG is a velocity magnitude tolerance. If the streamline reaches a point in with the velocity magnitude falls below this value the streamline is terminated. If this parameter is exceeded, the exit status returned by vis_TraceGetExit is set to VIS_STREAMZERO. By default TRACE_ZEROMAG is approximately the minimum representable single precision float value.

Table of Contents , Trace

NAME

vis_TraceSetTopology - set cell topology

C SPECIFICATION

void vis_TraceSetTopology (vis_Trace *trace,
                           Vint shape,
                           Vint maxi, 
                           Vint maxj)

INPUT ARGUMENTS

trace        Pointer to Trace object.
shape        Cell shape parameter
             =VIS_SHAPETRI           Triangle
             =VIS_SHAPEQUAD          Quadrilateral
             =VIS_SHAPEPOLYGON       Polygon
maxi         Topology parameters
maxj

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if a maxi or maxj less than 0 or equal to 1 is input. VIS_ERROR_ENUM is generated if an improper shape is input.

DESCRIPTION

Set cell topology. All subsequent draw and computation methods assume cells of this topology. See section VisTools, Computational Cells for a description of element topology conventions.

Table of Contents

8.4 3D Domains - Stream

Use Stream to generate tangent curves in 3D domains. Several different types of tangent curves may be generated such as ribbons, tubes or ellipses. These alternate types help to represent field divergence or curl. The functions associated with a Stream object are the following.

The initial conditions for streamline integration are set using vis_StreamSetEnter. The initial position of a streamline is specified in natural coordinates. A special function, vis_StreamConvertCoord is provided to convert physical coordinates into natural coordinates. The current cell topology is specified using vis_StreamSetTopology. If the current cell topology is polyhedral, ie VIS_SHAPEPOLYHED, it is recommended for performance reasons that the polyhedral node connectivity be entered using vis_StreamSetElemNode and the use of it toggled using vis_StreamSetParami.

A streamline is computed using vis_StreamCurv. The streamline computation terminates if the streamline exits a face of the element or cell array, encounters a zero length vector or branches (tensor fields only) at a point internal to the element or cell array. Use vis_StreamGetExit to return information about the termination status of a streamline. In particular the face number through which the streamline exited can be used to indicate an adjacent element in which the streamline may continue to be propagated.

If a streamline is to be continued in an adjacent element or cell array, use vis_StreamComputeCoord to compute the physical coordinates of the exit point of the streamline from the natural coordinates provided by vis_StreamGetExit. Use the exit face number to point to the element or cell array into which the streamline is propagating. Call vis_StreamConvertCoord to calculate the natural coordinates of the entrance position of the streamline in the new element or cell array. Set the initial conditions for streamline generation with vis_StreamSetEnter and continue the generation of the streamline in the new element or cell array with vis_StreamCurv. Note that the function call vis_StreamConvertCoord may be unable to compute natural coordinates due to severe element distortion or element inversions and does not call the error handler. Use the function vis_StreamGetConvert to get the conversion error status.

Table of Contents

8.5 Attribute Objects

A Stream object uses DrawFun, Levels, VisContext, ColorMap and TransMap objects to define attributes to generate a stream visualization entity. If size is mapped to field value, then the field value minimum and maximum set in the Levels object using vis_LevelsSetMinMax are used to compute the maximum absolute value of the field value which is mapped to maximum size. If a TransMap attribute object is not set any specified constant transparency or transparency mapping is ignored. Use a DataInt object to activate data interpolation. A Stream object uses the following VisContext components.

Color
Stream line, stream box or stream ellipse color
Draw
Flag to call graphics attribute and graphics primitive drawing functions.
Flags
OR the following flags: VIS_TIMEREVERSE integrates the tangent curve in negative time.
LineWidth
Line width of streamlines
LineStyle
Line style of streamlines
MapColor
Flag to map stream box and stream ellipse color to maximum principal value of tensor field. This option requires a Levels object.
MapSize
Flag to map the dimensions of stream box or stream ellipse to minimum and middle principal values of tensor field.
MinorColor
Stream ribbon, stream tube or stream twist color. Stream lines drawn in conjunction with these stream types are drawn using the Color component.
PointSize
Point size
Shade
Flag to apply light source shading
Size
Unit line width of cylindrical line style. The radius of stream tubes do not exceed this value. The radius of stream boxes and stream ellipses at maximum magnitude of field value.
StreamType
One of the following stream types: VIS_STREAMLINE draws a simple streamline in a vector or tensor field; VIS_STREAMPOINT draws discrete points at intersections of streamlines with cell faces. VIS_STREAMRIBBON draws a streamline and a constant width ribbon about the streamline which indicates the streamwise vorticity of the vector field. VIS_STREAMTUBE draws a variable radius stream tube which indicates the local cross stream divergence of the vector field. VIS_STREAMTWIST draws a variable radius stream tube and a line on the tube which indicate both the the local divergence and vorticity of the vector field. VIS_STREAMBOX draws a variable dimension stream box to indicate the magnitude and direction of the middle and minimum principal stresses in a tensor field. VIS_STREAMELLIPSE draws a variable dimension stream ellipse to indicate the magnitude and direction of the middle and minimum principal stresses in a tensor field.
Trans
Stream transparency for filled stream entities.
UnitTol
Unit tolerance used to determine a zero velocity. If the streamline is evaluated with a velocity magnitude which is less than the unit tolerance times the streamline entrance velocity magnitude then the streamline is terminated with a zero velocity status.
Table of Contents

8.6 Function Descriptions

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

Table of Contents , Stream

NAME

*vis_StreamBegin - create an instance of a Stream object

C SPECIFICATION

vis_Stream *vis_StreamBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a Stream object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL. The cell topology is set to a 8 noded hexahedral element. The initial streamline position is set to a natural coordinate of (0,0,0). The initial orientation vector is (1,0,0) and the initial time is set to zero.

Destroy an instance of a Stream object using 

     void vis_StreamEnd (vis_Stream *stream)

Return the current value of a Stream object error flag using 

     Vint vis_StreamError (vis_Stream *stream)

Table of Contents , Stream

NAME

vis_StreamComputeCoord - compute physical from natural coordinates

C SPECIFICATION

void vis_StreamComputeCoord (vis_Stream *stream,
                             Vfloat x[][3],
                             Vfloat r[3],
                             Vfloat xcoord[3])

INPUT ARGUMENTS

stream       Pointer to Stream object.
x            Array of point locations defining domain
r            Natural coordinates

OUTPUT ARGUMENTS

xcoord       Physical coordinates

DESCRIPTION

Compute the physical coordinates of a point from its natural coordinates. The point locations of the domain are assumed to be a curvilinear domain.

Table of Contents , Stream

NAME

vis_StreamConvertCoord - compute natural from physical coordinates

C SPECIFICATION

void vis_StreamConvertCoord (vis_Stream *stream,
                             Vfloat x[][3],
                             Vfloat xcoord[3],
                             Vfloat r[3])

INPUT ARGUMENTS

stream       Pointer to Stream object.
x            Array of point locations defining domain
xcoord       Physical coordinates

OUTPUT ARGUMENTS

r            Natural coordinates

DESCRIPTION

Compute the natural coordinates of a point from its physical coordinates. The point locations of the domain are assumed to be a curvilinear domain.

The calculation of natural coordinates from physical coordinates is the inverse operation performed by vis_StreamComputeCoord and is much more computationally intensive than the calculation of physical coordinates from natural coordinates. Note that this operation may fail for highly distorted or inverted elements. Use the function vis_StreamGetConvert to get the conversion error flag.

Table of Contents , Stream

NAME

vis_StreamCurv - compute streamline in curvilinear volume

C SPECIFICATION

void vis_StreamCurv (vis_Stream *stream,
                     Vint rank,
                     Vfloat s[],
                     Vfloat x[][3])

INPUT ARGUMENTS

stream       Pointer to Stream object.
rank         Type of field data, either vector or tensor
             =VIS_VECTOR             Vector field
             =VIS_TENSOR             Tensor field
s            Array of vector or tensor field values
x            Array of point locations defining domain

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper rank is specified.

DESCRIPTION

Compute a streamline in a curvilinear volume in field s at point locations x.

Table of Contents , Stream

NAME

vis_StreamGetConvert - get coordinate conversion error flag

C SPECIFICATION

void vis_StreamGetConvert (vis_Stream *stream,
                           Vint *convertflag)

INPUT ARGUMENTS

stream       Pointer to Stream object.

OUTPUT ARGUMENTS

convertflag  Current vis_StreamConvertCoord function error flag.
             =VIS_OFF         No conversion error
             =VIS_ON          Conversion error

DESCRIPTION

Get the conversion error flag of the previous call to vis_StreamConvertCoord.

Table of Contents , Stream

NAME

vis_StreamGetExit - get terminal state of streamline integration

C SPECIFICATION

void vis_StreamGetExit (vis_Stream *stream,
                        Vint iop,
                        Vint *status,
                        Vint *facenumber,
                        Vfloat xr[3],
                        Vfloat v[3], Vfloat w[3],
                        Vfloat *t)

INPUT ARGUMENTS

stream       Pointer to Stream object.
iop          World coordinate flag
             =0            Natural coordinates
             =1            World coordinates

OUTPUT ARGUMENTS

status       Integration termination status
             =VIS_STREAMZERO         Vector field zero internal to cell
             =VIS_STREAMCOMPUTE      Inverted or degenerate cell
             =VIS_STREAMEXIT         Streamline exited cell at face
             =VIS_STREAMBRANCH       Streamline branched internal to cell
             =VIS_STREAMMAXSTEPS     Streamline required more than fixed
                                     maximum number of time steps.
             =VIS_STREAMMAXEXCEEDED  Streamline exceeded max time or cells
facenumber   Face number of cell through which streamline exited.  If
             the streamline terminated internal to the cell then
             the face number is set to zero.
xr           Termination position of stream in world or natural coordinates
v, w         Termination orientation vectors
t            Termination time

DESCRIPTION

Get the termination conditions of streamline integration. This function will return undefined information if a previous call to vis_StreamCurv has not been made. The terminal streamline position is specified in world or natural coordinates. The orientation vectors, v and w are interpreted differently depending upon stream type. Please see vis_StreamSetEnter for a discussion of their interpretation. Generally, v and w obtained from this function should be used as input to vis_StreamSetEnter to continue a stream.

A termination status of VIS_STREAMBRANCH can only occur as a result of streamline generation in a tensor field. A termination status of VIS_STREAMMAXEXCEEDED indicates that either the STREAM_MAXCELL parameter set using vis_StreamSetParami or the STREAM_MAXTIME parameter set using vis_StreamSetParamf have been exceeded.

Table of Contents , Stream

NAME

vis_StreamSetContinuous - set continuous line mode

C SPECIFICATION

void vis_StreamSetContinuous (vis_Stream *stream,
                             Vint flag)

INPUT ARGUMENTS

stream       Pointer to Stream object.
flag         Flag for beginning of new continuous line
             =VIS_ON           Starts continuous line mode
             =VIS_OFF          Terminates continuous line mode

OUTPUT ARGUMENTS

None

ERRORS

None

DESCRIPTION

Indicate the start of a new continuous line. When in continuous line mode, successive lines drawn with vis_StreamCurv with VIS_CYLINDER line style will have their end curves matched for a continuous cylindrical display. A new call with flag set to VIS_ON indicates the start of a new continuous line and terminates any previously continuous line. If flag is set to VIS_OFF the continuous line mode is terminated. Default value for flag is VIS_OFF.

Table of Contents , Stream

NAME

vis_StreamSetElemNode - set input polyhedral cell connectivity

C SPECIFICATION

void vis_StreamSetElemNode (vis_Stream *stream,
                            Vint ix[])

INPUT ARGUMENTS

stream       Pointer to Stream object.
ix           Element connectivity

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OPERATION is generated if the element connectivity is not water tight.

DESCRIPTION

Set polyhedral element connectivity. This information is currently only required for element shape VIS_SHAPEPOLYHED. The use of polyhedral connectivity is optional and is toggled using vis_StreamSetParami.

Table of Contents , Stream

NAME

vis_StreamSetEnter - set initial conditions for streamline integration

C SPECIFICATION

void vis_StreamSetEnter (vis_Stream *stream,
                         Vint iop,
                         Vfloat xr[3],
                         Vfloat v[3], Vfloat w[3],
                         Vfloat t)

INPUT ARGUMENTS

stream       Pointer to Stream object.
iop          World coordinate flag
             =0            Natural coordinates
             =1            World coordinates
xr           Initial position of stream in world or natural coordinates
v, w         Initial orientation vectors
t            Initial time

OUTPUT ARGUMENTS

None

DESCRIPTION

Set the initial conditions for streamline integration. The initial streamline position is specified in world or natural coordinates. The initial orientation vectors, v and w, are only required for stream types VIS_STREAMRIBBON, VIS_STREAMTUBE and VIS_STREAMTWIST.

To start a streamline, input orientation vectors which are orthogonal to the velocity vector. The orientation vectors should themselves be orthogonal. For stream type VIS_STREAMRIBBON, v is the ribbon direction and width, w need only be orthogonal to v. It is used only to generate Gouraud shaded ribbons if requested. For stream types VIS_STREAMTUBE and VIS_STREAMTWIST, v and w indicate the initial radii of the stream tube. Generally v and w are of equal magnitude in this case, however they do not have to be. For VIS_STREAMTWIST, the direction of v also defines the orientation of the twist stream line on the stream tube. The function vis_StreamComputeCoord can be used to compute the velocity at a point by substituting velocity vectors for the coordinate vectors.

To continue a stream line, use the orientation vectors output by vis_StreamGetExit as input to this function.

Table of Contents , Stream

NAME

vis_StreamSetFaceFlag - set wall faces

C SPECIFICATION

void vis_StreamSetFaceFlag (vis_Stream *stream,
                            Vint flag)

INPUT ARGUMENTS

stream       Pointer to Stream object.
flag         Element face bit flags to indicate wall faces.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set face flag. The flag argument contains bit flags indicating which faces are to be considered to be wall faces. A wall face is an face which should have zero velocity and stream lines should not penetrate. The velocity field normal to the indicated walls is attenutated as the stream line approaches the walls while the tangent velocity field remains unchanged. The default face flag is 0.

Table of Contents , Stream

NAME

vis_StreamSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_StreamSetObject (vis_Stream *stream,
                          Vint objecttype,
                          Vobject *object)

INPUT ARGUMENTS

stream       Pointer to Stream object.
objecttype   The name of the object type to be set.
             =VIS_DATAINT            DataInt object
             =VGL_DRAWFUN            DrawFun object
             =VIS_LEVELS             Levels object
             =VIS_VISCONTEXT         VisContext object
             =VIS_COLORMAP           ColorMap object
             =VIS_TRANSMAP           TransMap object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. If a DataInt object is set then data interpolation is activated. To deactivate data interpolation, set a NULL DataInt object pointer.

Table of Contents , Stream

NAME

vis_StreamSetParam - set parameters for streamline integration

C SPECIFICATION

void vis_StreamSetParamf (vis_Stream *stream,
                          Vint ptype,
                          Vfloat fparam)
void vis_StreamSetParami (vis_Stream *stream,
                          Vint ptype,
                          Vint iparam)

INPUT ARGUMENTS

stream       Pointer to Stream object.
ptype        Parameter type to set.
             =STREAM_MAXCELL          Maximum number of cells
             =STREAM_MAXTIME          Maximum time
             =STREAM_ZEROMAG          Zero velocity magnitude
             =STREAM_USERELEMNODE     Enable using polyhedral connectivity
fparam       Specifies the float value that ptype will be set to.
iparam       Specifies the integer value that ptype will be set to.

OUTPUT ARGUMENTS

none

ERRORS

VIS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Specify parameters for controlling streamline integration. The parameters STREAM_MAXCELL, STREAM_MAXTIME and STREAM_ZEROMAG specify streamline termination parameters and are useful for stopping streamlines which get caught in recirculation or stagnation zones. Any number of termination parameters may be in effect. A streamline is terminated if any active termination parameter is exceeded.

The parameter STREAM_MAXCELL is the maximum number of cells which a streamline traverses in a single call to vis_StreamCurv. Setting STREAM_MAXCELL to zero turns off the use of maximum cells to terminate streamline integration. If this parameter is exceeded, the exit status returned by vis_StreamGetExit is set to VIS_STREAMMAXEXCEEDED. By default STREAM_MAXCELL is set to STREAM_MAXSTEPS (2048)

The parameter STREAM_MAXTIME is the maximum time which a streamline can reach. This parameter is set using vis_StreamSetEnter and returned using vis_StreamGetExit. Setting STREAM_MAXTIME to zero turns off the use of time to terminate streamline integration. If this parameter is exceeded, the exit status returned by vis_StreamGetExit is set to VIS_STREAMMAXEXCEEDED. By default STREAM_MAXTIME is 0.

The parameter STREAM_ZEROMAG is a velocity magnitude tolerance. If the streamline reaches a point in with the velocity magnitude falls below this value the streamline is terminated. If this parameter is exceeded, the exit status returned by vis_StreamGetExit is set to VIS_STREAMZERO. By default STREAM_ZEROMAG is approximately the minimum representable single precision float value.

The parameter STREAM_USERELEMNODE is used to enable the use of the user specified polyhedral connectivity using vis_StreamSetElemNode. By default, STREAM_USERELEMNODE is off.

Table of Contents , Stream

NAME

vis_StreamSetTopology - set cell topology

C SPECIFICATION

void vis_StreamSetTopology (vis_Stream *stream,
                            Vint shape,
                            Vint maxi, 
                            Vint maxj, 
                            Vint maxk)

INPUT ARGUMENTS

stream       Pointer to Stream object.
shape        Cell shape parameter
             =VIS_SHAPETET           Tetrahedron
             =VIS_SHAPEPYR           Pyramid
             =VIS_SHAPEWED           Wedge
             =VIS_SHAPEHEX           Hexahedron
             =VIS_SHAPEPOLYHED       Polyhedron
maxi         Topology parameters
maxj
maxk

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if a maxi, maxj or maxk less than 0 or equal to 1 is input. VIS_ERROR_ENUM is generated if an improper shape is input.

DESCRIPTION

Set cell topology. All subsequent draw and computation methods assume cells of this topology. See section VisTools, Computational Cells for a description of element topology conventions.