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.
Begin and end an instance of an object, return object error flag
vis_IsoClipBegin()
- create an instance of a IsoClip objectvis_IsoClipEnd()
- destroy an instance of a IsoClip objectvis_IsoClipError()
- return IsoClip object error flagvis_IsoClipCopy()
- make a copy of a IsoClip object
Set isosurface clipping type, value and pointer to data
vis_IsoClipSetCoordSys()
- set pointer to CoordSys objectvis_IsoClipSetDataPtr()
- set pointer to isosurface clipping datavis_IsoClipSetMode()
- set overall clipping modevis_IsoClipSetState()
- set isosurface clipping data State objectvis_IsoClipSetType()
- set isosurface clipping type and valuevis_IsoClipGetType()
- get isosurface clipping type and value
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
-
Vint vis_IsoClipError(vis_IsoClip *p)
return the current value of an IsoClip object error flag
-
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 toISOCLIP_ALL
then a graphics object is clipped only if all isosurfaces clip the object. By default mode is set toISOCLIP_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 toISOCLIP_DATA
for an index, then the functionvis_IsoClipSetDataPtr()
must be called for index to define the start of the data field used to define the isosurface. If type is set toISOCLIP_X
,ISOCLIP_Y
orISOCLIP_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 callvis_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
-
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.
-
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.
-
void vis_IsoClipCopy(vis_IsoClip *p, vis_IsoClip *fromp)
make a copy of an IsoClip object
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.
Begin and end an instance of an object, return object error flag
vis_DataIntBegin()
- create an instance of a DataInt objectvis_DataIntEnd()
- destroy an instance of a DataInt objectvis_DataIntError()
- return DataInt object error flagvis_DataIntCopy()
- make a copy of a DataInt object
Set pointer to data array
vis_DataIntSetDataPtr()
- set pointer to interpolation datavis_DataIntSetFunction()
- set user functionvis_DataIntSetState()
- set interpolation data State object
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
-
Vint vis_DataIntError(vis_DataInt *p)
return the current value of a DataInt object error flag
-
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
-
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.
-
void vis_DataIntCopy(vis_DataInt *p, vis_DataInt *fromp)
make a copy of a DataInt object
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.
Begin and end an instance of an object, return object error flag
vis_PrmClpBegin()
- create an instance of a PrmClp objectvis_PrmClpEnd()
- destroy an instance of a PrmClp objectvis_PrmClpError()
- return PrmClp object error flag
Operations
vis_PrmClpDrawFun()
- fill DrawFun objectvis_PrmClpSetObject()
- set pointers to attribute objects.
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
-
Vint vis_PrmClpError(vis_PrmClp *p)
return the current value of a PrmClp object error flag
-
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.