From: Regina Obe <lr@pcorp.us>
Date: Mon, 5 Oct 2015 22:47:39 +0000 (+0000)
Subject: update explanation of what mask and weight do.
X-Git-Tag: 2.2.0~13
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=70f5b9a3886ee37ff422414fbdfded2cc86a2c42;p=postgis

update explanation of what mask and weight do.

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

diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml
index d102126e8..5c248f638 100644
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -9253,7 +9253,7 @@ CREATE OR REPLACE FUNCTION sample_callbackfunc(value double precision[][][], pos
 							<term>mask</term>
 							<listitem>
 								<para>
-									An n-dimenional array (matrix) of numbers used to set pixels in raster to nodata.
+									An n-dimenional array (matrix) of numbers used to filter what cells get passed to map algebra call-back function. 0 means a neighbor cell value should be treated as no-data and 1 means value should be treated as data.  If weight is set to true, then the values, are used as multipliers to multiple the pixel value of that value in the neighborhood position.
 								</para>
 							</listitem>
 						</varlistentry>
@@ -9262,7 +9262,7 @@ CREATE OR REPLACE FUNCTION sample_callbackfunc(value double precision[][][], pos
 							<term>weighted</term>
 							<listitem>
 								<para>
-									boolean (true/false) to denote if a mask should be weighted or not (only applies to proto that takes a mask).
+									boolean (true/false) to denote if a mask value should be weighted (multiplied by original value) or not (only applies to proto that takes a mask).
 								</para>
 							</listitem>
 						</varlistentry>
@@ -9532,6 +9532,29 @@ WHERE t1.rid = 1
 					</programlisting>
 
 				</refsection>
+				
+				<refsection>
+					<title>Examples: Using Masks</title>
+
+					<para>Create our dummy table</para>
+					<programlisting>
+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,
+		'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
+	) AS rast
+FROM foo t1
+CROSS JOIN foo t2
+WHERE t1.rid = 1
+	AND t2.rid = 2
+					</programlisting>
+
+				</refsection>
 
 
 				<refsection>