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)

VolPack                                                                                             vpExtract(3)