vpVolumeNormals(3) | Library Functions Manual | vpVolumeNormals(3) |

# NAME¶

vpVolumeNormals - compute surface normal vectors and gradient magnitudes for a volume

# SYNOPSIS¶

#include <volpack.h>

vpResult

**vpVolumeNormals(***vpc, scalar_data, length,
scalar_field,* *grad_field, norm_field***)**

- vpContext *
*vpc;* - unsigned char *
*scalar_data;* - int
*length;* - int
*scalar_field;* - int
*grad_field;* - int
*norm_field;*

# ARGUMENTS¶

*vpc*- VolPack context from
**vpCreateContext.** *scalar_data*- 3D array of scalar samples.
*length*- Size of
*scalar_data*array in bytes. *scalar_field*- Voxel field number indicating the field in which to store the scalar samples.
*grad_field*- Voxel field number indicating the field in which to store the gradient magnitudes of the scalar samples.
*norm_field*- Voxel field number indicating the field in which to store encoded surface normal vectors.

# DESCRIPTION¶

**vpVolumeNormals** is used to precompute values for voxel
fields used in classification and shading algorithms. The input is a 3D
array of scalar values; a separate routine is provided for processing
scanlines of voxel data (see vpScanlineNormals(3)). For each voxel, the
routine computes an approximation for the gradient of the scalar field
(using a central-difference operator). From this vector the routine can
compute the magnitude of the gradient, which is useful for some
classification schemes (see vpSetClassifierTable(3)), and a surface normal
vector in the direction of the gradient vector, which is used to implement
lighting models (see vpShadeTable(3)). The scalar value, gradient magnitude
and surface normal vector are then stored into the fields of the voxel
array, which is separate from the array of scalar values.

The scalar array must be an array of 8-bit values (other sizes are
not currently supported). The dimensions of the array must match the volume
dimensions previously specified with **vpSetVolumeSize**. The *size*
argument is used to make sure the array has the correct size. The voxel
array must also be initialized by calling **vpSetRawVoxels** prior to
calling **vpVolumeNormals**.

The three voxel field number arguments indicate which voxel fields
the computed information should be stored into, and which field the scalar
samples should be copied to. The field numbers must correspond to
appropriately-sized voxel fields previously specified with
**vpSetVoxelField**. Any of these arguments can be the constant
VP_SKIP_FIELD, in which case the corresponding quantity is not computed or
copied. The voxel fields for the scalar value and the gradient magnitude
must be one-byte fields, and the field for the surface normal vector must be
a two-byte field. The constants VP_SCALAR_MAX, VP_GRAD_MAX and VP_NORM_MAX
give the maximum value that might be stored in each field, respectively. The
value stored in the surface normal vector field is actually an encoded
surface normal; see vpNormalIndex(3).

# ERRORS¶

The normal return value is VP_OK. The following error return values are possible:

- VPERROR_BAD_SIZE
- The size of the scalar array does not match the volume dimensions.
- VPERROR_BAD_VALUE
- One or more of the voxel fields specified is invalid, or the corresponding voxel field 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_VOLUME
- The volume array or volume dimensions have not been specified, or the size of the volume array does not match the volume dimensions.

# SEE ALSO¶

VolPack(3), vpCreateContext(3), vpNormalIndex(3), vpScanlineNormals(3), vpSetClassifierTable(3), vpSetLookupShader(3)

VolPack |