From: Regina Obe Date: Tue, 14 May 2013 12:57:25 +0000 (+0000) Subject: alphabetize raster processing section - impossible to find stuff otherwise X-Git-Tag: 2.1.0beta3~64 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=760741bc70c310a5af05adb408130f08ae50bf55;p=postgis alphabetize raster processing section - impossible to find stuff otherwise git-svn-id: http://svn.osgeo.org/postgis/trunk@11460 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml index 77ed212f9..fef2914b9 100644 --- a/doc/reference_raster.xml +++ b/doc/reference_raster.xml @@ -7657,7 +7657,145 @@ rid | rastbox + + + + 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 + + + + raster ST_Aspect + raster rast + integer band + raster customextent + text pixeltype=32BF + text units=DEGREES + boolean interpolate_nodata=FALSE + + + + + Description + + Returns the aspect (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the aspect equation to neighboring pixels. + + + units indicates the units of the aspect. Possible values are: RADIANS, DEGREES (default). + + + + 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: 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 + + 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_Clip @@ -7921,89 +8059,31 @@ WHERE rid = 4; - - + + - 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_ColorMap + Creates a new raster of up to four 8BUI bands (grayscale, RGB, RGBA) from the source raster and a specified band. Band 1 is assumed if not specified. - geometry ST_ConvexHull - raster rast + raster ST_ColorMap + raster rast + integer nband=1 + text colormap=grayscale + text method=INTERPOLATE - - - - 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_MinConvexHull - - Return the convex hull geometry of the raster excluding NODATA pixels. - - - - geometry ST_MinConvexHull + + raster ST_ColorMap raster rast - integer nband=NULL - + text colormap + text method=INTERPOLATE + @@ -8011,215 +8091,236 @@ FROM (SELECT ST_SetRotation(rast, 0.1, 0.1) As rast Description - Return the convex hull geometry of the raster excluding NODATA pixels. If nband is NULL, all bands of the raster are considered. + Apply a colormap to the band at nband of rast resulting a new raster comprised of up to four 8BUI bands. The number of 8BUI bands in the new raster is determined by the number of color components defined in colormap. - - Availability: 2.1.0 - + If nband is not specified, then band 1 is assumed. - - 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 + + colormap can be a keyword of a pre-defined colormap or a set of lines defining the value and the color components. + - 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)) + + Valid pre-defined colormap keyword: + + + + + + grayscale or greyscale for a one 8BUI band raster of shades of gray. + + + + + pseudocolor for a four 8BUI (RGBA) band raster with colors going from blue to green to red. + + + + + fire for a four 8BUI (RGBA) band raster with colors going from black to red to pale yellow. + + + + + bluered for a four 8BUI (RGBA) band raster with colors going from blue to pale white to red. + + + + + + Users can pass a set of entries (one per line) to colormap to specify custom colormaps. Each entry generally consists of five values: the pixel value and corresponding Red, Green, Blue, Alpha components (color components between 0 and 255). Percent values can be used instead of pixel values where 0% and 100% are the minimum and maximum values found in the raster band. Values can be separated with commas (','), tabs, colons (':') and/or spaces. The pixel value can be set to nv, null or nodata for the NODATA value. An example is provided below. + + + +5 0 0 0 255 +4 100:50 55 255 +1 150,100 150 255 +0% 255 255 255 255 +nv 0 0 0 0 - - - - See Also + - , - , - , - + The syntax of colormap is similar to that of the color-relief mode of GDAL gdaldem. - - - - - 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 . + + Valid keywords for method: + + + + + + INTERPOLATE to use linear interpolation to smoothly blend the colors between the given pixel values + + + + + EXACT to strictly match only those pixels values found in the colormap. Pixels whose value does not match a colormap entry will be set to 0 0 0 0 (RGBA) + + + + + NEAREST to use the colormap entry whose value is closest to the pixel value + + + + - This is different than ST_PixelAsPolygons where one geometry is returned for each pixel regardless of pixel value. + A great reference for colormaps is ColorBrewer. - - - - Examples - 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; + The resulting bands of new raster will have no nodata value set. To get back nodatavalue suitable for overlay with other rasters, + apply a operation. + + Availability: 2.1.0 + - 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 - , , , - - - - - - ST_Envelope - Returns the polygon representation of the extent of the raster. - - - - - - geometry ST_Envelope - raster rast - - - - - 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)) - - - - Examples - - SELECT rid, ST_AsText(ST_Envelope(rast)) As envgeomwkt -FROM dummy_rast; + Examples + This is a junk table to play with + +-- setup test raster table -- +DROP TABLE IF EXISTS funky_shapes; +CREATE TABLE funky_shapes(rast raster); +INSERT INTO funky_shapes(rast) +WITH ref As ( + SELECT ST_MakeEmptyRaster( 200, 200, 0, 200, 1, -1, 0, 0) As rast + ) +SELECT ST_Union(rast) +FROM (SELECT + ST_AsRaster( + ST_Rotate(ST_Buffer( + ST_GeomFromText('LINESTRING(0 2,50 50,150 150,125 50)'), i*2 + ), pi()*i*0.125, ST_Point(50,50)) + , ref.rast, '8BUI'::text, i*5) As rast + FROM ref cross JOIN generate_series(1,10,3) As i ) As shapes ; +SELECT ST_NumBands(rast) As n_orig + , ST_NumBands(ST_ColorMap(rast,1, 'greyscale')) As ngrey + , ST_NumBands(ST_ColorMap(rast,1, 'pseudocolor')) As npseudo + , ST_NumBands(ST_ColorMap(rast,1, 'fire')) As nfire + , ST_NumBands(ST_ColorMap(rast,1, 'bluered')) As nbluered + , ST_NumBands(ST_ColorMap(rast,1, '100% 255 0 0 +80% 160 0 0 +50% 130 0 0 +30% 30 0 0 +20% 60 0 0 +0% 0 0 0 +nv 255 255 255')) As nred +FROM funky_shapes; + + n_orig | ngrey | npseudo | nfire | nbluered | nred +--------+-------+---------+-------+----------+------ + 1 | 1 | 4 | 4 | 4 | 3 + + + Examples: Compare different color map looks using ST_AsPNG + SELECT ST_AsPNG(rast) As orig_png + , ST_AsPNG(ST_ColorMap(rast,1,'greyscale')) As grey_png + , ST_AsPNG(ST_ColorMap(rast,1, 'pseudocolor')) As pseudo_png + , ST_AsPNG(ST_ColorMap(rast,1, 'nfire')) As fire_png + , ST_AsPNG(ST_ColorMap(rast,1, 'bluered')) As bluered_png + , ST_AsPNG(ST_ColorMap(rast,1, '100% 255 0 0 +80% 160 0 0 +50% 130 0 0 +30% 30 0 0 +20% 60 0 0 +0% 0 0 0 +nv 255 255 255')) As red_png +FROM funky_shapes; - 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)) - - + + + + + + + + + + orig_png + + + + + + + + + grey_png + + + + + + + + + pseudo_png + + + + + + + + + + + fire_png + + + + + + + + + bluered_png + + + + + + + + + red_png + + + + + + + See Also - , , + + , + + , + , + , + , + + - - + + - ST_HillShade - Returns the hypothetical illumination of an elevation raster band using provided azimuth, altitude, brightness and scale inputs. + 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. + - 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 - - - - 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 + geometry ST_ConvexHull + raster rast @@ -8227,141 +8328,131 @@ FROM dummy_rast; Description - 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. - - - - - For more information about Hillshade, please refer to How hillshade works. - + 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. - - 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 - -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}}") -(1 row) - - - - - Examples: Variant 2 - - Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher. - + Examples + Refer to PostGIS Raster Specification for a diagram of this. -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; +-- 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 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 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; + + 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 + , , , + + - + - ST_Aspect - Returns the aspect (in degrees by default) of an elevation raster band. Useful for analyzing terrain. + ST_Envelope + Returns the polygon representation of the extent of the raster. + - 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 + geometry ST_Envelope + raster rast @@ -8369,137 +8460,64 @@ GROUP BY t1.rast; Description - Returns the aspect (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the aspect equation to neighboring pixels. - - - units indicates the units of the aspect. Possible values are: RADIANS, DEGREES (default). - - - - 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 - + 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)) + - - 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 - - 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. + + Examples + + SELECT rid, ST_AsText(ST_Envelope(rast)) As envgeomwkt +FROM dummy_rast; - -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; + 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)) + See Also - - , - , - , - , - , - - + , , - + - ST_Slope - Returns the slope (in degrees by default) of an elevation raster band. Useful for analyzing terrain. + ST_HillShade + Returns the hypothetical illumination of an elevation raster band using provided azimuth, altitude, brightness and scale inputs. - raster ST_Slope + raster ST_HillShade raster rast - integer nband=1 + integer band=1 text pixeltype=32BF - text units=DEGREES + double precision azimuth=315 + double precision altitude=45 + double precision max_bright=255 double precision scale=1.0 boolean interpolate_nodata=FALSE - raster ST_Slope + raster ST_HillShade raster rast - integer nband + integer band raster customextent text pixeltype=32BF - text units=DEGREES + double precision azimuth=315 + double precision altitude=45 + double precision max_bright=255 double precision scale=1.0 boolean interpolate_nodata=FALSE @@ -8509,10 +8527,18 @@ GROUP BY t1.rast; Description - Returns the slope (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the slope equation to neighboring pixels. + 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. - units indicates the units of the slope. Possible values are: RADIANS, DEGREES (default), PERCENT. + 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. @@ -8520,19 +8546,19 @@ GROUP BY t1.rast; - If interpolate_nodata is TRUE, values for NODATA pixels from the input raster will be interpolated using before computing the surface slope. + If interpolate_nodata is TRUE, values for NODATA pixels from the input raster will be interpolated using before computing the hillshade illumination. - For more information about Slope, Aspect and Hillshade, please refer to ESRI - How hillshade works and ERDAS Field Guide - Slope Images. + 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 units, scale, interpolate_nodata function parameters - Changed: 2.1.0 In prior versions, return values were in radians. Now, return values default to degrees - + 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 + @@ -8551,21 +8577,19 @@ WITH foo AS ( ) AS rast ) SELECT - ST_DumpValues(ST_Slope(rast, 1, '32BF')) + ST_DumpValues(ST_Hillshade(rast, 1, '32BF')) FROM foo - st_dumpvalues - ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + 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,"{{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 @@ -8593,7 +8617,7 @@ WITH foo AS ( ) SELECT t1.rast, - ST_Slope(ST_Union(t2.rast), 1, 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) @@ -8608,157 +8632,9 @@ GROUP BY t1.rast; , , , - , - - - - - - - - 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 - - - - - - Description - - 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 - --- needs examples - - - - - See Also - - , - , - , - , - , - - - - - - - - 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 - - - - Examples - --- needs examples - - - - - See Also - - , - , - , - , - , - - - - - - - - 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. + , + - - - This function only supports a focalmean radius of one. - - - Availability: 2.1.0 - - - - Examples - --- needs examples - - - - - See Also - - , - , - , - , - , - - @@ -8893,7 +8769,7 @@ WHERE A.rid =2 ) As foo; , , , , - + ST_MapAlgebra @@ -10567,8 +10443,94 @@ SELECT ST_MapAlgebraFctNgb(rast, 1, '8BUI', 4,4, See Also - , , - + , , + + + + + + ST_MinConvexHull + + Return the convex hull geometry of the raster excluding NODATA pixels. + + + + + + geometry ST_MinConvexHull + raster rast + integer nband=NULL + + + + + + Description + + + Return the convex hull geometry of the raster excluding NODATA pixels. If nband is NULL, all bands of the raster are considered. + + + Availability: 2.1.0 + + + + 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 + + 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 + + , + , + , + + + @@ -10774,30 +10736,256 @@ UPDATE wind - + + + 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 + + + + Examples + +-- needs examples + + + + + 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 + + + + 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. + + + units indicates the units of the slope. Possible values are: RADIANS, DEGREES (default), PERCENT. + + + + 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: 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_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_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 + + + + + + Description + + 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 + +-- needs examples + + + + + See Also + + , + , + , + , + , + + + + + + + - ST_ColorMap - Creates a new raster of up to four 8BUI bands (grayscale, RGB, RGBA) from the source raster and a specified band. Band 1 is assumed if not specified. + ST_TRI + Returns a raster with the calculated Terrain Ruggedness Index. - - - - - raster ST_ColorMap - raster rast - integer nband=1 - text colormap=grayscale - text method=INTERPOLATE - - + - - raster ST_ColorMap + + raster ST_TRI raster rast - text colormap - text method=INTERPOLATE - + integer nband + raster customextent + text pixeltype="32BF" + boolean interpolate_nodata=FALSE + @@ -10805,223 +10993,37 @@ UPDATE wind Description - Apply a colormap to the band at nband of rast resulting a new raster comprised of up to four 8BUI bands. The number of 8BUI bands in the new raster is determined by the number of color components defined in colormap. - - If nband is not specified, then band 1 is assumed. - - - colormap can be a keyword of a pre-defined colormap or a set of lines defining the value and the color components. - - - - Valid pre-defined colormap keyword: - - - - - - grayscale or greyscale for a one 8BUI band raster of shades of gray. - - - - - pseudocolor for a four 8BUI (RGBA) band raster with colors going from blue to green to red. - - - - - fire for a four 8BUI (RGBA) band raster with colors going from black to red to pale yellow. - - - - - bluered for a four 8BUI (RGBA) band raster with colors going from blue to pale white to red. - - - - - - Users can pass a set of entries (one per line) to colormap to specify custom colormaps. Each entry generally consists of five values: the pixel value and corresponding Red, Green, Blue, Alpha components (color components between 0 and 255). Percent values can be used instead of pixel values where 0% and 100% are the minimum and maximum values found in the raster band. Values can be separated with commas (','), tabs, colons (':') and/or spaces. The pixel value can be set to nv, null or nodata for the NODATA value. An example is provided below. - - - -5 0 0 0 255 -4 100:50 55 255 -1 150,100 150 255 -0% 255 255 255 255 -nv 0 0 0 0 - - - - The syntax of colormap is similar to that of the color-relief mode of GDAL gdaldem. - - - - Valid keywords for method: + Terrain Ruggedness Index is calculated by comparing a central pixel with its neighbors, taking the absolute values of the differences, and averaging the result. - - - - INTERPOLATE to use linear interpolation to smoothly blend the colors between the given pixel values - - - - - EXACT to strictly match only those pixels values found in the colormap. Pixels whose value does not match a colormap entry will be set to 0 0 0 0 (RGBA) - - - - - NEAREST to use the colormap entry whose value is closest to the pixel value - - - - - - A great reference for colormaps is ColorBrewer. - + This function only supports a focalmean radius of one. - The resulting bands of new raster will have no nodata value set. To get back nodatavalue suitable for overlay with other rasters, - apply a operation. - Availability: 2.1.0 + Availability: 2.1.0 Examples - This is a junk table to play with --- setup test raster table -- -DROP TABLE IF EXISTS funky_shapes; -CREATE TABLE funky_shapes(rast raster); -INSERT INTO funky_shapes(rast) -WITH ref As ( - SELECT ST_MakeEmptyRaster( 200, 200, 0, 200, 1, -1, 0, 0) As rast - ) -SELECT ST_Union(rast) -FROM (SELECT - ST_AsRaster( - ST_Rotate(ST_Buffer( - ST_GeomFromText('LINESTRING(0 2,50 50,150 150,125 50)'), i*2 - ), pi()*i*0.125, ST_Point(50,50)) - , ref.rast, '8BUI'::text, i*5) As rast - FROM ref cross JOIN generate_series(1,10,3) As i ) As shapes ; -SELECT ST_NumBands(rast) As n_orig - , ST_NumBands(ST_ColorMap(rast,1, 'greyscale')) As ngrey - , ST_NumBands(ST_ColorMap(rast,1, 'pseudocolor')) As npseudo - , ST_NumBands(ST_ColorMap(rast,1, 'fire')) As nfire - , ST_NumBands(ST_ColorMap(rast,1, 'bluered')) As nbluered - , ST_NumBands(ST_ColorMap(rast,1, '100% 255 0 0 -80% 160 0 0 -50% 130 0 0 -30% 30 0 0 -20% 60 0 0 -0% 0 0 0 -nv 255 255 255')) As nred -FROM funky_shapes; - - n_orig | ngrey | npseudo | nfire | nbluered | nred ---------+-------+---------+-------+----------+------ - 1 | 1 | 4 | 4 | 4 | 3 - - - Examples: Compare different color map looks using ST_AsPNG - SELECT ST_AsPNG(rast) As orig_png - , ST_AsPNG(ST_ColorMap(rast,1,'greyscale')) As grey_png - , ST_AsPNG(ST_ColorMap(rast,1, 'pseudocolor')) As pseudo_png - , ST_AsPNG(ST_ColorMap(rast,1, 'nfire')) As fire_png - , ST_AsPNG(ST_ColorMap(rast,1, 'bluered')) As bluered_png - , ST_AsPNG(ST_ColorMap(rast,1, '100% 255 0 0 -80% 160 0 0 -50% 130 0 0 -30% 30 0 0 -20% 60 0 0 -0% 0 0 0 -nv 255 255 255')) As red_png -FROM funky_shapes; - - - - - - - - - - - orig_png - - - - - - - - - grey_png - - - - - - - - - pseudo_png - - - - - - - - - - - fire_png - - - - - - - - - bluered_png - - - - - - - - - red_png - - - - - - - - +-- needs examples + + See Also - - , - - , - , - , - , - - + + , + , + , + , + , + + + ST_Union