NAME

VistaIOCombineBands, VistaIOCombineBandsVa - copy a series of image bands

SYNOPSIS

#include <vistaio.h>

VistaIOImage VistaIOCombineBands (nels, src_images, src_bands, dest)

int nels;
VistaIOImage src_images[], dest;
VistaIOBand src_bands[];

VistaIOImage VistaIOCombineBandsVa (dest, src_image1, src_band1, ..., NULL)

VistaIOImage dest, src_image1;
VistaIOBand src_band1;

ARGUMENTS

nels

Specifies the number of elements in the src_images and src_bands arrays.

src_images

Specifies an array of images containing the bands to be copied (i.e., the source images).

src_bands

Specifies an array identifying the bands to be copied. Each element may specify a particular band of the corresponding source image, or it may be the constant VistaIOAllBands to indicate that all bands of the corresponding source image should be copied.

dest

May specify an image to copy to (i.e., the destination image), or may be NULL to indicate that a new destination image should be created.

src_image1

Specifies the first image containing a band or bands to be copied (i.e., the first source image).

src_band1

May specify a particular band of src_image1 to be copied, or it may be the constant VistaIOAllBands to indicate that all bands of src_image1 should be copied.

DESCRIPTION

VistaIOCombineBands copies bands of pixel values from various source images to a destination image. The source images are listed in the array src_images, and the band(s) to be copied from each is listed in the array src_bands. Both arrays must have nels elements. A src_bands element may be VistaIOAllBands, indicating that all bands of the corresponding source image are to be copied, or it may be a particular band number, indicating that only that band of the corresponding source image is to be copied.

VistaIOCombineBandsVa is similar except that the source images and band numbers are specified by a variable-length argument list. The argument list contains one or more pairs of the form src_image1, src_band1, and it is terminated by the value NULL

All source images must have have the same pixel representation, number of rows, and number of columns.

If dest is NULL, a destination image is created with the same pixel representation, number of rows, and number of columns as the source images. The image is created with a number of bands equal to the total number of bands to be copied.

Otherwise dest specifies an image to which pixel values are to be copied. It must have the same pixel representation, number of rows, and number of columns as the source image, and it must have a number of bands equal to the total number bands to be copied.

Source image bands, taken in the sequence specified, are copied to consecutive destination image bands.

RETURN VALUES

Both routines return the destination image if they are successful and NULL otherwise.

SEE ALSO

VistaIOCopyBand(3), VistaIOCopyImage(3), VistaIOImage(3),

NOTES

No attributes are copied from any source images to the destination image.

DIAGNOSTICS

``Band band referenced in image of nbands band(s).''

Band band is to be copied from a source image having nbands bands. However band is outside of the range [0, nbands - 1].

``Destination image has dest_nbands bands; src_nbands expected.''

A destination image was specified but it has the wrong number of bands.

``Destination image has dest_prop property; src_prop expected.''

Property is one of ``pixels'', ``rows'', or ``columns''. A destination image was specified but it does not have the same pixel representation, number of rows, and number of columns as the source images.

AUTHOR

Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>