2010-04-05 01:05:46 +00:00
<?xml version="1.0" encoding="UTF-8"?>
<chapter id= "RT_reference" >
<title > WKT Raster Reference</title>
<para > 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.</para>
<para > WKT Raster is a sub-project of PostGIS that introduces a new type called <varname > raster</varname> 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.</para>
<para > For more information about WKT Raster, please refer to <ulink url= "http://trac.osgeo.org/postgis/wiki/WKTRaster" > PostGIS WKT Raster Home Page</ulink> .</para>
2010-04-05 01:32:30 +00:00
<para > For the examples in this reference we will be using a raster table of dummy rasters - Formed with the following code </para>
<programlisting >
2010-04-05 02:28:54 +00:00
CREATE TABLE dummy_rast(rid integer, rast raster);
INSERT INTO dummy_rast(rid, rast)
2010-04-05 04:30:44 +00:00
VALUES (1,
2010-04-05 01:32:30 +00:00
('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)
||
2010-04-05 02:28:54 +00:00
'00000000' -- SRID (int32 0)
2010-04-05 01:32:30 +00:00
||
'0A00' -- width (uint16 10)
||
'1400' -- height (uint16 20)
)::raster
2010-04-05 04:30:44 +00:00
),
-- Raster: 5 x 5 pixels, 3 bands, PT_8BUI pixel type, NODATA = 0
(2, ('01000003009A9999999999A93F9A9999999999A9BF000000E02B274A' ||
'41000000007719564100000000000000000000000000000000FFFFFFFF050005000400FDFEFDFEFEFDFEFEFDF9FAFEF' ||
'EFCF9FBFDFEFEFDFCFAFEFEFE04004E627AADD16076B4F9FE6370A9F5FE59637AB0E54F58617087040046566487A1506CA2E3FA5A6CAFFBFE4D566DA4CB3E454C5665')::raster);
2010-04-05 01:32:30 +00:00
</programlisting>
<sect1 id= "Raster_Accessors" >
2010-04-05 02:28:54 +00:00
<title > Raster Accessors</title>
2010-04-05 04:30:44 +00:00
<refentry id= "RT_ST_BandNoDataValue" >
2010-04-05 01:32:30 +00:00
<refnamediv >
2010-04-05 04:30:44 +00:00
<refname > ST_BandNoDataValue</refname>
<refpurpose > Returns the value in a given band that represents no data.</refpurpose>
2010-04-05 01:32:30 +00:00
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
2010-04-05 04:30:44 +00:00
<funcdef > integer <function > ST_BandNoDataValue</function> </funcdef>
2010-04-05 01:32:30 +00:00
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
2010-04-05 04:30:44 +00:00
<paramdef > <type > integer </type> <parameter > bandnum</parameter> </paramdef>
2010-04-05 01:32:30 +00:00
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
2010-04-05 04:30:44 +00:00
<para > Returns the value that represents no data for the band</para>
2010-04-05 01:32:30 +00:00
</refsection>
<refsection >
<title > Examples</title>
2010-04-05 04:30:44 +00:00
<programlisting > <!-- TODO: Need example -->
2010-04-05 01:32:30 +00:00
</programlisting>
</refsection>
2010-04-05 04:30:44 +00:00
<refsection >
<title > See Also</title>
<para > <xref linkend= "RT_ST_NumBands" /> </para>
</refsection>
</refentry>
2010-04-05 01:32:30 +00:00
2010-04-05 04:30:44 +00:00
<refentry id= "RT_ST_BandPixelType" >
<refnamediv >
<refname > ST_BandPixelType</refname>
<refpurpose > Returns the type of pixel for given band.</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
<funcdef > integer <function > ST_BandNoDataValue</function> </funcdef>
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
<paramdef > <type > integer </type> <parameter > bandnum</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
<para > Returns the value that represents no data for the band</para>
</refsection>
<refsection >
<title > Examples</title>
<programlisting > 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
</programlisting>
</refsection>
2010-04-05 01:32:30 +00:00
<refsection >
<title > See Also</title>
2010-04-05 04:30:44 +00:00
<para > <xref linkend= "RT_ST_NumBands" /> </para>
2010-04-05 01:32:30 +00:00
</refsection>
</refentry>
2010-04-05 02:28:54 +00:00
2010-04-05 04:30:44 +00:00
<refentry id= "RT_ST_GeoReference" >
2010-04-05 02:28:54 +00:00
<refnamediv >
2010-04-05 04:30:44 +00:00
<refname > ST_GeoReference</refname>
<refpurpose > Returns the georeference meta data in GDAL or ESRI format. Default is GDAL.</refpurpose>
2010-04-05 02:28:54 +00:00
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
2010-04-05 04:30:44 +00:00
<funcdef > text <function > ST_GeoReference</function> </funcdef>
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > text <function > ST_GeoReference</function> </funcdef>
2010-04-05 02:28:54 +00:00
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
2010-04-05 04:30:44 +00:00
<paramdef > <type > text </type> <parameter > format</parameter> </paramdef>
2010-04-05 02:28:54 +00:00
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
2010-04-05 04:30:44 +00:00
<para > Returns the georeference meta data in GDAL or ESRI format. Default is GDAL if no type specified. type is string 'GDAL' or 'ESRI'.</para>
<para > Difference between format representations is as follows:</para>
<para > <varname > GDAL</varname> :
<progromlisting > pixelsizex
skewy
skewx
pixelsizey
upperleftx
upperlefty</progromlisting> </para>
<para > <varname > ESRI</varname> :
<progromlisting > pixelsizex
skewy
skewx
pixelsizey
upperleftx + pixelsizex*0.5
upperleftx + pixelsizey*0.5</progromlisting> </para>
2010-04-05 02:28:54 +00:00
</refsection>
<refsection >
<title > Examples</title>
2010-04-05 04:30:44 +00:00
<programlisting > SELECT ST_GeoReference(rast, 'ESRI') As esri_ref, ST_GeoReference(rast, 'GDAL') As gdal_ref
FROM dummy_rast WHERE rid=1;
2010-04-05 02:28:54 +00:00
2010-04-05 04:30:44 +00:00
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
2010-04-05 02:28:54 +00:00
</programlisting>
</refsection>
2010-04-05 04:30:44 +00:00
2010-04-05 02:28:54 +00:00
<refsection >
<title > See Also</title>
2010-04-05 04:30:44 +00:00
<para > <xref linkend= "RT_ST_PixelSizeX" /> , <xref linkend= "RT_ST_PixelSizeY" /> </para>
2010-04-05 02:28:54 +00:00
</refsection>
</refentry>
2010-04-05 04:30:44 +00:00
<refentry id= "RT_ST_Height" >
2010-04-05 02:28:54 +00:00
<refnamediv >
2010-04-05 04:30:44 +00:00
<refname > ST_Height</refname>
<refpurpose > Returns the height of the raster in pixels?</refpurpose>
2010-04-05 02:28:54 +00:00
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
2010-04-05 04:30:44 +00:00
<funcdef > integer <function > ST_Height</function> </funcdef>
2010-04-05 02:28:54 +00:00
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
2010-04-05 04:30:44 +00:00
<para > Returns the height of the raster.</para>
2010-04-05 02:28:54 +00:00
</refsection>
<refsection >
<title > Examples</title>
2010-04-05 04:30:44 +00:00
<programlisting > SELECT rid, ST_Height(rast) As rastheight
FROM dummy_rast;
2010-04-05 02:28:54 +00:00
2010-04-05 04:30:44 +00:00
rid | rastheight
-----+------------
1 | 20
2 | 5
2010-04-05 02:28:54 +00:00
</programlisting>
</refsection>
2010-04-05 04:30:44 +00:00
<refsection >
<title > See Also</title>
<para > <xref linkend= "RT_ST_Width" /> </para>
</refsection>
</refentry>
<refentry id= "RT_ST_NumBands" >
<refnamediv >
<refname > ST_NumBands</refname>
<refpurpose > Returns the number of bands in the raster object.</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
<funcdef > integer <function > ST_NumBands</function> </funcdef>
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
<para > Returns the number of bands in the raster object.</para>
</refsection>
<refsection >
<title > Examples</title>
<programlisting > SELECT rid, ST_NumBands(rast) As numbands
FROM dummy_rast;
rid | numbands
----+----------
1 | 0
2 | 3
</programlisting>
</refsection>
2010-04-05 02:28:54 +00:00
<!-- Optionally add a "See Also" section -->
<refsection >
<title > See Also</title>
2010-04-05 04:30:44 +00:00
<para > <xref linkend= "RT_ST_Value" /> </para>
2010-04-05 02:28:54 +00:00
</refsection>
</refentry>
2010-04-05 04:30:44 +00:00
<refentry id= "RT_ST_PixelSizeX" >
2010-04-05 02:28:54 +00:00
<refnamediv >
2010-04-05 04:30:44 +00:00
<refname > ST_PixelSizeX</refname>
<refpurpose > Returns the x size of pixels in units of coordinate reference system?</refpurpose>
2010-04-05 02:28:54 +00:00
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
2010-04-05 04:30:44 +00:00
<funcdef > float8 <function > ST_PixelSizeX</function> </funcdef>
2010-04-05 02:28:54 +00:00
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
2010-04-05 04:30:44 +00:00
<para > Returns the x size of pixels in units of coordinate reference system?</para>
2010-04-05 02:28:54 +00:00
</refsection>
<refsection >
<title > Examples</title>
2010-04-05 04:30:44 +00:00
<programlisting > SELECT rid, ST_PixelSizeX(rast) As rastpixwidth
FROM dummy_rast;
2010-04-05 02:28:54 +00:00
2010-04-05 04:30:44 +00:00
rid | rastpixwidth
-----+--------------
1 | 2
2 | 0.05
2010-04-05 02:28:54 +00:00
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection >
<title > See Also</title>
2010-04-05 04:30:44 +00:00
<para > <xref linkend= "RT_ST_Width" /> </para>
2010-04-05 02:28:54 +00:00
</refsection>
</refentry>
2010-04-05 04:30:44 +00:00
<refentry id= "RT_ST_PixelSizeY" >
2010-04-05 01:32:30 +00:00
<refnamediv >
2010-04-05 04:30:44 +00:00
<refname > ST_PixelSizeY</refname>
<refpurpose > Returns the y size of pixels in units of coordinate reference system?</refpurpose>
2010-04-05 01:32:30 +00:00
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
2010-04-05 04:30:44 +00:00
<funcdef > float8 <function > ST_PixelSizeY</function> </funcdef>
2010-04-05 01:32:30 +00:00
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
2010-04-05 04:30:44 +00:00
<para > Returns the y size of pixels in units of coordinate reference system?</para>
2010-04-05 01:32:30 +00:00
</refsection>
<refsection >
<title > Examples</title>
2010-04-05 04:30:44 +00:00
<programlisting > SELECT rid, ST_PixelSizeY(rast) As rastpixheight
FROM dummy_rast;
2010-04-05 01:05:46 +00:00
2010-04-05 04:30:44 +00:00
rid | rastpixheight
-----+---------------
1 | 3
2 | -0.05 --this might be a bug
2010-04-05 01:32:30 +00:00
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection >
<title > See Also</title>
<para > <xref linkend= "RT_ST_Height" /> </para>
</refsection>
</refentry>
2010-04-05 02:28:54 +00:00
<refentry id= "RT_ST_SRID" >
<refnamediv >
<refname > ST_SRID</refname>
<refpurpose > Returns the spatial reference identifier of the raster as defined in spatial_ref_sys table.</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
<funcdef > integer <function > ST_SRID</function> </funcdef>
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
<para > Returns the spatial reference identifier of the raster object as defined in the spatial_ref_sys table.</para>
<note > <para > From PostGIS 2.0+ the srid of a non-georeferenced raster/geometry is 0 instead of the prior -1.</para> </note>
</refsection>
<refsection >
<title > Examples</title>
<programlisting > SELECT ST_SRID(rast) As srid
FROM dummy_rast WHERE rid=1;
srid
----------------
0
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection >
<title > See Also</title>
<para > <xref linkend= "spatial_ref_sys" /> , <xref linkend= "ST_SRID" /> </para>
</refsection>
</refentry>
<refentry id= "RT_ST_Value" >
<refnamediv >
<refname > ST_Value</refname>
<refpurpose > Returns the value of a given band in a given columnx, rowy pixel. Band numbers start at 1.</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
<funcdef > integer <function > ST_Value</function> </funcdef>
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
<paramdef > <type > integer </type> <parameter > bandnum</parameter> </paramdef>
<paramdef > <type > integer </type> <parameter > columnx</parameter> </paramdef>
<paramdef > <type > integer </type> <parameter > rowy</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
<para > Returns the value of a given band in a given columnx, rowy pixel. Band numbers start at 1.</para>
</refsection>
<refsection >
<title > Examples</title>
<programlisting > <!-- TODO: Examples needed -->
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection >
<title > See Also</title>
<para > <xref linkend= "RT_ST_NumBands" /> </para>
</refsection>
</refentry>
2010-04-05 04:30:44 +00:00
<refentry id= "RT_ST_Width" >
<refnamediv >
<refname > ST_Width</refname>
<refpurpose > Returns the width of the raster in pixels?</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
<funcdef > integer <function > ST_Width</function> </funcdef>
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
<para > Returns the width of the raster.</para>
</refsection>
<refsection >
<title > Examples</title>
<programlisting > SELECT ST_Width(rast) As rastwidth
FROM dummy_rast WHERE rid=1;
rastwidth
----------------
10
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection >
<title > See Also</title>
<para > <xref linkend= "RT_ST_Height" /> </para>
</refsection>
</refentry>
2010-04-05 01:32:30 +00:00
</sect1>
<sect1 id= "Raster_Outputs" >
<title > Raster Outputs</title>
<refentry id= "RT_ST_AsBinary" >
<refnamediv >
<refname > ST_AsBinary</refname>
<refpurpose > Return the Well-Known Binary (WKB) representation of the raster without SRID meta data.</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcprototype >
<funcdef > bytea <function > ST_AsBinary</function> </funcdef>
<paramdef > <type > raster </type> <parameter > rast</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection >
<title > Description</title>
<para > 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.</para>
<para > This is useful in binary cursors to pull data out of the
database without converting it to a string representation.</para>
</refsection>
<refsection >
<title > Examples</title>
2010-04-05 02:28:54 +00:00
<programlisting > SELECT ST_AsBinary(rast) As rastbin
FROM dummy_rast WHERE rid=1;
2010-04-05 01:32:30 +00:00
rastbin
2010-04-05 01:05:46 +00:00
---------------------------------------------------------------------------------
2010-04-05 01:32:30 +00:00
\001\000\000\000\000\000\000\000\000\000\000\000@\000\000\000\000\000\000\010@\
2010-04-05 01:05:46 +00:00
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
2010-04-05 01:32:30 +00:00
</programlisting>
2010-04-05 01:05:46 +00:00
2010-04-05 01:32:30 +00:00
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection >
<title > See Also</title>
<para > </para>
</refsection>
</refentry>
</sect1>
2010-04-05 01:05:46 +00:00
</chapter>
