The functions given below are the ones which a user of WKT Raster is likely to need and which are currently available in WKT Raster. There are other functions which are required support functions to the raster objects which are not of use to a general user. WKT Raster is a sub-project of PostGIS that introduces a new type called raster for storing and analyzing raster data. In order to use these functions, you need PostGIS 1.4 above installed in your database as well as wktraster compiled and the rtpostgis.sql loaded in your database. This will change later once the two projects are fully integrated. For more information about WKT Raster, please refer to PostGIS WKT Raster Home Page. For the examples in this reference we will be using a raster table of dummy rasters - Formed with the following code CREATE TABLE dummy_rast(rid integer, rast raster); INSERT INTO dummy_rast(rid, rast) VALUES (1, ('01' -- little endian (uint8 ndr) || '0000' -- version (uint16 0) || '0000' -- nBands (uint16 0) || '0000000000000040' -- scaleX (float64 2) || '0000000000000840' -- scaleY (float64 3) || '000000000000E03F' -- ipX (float64 0.5) || '000000000000E03F' -- ipY (float64 0.5) || '0000000000000000' -- skewX (float64 0) || '0000000000000000' -- skewY (float64 0) || '00000000' -- SRID (int32 0) || '0A00' -- width (uint16 10) || '1400' -- height (uint16 20) )::raster ), -- Raster: 5 x 5 pixels, 3 bands, PT_8BUI pixel type, NODATA = 0 (2, ('01000003009A9999999999A93F9A9999999999A9BF000000E02B274A' || '41000000007719564100000000000000000000000000000000FFFFFFFF050005000400FDFEFDFEFEFDFEFEFDF9FAFEF' || 'EFCF9FBFDFEFEFDFCFAFEFEFE04004E627AADD16076B4F9FE6370A9F5FE59637AB0E54F58617087040046566487A1506CA2E3FA5A6CAFFBFE4D566DA4CB3E454C5665')::raster); ST_MakeEmptyRaster Returns an empty raster of given dimensions, pixel x y, skew and spatial reference system with no bands raster ST_MakeEmptyRaster integer width integer height float8 ipx float8 ipy float8 scalex float8 scaley float8 skewx float8 skewy integer srid Returns the value that represents no data for the band INSERT INTO dummy_rast(rid,rast) VALUES(3, ST_MakeEmptyRaster( 100, 100, 0.0005, 0.0005, 1, 1, 0, 0, 4326) ) ST_BandNoDataValue Returns the value in a given band that represents no data. integer ST_BandNoDataValue raster rast integer bandnum Returns the value that represents no data for the band SELECT ST_BandNoDataValue(rast,1) As bnval1, ST_BandNoDataValue(rast,2) As bnval2, ST_BandNoDataValue(rast,3) As bnval3 FROM dummy_rast WHERE rid = 2; bnval1 | bnval2 | bnval3 --------+--------+-------- 0 | 0 | 0 ST_BandPixelType Returns the type of pixel for given band. text ST_BandPixelType raster rast integer bandnum Returns the value that represents no data for the band Pixel Types supported are as follows: 1BB - 1-bit boolean 2BUI - 2-bit unsigned integer 4BUI - 4-bit unsigned integer 8BSI - 8-bit signed integer 8BUI - 8-bit unsigned integer 16BSI - 16-bit signed integer 16BUI - 16-bit unsigned integer 16BUI - 16-bit unsigned integer 32BSI - 32-bit signed integer 32BUI - 32-bit unsigned integer 16BF - 16-bit float 32BF - 32-bit float 64BF - 64-bit float SELECT ST_BandPixelType(rast,1) As btype1, ST_BandPixelType(rast,2) As btype2, ST_BandPixelType(rast,3) As btype3 FROM dummy_rast WHERE rid = 2; btype1 | btype2 | btype3 --------+--------+-------- 8BUI | 8BUI | 8BUI ST_Box2D Returns the box 2d representation of the enclosing box of the raster box2dST_Box2D raster rast 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)) SELECT rid, ST_Box2D(rast) As rastbox FROM dummy_rast; rid | rastbox ----+------------------------------------------------- 1 | BOX(0.5 0.5,20.5 60.5) 2 | BOX(3427927.75 5793243.5,3427928 5793244) ST_Envelope Returns the polygon representation of the extent of the raster. geometry ST_Envelope raster rast Returns the polygon representation of the extent of the raster in spatial coordinate units defiend 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)) SELECT rid, ST_AsText(ST_Envelope(rast)) As envgeomwkt FROM dummy_rast; rid | envgeomwkt -----+-------------------------------------------------------------------- 1 | POLYGON((0 0,20 0,20 60,0 60,0 0)) 2 | POLYGON((3427927 5793243,3427928 5793243, 3427928 5793244,3427927 5793244, 3427927 5793243)) , , ST_GeoReference Returns the georeference meta data in GDAL or ESRI format. Default is GDAL. text ST_GeoReference raster rast text ST_GeoReference raster rast text format Returns the georeference meta data in GDAL or ESRI format. Default is GDAL if no type specified. type is string 'GDAL' or 'ESRI'. Difference between format representations is as follows: GDAL: pixelsizex skewy skewx pixelsizey upperleftx upperlefty ESRI: pixelsizex skewy skewx pixelsizey upperleftx + pixelsizex*0.5 upperlefty + pixelsizey*0.5 SELECT ST_GeoReference(rast, 'ESRI') As esri_ref, ST_GeoReference(rast, 'GDAL') As gdal_ref FROM dummy_rast WHERE rid=1; esri_ref | gdal_ref --------------+-------------- 2.0000000000 | 2.0000000000 0.0000000000 : 0.0000000000 0.0000000000 : 0.0000000000 3.0000000000 : 3.0000000000 1.5000000000 : 0.5000000000 2.0000000000 : 0.5000000000 , ST_Height Returns the height of the raster in pixels? integer ST_Height raster rast Returns the height of the raster. SELECT rid, ST_Height(rast) As rastheight FROM dummy_rast; rid | rastheight -----+------------ 1 | 20 2 | 5 ST_NumBands Returns the number of bands in the raster object. integer ST_NumBands raster rast Returns the number of bands in the raster object. SELECT rid, ST_NumBands(rast) As numbands FROM dummy_rast; rid | numbands ----+---------- 1 | 0 2 | 3 ST_PixelSizeX Returns the x size of pixels in units of coordinate reference system? float8 ST_PixelSizeX raster rast Returns the x size of pixels in units of coordinate reference system? SELECT rid, ST_PixelSizeX(rast) As rastpixwidth FROM dummy_rast; rid | rastpixwidth -----+-------------- 1 | 2 2 | 0.05 ST_PixelSizeY Returns the y size of pixels in units of coordinate reference system? float8 ST_PixelSizeY raster rast Returns the y size of pixels in units of coordinate reference system. May be negative. Refer to World File for more details. SELECT rid, ST_PixelSizeY(rast) As rastpixheight FROM dummy_rast; rid | rastpixheight -----+--------------- 1 | 3 2 | -0.05 ST_SRID Returns the spatial reference identifier of the raster as defined in spatial_ref_sys table. integer ST_SRID raster rast Returns the spatial reference identifier of the raster object as defined in the spatial_ref_sys table. From PostGIS 2.0+ the srid of a non-georeferenced raster/geometry is 0 instead of the prior -1. SELECT ST_SRID(rast) As srid FROM dummy_rast WHERE rid=1; srid ---------------- 0 , ST_UpperLeftX Returns the upper left x coordinate of raster in projected spatial ref. float8 ST_UpperLeftX raster rast Returns the upper left x coordinate of raster in projected spatial ref. SELECt rid, ST_UpperLeftX(rast) As ulx FROM dummy_rast; rid | ulx -----+------------ 1 | 0.5 2 | 3427927.75 , , ST_UpperLeftY Returns the upper left y coordinate of raster in projected spatial ref. float8 ST_UpperLeftY raster rast Returns the upper left y coordinate of raster in projected spatial ref. SELECT rid, ST_UpperLeftY(rast) As uly FROM dummy_rast; rid | uly -----+--------- 1 | 0.5 2 | 5793244 , , ST_Value Returns the value of a given band in a given columnx, rowy pixel. Band numbers start at 1. integer ST_Value raster rast integer bandnum integer columnx integer rowy Returns the value of a given band in a given columnx, rowy pixel. Band numbers start at 1. SELECt rid, ST_Value(rast, 1,1,1) As b1pval, ST_Value(rast, 2,1,1) As b2pval, ST_Value(rast, 3,1,1) As b3pval FROM dummy_rast WHERE rid=2; rid | b1pval | b2pval | b3pval -----+--------+--------+-------- 2 | 253 | 78 | 70 --- Get all values in bands 1,2,3 of each pixel -- SELECT x, y, ST_Value(rast, 1, x, y) As b1val, ST_Value(rast, 2, x, y) As b2val, ST_Value(rast, 3, x, y) As b3val FROM dummy_rast CROSS JOIN generate_series(1,1000) As x CROSS JOIN generate_series(1,1000) As y WHERE rid = 2 AND x <= ST_Width(rast) AND y <= ST_Height(rast); x | y | b1val | b2val | b3val ---+---+-------+-------+------- 1 | 1 | 253 | 78 | 70 1 | 2 | 253 | 96 | 80 1 | 3 | 250 | 99 | 90 1 | 4 | 251 | 89 | 77 1 | 5 | 252 | 79 | 62 2 | 1 | 254 | 98 | 86 2 | 2 | 254 | 118 | 108 : : ST_Width Returns the width of the raster in pixels? integer ST_Width raster rast Returns the width of the raster. SELECT ST_Width(rast) As rastwidth FROM dummy_rast WHERE rid=1; rastwidth ---------------- 10 ST_SetBandNoDataValue Sets the value for the given band that represents no data. integer ST_SetBandNoDataValue raster rast integer bandnum double precision val Returns the value that represents no data for the band. This will effect ST_Polygon and ST_ConvexHull results. -- change just first band no data value UPDATE dummy_rast SET rast = ST_SetBandNoDataValue(rast,1, 254) WHERE rid = 2; -- change no data band value of bands 1,2,3 UPDATE dummy_rast SET rast = ST_SetBandNoDataValue( ST_SetBandNoDataValue( ST_SetBandNoDataValue( rast,1, 254) ,2,99), 3,108) WHERE rid = 2; , ST_SetPixelSize Sets the x and y size of pixels in units of coordinate reference system. Number units/pixel width/height raster ST_SetPixelSize raster rast float8 xy raster ST_SetPixelSize raster rast float8 x float8 y Sets the x and y size of pixels in units of coordinate reference system. Number units/pixel width/height. If only one unit passed in, assumed x and y are the same number. UPDATE dummy_rast SET rast = ST_SetPixelSize(rast,1.5) WHERE rid = 2; SELECT ST_PixelSizeX(rast) As pixx, ST_PixelSizeY(rast) As pixy, ST_Box2D(rast) As newbox FROM dummy_rast WHERE rid = 2; pixx | pixy | newbox ------+------+---------------------------------------------- 1.5 | 1.5 | BOX(3427927.75 5793244,3427935.25 5793251.5) UPDATE dummy_rast SET rast = ST_SetPixelSize(rast,1.5,0.55) WHERE rid = 2; SELECT ST_PixelSizeX(rast) As pixx, ST_PixelSizeY(rast) As pixy, ST_Box2D(rast) As newbox FROM dummy_rast WHERE rid = 2; pixx | pixy | newbox ------+------+-------------------------------------------- 1.5 | 0.55 | BOX(3427927.75 5793244,3427935.25 5793247) , , ST_AsBinary Return the Well-Known Binary (WKB) representation of the raster without SRID meta data. bytea ST_AsBinary raster rast Returns the Binary representation of the raster. There are 2 variants of the function. The first variant takes no endian encoding paramater and defaults to little endian. The second variant takes a second argument denoting the encoding - using little-endian ('NDR') or big-endian ('XDR') encoding. This is useful in binary cursors to pull data out of the database without converting it to a string representation. SELECT ST_AsBinary(rast) As rastbin FROM dummy_rast WHERE rid=1; rastbin --------------------------------------------------------------------------------- \001\000\000\000\000\000\000\000\000\000\000\000@\000\000\000\000\000\000\010@\ 000\000\000\000\000\000\340?\000\000\000\000\000\000\340?\000\000\000\000\000\00 0\000\000\000\000\000\000\000\000\000\000\012\000\000\000\012\000\024\000 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 answer as ST_Envelope so only useful for irregularly shaped or skewed rasters. geometry ST_ConvexHull raster rast 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 answer 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 subtley different from ST_ConvexHull which does not floor. Refer to WKT 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)) , ,