ISOSURFACE

The ISOSURFACE procedure algorithm expands on the SHADE_VOLUME algorithm. It returns topologically consistent triangles by using oriented tetrahedral decomposition internally. This also allows the algorithm to isosurface any arbitrary tetrahedral mesh. If the user provides an optional auxiliary array, the data in this array is interpolated onto the output vertices and is returned as well. This auxiliary data array is allowed to have more than one value at each vertex. Any size leading dimension is allowed as long as the number of values in the subsequent dimensions matches the number of elements in the input Data array.

Syntax

ISOSURFACE, Data, Value, Outverts, Outconn [, GEOM_XYZ=array, TETRAHEDRA=array] [, AUXDATA_IN=array, AUXDATA_OUT=variable] [, PROGRESS_CALLBACK=string] [, PROGRESS_METHOD=string] [, PROGRESS_OBJECT=objref] [, PROGRESS_PERCENT=percent{0 to 100}] [, PROGRESS_USERDATA=value]

Arguments

Data

Input three-dimensional array of scalars which are to be contoured.

Value

Input scalar contour value. This value specifies the constant-density surface (also called an iso-surface) to be extracted.

Outverts

A named variable to contain an output [3, n] array of floating point vertices making up the triangle surfaces.

Outconn

A named variable to contain an output array of polygonal connectivity values (see IDLgrPolygon, POLYGONS keyword). If no polygons were extracted, this argument returns the array [–1].

Keywords

AUXDATA_IN

Input array of auxiliary data with trailing dimensions being the number of values in Data.

Note: If AUXDATA_IN is specified then AUXDATA_OUT must also be specified.

AUXDATA_OUT

Set this keyword to a named variable that will contain an output array of auxiliary data sampled at the locations in Outverts.

Note: If AUXDATA_OUT is specified then AUXDATA_IN must also be specified.

GEOM_XYZ

A [3,n] input array of vertex coordinates (one for each value in the Data array). This array is used to define the spatial location of each scalar. If this keyword is omitted, Data must be a three-dimensional array and the scalar locations are assumed to be on a uniform grid.

Note: If GEOM_XYZ is specified then TETRAHEDRA must also be specified if either is to be specified.

PROGRESS_CALLBACK

Set this keyword to a scalar string containing the name of the IDL function that ISOSURFACE calls at PROGRESS_PERCENT intervals as it generates the isosurface.

The PROGRESS_CALLBACK function returns a zero to signal ISOSURFACE to stop generating the isosurface. This causes ISOSURFACE to return a single vertex and a connectivity array of [-1], which specifies an empty polygon. If the callback function returns any non-zero value, ISOSURFACE continues to generate the isosurface.

The PROGRESS_CALLBACK function must specify a single argument, Percent, which ISOSURFACE sets to an integer between 0 and 100, inclusive.

The PROGRESS_CALLBACK function may specify an optional USERDATA keyword parameter, which ISOSURFACE sets to the variable provided in the PROGRESS_USERDATA keyword.

The following code shows an example of a progress callback function:

FUNCTION myProgressCallback, percent,$

   USERDATA = myStruct

oProgressBar = myStruct.oProgressBar

; This method updates the progress bar

; graphic and returns TRUE if the user has

; NOT pressed the cancel button.

keepGoing = oProgressBar-> $

   UpdateProgressValue(percent)

RETURN, keepGoing

END

PROGRESS_METHOD

Set this keyword to a scalar string containing the name of a function method that ISOSURFACE calls at PROGRESS_PERCENT intervals as it generates the isosurface. If this keyword is set, then the PROGRESS_OBJECT keyword must be set to an object reference that is an instance of a class that defines the specified method.

The PROGRESS_METHOD function method callback has the same specification as the callback described in the PROGRESS_CALLBACK keyword, except that it is defined as an object class method:

FUNCTION myClass::myProgressCallback, $

   percent, USERDATA = myStruct

PROGRESS_OBJECT

Set this keyword to an object reference that is an instance of a class that defines the method specified with the PROGRESS_METHOD keyword. If this keyword is set, then the PROGRESS_METHOD keyword must also be set.

PROGRESS_PERCENT

Set this keyword to a scalar in the range [1, 100] to specify the interval between invocations of the callback function. The default value is 5 and IDL silently clamps other values to the range [1, 100].

For example, a value of 5 (the default) specifies ISOSURFACE will call the callback function when the isosurface process is 0% complete, 5% complete, 10% complete, ..., 95% complete, and 100% complete.

PROGRESS_USERDATA

Set this property to any IDL variable that ISOSURFACE passes to the callback function in the callback function’s USERDATA keyword parameter. If this keyword is specified, then the callback function must be able to accept keyword parameters.

TETRAHEDRA

An input array of tetrahedral connectivity values. If this array is not specified, the connectivity is assumed to be a rectilinear grid over the input three-dimensional array. If this keyword is specified, the input data array need not be a three-dimensional array. Each tetrahedron is represented by four values in the connectivity array. Every four values in the array correspond to the vertices of a single tetrahedron.

Version History

5.5	Introduced
6.0	Added PROGRESS_CALLBACK, PROGRESS_METHOD, PROGRESS_OBJECT, PROGRESS_PERCENT, and PROGRESS_USERDATA keywords