From 59da4b7207fbd7ba8b3654517dfd8f28b8b3f84d Mon Sep 17 00:00:00 2001 From: Bborie Park Date: Tue, 14 May 2013 20:42:28 +0000 Subject: [PATCH] Fixed Raster Processing section git-svn-id: http://svn.osgeo.org/postgis/trunk@11463 b70326c6-7e19-0410-871a-916f4a2858ee --- doc/reference_raster.xml | 2885 +++++++++++++++++++------------------- 1 file changed, 1443 insertions(+), 1442 deletions(-) diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml index 8e21c2b37..b45d50321 100644 --- a/doc/reference_raster.xml +++ b/doc/reference_raster.xml @@ -10454,1717 +10454,1718 @@ WHERE ST_Intersects(rast, ST_GeomFromText('LINESTRING(230486 887771, 230500 887 - - DEM (Elevation) + + Built-in Map Algebra Callback Functions + + + + ST_Min4ma + + Raster processing function that calculates the minimum pixel value in a neighborhood. + + + + + + + float8 ST_Min4ma + float8[][] matrix + text nodatamode + text[] VARIADIC args + - - - ST_Aspect - Returns the aspect (in degrees by default) of an elevation raster band. Useful for analyzing terrain. - - - - - raster ST_Aspect - raster rast - integer band=1 - text pixeltype=32BF - text units=DEGREES - boolean interpolate_nodata=FALSE - + + double precision ST_Min4ma + double precision[][][] value + integer[][] pos + text[] VARIADIC userargs + + + - - raster ST_Aspect - raster rast - integer band - raster customextent - text pixeltype=32BF - text units=DEGREES - boolean interpolate_nodata=FALSE - - - - - - Description + + Description - Returns the aspect (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the aspect equation to neighboring pixels. + + Calculate the minimum pixel value in a neighborhood of pixels. + - - units indicates the units of the aspect. Possible values are: RADIANS, DEGREES (default). - + + For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. + + - When units = RADIANS, values are between 0 and 2 * pi radians measured clockwise from North. + Variant 1 is a specialized callback function for use as a callback parameter to . + + - When units = DEGREES, values are between 0 and 360 degrees measured clockwise from North. + Variant 2 is a specialized callback function for use as a callback parameter to . + + - If slope of pixel is zero, aspect of pixel is -1. + Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + - - - For more information about Slope, Aspect and Hillshade, please refer to ESRI - How hillshade works and ERDAS Field Guide - Aspect Images. - - + Availability: 2.0.0 + Enhanced: 2.1.0 Addition of Variant 2 + - Availability: 2.0.0 - Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional interpolate_nodata function parameter - Changed: 2.1.0 In prior versions, return values were in radians. Now, return values default to degrees - - - - Examples: Variant 1 - -WITH foo AS ( - SELECT ST_SetValues( - ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999), - 1, 1, 1, ARRAY[ - [1, 1, 1, 1, 1], - [1, 2, 2, 2, 1], - [1, 2, 3, 2, 1], - [1, 2, 2, 2, 1], - [1, 1, 1, 1, 1] - ]::double precision[][] - ) AS rast -) -SELECT - ST_DumpValues(ST_Aspect(rast, 1, '32BF')) -FROM foo + + Examples - st_dumpvalues - ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ----------------------------------- - (1,"{{315,341.565063476562,0,18.4349479675293,45},{288.434936523438,315,0,45,71.5650482177734},{270,270,-1,90,90},{251.565048217773,225,180,135,108.434951782227},{225,198.43495178 -2227,180,161.565048217773,135}}") + +SELECT + rid, + st_value( + st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_min4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 + ) +FROM dummy_rast +WHERE rid = 2; + rid | st_value +-----+---------- + 2 | 250 (1 row) - - + + + + + See Also + + , + , + , + , + , + , + , + + + + - - Examples: Variant 2 + + + ST_Max4ma + Raster processing function that calculates the maximum pixel value in a neighborhood. + + + + + + float8 ST_Max4ma + float8[][] matrix + text nodatamode + text[] VARIADIC args + - Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher. + + double precision ST_Max4ma + double precision[][][] value + integer[][] pos + text[] VARIADIC userargs + + + + + + Description - -WITH foo AS ( - SELECT ST_Tile( - ST_SetValues( - ST_AddBand( - ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0), - 1, '32BF', 0, -9999 - ), - 1, 1, 1, ARRAY[ - [1, 1, 1, 1, 1, 1], - [1, 1, 1, 1, 2, 1], - [1, 2, 2, 3, 3, 1], - [1, 1, 3, 2, 1, 1], - [1, 2, 2, 1, 2, 1], - [1, 1, 1, 1, 1, 1] - ]::double precision[] - ), - 2, 2 - ) AS rast -) -SELECT - t1.rast, - ST_Aspect(ST_Union(t2.rast), 1, t1.rast) -FROM foo t1 -CROSS JOIN foo t2 -WHERE ST_Intersects(t1.rast, t2.rast) -GROUP BY t1.rast; - - + Calculate the maximum pixel value in a neighborhood of pixels. + + + For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. + - - See Also + + Variant 1 is a specialized callback function for use as a callback parameter to . + + + - , - , - , - , - , - + Variant 2 is a specialized callback function for use as a callback parameter to . - - + - - - ST_HillShade - Returns the hypothetical illumination of an elevation raster band using provided azimuth, altitude, brightness and scale inputs. - - - - - raster ST_HillShade - raster rast - integer band=1 - text pixeltype=32BF - double precision azimuth=315 - double precision altitude=45 - double precision max_bright=255 - double precision scale=1.0 - boolean interpolate_nodata=FALSE - + + + Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + + - - raster ST_HillShade - raster rast - integer band - raster customextent - text pixeltype=32BF - double precision azimuth=315 - double precision altitude=45 - double precision max_bright=255 - double precision scale=1.0 - boolean interpolate_nodata=FALSE - - - - + Availability: 2.0.0 + Enhanced: 2.1.0 Addition of Variant 2 + + - Description + Examples - Returns the hypothetical illumination of an elevation raster band using the azimuth, altitude, brightness, and scale inputs. Utilizes map algebra and applies the hill shade equation to neighboring pixels. Return pixel values are between 0 and 255. + SELECT + rid, + st_value( + st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_max4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 + ) +FROM dummy_rast +WHERE rid = 2; + rid | st_value +-----+---------- + 2 | 254 +(1 row) + + + + + + See Also + + , + , + , + , + , + , + , + + + + - - azimuth is a value between 0 and 360 degrees measured clockwise from North. - + + + ST_Sum4ma + Raster processing function that calculates the sum of all pixel values in a neighborhood. + + + + + + float8 ST_Sum4ma + float8[][] matrix + text nodatamode + text[] VARIADIC args + - - altitude is a value between 0 and 90 degrees where 0 degrees is at the horizon and 90 degrees is directly overhead. - + + double precision ST_Sum4ma + double precision[][][] value + integer[][] pos + text[] VARIADIC userargs + + + + + + Description - - max_bright is a value between 0 and 255 with 0 as no brightness and 255 as max brightness. - + Calculate the sum of all pixel values in a neighborhood of pixels. + + + For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. + + + + Variant 1 is a specialized callback function for use as a callback parameter to . + + - scale is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120. + Variant 2 is a specialized callback function for use as a callback parameter to . + + - If interpolate_nodata is TRUE, values for NODATA pixels from the input raster will be interpolated using before computing the hillshade illumination. + Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + - - - For more information about Hillshade, please refer to How hillshade works. - - - - Availability: 2.0.0 - Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional interpolate_nodata function parameter - Changed: 2.1.0 In prior versions, azimuth and altitude were expressed in radians. Now, azimuth and altitude are expressed in degrees - - + Availability: 2.0.0 + Enhanced: 2.1.0 Addition of Variant 2 + - Examples: Variant 1 - -WITH foo AS ( - SELECT ST_SetValues( - ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999), - 1, 1, 1, ARRAY[ - [1, 1, 1, 1, 1], - [1, 2, 2, 2, 1], - [1, 2, 3, 2, 1], - [1, 2, 2, 2, 1], - [1, 1, 1, 1, 1] - ]::double precision[][] - ) AS rast -) -SELECT - ST_DumpValues(ST_Hillshade(rast, 1, '32BF')) -FROM foo - - st_dumpvalues - ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------ - (1,"{{NULL,NULL,NULL,NULL,NULL},{NULL,251.32763671875,220.749786376953,147.224319458008,NULL},{NULL,220.749786376953,180.312225341797,67.7497863769531,NULL},{NULL,147.224319458008 -,67.7497863769531,43.1210060119629,NULL},{NULL,NULL,NULL,NULL,NULL}}") + Examples + + SELECT + rid, + st_value( + st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_sum4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 + ) +FROM dummy_rast +WHERE rid = 2; + rid | st_value +-----+---------- + 2 | 2279 (1 row) - - + + + + + + See Also + + , + , + , + , + , + , + , + + + + - - Examples: Variant 2 + + + ST_Mean4ma + Raster processing function that calculates the mean pixel value in a neighborhood. + + + + + + float8 ST_Mean4ma + float8[][] matrix + text nodatamode + text[] VARIADIC args + - Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher. + + double precision ST_Mean4ma + double precision[][][] value + integer[][] pos + text[] VARIADIC userargs + + + + + + Description - -WITH foo AS ( - SELECT ST_Tile( - ST_SetValues( - ST_AddBand( - ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0), - 1, '32BF', 0, -9999 - ), - 1, 1, 1, ARRAY[ - [1, 1, 1, 1, 1, 1], - [1, 1, 1, 1, 2, 1], - [1, 2, 2, 3, 3, 1], - [1, 1, 3, 2, 1, 1], - [1, 2, 2, 1, 2, 1], - [1, 1, 1, 1, 1, 1] - ]::double precision[] - ), - 2, 2 - ) AS rast -) -SELECT - t1.rast, - ST_Hillshade(ST_Union(t2.rast), 1, t1.rast) -FROM foo t1 -CROSS JOIN foo t2 -WHERE ST_Intersects(t1.rast, t2.rast) -GROUP BY t1.rast; - - + Calculate the mean pixel value in a neighborhood of pixels. + + + For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. + - - See Also + + Variant 1 is a specialized callback function for use as a callback parameter to . + + + - , - , - , - , - , - + Variant 2 is a specialized callback function for use as a callback parameter to . - - + - - - ST_Roughness - Returns a raster with the calculated "roughness" of a DEM. - - - - - - raster ST_Roughness - raster rast - integer nband - raster customextent - text pixeltype="32BF" - boolean interpolate_nodata=FALSE - - - - - - Description - Calculates the "roughness" of a DEM, by subtracting the maximum from the minimum for a given area. - Availability: 2.1.0 - + + + Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + + + Availability: 2.0.0 + Enhanced: 2.1.0 Addition of Variant 2 + + Examples - --- needs examples - - - - - See Also - - , - , - , - , - , - - - - + + SELECT + rid, + st_value( + st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_mean4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 + ) +FROM dummy_rast +WHERE rid = 2; + rid | st_value +-----+------------------ + 2 | 253.222229003906 +(1 row) + + + + + + See Also + + , + , + , + , + , + , + + + + - - - ST_Slope - Returns the slope (in degrees by default) of an elevation raster band. Useful for analyzing terrain. - - - - - raster ST_Slope - raster rast - integer nband=1 - text pixeltype=32BF - text units=DEGREES - double precision scale=1.0 - boolean interpolate_nodata=FALSE - + + + ST_Range4ma + Raster processing function that calculates the range of pixel values in a neighborhood. + + + + + + float8 ST_Range4ma + float8[][] matrix + text nodatamode + text[] VARIADIC args + - - raster ST_Slope - raster rast - integer nband - raster customextent - text pixeltype=32BF - text units=DEGREES - double precision scale=1.0 - boolean interpolate_nodata=FALSE - - - + + double precision ST_Range4ma + double precision[][][] value + integer[][] pos + text[] VARIADIC userargs + + + - - Description - - Returns the slope (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the slope equation to neighboring pixels. + + Description - - units indicates the units of the slope. Possible values are: RADIANS, DEGREES (default), PERCENT. - + Calculate the range of pixel values in a neighborhood of pixels. + + + For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. + + + + Variant 1 is a specialized callback function for use as a callback parameter to . + + - scale is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120. + Variant 2 is a specialized callback function for use as a callback parameter to . + + - If interpolate_nodata is TRUE, values for NODATA pixels from the input raster will be interpolated using before computing the surface slope. + Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + - - - For more information about Slope, Aspect and Hillshade, please refer to ESRI - How hillshade works and ERDAS Field Guide - Slope Images. - - - - Availability: 2.0.0 - Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional units, scale, interpolate_nodata function parameters - Changed: 2.1.0 In prior versions, return values were in radians. Now, return values default to degrees - - + Availability: 2.0.0 + Enhanced: 2.1.0 Addition of Variant 2 + - Examples: Variant 1 - -WITH foo AS ( - SELECT ST_SetValues( - ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999), - 1, 1, 1, ARRAY[ - [1, 1, 1, 1, 1], - [1, 2, 2, 2, 1], - [1, 2, 3, 2, 1], - [1, 2, 2, 2, 1], - [1, 1, 1, 1, 1] - ]::double precision[][] - ) AS rast -) -SELECT - ST_DumpValues(ST_Slope(rast, 1, '32BF')) -FROM foo - - st_dumpvalues - ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ---------------------------------------------------------------------- - (1,"{{10.0249881744385,21.5681285858154,26.5650520324707,21.5681285858154,10.0249881744385},{21.5681285858154,35.2643890380859,36.8698959350586,35.2643890380859,21.5681285858154}, -{26.5650520324707,36.8698959350586,0,36.8698959350586,26.5650520324707},{21.5681285858154,35.2643890380859,36.8698959350586,35.2643890380859,21.5681285858154},{10.0249881744385,21. -5681285858154,26.5650520324707,21.5681285858154,10.0249881744385}}") + Examples + + SELECT + rid, + st_value( + st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_range4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 + ) +FROM dummy_rast +WHERE rid = 2; + rid | st_value +-----+---------- + 2 | 4 (1 row) - - + + + + + + See Also + + , + , + , + , + , + , + , + + + + + + + + ST_Distinct4ma + Raster processing function that calculates the number of unique pixel values in a neighborhood. + + + + + + float8 ST_Distinct4ma + float8[][] matrix + text nodatamode + text[] VARIADIC args + - - Examples: Variant 2 + + double precision ST_Distinct4ma + double precision[][][] value + integer[][] pos + text[] VARIADIC userargs + + + + + + Description - Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher. + Calculate the number of unique pixel values in a neighborhood of pixels. + + + Variant 1 is a specialized callback function for use as a callback parameter to . + - -WITH foo AS ( - SELECT ST_Tile( - ST_SetValues( - ST_AddBand( - ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0), - 1, '32BF', 0, -9999 - ), - 1, 1, 1, ARRAY[ - [1, 1, 1, 1, 1, 1], - [1, 1, 1, 1, 2, 1], - [1, 2, 2, 3, 3, 1], - [1, 1, 3, 2, 1, 1], - [1, 2, 2, 1, 2, 1], - [1, 1, 1, 1, 1, 1] - ]::double precision[] - ), - 2, 2 - ) AS rast -) -SELECT - t1.rast, - ST_Slope(ST_Union(t2.rast), 1, t1.rast) -FROM foo t1 -CROSS JOIN foo t2 -WHERE ST_Intersects(t1.rast, t2.rast) -GROUP BY t1.rast; - - - - - See Also + - , - , - , - , - , - + Variant 2 is a specialized callback function for use as a callback parameter to . - - - - - - ST_TPI - Returns a raster with the calculated Topographic Position Index. - + - - - - raster ST_TPI - raster rast - integer nband - raster customextent - text pixeltype="32BF" - boolean interpolate_nodata=FALSE - - - + + + Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + + + Availability: 2.0.0 + Enhanced: 2.1.0 Addition of Variant 2 + + - Description + Examples + + SELECT + rid, + st_value( + st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_distinct4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 + ) +FROM dummy_rast +WHERE rid = 2; + rid | st_value +-----+---------- + 2 | 3 +(1 row) + + + + + + See Also + + , + , + , + , + , + , + , + + + + - Calculates the Topographic Position Index, which is defined as the folcal mean with radius of one minus the center cell. + + + ST_StdDev4ma + Raster processing function that calculates the standard deviation of pixel values in a neighborhood. + + + + + + float8 ST_StdDev4ma + float8[][] matrix + text nodatamode + text[] VARIADIC args + - - This function only supports a focalmean radius of one. - - Availability: 2.1.0 - + + double precision ST_StdDev4ma + double precision[][][] value + integer[][] pos + text[] VARIADIC userargs + + + + + + Description - - Examples - --- needs examples - - + Calculate the standard deviation of pixel values in a neighborhood of pixels. + + + Variant 1 is a specialized callback function for use as a callback parameter to . + - - See Also + - , - , - , - , - , - + Variant 2 is a specialized callback function for use as a callback parameter to . - - - - - - ST_TRI - Returns a raster with the calculated Terrain Ruggedness Index. - - - - - - raster ST_TRI - raster rast - integer nband - raster customextent - text pixeltype="32BF" - boolean interpolate_nodata=FALSE - - - - - - Description + + - Terrain Ruggedness Index is calculated by comparing a central pixel with its neighbors, taking the absolute values of the differences, and averaging the result. + Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + - - This function only supports a focalmean radius of one. - - - Availability: 2.1.0 - - + Availability: 2.0.0 + Enhanced: 2.1.0 Addition of Variant 2 + + Examples - --- needs examples - - + + SELECT + rid, + st_value( + st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_stddev4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 + ) +FROM dummy_rast +WHERE rid = 2; + rid | st_value +-----+------------------ + 2 | 1.30170822143555 +(1 row) + + + + + + See Also + + , + , + , + , + , + , + , + + + + - - See Also - - , - , - , - , - , - - - - + + + ST_InvDistWeight4ma + Raster processing function that interpolates a pixel's value from the pixel's neighborhood. + - + + + + double precision ST_InvDistWeight4ma + double precision[][][] value + integer[][] pos + text[] VARIADIC userargs + + + - - Raster to Geometry + + Description - + Calculate an interpolated value for a pixel using the Inverse Distance Weighted method. + + + There are two optional parameters that can be passed through userargs. The first parameter is the power factor (variable k in the equation below) between 0 and 1 used in the Inverse Distance Weighted equation. If not specified, default value is 1. The second parameter is the weight percentage applied only when the value of the pixel of interest is included with the interpolated value from the neighborhood. If not specified and the pixel of interest has a value, that value is returned. + + + + The basic inverse distance weight equation is: + + + + + + + + + k = power factor, a real number between 0 and 1 + + + + + + + + This function is a specialized callback function for use as a callback parameter to . + + + Availability: 2.1.0 + + + + Examples + +-- NEEDS EXAMPLE + + + + + See Also + + , + + + + + + + + ST_MinDist4ma + Raster processing function that returns the minimum distance (in number of pixels) between the pixel of interest and a neighboring pixel with value. + + + + + + double precision ST_MinDist4ma + double precision[][][] value + integer[][] pos + text[] VARIADIC userargs + + + + + + Description + + Return the shortest distance (in number of pixels) between the pixel of interest and the closest pixel with value in the neighborhood. + + + + The intent of this function is to provide an informative data point that helps infer the usefulness of the pixel of interest's interpolated value from . This function is particularly useful when the neighborhood is sparsely populated. + + + + + This function is a specialized callback function for use as a callback parameter to . + + + Availability: 2.1.0 + + + + Examples + +-- NEEDS EXAMPLE + + + + + See Also + + , + + + + + + + + + DEM (Elevation) + + - Box3D - Returns the box 3d representation of the enclosing box of the raster. + ST_Aspect + Returns the aspect (in degrees by default) of an elevation raster band. Useful for analyzing terrain. - - box3d Box3D + raster ST_Aspect raster rast - + integer band=1 + text pixeltype=32BF + text units=DEGREES + boolean interpolate_nodata=FALSE + + + + raster ST_Aspect + raster rast + integer band + raster customextent + text pixeltype=32BF + text units=DEGREES + boolean interpolate_nodata=FALSE + Description - - Returns the box representing the extent of the raster. + + Returns the aspect (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the aspect equation to neighboring pixels. + - The polygon is defined by the corner points of the bounding box ((MINX, MINY), (MAXX, MAXY)) + units indicates the units of the aspect. Possible values are: RADIANS, DEGREES (default). - Changed: 2.0.0 In pre-2.0 versions, there used to be a box2d instead of box3d. Since box2d is a deprecated type, this was changed to box3d. + + When units = RADIANS, values are between 0 and 2 * pi radians measured clockwise from North. + + + + When units = DEGREES, values are between 0 and 360 degrees measured clockwise from North. + + + + If slope of pixel is zero, aspect of pixel is -1. + + + + + For more information about Slope, Aspect and Hillshade, please refer to ESRI - How hillshade works and ERDAS Field Guide - Aspect Images. + + + + Availability: 2.0.0 + Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional interpolate_nodata function parameter + Changed: 2.1.0 In prior versions, return values were in radians. Now, return values default to degrees - Examples - + Examples: Variant 1 +WITH foo AS ( + SELECT ST_SetValues( + ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999), + 1, 1, 1, ARRAY[ + [1, 1, 1, 1, 1], + [1, 2, 2, 2, 1], + [1, 2, 3, 2, 1], + [1, 2, 2, 2, 1], + [1, 1, 1, 1, 1] + ]::double precision[][] + ) AS rast +) SELECT - rid, - Box3D(rast) AS rastbox -FROM dummy_rast; + ST_DumpValues(ST_Aspect(rast, 1, '32BF')) +FROM foo -rid | rastbox -----+------------------------------------------------- -1 | BOX3D(0.5 0.5 0,20.5 60.5 0) -2 | BOX3D(3427927.75 5793243.5 0,3427928 5793244 0) + st_dumpvalues + +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +---------------------------------- + (1,"{{315,341.565063476562,0,18.4349479675293,45},{288.434936523438,315,0,45,71.5650482177734},{270,270,-1,90,90},{251.565048217773,225,180,135,108.434951782227},{225,198.43495178 +2227,180,161.565048217773,135}}") +(1 row) + + + + + Examples: Variant 2 + + Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher. + + +WITH foo AS ( + SELECT ST_Tile( + ST_SetValues( + ST_AddBand( + ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0), + 1, '32BF', 0, -9999 + ), + 1, 1, 1, ARRAY[ + [1, 1, 1, 1, 1, 1], + [1, 1, 1, 1, 2, 1], + [1, 2, 2, 3, 3, 1], + [1, 1, 3, 2, 1, 1], + [1, 2, 2, 1, 2, 1], + [1, 1, 1, 1, 1, 1] + ]::double precision[] + ), + 2, 2 + ) AS rast +) +SELECT + t1.rast, + ST_Aspect(ST_Union(t2.rast), 1, t1.rast) +FROM foo t1 +CROSS JOIN foo t2 +WHERE ST_Intersects(t1.rast, t2.rast) +GROUP BY t1.rast; See Also - + , + , + , + , + , + - + - ST_ConvexHull - Return the convex hull geometry of the raster including pixel values equal to BandNoDataValue. - For regular shaped and non-skewed - rasters, this gives the same result as ST_Envelope so only useful for irregularly shaped or skewed rasters. + ST_HillShade + Returns the hypothetical illumination of an elevation raster band using provided azimuth, altitude, brightness and scale inputs. - - geometry ST_ConvexHull - raster rast + raster ST_HillShade + raster rast + integer band=1 + text pixeltype=32BF + double precision azimuth=315 + double precision altitude=45 + double precision max_bright=255 + double precision scale=1.0 + boolean interpolate_nodata=FALSE - - - - - Description - Return the convex hull geometry of the raster including the NoDataBandValue band pixels. For regular shaped and non-skewed - rasters, this gives more or less the same result as ST_Envelope - so only useful for irregularly shaped or skewed rasters. - - ST_Envelope floors the coordinates and hence add a little buffer around the raster so the answer is subtly - different from ST_ConvexHull which does not floor. - - - - - Examples - Refer to PostGIS Raster Specification for a diagram of this. - --- Note envelope and convexhull are more or less the same -SELECT ST_AsText(ST_ConvexHull(rast)) As convhull, - ST_AsText(ST_Envelope(rast)) As env -FROM dummy_rast WHERE rid=1; - - convhull | env ---------------------------------------------------------+------------------------------------ - POLYGON((0.5 0.5,20.5 0.5,20.5 60.5,0.5 60.5,0.5 0.5)) | POLYGON((0 0,20 0,20 60,0 60,0 0)) - - --- now we skew the raster --- note how the convex hull and envelope are now different -SELECT ST_AsText(ST_ConvexHull(rast)) As convhull, - ST_AsText(ST_Envelope(rast)) As env -FROM (SELECT ST_SetRotation(rast, 0.1, 0.1) As rast - FROM dummy_rast WHERE rid=1) As foo; - - convhull | env ---------------------------------------------------------+------------------------------------ - POLYGON((0.5 0.5,20.5 1.5,22.5 61.5,2.5 60.5,0.5 0.5)) | POLYGON((0 0,22 0,22 61,0 61,0 0)) - - - - - - See Also - - , - , - , - - - - - - - - ST_DumpAsPolygons - Returns a set of geomval (geom,val) rows, from a given raster band. If no band number is specified, band num defaults to 1. - - - - - setof geomval ST_DumpAsPolygons + raster ST_HillShade raster rast - integer band_num=1 - boolean exclude_nodata_value=TRUE + integer band + raster customextent + text pixeltype=32BF + double precision azimuth=315 + double precision altitude=45 + double precision max_bright=255 + double precision scale=1.0 + boolean interpolate_nodata=FALSE - - - + + + Description - This is a set-returning function (SRF). It returns a set of - geomval rows, formed by a geometry (geom) and a pixel band value (val). - Each polygon is the union of all pixels for that band that have the same pixel value denoted by val. - - ST_DumpAsPolygon is useful for polygonizing rasters. It is the - reverse of a GROUP BY in that it creates new rows. For example it - can be used to expand a single raster into multiple POLYGONS/MULTIPOLYGONS. - - Availability: Requires GDAL 1.7 or higher. - If there is a no data value set for a band, pixels with that value will not be returned. - If you only care about count of pixels with a given value in a raster, it is faster to use . + + Returns the hypothetical illumination of an elevation raster band using the azimuth, altitude, brightness, and scale inputs. Utilizes map algebra and applies the hill shade equation to neighboring pixels. Return pixel values are between 0 and 255. + + + azimuth is a value between 0 and 360 degrees measured clockwise from North. + + + + altitude is a value between 0 and 90 degrees where 0 degrees is at the horizon and 90 degrees is directly overhead. + + + + max_bright is a value between 0 and 255 with 0 as no brightness and 255 as max brightness. + + + + scale is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120. + + + + If interpolate_nodata is TRUE, values for NODATA pixels from the input raster will be interpolated using before computing the hillshade illumination. + + - This is different than ST_PixelAsPolygons where one geometry is returned for each pixel regardless of pixel value. + For more information about Hillshade, please refer to How hillshade works. - - - - Examples + + Availability: 2.0.0 + Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional interpolate_nodata function parameter + Changed: 2.1.0 In prior versions, azimuth and altitude were expressed in radians. Now, azimuth and altitude are expressed in degrees + + + + + Examples: Variant 1 -SELECT val, ST_AsText(geom) As geomwkt -FROM ( -SELECT (ST_DumpAsPolygons(rast)).* -FROM dummy_rast -WHERE rid = 2 -) As foo -WHERE val BETWEEN 249 and 251 -ORDER BY val; +WITH foo AS ( + SELECT ST_SetValues( + ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999), + 1, 1, 1, ARRAY[ + [1, 1, 1, 1, 1], + [1, 2, 2, 2, 1], + [1, 2, 3, 2, 1], + [1, 2, 2, 2, 1], + [1, 1, 1, 1, 1] + ]::double precision[][] + ) AS rast +) +SELECT + ST_DumpValues(ST_Hillshade(rast, 1, '32BF')) +FROM foo - val | geomwkt ------+-------------------------------------------------------------------------- - 249 | POLYGON((3427927.95 5793243.95,3427927.95 5793243.85,3427928 5793243.85, - 3427928 5793243.95,3427927.95 5793243.95)) - 250 | POLYGON((3427927.75 5793243.9,3427927.75 5793243.85,3427927.8 5793243.85, - 3427927.8 5793243.9,3427927.75 5793243.9)) - 250 | POLYGON((3427927.8 5793243.8,3427927.8 5793243.75,3427927.85 5793243.75, - 3427927.85 5793243.8, 3427927.8 5793243.8)) - 251 | POLYGON((3427927.75 5793243.85,3427927.75 5793243.8,3427927.8 5793243.8, - 3427927.8 5793243.85,3427927.75 5793243.85)) + st_dumpvalues + +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +----------------------------------------------------------------------- + (1,"{{NULL,NULL,NULL,NULL,NULL},{NULL,251.32763671875,220.749786376953,147.224319458008,NULL},{NULL,220.749786376953,180.312225341797,67.7497863769531,NULL},{NULL,147.224319458008 +,67.7497863769531,43.1210060119629,NULL},{NULL,NULL,NULL,NULL,NULL}}") +(1 row) - + + + + Examples: Variant 2 + + Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher. + + +WITH foo AS ( + SELECT ST_Tile( + ST_SetValues( + ST_AddBand( + ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0), + 1, '32BF', 0, -9999 + ), + 1, 1, 1, ARRAY[ + [1, 1, 1, 1, 1, 1], + [1, 1, 1, 1, 2, 1], + [1, 2, 2, 3, 3, 1], + [1, 1, 3, 2, 1, 1], + [1, 2, 2, 1, 2, 1], + [1, 1, 1, 1, 1, 1] + ]::double precision[] + ), + 2, 2 + ) AS rast +) +SELECT + t1.rast, + ST_Hillshade(ST_Union(t2.rast), 1, t1.rast) +FROM foo t1 +CROSS JOIN foo t2 +WHERE ST_Intersects(t1.rast, t2.rast) +GROUP BY t1.rast; + + See Also - , - , - , - + , + , + , + , + , + - + - ST_Envelope - Returns the polygon representation of the extent of the raster. + ST_Roughness + Returns a raster with the calculated "roughness" of a DEM. - geometry ST_Envelope + raster ST_Roughness raster rast + integer nband + raster customextent + text pixeltype="32BF" + boolean interpolate_nodata=FALSE Description - - Returns the polygon representation of the extent of the raster in spatial coordinate units defined by srid. It is a float8 minimum bounding box represented as a polygon. - - The polygon is defined by the corner points of the bounding box - ((MINX, MINY), - (MINX, MAXY), - (MAXX, MAXY), - (MAXX, MINY), - (MINX, MINY)) - + Calculates the "roughness" of a DEM, by subtracting the maximum from the minimum for a given area. + Availability: 2.1.0 - + Examples - -SELECT rid, ST_AsText(ST_Envelope(rast)) As envgeomwkt -FROM dummy_rast; - - rid | envgeomwkt ------+-------------------------------------------------------------------- - 1 | POLYGON((0 0,20 0,20 60,0 60,0 0)) - 2 | POLYGON((3427927 5793243,3427928 5793243, - 3427928 5793244,3427927 5793244, 3427927 5793243)) +-- needs examples - + - - See Also + + See Also - , - , - - - - - - + , + , + , + , + , + + + + + + - ST_MinConvexHull - - Return the convex hull geometry of the raster excluding NODATA pixels. - + ST_Slope + Returns the slope (in degrees by default) of an elevation raster band. Useful for analyzing terrain. - - - geometry ST_MinConvexHull + + raster ST_Slope raster rast - integer nband=NULL - + integer nband=1 + text pixeltype=32BF + text units=DEGREES + double precision scale=1.0 + boolean interpolate_nodata=FALSE + + + + raster ST_Slope + raster rast + integer nband + raster customextent + text pixeltype=32BF + text units=DEGREES + double precision scale=1.0 + boolean interpolate_nodata=FALSE + - + Description + + Returns the slope (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the slope equation to neighboring pixels. - Return the convex hull geometry of the raster excluding NODATA pixels. If nband is NULL, all bands of the raster are considered. + units indicates the units of the slope. Possible values are: RADIANS, DEGREES (default), PERCENT. - Availability: 2.1.0 + + scale is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120. + + + + If interpolate_nodata is TRUE, values for NODATA pixels from the input raster will be interpolated using before computing the surface slope. + + + + + For more information about Slope, Aspect and Hillshade, please refer to ESRI - How hillshade works and ERDAS Field Guide - Slope Images. + + + + Availability: 2.0.0 + Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional units, scale, interpolate_nodata function parameters + Changed: 2.1.0 In prior versions, return values were in radians. Now, return values default to degrees + + + + + Examples: Variant 1 + +WITH foo AS ( + SELECT ST_SetValues( + ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999), + 1, 1, 1, ARRAY[ + [1, 1, 1, 1, 1], + [1, 2, 2, 2, 1], + [1, 2, 3, 2, 1], + [1, 2, 2, 2, 1], + [1, 1, 1, 1, 1] + ]::double precision[][] + ) AS rast +) +SELECT + ST_DumpValues(ST_Slope(rast, 1, '32BF')) +FROM foo + + st_dumpvalues + +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +--------------------------------------------------------------------- + (1,"{{10.0249881744385,21.5681285858154,26.5650520324707,21.5681285858154,10.0249881744385},{21.5681285858154,35.2643890380859,36.8698959350586,35.2643890380859,21.5681285858154}, +{26.5650520324707,36.8698959350586,0,36.8698959350586,26.5650520324707},{21.5681285858154,35.2643890380859,36.8698959350586,35.2643890380859,21.5681285858154},{10.0249881744385,21. +5681285858154,26.5650520324707,21.5681285858154,10.0249881744385}}") +(1 row) + - Examples + Examples: Variant 2 + + Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher. + WITH foo AS ( - SELECT + SELECT ST_Tile( ST_SetValues( - ST_SetValues( - ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(9, 9, 0, 0, 1, -1, 0, 0, 0), 1, '8BUI', 0, 0), 2, '8BUI', 1, 0), - 1, 1, 1, - ARRAY[ - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 1, 0, 0, 0, 0, 1], - [0, 0, 0, 1, 1, 0, 0, 0, 0], - [0, 0, 0, 1, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0] - ]::double precision[][] + ST_AddBand( + ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0), + 1, '32BF', 0, -9999 ), - 2, 1, 1, - ARRAY[ - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [1, 0, 0, 0, 0, 1, 0, 0, 0], - [0, 0, 0, 0, 1, 1, 0, 0, 0], - [0, 0, 0, 0, 0, 1, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 1, 0, 0, 0, 0, 0, 0] - ]::double precision[][] - ) AS rast + 1, 1, 1, ARRAY[ + [1, 1, 1, 1, 1, 1], + [1, 1, 1, 1, 2, 1], + [1, 2, 2, 3, 3, 1], + [1, 1, 3, 2, 1, 1], + [1, 2, 2, 1, 2, 1], + [1, 1, 1, 1, 1, 1] + ]::double precision[] + ), + 2, 2 + ) AS rast ) SELECT - ST_AsText(ST_ConvexHull(rast)) AS hull, - ST_AsText(ST_MinConvexHull(rast)) AS mhull, - ST_AsText(ST_MinConvexHull(rast, 1)) AS mhull_1, - ST_AsText(ST_MinConvexHull(rast, 2)) AS mhull_2 -FROM foo - - hull | mhull | mhull_1 | mhull_2 -----------------------------------+-------------------------------------+-------------------------------------+------------------------------------- - POLYGON((0 0,9 0,9 -9,0 -9,0 0)) | POLYGON((0 -3,9 -3,9 -9,0 -9,0 -3)) | POLYGON((3 -3,9 -3,9 -6,3 -6,3 -3)) | POLYGON((0 -3,6 -3,6 -9,0 -9,0 -3)) + t1.rast, + ST_Slope(ST_Union(t2.rast), 1, t1.rast) +FROM foo t1 +CROSS JOIN foo t2 +WHERE ST_Intersects(t1.rast, t2.rast) +GROUP BY t1.rast; - + See Also - , - , - , - + , + , + , + , + , + - - - - ST_Polygon - Returns a multipolygon geometry formed by the union of pixels that have a pixel value that is not no data value. If no band number is specified, band num defaults to 1. - - - + + + + ST_TPI + Returns a raster with the calculated Topographic Position Index. + + + - - geometry ST_Polygon + + raster ST_TPI raster rast - integer band_num=1 - + integer nband + raster customextent + text pixeltype="32BF" + boolean interpolate_nodata=FALSE + - - + + Description - Availability: 0.1.6 Requires GDAL 1.7 or higher. - Enhanced: 2.1.0 Improved Speed (fully C-Based) and the returning multipolygon is ensured to be valid. - Changed: 2.1.0 In prior versions would sometimes return a polygon, changed to always return multipolygon. + + Calculates the Topographic Position Index, which is defined as the folcal mean with radius of one minus the center cell. + + + This function only supports a focalmean radius of one. + + Availability: 2.1.0 - + Examples --- by default no data band value is 0 or not set, so polygon will return a square polygon -SELECT ST_AsText(ST_Polygon(rast)) As geomwkt -FROM dummy_rast -WHERE rid = 2; +-- needs examples + + -geomwkt --------------------------------------------- -MULTIPOLYGON(((3427927.75 5793244,3427928 5793244,3427928 5793243.75,3427927.75 5793243.75,3427927.75 5793244))) - - --- now we change the no data value of first band -UPDATE dummy_rast SET rast = ST_SetBandNoDataValue(rast,1,254) -WHERE rid = 2; -SELECt rid, ST_BandNoDataValue(rast) -from dummy_rast where rid = 2; + + See Also + + , + , + , + , + , + + + + --- ST_Polygon excludes the pixel value 254 and returns a multipolygon -SELECT ST_AsText(ST_Polygon(rast)) As geomwkt -FROM dummy_rast -WHERE rid = 2; + + + ST_TRI + Returns a raster with the calculated Terrain Ruggedness Index. + -geomwkt ---------------------------------------------------------- -MULTIPOLYGON(((3427927.9 5793243.95,3427927.85 5793243.95,3427927.85 5793244,3427927.9 5793244,3427927.9 5793243.95)),((3427928 5793243.85,3427928 5793243.8,3427927.95 5793243.8,3427927.95 5793243.85,3427927.9 5793243.85,3427927.9 5793243.9,3427927.9 5793243.95,3427927.95 5793243.95,3427928 5793243.95,3427928 5793243.85)),((3427927.8 5793243.75,3427927.75 5793243.75,3427927.75 5793243.8,3427927.75 5793243.85,3427927.75 5793243.9,3427927.75 5793244,3427927.8 5793244,3427927.8 5793243.9,3427927.8 5793243.85,3427927.85 5793243.85,3427927.85 5793243.8,3427927.85 5793243.75,3427927.8 5793243.75))) + + + + raster ST_TRI + raster rast + integer nband + raster customextent + text pixeltype="32BF" + boolean interpolate_nodata=FALSE + + + --- Or if you want the no data value different for just one time + + Description -SELECT ST_AsText( - ST_Polygon( - ST_SetBandNoDataValue(rast,1,252) - ) - ) As geomwkt -FROM dummy_rast -WHERE rid =2; + + Terrain Ruggedness Index is calculated by comparing a central pixel with its neighbors, taking the absolute values of the differences, and averaging the result. + -geomwkt ---------------------------------- -MULTIPOLYGON(((3427928 5793243.85,3427928 5793243.8,3427928 5793243.75,3427927.85 5793243.75,3427927.8 5793243.75,3427927.8 5793243.8,3427927.75 5793243.8,3427927.75 5793243.85,3427927.75 5793243.9,3427927.75 5793244,3427927.8 5793244,3427927.85 5793244,3427927.9 5793244,3427928 5793244,3427928 5793243.95,3427928 5793243.85),(3427927.9 5793243.9,3427927.9 5793243.85,3427927.95 5793243.85,3427927.95 5793243.9,3427927.9 5793243.9))) - + + This function only supports a focalmean radius of one. + + + Availability: 2.1.0 + + Examples + +-- needs examples + + + See Also - - , - - + + , + , + , + , + , + + - + - + + Raster to Geometry - - Raster Map Algebra Built-in Functions - - - ST_Min4ma - - Raster processing function that calculates the minimum pixel value in a neighborhood. - - + + + Box3D + Returns the box 3d representation of the enclosing box of the raster. + - - - - float8 ST_Min4ma - float8[][] matrix - text nodatamode - text[] VARIADIC args - - - - double precision ST_Min4ma - double precision[][][] value - integer[][] pos - text[] VARIADIC userargs - - - - - - Description - - - Calculate the minimum pixel value in a neighborhood of pixels. - - - - For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. - - - + + + + box3d Box3D + raster rast + + + + + + Description + + Returns the box representing the extent of the raster. - Variant 1 is a specialized callback function for use as a callback parameter to . + The polygon is defined by the corner points of the bounding box ((MINX, MINY), (MAXX, MAXY)) - - - - Variant 2 is a specialized callback function for use as a callback parameter to . - - + Changed: 2.0.0 In pre-2.0 versions, there used to be a box2d instead of box3d. Since box2d is a deprecated type, this was changed to box3d. + + + + Examples + + +SELECT + rid, + Box3D(rast) AS rastbox +FROM dummy_rast; - +rid | rastbox +----+------------------------------------------------- +1 | BOX3D(0.5 0.5 0,20.5 60.5 0) +2 | BOX3D(3427927.75 5793243.5 0,3427928 5793244 0) + + + + + See Also - Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + - + + - Availability: 2.0.0 - Enhanced: 2.1.0 Addition of Variant 2 - + + + ST_ConvexHull + Return the convex hull geometry of the raster including pixel values equal to BandNoDataValue. + For regular shaped and non-skewed + rasters, this gives the same result as ST_Envelope so only useful for irregularly shaped or skewed rasters. + + + + + + geometry ST_ConvexHull + raster rast + + + + + + Description - - Examples + Return the convex hull geometry of the raster including the NoDataBandValue band pixels. For regular shaped and non-skewed + rasters, this gives more or less the same result as ST_Envelope + so only useful for irregularly shaped or skewed rasters. + + ST_Envelope floors the coordinates and hence add a little buffer around the raster so the answer is subtly + different from ST_ConvexHull which does not floor. + + + + + Examples + Refer to PostGIS Raster Specification for a diagram of this. + +-- Note envelope and convexhull are more or less the same +SELECT ST_AsText(ST_ConvexHull(rast)) As convhull, + ST_AsText(ST_Envelope(rast)) As env +FROM dummy_rast WHERE rid=1; - -SELECT - rid, - st_value( - st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_min4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 - ) -FROM dummy_rast -WHERE rid = 2; - rid | st_value ------+---------- - 2 | 250 -(1 row) + convhull | env +--------------------------------------------------------+------------------------------------ + POLYGON((0.5 0.5,20.5 0.5,20.5 60.5,0.5 60.5,0.5 0.5)) | POLYGON((0 0,20 0,20 60,0 60,0 0)) - + +-- now we skew the raster +-- note how the convex hull and envelope are now different +SELECT ST_AsText(ST_ConvexHull(rast)) As convhull, + ST_AsText(ST_Envelope(rast)) As env +FROM (SELECT ST_SetRotation(rast, 0.1, 0.1) As rast + FROM dummy_rast WHERE rid=1) As foo; + + convhull | env +--------------------------------------------------------+------------------------------------ + POLYGON((0.5 0.5,20.5 1.5,22.5 61.5,2.5 60.5,0.5 0.5)) | POLYGON((0 0,22 0,22 61,0 61,0 0)) + + - - See Also - - , - , - , - , - , - , - , - - - - + + + See Also + + , + , + , + + + + - - - ST_Max4ma - Raster processing function that calculates the maximum pixel value in a neighborhood. - - - - - - float8 ST_Max4ma - float8[][] matrix - text nodatamode - text[] VARIADIC args - - - - double precision ST_Max4ma - double precision[][][] value - integer[][] pos - text[] VARIADIC userargs - - - - - - Description - - Calculate the maximum pixel value in a neighborhood of pixels. - - - For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. - - - - Variant 1 is a specialized callback function for use as a callback parameter to . - - - - - Variant 2 is a specialized callback function for use as a callback parameter to . - - - - - - Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. - - - - Availability: 2.0.0 - Enhanced: 2.1.0 Addition of Variant 2 - - - - Examples - - SELECT - rid, - st_value( - st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_max4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 - ) -FROM dummy_rast -WHERE rid = 2; - rid | st_value ------+---------- - 2 | 254 -(1 row) - - - - - - See Also - - , - , - , - , - , - , - , - - - - - - - - ST_Sum4ma - Raster processing function that calculates the sum of all pixel values in a neighborhood. - - - - - - float8 ST_Sum4ma - float8[][] matrix - text nodatamode - text[] VARIADIC args - - - - double precision ST_Sum4ma - double precision[][][] value - integer[][] pos - text[] VARIADIC userargs - - - - - - Description - - Calculate the sum of all pixel values in a neighborhood of pixels. - - - For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. - - - - Variant 1 is a specialized callback function for use as a callback parameter to . - - - - - Variant 2 is a specialized callback function for use as a callback parameter to . - - - - - - Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. - - - - Availability: 2.0.0 - Enhanced: 2.1.0 Addition of Variant 2 - - - - Examples - - SELECT - rid, - st_value( - st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_sum4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 - ) -FROM dummy_rast -WHERE rid = 2; - rid | st_value ------+---------- - 2 | 2279 -(1 row) - - - - - - See Also - - , - , - , - , - , - , - , - - - - - - - - ST_Mean4ma - Raster processing function that calculates the mean pixel value in a neighborhood. - - - - - - float8 ST_Mean4ma - float8[][] matrix - text nodatamode - text[] VARIADIC args - - - - double precision ST_Mean4ma - double precision[][][] value - integer[][] pos - text[] VARIADIC userargs - - - - - - Description - - Calculate the mean pixel value in a neighborhood of pixels. - - - For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. - - - - Variant 1 is a specialized callback function for use as a callback parameter to . - - - - - Variant 2 is a specialized callback function for use as a callback parameter to . - - - - - - Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. - - - - Availability: 2.0.0 - Enhanced: 2.1.0 Addition of Variant 2 - - - - Examples - - SELECT - rid, - st_value( - st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_mean4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 - ) -FROM dummy_rast -WHERE rid = 2; - rid | st_value ------+------------------ - 2 | 253.222229003906 -(1 row) - - - - - - See Also - - , - , - , - , - , - , - - - - - - - - ST_Range4ma - Raster processing function that calculates the range of pixel values in a neighborhood. - - - - - - float8 ST_Range4ma - float8[][] matrix - text nodatamode - text[] VARIADIC args - - - - double precision ST_Range4ma - double precision[][][] value - integer[][] pos - text[] VARIADIC userargs - - - - - - Description - - Calculate the range of pixel values in a neighborhood of pixels. - - - For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs. - - - - Variant 1 is a specialized callback function for use as a callback parameter to . - - - - - Variant 2 is a specialized callback function for use as a callback parameter to . - - - - - - Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. - - - - Availability: 2.0.0 - Enhanced: 2.1.0 Addition of Variant 2 - - - + + + ST_DumpAsPolygons + Returns a set of geomval (geom,val) rows, from a given raster band. If no band number is specified, band num defaults to 1. + + + + + + setof geomval ST_DumpAsPolygons + raster rast + integer band_num=1 + boolean exclude_nodata_value=TRUE + + + + + + Description + This is a set-returning function (SRF). It returns a set of + geomval rows, formed by a geometry (geom) and a pixel band value (val). + Each polygon is the union of all pixels for that band that have the same pixel value denoted by val. + + ST_DumpAsPolygon is useful for polygonizing rasters. It is the + reverse of a GROUP BY in that it creates new rows. For example it + can be used to expand a single raster into multiple POLYGONS/MULTIPOLYGONS. + + Availability: Requires GDAL 1.7 or higher. + If there is a no data value set for a band, pixels with that value will not be returned. + If you only care about count of pixels with a given value in a raster, it is faster to use . + + + This is different than ST_PixelAsPolygons where one geometry is returned for each pixel regardless of pixel value. + + + + + Examples - - SELECT - rid, - st_value( - st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_range4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 - ) + +SELECT val, ST_AsText(geom) As geomwkt +FROM ( +SELECT (ST_DumpAsPolygons(rast)).* FROM dummy_rast -WHERE rid = 2; - rid | st_value ------+---------- - 2 | 4 -(1 row) - - - - - - See Also - - , - , - , - , - , - , - , - - - - - - - - ST_Distinct4ma - Raster processing function that calculates the number of unique pixel values in a neighborhood. - - - - - - float8 ST_Distinct4ma - float8[][] matrix - text nodatamode - text[] VARIADIC args - - - - double precision ST_Distinct4ma - double precision[][][] value - integer[][] pos - text[] VARIADIC userargs - - - - - - Description - - Calculate the number of unique pixel values in a neighborhood of pixels. - - - Variant 1 is a specialized callback function for use as a callback parameter to . - +WHERE rid = 2 +) As foo +WHERE val BETWEEN 249 and 251 +ORDER BY val; - - - Variant 2 is a specialized callback function for use as a callback parameter to . - - + val | geomwkt +-----+-------------------------------------------------------------------------- + 249 | POLYGON((3427927.95 5793243.95,3427927.95 5793243.85,3427928 5793243.85, + 3427928 5793243.95,3427927.95 5793243.95)) + 250 | POLYGON((3427927.75 5793243.9,3427927.75 5793243.85,3427927.8 5793243.85, + 3427927.8 5793243.9,3427927.75 5793243.9)) + 250 | POLYGON((3427927.8 5793243.8,3427927.8 5793243.75,3427927.85 5793243.75, + 3427927.85 5793243.8, 3427927.8 5793243.8)) + 251 | POLYGON((3427927.75 5793243.85,3427927.75 5793243.8,3427927.8 5793243.8, + 3427927.8 5793243.85,3427927.75 5793243.85)) + + - + + See Also - Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + , + , + , + - - - Availability: 2.0.0 - Enhanced: 2.1.0 Addition of Variant 2 - - - - Examples - - SELECT - rid, - st_value( - st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_distinct4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 - ) -FROM dummy_rast -WHERE rid = 2; - rid | st_value ------+---------- - 2 | 3 -(1 row) - - - - - - See Also - - , - , - , - , - , - , - , - - - - + + - - - ST_StdDev4ma - Raster processing function that calculates the standard deviation of pixel values in a neighborhood. - - - - - - float8 ST_StdDev4ma - float8[][] matrix - text nodatamode - text[] VARIADIC args - + + + ST_Envelope + Returns the polygon representation of the extent of the raster. + - - double precision ST_StdDev4ma - double precision[][][] value - integer[][] pos - text[] VARIADIC userargs - - - - - - Description + + + + geometry ST_Envelope + raster rast + + + - Calculate the standard deviation of pixel values in a neighborhood of pixels. - - - Variant 1 is a specialized callback function for use as a callback parameter to . - + + Description - - - Variant 2 is a specialized callback function for use as a callback parameter to . - - + Returns the polygon representation of the extent of the raster in spatial coordinate units defined by srid. It is a float8 minimum bounding box represented as a polygon. - - - Use of Variant 1 is discouraged since has been deprecated as of 2.1.0. + The polygon is defined by the corner points of the bounding box + ((MINX, MINY), + (MINX, MAXY), + (MAXX, MAXY), + (MAXX, MINY), + (MINX, MINY)) - - - Availability: 2.0.0 - Enhanced: 2.1.0 Addition of Variant 2 - + Examples - SELECT - rid, - st_value( - st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_stddev4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2 - ) -FROM dummy_rast -WHERE rid = 2; - rid | st_value ------+------------------ - 2 | 1.30170822143555 -(1 row) - - - - - - See Also - - , - , - , - , - , - , - , - - - - + +SELECT rid, ST_AsText(ST_Envelope(rast)) As envgeomwkt +FROM dummy_rast; + + rid | envgeomwkt +-----+-------------------------------------------------------------------- + 1 | POLYGON((0 0,20 0,20 60,0 60,0 0)) + 2 | POLYGON((3427927 5793243,3427928 5793243, + 3427928 5793244,3427927 5793244, 3427927 5793243)) + + - - - ST_InvDistWeight4ma - Raster processing function that interpolates a pixel's value from the pixel's neighborhood. - + + See Also + + , + , + + + + - - - - double precision ST_InvDistWeight4ma - double precision[][][] value - integer[][] pos - text[] VARIADIC userargs - - - + + + ST_MinConvexHull + + Return the convex hull geometry of the raster excluding NODATA pixels. + + - - Description + + + + geometry ST_MinConvexHull + raster rast + integer nband=NULL + + + - Calculate an interpolated value for a pixel using the Inverse Distance Weighted method. + + Description - - There are two optional parameters that can be passed through userargs. The first parameter is the power factor (variable k in the equation below) between 0 and 1 used in the Inverse Distance Weighted equation. If not specified, default value is 1. The second parameter is the weight percentage applied only when the value of the pixel of interest is included with the interpolated value from the neighborhood. If not specified and the pixel of interest has a value, that value is returned. - + + Return the convex hull geometry of the raster excluding NODATA pixels. If nband is NULL, all bands of the raster are considered. + - - The basic inverse distance weight equation is: + Availability: 2.1.0 + - - - - - - - - k = power factor, a real number between 0 and 1 - - - - - + + Examples + +WITH foo AS ( + SELECT + ST_SetValues( + ST_SetValues( + ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(9, 9, 0, 0, 1, -1, 0, 0, 0), 1, '8BUI', 0, 0), 2, '8BUI', 1, 0), + 1, 1, 1, + ARRAY[ + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [0, 0, 0, 1, 0, 0, 0, 0, 1], + [0, 0, 0, 1, 1, 0, 0, 0, 0], + [0, 0, 0, 1, 0, 0, 0, 0, 0], + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [0, 0, 0, 0, 0, 0, 0, 0, 0] + ]::double precision[][] + ), + 2, 1, 1, + ARRAY[ + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [1, 0, 0, 0, 0, 1, 0, 0, 0], + [0, 0, 0, 0, 1, 1, 0, 0, 0], + [0, 0, 0, 0, 0, 1, 0, 0, 0], + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [0, 0, 0, 0, 0, 0, 0, 0, 0], + [0, 0, 1, 0, 0, 0, 0, 0, 0] + ]::double precision[][] + ) AS rast +) +SELECT + ST_AsText(ST_ConvexHull(rast)) AS hull, + ST_AsText(ST_MinConvexHull(rast)) AS mhull, + ST_AsText(ST_MinConvexHull(rast, 1)) AS mhull_1, + ST_AsText(ST_MinConvexHull(rast, 2)) AS mhull_2 +FROM foo - - This function is a specialized callback function for use as a callback parameter to . - + hull | mhull | mhull_1 | mhull_2 +----------------------------------+-------------------------------------+-------------------------------------+------------------------------------- + POLYGON((0 0,9 0,9 -9,0 -9,0 0)) | POLYGON((0 -3,9 -3,9 -9,0 -9,0 -3)) | POLYGON((3 -3,9 -3,9 -6,3 -6,3 -3)) | POLYGON((0 -3,6 -3,6 -9,0 -9,0 -3)) + + + + + See Also + + , + , + , + + + + + + + + ST_Polygon + Returns a multipolygon geometry formed by the union of pixels that have a pixel value that is not no data value. If no band number is specified, band num defaults to 1. + + + + + + geometry ST_Polygon + raster rast + integer band_num=1 + + + + + + Description + Availability: 0.1.6 Requires GDAL 1.7 or higher. + Enhanced: 2.1.0 Improved Speed (fully C-Based) and the returning multipolygon is ensured to be valid. + Changed: 2.1.0 In prior versions would sometimes return a polygon, changed to always return multipolygon. + - Availability: 2.1.0 - + + Examples + +-- by default no data band value is 0 or not set, so polygon will return a square polygon +SELECT ST_AsText(ST_Polygon(rast)) As geomwkt +FROM dummy_rast +WHERE rid = 2; - - Examples - --- NEEDS EXAMPLE - - +geomwkt +-------------------------------------------- +MULTIPOLYGON(((3427927.75 5793244,3427928 5793244,3427928 5793243.75,3427927.75 5793243.75,3427927.75 5793244))) + + +-- now we change the no data value of first band +UPDATE dummy_rast SET rast = ST_SetBandNoDataValue(rast,1,254) +WHERE rid = 2; +SELECt rid, ST_BandNoDataValue(rast) +from dummy_rast where rid = 2; - - See Also - - , - - - - +-- ST_Polygon excludes the pixel value 254 and returns a multipolygon +SELECT ST_AsText(ST_Polygon(rast)) As geomwkt +FROM dummy_rast +WHERE rid = 2; - - - ST_MinDist4ma - Raster processing function that returns the minimum distance (in number of pixels) between the pixel of interest and a neighboring pixel with value. - +geomwkt +--------------------------------------------------------- +MULTIPOLYGON(((3427927.9 5793243.95,3427927.85 5793243.95,3427927.85 5793244,3427927.9 5793244,3427927.9 5793243.95)),((3427928 5793243.85,3427928 5793243.8,3427927.95 5793243.8,3427927.95 5793243.85,3427927.9 5793243.85,3427927.9 5793243.9,3427927.9 5793243.95,3427927.95 5793243.95,3427928 5793243.95,3427928 5793243.85)),((3427927.8 5793243.75,3427927.75 5793243.75,3427927.75 5793243.8,3427927.75 5793243.85,3427927.75 5793243.9,3427927.75 5793244,3427927.8 5793244,3427927.8 5793243.9,3427927.8 5793243.85,3427927.85 5793243.85,3427927.85 5793243.8,3427927.85 5793243.75,3427927.8 5793243.75))) - - - - double precision ST_MinDist4ma - double precision[][][] value - integer[][] pos - text[] VARIADIC userargs - - - +-- Or if you want the no data value different for just one time - - Description +SELECT ST_AsText( + ST_Polygon( + ST_SetBandNoDataValue(rast,1,252) + ) + ) As geomwkt +FROM dummy_rast +WHERE rid =2; - Return the shortest distance (in number of pixels) between the pixel of interest and the closest pixel with value in the neighborhood. +geomwkt +--------------------------------- +MULTIPOLYGON(((3427928 5793243.85,3427928 5793243.8,3427928 5793243.75,3427927.85 5793243.75,3427927.8 5793243.75,3427927.8 5793243.8,3427927.75 5793243.8,3427927.75 5793243.85,3427927.75 5793243.9,3427927.75 5793244,3427927.8 5793244,3427927.85 5793244,3427927.9 5793244,3427928 5793244,3427928 5793243.95,3427928 5793243.85),(3427927.9 5793243.9,3427927.9 5793243.85,3427927.95 5793243.85,3427927.95 5793243.9,3427927.9 5793243.9))) + + - + + See Also - The intent of this function is to provide an informative data point that helps infer the usefulness of the pixel of interest's interpolated value from . This function is particularly useful when the neighborhood is sparsely populated. + , + - - - - This function is a specialized callback function for use as a callback parameter to . - - - Availability: 2.1.0 - - - - Examples - --- NEEDS EXAMPLE - - + + - - See Also - - , - - - - + - + Raster Operators -- 2.40.0