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

# VistaIOCopyImage(3)

copy an image

## NAME

VistaIOCopyImage - copy an image

## SYNOPSIS

```
#include <vistaio.h>
```

**VistaIOImage VistaIOCopyImagePixels (*src*, *dest*, *band*)**

**VistaIOImage *src*, *dest*;** **VistaIOBand *band*;**

**VistaIOImage VistaIOCopyImageAttrs (*src*, *dest*)**

**VistaIOImage *src*, *dest*;**

**VistaIOImage VistaIOCopyImage (*src*, *dest*, *band*)**

**VistaIOImage *src*, *dest*;** **VistaIOBand *band*;**

## ARGUMENTS

- *src*

  Specifies the source image.

- *dest*

  May specify a destination image; or may be **NULL** to indicate that a new destination image should be created.

- *band*

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

## DESCRIPTION

**VistaIOCopyImagePixels** copies pixel values from the source image to the destination image. (No other image properties are copied.)

**VistaIOCopyImageAttrs** copies attributes from the source image to the  destination image. (No pixel values are copied.) If the destination image  already has an attribute list, it is first deleted. Then the destination  image is given a copy of the source image's attribute list. Finally, if the  source and destination images do not have the same number of bands then the  destination image's band interpretation attributes may be edited to ensure  their validity:

- •

  if they do not have the same number of bands then (a) any band  interpretation attributes, such as **frame\_interp** and  **color\_interp**, are deleted from the destination image's copy; (b) the  size of the destination image's component dimension (**ncomponents**) is  set equal to its number of bands; and (c) the sizes of its other band  interpretation dimensions (**nframes**, **nviewpoints**, and  **ncolors**) are set to 1.

- •

  if they have the same number of bands then (a) all attributes are copied unchanged from the source image to the destination image; and (b) the sizes of the band interpretation dimensions are copied as well.

**VistaIOCopyImage** copies both pixel values and attributes from one image to the other. It is equivalent to calling both **VistaIOCopyImagePixels** and **VistaIOCopyImageAttrs**.

You can specify  **NULL** as a destination image to any of these routines; they will then create an appropriate destination image, copy to it, and return it. If you supply a destination image to **VistaIOCopyImage** or **VistaIOCopyImagePixels**, it must have the same number of rows, number of columns, and pixel representation as the source image; also, it must have a number of bands consistent with *src* and *band*.

## RETURN VALUES

Each of these routines returns the destination image if it is successful and **NULL** otherwise.

## SEE ALSO

[**VistaIOCopyBand**(3)](/VistaIOCopyBand/3.md), [**VistaIOCombineBands**(3)](/VistaIOCombineBands/3.md) [**VistaIOImage**(3)](/VistaIOImage/3.md),

## NOTES

**VistaIOCopyAttrList**(3) is used to copy attributes from the source image  to the destination image. Thus the destination image's attribute list  contains its own copy of each attribute value — except that for a  **VistaIOPointer** value, the pointer is copied but not the (opaque) data  structure to which it points.

## DIAGNOSTICS

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

  The *band* argument is invalid given the number of bands in *src*.

- \`\`Destination image has *dest\_nbands* bands; *src\_nbands* expected.''

  A destination image was specified but it has the wrong number of bands. If *band* is **VistaIOAllBands**, the destination image must have the same number of bands as the source image. Otherwise, it must have a single band.

- \`\`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 image.

## AUTHOR

Art Pope \<pope@cs.ubc.ca\>

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