From 07e0193feddd5aaa47f0c9aa67bfc6d3dbcd4fd0 Mon Sep 17 00:00:00 2001
From: Regina Obe <lr@pcorp.us>
Date: Mon, 5 Apr 2010 02:28:54 +0000
Subject: [PATCH] more accessors

git-svn-id: http://svn.osgeo.org/postgis/trunk@5485 b70326c6-7e19-0410-871a-916f4a2858ee
---
 doc/reference_wktraster.xml | 249 ++++++++++++++++++++++++++++++------
 1 file changed, 212 insertions(+), 37 deletions(-)

diff --git a/doc/reference_wktraster.xml b/doc/reference_wktraster.xml
index a97cfdd7f..b9baa779e 100644
--- a/doc/reference_wktraster.xml
+++ b/doc/reference_wktraster.xml
@@ -12,9 +12,9 @@
   <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(rast raster);
-INSERT INTO dummy_rast(rast)
-VALUES(
+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)
@@ -33,7 +33,7 @@ VALUES(
 ||
 '0000000000000000' -- skewY (float64 0)
 ||
-'0A000000' -- SRID (int32 10)
+'00000000' -- SRID (int32 0)
 ||
 '0A00' -- width (uint16 10)
 ||
@@ -43,7 +43,7 @@ VALUES(
   </programlisting>
   
 	<sect1 id="Raster_Accessors">
-		<title>Raster Accessorts</title>
+		<title>Raster Accessors</title>
 		<refentry id="RT_ST_Height">
 			<refnamediv>
 				<refname>ST_Height</refname>
@@ -69,7 +69,7 @@ VALUES(
 					<title>Examples</title>
 				
 					<programlisting>SELECT ST_Height(rast) As rastheight
-FROM dummy_rast LIMIT 1;
+FROM dummy_rast WHERE rid=1;
 
 rastheight
 ----------------
@@ -84,6 +84,129 @@ rastheight
 				<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>
@@ -109,7 +232,7 @@ rastheight
 					<title>Examples</title>
 				
 					<programlisting>SELECT ST_Width(rast) As rastwidth
-FROM dummy_rast LIMIT 1;
+FROM dummy_rast WHERE rid=1;
 
 rastwidth
 ----------------
@@ -124,6 +247,86 @@ rastwidth
 				<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">
@@ -156,36 +359,8 @@ rastwidth
 				<refsection>
 					<title>Examples</title>
 				
-					<programlisting>CREATE TABLE dummy_rast(rast raster);
-INSERT INTO dummy_rast(rast)
-VALUES(
-('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)
-||
-'0A000000' -- SRID (int32 10)
-||
-'0A00' -- width (uint16 10)
-||
-'1400' -- height (uint16 20)
-)::raster
-);			
-SELECT ST_AsBinary(rast) As rastbin
-FROM dummy_rast LIMIT 1;
+					<programlisting>SELECT ST_AsBinary(rast) As rastbin
+FROM dummy_rast WHERE rid=1;
 
 					 rastbin
 ---------------------------------------------------------------------------------
-- 
2.40.0