## table of contents

vpCreateMinMaxOctree(3) | Library Functions Manual | vpCreateMinMaxOctree(3) |

# NAME¶

vpCreateMinMaxOctree, vpMinMaxOctreeThreshold, vpDestroyMinMaxOctree - create/destroy a min-max octree for optimized rendering

# SYNOPSIS¶

#include <volpack.h>

vpResult

**vpCreateMinMaxOctree(***vpc, root_node_size,
base_node_size***)**

- vpContext *
*vpc;* - int
*root_node_size, base_node_size;*

vpResult

**vpMinMaxOctreeThreshold(***vpc, param_num,
range***)**

- vpContext *
*vpc;* - int
*param_num, range;*

vpResult

**vpDestroyMinMaxOctree(***vpc***)**

- vpContext *
*vpc;*

# ARGUMENTS¶

*vpc*- VolPack context from
**vpCreateContext.** *root_node_size*- Number of voxels per side in the top level (largest nodes) of the octree. Not currently used.
*base_node_size*- Number of voxels per side in the bottom level (smallest nodes) of the octree. Must be a power of 2.
*param_num*- Identifying number of one parameter of the opacity transfer function.
*range*- Range threshold for one parameter of the opacity transfer function. If an octree node spans a larger range then it is subdivided.

# DESCRIPTION¶

These routines are used to create and destroy a min-max octree, an internal data structure that is used to accelerate classifying and rendering volume data in a 3D voxel array. The octree is a hierarchical data structure that contains minimum and maximum values for each voxel field. It does not duplicate the data in the voxel array. The octree is not used with preclassified volumes (see vpClassifyVolume(3)).

Before creating an octree, declare a 3D voxel array using
**vpSetVolumeSize, vpSetVoxelSize, vpSetVoxelField** and
**vpSetRawVoxels,** and initialize parameters for the opacity transfer
function by calling **vpSetClassifierTable**. Then initialize the voxel
data in the array. The lookup tables for the opacity transfer function do
not need to be initialized.

Now call **vpMinMaxOctreeThreshold** once for each parameter to
the opacity transfer function. The parameter number is the same number as
the parameter number you would pass to **vpClassifierTable.** The
*range* argument specifies a "small" range of values for the
corresponding parameter. The opacity of a voxel should not vary much for
voxels within this range of parameter space. Choosing a value which is too
small or too large may result in a reduced performance benefit during
rendering. The function **vpOctreeMask** can be used to visualize the
effectiveness of various parameter ranges. Note that you must choose the
voxel field associated with each opacity transfer function parameter in
advance of creating the octree (by calling **vpSetClassiferTable**), but
the opacity transfer function itself does not need to be known since the
lookup tables do not need to be initialized. In the current implementation
all of the parameters must be one or two-byte voxel fields; four-byte fields
are not allowed.

Finally, call **vpCreateMinMaxOctree** to actually compute the
octree. The arguments specify the largest and smallest node size. These
values can be used to trade off storage size of the octree for increased
resolution. The octree is stored in the rendering context and is used
automatically in subsequent calls to **vpClassifyVolume** and
**vpRenderRawVolume.** Only one octree may be stored in a context at a
time. If an octree already exists when **vpCreateMinMaxOctree** is called
then the old octree is destroyed.

If the data in the voxel array changes then the min-max octree
must be explicitly recomputed by calling **vpCreateMinMaxOctree** again
before the next call to **vpClassifyVolume** or
**vpRenderRawVolume.**

**vpDestroyMinMaxOctree** destroys the current min-max octree
and frees the associated storage.

# STATE VARIABLES¶

The current octree parameters can be retrieved with the following state variable codes (see vpGeti(3)): VP_CLASSIFY_FIELD_COUNT, VP_CLASSIFY_FIELDS, VP_MMOCTREE_THRESHOLDS, VP_MMOCTREE_SIZE.

# ERRORS¶

The normal return value for all three functions is VP_OK.
**vpMinMaxOctreeThreshold** can return the following error value:

- VPERROR_BAD_VALUE
- The parameter number is invalid.

**vpCreateMinMaxOctree** can return the following error
values:

- VPERROR_BAD_VALUE
- The node size arguments are not a power of two.
- VPERROR_BAD_VOXEL
- The voxel size or the voxel fields have not been specified or have been incorrectly specified, or the number of parameters to the opacity transfer function has been incorrectly specified.
- VPERROR_BAD_VOLUME
- The volume array or volume dimensions have not been specified, or the size of the volume array does not match the volume dimensions.
- VPERROR_BAD_CLASSIFIER
- The fields specified as parameters to the opacity transfer function are invalid or do not have valid sizes.
- VPERROR_LIMIT_EXCEEDED
- The volume is too large, so the maximum size of the octree has been exceeded. Change the constant VP_MAX_OCTREE_LEVELS in volpack.h and recompile the VolPack library.

# SEE ALSO¶

VolPack(3), vpCreateContext(3), vpClassifyVolume(3), vpOctreeMask(3), vpRenderRawVolume(3)

VolPack |