1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
.\" Copyright (c) 1994 The Board of Trustees of The Leland Stanford
.\" Junior University. All rights reserved.
.\"
.\" Permission to use, copy, modify and distribute this software and its
.\" documentation for any purpose is hereby granted without fee, provided
.\" that the above copyright notice and this permission notice appear in
.\" all copies of this software and that you do not sell the software.
.\" Commercial licensing is available by contacting the author.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\" Author:
.\" Phil Lacroute
.\" Computer Systems Laboratory
.\" Electrical Engineering Dept.
.\" Stanford University
.\"
.\" $Date: 1994/12/31 19:49:53 $
.\" $Revision: 1.1 $
.\"
.\" Macros
.\" .FS <type> -- function start
.\" <type> is return type of function
.\" name and arguments follow on next line
.de FS
.PD 0v
.PP
\\$1
.HP 8
..
.\" .FA -- function arguments
.\" one argument declaration follows on next line
.de FA
.IP " " 4
..
.\" .FE -- function end
.\" end of function declaration
.de FE
.PD
..
.\" .DS -- display start
.de DS
.IP " " 4
..
.\" .DE -- display done
.de DE
.LP
..
.TH vpExtract 3 "" VolPack
.SH NAME
vpExtract \- extract one field from a rectangular region of a volume
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpExtract(\fIvpc, volume_type, x0, y0, z0, x1, y1, z1, field, dst,
dst_size, dst_xstride, dst_ystride, dst_zstride\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
int \fIvolume_type;\fR
.FA
int \fIx0, y0, z0;\fR
.FA
int \fIx1, y1, z1;\fR
.FA
int \fIfield;\fR
.FA
void *\fIdst;\fR
.FA
int \fIdst_size;\fR
.FA
int \fIdst_xstride, dst_ystride, dst_zstride;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIvolume_type\fR
A code indicating which volume data structure to extract the region
from (VP_RAW_VOLUME, VP_CLASSIFIED_VOLUME, VP_CLX_VOLUME,
VP_CLY_VOLUME or VP_CLZ_VOLUME)
.IP "\fIx0, y0, z0\fR"
Origin of the extracted region in the voxel array.
.IP "\fIx1, y1, z1\fR"
Opposite corner of the extracted region in the voxel array.
.IP \fIfield\fR
A voxel field number identifying the field to extract, or one of these
special codes: VP_OPACITY_FIELD, VP_CORRECTED_OPAC_FIELD, VP_COLOR_FIELD.
.IP \fIdst\fR
Destination array.
.IP \fIdst_size\fR
Size of destination array in bytes.
.IP "\fIdst_xstride, dst_ystride, dst_zstride\fR"
Strides (in bytes) for the X, Y and Z dimensions of the destination array.
.SH DESCRIPTION
\fBvpExtract\fR is used to extract one field from a rectangular region
of the 3D voxel array or the preclassified volume and store the result
in a separate array. It is also possible to retrieve computed
voxel opacities or colors.
.PP
The \fIvolume_type\fR argument is used to choose which data structure
the region should be extracted from. The choices are:
.IP VP_RAW_VOLUME
Extract from the 3D voxel array (see vpSetRawVoxels(3)).
.IP VP_CLASSIFIED_VOLUME
Extract from the preclassified volume (see vpClassifyVolume(3)). The are
three copies of the voxel data in the preclassified volume, one for
each principal viewing axis. The copy which will result in the
fastest access (best memory stride) is selected.
.IP VP_CLX_VOLUME
Extract from the preclassified volume used for X-axis viewing.
.IP VP_CLY_VOLUME
Extract from the preclassified volume used for Y-axis viewing.
.IP VP_CLZ_VOLUME
Extract from the preclassified volume used for Z-axis viewing.
.PP
The last three choices for the \fIvolume_type\fR argument are usually
used only for debugging.
.PP
The next six arguments give the coordinates of the corners of the
extracted region in the volume. The coordinates are indexes into the
array.
.PP
The \fIfield\fR argument is used to select which voxel field to
extract. Any of the voxel field numbers previously specified with
\fBvpVoxelField\fR may be specified. The output array must be sized
appropriately for the dimensions of the region and the size of the
extracted field. The following special constants may also be used
instead of a voxel field number:
.IP VP_OPACITY_FIELD
Return voxel opacities for voxels in the indicated region. If the
3D voxel array is selected then the opacities are computed on-the-fly
using the current opacity transfer function. The minimum opacity
threshold is ignored. If the preclassified volume is selected then
the precomputed opacities are extracted. Opacities below the minimum
opacity threshold at the time the volume was classified are set to 0.
The output array should have type unsigned char, and the opacities are
stored as number between 0 (transparent) and 255 (opaque).
.IP VP_CORRECTED_OPAC_FIELD
This option is the same as the VP_OPACITY_FIELD option, except that
voxel opacities are corrected for the current view transformation. The
opacity transfer function is assumed to produce the opacity of a voxel
viewed perpendicular to one face of the volume with no scale factor.
If the voxel has been scaled or rotated with respect to the viewer
then the apparent opacity must be corrected.
.IP VP_COLOR_FIELD
Return voxel colors for voxels in the indicated region. The colors
are computed on-the-fly using the current shading, lighting and
material parameters. The output array should have type unsigned char,
and each color channel is stored as number between 0 (off) and 255
(full intensity). The number of color channels per pixels is
determined by the current shading parameters. (Not currently
supported for preclassified volumes.)
.PP
The remaining arguments specify the output array, its size (for error
checking), and the stride for each dimension (to allow padding the end
of scanlines or storing the result in a higher-dimension array).
.SH ERRORS
The normal return value is VP_OK. The following error return values
are possible:
.IP VPERROR_BAD_VALUE
The volume coordinates are out of bounds or invalid (x0 > x1, etc.),
or the field number is invalid.
.IP VPERROR_BAD_SIZE
The destination array size is incorrect.
.IP VPERROR_BAD_VOLUME
The volume data does not exist.
.IP VPERROR_BAD_OPTION
The \fIvolume_type\fR argument is invalid.
.IP VPERROR_BAD_VOLUME
The volume size or data is missing or invalid.
.IP VPERROR_BAD_VOXEL
The voxel fields are incorrectly defined.
.IP VPERROR_BAD_CLASSIFIER
The opacity transfer function is incorrectly specified.
.IP VPERROR_BAD_SHADER
The shading parameters have been incorrectly specified.
.IP VPERROR_SINGULAR
One or more of the view transformation matrices is singular.
.SH SEE ALSO
VolPack(3), vpCreateContext(3)
|
