---
name: "im_extract_band"
section: "3"
platform: "linux"
package: "libvips10-dev"
version: "7.10.21-1"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/im_extract"
---

# im\_extract\_band(3)

extract a portion of an image

Part of [im\_extract(3)](/im_extract/3.md).

## NAME

im\_extract, im\_extract\_band, im\_extract\_bands, im\_etract\_area - extract a portion of an image

## SYNOPSIS

**#include \<vips/vips.h\>**

int im\_extract(in, out, pbox)\
 IMAGE \*in, \*out;\
 IMAGE\_BOX \*pbox;

int im\_extract\_band(in, out, band)\
 IMAGE \*in, \*out;\
 int band;

int im\_extract\_bands(in, out, band, nbands)\
 IMAGE \*in, \*out;\
 int band;\
 int nbands;

int im\_extract\_area(in, out, x, y, w, h)\
 IMAGE \*in, \*out;\
 int x, y, w, h;

## DESCRIPTION

**[im\_extract(3)](/im_extract/3.md)** extracts a portion of the image pointed by in and writes the result to out. pbox specifies the size and position of the area to be extracted and is defined as

  /\* Used to define a region of interest for \
    \* im\_extract() etc.\
    \*/\
   typedef struct { \
     int xstart;\
     int ystart;\
     int xsize;\
     int ysize;\
     int chsel;   \
   } IMAGE\_BOX;

see \<vips/vips.h\>. if pbox-\>chsel is set to -1, all bands  are extracted; otherwise pbox-\>chsel gives the band to extract, numbering from zero. The area specified by pbox must lie entirely within the image.

Works for any size image, any number of bands, any type. Works for LABPACK coded images too! But disallows band extraction in this case.

If used as part of a pipeline of partial image operations, im\_extract() magically vanishes if chsel is -1. See the VIPS IO System Guide.

**[im\_extract\_area(3)](/im_extract_area/3.md)** is a convenience function which extracts an area from an image, leaving the bands the same.

**[im\_extract\_bands(3)](/im_extract_bands/3.md)** takes  **nbands** out of an image, starting from band **band.** So, for example, nbands == 2, bands == 1 will form a two band image from an RGB image, where the two bands are the G and the B bands.

**[im\_extract\_band(3)](/im_extract_band/3.md)** is a convenience function which extracts a single band from an image.

## RETURN VALUE

The function returns 0 on success and -1 on error.

## SEE ALSO

[im\_insert(3)](/im_insert/3.md), [im\_lrjoin(3)](/im_lrjoin/3.md), [im\_lrmerge(3)](/im_lrmerge/3.md), [im\_stats(3)](/im_stats/3.md), [im\_region\_region(3)](/im_region_region/3.md).

## COPYRIGHT

J. Cupitt,

## AUTHOR

J. Cupitt - 11/04/1990