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)