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.

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.

4.2. Function Descriptions

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

vis_IsoClip *vis_IsoClipBegin(void)

create an instance of an IsoClip object

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)

Returns

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

void vis_IsoClipEnd(vis_IsoClip *p)

destroy an instance of an IsoClip object using

See vis_IsoClipBegin()

Vint vis_IsoClipError(vis_IsoClip *p)

return the current value of an IsoClip object error flag

See vis_IsoClipBegin()

void vis_IsoClipSetMode(vis_IsoClip *p, Vint mode)

set overall clipping mode

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.

Errors

VIS_ERROR_ENUM is generated if an improper mode is input.

Parameters

  • p – Pointer to IsoClip object.

  • mode – Overall clipping mode. 

    x=ISOCLIP_ANY            Clip if any isosurface clips
 =ISOCLIP_ALL            Clip if all isosurfaces clip

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

set isosurface clipping type and value

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 a index, type, hityon and value as output arguments using 

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

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.

Parameters

  • p – Pointer to IsoClip object.

  • index – The isosurface clipping index in the range 0 <= index <= 5.

  • type – Isosurface clipping type. 

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

    x=ISOCLIP_HITHER         Clip positive halfspace.
 =ISOCLIP_YON            Clip negative halfspace

  • value – Scalar value defining isosurface.

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

get isosurface clipping type and value

See vis_IsoClipSetType()

void vis_IsoClipSetDataPtr(vis_IsoClip *p, Vint index, Vfloat dataptr[])

set pointer to isosurface clipping scalar field data

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.

Errors

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

Parameters

  • p – 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

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

set isosurface clipping data State object

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.

Errors

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

Parameters

  • p – 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

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

set pointer to CoordSys object

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

Errors

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

Parameters

  • p – Pointer to IsoClip object.

  • index – The isosurface clipping index in the range 0 <= index <= 5.

  • coordsys – Pointer to CoordSys object.

void vis_IsoClipCopy(vis_IsoClip *p, vis_IsoClip *fromp)

make a copy of an IsoClip object

See vis_IsoClipBegin()

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.

4.4. Function Descriptions

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

vis_DataInt *vis_DataIntBegin(void)

create an instance of a DataInt object

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)

Returns

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

void vis_DataIntEnd(vis_DataInt *p)

destroy an instance of a DataInt object

See vis_DataIntBegin()

Vint vis_DataIntError(vis_DataInt *p)

return the current value of a DataInt object error flag

See vis_DataIntBegin()

void vis_DataIntSetDataPtr(vis_DataInt *p, Vint index, Vint nrws, Vfloat dataptr[])

set pointer to interpolation data

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)

Errors

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

Parameters

  • p – 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

void vis_DataIntGetDataPtr(vis_DataInt *p, Vint index, Vint *nrws, Vfloat **data)

get pointer to interpolation data

See vis_DataIntSetDataPtr()

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

set user callback function

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.

Errors

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

Parameters

  • p – 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

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

set interpolation data State object

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.

Errors

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

Parameters

  • p – 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

void vis_DataIntCopy(vis_DataInt *p, vis_DataInt *fromp)

make a copy of a DataInt object

See vis_DataIntBegin()

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

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.

4.7. Function Descriptions

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

vis_PrmClp *vis_PrmClpBegin(void)

create an instance of a PrmClp object

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)

Returns

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

void vis_PrmClpEnd(vis_PrmClp *p)

destroy an instance of a PrmClp object

See vis_PrmClpBegin()

Vint vis_PrmClpError(vis_PrmClp *p)

return the current value of a PrmClp object error flag

See vis_PrmClpBegin()

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

set pointers to attribute objects

Set a pointer to an attribute object.

Errors

VIS_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

Parameters

  • p – Pointer to PrmClp object.

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

    x=VGL_DRAWFUN            DrawFun object
 =VIS_ISOCLIP            IsoClip object

  • object – Pointer to the object to be set.

void vis_PrmClpDrawFun(vis_PrmClp *p, vgl_DrawFun *drawfun)

return pointers to drawing functions

Fill a DrawFun object with primitive clipping drawing functions.

Parameters

  • p – Pointer to PrmClp object

  • drawfun – Pointer to DrawFun object to be filled with primitive clipping drawing functions.