NAME

       vpVolumeNormals - compute surface normal vectors and gradient magnitudes for a volume

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpVolumeNormals(vpc, scalar_data, length, scalar_field, grad_field, norm_field)
           vpContext *vpc;
           unsigned char *scalar_data;
           int length;
           int scalar_field;
           int grad_field;
           int norm_field;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       scalar_data
              3D array of scalar samples.

       length Size of scalar_data array in bytes.

       scalar_field
              Voxel field number indicating the field in which to store the scalar samples.

       grad_field
              Voxel  field  number  indicating the field in which to store the gradient magnitudes of the scalar
              samples.

       norm_field
              Voxel field number indicating the field in which to store encoded surface normal vectors.

DESCRIPTION

       vpVolumeNormals is used to precompute  values  for  voxel  fields  used  in  classification  and  shading
       algorithms.   The  input  is  a  3D array of scalar values; a separate routine is provided for processing
       scanlines  of  voxel  data  (see  vpScanlineNormals(3)).   For  each  voxel,  the  routine  computes   an
       approximation  for  the  gradient  of  the scalar field (using a central-difference operator).  From this
       vector the routine can compute the magnitude of the gradient, which is  useful  for  some  classification
       schemes  (see  vpSetClassifierTable(3)),  and  a  surface  normal vector in the direction of the gradient
       vector, which is used to implement lighting models (see vpShadeTable(3)).   The  scalar  value,  gradient
       magnitude and surface normal vector are then stored into the fields of the voxel array, which is separate
       from the array of scalar values.

       The  scalar  array  must  be  an  array  of  8-bit values (other sizes are not currently supported).  The
       dimensions of the array must match the volume dimensions previously specified with vpSetVolumeSize.   The
       size  argument  is  used  to  make  sure  the  array  has the correct size.  The voxel array must also be
       initialized by calling vpSetRawVoxels prior to calling vpVolumeNormals.

       The three voxel field number arguments indicate which voxel fields the  computed  information  should  be
       stored  into,  and which field the scalar samples should be copied to.  The field numbers must correspond
       to appropriately-sized voxel fields previously specified with vpSetVoxelField.  Any  of  these  arguments
       can  be  the  constant VP_SKIP_FIELD, in which case the corresponding quantity is not computed or copied.
       The voxel fields for the scalar value and the gradient magnitude must be one-byte fields, and  the  field
       for  the  surface  normal  vector must be a two-byte field.  The constants VP_SCALAR_MAX, VP_GRAD_MAX and
       VP_NORM_MAX give the maximum value that might be stored in each field, respectively.  The value stored in
       the surface normal vector field is actually an encoded surface normal; see vpNormalIndex(3).

ERRORS

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

       VPERROR_BAD_SIZE
              The size of the scalar array does not match the volume dimensions.

       VPERROR_BAD_VALUE
              One or more of the voxel fields specified is invalid, or the corresponding  voxel  field  has  the
              wrong size.

       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.

SEE ALSO

       VolPack(3),   vpCreateContext(3),   vpNormalIndex(3),   vpScanlineNormals(3),    vpSetClassifierTable(3),
       vpSetLookupShader(3)

VolPack                                                                                       vpVolumeNormals(3)