INTERVAL_VOLUME

The INTERVAL_VOLUME procedure is used to generate a tetrahedral mesh from volumetric data. The generated mesh spans the portion of the volume where the volume data samples fall between two constant data values. This can also be thought of as a mesh constructed to fill the volume between two isosurfaces which are drawn according to the two supplied constant data values. The algorithm is very similar to the ISOSURFACE algorithm and expands upon the SHADE_VOLUME algorithm. A topologically-consistent tetrahedral mesh is returned by decomposing the volume into oriented tetrahedra. This also allows the algorithm to find the interval volume of any tetrahedral mesh.

If an auxiliary array is provided, its data is interpolated onto the output vertices and is returned. This auxiliary data array may have multiple values 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.

Examples

The following example generates an interval volume from a pre-existing dataset and displays the surface of the volume:

RESTORE, FILEPATH('clouds3d.dat', $

   SUBDIRECTORY=['examples','data'])

INTERVAL_VOLUME, rain, 0.1, 0.6, verts, conn

conn = TETRA_SURFACE(verts, conn)

oRain = OBJ_NEW('IDLgrPolygon', verts, POLYGONS=conn, $

   COLOR=[255,255,255], SHADING=1)

XOBJVIEW, oRain, BACKGROUND=[150,200,255]

Syntax

INTERVAL_VOLUME, Data, Value0, Value1, Outverts, Outconn [, AUXDATA_IN=array, AUXDATA_OUT=variable]
[, GEOM_XYZ=array, TETRAHEDRA=array] [, 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 that define the volume data.

Value0

Input scalar iso-value. This value specifies one of the limits for the interval volume. The generated interval volume encloses all volume samples between and including Value0 and Value1. Value0 may be greater than or less than Value1, but the two values may not be exactly equal. This value also cannot be a NaN, but can be +/- INF.

Value1

Input scalar iso-value. This value specifies the other limit for the interval volume. The generated interval volume encloses all volume samples between and including Value0 and Value1. Value1 may be greater than or less than Value0, but the two values may not be exactly equal. This value also cannot be a NaN, but can be +/- INF.

Outverts

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

Outconn

A named variable to contain an output array of tetrahedral mesh connectivity values. This array is one-dimensional and consists of a series of four vertex indices, where each group of four indices describes a tetrahedron. The connectivity values are indices into the vertex array returned in Outverts. If no tetrahedra are extracted, this argument returns the array [-1].

Keywords

AUXDATA_IN

This keyword defines the input array of auxiliary data with trailing dimensions being the number of values in Data.

Note: If you specify the AUXDATA_IN then you must specify AUXDATA_OUT.

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 you specify AUXDATA_OUT then you must specify AUXDATA_IN.

GEOM_XYZ

This keyword defines 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 you specify GEOM_XYZ then you must specify TETRAHEDRA.

PROGRESS_CALLBACK

Set this keyword to a scalar string containing the name of the IDL function that the INTERVAL_VOLUME procedure calls at PROGRESS_PERCENT intervals as it generates the interval volume.

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

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

The PROGRESS_CALLBACK function may specify an optional USERDATA keyword parameter, which INTERVAL_VOLUME 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 the INTERVAL_VOLUME procedure calls at PROGRESS_PERCENT intervals as it generates the interval. 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 INTERVAL_VOLUME will call the callback function when the interval volume process is 0% complete, 5% complete, 10% complete, ..., 95% complete, and 100% complete.

PROGRESS_USERDATA

Set this property to any IDL variable that INTERVAL_VOLUME 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

This keyword defines 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.

Note: If you specify TETRAHEDRA then you must specify GEOM_XYZ.

Version History

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

Resources and References

For more information on the INTERVAL_VOLUME algorithm, see the paper, “Interval Volume Tetrahedrization”, Nielson and Sung, Proceedings: IEEE Visualization, 1997.