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                                                                                  vpCreateMinMaxOctree(3)