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

# OctreeMask(3)

compute a mask representing one level of a min-max octree

## NAME

vpOctreeMask - compute a mask representing one level of a min-max octree

## SYNOPSIS

\#include \<volpack.h\>

vpResult

**vpOctreeMask(***vpc, array, array\_size, max\_level***)**

-

  vpContext *\*vpc;*

-

  unsigned char \**array;*

-

  int *array\_size;*

-

  int *max\_level;*

## ARGUMENTS

- *vpc*

  VolPack context from **vpCreateContext.**

- *array*

  A 3D array for storing the mask.

- *array\_size*

  Size of *array* in bytes.

- *max\_level*

  Maximum octree level to descend to.

## DESCRIPTION

**vpOctreeMask** is used for performance debugging when rendering volumes with a min-max octree.  During rendering the min-max octree is used to help determine which voxels are transparent.  The time required to make this determination can be minimized by an appropriate choice for the range parameters for **vpMinMaxOctreeThreshold** and the node size parameters for **vpCreateMinMaxOctree**. **vpOctreeMask** provides information that can help to determine whether a set of parameters works effectively or not.

The output of the routine is stored in a 3D array of bytes that has the same dimensions as the volume (although each element is only one byte, regardless of the size of a voxel).  For each voxel in the volume the corresponding byte in the output array is set by **vpOctreeMask** to one of three values: 0 if the voxel is definitely transparent, 255 if the voxel may be non-transparent, or 128 if the voxel may be non-transparent and there is more detailed information available at unvisited levels of the octree.  The *max\_level* argument specifies the deepest level of the octree to be visited (the root level is level 0).

A suggested way to use this routine is to compute an octree using a particular set of parameters and then call **vpOctreeMask** with several different values for *max\_level.*  For each resulting mask array, look at slices (or create a volume rendering!) and see how accurately the mask captures the general shape of the data in the original volume.  The best set of parameters results in a mask that captures the general shape without an excessively small value for the minimum octree node size (which would result in a very large data structure and a lot of traversal overhead).

## ERRORS

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

- VPERROR\_BAD\_SIZE

  There is no octree or the output array has the wrong size.

- VPERROR\_BAD\_VOXEL

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

- 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), vpCreateMinMaxOctree(3)