.\" Copyright (c) 1994 The Board of Trustees of The Leland Stanford
.\" Junior University.  All rights reserved.
.\" 
.\" Permission to use, copy, modify and distribute this software and its
.\" documentation for any purpose is hereby granted without fee, provided
.\" that the above copyright notice and this permission notice appear in
.\" all copies of this software and that you do not sell the software.
.\" Commercial licensing is available by contacting the author.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
.\" 
.\" Author:
.\"    Phil Lacroute
.\"    Computer Systems Laboratory
.\"    Electrical Engineering Dept.
.\"    Stanford University
.\" 
.\" $Date: 1994/12/31 19:49:53 $
.\" $Revision: 1.1 $
.\"
.\" Macros
.\" .FS <type>  --  function start
.\"     <type> is return type of function
.\"     name and arguments follow on next line
.de FS
.PD 0v
.PP
\\$1
.HP 8
..
.\" .FA  --  function arguments
.\"     one argument declaration follows on next line
.de FA
.IP " " 4
..
.\" .FE  --  function end
.\"     end of function declaration
.de FE
.PD
..
.\" .DS  --  display start
.de DS
.IP " " 4
..
.\" .DE  --  display done
.de DE
.LP
..
.TH vpSetClassifierTable 3 "" VolPack
.SH NAME
vpSetClassifierTable \- specify an opacity transfer function
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpSetClassifierTable(\fIvpc, param_num, param_field, table,
table_size\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
int \fIparam_num, param_field;\fR
.FA
float *\fItable;\fR
.FA
int \fItable_size;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIparam_num\fR
Parameter number identifying one parameter of the opacity transfer
function.
.IP \fIparam_field\fR
Field number identifying a voxel field that contains the parameter.
.IP \fItable\fR
Lookup table that defines the mapping from the voxel field value to
the opacity.
.IP \fItable_size\fR
Size of \fItable\fR in bytes.
.SH DESCRIPTION
\fBvpSetClassifierTable\fR is used to specify lookup tables that
define an opacity transfer function.  The opacity transfer function
must be of the form:
.DS
opacity = f0(param0) * f1(param1) * ... * fN(paramN)
.DE
where each of the factors is a function of one voxel field (see below
for implementing more general classification models).
\fBvpSetClassifierTable\fR 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: \fBvpClassifyScalars, vpClassifyVolume,\fR
or \fBvpClassifyScanline.\fR  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.
.PP
The parameters of the opacity transfer function are numbered from
zero, and the total number of parameters must be specified using
\fBvpSetVoxelSize\fR before calling \fBvpSetClassifierTable\fR.  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).
.PP
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:
.DS
float table[MAX_FIELD_VALUE + 1];
.DE
where MAX_FIELD_VALUE is the maximum possible value in the voxel field
as specified with \fBvpSetVoxelField.\fR  The table may also be
dynamically allocated.  Note that VolPack will never free the table,
even if the VolPack context is destroyed with \fBvpDestroyContext,\fR
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 \fBvpSetClassifierTable,\fR but
before calling one of the classification routines.  See the function
\fBvpRamp\fR for a convenient way to initialize tables with piece-wise
linear ramps.
.PP
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
\fBvpSetClassifierTable.\fR
.PP
The minimum opacity threshold should be set at the same time as the
opacity transfer function.  See the VP_MIN_VOXEL_OPACITY argument to
\fBvpSetd\fR.
.SH "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
.SH ERRORS
The normal return value is VP_OK.  The following error return value is
possible:
.IP VPERROR_BAD_VALUE
Either \fIparam_num\fR or \fIfield_num\fR is out of range.
.SH SEE ALSO
VolPack(3), vpCreateContext(3), vpClassifyScanline(3),
vpClassifyScalars(3), vpClassifyVolume(3), vpRamp(3)