begin documentation of 2 band ST_MapAlgebraFct -- waiting for dustymugs to fix signat...

git-svn-id: http://svn.osgeo.org/postgis/trunk@8142 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml
index b626a4971f9b3458d9373963ea0a8c9723f40a64..b03d4a0e51d13f7e1bbc58e5c90f345f00fbee16 100644 (file)
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -5515,7 +5515,7 @@ WITH mygeoms
                <refentry id="RT_ST_MapAlgebraFct">
                        <refnamediv>
                                <refname>ST_MapAlgebraFct</refname>
-                               <refpurpose>Creates a new one band raster formed by applying a valid PostgreSQL function on the input raster band and of pixeltype prodived. Band 1 is assumed if no band is specified.</refpurpose>
+                               <refpurpose>1 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the input raster band and of pixeltype prodived. Band 1 is assumed if no band is specified.</refpurpose>
                        </refnamediv>
 
                        <refsynopsisdiv>
@@ -5740,6 +5740,81 @@ WHERE rid=167;
                        </refsection>
                </refentry>
                
+               <refentry id="RT_ST_MapAlgebraFct2">
+                       <refnamediv>
+                               <refname>ST_MapAlgebraFct</refname>
+                               <refpurpose>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.</refpurpose>
+                       </refnamediv>
+
+                       <refsynopsisdiv>
+                               <funcsynopsis>
+                                       <funcprototype>
+                                               <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+                                               <paramdef><type>raster</type> <parameter>rast1</parameter></paramdef>
+                                               <paramdef><type>raster</type> <parameter>rast2</parameter></paramdef>
+                                               <paramdef><type>regprocedure</type> <parameter>userfunction</parameter></paramdef>
+                                               <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+                                       </funcprototype>                                
+                               
+                               </funcsynopsis>
+                       </refsynopsisdiv>
+
+                       <refsection>
+                               <title>Description</title>
+                               
+                               <para>Creates a new one band raster formed by applying a valid PostgreSQL function specified by the <varname>userfunction</varname> on the input raster <varname>rast1</varname>,<varname>rast2</varname> . If no <varname>band1</varname> or <varname>band2</varname> is specified, band 1 is assumed. The new raster will have the same georeference, width, and height as the original rasters but will only have one band.</para>
+
+                               <para>If <varname>pixeltype</varname> 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 <varname>rast1</varname> band.</para>
+
+                <para>The <varname>userfunction</varname> 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:
+                <programlisting>CREATE OR REPLACE FUNCTION raster_mapalgebra_union(
+       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 ((rast1 + rast2)/2.);
+                       WHEN rast1 IS NULL AND rast2 IS NULL THEN
+                               RETURN NULL;
+                       WHEN rast1 IS NULL THEN
+                               RETURN rast2;
+                       ELSE
+                               RETURN rast1;
+               END CASE;
+
+               RETURN NULL;
+       END;
+       $$ LANGUAGE 'plpgsql';</programlisting>
+                The <varname>userfunction</varname> 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 <varname>rast1</varname> (regardless of the raster datatype), the second argument is an individual raster cell value in <varname>rast2</varname>, and the third argument indicates that all remaining parameters to <xref linkend="RT_ST_MapAlgebraFct2" /> shall be passed through to the <varname>userfunction</varname>.</para>
+
+                <para>Passing a <type>regprodedure</type> argument to a SQL function requires the full function signature to be passed, then cast to a <type>regprocedure</type> type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:<programlisting>'simple_function(double precision,double precision, text[])'::regprocedure</programlisting>Note 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 <type>regprocedure</type>.</para>
+
+                <para>The third argument to the <varname>userfunction</varname> is a <type>variadic text</type> array. All trailing text arguments to any <xref linkend="RT_ST_MapAlgebraFct2" /> call are passed through to the specified <varname>userfunction</varname>, and are contained in the <varname>userargs</varname> argument.</para>
+
+                <note><para>For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of <ulink url="http://www.postgresql.org/docs/current/interactive/xfunc-sql.html">Query Language (SQL) Functions</ulink>.</para></note>
+
+                <note><para>The <type>text[]</type> argument to the <varname>userfunction</varname> is required, regardless of whether you choose to pass any arguments to your user function for processing or not.</para></note>
+
+                               <para>Availability: 2.0.0</para>
+                       </refsection>
+
+                       <refsection>
+                               <title>Examples</title>
+
+                               <para>Coming soon <!-- TODO: Add examples --></para>
+                       </refsection>
+
+                       <refsection>
+                               <title>See Also</title>
+                               <para><xref linkend="RT_ST_MapAlgebraExpr2" />, <xref linkend="RT_ST_BandPixelType" />, <xref linkend="RT_ST_GeoReference" />, <xref linkend="RT_ST_SetValue" /></para>
+                       </refsection>
+               </refentry>
+               
                <refentry id="RT_ST_Polygon">
                  <refnamediv>
                        <refname>ST_Polygon</refname>