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)