1vpCreateMinMaxOctree(3) Library Functions Manual vpCreateMinMaxOctree(3)
2
6 vpCreateMinMaxOctree, vpMinMaxOctreeThreshold, vpDestroyMinMaxOctree -
7 create/destroy a min-max octree for optimized rendering
8
10 #include <volpack.h>
11 vpResult
13 vpCreateMinMaxOctree(vpc, root_node_size, base_node_size)
14 vpContext *vpc;
15 int root_node_size, base_node_size;
16 vpResult
18 vpMinMaxOctreeThreshold(vpc, param_num, range)
19 vpContext *vpc;
20 int param_num, range;
21 vpResult
23 vpDestroyMinMaxOctree(vpc)
24 vpContext *vpc;
25
27 vpc VolPack context from vpCreateContext.
28 root_node_size
30 Number of voxels per side in the top level (largest nodes) of
31 the octree. Not currently used.
32 base_node_size
34 Number of voxels per side in the bottom level (smallest nodes)
35 of the octree. Must be a power of 2.
36 param_num
38 Identifying number of one parameter of the opacity transfer
39 function.
40 range Range threshold for one parameter of the opacity transfer func‐
42 tion. If an octree node spans a larger range then it is subdi‐
43 vided.
44
46 These routines are used to create and destroy a min-max octree, an
47 internal data structure that is used to accelerate classifying and ren‐
48 dering volume data in a 3D voxel array. The octree is a hierarchical
49 data structure that contains minimum and maximum values for each voxel
50 field. It does not duplicate the data in the voxel array. The octree
51 is not used with preclassified volumes (see vpClassifyVolume(3)).
52 Before creating an octree, declare a 3D voxel array using vpSetVolume‐
54 Size, vpSetVoxelSize, vpSetVoxelField and vpSetRawVoxels, and initial‐
55 ize parameters for the opacity transfer function by calling vpSetClas‐
56 sifierTable. Then initialize the voxel data in the array. The lookup
57 tables for the opacity transfer function do not need to be initialized.
58 Now call vpMinMaxOctreeThreshold once for each parameter to the opacity
60 transfer function. The parameter number is the same number as the
61 parameter number you would pass to vpClassifierTable. The range argu‐
62 ment specifies a "small" range of values for the corresponding parame‐
63 ter. The opacity of a voxel should not vary much for voxels within
64 this range of parameter space. Choosing a value which is too small or
65 too large may result in a reduced performance benefit during rendering.
66 The function vpOctreeMask can be used to visualize the effectiveness of
67 various parameter ranges. Note that you must choose the voxel field
68 associated with each opacity transfer function parameter in advance of
69 creating the octree (by calling vpSetClassiferTable), but the opacity
70 transfer function itself does not need to be known since the lookup
71 tables do not need to be initialized. In the current implementation
72 all of the parameters must be one or two-byte voxel fields; four-byte
73 fields are not allowed.
74 Finally, call vpCreateMinMaxOctree to actually compute the octree. The
76 arguments specify the largest and smallest node size. These values can
77 be used to trade off storage size of the octree for increased resolu‐
78 tion. The octree is stored in the rendering context and is used auto‐
79 matically in subsequent calls to vpClassifyVolume and vpRenderRawVol‐
80 ume. Only one octree may be stored in a context at a time. If an
81 octree already exists when vpCreateMinMaxOctree is called then the old
82 octree is destroyed.
83 If the data in the voxel array changes then the min-max octree must be
85 explicitly recomputed by calling vpCreateMinMaxOctree again before the
86 next call to vpClassifyVolume or vpRenderRawVolume.
87 vpDestroyMinMaxOctree destroys the current min-max octree and frees the
89 associated storage.
90
92 The current octree parameters can be retrieved with the following state
93 variable codes (see vpGeti(3)): VP_CLASSIFY_FIELD_COUNT, VP_CLAS‐
94 SIFY_FIELDS, VP_MMOCTREE_THRESHOLDS, VP_MMOCTREE_SIZE.
95
97 The normal return value for all three functions is VP_OK. vpMinMaxOc‐
98 treeThreshold can return the following error value:
99 VPERROR_BAD_VALUE
101 The parameter number is invalid.
102 vpCreateMinMaxOctree can return the following error values:
104 VPERROR_BAD_VALUE
106 The node size arguments are not a power of two.
107 VPERROR_BAD_VOXEL
109 The voxel size or the voxel fields have not been specified or
110 have been incorrectly specified, or the number of parameters to
111 the opacity transfer function has been incorrectly specified.
112 VPERROR_BAD_VOLUME
114 The volume array or volume dimensions have not been specified,
115 or the size of the volume array does not match the volume dimen‐
116 sions.
117 VPERROR_BAD_CLASSIFIER
119 The fields specified as parameters to the opacity transfer func‐
120 tion are invalid or do not have valid sizes.
121 VPERROR_LIMIT_EXCEEDED
123 The volume is too large, so the maximum size of the octree has
124 been exceeded. Change the constant VP_MAX_OCTREE_LEVELS in vol‐
125 pack.h and recompile the VolPack library.
126
128 VolPack(3), vpCreateContext(3), vpClassifyVolume(3), vpOctreeMask(3),
129 vpRenderRawVolume(3)
130VolPack vpCreateMinMaxOctree(3)