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
),
-- Raster: 5 x 5 pixels, 3 bands, PT_8BUI pixel type, NODATA = 0
(2,  ('01000003009A9999999999A93F9A9999999999A9BF000000E02B274A' ||
'41000000007719564100000000000000000000000000000000FFFFFFFF050005000400FDFEFDFEFEFDFEFEFDF9FAFEF' ||
'EFCF9FBFDFEFEFDFCFAFEFEFE04004E627AADD16076B4F9FE6370A9F5FE59637AB0E54F58617087040046566487A1506CA2E3FA5A6CAFFBFE4D566DA4CB3E454C5665')::raster);
  </programlisting>
  	<sect1 id="Raster_Constructors">
  		<title>Raster Constructors</title>
  		<refentry id="RT_ST_MakeEmptyRaster">
			<refnamediv>
				<refname>ST_MakeEmptyRaster</refname>
				<refpurpose>Returns an empty raster of given dimensions, pixel x y, skew and spatial reference system with no bands</refpurpose>
			</refnamediv>
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>raster <function>ST_MakeEmptyRaster</function></funcdef>
					<paramdef><type>integer </type> <parameter>width</parameter></paramdef>
					<paramdef><type>integer </type> <parameter>height</parameter></paramdef>
					<paramdef><type>float8 </type> <parameter>ipx</parameter></paramdef>
					<paramdef><type>float8 </type> <parameter>ipy</parameter></paramdef>
					<paramdef><type>float8 </type> <parameter>scalex</parameter></paramdef>
					<paramdef><type>float8 </type> <parameter>scaley</parameter></paramdef>
					<paramdef><type>float8 </type> <parameter>skewx</parameter></paramdef>
					<paramdef><type>float8 </type> <parameter>skewy</parameter></paramdef>
					<paramdef><type>integer </type> <parameter>srid</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>
INSERT INTO dummy_rast(rid,rast)
VALUES(3, ST_MakeEmptyRaster( 100, 100, 0.0005, 0.0005, 1, 1, 0, 0, 4326) )
				</programlisting>
			
			</refsection>

			<refsection>
				<title>See Also</title>
				<para></para>
			</refsection>
		</refentry>
  	</sect1>
	<sect1 id="Raster_Accessors">
		<title>Raster Accessors</title>
		<refentry id="RT_ST_BandNoDataValue">
			<refnamediv>
				<refname>ST_BandNoDataValue</refname>
				<refpurpose>Returns the value in a given band that represents no data.</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_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
				</programlisting>
			
			</refsection>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_NumBands" /></para>
			</refsection>
		</refentry>
		
		<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>text <function>ST_BandPixelType</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>
				<para>Pixel Types supported are as follows:
					<itemizedlist>
						<listitem>
						  <para>1BB -  1-bit boolean</para>
						</listitem>
						
						<listitem>
						  <para>2BUI - 2-bit unsigned integer</para>
						</listitem>
		
						<listitem>
						  <para>4BUI - 4-bit unsigned integer </para>
						</listitem>
		
						<listitem>
						  <para>8BSI - 8-bit signed integer </para>
						</listitem>
						<listitem>
						  <para>8BUI - 8-bit unsigned integer</para>
						</listitem>
						<listitem>
						  <para>16BSI - 16-bit signed integer</para>
						</listitem>
						<listitem>
						  <para>16BUI - 16-bit unsigned integer</para>
						</listitem>
						<listitem>
						  <para>16BUI - 16-bit unsigned integer</para>
						</listitem>
						<listitem>
						  <para>32BSI - 32-bit signed integer</para>
						</listitem>
						<listitem>
						  <para>32BUI - 32-bit unsigned integer</para>
						</listitem>
						<listitem>
						  <para>16BF - 16-bit float</para>
						</listitem>
						<listitem>
						  <para>32BF - 32-bit float</para>
						</listitem>
						<listitem>
						  <para>64BF - 64-bit float</para>
						</listitem>
					</itemizedlist>
				</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>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_NumBands" /></para>
			</refsection>
		</refentry>
		
		<refentry id="RT_ST_Box2D">
			<refnamediv>
				<refname>ST_Box2D</refname>
				<refpurpose>Returns the box 2d representation of the enclosing box of the raster</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>box2d<function>ST_Box2D</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>Returns the box representing the extent of the raster.</para>
				<para>The polygon is defined by the corner points of the bounding box
			((<varname>MINX</varname>, <varname>MINY</varname>),
			(<varname>MAXX</varname>, <varname>MAXY</varname>))</para>
			</refsection>
				
			<refsection>
				<title>Examples</title>
			
				<programlisting>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)
			</programlisting>
			
			</refsection>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_Envelope" /></para>
			</refsection>
		</refentry>
		
		<refentry id="RT_ST_Envelope">
			<refnamediv>
				<refname>ST_Envelope</refname>
				<refpurpose>Returns the polygon representation of the extent of the raster.</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>geometry <function>ST_Envelope</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>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. </para>
				<para>The polygon is defined by the corner points of the bounding box
			((<varname>MINX</varname>, <varname>MINY</varname>),
			(<varname>MINX</varname>, <varname>MAXY</varname>),
			(<varname>MAXX</varname>, <varname>MAXY</varname>),
			(<varname>MAXX</varname>, <varname>MINY</varname>),
			(<varname>MINX</varname>, <varname>MINY</varname>))</para>
				</refsection>
				
				<refsection>
					<title>Examples</title>
				
					<programlisting>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))
				</programlisting>
			
			</refsection>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="ST_Envelope" />, <xref linkend="ST_AsText" />, <xref linkend="RT_ST_SRID" /></para>
			</refsection>
		</refentry>
		
		<refentry id="RT_ST_GeoReference">
			<refnamediv>
				<refname>ST_GeoReference</refname>
				<refpurpose>Returns the georeference meta data in GDAL or ESRI format. Default is GDAL.</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>text <function>ST_GeoReference</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
				  </funcprototype>
				  <funcprototype>
					<funcdef>text <function>ST_GeoReference</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
					<paramdef><type>text </type> <parameter>format</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<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>: 
<programlisting>pixelsizex 
skewy 
skewx
pixelsizey
upperleftx
upperlefty</programlisting></para>
				<para><varname>ESRI</varname>: 
<programlisting>pixelsizex 
skewy 
skewx
pixelsizey
upperleftx + pixelsizex*0.5
upperlefty + pixelsizey*0.5</programlisting></para>
			</refsection>
				
			<refsection>
				<title>Examples</title>
			
				<programlisting>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
				</programlisting>	
			</refsection>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_PixelSizeX" />, <xref linkend="RT_ST_PixelSizeY" /></para>
			</refsection>
		</refentry>
		
		<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 rid, ST_Height(rast) As rastheight
FROM dummy_rast;

 rid | rastheight
-----+------------
   1 |         20
   2 |          5
				</programlisting>
			
			</refsection>

			<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>
		
			<!-- 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 rid, ST_PixelSizeX(rast) As rastpixwidth
FROM dummy_rast;

 rid | rastpixwidth
-----+--------------
   1 |            2
   2 |         0.05
				</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.  May be negative.  Refer to <ulink url="http://en.wikipedia.org/wiki/World_file">World File</ulink>
				for more details.</para>
				</refsection>
				
				<refsection>
					<title>Examples</title>
				
					<programlisting>SELECT rid, ST_PixelSizeY(rast) As rastpixheight
FROM dummy_rast;

 rid | rastpixheight
-----+---------------
   1 |             3
   2 |         -0.05
				</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_UpperLeftX">
			<refnamediv>
				<refname>ST_UpperLeftX</refname>
				<refpurpose>Returns the upper left x coordinate of raster in projected spatial ref.</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>float8 <function>ST_UpperLeftX</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>Returns the upper left x coordinate of raster in projected spatial ref.</para>
				</refsection>
				
				<refsection>
					<title>Examples</title>
				
					<programlisting>
SELECt rid, ST_UpperLeftX(rast) As ulx
FROM dummy_rast;

 rid |    ulx
-----+------------
   1 |        0.5
   2 | 3427927.75
				</programlisting>
			
			</refsection>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_UpperLeftY" />, <xref linkend="RT_ST_GeoReference" />, <xref linkend="RT_ST_Box2D" /></para>
			</refsection>
		</refentry>
		
		<refentry id="RT_ST_UpperLeftY">
			<refnamediv>
				<refname>ST_UpperLeftY</refname>
				<refpurpose>Returns the upper left y coordinate of raster in projected spatial ref.</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>float8 <function>ST_UpperLeftY</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>Returns the upper left y coordinate of raster in projected spatial ref.</para>
				</refsection>
				
				<refsection>
					<title>Examples</title>
				
					<programlisting>
SELECT rid, ST_UpperLeftY(rast) As uly
FROM dummy_rast;

 rid |   uly
-----+---------
   1 |     0.5
   2 | 5793244
				</programlisting>
			
			</refsection>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_UpperLeftX" />, <xref linkend="RT_ST_GeoReference" />, <xref linkend="RT_ST_Box2D" /></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>
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
				</programlisting>
				
				<programlisting>
--- 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 &lt;= ST_Width(rast) AND y &lt;= 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
 :
 :
				</programlisting>
			
			</refsection>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_NumBands" /></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>
	</sect1>
	
	<sect1 id="Raster_Editors">
		<title>Raster Editors</title>
		<refentry id="RT_ST_SetBandNoDataValue">
			<refnamediv>
				<refname>ST_SetBandNoDataValue</refname>
				<refpurpose>Sets the value for the given band that represents no data.</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>integer <function>ST_SetBandNoDataValue</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
					<paramdef><type>integer </type> <parameter>bandnum</parameter></paramdef>
					<paramdef><type>double precision </type> <parameter>val</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>Returns the value that represents no data for the band.  This will effect ST_Polygon and ST_ConvexHull results.</para>
				</refsection>
				
				<refsection>
					<title>Examples</title>
				
					<programlisting>-- 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;
					</programlisting>
			
			</refsection>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_BandNoDataValue" />,<xref linkend="RT_ST_NumBands" /></para>
			</refsection>
		</refentry>
		
		<refentry id="RT_ST_SetPixelSize">
			<refnamediv>
				<refname>ST_SetPixelSize</refname>
				<refpurpose>Sets the x and y size of pixels in units of coordinate reference system. Number units/pixel width/height</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>raster <function>ST_SetPixelSize</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
					<paramdef><type>float8 </type> <parameter>xy</parameter></paramdef>
				  </funcprototype>
				  
				  <funcprototype>
					<funcdef>raster <function>ST_SetPixelSize</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
					<paramdef><type>float8 </type> <parameter>x</parameter></paramdef>
					<paramdef><type>float8 </type> <parameter>y</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>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.</para>
				</refsection>
				
				<refsection>
					<title>Examples</title>
				
					<programlisting>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)
				</programlisting>
				<programlisting>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)
				</programlisting>
			
			</refsection>

			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_PixelSizeX" />, <xref linkend="RT_ST_PixelSizeY" />, <xref linkend="RT_ST_Box2D" /></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>
	
	<sect1 id="Raster_Processing">
		<title>Raster Processing Functions</title>
		<refentry id="RT_ST_ConvexHull">
			<refnamediv>
				<refname>ST_ConvexHull</refname>
				<refpurpose>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.</refpurpose>
			</refnamediv>
		
			<refsynopsisdiv>
				<funcsynopsis>
				  <funcprototype>
					<funcdef>geometry <function>ST_ConvexHull</function></funcdef>
					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
				  </funcprototype>
				</funcsynopsis>
			</refsynopsisdiv>
		
			<refsection>
				<title>Description</title>
				
				<para>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.</para>
				
				<para><note>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.</note>
				</para>
			</refsection>
				
			<refsection>
				<title>Examples</title>
				<para>Refer to <ulink url="http://trac.osgeo.org/postgis/wiki/WKTRaster/SpecificationWorking01">WKT Raster Specification</ulink>
					 for a diagram of this.</para>
				<informaltable>
				  <tgroup cols="2">
					<tbody>
					  <row>
						<entry>
							<para> <!-- TODO: Put in pictures -->
<programlisting>-- 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))
 </programlisting>
						</para>
					</entry>

					<entry>
						<para> <!-- TODO: Put in pictures -->
				<programlisting> 
-- 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))
				</programlisting>
						</para>
					</entry>
			</row>
		</tbody>
		</tgroup>
		</informaltable>
			</refsection>
		
			<!-- Optionally add a "See Also" section -->
			<refsection>
				<title>See Also</title>
				<para><xref linkend="RT_ST_Envelope" />, <xref linkend="ST_ConvexHull" />, <xref linkend="ST_AsText" /></para>
			</refsection>
		</refentry>
	</sect1>
</chapter>