oracular (3) ClsfyTable.3.gz

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)