[raster] Add docs for ST_MapAlgebra with mask parameter

[dustymugs]

Need to add docs for mask parameter containing variant of ST_MapAlgebra.

[robe]

dustymugs if you are around, I'm working on adding this to docs. I presume this is new in 2.2.0 (so flagging it as such). Can you explain what the mask does? From example in rt_mapalgebra_mast.sql — looks like the mask is a matrix of some sort which I am guessing only gets applied to the neighborhood of pixels to set pixels as nodata.

So I'm guessing it does similar to :

​http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=selectmask

(I apologize now for linking to competitor documentation )

If I don't hear back from you before Paul pulls the switch, I'll just document the protos and be very vague about what it does not to embarrass myself.

[dustymugs]

Thanks for the reminder. I'll take a look. Need to refresh my memory.

[robe]

I'm guessing it does similar to ST_Clip except instead of passing in a geometry you pass in a matrix?

Anway committed first attempt at r14178. I'm not sure what weighted arg does either. I'll try to come up with a visual example before Paul pulls the trigger.

[dustymugs]

I don't believe it does what that ESRI link does…

Instead, the mask is used to pull the neighborhood that you want for the pixel of interest…

[robe]

I guess I'll have a better idea once I do a visual picture example .

So what does the weighted param do? does it add the mask to the otherwise neighborhood? instead of just replacing it?

[robe]

dustymugs: seems you have hard-coded somewhere a neighborhood of 1 for mask as I can't input distance x and y. Yet I can't find where that is. So if I understand correctly, then the mask should always be a 3x3 matrix as it stands. I'm also not sure what you mean by pull the neighborhood.

[dustymugs]

Just looked through the code and I see no hard-coding of any neighborhood… I'll see about sending you an example…

[dustymugs]

Probably not the best example…

The idea is that instead of distancex and distancey, the mask (an odd numbered array in X and Y) can provide a means to selectively filter pixels.

In the example below, I provide a mask of

1 0 0
0 1 0
0 0 1

which drives the neighborhood fetch to only pass those pixels in the neighborhood where the mask element is 1 (true) to the MapAlgebra Callback function.

DROP FUNCTION sample_callbackfunc(double precision[],integer[],text[]);
CREATE OR REPLACE FUNCTION sample_callbackfunc(v double precision[][][], pos int[][], VARIADIC userargs text[])
RETURNS double precision
AS $$
BEGIN
	RAISE NOTICE 'v = %', v;
	RAISE NOTICE 'pos = %', pos;
	RAISE NOTICE 'userargs = %', userargs;
	RETURN v[1][1][1];
END;
$$ LANGUAGE 'plpgsql';

WITH foo AS (
	SELECT 1 AS rid, ST_AddBand(ST_MakeEmptyRaster(4, 4, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast
)
SELECT
	ST_DumpValues(
		ST_MapAlgebra(
			rast, 1, 
			'sample_callbackfunc(double precision[], int[], text[])'::regprocedure,
			ARRAY[[1, 0, 0],[0, 1, 0],[0, 0, 1]]::double precision[], False
		)
	)
FROM foo

[robe]

Ah okay I think I'm getting it now. I kept on thinking it was being applied after the mapalgebra call. So should the mask always be 0s and 1s? I'm not sure that behavior works right because when I gave it a 5x5 matrix it complained dimension was not the same as neighbor (that's why I augmented the error message to see what it thought was wrong). That's what I had thought that the distance was inferred from the matrix.

Here is an example:

DROP TABLE IF EXISTS shapes;
CREATE TABLE shapes(rid integer, rast raster);  

INSERT INTO shapes(rid,rast)
VALUES ( 1, ST_AsRaster(
		ST_Buffer(
			ST_GeomFromText('LINESTRING(50 50,150 150,150 50)'), 10,'join=bevel'), 
			200,200,ARRAY['8BUI'], ARRAY[118], ARRAY[0]) );

 SELECT st_mapalgebra(rast,1,'st_mean4ma(double precision[], int[], text[])'::regprocedure,'{{1,0,1,1,1}, {1,0,1,1,1}, {1,0,1,1,1}, {1,0,1,1,1}, {1,0,1,1,1}}'::double precision[],false)
FROM shapes;

Gives me:

ERROR:  rt_pixel_set_array: mask dimensions 5 x 5 do not match given dims 3 x 3

Why doesn't the distancex/y become 2,2?

[dustymugs]

Distance is two pixels left, right, up, down from the pixel of interest…

2 2 2 2 2
2 1 1 1 2
2 1 0 1 2
2 1 1 1 2
2 2 2 2 2

So the distance x/y are correct. As for that error message, I'll need to dig.

[robe]

I updated the doco at r14198. I'm still coming up with examples, but uncortable at the fact that my examples don't seem to display what I expect them to.

[robe]

put in pictures at r14199. done enough for release