provide an example of map algebra

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

diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml
index 6eeb357c0781b5b686046f9f1cb23cfff415a04b..773af74487d45ded4e2b785f949015c193e9e99f 100644 (file)
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -3295,7 +3295,7 @@ WHERE A.rid =2 ) As foo;
                <refentry id="RT_ST_MapAlgebra">
                        <refnamediv>
                                <refname>ST_MapAlgebra</refname>
-                               <refpurpose>Creates a new raster formed by applying algebraic operations defined by the expression on the input raster and of pixeeltype provided.  band 1 is assumed if no band is specified.</refpurpose>
+                               <refpurpose>Creates a new one band raster formed by applying a valid PostgreSQL algebraic operations on the input raster band and of pixeeltype provided.  band 1 is assumed if no band is specified.</refpurpose>
                        </refnamediv>
                
                        <refsynopsisdiv>
@@ -3345,8 +3345,11 @@ WHERE A.rid =2 ) As foo;
                        <refsection>
                                <title>Description</title>
                                
-                               <para>Creates a new raster formed by applying algebraic operations defined by the expression on the input raster. If no band number is specified
-        band 1 is assumed.</para>
+                               <para>Creates a new one band raster formed by applying algebraic operations defined by the <varname>expression</varname> on the input raster (<varname>rast</varname>). If no <varnum>band</varnum> 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.</para>
+        
+                 <para>If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype.  If no pixeltype is passed in, then the new raster band will have the same pixeltype as the input <varname>rast</varname></para>
+                 <para>Use the term <varname>rast</varname> to refer to the band you are changing.</para>
                        
                  <para>Availability: 2.0.0 </para>
              </refsection>
@@ -3354,12 +3357,31 @@ WHERE A.rid =2 ) As foo;
              <refsection>
                                <title>Examples</title>
                                
-                               <!-- TODO -->
+                               <para>Create a new 1 band raster from our original that is  a function of modulo 2 of the original raster band.</para>
+                               <programlisting>ALTER TABLE dummy_rast ADD COLUMN map_rast raster;
+UPDATE dummy_rast SET map_rast = ST_MapAlgebra(rast,'mod(rast,2)') WHERE rid = 2;
+
+SELECT ST_Value(rast,1,i,j) As origval, ST_Value(map_rast, 1, i, j) As mapval
+FROM dummy_rast CROSS JOIN generate_series(1, 3) AS i CROSS JOIN generate_series(1,3) AS j
+WHERE rid = 2;
+
+ origval | mapval
+---------+--------
+     253 |      1
+     254 |      0
+     253 |      1
+     253 |      1
+     254 |      0
+     254 |      0
+     250 |      0
+     254 |      0
+     254 |      0
+                               </programlisting>                               
                        </refsection>
 
                        <refsection>
                                <title>See Also</title>
-                               <para></para>
+                               <para><xref linkend="RT_ST_GeoReference" />, <xref linkend="RT_ST_BandPixelType" /></para>
                        </refsection>
                </refentry>