ST_AddBand
Prev | 12.3. Raster Constructors | Next

## Name

ST_AddBand — Returns a raster with the new band(s) of given type added with given initial value in the given index location. If no index is specified, the band is added to the end.

## Synopsis

`(1) raster ST_AddBand(`raster rast, addbandarg[] addbandargset`)`;

`(2) raster ST_AddBand(`raster rast, integer index, text pixeltype, double precision initialvalue=0, double precision nodataval=NULL`)`;

`(3) raster ST_AddBand(`raster rast, text pixeltype, double precision initialvalue=0, double precision nodataval=NULL`)`;

`(4) raster ST_AddBand(`raster torast, raster fromrast, integer fromband=1, integer torastindex=at_end`)`;

`(5) raster ST_AddBand(`raster torast, raster[] fromrasts, integer fromband=1, integer torastindex=at_end`)`;

`(6) raster ST_AddBand(`raster rast, integer index, text outdbfile, integer[] outdbindex, double precision nodataval=NULL`)`;

`(7) raster ST_AddBand(`raster rast, text outdbfile, integer[] outdbindex, integer index=at_end, double precision nodataval=NULL`)`;

## Description

Returns a raster with a new band added in given position (index), of given type, of given initial value, and of given nodata value. If no index is specified, the band is added to the end. If no `fromband` is specified, band 1 is assumed. Pixel type is a string representation of one of the pixel types specified in ST_BandPixelType. If an existing index is specified all subsequent bands >= that index are incremented by 1. If an initial value greater than the max of the pixel type is specified, then the initial value is set to the highest value allowed by the pixel type.

For the variant that takes an array of addbandarg (Variant 1), a specific addbandarg's index value is relative to the raster at the time when the band described by that addbandarg is being added to the raster. See the Multiple New Bands example below.

For the variant that takes an array of rasters (Variant 5), if `torast` is NULL then the `fromband` band of each raster in the array is accumulated into a new raster.

For the variants that take `outdbfile` (Variants 6 and 7), the value must include the full path to the raster file. The file must also be accessible to the postgres server process.

Enhanced: 2.1.0 support for addbandarg added.

Enhanced: 2.1.0 support for new out-db bands added.

## Examples: Single New Band

    -- Add another band of type 8 bit unsigned integer with pixels initialized to 200
    UPDATE dummy_rast
        SET rast = ST_AddBand(rast,'8BUI'::text,200)
    WHERE rid = 1;

    -- Create an empty raster 100x100 units, with upper left  right at 0, add 2 bands (band 1 is 0/1 boolean bit switch, band2 allows values 0-15)
    -- uses addbandargs
    INSERT INTO dummy_rast(rid,rast)
        VALUES(10, ST_AddBand(ST_MakeEmptyRaster(100, 100, 0, 0, 1, -1, 0, 0, 0),
        ARRAY[
            ROW(1, '1BB'::text, 0, NULL),
            ROW(2, '4BUI'::text, 0, NULL)
                ]::addbandarg[]
         )
        );

    -- output meta data of raster bands to verify all is right --
    SELECT  (bmd).*
    FROM (SELECT ST_BandMetaData(rast,generate_series(1,2)) As bmd
        FROM dummy_rast WHERE rid = 10) AS foo;
     --result --
     pixeltype | nodatavalue | isoutdb | path
    -----------+----------------+-------------+---------+------
     1BB       |             | f       |
     4BUI      |             | f       |

    -- output meta data of raster -
    SELECT  (rmd).width, (rmd).height, (rmd).numbands
    FROM (SELECT ST_MetaData(rast) As rmd
        FROM dummy_rast WHERE rid = 10) AS foo;
    -- result --
     upperleftx | upperlefty | width | height | scalex | scaley | skewx | skewy | srid | numbands
    ------------+------------+-------+--------+------------+------------+-------+-------+------+----------
              0 |          0 |   100 |    100 |      1 |     -1 |     0 |     0 |   0 |        2

## Examples: Multiple New Bands

    SELECT
        *
    FROM ST_BandMetadata(
        ST_AddBand(
            ST_MakeEmptyRaster(10, 10, 0, 0, 1, -1, 0, 0, 0),
            ARRAY[
                ROW(NULL, '8BUI', 255, 0),
                ROW(NULL, '16BUI', 1, 2),
                ROW(2, '32BUI', 100, 12),
                ROW(2, '32BF', 3.14, -1)
            ]::addbandarg[]
        ),
        ARRAY[]::integer[]
    );

     bandnum | pixeltype | nodatavalue | isoutdb | path
    ---------+-----------+-------------+---------+------
           1 | 8BUI      |           0 | f       |
           2 | 32BF      |          -1 | f       |
           3 | 32BUI     |          12 | f       |
           4 | 16BUI     |           2 | f       |

    -- Aggregate the 1st band of a table of like rasters into a single raster
    -- with as many bands as there are test_types and as many rows (new rasters) as there are mice
    -- NOTE: The ORDER BY test_type is only supported in PostgreSQL 9.0+
    -- for 8.4 and below it usually works to order your data in a subselect (but not guaranteed)
    -- The resulting raster will have a band for each test_type alphabetical by test_type
    -- For mouse lovers: No mice were harmed in this exercise
    SELECT
        mouse,
        ST_AddBand(NULL, array_agg(rast ORDER BY test_type), 1) As rast
    FROM mice_studies
    GROUP BY mouse;

## Examples: New Out-db band

    SELECT
        *
    FROM ST_BandMetadata(
        ST_AddBand(
            ST_MakeEmptyRaster(10, 10, 0, 0, 1, -1, 0, 0, 0),
            '/home/raster/mytestraster.tif'::text, NULL::int[]
        ),
        ARRAY[]::integer[]
    );

     bandnum | pixeltype | nodatavalue | isoutdb | path
    ---------+-----------+-------------+---------+------
           1 | 8BUI      |             | t       | /home/raster/mytestraster.tif
           2 | 8BUI      |             | t       | /home/raster/mytestraster.tif
           3 | 8BUI      |             | t       | /home/raster/mytestraster.tif

## See Also

ST_BandMetaData, ST_BandPixelType, ST_MakeEmptyRaster, ST_MetaData, ST_NumBands, ST_Reclass

Prev | Up | Next
ST_CreateOverview | Home | ST_AsRaster