From: Bborie Park Date: Tue, 14 May 2013 18:52:09 +0000 (+0000) Subject: Reorganized the entire Raster Processing section. Lets see if this makes X-Git-Tag: 2.1.0beta3~62 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=b734dc2da1bf14a83ea00b801b39c440824312fc;p=postgis Reorganized the entire Raster Processing section. Lets see if this makes things easier to find... or not. git-svn-id: http://svn.osgeo.org/postgis/trunk@11462 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml index a905d96d2..8e21c2b37 100644 --- a/doc/reference_raster.xml +++ b/doc/reference_raster.xml @@ -7612,287 +7612,107 @@ FROM dummy_rast WHERE rid=2; Raster Processing - - - Box3D - Returns the box 3d representation of the enclosing box of the raster. - - - - - - box3d Box3D - raster rast - - - - - - Description - - Returns the box representing the extent of the raster. - The polygon is defined by the corner points of the bounding box - ((MINX, MINY), - (MAXX, MAXY)) - - 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 - - - - - - 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 - + + Map Algebra + + + + ST_Clip + Returns the raster clipped by the input geometry. If band number not is specified, all bands are processed. If crop is not specified or TRUE, the output raster is cropped. + + + + + + + raster ST_Clip + raster rast + integer[] nband + geometry geom + double precision[] nodataval=NULL + boolean crop=TRUE + + + + raster ST_Clip + raster rast + integer nband + geometry geom + double precision nodataval + boolean crop=TRUE + + + + raster ST_Clip + raster rast + integer nband + geometry geom + boolean crop + + + + raster ST_Clip + raster rast + geometry geom + double precision[] nodataval=NULL + boolean crop=TRUE + + + + raster ST_Clip + raster rast + geometry geom + double precision nodataval + boolean crop=TRUE + + + + raster ST_Clip + raster rast + geometry geom + boolean crop + + + + - - 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. - - - 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. + Returns a raster that is clipped by the input geometry geom. If band index is not specified, all bands are processed. - - - 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 - Returns the raster clipped by the input geometry. If band number not is specified, all bands are processed. If crop is not specified or TRUE, the output raster is cropped. - - - - - - - raster ST_Clip - raster rast - integer[] nband - geometry geom - double precision[] nodataval=NULL - boolean crop=TRUE - - - - raster ST_Clip - raster rast - integer nband - geometry geom - double precision nodataval - boolean crop=TRUE - - - - raster ST_Clip - raster rast - integer nband - geometry geom - boolean crop - - - - raster ST_Clip - raster rast - geometry geom - double precision[] nodataval=NULL - boolean crop=TRUE - - - - raster ST_Clip - raster rast - geometry geom - double precision nodataval - boolean crop=TRUE - - - - raster ST_Clip - raster rast - geometry geom - boolean crop - - - - - - - Description - - - Returns a raster that is clipped by the input geometry geom. If band index is not specified, all bands are processed. - - - Rasters resulting from ST_Clip must have a nodata value assigned for areas clipped, one for each band. If none are provided and the input raster do not have a nodata value defined, nodata values of the resulting raster are set to ST_MinPossibleValue(ST_BandPixelType(rast, band)). When the number of nodata value in the array is smaller than the number of band, the last one in the array is used for the remaining bands. If the number of nodata value is greater than the number of band, the extra nodata values are ignored. All variants accepting an array of nodata values also accept a single value which will be assigned to each band. - + + Rasters resulting from ST_Clip must have a nodata value assigned for areas clipped, one for each band. If none are provided and the input raster do not have a nodata value defined, nodata values of the resulting raster are set to ST_MinPossibleValue(ST_BandPixelType(rast, band)). When the number of nodata value in the array is smaller than the number of band, the last one in the array is used for the remaining bands. If the number of nodata value is greater than the number of band, the extra nodata values are ignored. All variants accepting an array of nodata values also accept a single value which will be assigned to each band. + - - If crop is not specified, true is assumed meaning the output raster is cropped to the intersection of the geomand rast extents. If crop is set to false, the new raster gets the same extent as rast. - + + If crop is not specified, true is assumed meaning the output raster is cropped to the intersection of the geomand rast extents. If crop is set to false, the new raster gets the same extent as rast. + - Availability: 2.0.0 + Availability: 2.0.0 - Enhanced: 2.1.0 Rewritten in C + Enhanced: 2.1.0 Rewritten in C - - Examples here use Massachusetts aerial data available on MassGIS site MassGIS Aerial Orthos. Coordinates are in Massachusetts State Plane Meters. - - + + Examples here use Massachusetts aerial data available on MassGIS site MassGIS Aerial Orthos. Coordinates are in Massachusetts State Plane Meters. + + - - Examples: 1 band clipping + + Examples: 1 band clipping - + -- Clip the first band of an aerial tile by a 20 meter buffer. SELECT ST_Clip(rast, 1, ST_Buffer(ST_Centroid(ST_Envelope(rast)),20) ) from aerials.boston WHERE rid = 4; - + - + -- Demonstrate effect of crop on final dimensions of raster -- Note how final extent is clipped to that of the geometry -- if crop = true @@ -7907,100 +7727,100 @@ WHERE rid = 6) As foo; xmax_w_trim | xmax_clipper | xmax_wo_trim | xmax_rast_orig ------------------+------------------+------------------+------------------ 230657.436173996 | 230657.436173996 | 230666.436173996 | 230666.436173996 - + - - - - - - - - - - - - - Full raster tile before clipping - - - - - - - - - - - - - - After Clipping - - - - - - - - - - - - - Examples: 1 band clipping with no crop and add back other bands unchanged + + + + + + + + + + + + + Full raster tile before clipping + + + + + + + + + + + + + + After Clipping + + + + + + + + + + - + + Examples: 1 band clipping with no crop and add back other bands unchanged + + -- Same example as before, but we need to set crop to false to be able to use ST_AddBand -- because ST_AddBand requires all bands be the same Width and height SELECT ST_AddBand(ST_Clip(rast, 1, ST_Buffer(ST_Centroid(ST_Envelope(rast)),20),false ), ARRAY[ST_Band(rast,2),ST_Band(rast,3)] ) from aerials.boston WHERE rid = 6; - + - - - - - - - - - - - - - Full raster tile before clipping - - - - - - - - - - - - - - After Clipping - surreal - - - - - - - - - - - - - Examples: Clip all bands + + + + + + + + + + + + + Full raster tile before clipping + + + + + + + + + + + + + + After Clipping - surreal + + + + + + + + + + - + + Examples: Clip all bands + + -- Clip all bands of an aerial tile by a 20 meter buffer. -- Only difference is we don't specify a specific band to clip -- so all bands are clipped @@ -8009,981 +7829,777 @@ SELECT ST_Clip(rast, false ) from aerials.boston WHERE rid = 4; - + - - - - - - - - - - - - - Full raster tile before clipping - - - - - - - - - - - - - - After Clipping - - - - - - - - - - + + + + + + + + + + + + + Full raster tile before clipping + + + + + + + + + + + + + + After Clipping + + + + + + + + + + - - - 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. - - - - - - raster ST_ColorMap - raster rast - integer nband=1 - text colormap=grayscale - text method=INTERPOLATE - - + + + 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. + + + + + + raster ST_ColorMap + raster rast + integer nband=1 + text colormap=grayscale + text method=INTERPOLATE + + + + + + raster ST_ColorMap + raster rast + text colormap + text method=INTERPOLATE + + + - - - raster ST_ColorMap - raster rast - text colormap - text method=INTERPOLATE - - - + + Description - - 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. + - - 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. + 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. - + + 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: - + + 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. - - - + + + + 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. - + + 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. - + + The syntax of colormap is similar to that of the color-relief mode of GDAL gdaldem. + - - Valid keywords for method: - + + Valid keywords for method: + - - - - INTERPOLATE to use linear interpolation to smoothly blend the colors between the given pixel values - - - + + + + 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 + + + + + - 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) + A great reference for colormaps is ColorBrewer. - - + + - NEAREST to use the colormap entry whose value is closest to the pixel value + The resulting bands of new raster will have no NODATA value set. Use to set a NODATA value if one is needed. - - + - - - A great reference for colormaps is ColorBrewer. - - - - - The resulting bands of new raster will have no NODATA value set. Use to set a NODATA value if one is needed. - - + Availability: 2.1.0 + - Availability: 2.1.0 - + + Examples + This is a junk table to play with - - 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; - +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 - - - - - - - - + + 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; + - - See Also - - , - - , - , - , - , - - - - + + + + + + + + + + + + + orig_png + + + + + + + + + + + + + + grey_png + + + + + + + + + + + + + + pseudo_png + + + + + + + + + + + + + + + + fire_png + + + + + + + + + + + + + + bluered_png + + + + + + + + + + + + + + red_png + + + + + + + + + + - - - 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 - - - + + See Also + + , + + , + , + , + , + + + + + + + + ST_Intersection + Returns a raster or a set of geometry-pixelvalue pairs representing the shared portion of two rasters or the geometrical intersection of a vectorization of the raster and a geometry. + + + + + + setof geomval ST_Intersection + geometry geom + raster rast + integer band_num=1 + + + + setof geomval ST_Intersection + raster rast + geometry geom + + + + setof geomval ST_Intersection + raster rast + integer band_num + geometry geom + + + + raster ST_Intersection + raster rast1 + raster rast2 + double precision[] nodataval + + + + raster ST_Intersection + raster rast1 + raster rast2 + text returnband='BOTH' + double precision[] nodataval=NULL + + + + raster ST_Intersection + raster rast1 + integer band_num1 + raster rast2 + integer band_num2 + double precision[] nodataval + + + + raster ST_Intersection + raster rast1 + integer band_num1 + raster rast2 + integer band_num2 + text returnband='BOTH' + double precision[] nodataval=NULL + + + + - - Description + + Description + + Returns a raster or a set of geometry-pixelvalue pairs representing the shared portion of two rasters or the geometrical intersection of a vectorization of the raster and a geometry. + + + + The first three variants, returning a setof geomval, works in vector space. The raster is first vectorized (using ST_DumpAsPolygon) into a set of geomval rows and those rows are then intersected with the geometry using the ST_Intersection(geometry, geometry) PostGIS function. Geometries intersecting only with a nodata value area of a raster returns an empty geometry. They are normally excluded from the results by the proper usage of ST_Intersect in the WHERE clause. + - 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. + + You can access the geometry and the value parts of the resulting set of geomval by surrounding them with parenthesis and adding '.geom' or '.val' at the end of the expression. e.g. (ST_Intersection(rast, geom)).geom + - 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. - - + + The other variants, returning a raster, works in raster space. They are using the two rasters version of ST_MapAlgebraExpr to perform the intersection. + - - 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 - - , - , - , - - - - + + The extent of the resulting raster corresponds to the geometrical intersection of the two raster extents. The resulting raster includes 'BAND1', 'BAND2' or 'BOTH' bands, following what is passed as the returnband parameter. Nodata value areas present in any band results in nodata value areas in every bands of the result. In other words, any pixel intersecting with a nodata value pixel becomes a nodata value pixel in the result. + + + + Rasters resulting from ST_Intersection must have a nodata value assigned for areas not intersecting. You can define or replace the nodata value for any resulting band by providing a nodataval[] array of one or two nodata values depending if you request 'BAND1', 'BAND2' or 'BOTH' bands. The first value in the array replace the nodata value in the first band and the second value replace the nodata value in the second band. If one input band do not have a nodata value defined and none are provided as an array, one is chosen using the ST_MinPossibleValue function. All variant accepting an array of nodata value can also accept a single value which will be assigned to each requested band. + - - - 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. + In all variants, if no band number is specified band 1 is assumed. - - - - - Examples - SELECT val, ST_AsText(geom) As geomwkt + + + + To get more control on the resulting extent or on what to return when encountering a nodata value, use the two rasters version of . + + + + + + To compute the intersection of a raster band with a geometry in raster space, use . ST_Clip works on multiple bands rasters and does not return a band corresponding to the rasterized geometry. + + + + + + ST_Intersection should be used in conjunction with ST_Intersects and an index on the raster column and/or the geometry column. + + + + + Enhanced: 2.0.0 - Intersection in the raster space was introduced. In earlier pre-2.0.0 versions, only intersection performed in vector space were supported. + + + + + Examples: Geometry, Raster -- resulting in geometry vals + + +SELECT + foo.rid, + foo.gid, + ST_AsText((foo.geomval).geom) As geomwkt, + (foo.geomval).val FROM ( -SELECT (ST_DumpAsPolygons(rast)).* -FROM dummy_rast -WHERE rid = 2 -) As foo -WHERE val BETWEEN 249 and 251 -ORDER BY val; + SELECT + A.rid, + g.gid, + ST_Intersection(A.rast, g.geom) As geomval + FROM dummy_rast AS A + CROSS JOIN ( + VALUES + (1, ST_Point(3427928, 5793243.85) ), + (2, ST_GeomFromText('LINESTRING(3427927.85 5793243.75,3427927.8 5793243.75,3427927.8 5793243.8)')), + (3, ST_GeomFromText('LINESTRING(1 2, 3 4)')) + ) As g(gid,geom) + WHERE A.rid = 2 +) As 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)) - - - - 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)) + rid | gid | geomwkt | val +-----+-----+--------------------------------------------------------------------------------------------- + 2 | 1 | POINT(3427928 5793243.85) | 249 + 2 | 1 | POINT(3427928 5793243.85) | 253 + 2 | 2 | POINT(3427927.85 5793243.75) | 254 + 2 | 2 | POINT(3427927.8 5793243.8) | 251 + 2 | 2 | POINT(3427927.8 5793243.8) | 253 + 2 | 2 | LINESTRING(3427927.8 5793243.75,3427927.8 5793243.8) | 252 + 2 | 2 | MULTILINESTRING((3427927.8 5793243.8,3427927.8 5793243.75),...) | 250 + 2 | 3 | GEOMETRYCOLLECTION EMPTY + - + - Examples - - SELECT rid, ST_AsText(ST_Envelope(rast)) As envgeomwkt -FROM dummy_rast; + Example: Raster, Geometry -- resulting is a raster + Examples coming soon + + - 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_MapAlgebra + + Callback function version - Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function. + + + + + + + + raster ST_MapAlgebra + rastbandarg[] rastbandargset + regprocedure callbackfunc + text pixeltype=NULL + text extenttype=INTERSECTION + raster customextent=NULL + integer distancex=0 + integer distancey=0 + text[] VARIADIC userargs=NULL + + + + raster ST_MapAlgebra + raster rast + integer[] nband + regprocedure callbackfunc + text pixeltype=NULL + text extenttype=FIRST + raster customextent=NULL + integer distancex=0 + integer distancey=0 + text[] VARIADIC userargs=NULL + + + + raster ST_MapAlgebra + raster rast + integer nband + regprocedure callbackfunc + text pixeltype=NULL + text extenttype=FIRST + raster customextent=NULL + integer distancex=0 + integer distancey=0 + text[] VARIADIC userargs=NULL + + + + raster ST_MapAlgebra + raster rast1 + integer nband1 + raster rast2 + integer nband2 + regprocedure callbackfunc + text pixeltype=NULL + text extenttype=INTERSECTION + raster customextent=NULL + integer distancex=0 + integer distancey=0 + text[] VARIADIC userargs=NULL + + + + - - See Also - , , - - - - - - 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 - + + Description - - 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 - - - - - - Description + + Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function. + - 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. + + + rast,rast1,rast2, rastbandargset + + + Rasters on which the map algebra process is evaluated.rastbandargset allows the use of a map algebra operation on many rasters and/or many bands. See example Variant 1. + + + + + nband, nband1, nband2 + + + Band numbers of the raster to be evaluated. nband can be an integer or integer[] denoting the bands. nband1 is band on rast1 and nband2 is band on rast2 for hte 2 raster/2band case. + + + + + callbackfunc + + + The callbackfunc parameter must be the name and signature of an SQL or PL/pgSQL function, cast to a regprocedure. An example PL/pgSQL function example is: + +CREATE OR REPLACE FUNCTION sample_callbackfunc(value double precision[][][], position integer[][], VARIADIC userargs text[]) + RETURNS double precision + AS $$ + BEGIN + RETURN 0; + END; + $$ LANGUAGE 'plpgsql' IMMUTABLE; + - - azimuth is a value between 0 and 360 degrees measured clockwise from North. - + The callbackfunc must have three arguments: a 3-dimension double precision array, a 2-dimension integer array and a variadic 1-dimension text array. The first argument value is the set of values (as double precision) from all input rasters. The three dimensions (where indexes are 1-based) are: raster #, row y, column x. The second argument position is the set of pixel positions from the output raster and input rasters. The outer dimension (where indexes are 0-based) is the raster #. The position at outer dimension index 0 is the output raster's pixel position. For each outer dimension, there are two elements in the inner dimension for X and Y. The third argument userargs is for passing through any user-specified arguments. + - - altitude is a value between 0 and 90 degrees where 0 degrees is at the horizon and 90 degrees is directly overhead. - + + Passing a regprocedure argument to a SQL function requires the full function signature to be passed, then cast to a regprocedure type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is: - - max_bright is a value between 0 and 255 with 0 as no brightness and 255 as max brightness. - + +'sample_callbackfunc(double precision[], integer[], text[])'::regprocedure + - - scale is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120. - + Note that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a regprocedure. + - - If interpolate_nodata is TRUE, values for NODATA pixels from the input raster will be interpolated using before computing the hillshade illumination. - + + + + + pixeltype + + + If pixeltype is passed in, the one band of the new raster will be of that pixeltype. If pixeltype is passed NULL or left out, the new raster band will have the same pixeltype as the specified band of the first raster (for extent types: INTERSECTION, UNION, FIRST, CUSTOM) or the specified band of the appropriate raster (for extent types: SECOND, LAST). If in doubt, always specify pixeltype. + + + The resulting pixel type of the output raster must be one listed in or left out or set to NULL. + + + + + + extenttype + + + Possible values are INTERSECTION (default), UNION, FIRST (default for one raster variants), SECOND, LAST, CUSTOM. + + + + + + customextent + + + If extentype is CUSTOM, a raster must be provided for customextent. See example 4 of Variant 1. + + + + + + distancex + + + The distance in pixels from the reference cell. So width of resulting matrix would be 2*distancex + 1.If not specified only the reference cell is considered (neighborhood of 0). + + + + + + distancey + + + The distance in pixels from reference cell in y direction. Height of resulting matrix would be 2*distancey + 1 .If not specified only the reference cell is considered (neighborhood of 0). + + + + + + userargs + + + The third argument to the callbackfunc is a variadic text array. All trailing text arguments are passed through to the specified callbackfunc, and are contained in the userargs argument. + + + + + + + + For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of Query Language (SQL) Functions. + + + + + + The text[] argument to the callbackfunc is required, regardless of whether you choose to pass any arguments to the callback function for processing or not. + + - - For more information about Hillshade, please refer to How hillshade works. + Variant 1 accepts an array of rastbandarg allowing the use of a map algebra operation on many rasters and/or many bands. See example Variant 1. - - 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 + + Variants 2 and 3 operate upon one or more bands of one raster. See example Variant 2 and 3. + - - - - Examples: Variant 1 - + + Variant 4 operate upon two rasters with one band per raster. See example Variant 4. + + + Availability: 2.1.0 + + + + + Examples: Variant 1 + + One raster, one band + 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[][] + SELECT 1 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast +) +SELECT + ST_MapAlgebra( + ARRAY[ROW(rast, 1)]::rastbandarg[], + 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure ) AS rast +FROM foo + + + One raster, several bands + +WITH foo AS ( + SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast ) SELECT - ST_DumpValues(ST_Hillshade(rast, 1, '32BF')) + ST_MapAlgebra( + ARRAY[ROW(rast, 3), ROW(rast, 1), ROW(rast, 3), ROW(rast, 2)]::rastbandarg[], + 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure + ) AS rast 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. - - -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_Intersection - Returns a raster or a set of geometry-pixelvalue pairs representing the shared portion of two rasters or the geometrical intersection of a vectorization of the raster and a geometry. - - - - - - setof geomval ST_Intersection - geometry geom - raster rast - integer band_num=1 - - - - setof geomval ST_Intersection - raster rast - geometry geom - - - - setof geomval ST_Intersection - raster rast - integer band_num - geometry geom - - - - raster ST_Intersection - raster rast1 - raster rast2 - double precision[] nodataval - - - - raster ST_Intersection - raster rast1 - raster rast2 - text returnband='BOTH' - double precision[] nodataval=NULL - - - - raster ST_Intersection - raster rast1 - integer band_num1 - raster rast2 - integer band_num2 - double precision[] nodataval - - - - raster ST_Intersection - raster rast1 - integer band_num1 - raster rast2 - integer band_num2 - text returnband='BOTH' - double precision[] nodataval=NULL - - - - - - - Description - Returns a raster or a set of geometry-pixelvalue pairs representing the shared portion of two rasters or the geometrical intersection of a vectorization of the raster and a geometry. - - The first three variants, returning a setof geomval, works in vector space. The raster is first vectorized (using ST_DumpAsPolygon) into a set of geomval rows and those rows are then intersected with the geometry using the ST_Intersection(geometry, geometry) PostGIS function. Geometries intersecting only with a nodata value area of a raster returns an empty geometry. They are normally excluded from the results by the proper usage of ST_Intersect in the WHERE clause. - - You can access the geometry and the value parts of the resulting set of geomval by surrounding them with parenthesis and adding '.geom' or '.val' at the end of the expression. e.g. (ST_Intersection(rast, geom)).geom - - The other variants, returning a raster, works in raster space. They are using the two rasters version of ST_MapAlgebraExpr to perform the intersection. - - The extent of the resulting raster corresponds to the geometrical intersection of the two raster extents. The resulting raster includes 'BAND1', 'BAND2' or 'BOTH' bands, following what is passed as the returnband parameter. Nodata value areas present in any band results in nodata value areas in every bands of the result. In other words, any pixel intersecting with a nodata value pixel becomes a nodata value pixel in the result. - - Rasters resulting from ST_Intersection must have a nodata value assigned for areas not intersecting. You can define or replace the nodata value for any resulting band by providing a nodataval[] array of one or two nodata values depending if you request 'BAND1', 'BAND2' or 'BOTH' bands. The first value in the array replace the nodata value in the first band and the second value replace the nodata value in the second band. If one input band do not have a nodata value defined and none are provided as an array, one is chosen using the ST_MinPossibleValue function. All variant accepting an array of nodata value can also accept a single value which will be assigned to each requested band. - - In all variants, if no band number is specified band 1 is assumed. - - To get more control on the resulting extent or on what to return when encountering a nodata value, use the two rasters version of . - - To compute the intersection of a raster band with a geometry in raster space, use . ST_Clip works on multiple bands rasters and does not return a band corresponding to the rasterized geometry. - - ST_Intersection should be used in conjunction with ST_Intersects and an index on the raster column and/or the geometry column. - - Enhanced: 2.0.0 - Intersection in the raster space was introduced. In earlier pre-2.0.0 versions, only intersection performed in vector space were supported. - - - - Examples: Geometry, Raster -- resulting in geometry vals - - SELECT foo.rid, foo.gid, - ST_AsText((foo.geomval).geom) As geomwkt, (foo.geomval).val -FROM - ( -SELECT A.rid, g.gid , ST_Intersection(A.rast, g.geom) As geomval - FROM dummy_rast AS A CROSS JOIN - (VALUES (1, ST_Point(3427928, 5793243.85) ) , - (2, ST_GeomFromText('LINESTRING(3427927.85 5793243.75,3427927.8 5793243.75,3427927.8 5793243.8)') ), - (3, ST_GeomFromText('LINESTRING(1 2, 3 4)') ) - ) As g(gid,geom) -WHERE A.rid =2 ) As foo; - - rid | gid | geomwkt | val ------+-----+--------------------------------------------------------------------------------------------- - 2 | 1 | POINT(3427928 5793243.85) | 249 - 2 | 1 | POINT(3427928 5793243.85) | 253 - 2 | 2 | POINT(3427927.85 5793243.75) | 254 - 2 | 2 | POINT(3427927.8 5793243.8) | 251 - 2 | 2 | POINT(3427927.8 5793243.8) | 253 - 2 | 2 | LINESTRING(3427927.8 5793243.75,3427927.8 5793243.8) | 252 - 2 | 2 | MULTILINESTRING((3427927.8 5793243.8,3427927.8 5793243.75),...) | 250 - 2 | 3 | GEOMETRYCOLLECTION EMPTY - - - - - - Example: Raster, Geometry -- resulting is a raster - Examples coming soon - - - - - - See Also - , , , , - - - - - - ST_MapAlgebra - - Callback function version - Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function. - - - - - - - - raster ST_MapAlgebra - rastbandarg[] rastbandargset - regprocedure callbackfunc - text pixeltype=NULL - text extenttype=INTERSECTION - raster customextent=NULL - integer distancex=0 - integer distancey=0 - text[] VARIADIC userargs=NULL - - - - raster ST_MapAlgebra - raster rast - integer[] nband - regprocedure callbackfunc - text pixeltype=NULL - text extenttype=FIRST - raster customextent=NULL - integer distancex=0 - integer distancey=0 - text[] VARIADIC userargs=NULL - - - - raster ST_MapAlgebra - raster rast - integer nband - regprocedure callbackfunc - text pixeltype=NULL - text extenttype=FIRST - raster customextent=NULL - integer distancex=0 - integer distancey=0 - text[] VARIADIC userargs=NULL - - - - raster ST_MapAlgebra - raster rast1 - integer nband1 - raster rast2 - integer nband2 - regprocedure callbackfunc - text pixeltype=NULL - text extenttype=INTERSECTION - raster customextent=NULL - integer distancex=0 - integer distancey=0 - text[] VARIADIC userargs=NULL - - - - - - - Description - - - Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function. - - - - - rast,rast1,rast2, rastbandargset - Rasters on which the map algebra process is evaluated.rastbandargset allows the use of a map algebra operation on many rasters and/or many bands. See example Variant 1. - - - nband, nband1, nband2 - Band numbers of the raster to be evaluated. nband can be an integer or integer[] denoting the bands. nband1 is band on rast1 and nband2 is band on rast2 for hte 2 raster/2band case. - - - callbackfunc - - The callbackfunc parameter must be the name and signature of an SQL or PL/pgSQL function, cast to a regprocedure. An example PL/pgSQL function example is: - -CREATE OR REPLACE FUNCTION sample_callbackfunc(value double precision[][][], position integer[][], VARIADIC userargs text[]) - RETURNS double precision - AS $$ - BEGIN - RETURN 0; - END; - $$ LANGUAGE 'plpgsql' IMMUTABLE; - - - The callbackfunc must have three arguments: a 3-dimension double precision array, a 2-dimension integer array and a variadic 1-dimension text array. The first argument value is the set of values (as double precision) from all input rasters. The three dimensions (where indexes are 1-based) are: raster #, row y, column x. The second argument position is the set of pixel positions from the output raster and input rasters. The outer dimension (where indexes are 0-based) is the raster #. The position at outer dimension index 0 is the output raster's pixel position. For each outer dimension, there are two elements in the inner dimension for X and Y. The third argument userargs is for passing through any user-specified arguments. - - - - Passing a regprocedure argument to a SQL function requires the full function signature to be passed, then cast to a regprocedure type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is: - + Several rasters, several bands -'sample_callbackfunc(double precision[], integer[], text[])'::regprocedure - - - Note that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a regprocedure. - - - - - - pixeltype - If pixeltype is passed in, the one band of the new raster will be of that pixeltype. If pixeltype is passed NULL or left out, the new raster band will have the same pixeltype as the specified band of the first raster (for extent types: INTERSECTION, UNION, FIRST, CUSTOM) or the specified band of the appropriate raster (for extent types: SECOND, LAST). If in doubt, always specify pixeltype. - The resulting pixel type of the output raster must be one listed in or left out or set to NULL. - - - - extenttype - - Possible values are INTERSECTION (default), UNION, FIRST (default for one raster variants), SECOND, LAST, CUSTOM. - - - - - customextent - - If extentype is CUSTOM, a raster must be provided for customextent. See example 4 of Variant 1. - - - - distancex - The distance in pixels from the reference cell. So width of resulting matrix would be 2*distancex + 1.If not specified only the reference cell is considered (neighborhood of 0). - - - distancey - The distance in pixels from reference cell in y direction. Height of resulting matrix would be 2*distancey + 1 .If not specified only the reference cell is considered (neighborhood of 0). - - - - userargs - - The third argument to the callbackfunc is a variadic text array. All trailing text arguments are passed through to the specified callbackfunc, and are contained in the userargs argument. - - - - - - - - - - For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of Query Language (SQL) Functions. - - - - - - The text[] argument to the callbackfunc is required, regardless of whether you choose to pass any arguments to the callback function for processing or not. - - - - - - Variant 1 accepts an array of rastbandarg allowing the use of a map algebra operation on many rasters and/or many bands. See example Variant 1. - - - - Variants 2 and 3 operate upon one or more bands of one raster. See example Variant 2 and 3. - - - - Variant 4 operate upon two rasters with one band per raster. See example Variant 4. - - - Availability: 2.1.0 - - - - - Examples: Variant 1 - - One raster, one band - -WITH foo AS ( - SELECT 1 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast -) -SELECT - ST_MapAlgebra( - ARRAY[ROW(rast, 1)]::rastbandarg[], - 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure - ) AS rast -FROM foo - - - One raster, several bands - -WITH foo AS ( - SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast -) -SELECT - ST_MapAlgebra( - ARRAY[ROW(rast, 3), ROW(rast, 1), ROW(rast, 3), ROW(rast, 2)]::rastbandarg[], - 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure - ) AS rast -FROM foo - - - Several rasters, several bands - WITH foo AS ( SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast UNION ALL SELECT 2 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 1, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0), 2, '8BUI', 20, 0), 3, '32BUI', 300, 0) AS rast @@ -8997,10 +8613,10 @@ FROM foo t1 CROSS JOIN foo t2 WHERE t1.rid = 1 AND t2.rid = 2 - + - Complete example of tiles of a coverage with neighborhood. This query only works with PostgreSQL 9.1 or higher. - + Complete example of tiles of a coverage with neighborhood. This query only works with PostgreSQL 9.1 or higher. + WITH foo AS ( SELECT 0 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast UNION ALL SELECT 1, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, 0, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0) AS rast UNION ALL @@ -9029,10 +8645,10 @@ WHERE t1.rid = 4 AND t2.rid BETWEEN 0 AND 8 AND ST_Intersects(t1.rast, t2.rast) GROUP BY t1.rid, t1.rast - + - Example like the prior one for tiles of a coverage with neighborhood but works with PostgreSQL 9.0. - + Example like the prior one for tiles of a coverage with neighborhood but works with PostgreSQL 9.0. + WITH src AS ( SELECT 0 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast UNION ALL SELECT 1, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, 0, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0) AS rast UNION ALL @@ -9076,15 +8692,14 @@ SELECT (ST_BandMetadata(rast, 1)), ST_Value(rast, 1, 1, 1) FROM bar; - - - + + - - Examples: Variants 2 and 3 + + Examples: Variants 2 and 3 - One raster, several bands - + One raster, several bands + WITH foo AS ( SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast ) @@ -9094,10 +8709,10 @@ SELECT 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure ) AS rast FROM foo - + - One raster, one band - + One raster, one band + WITH foo AS ( SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast ) @@ -9107,15 +8722,14 @@ SELECT 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure ) AS rast FROM foo - - - + + - - Examples: Variant 4 + + Examples: Variant 4 - Two rasters, two bands - + Two rasters, two bands + WITH foo AS ( SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast UNION ALL SELECT 2 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 1, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0), 2, '8BUI', 20, 0), 3, '32BUI', 300, 0) AS rast @@ -9130,253 +8744,251 @@ FROM foo t1 CROSS JOIN foo t2 WHERE t1.rid = 1 AND t2.rid = 2 - - - - - - See Also - - - , - , - - - - - - - - - ST_MapAlgebra - - Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions. - - + - - + - - raster ST_MapAlgebra - raster rast - integer nband - text pixeltype - text expression - double precision nodataval=NULL - + + See Also - - raster ST_MapAlgebra - raster rast - text pixeltype - text expression - double precision nodataval=NULL - + + , + , + + + - - raster ST_MapAlgebra - raster rast1 - integer nband1 - raster rast2 - integer nband2 - text expression - text pixeltype=NULL - text extenttype=INTERSECTION - text nodata1expr=NULL - text nodata2expr=NULL - double precision nodatanodataval=NULL - + - - raster ST_MapAlgebra - raster rast1 - raster rast2 - text expression - text pixeltype=NULL - text extenttype=INTERSECTION - text nodata1expr=NULL - text nodata2expr=NULL - double precision nodatanodataval=NULL - + + + ST_MapAlgebra + + Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions. + + - - + + + + + raster ST_MapAlgebra + raster rast + integer nband + text pixeltype + text expression + double precision nodataval=NULL + + + + raster ST_MapAlgebra + raster rast + text pixeltype + text expression + double precision nodataval=NULL + + + + raster ST_MapAlgebra + raster rast1 + integer nband1 + raster rast2 + integer nband2 + text expression + text pixeltype=NULL + text extenttype=INTERSECTION + text nodata1expr=NULL + text nodata2expr=NULL + double precision nodatanodataval=NULL + + + + raster ST_MapAlgebra + raster rast1 + raster rast2 + text expression + text pixeltype=NULL + text extenttype=INTERSECTION + text nodata1expr=NULL + text nodata2expr=NULL + double precision nodatanodataval=NULL + + + + - - Description + + Description - - Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions. - + + Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions. + - Availability: 2.1.0 - + Availability: 2.1.0 + - - Description: Variants 1 and 2 (one raster) + + Description: Variants 1 and 2 (one raster) - - Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the expression on the input raster (rast). If nband is not provided, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band. - + + Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the expression on the input raster (rast). If nband is not provided, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band. + - - If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input rast band. - + + If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input rast band. + - - Keywords permitted for expression - - - [rast] - Pixel value of the pixel of interest - - - [rast.val] - Pixel value of the pixel of interest - - - [rast.x] - 1-based pixel column of the pixel of interest - - - [rast.y] - 1-based pixel row of the pixel of interest + + Keywords permitted for expression + + + [rast] - Pixel value of the pixel of interest + + + [rast.val] - Pixel value of the pixel of interest + + + [rast.x] - 1-based pixel column of the pixel of interest + + + [rast.y] - 1-based pixel row of the pixel of interest + + - - - + - + - - Description: Variants 3 and 4 (two raster) + + Description: Variants 3 and 4 (two raster) - - Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the expression on the two input raster bands rast1, (rast2). If no band1, band2 is specified band 1 is assumed. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the extenttype parameter. - + + Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the expression on the two input raster bands rast1, (rast2). If no band1, band2 is specified band 1 is assumed. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the extenttype parameter. + - - - expression - - - A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer - - - - - pixeltype - - - The resulting pixel type of the output raster. Must be one listed in , left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster. - - - - - extenttype - - - Controls the extent of resulting raster - + + + expression + + + A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer + + + + + pixeltype + + + The resulting pixel type of the output raster. Must be one listed in , left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster. + + + + + extenttype + + + Controls the extent of resulting raster + - - - - INTERSECTION - The extent of the new raster is the intersection of the two rasters. This is the default. - - - - - UNION - The extent of the new raster is the union of the two rasters. - - - - - FIRST - The extent of the new raster is the same as the one of the first raster. - - - - - SECOND - The extent of the new raster is the same as the one of the second raster. - - - - - - - nodata1expr - - - An algebraic expression involving only rast2 or a constant that defines what to return when pixels of rast1 are nodata values and spatially corresponding rast2 pixels have values. - - - - - nodata2expr - - - An algebraic expression involving only rast1 or a constant that defines what to return when pixels of rast2 are nodata values and spatially corresponding rast1 pixels have values. - - - - - nodatanodataval - - - A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values. - - - - - - - Keywords permitted in expression, nodata1expr and nodata2expr - - - [rast1] - Pixel value of the pixel of interest from rast1 - - - [rast1.val] - Pixel value of the pixel of interest from rast1 - - - [rast1.x] - 1-based pixel column of the pixel of interest from rast1 - - - [rast1.y] - 1-based pixel row of the pixel of interest from rast1 - - - [rast2] - Pixel value of the pixel of interest from rast2 - - - [rast2.val] - Pixel value of the pixel of interest from rast2 - - - [rast2.x] - 1-based pixel column of the pixel of interest from rast2 - - - [rast2.y] - 1-based pixel row of the pixel of interest from rast2 - - - - + + + + INTERSECTION - The extent of the new raster is the intersection of the two rasters. This is the default. + + + + + UNION - The extent of the new raster is the union of the two rasters. + + + + + FIRST - The extent of the new raster is the same as the one of the first raster. + + + + + SECOND - The extent of the new raster is the same as the one of the second raster. + + + + + + + nodata1expr + + + An algebraic expression involving only rast2 or a constant that defines what to return when pixels of rast1 are nodata values and spatially corresponding rast2 pixels have values. + + + + + nodata2expr + + + An algebraic expression involving only rast1 or a constant that defines what to return when pixels of rast2 are nodata values and spatially corresponding rast1 pixels have values. + + + + + nodatanodataval + + + A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values. + + + + - + + Keywords permitted in expression, nodata1expr and nodata2expr + + + [rast1] - Pixel value of the pixel of interest from rast1 + + + [rast1.val] - Pixel value of the pixel of interest from rast1 + + + [rast1.x] - 1-based pixel column of the pixel of interest from rast1 + + + [rast1.y] - 1-based pixel row of the pixel of interest from rast1 + + + [rast2] - Pixel value of the pixel of interest from rast2 + + + [rast2.val] - Pixel value of the pixel of interest from rast2 + + + [rast2.x] - 1-based pixel column of the pixel of interest from rast2 + + + [rast2.y] - 1-based pixel row of the pixel of interest from rast2 + + + + + - - Examples: Variants 1 and 2 + + Examples: Variants 1 and 2 - + WITH foo AS ( SELECT ST_AddBand(ST_MakeEmptyRaster(10, 10, 0, 0, 1, 1, 0, 0, 0), '32BF', 1, -1) AS rast ) SELECT ST_MapAlgebra(rast, 1, NULL, 'ceil([rast]*[rast.x]/[rast.y]+[rast.val])') FROM foo - - - + + - - Examples: Variant 3 and 4 + + Examples: Variant 3 and 4 - + WITH foo AS ( SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast UNION ALL SELECT 2 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 1, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0), 2, '8BUI', 20, 0), 3, '32BUI', 300, 0) AS rast @@ -9391,80 +9003,86 @@ FROM foo t1 CROSS JOIN foo t2 WHERE t1.rid = 1 AND t2.rid = 2 - - - - - - See Also - - - , - , - - - + + - + + See Also - - - ST_MapAlgebraExpr - 1 raster band version: Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation on the input raster band and of pixeltype provided. Band 1 is assumed if no band is specified. - - - - - - raster ST_MapAlgebraExpr - raster rast - integer band - text pixeltype - text expression - double precision nodataval=NULL - + + , + , + + + + + + + + ST_MapAlgebraExpr + 1 raster band version: Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation on the input raster band and of pixeltype provided. Band 1 is assumed if no band is specified. + + + + + + + raster ST_MapAlgebraExpr + raster rast + integer band + text pixeltype + text expression + double precision nodataval=NULL + - - raster ST_MapAlgebraExpr - raster rast - text pixeltype - text expression - double precision nodataval=NULL - - - + + raster ST_MapAlgebraExpr + raster rast + text pixeltype + text expression + double precision nodataval=NULL + + + - - Description + + Description - - - is deprecated as of 2.1.0. Use instead. - - + + + is deprecated as of 2.1.0. Use instead. + + - Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the expression on the input raster (rast). If no band is specified band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band. - - If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input rast band. + + Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the expression on the input raster (rast). If no band is specified band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band. + - In the expression you can use the term - [rast] to refer to the pixel value of - the original band, [rast.x] to refer to - the 1-based pixel column index, [rast.y] - to refer to the 1-based pixel row index. - - Availability: 2.0.0 - - - - Examples - - Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band. - ALTER TABLE dummy_rast ADD COLUMN map_rast raster; + + If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input rast band. + + + + In the expression you can use the term [rast] to refer to the pixel value of the original band, [rast.x] to refer to the 1-based pixel column index, [rast.y] to refer to the 1-based pixel row index. + + + Availability: 2.0.0 + + + + Examples + + Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band. + +ALTER TABLE dummy_rast ADD COLUMN map_rast raster; UPDATE dummy_rast SET map_rast = ST_MapAlgebraExpr(rast,NULL,'mod([rast],2)') WHERE rid = 2; -SELECT ST_Value(rast,1,i,j) As origval, ST_Value(map_rast, 1, i, j) As mapval -FROM dummy_rast CROSS JOIN generate_series(1, 3) AS i CROSS JOIN generate_series(1,3) AS j +SELECT + ST_Value(rast,1,i,j) As origval, + ST_Value(map_rast, 1, i, j) As mapval +FROM dummy_rast +CROSS JOIN generate_series(1, 3) AS i +CROSS JOIN generate_series(1,3) AS j WHERE rid = 2; origval | mapval @@ -9478,15 +9096,20 @@ WHERE rid = 2; 250 | 0 254 | 0 254 | 0 - - Create a new 1 band raster of pixel-type 2BUI from our original that is reclassified and set the nodata value to be 0. - ALTER TABLE dummy_rast ADD COLUMN map_rast2 raster; -UPDATE dummy_rast SET map_rast2 = ST_MapAlgebraExpr(rast,'2BUI','CASE WHEN [rast] BETWEEN 100 and 250 THEN 1 -WHEN [rast] = 252 THEN 2 -WHEN [rast] BETWEEN 253 and 254 THEN 3 ELSE 0 END', '0') WHERE rid = 2; + -SELECT DISTINCT ST_Value(rast,1,i,j) As origval, ST_Value(map_rast2, 1, i, j) As mapval -FROM dummy_rast CROSS JOIN generate_series(1, 5) AS i CROSS JOIN generate_series(1,5) AS j + Create a new 1 band raster of pixel-type 2BUI from our original that is reclassified and set the nodata value to be 0. + ALTER TABLE dummy_rast ADD COLUMN map_rast2 raster; +UPDATE dummy_rast SET + map_rast2 = ST_MapAlgebraExpr(rast,'2BUI','CASE WHEN [rast] BETWEEN 100 and 250 THEN 1 WHEN [rast] = 252 THEN 2 WHEN [rast] BETWEEN 253 and 254 THEN 3 ELSE 0 END', '0') +WHERE rid = 2; + +SELECT DISTINCT + ST_Value(rast,1,i,j) As origval, + ST_Value(map_rast2, 1, i, j) As mapval +FROM dummy_rast +CROSS JOIN generate_series(1, 5) AS i +CROSS JOIN generate_series(1,5) AS j WHERE rid = 2; origval | mapval @@ -9498,165 +9121,225 @@ WHERE rid = 2; 253 | 3 254 | 3 -SELECT ST_BandPixelType(map_rast2) As b1pixtyp -FROM dummy_rast WHERE rid = 2; +SELECT + ST_BandPixelType(map_rast2) As b1pixtyp +FROM dummy_rast +WHERE rid = 2; b1pixtyp ---------- - 2BUI - - - - - - - - - - original (column rast-view) - - - - - - - - - rast_view_ma - - - - - - - - Create a new 3 band raster same pixel type from our original 3 band raster with first band - altered by map algebra and remaining 2 bands unaltered. - SELECT ST_AddBand( -ST_AddBand( + 2BUI + + + + + + + + + + + + + + + original (column rast-view) + + + + + + + + + + + + + + rast_view_ma + + + + + + + + + + + Create a new 3 band raster same pixel type from our original 3 band raster with first band altered by map algebra and remaining 2 bands unaltered. + +SELECT ST_AddBand( - ST_MakeEmptyRaster(rast_view), - ST_MapAlgebraExpr(rast_view,1,NULL,'tan([rast])*[rast]') + ST_AddBand( + ST_AddBand( + ST_MakeEmptyRaster(rast_view), + ST_MapAlgebraExpr(rast_view,1,NULL,'tan([rast])*[rast]') ), - ST_Band(rast_view,2) - ), - ST_Band(rast_view, 3) As rast_view_ma -) + ST_Band(rast_view,2) + ), + ST_Band(rast_view, 3) As rast_view_ma + ) FROM wind -WHERE rid=167; - - +WHERE rid=167; + + - - See Also - , , , , - - - - - - ST_MapAlgebraExpr - 2 raster band version: Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation on the two input raster bands and of pixeltype provided. band 1 of each raster is assumed if no band numbers are specified. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster and have its extent defined by the "extenttype" parameter. Values for "extenttype" can be: INTERSECTION, UNION, FIRST, SECOND. - - - - - - raster ST_MapAlgebraExpr - raster rast1 - raster rast2 - text expression - text pixeltype=same_as_rast1_band - text extenttype=INTERSECTION - text nodata1expr=NULL - text nodata2expr=NULL - double precision nodatanodataval=NULL - + + See Also + + , + , + , + , + + + + + + + + ST_MapAlgebraExpr + + 2 raster band version: Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation on the two input raster bands and of pixeltype provided. band 1 of each raster is assumed if no band numbers are specified. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster and have its extent defined by the "extenttype" parameter. Values for "extenttype" can be: INTERSECTION, UNION, FIRST, SECOND. + + + + + + + raster ST_MapAlgebraExpr + raster rast1 + raster rast2 + text expression + text pixeltype=same_as_rast1_band + text extenttype=INTERSECTION + text nodata1expr=NULL + text nodata2expr=NULL + double precision nodatanodataval=NULL + - - raster ST_MapAlgebraExpr - raster rast1 - integer band1 - raster rast2 - integer band2 - text expression - text pixeltype=same_as_rast1_band - text extenttype=INTERSECTION - text nodata1expr=NULL - text nodata2expr=NULL - double precision nodatanodataval=NULL - - - - - - Description + + raster ST_MapAlgebraExpr + raster rast1 + integer band1 + raster rast2 + integer band2 + text expression + text pixeltype=same_as_rast1_band + text extenttype=INTERSECTION + text nodata1expr=NULL + text nodata2expr=NULL + double precision nodatanodataval=NULL + + + - + + Description + + + + is deprecated as of 2.1.0. Use instead. + + + - is deprecated as of 2.1.0. Use instead. + Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the expression on the two input raster bands rast1, (rast2). If no band1, band2 is specified band 1 is assumed. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the extenttype parameter. - - - Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the expression on the two input raster bands rast1, (rast2). If no band1, band2 is specified band 1 is assumed. - The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the extenttype parameter. - - - - expression - A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer - - - pixeltype - The resulting pixel type of the output raster. Must be one listed in , left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster. - - - extenttype - Controls the extent of resulting raster - + + + + expression - INTERSECTION - The extent of the new raster is the intersection of the two rasters. This is the default. + + A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer + + + + + pixeltype - UNION - The extent of the new raster is the union of the two rasters. + + The resulting pixel type of the output raster. Must be one listed in , left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster. + + + + + extenttype - FIRST - The extent of the new raster is the same as the one of the first raster. + Controls the extent of resulting raster + + + + INTERSECTION - The extent of the new raster is the intersection of the two rasters. This is the default. + + + + + UNION - The extent of the new raster is the union of the two rasters. + + + + + FIRST - The extent of the new raster is the same as the one of the first raster. + + + + + SECOND - The extent of the new raster is the same as the one of the second raster. + + + + + + + nodata1expr - SECOND - The extent of the new raster is the same as the one of the second raster. + + An algebraic expression involving only rast2 or a constant that defines what to return when pixels of rast1 are nodata values and spatially corresponding rast2 pixels have values. + - - - - - nodata1expr - An algebraic expression involving only rast2 or a constant that defines what to return when pixels of rast1 are nodata values and spatially corresponding rast2 pixels have values. - - - nodata2expr - An algebraic expression involving only rast1 or a constant that defines what to return when pixels of rast2 are nodata values and spatially corresponding rast1 pixels have values. - - - nodatanodataval - A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values. - - - - - If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL or no pixel type specified, then the new raster band will have the same pixeltype as the input rast1 band. - Use the term [rast1.val] [rast2.val] to refer to the pixel value of the original raster bands and - [rast1.x], [rast1.y] etc. to refer to the column / row positions of the pixels. - - - Availability: 2.0.0 - - - - Example: 2 Band Intersection and Union - - Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band. - + + + + nodata2expr + + + An algebraic expression involving only rast1 or a constant that defines what to return when pixels of rast2 are nodata values and spatially corresponding rast1 pixels have values. + + + + + + nodatanodataval + + + A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values. + + + + + + + If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL or no pixel type specified, then the new raster band will have the same pixeltype as the input rast1 band. + + + Use the term [rast1.val] [rast2.val] to refer to the pixel value of the original raster bands and [rast1.x], [rast1.y] etc. to refer to the column / row positions of the pixels. + + + Availability: 2.0.0 + + + + Example: 2 Band Intersection and Union + + Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band. + --Create a cool set of rasters -- DROP TABLE IF EXISTS fun_shapes; CREATE TABLE fun_shapes(rid serial PRIMARY KEY, fun_name text, rast raster); @@ -9690,37 +9373,49 @@ FROM CROSS JOIN (SELECT rast FROM fun_shapes WHERE fun_name = 'rand bubbles') As bub - - - - - - - - - - - mapalgebra intersection - - - - - - - - - map algebra union - - - - - - - - - - Example: Overlaying rasters on a canvas as separate bands - + + + + + + + + + + + + + + + mapalgebra intersection + + + + + + + + + + + + + + map algebra union + + + + + + + + + + + + + Example: Overlaying rasters on a canvas as separate bands + -- we use ST_AsPNG to render the image so all single band ones look grey -- WITH mygeoms AS ( SELECT 2 As bnum, ST_Buffer(ST_Point(1,5),10) As geom @@ -9748,59 +9443,79 @@ WITH mygeoms ) SELECT rasts[1] As rast1 , rasts[2] As rast2, rasts[3] As rast3, ST_AddBand( ST_AddBand(rasts[1],rasts[2]), rasts[3]) As final_rast - FROM rbands; + FROM rbands; + - - - - - - - - - - rast1 - - - - - - - - - rast2 - - - - - - - - - - - rast3 - - - - - - - - - - final_rast - - - - - - - - - - Example: Overlay 2 meter boundary of select parcels over an aerial imagery - -- Create new 3 band raster composed of first 2 clipped bands, and overlay of 3rd band with our geometry + + + + + + + + + + + + rast1 + + + + + + + + + + + + + rast2 + + + + + + + + + + + + + + + + rast3 + + + + + + + + + + + + + + final_rast + + + + + + + + + + + + + Example: Overlay 2 meter boundary of select parcels over an aerial imagery + + -- Create new 3 band raster composed of first 2 clipped bands, and overlay of 3rd band with our geometry -- This query took 3.6 seconds on PostGIS windows 64-bit install WITH pr AS -- Note the order of operation: we clip all the rasters to dimensions of our region @@ -9824,138 +9539,164 @@ GROUP BY geom) SELECT ST_AddBand(ST_Band(clipped,ARRAY[1,2]) , ST_MapAlgebraExpr(ST_Band(clipped,3), ST_AsRaster(ST_Buffer(ST_Boundary(geom),2),clipped, '8BUI',250), '[rast2.val]', '8BUI', 'FIRST', '[rast2.val]', '[rast1.val]') ) As rast -FROM prunion; - - - - - - - - - - - The blue lines are the boundaries of select parcels - - - - - - - - - - See Also - , , , , , , , - , , - - +FROM prunion; + - - - ST_MapAlgebraFct - 1 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the input raster band and of pixeltype prodived. Band 1 is assumed if no band is specified. - + + + + + + + + + + + + + The blue lines are the boundaries of select parcels + + + + + + + + + + - - - - raster ST_MapAlgebraFct - raster rast - regprocedure onerasteruserfunc - - - raster ST_MapAlgebraFct - raster rast - regprocedure onerasteruserfunc - text[] VARIADIC args - - - - raster ST_MapAlgebraFct - raster rast - text pixeltype - regprocedure onerasteruserfunc - - - raster ST_MapAlgebraFct - raster rast - text pixeltype - regprocedure onerasteruserfunc - text[] VARIADIC args - + + See Also + + , + , + , + , + , + , + , + , + , + + + + + + + + ST_MapAlgebraFct + 1 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the input raster band and of pixeltype prodived. Band 1 is assumed if no band is specified. + + + + + + raster ST_MapAlgebraFct + raster rast + regprocedure onerasteruserfunc + + + raster ST_MapAlgebraFct + raster rast + regprocedure onerasteruserfunc + text[] VARIADIC args + + + + raster ST_MapAlgebraFct + raster rast + text pixeltype + regprocedure onerasteruserfunc + + + raster ST_MapAlgebraFct + raster rast + text pixeltype + regprocedure onerasteruserfunc + text[] VARIADIC args + - - raster ST_MapAlgebraFct - raster rast - integer band - regprocedure onerasteruserfunc - - - raster ST_MapAlgebraFct - raster rast - integer band - regprocedure onerasteruserfunc - text[] VARIADIC args - - - - raster ST_MapAlgebraFct - raster rast - integer band - text pixeltype - regprocedure onerasteruserfunc - - - raster ST_MapAlgebraFct - raster rast - integer band - text pixeltype - regprocedure onerasteruserfunc - text[] VARIADIC args - - - - + + raster ST_MapAlgebraFct + raster rast + integer band + regprocedure onerasteruserfunc + + + raster ST_MapAlgebraFct + raster rast + integer band + regprocedure onerasteruserfunc + text[] VARIADIC args + + + + raster ST_MapAlgebraFct + raster rast + integer band + text pixeltype + regprocedure onerasteruserfunc + + + raster ST_MapAlgebraFct + raster rast + integer band + text pixeltype + regprocedure onerasteruserfunc + text[] VARIADIC args + + + + - - Description + + Description - - - is deprecated as of 2.1.0. Use instead. - - + + + is deprecated as of 2.1.0. Use instead. + + - Creates a new one band raster formed by applying a valid PostgreSQL function specified by the onerasteruserfunc on the input raster (rast). If no band is specified, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band. + Creates a new one band raster formed by applying a valid PostgreSQL function specified by the onerasteruserfunc on the input raster (rast). If no band is specified, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band. - If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input rast band. + If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input rast band. - The onerasteruserfunc parameter must be the name and signature of a SQL or PL/pgSQL function, cast to a regprocedure. A very simple and quite useless PL/pgSQL function example is: + The onerasteruserfunc parameter must be the name and signature of a SQL or PL/pgSQL function, cast to a regprocedure. A very simple and quite useless PL/pgSQL function example is: CREATE OR REPLACE FUNCTION simple_function(pixel FLOAT, pos INTEGER[], VARIADIC args TEXT[]) RETURNS FLOAT AS $$ BEGIN RETURN 0.0; END; $$ LANGUAGE 'plpgsql' IMMUTABLE; - The userfunction may accept two or three arguments: a float value, an optional integer array, and a variadic text array. The first argument is the value of an individual raster cell (regardless of the raster datatype). The second argument is the position of the current processing cell in the form '{x,y}'. The third argument indicates that all remaining parameters to shall be passed through to the userfunction. + The userfunction may accept two or three arguments: a float value, an optional integer array, and a variadic text array. The first argument is the value of an individual raster cell (regardless of the raster datatype). The second argument is the position of the current processing cell in the form '{x,y}'. The third argument indicates that all remaining parameters to shall be passed through to the userfunction. + - Passing a regprodedure argument to a SQL function requires the full function signature to be passed, then cast to a regprocedure type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:'simple_function(float,integer[],text[])'::regprocedureNote that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a regprocedure. + + Passing a regprodedure argument to a SQL function requires the full function signature to be passed, then cast to a regprocedure type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:'simple_function(float,integer[],text[])'::regprocedureNote that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a regprocedure. + - The third argument to the userfunction is a variadic text array. All trailing text arguments to any call are passed through to the specified userfunction, and are contained in the args argument. + + The third argument to the userfunction is a variadic text array. All trailing text arguments to any call are passed through to the specified userfunction, and are contained in the args argument. + - For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of Query Language (SQL) Functions. + + For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of Query Language (SQL) Functions. + - The text[] argument to the userfunction is required, regardless of whether you choose to pass any arguments to your user function for processing or not. + + The text[] argument to the userfunction is required, regardless of whether you choose to pass any arguments to your user function for processing or not. + - Availability: 2.0.0 - + Availability: 2.0.0 + - - Examples + + Examples - Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band. - ALTER TABLE dummy_rast ADD COLUMN map_rast raster; + Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band. + ALTER TABLE dummy_rast ADD COLUMN map_rast raster; CREATE FUNCTION mod_fct(pixel float, pos integer[], variadic args text[]) RETURNS float AS $$ @@ -9982,9 +9723,10 @@ WHERE rid = 2; 250 | 0 254 | 0 254 | 0 - - Create a new 1 band raster of pixel-type 2BUI from our original that is reclassified and set the nodata value to a passed parameter to the user function (0). - ALTER TABLE dummy_rast ADD COLUMN map_rast2 raster; + + + Create a new 1 band raster of pixel-type 2BUI from our original that is reclassified and set the nodata value to a passed parameter to the user function (0). + ALTER TABLE dummy_rast ADD COLUMN map_rast2 raster; CREATE FUNCTION classify_fct(pixel float, pos integer[], variadic args text[]) RETURNS float AS @@ -10027,34 +9769,36 @@ FROM dummy_rast WHERE rid = 2; b1pixtyp ---------- - 2BUI - - - - - - - - - - original (column rast-view) - - - - - - - - rast_view_ma - - - - - - - - Create a new 3 band raster same pixel type from our original 3 band raster with first band altered by map algebra and remaining 2 bands unaltered. - CREATE FUNCTION rast_plus_tan(pixel float, pos integer[], variadic args text[]) + 2BUI + + + + + + + + + + + + original (column rast-view) + + + + + + + + rast_view_ma + + + + + + + + Create a new 3 band raster same pixel type from our original 3 band raster with first band altered by map algebra and remaining 2 bands unaltered. + CREATE FUNCTION rast_plus_tan(pixel float, pos integer[], variadic args text[]) RETURNS float AS $$ @@ -10075,62 +9819,69 @@ SELECT ST_AddBand( ST_Band(rast_view, 3) As rast_view_ma ) FROM wind -WHERE rid=167; - - +WHERE rid=167; + + - - See Also - , , , - - - - - - ST_MapAlgebraFct - 2 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the 2 input raster bands and of pixeltype prodived. Band 1 is assumed if no band is specified. Extent type defaults to INTERSECTION if not specified. - + + See Also + + , + , + , + + + + + + + + ST_MapAlgebraFct + 2 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the 2 input raster bands and of pixeltype prodived. Band 1 is assumed if no band is specified. Extent type defaults to INTERSECTION if not specified. + + + + + + raster ST_MapAlgebraFct + raster rast1 + raster rast2 + regprocedure tworastuserfunc + text pixeltype=same_as_rast1 + text extenttype=INTERSECTION + text[] VARIADIC userargs + + + + raster ST_MapAlgebraFct + raster rast1 + integer band1 + raster rast2 + integer band2 + regprocedure tworastuserfunc + text pixeltype=same_as_rast1 + text extenttype=INTERSECTION + text[] VARIADIC userargs + + + - - - - raster ST_MapAlgebraFct - raster rast1 - raster rast2 - regprocedure tworastuserfunc - text pixeltype=same_as_rast1 - text extenttype=INTERSECTION - text[] VARIADIC userargs - + + Description - - raster ST_MapAlgebraFct - raster rast1 - integer band1 - raster rast2 - integer band2 - regprocedure tworastuserfunc - text pixeltype=same_as_rast1 - text extenttype=INTERSECTION - text[] VARIADIC userargs - - - + + + is deprecated as of 2.1.0. Use instead. + + - - Description - - - - is deprecated as of 2.1.0. Use instead. + Creates a new one band raster formed by applying a valid PostgreSQL function specified by the tworastuserfunc on the input raster rast1, rast2. If no band1 or band2 is specified, band 1 is assumed. The new raster will have the same georeference, width, and height as the original rasters but will only have one band. - - - Creates a new one band raster formed by applying a valid PostgreSQL function specified by the tworastuserfunc on the input raster rast1, rast2. If no band1 or band2 is specified, band 1 is assumed. The new raster will have the same georeference, width, and height as the original rasters but will only have one band. - If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL or left out, then the new raster band will have the same pixeltype as the input rast1 band. + If pixeltype is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL or left out, then the new raster band will have the same pixeltype as the input rast1 band. + - The tworastuserfunc parameter must be the name and signature of an SQL or PL/pgSQL function, cast to a regprocedure. An example PL/pgSQL function example is: + The tworastuserfunc parameter must be the name and signature of an SQL or PL/pgSQL function, cast to a regprocedure. An example PL/pgSQL function example is: CREATE OR REPLACE FUNCTION simple_function_for_two_rasters(pixel1 FLOAT, pixel2 FLOAT, pos INTEGER[], VARIADIC args TEXT[]) RETURNS FLOAT AS $$ BEGIN @@ -10138,22 +9889,29 @@ WHERE rid=167; END; $$ LANGUAGE 'plpgsql' IMMUTABLE; - The tworastuserfunc may accept three or four arguments: a double precision value, a double precision value, an optional integer array, and a variadic text array. The first argument is the value of an individual raster cell in rast1 (regardless of the raster datatype). The second argument is an individual raster cell value in rast2. The third argument is the position of the current processing cell in the form '{x,y}'. The fourth argument indicates that all remaining parameters to shall be passed through to the tworastuserfunc. + The tworastuserfunc may accept three or four arguments: a double precision value, a double precision value, an optional integer array, and a variadic text array. The first argument is the value of an individual raster cell in rast1 (regardless of the raster datatype). The second argument is an individual raster cell value in rast2. The third argument is the position of the current processing cell in the form '{x,y}'. The fourth argument indicates that all remaining parameters to shall be passed through to the tworastuserfunc. + - Passing a regprodedure argument to a SQL function requires the full function signature to be passed, then cast to a regprocedure type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:'simple_function(double precision, double precision, integer[], text[])'::regprocedureNote that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a regprocedure. + Passing a regprodedure argument to a SQL function requires the full function signature to be passed, then cast to a regprocedure type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:'simple_function(double precision, double precision, integer[], text[])'::regprocedureNote that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a regprocedure. + - The third argument to the tworastuserfunc is a variadic text array. All trailing text arguments to any call are passed through to the specified tworastuserfunc, and are contained in the userargs argument. + The third argument to the tworastuserfunc is a variadic text array. All trailing text arguments to any call are passed through to the specified tworastuserfunc, and are contained in the userargs argument. + - For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of Query Language (SQL) Functions. + + For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of Query Language (SQL) Functions. + - The text[] argument to the tworastuserfunc is required, regardless of whether you choose to pass any arguments to your user function for processing or not. + + The text[] argument to the tworastuserfunc is required, regardless of whether you choose to pass any arguments to your user function for processing or not. + - Availability: 2.0.0 - + Availability: 2.0.0 + - - Example: Overlaying rasters on a canvas as separate bands - + + Example: Overlaying rasters on a canvas as separate bands + -- define our user defined function -- CREATE OR REPLACE FUNCTION raster_mapalgebra_union( rast1 double precision, @@ -10217,30 +9975,33 @@ SELECT ST_AddBand(ST_AddBand(rasts[1], rasts[2]),rasts[3]), 4, 'map bands overla 'raster_mapalgebra_union(double precision, double precision, integer[], text[])'::regprocedure, '8BUI', 'FIRST') FROM map_shapes As m1 CROSS JOIN map_shapes As m2 WHERE m1.descrip = 'canvas' AND m2.descrip <> 'canvas' ORDER BY m2.bnum) As rasts) As foo; + - - - - - - - - - - - - map bands overlay (canvas) (R: small road, G: circle, B: big road) - - - - - - - - - - User Defined function that takes extra args - + + + + + + + + + + + + map bands overlay (canvas) (R: small road, G: circle, B: big road) + + + + + + + + + + + + User Defined function that takes extra args + CREATE OR REPLACE FUNCTION raster_mapalgebra_userargs( rast1 double precision, rast2 double precision, @@ -10271,118 +10032,113 @@ SELECT ST_MapAlgebraFct(m1.rast, 1, m1.rast, 3, '8BUI', 'INTERSECT', '100','200','200','0') FROM map_shapes As m1 WHERE m1.descrip = 'map bands overlay fct union (canvas)'; - - - - - - - - user defined with extra args and different bands from same raster - - - - - - + - - See Also - , , , - - - - - - ST_MapAlgebraFctNgb - - 1-band version: Map Algebra Nearest Neighbor using user-defined PostgreSQL function. Return a raster which values are the result of a PLPGSQL user function involving a neighborhood of values from the input raster band. - - - - - - raster ST_MapAlgebraFctNgb - raster rast - integer band - text pixeltype - integer ngbwidth - integer ngbheight - regprocedure onerastngbuserfunc - text nodatamode - text[] VARIADIC args - - - - - - - Description - - - is deprecated as of 2.1.0. Use instead. + + + + + + user defined with extra args and different bands from same raster + + - + - (one raster version) Return a raster which values - are the result of a PLPGSQL user function involving a - neighborhood of values from the input raster band. The user function takes the neighborhood of pixel values - as an array of numbers, for each pixel, returns the result from the user function, - replacing pixel value of currently inspected pixel with the function result. + + See Also + + , + , + , + + + + + + + + ST_MapAlgebraFctNgb + 1-band version: Map Algebra Nearest Neighbor using user-defined PostgreSQL function. Return a raster which values are the result of a PLPGSQL user function involving a neighborhood of values from the input raster band. + + + + + + raster ST_MapAlgebraFctNgb + raster rast + integer band + text pixeltype + integer ngbwidth + integer ngbheight + regprocedure onerastngbuserfunc + text nodatamode + text[] VARIADIC args + + + - - - rast - Raster on which the user function is evaluated. - - - band - Band number of the raster to be evaluated. Default to 1. - - - pixeltype - The resulting pixel type of the output raster. Must be one listed in or left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the rast. Results are truncated if they are larger than what is allowed for the pixeltype. - - - ngbwidth - The width of the neighborhood, in cells. - - - ngbheight - The height of the neighborhood, in cells. - - - onerastngbuserfunc - PLPGSQL/psql user function to apply to neighborhood pixels of a single band of a raster. The first element is a 2-dimensional - array of numbers representing the rectangular pixel neighborhood - - - nodatamode - Defines what value to pass to the function for a neighborhood pixel that is nodata or NULL - 'ignore': any NODATA values encountered in the neighborhood are ignored by the computation -- this flag must be sent to the user callback function, and the user function decides how to ignore it. - 'NULL': any NODATA values encountered in the neighborhood will cause the resulting pixel to be NULL -- the user callback function is skipped in this case. - 'value': any NODATA values encountered in the neighborhood are replaced by the reference pixel (the one in the center of the neighborhood). Note that if this value is NODATA, the behavior is the same as 'NULL' (for the affected neighborhood) - - - - args - Arguments to pass into the user function. - - + + Description - Availability: 2.0.0 - - - - - - - Examples - Examples utilize the katrina raster loaded as a single tile described in - http://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html - and then prepared in the examples - + + + is deprecated as of 2.1.0. Use instead. + + + + (one raster version) Return a raster which values are the result of a PLPGSQL user function involving a neighborhood of values from the input raster band. The user function takes the neighborhood of pixel values as an array of numbers, for each pixel, returns the result from the user function, replacing pixel value of currently inspected pixel with the function result. + + + + rast + Raster on which the user function is evaluated. + + + band + Band number of the raster to be evaluated. Default to 1. + + + pixeltype + The resulting pixel type of the output raster. Must be one listed in or left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the rast. Results are truncated if they are larger than what is allowed for the pixeltype. + + + ngbwidth + The width of the neighborhood, in cells. + + + ngbheight + The height of the neighborhood, in cells. + + + onerastngbuserfunc + PLPGSQL/psql user function to apply to neighborhood pixels of a single band of a raster. The first element is a 2-dimensional array of numbers representing the rectangular pixel neighborhood + + + nodatamode + + Defines what value to pass to the function for a neighborhood pixel that is nodata or NULL + 'ignore': any NODATA values encountered in the neighborhood are ignored by the computation -- this flag must be sent to the user callback function, and the user function decides how to ignore it. + 'NULL': any NODATA values encountered in the neighborhood will cause the resulting pixel to be NULL -- the user callback function is skipped in this case. + 'value': any NODATA values encountered in the neighborhood are replaced by the reference pixel (the one in the center of the neighborhood). Note that if this value is NODATA, the behavior is the same as 'NULL' (for the affected neighborhood) + + + + args + Arguments to pass into the user function. + + + + Availability: 2.0.0 + + + + Examples + + Examples utilize the katrina raster loaded as a single tile described in http://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html and then prepared in the examples + + -- -- A simple 'callback' user function that averages up all the values in a neighborhood. -- @@ -10414,250 +10170,104 @@ SELECT ST_MapAlgebraFctNgb(rast, 1, '8BUI', 4,4, 'rast_avg(float[][], text, text[])'::regprocedure, 'NULL', NULL) As nn_with_border FROM katrinas_rescaled limit 1; - + - - - - - - - - - - First band of our raster - - - - - - - - new raster after averaging pixels withing 4x4 pixels of each other - - - - - - - - - - - See Also - - , , - - + + + + + + + + + + + + + First band of our raster + + + + + + + + + + + + + + new raster after averaging pixels withing 4x4 pixels of each other + + + + + + + + + + - - - ST_MinConvexHull - - Return the convex hull geometry of the raster excluding NODATA pixels. - + + + See Also + + , + , + + + + + + + + ST_Reclass + Creates a new raster composed of band types reclassified from original. The nband is the band to be changed. If nband is not specified assumed to be 1. All other bands are returned unchanged. Use case: convert a 16BUI band to a 8BUI and so forth for simpler rendering as viewable formats. + + + + + + raster ST_Reclass + raster rast + integer nband + text reclassexpr + text pixeltype + double precision nodataval=NULL + + + + raster ST_Reclass + raster rast + reclassarg[] VARIADIC reclassargset + + + + raster ST_Reclass + raster rast + text reclassexpr + text pixeltype + + + - - - - geometry ST_MinConvexHull - raster rast - integer nband=NULL - - - + + Description + + Creates a new raster formed by applying a valid PostgreSQL algebraic operation defined by the reclassexpr on the input raster (rast). If no band is specified band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster. Bands not designated will come back unchanged. Refer to for description of valid reclassification expressions. - - Description + The bands of the new raster will have pixel type of pixeltype. If reclassargset is passed in then each reclassarg defines behavior of each band generated. - - 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 - + Availability: 2.0.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 - - , - , - , - - - - - - - - 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. - - - - 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; - -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; - --- 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; - -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))) - --- Or if you want the no data value different for just one time - -SELECT ST_AsText( - ST_Polygon( - ST_SetBandNoDataValue(rast,1,252) - ) - ) As geomwkt -FROM dummy_rast -WHERE rid =2; - -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 - , - - - - - - ST_Reclass - Creates a new raster composed of band types reclassified from original. The nband is the band to be changed. If nband is not specified assumed to be 1. All other bands are returned unchanged. - Use case: convert a 16BUI band to a 8BUI and so forth for simpler rendering as viewable formats. - - - - - - raster ST_Reclass - raster rast - integer nband - text reclassexpr - text pixeltype - double precision nodataval=NULL - - - - raster ST_Reclass - raster rast - reclassarg[] VARIADIC reclassargset - - - - raster ST_Reclass - raster rast - text reclassexpr - text pixeltype - - - - - - Description - - Creates a new raster formed by applying a valid PostgreSQL algebraic operation defined by the reclassexpr on the input raster (rast). If no band is specified - band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster. Bands not designated will come back unchanged. - Refer to for description of valid reclassification expressions. - - The bands of the new raster will have pixel type of pixeltype. If reclassargset is passed in then each reclassarg defines behavior of each band generated. - - - Availability: 2.0.0 - - - - Examples Basic - - Create a new raster from the original where band 2 is converted from 8BUI to 4BUI and all values from 101-254 are set to nodata value. - ALTER TABLE dummy_rast ADD COLUMN reclass_rast raster; + + Examples Basic + Create a new raster from the original where band 2 is converted from 8BUI to 4BUI and all values from 101-254 are set to nodata value. + +ALTER TABLE dummy_rast ADD COLUMN reclass_rast raster; UPDATE dummy_rast SET reclass_rast = ST_Reclass(rast,2,'0-87:1-10, 88-100:11-15, 101-254:0-0', '4BUI',0) WHERE rid = 2; SELECT i as col, j as row, ST_Value(rast,2,i,j) As origval, @@ -10676,15 +10286,16 @@ WHERE rid = 2; 3 | 2 | 180 | | 0 1 | 3 | 99 | 15 | 15 2 | 3 | 112 | | 0 - 3 | 3 | 169 | | 0 - - - - Example: Advanced using multiple reclassargs - - Create a new raster from the original where band 1,2,3 is converted to 1BB,4BUI, 4BUI respectively and reclassified. - Note this uses the variadic reclassarg argument which can take as input an indefinite number of reclassargs (theoretically as many bands as you have) - UPDATE dummy_rast SET reclass_rast = + 3 | 3 | 169 | | 0 + + + + + Example: Advanced using multiple reclassargs + + Create a new raster from the original where band 1,2,3 is converted to 1BB,4BUI, 4BUI respectively and reclassified. Note this uses the variadic reclassarg argument which can take as input an indefinite number of reclassargs (theoretically as many bands as you have) + +UPDATE dummy_rast SET reclass_rast = ST_Reclass(rast, ROW(2,'0-87]:1-10, (87-100]:11-15, (101-254]:0-0', '4BUI',NULL)::reclassarg, ROW(1,'0-253]:1, 254:0', '1BB', NULL)::reclassarg, @@ -10707,13 +10318,14 @@ col | row | ov1 | rv1 | ov2 | rv2 | ov3 | rv3 3 | 2 | 254 | 0 | 180 | 0 | 162 | 4 1 | 3 | 250 | 1 | 99 | 15 | 90 | 3 2 | 3 | 254 | 0 | 112 | 0 | 108 | 3 - 3 | 3 | 254 | 0 | 169 | 0 | 175 | 4 - - - Example: Advanced Map a single band 32BF raster to multiple viewable bands - - Create a new 3 band (8BUI,8BUI,8BUI viewable raster) from a raster that has only one 32bf band - + 3 | 3 | 254 | 0 | 169 | 0 | 175 | 4 + + + + + Example: Advanced Map a single band 32BF raster to multiple viewable bands + Create a new 3 band (8BUI,8BUI,8BUI viewable raster) from a raster that has only one 32bf band + ALTER TABLE wind ADD COLUMN rast_view raster; UPDATE wind set rast_view = ST_AddBand( NULL, @@ -10722,130 +10334,192 @@ UPDATE wind ST_Reclass(rast,1, '11-33):0-255,[0-32:0,(34-1000:0'::text, '8BUI'::text,0), ST_Reclass(rast,1,'0-32]:0,(32-100:100-255'::text, '8BUI'::text,0) ] - ) ; - - - - - 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 - + + See Also + + , + , + , + , + , + + + + + + + + ST_Union + Returns the union of a set of raster tiles into a single raster composed of 1 or more bands. + + + + + + raster ST_Union + setof raster rast + + + + + raster ST_Union + setof raster rast + unionarg[] unionargset + + + + + raster ST_Union + setof raster rast + integer nband + + + + + raster ST_Union + setof raster rast + text uniontype + + + + + raster ST_Union + setof raster rast + integer nband + text uniontype + + + + + + Description + + Returns the union of a set of raster tiles into a single raster composed of at least one band. The resulting raster's extent is the extent of the whole set. In the case of intersection, the resulting value is defined by uniontype which is one of the following: LAST (default), FIRST, MIN, MAX, COUNT, SUM, MEAN, RANGE. - - Examples - --- needs examples - - + Availability: 2.0.0 + Enhanced: 2.1.0 Improved Speed (fully C-Based). + Availability: 2.1.0 ST_Union(rast, unionarg) variant was introduced. + Enhanced: 2.1.0 ST_Union(rast) (variant 1) unions all bands of all input rasters. Prior versions of PostGIS assumed the first band. + Enhanced: 2.1.0 ST_Union(rast, uniontype) (variant 4) unions all bands of all input rasters. + + + Examples: Reconstitute a single band chunked raster tile + +-- this creates a single band from first band of raster tiles +-- that form the original file system tile +SELECT filename, ST_Union(rast,1) As file_rast +FROM sometable WHERE filename IN('dem01', 'dem02') GROUP BY filename; + + + + + Examples: Return a multi-band raster that is the union of tiles intersecting geometry + +-- this creates a multi band raster collecting all the tiles that intersect a line +-- Note: In 2.0, this would have just returned a single band raster +-- , new union works on all bands by default +-- this is equivalent to unionarg: ARRAY[ROW(1, 'LAST'), ROW(2, 'LAST'), ROW(3, 'LAST')]::unionarg[] +SELECT ST_Union(rast) +FROM aerials.boston +WHERE ST_Intersects(rast, ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) ); + + + + Examples: Return a multi-band raster that is the union of tiles intersecting geometry + Here we use the longer syntax if we only wanted a subset of bands or we want to change order of bands + +-- this creates a multi band raster collecting all the tiles that intersect a line +SELECT ST_Union(rast,ARRAY[ROW(2, 'LAST'), ROW(1, 'LAST'), ROW(3, 'LAST')]::unionarg[]) +FROM aerials.boston +WHERE ST_Intersects(rast, ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) ); + + - - See Also - - , - , - , - , - , - - - - + + + See Also + + , + , + , + , + + + + + + + + + DEM (Elevation) + + + + 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 + + + - - - 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 - + + Description - - 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. + 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 slope. Possible values are: RADIANS, DEGREES (default), PERCENT. - + + units indicates the units of the aspect. Possible values are: RADIANS, DEGREES (default). + - - scale is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120. - + + When units = RADIANS, values are between 0 and 2 * pi radians measured clockwise from North. + - - If interpolate_nodata is TRUE, values for NODATA pixels from the input raster will be interpolated using before computing the surface slope. - + + When units = DEGREES, values are between 0 and 360 degrees measured clockwise from North. + - - For more information about Slope, Aspect and Hillshade, please refer to ESRI - How hillshade works and ERDAS Field Guide - Slope Images. + If slope of pixel is zero, aspect of pixel is -1. - - 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 - + + + 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), @@ -10859,27 +10533,25 @@ WITH foo AS ( ) AS rast ) SELECT - ST_DumpValues(ST_Slope(rast, 1, '32BF')) + ST_DumpValues(ST_Aspect(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,"{{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 + + Examples: Variant 2 - Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher. + 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( @@ -10901,235 +10573,880 @@ WITH foo AS ( ) SELECT t1.rast, - ST_Slope(ST_Union(t2.rast), 1, 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 - - , - , - , - , - , - - - - + + See Also + + , + , + , + , + , + + + + + + + + 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 + + + + 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 + + + - - - ST_TPI - Returns a raster with the calculated Topographic Position Index. - + + 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. - - - - raster ST_TPI - raster rast - integer nband - raster customextent - text pixeltype="32BF" - boolean interpolate_nodata=FALSE - - - + + azimuth is a value between 0 and 360 degrees measured clockwise from North. + - - Description + + altitude is a value between 0 and 90 degrees where 0 degrees is at the horizon and 90 degrees is directly overhead. + - Calculates the Topographic Position Index, which is defined as the folcal mean with radius of one minus the center cell. + + max_bright is a value between 0 and 255 with 0 as no brightness and 255 as max brightness. + - - This function only supports a focalmean radius of one. - - 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. + - - Examples - --- needs examples - - + + If interpolate_nodata is TRUE, values for NODATA pixels from the input raster will be interpolated using before computing the hillshade illumination. + - - See Also - - , - , - , - , - , - - - - + + + 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 - - - ST_TRI - Returns a raster with the calculated Terrain Ruggedness Index. - + + + + 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 - - - - raster ST_TRI - raster rast - integer nband - raster customextent - text pixeltype="32BF" - boolean interpolate_nodata=FALSE - - - + 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) + + - - Description + + Examples: Variant 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. - + Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher. - - This function only supports a focalmean radius of one. - + +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; + + - Availability: 2.1.0 - + + 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 + + + - - Examples - + + 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 + + See Also , - , + , , , , - - - - - - - ST_Union - Returns the union of a set of raster tiles into a single raster composed of 1 or more bands. - - - - - - raster ST_Union - setof raster rast - - - - - raster ST_Union - setof raster rast - unionarg[] unionargset - - - - - raster ST_Union - setof raster rast - integer nband - - - - - raster ST_Union - setof raster rast - text uniontype - - - - - raster ST_Union - setof raster rast - integer nband - text uniontype - - - + + + + + + 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 + + Description - Returns the union of a set of raster tiles into a single raster composed of at least one band. The resulting raster's extent is the extent of the whole set. In the case of intersection, the resulting value is defined by uniontype which is one of the following: LAST (default), FIRST, MIN, MAX, COUNT, SUM, MEAN, RANGE. + Returns the slope (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the slope equation to neighboring pixels. - Availability: 2.0.0 - For variant ST_Union(rast,uniontype), band 1 is assumed. - Enhanced: 2.1.0 Improved Speed (fully C-Based). - Availability: 2.1.0 ST_Union(rast, unionarg) variant was introduced. - Enhanced: 2.1.0 ST_Union(rast) (variant 1) unions all bands of all input rasters. Prior versions of PostGIS assumed the first band. - Enhanced: 2.1.0 ST_Union(rast, uniontype) (variant 4) unions all bands of all input rasters. - - - - - - Examples: Reconstitute a single band chunked raster tile - --- this creates a single band from first band of raster tiles --- that form the original file system tile -SELECT filename, ST_Union(rast,1) As file_rast -FROM sometable WHERE filename IN('dem01', 'dem02') GROUP BY filename; - - - - Examples: Return a multi-band raster that is the union of tiles intersecting geometry - -- this creates a multi band raster collecting all the tiles that intersect a line --- Note: In 2.0, this would have just returned a single band raster --- , new union works on all bands by default --- this is equivalent to unionarg: ARRAY[ROW(1, 'LAST'), ROW(2, 'LAST'), ROW(3, 'LAST')]::unionarg[] - SELECT ST_Union(rast) -FROM aerials.boston -WHERE ST_Intersects(rast, ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) ); - - - Examples: Return a multi-band raster that is the union of tiles intersecting geometry - Here we use the longer syntax if we only wanted a subset of bands or we want to change order of bands - -- this creates a multi band raster collecting all the tiles that intersect a line -SELECT ST_Union(rast,ARRAY[ROW(2, 'LAST'), ROW(1, 'LAST'), ROW(3, 'LAST')]::unionarg[]) -FROM aerials.boston -WHERE ST_Intersects(rast, ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) ); - + + 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_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 + + , + , + , + , + , + + + + + + + + + Raster to Geometry + + + + Box3D + Returns the box 3d representation of the enclosing box of the raster. + + + + + + box3d Box3D + raster rast + + + + + + Description + + Returns the box representing the extent of the raster. + + The polygon is defined by the corner points of the bounding box ((MINX, MINY), (MAXX, MAXY)) + + + 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 + + + + + + + + + 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 + + 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 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_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; + + 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_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 + + , + , + , + + + + + + + + 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. + + + + 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; + +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; + +-- 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; + +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))) + +-- Or if you want the no data value different for just one time + +SELECT ST_AsText( + ST_Polygon( + ST_SetBandNoDataValue(rast,1,252) + ) + ) As geomwkt +FROM dummy_rast +WHERE rid =2; + +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 + + , + + + + + + - - - See Also - - , - , - , - , - - - - - - Raster Processing Builtin Functions + + Raster Map Algebra Built-in Functions ST_Min4ma