Man Linux: Main Page and Category List

NAME

       vpClassifyVolume,    vpDestroyClassifiedVolume   -   create/destroy   a
       preclassified volume for fast rendering

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpClassifyVolume(vpc)
           vpContext *vpc;

       vpResult
       vpDestroyClassifyVolume(vpc)
           vpContext *vpc;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

DESCRIPTION

       vpClassifyVolume is used to compute a preclassified volume for the fast
       rendering  algorithm.   The  preclassified  volume  is an internal data
       structure optimized for rendering speed.   vpClassifyVolume  should  be
       called  after  a  voxel  array  has been defined (with vpSetVolumeSize,
       vpSetVoxelSize, vpSetVoxelField, and  vpSetRawVoxels)  and  initialized
       (with  vpVolumeNormals or a user-defined routine).  An opacity transfer
       function must  also  be  defined  with  vpSetClassifierTable,  and  the
       minimum  opacity  threshold should be set with the VP_MIN_VOXEL_OPACITY
       parameter to vpSeti.  Two alternative routines are provided to  compute
       a preclassified volume directly from a 3D scalar array or a sequence of
       scalar scanlines in order to avoid allocating a large  3D  voxel  array
       (see vpClassifyScalars(3) and vpClassifyScanline(3)).

       vpClassifyVolume  classifies  and processes the data in the voxel array
       and creates a separate preclassified volume.  The preclassified data is
       stored  in  a run-length encoded format, and voxels that have opacities
       less than or equal to the  minimum  opacity  threshold  are  discarded.
       Normally, three copies of the preclassified volume are created, one for
       each of the three principal viewing axis.  If only one  or  two  copies
       are  necessary  for the required range of viewpoints then vpSeti may be
       called with one or more of the following parameters  to  specify  which
       copies  are  required:  VP_VIEW_X_AXIS, VP_VIEW_Y_AXIS, VP_VIEW_Z_AXIS.
       Using these parameters is not recommended unless swap space is lacking.

       If   a  min-max  octree  is  present  in  the  rendering  context  (see
       vpCreateMinMaxOctree(3)) then it is used to accelerate  computation  of
       the  preclassified  volume.   It  is  advantageous  to create a min-max
       octree if the same volume data will be classified multiple times  (with
       different opacity transfer functions).

       Once  vpClassifyVolume  is  finished,  the  original  voxel array is no
       longer necessary for rendering as long as the opacity transfer function
       and  the  volume data do not change.  If any changes are made, then the
       preclassified  volume  must  be  explicitly   recomputed   by   calling
       vpClassifyVolume again.  Only one preclassified volume may be stored in
       a rendering context at a time.   Calling  vpClassifyVolume  causes  any
       existing preclassified volume to be destroyed.

       vpDestroyClassifiedVolume destroys the current preclassified volume and
       frees the associated space.

STATE VARIABLES

       Information about the current preclassified  volume  can  be  retrieved
       with    the   following   state   variable   codes   (see   vpGeti(3)):
       VP_VIEW_X_SIZE,   VP_VIEW_Y_SIZE,    VP_VIEW_Z_SIZE,    VP_VIEW_X_AXIS,
       VP_VIEW_Y_AXIS, VP_VIEW_Z_AXIS.

ERRORS

       The  normal  return  value is VP_OK.  The following error return values
       are possible:

       VPERROR_BAD_VOXEL
              The voxel size or the voxel fields have not  been  specified  or
              have 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  opacity  transfer function tables have invalid sizes or are
              associated with invalid voxel fields or  have  been  incorrectly
              specified.

SEE ALSO

       VolPack(3),         vpCreateContext(3),        vpSetClassifierTable(3),
       vpClassifyScalars(3), vpClassifyScanline(3)