.\" 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 vpClassifyVolume 3 "" VolPack
.SH NAME
vpClassifyVolume, vpDestroyClassifiedVolume \- create/destroy a
preclassified volume for fast rendering
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpClassifyVolume(\fIvpc\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FE
.sp
.FS vpResult
\fBvpDestroyClassifyVolume(\fIvpc\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.SH DESCRIPTION
\fBvpClassifyVolume\fR is used to compute a preclassified volume for
the fast rendering algorithm.  The preclassified volume is an internal
data structure optimized for rendering speed.  \fBvpClassifyVolume\fR
should be called after a voxel array has been defined (with
\fBvpSetVolumeSize, vpSetVoxelSize, vpSetVoxelField,\fR and
\fBvpSetRawVoxels\fR) and initialized (with \fBvpVolumeNormals\fR or a
user-defined routine).  An opacity transfer function must also be
defined with \fBvpSetClassifierTable,\fR and the minimum opacity
threshold should be set with the VP_MIN_VOXEL_OPACITY parameter to
\fBvpSeti\fR.  Two alternative routines are provided to compute a
preclassified volume directly from a 3D scalar array or a sequence of
scalar scanlines in order to avoid allocating a large 3D voxel array
(see vpClassifyScalars(3) and vpClassifyScanline(3)).
.PP
\fBvpClassifyVolume\fR classifies and processes the data in the voxel
array and creates a separate preclassified volume.  The preclassified
data is stored in a run-length encoded format, and voxels that have
opacities less than or equal to the minimum opacity threshold are
discarded.  Normally, three copies of the preclassified volume are
created, one for each of the three principal viewing axis.  If only
one or two copies are necessary for the required range of viewpoints
then \fBvpSeti\fR may be called with one or more of the following
parameters to specify which copies are required: VP_VIEW_X_AXIS,
VP_VIEW_Y_AXIS, VP_VIEW_Z_AXIS.  Using these parameters is not
recommended unless swap space is lacking.
.PP
If a min-max octree is present in the rendering context (see
vpCreateMinMaxOctree(3)) then it is used to accelerate computation of the
preclassified volume.  It is advantageous to create a min-max octree
if the same volume data will be classified multiple times (with
different opacity transfer functions).
.PP
Once \fBvpClassifyVolume\fR is finished, the original voxel array is
no longer necessary for rendering as long as the opacity transfer
function and the volume data do not change.  If any changes are
made, then the preclassified volume must be explicitly recomputed by
calling \fBvpClassifyVolume\fR again.  Only one preclassified volume
may be stored in a rendering context at a time.  Calling
\fBvpClassifyVolume\fR causes any existing preclassified volume to be
destroyed.
.PP
\fBvpDestroyClassifiedVolume\fR destroys the current preclassified
volume and frees the associated space.
.SH "STATE VARIABLES"
Information about the current preclassified volume can be retrieved
with the following state variable codes (see vpGeti(3)): VP_VIEW_X_SIZE,
VP_VIEW_Y_SIZE, VP_VIEW_Z_SIZE, VP_VIEW_X_AXIS, VP_VIEW_Y_AXIS,
VP_VIEW_Z_AXIS.
.SH ERRORS
The normal return value is VP_OK.  The following error return values
are possible:
.IP VPERROR_BAD_VOXEL
The voxel size or the voxel fields have not been specified or have
been incorrectly specified.
.IP VPERROR_BAD_VOLUME
The volume array or volume dimensions have not been specified, or the
size of the volume array does not match the volume dimensions.
.IP VPERROR_BAD_CLASSIFIER
The opacity transfer function tables have invalid sizes or are
associated with invalid voxel fields or have been incorrectly
specified.
.SH SEE ALSO
VolPack(3), vpCreateContext(3), vpSetClassifierTable(3),
vpClassifyScalars(3), vpClassifyScanline(3)