.\" 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 vpClassifyScalars 3 "" VolPack
.SH NAME
vpClassifyScalars \- create a preclassified volume from scalar data
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpClassifyScalars(\fIvpc, scalar_data, length, scalar_field,
gradient_field, norm_field\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
unsigned char *\fIscalars;\fR
.FA
int \fIsize;\fR
.FA
int \fIscalar_field, gradient_field, norm_field;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIscalar_data\fR
A 3D array containing one 8-bit scalar value for each voxel in the
volume.
.IP \fIlength\fR
Size of \fIscalar_data\fR in bytes.
.IP \fIscalar_field\fR
Field number identifying a voxel field for storing the scalar value.
.IP \fIgradient_field\fR
Field number identifying a voxel field for storing the gradient
magnitude of the scalar value.
.IP \fInorm_field\fR
Field number identifying a voxel field for storing the surface normal
vector for the voxel.
.SH DESCRIPTION
\fBvpClassifyScalars\fR combines the functionality of
\fBvpVolumeNormals\fR and \fBvpClassifyVolume\fR to produce a
preclassified volume directly from a 3D array of scalar values without
creating a 3D voxel array.  This routine is useful for preparing large
data sets for rendering with a fixed classification function,
especially if the 3D voxel array would be too large to fit in main
memory.  The primary limitation is that the only fields each voxel may
contain are the fields produced by \fBvpVolumeNormals\fR: an 8-bit
scalar value, and 8-bit gradient and/or a 16-bit surface normal
vector.  See also \fBvpClassifyScanline\fR for processing one scanline of
a scalar array at a time.
.PP
To use the function, first define the volume size, voxel size, and
voxel fields as you would before calling \fBvpVolumeNormals\fR.
However, there is no need to call \fBvpSetRawVoxels.\fR  Also define
the opacity transfer function (see vpSetClassifierTable(3)).  Then call
\fBvpClassifyScalars\fR with the same arguments you would use for
\fBvpVolumeNormals;\fR see vpVolumeNormals(3) for more details.  The
result is a preclassified volume, as described in vpClassifyVolume(3).
If a voxel array has been declared it is not used or modified.
.PP
Any existing preclassified volume data is destroyed.
.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_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), vpVolumeNormals(3),
vpSetClassifierTable(3), vpClassifyVolume(3), vpClassifyScanline(3)