NAME

       vpClassifyScalars - create a preclassified volume from scalar data

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpClassifyScalars(vpc, scalar_data, length, scalar_field, gradient_field, norm_field)
           vpContext *vpc;
           unsigned char *scalars;
           int size;
           int scalar_field, gradient_field, norm_field;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       scalar_data
              A 3D array containing one 8-bit scalar value for each voxel in the volume.

       length Size of scalar_data in bytes.

       scalar_field
              Field number identifying a voxel field for storing the scalar value.

       gradient_field
              Field number identifying a voxel field for storing the gradient magnitude of the scalar value.

       norm_field
              Field number identifying a voxel field for storing the surface normal vector for the voxel.

DESCRIPTION

       vpClassifyScalars  combines  the  functionality  of  vpVolumeNormals  and  vpClassifyVolume  to produce a
       preclassified volume directly from a 3D array of scalar values without creating a 3D voxel  array.   This
       routine  is  useful  for  preparing  large  data sets for rendering with a fixed classification function,
       especially if the 3D voxel array would be too large to fit in main memory.   The  primary  limitation  is
       that  the  only fields each voxel may contain are the fields produced by vpVolumeNormals: an 8-bit scalar
       value, and 8-bit gradient and/or a  16-bit  surface  normal  vector.   See  also  vpClassifyScanline  for
       processing one scanline of a scalar array at a time.

       To  use  the  function,  first  define  the volume size, voxel size, and voxel fields as you would before
       calling vpVolumeNormals.  However, there is no need to call  vpSetRawVoxels.   Also  define  the  opacity
       transfer function (see vpSetClassifierTable(3)).  Then call vpClassifyScalars with the same arguments you
       would  use  for  vpVolumeNormals; see vpVolumeNormals(3) for more details.  The result is a preclassified
       volume, as described in vpClassifyVolume(3).  If a voxel array has  been  declared  it  is  not  used  or
       modified.

       Any existing preclassified volume data is destroyed.

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_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),   vpVolumeNormals(3),   vpSetClassifierTable(3),   vpClassifyVolume(3),
       vpClassifyScanline(3)

VolPack                                                                                     vpClassifyScalars(3)