WKT Raster Reference
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);
Raster Constructors
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
Description
Returns the value that represents no data for the band
Examples
INSERT INTO dummy_rast(rid,rast)
VALUES(3, ST_MakeEmptyRaster( 100, 100, 0.0005, 0.0005, 1, 1, 0, 0, 4326) )
See Also
Raster Accessors
ST_BandNoDataValue
Returns the value in a given band that represents no data.
integer ST_BandNoDataValue
raster rast
integer bandnum
Description
Returns the value that represents no data for the band
Examples
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
See Also
ST_BandPixelType
Returns the type of pixel for given band.
text ST_BandPixelType
raster rast
integer bandnum
Description
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
Examples
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
See Also
ST_Box2D
Returns the box 2d representation of the enclosing box of the raster
box2dST_Box2D
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))
Examples
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)
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 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))
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_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
Description
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
Examples
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
See Also
,
ST_Height
Returns the height of the raster in pixels?
integer ST_Height
raster rast
Description
Returns the height of the raster.
Examples
SELECT rid, ST_Height(rast) As rastheight
FROM dummy_rast;
rid | rastheight
-----+------------
1 | 20
2 | 5
See Also
ST_NumBands
Returns the number of bands in the raster object.
integer ST_NumBands
raster rast
Description
Returns the number of bands in the raster object.
Examples
SELECT rid, ST_NumBands(rast) As numbands
FROM dummy_rast;
rid | numbands
----+----------
1 | 0
2 | 3
See Also
ST_PixelSizeX
Returns the x size of pixels in units of coordinate reference system?
float8 ST_PixelSizeX
raster rast
Description
Returns the x size of pixels in units of coordinate reference system?
Examples
SELECT rid, ST_PixelSizeX(rast) As rastpixwidth
FROM dummy_rast;
rid | rastpixwidth
-----+--------------
1 | 2
2 | 0.05
See Also
ST_PixelSizeY
Returns the y size of pixels in units of coordinate reference system?
float8 ST_PixelSizeY
raster rast
Description
Returns the y size of pixels in units of coordinate reference system. May be negative. Refer to World File
for more details.
Examples
SELECT rid, ST_PixelSizeY(rast) As rastpixheight
FROM dummy_rast;
rid | rastpixheight
-----+---------------
1 | 3
2 | -0.05
See Also
ST_SRID
Returns the spatial reference identifier of the raster as defined in spatial_ref_sys table.
integer ST_SRID
raster rast
Description
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.
Examples
SELECT ST_SRID(rast) As srid
FROM dummy_rast WHERE rid=1;
srid
----------------
0
See Also
,
ST_UpperLeftX
Returns the upper left x coordinate of raster in projected spatial ref.
float8 ST_UpperLeftX
raster rast
Description
Returns the upper left x coordinate of raster in projected spatial ref.
Examples
SELECt rid, ST_UpperLeftX(rast) As ulx
FROM dummy_rast;
rid | ulx
-----+------------
1 | 0.5
2 | 3427927.75
See Also
, ,
ST_UpperLeftY
Returns the upper left y coordinate of raster in projected spatial ref.
float8 ST_UpperLeftY
raster rast
Description
Returns the upper left y coordinate of raster in projected spatial ref.
Examples
SELECT rid, ST_UpperLeftY(rast) As uly
FROM dummy_rast;
rid | uly
-----+---------
1 | 0.5
2 | 5793244
See Also
, ,
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
Description
Returns the value of a given band in a given columnx, rowy pixel. Band numbers start at 1.
Examples
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
:
:
See Also
ST_Width
Returns the width of the raster in pixels?
integer ST_Width
raster rast
Description
Returns the width of the raster.
Examples
SELECT ST_Width(rast) As rastwidth
FROM dummy_rast WHERE rid=1;
rastwidth
----------------
10
See Also
Raster Editors
ST_SetBandNoDataValue
Sets the value for the given band that represents no data.
integer ST_SetBandNoDataValue
raster rast
integer bandnum
double precision val
Description
Returns the value that represents no data for the band. This will effect ST_Polygon and ST_ConvexHull results.
Examples
-- 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;
See Also
,
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
Description
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.
Examples
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)
See Also
, ,
Raster Outputs
ST_AsBinary
Return the Well-Known Binary (WKB) representation of the raster without SRID meta data.
bytea ST_AsBinary
raster rast
Description
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.
Examples
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
See Also
Raster Processing Functions
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
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 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.
Examples
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))
See Also
, ,