1vpVolumeNormals(3) Library Functions Manual vpVolumeNormals(3)
2
6 vpVolumeNormals - compute surface normal vectors and gradient magni‐
7 tudes for a volume
8
10 #include <volpack.h>
11 vpResult
13 vpVolumeNormals(vpc, scalar_data, length, scalar_field, grad_field,
14 norm_field)
15 vpContext *vpc;
16 unsigned char *scalar_data;
17 int length;
18 int scalar_field;
19 int grad_field;
20 int norm_field;
21
23 vpc VolPack context from vpCreateContext.
24 scalar_data
26 3D array of scalar samples.
27 length Size of scalar_data array in bytes.
29 scalar_field
31 Voxel field number indicating the field in which to store the
32 scalar samples.
33 grad_field
35 Voxel field number indicating the field in which to store the
36 gradient magnitudes of the scalar samples.
37 norm_field
39 Voxel field number indicating the field in which to store
40 encoded surface normal vectors.
41
43 vpVolumeNormals is used to precompute values for voxel fields used in
44 classification and shading algorithms. The input is a 3D array of
45 scalar values; a separate routine is provided for processing scanlines
46 of voxel data (see vpScanlineNormals(3)). For each voxel, the routine
47 computes an approximation for the gradient of the scalar field (using a
48 central-difference operator). From this vector the routine can compute
49 the magnitude of the gradient, which is useful for some classification
50 schemes (see vpSetClassifierTable(3)), and a surface normal vector in
51 the direction of the gradient vector, which is used to implement light‐
52 ing models (see vpShadeTable(3)). The scalar value, gradient magnitude
53 and surface normal vector are then stored into the fields of the voxel
54 array, which is separate from the array of scalar values.
55 The scalar array must be an array of 8-bit values (other sizes are not
57 currently supported). The dimensions of the array must match the vol‐
58 ume dimensions previously specified with vpSetVolumeSize. The size
59 argument is used to make sure the array has the correct size. The
60 voxel array must also be initialized by calling vpSetRawVoxels prior to
61 calling vpVolumeNormals.
62 The three voxel field number arguments indicate which voxel fields the
64 computed information should be stored into, and which field the scalar
65 samples should be copied to. The field numbers must correspond to
66 appropriately-sized voxel fields previously specified with vpSetVox‐
67 elField. Any of these arguments can be the constant VP_SKIP_FIELD, in
68 which case the corresponding quantity is not computed or copied. The
69 voxel fields for the scalar value and the gradient magnitude must be
70 one-byte fields, and the field for the surface normal vector must be a
71 two-byte field. The constants VP_SCALAR_MAX, VP_GRAD_MAX and
72 VP_NORM_MAX give the maximum value that might be stored in each field,
73 respectively. The value stored in the surface normal vector field is
74 actually an encoded surface normal; see vpNormalIndex(3).
75
77 The normal return value is VP_OK. The following error return values
78 are possible:
79 VPERROR_BAD_SIZE
81 The size of the scalar array does not match the volume dimen‐
82 sions.
83 VPERROR_BAD_VALUE
85 One or more of the voxel fields specified is invalid, or the
86 corresponding voxel field has the wrong size.
87 VPERROR_BAD_VOXEL
89 The voxel size or the voxel fields have not been specified or
90 have been incorrectly specified.
91 VPERROR_BAD_VOLUME
93 The volume array or volume dimensions have not been specified,
94 or the size of the volume array does not match the volume dimen‐
95 sions.
96
98 VolPack(3), vpCreateContext(3), vpNormalIndex(3), vpScanlineNormals(3),
99 vpSetClassifierTable(3), vpSetLookupShader(3)
100VolPack vpVolumeNormals(3)