postgis/doc/reference_wktraster.xml

<?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>
  <para>For the examples in this reference we will be using a raster table of dummy rasters - Formed with the following code </para>
  <programlisting>
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
);
  </programlisting>
  
	<sect1 id="Raster_Accessors">
		<title>Raster Accessors</title>
		<refentry id="RT_ST_Height">
			<refnamediv>
				<refname>ST_Height</refname>
				<refpurpose>Returns the height of the raster in pixels?</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>integer <function>ST_Height</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>Returns the height of the raster.</para>
				</refsection>
				
				<refsection>
					<title>Examples</title>
				
					<programlisting>SELECT ST_Height(rast) As rastheight
FROM dummy_rast WHERE rid=1;

rastheight
----------------
20
				</programlisting>
			
			</refsection>
		
			<!-- Optionally add a "See Also" section -->
			<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 ST_NumBands(rast) As numbands
FROM dummy_rast WHERE rid=1;

numbands
----------------
0
				</programlisting>	
			</refsection>
		
			<!-- Optionally add a "See Also" section -->
			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_Value" /></para>
			</refsection>
		</refentry>
		
		<refentry id="RT_ST_PixelSizeX">
			<refnamediv>
				<refname>ST_PixelSizeX</refname>
				<refpurpose>Returns the x size of pixels in units of coordinate reference system?</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>float8 <function>ST_PixelSizeX</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>Returns the x size of pixels in units of coordinate reference system?</para>
				</refsection>
				
				<refsection>
					<title>Examples</title>
				
					<programlisting>SELECT ST_PixelSizeX(rast) As rastpixwidth
FROM dummy_rast WHERE rid=1;

rastpixwidth
----------------
2
				</programlisting>
			
			</refsection>
		
			<!-- Optionally add a "See Also" section -->
			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_Width" /></para>
			</refsection>
		</refentry>
		
		<refentry id="RT_ST_PixelSizeY">
			<refnamediv>
				<refname>ST_PixelSizeY</refname>
				<refpurpose>Returns the y size of pixels in units of coordinate reference system?</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>float8 <function>ST_PixelSizeY</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>Returns the y size of pixels in units of coordinate reference system?</para>
				</refsection>
				
				<refsection>
					<title>Examples</title>
				
					<programlisting>SELECT ST_PixelSizeY(rast) As rastpixheight
FROM dummy_rast WHERE rid=1;

rastpixheight
----------------
3
				</programlisting>
			
			</refsection>
		
			<!-- Optionally add a "See Also" section -->
			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_Height" /></para>
			</refsection>
		</refentry>
		
		<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>
		
		<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>
	</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>
				
					<programlisting>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 
				</programlisting>
			
			</refsection>
		
			<!-- Optionally add a "See Also" section -->
			<refsection>
				<title>See Also</title>
				<para></para>
			</refsection>
		</refentry>
	</sect1>
</chapter>