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)