NAME

       vpResample, vpResample2D, vpResample3D - resample an array

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpResample(vpc,    num_dimens,    src_dimens,    dst_dimens,   src_strides,   dst_strides,
               element_type, src_array, dst_array)
           vpContext *vpc;
           int num_dimens;
           int *src_dimens, *dst_dimens;
           int *src_strides, *dst_strides;
           int element_type;
           void *src_array, *dst_array;

       vpResult
       vpResample2D(src_array, src_x, src_y, dst_array, dst_x, dst_y, element_type, filter_type)
           void *src_array;
           int src_x, src_y;
           void *dst_array;
           int dst_x, dst_y;
           int element_type;
           int filter_type;

       vpResult
       vpResample3D(src_array, src_x, src_y, src_z, dst_array, dst_x, dst_y, dst_z, element_type,
               filter_type)
           void *src_array;
           int src_x, src_y, src_z;
           void *dst_array;
           int dst_x, dst_y, dst_z;
           int element_type;
           int filter_type;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       num_dimens
              Number of dimensions in the input and output arrays.

       src_dimens
              Array containing the dimensions of the input array.

       dst_dimens
              Array containing the dimensions of the output array.

       src_strides
              Array containing the strides for each dimension of the input array.

       dst_strides
              Array containing the strides for each dimension of the output array.

       element_type
              Constant  specifying  the  data  type  of  the array elements (VP_UCHAR, VP_USHORT,
              VP_FLOAT).

       src_array
              Input array containing input data.

       dst_array
              Output array for result data.

       src_x, src_y, src_z
              Dimensions of the input array.

       dst_x, dst_y, dst_z
              Dimensions of the result array.

       filter_type
              Constant specifying one of the predefined filters (VP_BOX_FILTER, VP_LINEAR_FILTER,
              VP_GAUSSIAN_FILTER, VP_BSPLINE_FILTER, VP_MITCHELL_FILTER).

DESCRIPTION

       vpResample is used to resample an array to a new grid with a different resolution.  It can
       be used to scale up or decimate an array of  volume  data,  for  instance.   An  arbitrary
       separable space-invariant resampling filter can be specified via a lookup table containing
       filter weights.  The input array may have an arbitrary number of dimensions, but  on  each
       call  to vpResample only one dimension of the array is resampled.  To scale all dimensions
       call the routine once  for  each  dimension.   Transformations  other  than  scales  (e.g.
       rotations and shears) are not supported by these routines.

       The routines vpResample2D and vpResample3D provide a simpler (but less flexible) interface
       to vpResample.  They take as arguments an input array with its dimensions, an output array
       with  its  dimensions,  and  a constant specifying a filter.  The input array is resampled
       once for each dimension  and  then  stored  in  the  output  array.   These  two  routines
       automatically create a filter weight table and arrays for temporary results.

       The remainder of this man page describe vpResample.  The vpc argument is a VolPack context
       that contains a description of the resampling  filter.   Use  vpSetFilter  to  define  the
       filter.   The volume data and rendering parameters currently stored in the context are not
       affected by calls to vpResample.

       The remaining arguments to vpResample describe the size and layout of the input and output
       arrays.   The two arrays must have the same number of dimensions, specified by num_dimens.
       The sizes of the dimensions are specified by src_dimens and dst_dimens which are 1D arrays
       with  num_dimens elements in each array.  src_dimens[0] is the size of the input dimension
       to be resampled.  dst_dimens[0] is the size of the output dimension after  resampling,  so
       the  scale  factor is dst_dimens[0] / src_dimens[0].  The remaining elements of src_dimens
       give the sizes of the other input array dimensions in any order (although  some  orderings
       result  in  faster  execution  due  to  lower  memory  overhead).   The other output array
       dimensions are ignored (although they should be the same as the corresponding input  array
       dimensions since only one dimensions is resampled).

       The  src_strides and dst_stride arguments are 1D arrays that contain a stride in bytes for
       each dimension of the input and output arrays, stored in the same order as the  dimensions
       sizes in src_dimens.

       The  element_type argument specifies the data type of each element of the input and output
       data arrays.  The supported types are:

       VP_UCHAR
              Unsigned character (1 byte per element).

       VP_USHORT
              Unsigned short (2 bytes per element).

       VP_FLOAT
              Single-precision floating point (4 bytes per element).

       Finally, the last two arguments to vpResample are pointers to the first  elements  of  the
       input and output arrays.

ERRORS

       The normal return value is VP_OK.  The following error return values are possible:

       VPERROR_BAD_SIZE
              No filter weight table has been specified.

SEE ALSO

       VolPack(3), vpSetFilter(3)