ST_AddBand
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.
This example adds another 8-bit unsigned integer band 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.
Output metadata for the raster bands to verify they are correct.
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[]
)
);
SELECT (bmd).*
FROM (SELECT ST_BandMetaData(rast, generate_series(1, 2)) As bmd
FROM dummy_rast WHERE rid = 10) AS foo;
pixeltype | nodatavalue | isoutdb | path -----------+----------------+-------------+---------+------ 1BB | | f | 4BUI | | f |
This example outputs metadata for the raster.
SELECT (rmd).width, (rmd).height, (rmd).numbands
FROM (SELECT ST_MetaData(rast) As rmd
FROM dummy_rast WHERE rid = 10) AS foo;
width | height | numbands -------+--------+---------- 100 | 100 | 2
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 | outdbbandnum | filesize | filetimestamp
---------+-----------+-------------+---------+------+--------------+----------+---------------
1 | 8BUI | 0 | f | null | null | null | null
2 | 32BF | -1 | f | null | null | null | null
3 | 32BUI | 12 | f | null | null | null | null
4 | 16BUI | 2 | f | null | null | null | null
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 that The ORDER BY test_type clause relies on aggregate ORDER BY support. 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;
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