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.