---
name: "ClsfyVolume"
section: "3"
platform: "linux"
package: "libvolpack1-dev"
version: "1.0b3-10"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/ClsfyVolume"
---

# ClsfyVolume(3)

create/destroy a preclassified volume for fast rendering

## NAME

vpClassifyVolume, vpDestroyClassifiedVolume - create/destroy a preclassified volume for fast rendering

## SYNOPSIS

\#include \<volpack.h\>

vpResult

**vpClassifyVolume(***vpc***)**

-

  vpContext \**vpc;*

vpResult

**vpDestroyClassifyVolume(***vpc***)**

-

  vpContext \**vpc;*

## ARGUMENTS

- *vpc*

  VolPack context from **vpCreateContext.**

## DESCRIPTION

**vpClassifyVolume** is used to compute a preclassified volume for the fast rendering algorithm.  The preclassified volume is an internal data structure optimized for rendering speed.  **vpClassifyVolume** should be called after a voxel array has been defined (with **vpSetVolumeSize, vpSetVoxelSize, vpSetVoxelField,** and **vpSetRawVoxels**) and initialized (with **vpVolumeNormals** or a user-defined routine).  An opacity transfer function must also be defined with **vpSetClassifierTable,** and the minimum opacity threshold should be set with the VP\_MIN\_VOXEL\_OPACITY parameter to **vpSeti**.  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)).

**vpClassifyVolume** 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 **vpSeti** 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.

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).

Once **vpClassifyVolume** 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 **vpClassifyVolume** again.  Only one preclassified volume may be stored in a rendering context at a time.  Calling **vpClassifyVolume** causes any existing preclassified volume to be destroyed.

**vpDestroyClassifiedVolume** destroys the current preclassified volume and frees the associated space.

## 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.

## ERRORS

The normal return value is VP\_OK.  The following error return values are possible:

- VPERROR\_BAD\_VOXEL

  The voxel size or the voxel fields have not been specified or have been incorrectly specified.

- 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.

- VPERROR\_BAD\_CLASSIFIER

  The opacity transfer function tables have invalid sizes or are associated with invalid voxel fields or have been incorrectly specified.

## SEE ALSO

[VolPack(3)](/VolPack/3.md), vpCreateContext(3), vpSetClassifierTable(3), vpClassifyScalars(3), vpClassifyScanline(3)