From 5ed584de8b7e67a03b8275b97b5440a635ed1b58 Mon Sep 17 00:00:00 2001 From: Regina Obe Date: Sat, 12 Nov 2011 04:27:51 +0000 Subject: [PATCH] add examples and fix arg list git-svn-id: http://svn.osgeo.org/postgis/trunk@8144 b70326c6-7e19-0410-871a-916f4a2858ee --- doc/html/images/st_mapalgebrafct2_01.png | Bin 0 -> 1433 bytes doc/html/images/st_mapalgebrafct2_02.png | Bin 0 -> 5276 bytes doc/reference_raster.xml | 149 ++++++++++++++++++++--- 3 files changed, 132 insertions(+), 17 deletions(-) create mode 100644 doc/html/images/st_mapalgebrafct2_01.png create mode 100644 doc/html/images/st_mapalgebrafct2_02.png diff --git a/doc/html/images/st_mapalgebrafct2_01.png b/doc/html/images/st_mapalgebrafct2_01.png new file mode 100644 index 0000000000000000000000000000000000000000..f22bec8e7b823c1e59008b3007203f3700b00834 GIT binary patch literal 1433 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 x@%M}iX ST_MapAlgebraFct - 2 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the 2 input raster bands and of pixeltype prodived. Band 1 is assumed if no band is specified. + 2 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the 2 input raster bands and of pixeltype prodived. Band 1 is assumed if no band is specified. Extent type defaults to INTERSECTION if not specified @@ -5753,9 +5753,22 @@ WHERE rid=167; raster rast1 raster rast2 regprocedure userfunction + text pixeltype=same_as_rast1 + text extenttype=INTERSECTION text[] VARIADIC userargs + + raster ST_MapAlgebraFct + raster rast1 + integer band1 + raster rast2 + integer band2 + regprocedure userfunction + text pixeltype=same_as_rast1 + text extenttype=INTERSECTION + text[] VARIADIC userargs + @@ -5767,7 +5780,24 @@ WHERE rid=167; If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL or left out, then the new raster band will have the same pixeltype as the input rast1 band. The userfunction parameter must be the name and signature of an SQL or PL/pgSQL function, cast to a regprocedure. An example PL/pgSQL function example is: - CREATE OR REPLACE FUNCTION raster_mapalgebra_union( + The userfunction is required to accept three arguments: a double precision value, a double precision value and a variadic text array. The first argument is the value of an individual raster cell in rast1 (regardless of the raster datatype), the second argument is an individual raster cell value in rast2, and the third argument indicates that all remaining parameters to shall be passed through to the userfunction. + + Passing a regprodedure argument to a SQL function requires the full function signature to be passed, then cast to a regprocedure type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:'simple_function(double precision,double precision, text[])'::regprocedureNote that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a regprocedure. + + The third argument to the userfunction is a variadic text array. All trailing text arguments to any call are passed through to the specified userfunction, and are contained in the userargs argument. + + For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of Query Language (SQL) Functions. + + The text[] argument to the userfunction is required, regardless of whether you choose to pass any arguments to your user function for processing or not. + + Availability: 2.0.0 + + + + Example: Overlaying rasters on a canvas as separate bands + +-- define our user defined function -- +CREATE OR REPLACE FUNCTION raster_mapalgebra_union( rast1 double precision, rast2 double precision, VARIADIC userargs text[] @@ -5789,25 +5819,110 @@ WHERE rid=167; RETURN NULL; END; - $$ LANGUAGE 'plpgsql'; - The userfunction is required to accept three arguments: a double precision value, a double precision value and a variadic text array. The first argument is the value of an individual raster cell in rast1 (regardless of the raster datatype), the second argument is an individual raster cell value in rast2, and the third argument indicates that all remaining parameters to shall be passed through to the userfunction. - - Passing a regprodedure argument to a SQL function requires the full function signature to be passed, then cast to a regprocedure type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:'simple_function(double precision,double precision, text[])'::regprocedureNote that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a regprocedure. - - The third argument to the userfunction is a variadic text array. All trailing text arguments to any call are passed through to the specified userfunction, and are contained in the userargs argument. + $$ LANGUAGE 'plpgsql' IMMUTABLE COST 1000; - For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of Query Language (SQL) Functions. - - The text[] argument to the userfunction is required, regardless of whether you choose to pass any arguments to your user function for processing or not. +-- prep our test table of rasters +DROP TABLE IF EXISTS map_shapes; +CREATE TABLE map_shapes(rid serial PRIMARY KEY, rast raster, bnum integer, descrip text); +INSERT INTO map_shapes(rast,bnum, descrip) +WITH mygeoms + AS ( SELECT 2 As bnum, ST_Buffer(ST_Point(90,90),30) As geom, 'circle' As descrip + UNION ALL + SELECT 3 AS bnum, + ST_Buffer(ST_GeomFromText('LINESTRING(50 50,150 150,150 50)'), 15) As geom, 'big road' As descrip + UNION ALL + SELECT 1 As bnum, + ST_Translate(ST_Buffer(ST_GeomFromText('LINESTRING(60 50,150 150,150 50)'), 8,'join=bevel'), 10,-6) As geom, 'small road' As descrip + ), + -- define our canvas to be 1 to 1 pixel to geometry + canvas + AS ( SELECT ST_AddBand(ST_MakeEmptyRaster(250, + 250, + ST_XMin(e)::integer, ST_YMax(e)::integer, 1,-1, 0, 0 ) , '8BUI'::text,0) As rast + FROM (SELECT ST_Extent(geom) As e, + Max(ST_SRID(geom)) As srid + from mygeoms + ) As foo + ) +-- return our rasters aligned with our canvas +SELECT ST_AsRaster(m.geom, canvas.rast, '8BUI', 240) As rast, bnum, descrip + FROM mygeoms AS m CROSS JOIN canvas +UNION ALL +SELECT canvas.rast, 4, 'canvas' +FROM canvas; + +-- Map algebra on single band rasters and then collect with ST_AddBand +INSERT INTO map_shapes(rast,bnum,descrip) +SELECT ST_AddBand(ST_AddBand(rasts[1], rasts[2]),rasts[3]), 4, 'map bands overlay fct union (canvas)' + FROM (SELECT ARRAY(SELECT ST_MapAlgebraFct(m1.rast, m2.rast, + 'raster_mapalgebra_union(double precision,double precision, text[])'::regprocedure, '8BUI', 'FIRST') + FROM map_shapes As m1 CROSS JOIN map_shapes As m2 + WHERE m1.descrip = 'canvas' AND m2.descrip <> 'canvas' ORDER BY m2.bnum) As rasts) As foo; + + + + + + + + + + + + + map bands overlay (canvas) (R: small raod, G: circle, B: big road) + + + + + + + + + + User Defined function that takes extra args + +CREATE OR REPLACE FUNCTION raster_mapalgebra_userargs( + rast1 double precision, + rast2 double precision, + VARIADIC userargs text[] +) + RETURNS double precision + AS $$ + DECLARE + BEGIN + CASE + WHEN rast1 IS NOT NULL AND rast2 IS NOT NULL THEN + RETURN least(userargs[1]::integer,(rast1 + rast2)/2.); + WHEN rast1 IS NULL AND rast2 IS NULL THEN + RETURN userargs[2]::integer; + WHEN rast1 IS NULL THEN + RETURN greatest(rast2,random()*userargs[3]::integer)::integer; + ELSE + RETURN greatest(rast1, random()*userargs[4]::integer)::integer; + END CASE; - Availability: 2.0.0 + RETURN NULL; + END; + $$ LANGUAGE 'plpgsql' VOLATILE COST 1000; + +SELECT ST_MapAlgebraFct(m1.rast, 1, m1.rast,3 , + 'raster_mapalgebra_userargs(double precision,double precision, text[])'::regprocedure, + '8BUI', 'INTERSECT', '100','200','200','0') + FROM map_shapes As m1 + WHERE m1.descrip = 'map bands overlay fct union (canvas)'; + + + + + + + user defined with extra args and different bands from same raster + + + - - Examples - - Coming soon - See Also -- 2.40.0