NAME
vpExtract - extract one field from a rectangular region of a volume
SYNOPSIS
#include <volpack.h>
vpResult
vpExtract(vpc, volume_type, x0, y0, z0, x1, y1, z1, field, dst,
dst_size, dst_xstride, dst_ystride, dst_zstride)
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;
ARGUMENTS
vpc VolPack context from vpCreateContext.
volume_type
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)
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.
field 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.
dst Destination array.
dst_size
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 array.
DESCRIPTION
vpExtract 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.
The volume_type argument is used to choose which data structure the
region should be extracted from. The choices are:
VP_RAW_VOLUME
Extract from the 3D voxel array (see vpSetRawVoxels(3)).
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.
VP_CLX_VOLUME
Extract from the preclassified volume used for X-axis viewing.
VP_CLY_VOLUME
Extract from the preclassified volume used for Y-axis viewing.
VP_CLZ_VOLUME
Extract from the preclassified volume used for Z-axis viewing.
The last three choices for the volume_type argument are usually used
only for debugging.
The next six arguments give the coordinates of the corners of the
extracted region in the volume. The coordinates are indexes into the
array.
The field argument is used to select which voxel field to extract. Any
of the voxel field numbers previously specified with vpVoxelField 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:
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).
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.
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.)
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).
ERRORS
The normal return value is VP_OK. The following error return values
are possible:
VPERROR_BAD_VALUE
The volume coordinates are out of bounds or invalid (x0 > x1,
etc.), or the field number is invalid.
VPERROR_BAD_SIZE
The destination array size is incorrect.
VPERROR_BAD_VOLUME
The volume data does not exist.
VPERROR_BAD_OPTION
The volume_type argument is invalid.
VPERROR_BAD_VOLUME
The volume size or data is missing or invalid.
VPERROR_BAD_VOXEL
The voxel fields are incorrectly defined.
VPERROR_BAD_CLASSIFIER
The opacity transfer function is incorrectly specified.
VPERROR_BAD_SHADER
The shading parameters have been incorrectly specified.
VPERROR_SINGULAR
One or more of the view transformation matrices is singular.
SEE ALSO
VolPack(3), vpCreateContext(3)