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.

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.

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_STREAMPOINT, VIS_STREAMBOX and VIS_STREAMELLIPSE are supported. Stream types VIS_STREAMRIBBON, VIS_STREAMTUBE and VIS_STREAMTWIST are not supported.

8.3. Function Descriptions

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

vis_Trace *vis_TraceBegin(void)

create an instance of a Trace object

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)

Returns

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

void vis_TraceEnd(vis_Trace *p)

destroy an instance of a Trace object

See vis_TraceBegin()

Vint vis_TraceError(vis_Trace *p)

return the current value of a Trace object error flag

See vis_TraceBegin()

void vis_TraceSetObject(vis_Trace *p, Vint objecttype, Vobject *object)

set pointers to attribute objects

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.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters

  • p – Pointer to Trace object.

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

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

void vis_TraceSetParami(vis_Trace *p, Vint ptype, Vint iparam)

set parameters for streamline integration

See vis_TraceSetParamf()

Parameters

  • p – Pointer to Trace object.

  • ptype – Parameter type to set. 

    x=TRACE_MAXCELL           Maximum number of cells
 =TRACE_MAXTIME           Maximum time
 =TRACE_ZEROMAG           Zero velocity magnitude

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

void vis_TraceSetParamf(vis_Trace *p, Vint ptype, Vfloat fparam)

set parameters for streamline integration

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.

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters

  • p – Pointer to Trace object.

  • ptype – Parameter type to set. 

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

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

set cell topology

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

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.

Parameters

  • p – Pointer to Trace object.

  • shape – Cell shape parameter 

    x=VIS_SHAPETRI           Triangle
 =VIS_SHAPEQUAD          Quadrilateral
 =VIS_SHAPEPOLYGON       Polygon

  • maxi – Topology parameter

  • maxj – Topology parameter

void vis_TraceSetEdgeFlag(vis_Trace *p, Vint flag)

set wall edges

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.

Parameters

  • p – Pointer to Trace object.

  • flag – Element edge bit flags to indicate wall edges.

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

set initial conditions for streamline integration

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.

Parameters

  • p – 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 – Initial orientation vectors

  • w – Initial orientation vectors

  • t – Initial time

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

get terminal state of streamline integration

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.

Parameters

  • p – Pointer to Trace object.

  • iop – World coordinate flag 

    =0            Natural coordinates
=1            World coordinates

  • status – [out] Integration termination status 

    x=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 – [out] 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 – [out] Termination position of stream in world or natural coordinates

  • v – [out] Termination orientation vectors

  • w – [out] Termination orientation vectors

  • t – [out] Termination time

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

compute physical from natural coordinates

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

Parameters

  • p – Pointer to Trace object.

  • x – Array of point locations defining domain

  • r – Natural coordinates

  • xcoord – [out] Physical coordinates

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

compute natural from physical coordinates

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.

Parameters

  • p – Pointer to Trace object.

  • x – Array of point locations defining domain

  • xcoord – Physical coordinates

  • r – [out] Natural coordinates

void vis_TraceGetConvert(vis_Trace *p, Vint *convertflag)

get coordinate conversion error flag

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

Parameters

  • p – Pointer to Trace object.

  • convertflag – [out] Current vis_TraceConvertCoord() function error flag. 

    x=VIS_OFF         No conversion error
 =VIS_ON          Conversion error

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

compute streamline on a curvilinear surface

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.

Errors

VIS_ERROR_ENUM is generated if an improper rank is specified.

Parameters

  • p – Pointer to Trace object.

  • rank – Type of field data, either vector or tensor 

    x=VIS_VECTOR             Vector field
 =VIS_TENSOR             Tensor field

  • s – Array of vector or tensor field values

  • x – Array of point locations defining domain

void vis_TraceSetContinuous(vis_Trace *p, Vint flag)

set continuous line mode

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.

Parameters

  • p – Pointer to Trace object.

  • flag – Flag for beginning of new continuous line 

    x=VIS_ON           Starts continuous line mode
 =VIS_OFF          Terminates continuous line mode

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.

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.

8.6. Function Descriptions

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

vis_Stream *vis_StreamBegin(void)

create an instance of a Stream object

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)

Returns

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

void vis_StreamEnd(vis_Stream *p)

destroy an instance of a Stream object

See vis_StreamBegin()

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

set pointers to attribute objects

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.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters

  • p – Pointer to Stream object.

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

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

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

set cell topology

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

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.

Parameters

  • p – Pointer to Stream object.

  • shape – Cell shape parameter 

    x=VIS_SHAPETET           Tetrahedron
 =VIS_SHAPEPYR           Pyramid
 =VIS_SHAPEWED           Wedge
 =VIS_SHAPEHEX           Hexahedron
 =VIS_SHAPEPOLYHED       Polyhedron

  • maxi – Topology parameter

  • maxj – Topology parameter

  • maxk – Topology parameter

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

set input polyhedral cell connectivity

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

Errors

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

Parameters

  • p – Pointer to Stream object.

  • ix – Element connectivity

void vis_StreamSetParami(vis_Stream *p, Vint type, Vint iparam)

set parameters for streamline integration

See vis_StreamSetParamf()

Parameters

  • p – Pointer to Stream object.

  • type – Parameter type to set. 

    x=STREAM_MAXCELL          Maximum number of cells
 =STREAM_MAXTIME          Maximum time
 =STREAM_ZEROMAG          Zero velocity magnitude
 =STREAM_USERELEMNODE     Enable using polyhedral connectivity

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

void vis_StreamSetParamf(vis_Stream *p, Vint ptype, Vfloat fparam)

set parameters for streamline integration

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.

Errors

VIS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters

  • p – Pointer to Stream object.

  • ptype – Parameter type to set. 

    x=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 type will be set to.

void vis_StreamSetFaceFlag(vis_Stream *p, Vint flag)

set wall faces

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.

Parameters

  • p – Pointer to Stream object.

  • flag – Element face bit flags to indicate wall faces.

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

set initial conditions for streamline integration

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.

Parameters

  • p – 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 – Initial orientation vectors

  • w – Initial orientation vectors

  • t – Initial time

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

get terminal state of streamline integration

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.

Parameters

  • p – Pointer to Stream object.

  • iop – World coordinate flag 

    =0            Natural coordinates
=1            World coordinates

  • status – [out] Integration termination status 

    x=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 – [out] 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 – [out] Termination position of stream in world or natural coordinates

  • v – [out] Termination orientation vectors

  • w – [out] Termination orientation vectors

  • t – [out] Termination time

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

compute physical from natural coordinates

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

Parameters

  • p – Pointer to Stream object.

  • x – Array of point locations defining domain

  • r – Natural coordinates

  • xcoord – [out] Physical coordinates

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

compute natural from physical coordinates

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.

Parameters

  • p – Pointer to Stream object.

  • x – Array of point locations defining domain

  • xcoord – Physical coordinates

  • r – [out] Natural coordinates

void vis_StreamGetConvert(vis_Stream *p, Vint *convertflag)

get coordinate conversion error flag

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

Parameters

  • p – Pointer to Stream object.

  • convertflag – [out] Current vis_StreamConvertCoord() function error flag. 

    x=VIS_OFF         No conversion error
 =VIS_ON          Conversion error

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

compute streamline in curvilinear volume

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

Errors

VIS_ERROR_ENUM is generated if an improper rank is specified.

Parameters

  • p – Pointer to Stream object.

  • rank – Type of field data, either vector or tensor 

    x=VIS_VECTOR             Vector field
 =VIS_TENSOR             Tensor field

  • s – Array of vector or tensor field values

  • x – Array of point locations defining domain

void vis_StreamSetContinuous(vis_Stream *p, Vint flag)

set continuous line mode

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.

Parameters

  • p – Pointer to Stream object.

  • flag – Flag for beginning of new continuous line 

    x=VIS_ON           Starts continuous line mode
 =VIS_OFF          Terminates continuous line mode