Table of Contents

4. Isosurface Clipping, Data Interpolation - IsoClip,DataInt,PrmClp

The IsoClip and DataInt modules are used to place visualization modules into isosurface clipping or data interpolation mode. These modules modify the default behavior of visualization objects.

The PrmClp module supports the clipping of graphics primitive geometries.

Table of Contents

4.1 Isosurface Clipping - IsoClip

A unique feature of VisTools is the ability to clip visualization entities to any isosurface. Clipping may occur on the positive half space (hither clipping) or on the negative half space (yon clipping) defined by an isosurface. IsoClip objects are used to define a set of the isosurfaces to which visualization entities are to be clipped. Up to 6 isosurfaces may be set in an IsoClip object to perform isosurface clipping. To activate isosurface clipping in a visualization object, set the IsoClip object as an attribute object in the visualization object. The methods associated with an IsoClip object are the following.

Each isosurface in an IsoClip object can be set to clip to the hither or yon side of the isosurface. Hither clipping removes or clips objects in the half space on the "positive" side of the isosurface. Yon clipping removes or clips objects in the half space on the "negative" side of the isosurface. Isosurfaces may be defined by an isovalue of a scalar data field or as an isovalue of coordinates expressed in a user defined coordinate system. The function, vis_IsoClipSetMode is used to set the overall clipping mode. With the default mode ISOCLIP_ANY, a graphics object is clipped if any isosurface in IsoClip clips the object. Alternatively with mode ISOCLIP_ALL a graphics object is clipped only if all isosurfaces in IsoClip clip the object.

Use vis_IsoClipSetType to set the clipping type and scalar constant used to define the isosurface. If the isosurface is to be defined by a scalar data field, use vis_IsoClipSetDataPtr to set the pointer to the current start of the scalar field data used to define the isosurface. Use vis_IsoClipSetState to set a State object which contains the scalar field data used to define the isosurface. This is used to do isosurface clipping with the model traversal functions. If the isosurface is to be defined by a set of coordinates expressed in a user defined coordinate system, use vis_IsoClipSetCoordSys to set a CoordSys object which defines the coordinate system. If the coordinate field is in the global coordinate system then vis_IsoClipSetCoordSys does not need to be called.

Table of Contents

4.2 Function Descriptions

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

Table of Contents , IsoClip

NAME

*vis_IsoClipBegin - create an instance of a IsoClip object

C SPECIFICATION

vis_IsoClip *vis_IsoClipBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a IsoClip object. Memory is allocated for the object private data and the pointer to the data is returned. By default the isosurface clipping type is ISOCLIP_NONE and the value is 0.

Destroy an instance of a IsoClip object using 

     void vis_IsoClipEnd (vis_IsoClip *isoclip)

Return the current value of a IsoClip object error flag using 

     Vint vis_IsoClipError (vis_IsoClip *isoclip)

Make a copy of a IsoClip object. The private data from the fromisoclip object is copied to the isoclip object. Any previous private data in isoclip is lost. 

     void vis_IsoClipCopy (vis_IsoClip *isoclip,
                           vis_IsoClip *fromisoclip)

Table of Contents , IsoClip

NAME

vis_IsoClipSetCoordSys - set pointer to CoordSys object

C SPECIFICATION

void vis_IsoClipSetCoordSys (vis_IsoClip *isoclip,
                             Vint index,
                             vis_CoordSys *coordsys)

INPUT ARGUMENTS

isoclip      Pointer to IsoClip object.
index        The isosurface clipping index in the range
             0 <= index <= 5.
coordsys     Pointer to CoordSys object.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an index out of range is specified.

DESCRIPTION

Set a pointer to the CoordSys object which defines the local coordinate system in which the coordinate field for index is to be expressed.

Table of Contents , IsoClip

NAME

vis_IsoClipSetDataPtr - set pointer to isosurface clipping scalar field data

C SPECIFICATION

void vis_IsoClipSetDataPtr (vis_IsoClip *isoclip,
                            Vint index,
                            Vfloat *dataptr)

INPUT ARGUMENTS

isoclip      Pointer to IsoClip object.
index        The isosurface clipping index in the range
             0 <= index <= 5.
dataptr      Pointer to start of isosurface clipping scalar field data

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an index out of range is specified.

DESCRIPTION

Set a pointer to the isosurface clipping scalar field data. Note that scalar field values are not copied by this function, only the pointer itself is copied.

Table of Contents , IsoClip

NAME

vis_IsoClipSetMode - set overall clipping mode

C SPECIFICATION

void vis_IsoClipSetMode (vis_IsoClip *isoclip,
                         Vint mode)

INPUT ARGUMENTS

isoclip      Pointer to IsoClip object.
mode         Overall clipping mode.
             =ISOCLIP_ANY            Clip if any isosurface clips
             =ISOCLIP_ALL            Clip if all isosurfaces clip

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_ENUM is generated if an improper mode is input.

DESCRIPTION

Set the overall clipping mode. If mode is set to ISOCLIP_ANY then a graphics object is clipped if any isosurface clips the object. If mode is set to ISOCLIP_ALL then a graphics object is clipped only if all isosurfaces clip the object. By default mode is set to ISOCLIP_ANY.

Table of Contents , IsoClip

NAME

vis_IsoClipSetState - set isosurface clipping data State object

C SPECIFICATION

void vis_IsoClipSetState (vis_IsoClip *isoclip,
                          Vint index,
                          vis_State *state)

INPUT ARGUMENTS

isoclip      Pointer to IsoClip object.
index        The isosurface clipping index in the range
             0 <= index <= 5.
state        Pointer to State object containing isosurface clipping
             scalar field data

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an index out of range is specified.

DESCRIPTION

Set a State object which contains the scalar field data used to define the isosurface. This is used to do isosurface clipping with the model traversal functions such as vis_EdgeTrav, vis_ContourTrav, etc. The contents of state are not accessed until the model traversal function is called.

Table of Contents , IsoClip

NAME

vis_IsoClipSetType - set isosurface clipping type and value

C SPECIFICATION

void vis_IsoClipSetType (vis_IsoClip *isoclip,
                         Vint index,
                         Vint type,
                         Vint hityon,
                         Vfloat value)

INPUT ARGUMENTS

isoclip      Pointer to IsoClip object.
index        The isosurface clipping index in the range
             0 <= index <= 5.
type         Isosurface clipping type.
             =ISOCLIP_DATA           Clip to data field
             =ISOCLIP_NONE           Do not clip.
             =ISOCLIP_X              Clip to x coordinate field
             =ISOCLIP_Y              Clip to y coordinate field
             =ISOCLIP_Z              Clip to z coordinate field
hityon       Clip to hither or yon
             =ISOCLIP_HITHER         Clip positive halfspace.
             =ISOCLIP_YON            Clip negative halfspace
value        Scalar value defining isosurface.

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an index out of range is specified. VIS_ERROR_ENUM is generated if an improper type or hityon is input.

DESCRIPTION

Set the isosurface clipping type, hither and yon direction and value. The value defines the constant scalar value at which the isosurface occurs. To turn off isosurface clipping for a particular isosurface index, set the type to ISOCLIP_NONE. In this case, the input value of hityon is ignored. If type is set to ISOCLIP_DATA for an index, then the function vis_IsoClipSetDataPtr must be called for index to define the start of the data field used to define the isosurface. If type is set to ISOCLIP_X, ISOCLIP_Y or ISOCLIP_Z for an index, then the x, y or z node coordinates are used to define the isosurface. By default, the coordinates are assumed to be the global coordinates. In order to use a coordinate field in a user defined local coordinate system call vis_IsoClipSetCoordSys for index. Note that for cylindrical systems the x, y and z coordintes are the local radial, tangential angle and axial coordinates respectively. For spherical systems the x, y and z coordintes are the local radial, tangential angle and azimuthal angle coordinates respectively.

Get index, type, hityon and value as output arguments using 

     void vis_IsoClipGetType (vis_IsoClip *isoclip,
                              Vint *index,
                              Vint *type,
                              Vint *hityon,
                              Vfloat *value)

Table of Contents

4.3 Data Interpolation - DataInt

Many visualization modules in VisTools have the ability to perform data interpolations while generating visualization entities. For example, data can be interpolated to an isosurface so that is may be subsequently contoured on the isosurface. DataInt objects are used to define the data arrays which are to be interpolated. DataInt has been designed to allow up to six separate data arrays to be interpolated. Note however that the current implementation only allows a single data array. To activate data interpolation in a visualization object, set the DataInt object as an attribute object. The methods associated with a DataInt object are the following.

Each data array in a DataInt object is identified by an index between 0 and 5 and is defined by a row dimension and a pointer to the current start of the field data to be interpolated. Use vis_DataIntSetDataPtr to specify the row dimension and pointer to the current start of the field data to be interpolated. Use vis_DataIntSetState to set a State object which contains the field data to be interpolated. This is used to do isosurface clipping with the model traversal functions. Use vis_DataIntSetFunction to register a user defined callback function that is called by a visualization object before it first accesses interpolation data. A DataInt object does not require any attribute objects.

Table of Contents

4.4 Function Descriptions

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

Table of Contents , DataInt

NAME

*vis_DataIntBegin - create an instance of a DataInt object

C SPECIFICATION

vis_DataInt *vis_DataIntBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a DataInt object. Memory is allocated for the object private data and the pointer to the data is returned. The user defined callback function is set to NULL.

Destroy an instance of a DataInt object using 

     void vis_DataIntEnd (vis_DataInt *dataint)

Return the current value of a DataInt object error flag using 

     Vint vis_DataIntError (vis_DataInt *dataint)

Make a copy of a DataInt object. The private data from the fromdataint object is copied to the dataint object. Any previous private data in dataint is lost. 

     void vis_DataIntCopy (vis_DataInt *dataint,
                           vis_DataInt *fromdataint)

Table of Contents , DataInt

NAME

vis_DataIntSetDataPtr - set pointer to interpolation data

C SPECIFICATION

void vis_DataIntSetDataPtr (vis_DataInt *dataint,
                            Vint index,
                            Vint nrws,
                            Vfloat *dataptr)

INPUT ARGUMENTS

dataint      Pointer to DataInt object.
index        The data array index in the range
             0 <= index <= 5.
nrws         Row dimension of the data array dataptr.
             1 <= nrws <= 16.
dataptr      Pointer to start of field data

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an index or a nrws out of range is specified.

DESCRIPTION

Set the row dimension and pointer to an array of data values to be interpolated by a visualization object during draw methods. When data interpolation is active the "Data" drawing functions are called for point, line and polygon primitives. Each "Data" primitive will immediately precede its corresponding graphics primitive.

Note that the current implementation of the DataInt module allows only a single data array. This implies that index must equal zero.

Inquire of defined nrws and dataptr as output arguments for a given index using 

     void vis_DataIntGetDataPtr(vis_DataInt *dataint,
                                Vint index,
                                Vint *nrws,
                                Vfloat **dataptr)

Table of Contents , DataInt

NAME

vis_DataIntSetFunction - set user callback function

C SPECIFICATION

void vis_DataIntSetFunction (vis_DataInt *dataint,
                             Vint index,
                             void (*function)(vis_DataInt*, Vobject*),
                             Vobject *object)

INPUT ARGUMENTS

dataint      Pointer to DataInt object.
index        The data array index in the range
             0 <= index <= 5.
function     Pointer to callback function
object       Pointer to the object to be returned as function argument

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an index out of range is specified.

DESCRIPTION

Set a user defined callback function to be called by a visualization object. Data interpolation callback functions are designed to be used to compute fields to be interpolated only when a visualization object actually requires the field data. This avoids the expense of computing the data to be interpolated if it is unnecessary. In general, the callback function will be invoked once before any "Data" drawing function is called by any visualization object which accepts a DataInt attribute object. If function is NULL, then visualization objects do not attempt to invoke the callback function. By default the callback function is NULL.

Table of Contents , DataInt

NAME

vis_DataIntSetState - set interpolation data State object

C SPECIFICATION

void vis_DataIntSetState (vis_DataInt *dataint,
                          Vint index,
                          vis_State *state)

INPUT ARGUMENTS

dataint      Pointer to DataInt object.
index        The data array index in the range
             0 <= index <= 5.
state        Pointer to State object containing isosurface clipping
             scalar field data

OUTPUT ARGUMENTS

None

ERRORS

VIS_ERROR_VALUE is generated if an index out of range is specified.

DESCRIPTION

Set a State object which contains the field data interpolated by a visualization object during draw methods. This is used to do data interpolation with the model traversal functions such as vis_EdgeTrav, vis_ContourTrav, etc. When data interpolation is active the "Data" drawing functions are called for point, line and polygon primitives. Each "Data" primitive will immediately precede its corresponding graphics primitive. The contents of state are not accessed until the model traversal function is called.

Note that the current implementation of the DataInt module allows only a single data array. This implies that index must equal zero.

Table of Contents

4.5 Graphics Primitive Clipping - PrmClp

Use PrmClp to directly clip graphics primitives. This module is useful for clipping "orphan" graphics primitives which have not been generated by a visualization module such as Edge or Contour. The functions associated with an PrmClp object are the following.

Instance a PrmClp object using vis_PrmClpBegin. Set attribute objects using vis_PrmClpSetObject. Register the drawing functions in a DrawFun object for incoming graphics primitives using vis_PrmClpDrawFun.

Table of Contents

4.6 Attribute Objects

A PrmClp object uses DrawFun and IsoClip objects to define attributes to process graphics primitives. The DrawFun and IsoClip objects are required. A PrmClp object clips all polygon, polyline, polypoint and text graphics primitives drawing functions. A modelview matrix stack is implemented so that all modelview matrix drawin functions are captured and the incoming graphics primitives are transformed accordingly before clipping. All graphics primitive attributes are passed directly through to the downstream drawing function.

Table of Contents

4.7 Function Descriptions

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

Table of Contents , PrmClp

NAME

*vis_PrmClpBegin - create an instance of an PrmClp object

C SPECIFICATION

vis_PrmClp *vis_PrmClpBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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

Destroy an instance of a PrmClp object using 

     void vis_PrmClpEnd (vis_PrmClp *prmclp)

Return the current value of a PrmClp object error flag using 

     Vint vis_PrmClpError (vis_PrmClp *prmclp)

Table of Contents , PrmClp

NAME

vis_PrmClpDrawFun - return pointers to drawing functions

C SPECIFICATION

void vis_PrmClpDrawFun (vis_PrmClp *prmclp,
                        vgl_DrawFun *drawfun)

INPUT ARGUMENTS

prmclp       Pointer to PrmClp object.
drawfun      Pointer to DrawFun object to be filled with primitive
             clipping drawing functions.

OUTPUT ARGUMENTS

None

DESCRIPTION

Fill a DrawFun object with primitive clipping drawing functions.

Table of Contents , PrmClp

NAME

vis_PrmClpSetObject - set pointers to attribute objects

C SPECIFICATION

void vis_PrmClpSetObject (vis_PrmClp *prmclp,
                          Vint objecttype,
                          Vobject *object)

INPUT ARGUMENTS

prmclp       Pointer to PrmClp object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
             =VIS_ISOCLIP            IsoClip 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.