Man Linux: Main Page and Category List

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)