NAME

       vpSetClassifierTable - specify an opacity transfer function

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpSetClassifierTable(vpc, param_num, param_field, table, table_size)
           vpContext *vpc;
           int param_num, param_field;
           float *table;
           int table_size;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       param_num
              Parameter number identifying one parameter of the opacity transfer function.

       param_field
              Field number identifying a voxel field that contains the parameter.

       table  Lookup table that defines the mapping from the voxel field value to the opacity.

       table_size
              Size of table in bytes.

DESCRIPTION

       vpSetClassifierTable  is  used  to  specify  lookup tables that define an opacity transfer function.  The
       opacity transfer function must be of the form: opacity = f0(param0) * f1(param1) * ... * fN(paramN) where
       each of the factors is  a  function  of  one  voxel  field  (see  below  for  implementing  more  general
       classification  models).   vpSetClassifierTable  must  be called once for each factor to specify a lookup
       table that defines the factor.  After the function has been specified, opacities are computed by  calling
       one  of  the  classification  functions:  vpClassifyScalars, vpClassifyVolume, or vpClassifyScanline.  To
       classify a voxel, these functions use the values in the fields of the voxel as indexes into  the  opacity
       transfer function tables, retrieve one value from each table, and multiply the values together to compute
       the  opacity  for the voxel.  The opacity should be a number in the range 0.0-1.0, so normally each table
       contains numbers that are also in this range.

       The parameters of the opacity transfer  function  are  numbered  from  zero,  and  the  total  number  of
       parameters  must  be  specified  using vpSetVoxelSize before calling vpSetClassifierTable.  The number of
       parameters is independent of the number of voxel fields: some fields may not be used as  parameters,  and
       one  field  could be used multiple times (although this is inefficient since all of the tables indexed by
       the same parameter could be merged into one table).

       Each table should be a 1D array of numbers with one entry for each possible value  of  the  corresponding
       voxel  field.   The  voxel field must contain an unsigned integer quantity.  Normally each table would be
       declared: float table[MAX_FIELD_VALUE + 1]; where MAX_FIELD_VALUE is the maximum possible  value  in  the
       voxel  field  as specified with vpSetVoxelField.  The table may also be dynamically allocated.  Note that
       VolPack will never free the table, even if the VolPack context is destroyed with vpDestroyContext, so the
       application is responsible for freeing the memory when appropriate.  The  values  in  the  table  may  be
       initialized  or modified at any time before or after calling vpSetClassifierTable, but before calling one
       of the classification routines.  See the function vpRamp for a convenient way to initialize  tables  with
       piece-wise linear ramps.

       Classification  functions  that  are not expressible in the form above can be handled as follows.  First,
       write your own routine that computes the opacity for each voxel.   Next,  quantize  the  opacities  using
       somewhere  between  8  and  16 bits per voxel, and store the quantized values in one field of each voxel.
       Finally, define an opacity transfer function table that maps the  quantized  opacities  into  a  floating
       point  number  in  the  range  0.0-1.0  and  use  the table to define a single-parameter opacity transfer
       function by calling vpSetClassifierTable.

       The minimum opacity threshold should be set at the same time as the opacity transfer function.   See  the
       VP_MIN_VOXEL_OPACITY argument to vpSetd.

STATE VARIABLES

       The  current  classification function parameters can be retrieved with the following state variable codes
       (see       vpGeti(3)):       VP_CLASSIFY_FIELD_COUNT,       VP_CLASSIFY_FIELDS,       VP_CLASSIFY_TABLES,
       VP_CLASSIFY_TABLE_SIZES, VP_MIN_VOXEL_OPACITY

ERRORS

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

       VPERROR_BAD_VALUE
              Either param_num or field_num is out of range.

SEE ALSO

       VolPack(3),   vpCreateContext(3),   vpClassifyScanline(3),   vpClassifyScalars(3),   vpClassifyVolume(3),
       vpRamp(3)

VolPack                                                                                  vpSetClassifierTable(3)