1vpExtract(3) Library Functions Manual vpExtract(3)
2
6 vpExtract - extract one field from a rectangular region of a volume
7
9 #include <volpack.h>
10 vpResult
12 vpExtract(vpc, volume_type, x0, y0, z0, x1, y1, z1, field, dst,
13 dst_size, dst_xstride, dst_ystride, dst_zstride)
14 vpContext *vpc;
15 int volume_type;
16 int x0, y0, z0;
17 int x1, y1, z1;
18 int field;
19 void *dst;
20 int dst_size;
21 int dst_xstride, dst_ystride, dst_zstride;
22
24 vpc VolPack context from vpCreateContext.
25 volume_type
27 A code indicating which volume data structure to extract the
28 region from (VP_RAW_VOLUME, VP_CLASSIFIED_VOLUME, VP_CLX_VOLUME,
29 VP_CLY_VOLUME or VP_CLZ_VOLUME)
30 x0, y0, z0
32 Origin of the extracted region in the voxel array.
33 x1, y1, z1
35 Opposite corner of the extracted region in the voxel array.
36 field A voxel field number identifying the field to extract, or one of
38 these special codes: VP_OPACITY_FIELD, VP_CORRECTED_OPAC_FIELD,
39 VP_COLOR_FIELD.
40 dst Destination array.
42 dst_size
44 Size of destination array in bytes.
45 dst_xstride, dst_ystride, dst_zstride
47 Strides (in bytes) for the X, Y and Z dimensions of the destina‐
48 tion array.
49
51 vpExtract is used to extract one field from a rectangular region of the
52 3D voxel array or the preclassified volume and store the result in a
53 separate array. It is also possible to retrieve computed voxel opaci‐
54 ties or colors.
55 The volume_type argument is used to choose which data structure the
57 region should be extracted from. The choices are:
58 VP_RAW_VOLUME
60 Extract from the 3D voxel array (see vpSetRawVoxels(3)).
61 VP_CLASSIFIED_VOLUME
63 Extract from the preclassified volume (see vpClassifyVolume(3)).
64 The are three copies of the voxel data in the preclassified vol‐
65 ume, one for each principal viewing axis. The copy which will
66 result in the fastest access (best memory stride) is selected.
67 VP_CLX_VOLUME
69 Extract from the preclassified volume used for X-axis viewing.
70 VP_CLY_VOLUME
72 Extract from the preclassified volume used for Y-axis viewing.
73 VP_CLZ_VOLUME
75 Extract from the preclassified volume used for Z-axis viewing.
76 The last three choices for the volume_type argument are usually used
78 only for debugging.
79 The next six arguments give the coordinates of the corners of the
81 extracted region in the volume. The coordinates are indexes into the
82 array.
83 The field argument is used to select which voxel field to extract. Any
85 of the voxel field numbers previously specified with vpVoxelField may
86 be specified. The output array must be sized appropriately for the
87 dimensions of the region and the size of the extracted field. The fol‐
88 lowing special constants may also be used instead of a voxel field num‐
89 ber:
90 VP_OPACITY_FIELD
92 Return voxel opacities for voxels in the indicated region. If
93 the 3D voxel array is selected then the opacities are computed
94 on-the-fly using the current opacity transfer function. The
95 minimum opacity threshold is ignored. If the preclassified vol‐
96 ume is selected then the precomputed opacities are extracted.
97 Opacities below the minimum opacity threshold at the time the
98 volume was classified are set to 0. The output array should
99 have type unsigned char, and the opacities are stored as number
100 between 0 (transparent) and 255 (opaque).
101 VP_CORRECTED_OPAC_FIELD
103 This option is the same as the VP_OPACITY_FIELD option, except
104 that voxel opacities are corrected for the current view trans‐
105 formation. The opacity transfer function is assumed to produce
106 the opacity of a voxel viewed perpendicular to one face of the
107 volume with no scale factor. If the voxel has been scaled or
108 rotated with respect to the viewer then the apparent opacity
109 must be corrected.
110 VP_COLOR_FIELD
112 Return voxel colors for voxels in the indicated region. The
113 colors are computed on-the-fly using the current shading, light‐
114 ing and material parameters. The output array should have type
115 unsigned char, and each color channel is stored as number
116 between 0 (off) and 255 (full intensity). The number of color
117 channels per pixels is determined by the current shading parame‐
118 ters. (Not currently supported for preclassified volumes.)
119 The remaining arguments specify the output array, its size (for error
121 checking), and the stride for each dimension (to allow padding the end
122 of scanlines or storing the result in a higher-dimension array).
123
125 The normal return value is VP_OK. The following error return values
126 are possible:
127 VPERROR_BAD_VALUE
129 The volume coordinates are out of bounds or invalid (x0 > x1,
130 etc.), or the field number is invalid.
131 VPERROR_BAD_SIZE
133 The destination array size is incorrect.
134 VPERROR_BAD_VOLUME
136 The volume data does not exist.
137 VPERROR_BAD_OPTION
139 The volume_type argument is invalid.
140 VPERROR_BAD_VOLUME
142 The volume size or data is missing or invalid.
143 VPERROR_BAD_VOXEL
145 The voxel fields are incorrectly defined.
146 VPERROR_BAD_CLASSIFIER
148 The opacity transfer function is incorrectly specified.
149 VPERROR_BAD_SHADER
151 The shading parameters have been incorrectly specified.
152 VPERROR_SINGULAR
154 One or more of the view transformation matrices is singular.
155
157 VolPack(3), vpCreateContext(3)
158VolPack vpExtract(3)