vpExtract - extract one field from a rectangular region of a volume
vpExtract(vpc, volume_type, x0, y0, z0, x1, y1, z1,
field, dst, dst_size, dst_xstride, dst_ystride,
- vpContext *vpc;
- int volume_type;
- int x0, y0, z0;
- int x1, y1, z1;
- int field;
- void *dst;
- int dst_size;
- int dst_xstride, dst_ystride, dst_zstride;
- VolPack context from vpCreateContext.
- 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
- x0, y0, z0
- Origin of the extracted region in the voxel array.
- x1, y1, z1
- Opposite corner of the extracted region in the voxel array.
- A voxel field number identifying the field to extract, or one of these
special codes: VP_OPACITY_FIELD, VP_CORRECTED_OPAC_FIELD,
- Destination array.
- Size of destination array in bytes.
- dst_xstride, dst_ystride, dst_zstride
- Strides (in bytes) for the X, Y and Z dimensions of the destination
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.
argument is used to choose which data structure the
region should be extracted from. The choices are:
- Extract from the 3D voxel array (see vpSetRawVoxels(3)).
- 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.
- Extract from the preclassified volume used for X-axis viewing.
- Extract from the preclassified volume used for Y-axis viewing.
- Extract from the preclassified volume used for Z-axis viewing.
The last three choices for the volume_type
argument are usually used only
The next six arguments give the coordinates of the corners of the extracted
region in the volume. The coordinates are indexes into the array.
argument is used to select which voxel field to extract. Any of
the voxel field numbers previously specified with vpVoxelField
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:
- 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).
- 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.
- 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
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).
The normal return value is VP_OK. The following error return values are
- The volume coordinates are out of bounds or invalid (x0 > x1, etc.), or
the field number is invalid.
- The destination array size is incorrect.
- The volume data does not exist.
- The volume_type argument is invalid.
- The volume size or data is missing or invalid.
- The voxel fields are incorrectly defined.
- The opacity transfer function is incorrectly specified.
- The shading parameters have been incorrectly specified.
- One or more of the view transformation matrices is singular.