diff --git a/NEWS b/NEWS
index ec6adf80e..91b565b3a 100644
--- a/NEWS
+++ b/NEWS
@@ -24,11 +24,12 @@ PostGIS 2.1.0
* Enhancements *
- #823, tiger geocoder: Make loader_generate_script download portion less greedy
+ - #1661, Add aggregate variant of ST_SameAlignment
- #1719, Add support for Point and GeometryCollection ST_MakeValid inputs
- #1796, Big performance boost for distance calculations in geography
- #1802, improved function interruptibility.
- #1856, tiger geocoder: reverse geocoder rating setting for prefer numbered highway name
- - #1661, Add aggregate variant of ST_SameAlignment
+ - #1938, Refactor basic ST_AddBand to add multiple new bands in one call
* Fixes *
diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml
index d4c2022dc..d66ae5db5 100644
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -69,7 +69,79 @@ VALUES (1,
-
+
+
+
+ addbandarg
+ A composite type used as input into the ST_AddBand function defining the attributes and initial value of the new band.
+
+
+
+ Description
+
+ A composite type used as input into the ST_AddBand function defining the attributes and initial value of the new band.
+
+
+
+
+ index
+ integer
+
+
+
+ 1-based value indicating the position where the new band will be added amongst the raster's bands. If NULL, the new band will be added at the end of the raster's bands.
+
+
+
+
+
+
+ pixeltype
+ text
+
+
+
+ Pixel type of the new band. One of defined pixel types as described in .
+
+
+
+
+
+
+ initialvalue
+ double precision
+
+
+
+ Initial value that all pixels of new band will be set to.
+
+
+
+
+
+
+ nodataval
+ double precision
+
+
+
+ NODATA value of the new band. If NULL, the new band will not have a NODATA value assigned.
+
+
+
+
+
+
+
+
+
+ See Also
+
+
+
+
+
+
histogram
@@ -880,75 +952,94 @@ WHERE short_name = 'GTiff') As g;
-
- Raster Constructors
-
+
+ Raster Constructors
+
+
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.
+
+ 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.
+
-
+
-
- raster ST_AddBand
- raster rast
- text pixeltype
- double precision initialvalue=0
- double precision nodataval=NULL
-
-
-
- raster ST_AddBand
- raster rast
- integer index
- text pixeltype
- double precision initialvalue=0
- double precision nodataval=NULL
-
-
-
- raster ST_AddBand
- raster torast
- raster fromrast
- integer fromband=1
- integer torastindex=at_end
-
-
-
- raster ST_AddBand
- raster torast
- raster[] fromrasts
- integer fromband=1
-
+
+
+ raster ST_AddBand
+
+ raster rast
+ addbandarg[] addbandargset
+
+
+
+ raster ST_AddBand
+
+ raster rast
+ text pixeltype
+ double precision initialvalue=0
+ double precision nodataval=NULL
+
+
+
+ raster ST_AddBand
+
+ raster rast
+ integer index
+ text pixeltype
+ double precision initialvalue=0
+ double precision nodataval=NULL
+
+
+
+ raster ST_AddBand
+
+ raster torast
+ raster fromrast
+ integer fromband=1
+ integer torastindex=at_end
+
+
+
+ raster ST_AddBand
+
+ raster torast
+ raster[] fromrasts
+ integer fromband=1
+
-
+
- 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 . 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. The last version add the
- fromband from fromrast raster to torast in position torastindex.
- For the version that takes an array of bands if torast is NULL, then the fromband band of each raster in the array
- is accumulated into a new raster
-
-
-
- Examples: Single Add Band versions
-
- -- Add another band of type 8 bit unsigned integer with pixels initialized to 200
+ 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 . 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. The last version add the fromband from fromrast raster to torast in position torastindex.
+
+
+
+ For the version that takes an array of , 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 version that takes an array of bands if torast is NULL, then the fromband band of each raster in the array is accumulated into a new raster.
+
+
+
+
+ Examples: Single New Band versions
+
+
+-- 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)
+
+
+
+-- 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)
INSERT INTO dummy_rast(rid,rast)
VALUES(10, ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(100, 100, 0, 0, 1, -1, 0, 0, 0), '1BB'::text), '4BUI'::text) );
@@ -971,14 +1062,42 @@ FROM (SELECT ST_MetaData(rast) As rmd
upperleftx | upperlefty | width | height | scalex | scaley | skewx | skewy | srid | numbands
------------+------------+-------+--------+------------+------------+-------+-------+------+----------
0 | 0 | 100 | 100 | 1 | -1 | 0 | 0 | 0 | 2
-
-
+
-
+
- Examples: Multi-Band versions
-
- -- Aggregate the 1st band of a table of like rasters into a single raster
+ 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 |
+
+
+
+
+ Examples: Multi-Band versions
+
+
+-- 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)
@@ -986,16 +1105,23 @@ FROM (SELECT ST_MetaData(rast) As rmd
-- 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;
-
-
+ GROUP BY mouse;
+
See Also
- , , , , ,
+
+ ,
+ ,
+ ,
+ ,
+ ,
+
+
+
ST_AsRaster