---
name: "VistaIOCombineBands"
section: "3"
platform: "linux"
package: "libvistaio-dev"
version: "1.2.19-3+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/VistaIOCombineBands"
---

# VistaIOCombineBands(3)

copy a series of image bands

## 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)](/VistaIOCopyBand/3.md), [**VistaIOCopyImage**(3)](/VistaIOCopyImage/3.md), [**VistaIOImage**(3)](/VistaIOImage/3.md),

## 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\>**