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)