ST_Band
Prev | 12.3. Raster Constructors | Next

## Name

ST_Band — Returns one or more bands of an existing raster as a new raster. Useful for building new rasters from existing rasters.

## Synopsis

`raster ST_Band(`raster rast, integer[] nbands = ARRAY[1]`)`;

`raster ST_Band(`raster rast, integer nband`)`;

`raster ST_Band(`raster rast, text nbands, character delimiter=,`)`;

## Description

Returns one or more bands of an existing raster as a new raster. Useful for building new rasters from existing rasters or export of only selected bands of a raster or rearranging the order of bands in a raster. If no band is specified or any of specified bands does not exist in the raster, then all bands are returned. Used as a helper function in various functions such as for deleting a band.

For the `nbands` as text variant of function, the default delimiter is `,` which means you can ask for `'1,2,3'` and if you wanted to use a different delimeter you would do `ST_Band(rast, '1@2@3', '@')`. For asking for multiple bands, we strongly suggest you use the array form of this function e.g. `ST_Band(rast, '{1,2,3}'::int[]);` since the `text` list of bands form may be removed in future versions of PostGIS.

Availability: 2.0.0

## Examples

    -- Make 2 new rasters: 1 containing band 1 of dummy, second containing band 2 of dummy and then reclassified as a 2BUI
    SELECT ST_NumBands(rast1) As numb1, ST_BandPixelType(rast1) As pix1,
     ST_NumBands(rast2) As numb2,  ST_BandPixelType(rast2) As pix2
    FROM (
        SELECT ST_Band(rast) As rast1, ST_Reclass(ST_Band(rast,3), '100-200):1, [200-254:2', '2BUI') As rast2
            FROM dummy_rast
            WHERE rid = 2) As foo;

     numb1 | pix1 | numb2 | pix2
    -------+------+-------+------
         1 | 8BUI |     1 | 2BUI

    -- Return bands 2 and 3. Using array cast syntax
    SELECT ST_NumBands(ST_Band(rast, '{2,3}'::int[])) As num_bands
        FROM dummy_rast WHERE rid=2;

    num_bands
    ----------
    2

    -- Return bands 2 and 3. Use array to define bands
    SELECT ST_NumBands(ST_Band(rast, ARRAY[2,3])) As num_bands
        FROM dummy_rast
    WHERE rid=2;

original (column rast) | dupe_band | sing_band

    --Make a new raster with 2nd band of original and 1st band repeated twice,
    and another with just the third band
    SELECT rast, ST_Band(rast, ARRAY[2,1,1]) As dupe_band,
        ST_Band(rast, 3) As sing_band
    FROM samples.than_chunked
    WHERE rid=35;

## See Also

ST_AddBand, ST_NumBands, ST_Reclass, Chapter 12, Raster Reference

Prev | Up | Next
ST_AsRaster | Home | ST_MakeEmptyCoverage