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

# ScanNormals(3)

compute surface normal vectors and gradient magnitudes for a scanline

## NAME

vpScanlineNormals - compute surface normal vectors and gradient magnitudes for a scanline

## SYNOPSIS

\#include \<volpack.h\>

vpResult

**vpScanlineNormals(***vpc, length, scalar\_data, scalar\_minus\_y,* *scalar\_plus\_y, scalar\_minus\_z, scalar\_plus\_z, voxel\_data, scalar\_field,* *grad\_field, norm\_field***)**

-

  vpContext \**vpc;*

-

  int *length;*

-

  unsigned char \**scalar\_data;*

-

  unsigned char \**scalar\_minus\_y,* \**scalar\_plus\_y;*

-

  unsigned char \**scalar\_minus\_z,* \**scalar\_plus\_z;*

-

  void \**voxel\_data;*

-

  int *scalar\_field;*

-

  int *grad\_field;*

-

  int *norm\_field;*

## ARGUMENTS

- *vpc*

  VolPack context from **vpCreateContext.**

- *length*

  Size of *scalar\_data* array in bytes.

- *scalar\_data*

  1D array of scalar samples.

- *scalar\_minus\_y*

  1D array of scalar samples adjacent to *scalar\_data* in the -Y direction.

- *scalar\_plus\_y*

  1D array of scalar samples adjacent to *scalar\_data* in the +Y direction.

- *scalar\_minus\_z*

  1D array of scalar samples adjacent to *scalar\_data* in the -Z direction.

- *scalar\_plus\_z*

  1D array of scalar samples adjacent to *scalar\_data* in the +Z direction.

- *voxel\_data*

  1D array of voxels for storing results.

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

**vpScanlineNormals** is used to precompute values for voxel fields used in classification and shading algorithms.  The input is a collection of 5 adjacent 1D arrays of scalar values; a separate routine is provided for processing a full 3D array of voxel data (see vpVolumeNormals(3)).  **vpScanlineNormals** is useful for loading large volumes into memory scanline-by-scanline and precomputing voxel fields incrementally, instead of loading a complete copy of the 3D scalar array in addition to the voxel array.  In all other respects this routine is identical in function to **vpVolumeNormals**.

The 1D scalar arrays must be arrays of 8-bit values (other sizes are not currently supported).  The *length* parameter indicates both the size and the number of elements in each of the scalar arrays. **vpScanlineNormals** performs the computation described in vpVolumeNormals(3), but only for the single scanline specified by *scalar\_data*.  The other four scanline arguments must be the immediately adjacent scanlines and are used to compute the gradient.

The results are stored in the *voxel\_data* array which must have space for the same number of voxels as the length of one scalar scanline.  The size of a voxel must be specified with **vpSetVoxelSize** before calling **vpScanlineNormals,** but it is not necessary to call **vpSetRawVoxels.**  The arguments *scalar\_field, grad\_field* and *norm\_field* specify which voxel fields the computed quantities should be stored into.  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\_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.

## SEE ALSO

[VolPack(3)](/VolPack/3.md), vpCreateContext(3), vpNormalIndex(3), vpVolumeNormals(3), vpSetClassifierTable(3), vpSetLookupShader(3)