From 653bde1da36cbc5a1a40122057354e7b2cdf0c6c Mon Sep 17 00:00:00 2001 From: Bborie Park Date: Tue, 16 Oct 2012 19:55:56 +0000 Subject: [PATCH] Added news blurb and docs regarding expression variants of ST_MapAlgebra. git-svn-id: http://svn.osgeo.org/postgis/trunk@10442 b70326c6-7e19-0410-871a-916f4a2858ee --- NEWS | 2 + doc/reference_raster.xml | 271 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 271 insertions(+), 2 deletions(-) diff --git a/NEWS b/NEWS index b0d9a0d62..539f227d7 100644 --- a/NEWS +++ b/NEWS @@ -12,6 +12,8 @@ PostGIS 2.1.0 - ST_Estimated_Extent renamed to ST_EstimatedExtent - ST_MapAlgebraFctNgb and 1 and 2 raster variants of ST_MapAlgebraFct. Use ST_MapAlgebra instead + - 1 and 2 raster variants of ST_MapAlgebraExpr. + Use expression variants of ST_MapAlgebra instead * New Features * diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml index af637b519..f756b8e55 100644 --- a/doc/reference_raster.xml +++ b/doc/reference_raster.xml @@ -7539,7 +7539,7 @@ WHERE A.rid =2 ) As foo; ST_MapAlgebra - Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function. + Callback function version - Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function. @@ -7860,10 +7860,265 @@ WHERE t1.rid = 1 , - + , + + + + + + + + + ST_MapAlgebra + + Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions. + + + + + + + + raster ST_MapAlgebra + raster rast + integer nband + text pixeltype + text expression + double precision nodataval=NULL + + + + raster ST_MapAlgebra + raster rast + text pixeltype + text expression + double precision nodataval=NULL + + + + raster ST_MapAlgebra + raster rast1 + integer nband1 + raster rast2 + integer nband2 + text expression + text pixeltype=NULL + text extenttype=INTERSECTION + text nodata1expr=NULL + text nodata2expr=NULL + double precision nodatanodataval=NULL + + + + raster ST_MapAlgebra + raster rast1 + raster rast2 + text expression + text pixeltype=NULL + text extenttype=INTERSECTION + text nodata1expr=NULL + text nodata2expr=NULL + double precision nodatanodataval=NULL + + + + + + + Description: Variants 1 and 2 (one raster) + + + Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the expression on the input raster (rast). If nband is not provided, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band. + + + + If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input rast band. + + + + Keywords permitted for expression + + + [rast] - Pixel value of the pixel of interest + + + [rast.val] - Pixel value of the pixel of interest + + + [rast.x] - 1-based pixel column of the pixel of interest + + + [rast.y] - 1-based pixel row of the pixel of interest + + + + + + + + + Description: Variants 3 and 4 (two raster) + + + Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the expression on the two input raster bands rast1, (rast2). If no band1, band2 is specified band 1 is assumed. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the extenttype parameter. + + + + + expression + + + A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer + + + + + pixeltype + + + The resulting pixel type of the output raster. Must be one listed in , left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster. + + + + + extenttype + + + Controls the extent of resulting raster + + + + + + INTERSECTION - The extent of the new raster is the intersection of the two rasters. This is the default. + + + + + UNION - The extent of the new raster is the union of the two rasters. + + + + + FIRST - The extent of the new raster is the same as the one of the first raster. + + + + + SECOND - The extent of the new raster is the same as the one of the second raster. + + + + + + + nodata1expr + + + An algebraic expression involving only rast2 or a constant that defines what to return when pixels of rast1 are nodata values and spatially corresponding rast2 pixels have values. + + + + + nodata2expr + + + An algebraic expression involving only rast1 or a constant that defines what to return when pixels of rast2 are nodata values and spatially corresponding rast1 pixels have values. + + + + + nodatanodataval + + + A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values. + + + + + + + Keywords permitted in expression, nodata1expr and nodata2expr + + + [rast1] - Pixel value of the pixel of interest from rast1 + + + [rast1.val] - Pixel value of the pixel of interest from rast1 + + + [rast1.x] - 1-based pixel column of the pixel of interest from rast1 + + + [rast1.y] - 1-based pixel row of the pixel of interest from rast1 + + + [rast2] - Pixel value of the pixel of interest from rast2 + + + [rast2.val] - Pixel value of the pixel of interest from rast2 + + + [rast2.x] - 1-based pixel column of the pixel of interest from rast2 + + + [rast2.y] - 1-based pixel row of the pixel of interest from rast2 + + + + + + Availability: 2.1.0 + + + + Examples: Variants 1 and 2 + + +WITH foo AS ( + SELECT ST_AddBand(ST_MakeEmptyRaster(10, 10, 0, 0, 1, 1, 0, 0, 0), '32BF', 1, -1) AS rast +) +SELECT + ST_MapAlgebra(rast, 1, NULL, 'ceil([rast]*[rast.x]/[rast.y]+[rast.val])') +FROM foo + + + + + + Examples: Variant 3 and 4 + + +WITH foo AS ( + SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast UNION ALL + SELECT 2 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 1, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0), 2, '8BUI', 20, 0), 3, '32BUI', 300, 0) AS rast +) +SELECT + ST_MapAlgebra( + t1.rast, 2, + t2.rast, 1, + '([rast2] + [rast1.val]) / 2' + ) AS rast +FROM foo t1 +CROSS JOIN foo t2 +WHERE t1.rid = 1 + AND t2.rid = 2 + + + + + + See Also + + + , + , + + + @@ -7896,6 +8151,12 @@ WHERE t1.rid = 1 Description + + + + is deprecated as of 2.1.0. Use instead. + + Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the expression on the input raster (rast). If no band is specified band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band. @@ -8045,6 +8306,12 @@ WHERE rid=167; Description + + + + is deprecated as of 2.1.0. Use instead. + + Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the expression on the two input raster bands rast1, (rast2). If no band1, band2 is specified band 1 is assumed. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the extenttype parameter. -- 2.40.0