postgis/doc/using_raster_dataman.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="using_raster.xml">
  <title>Raster Data Management and Queries</title>
  <sect1 id="RT_Loading_Rasters"> 
    <title>Loading and Creating Rasters</title>
    <para>For most use cases, you will create PostGIS rasters by loading existing raster files using the packaged <varname>raster2pgsql</varname> raster loader.</para>

    <para>
        The <varname>raster2pgsql</varname> is a raster loader executable that loads GDAL supported raster formats into sql suitable for loading into a PostGIS raster table.
        It is capable of loading folders of raster files as well as creating overviews of rasters. </para>
    <para>Since the raster2pgsql is compiled as part of PostGIS most often (unless you compile your own GDAL library), the raster types supported
    	by the executable will be the same as those compiled in the GDAL dependency library.  To get a list of raster types your particular PostGIS install
    	supports, refer to  <xref linkend="RT_ST_GDALDrivers" />.</para>
    <note>
    	<para>The older version of this tool was a python script.  The executable has replaced the python script.  If you still find the need for the Python script
        Examples of the pyhton one can be found at <ulink url="http://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html">GDAL PostGIS Raster Driver Usage</ulink> 
        </para></note>
        
    <para>EXAMPLE USAGE: 
    	<programlisting>raster2pgsql <varname>raster_options_go_here</varname> <varname>raster_file</varname> <varname>someschema</varname>.<varname>sometable</varname> &gt; out.sql</programlisting>
    </para>
    <variablelist>
         <varlistentry>
          <term>-?</term>
          <listitem>
            <para>
              Display help screen.  Help will also display if you don't pass in any arguments.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>(c|a|d) These are mutually exclusive options:</term>
          <listitem>
            <para>
              <variablelist>
                <varlistentry>
                  <term>-c</term>
                  <listitem>
                    <para>
                      Create new table and populate it with raster(s), <emphasis>this is the default mode</emphasis>
                    </para>
                  </listitem>
                </varlistentry>
    
                <varlistentry>
                  <term>-a</term>
                  <listitem>
                    <para>
                      Append raster(s) to an existing table.
                    </para>
                  </listitem>
                </varlistentry>
    
                <varlistentry>
                  <term>-d</term>
                  <listitem>
                    <para>
                      Drop table, create new one and populate it with raster(s)
                    </para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </para>
          </listitem>
        </varlistentry>
     
        <varlistentry>
          <term>Raster processing: Optional parameters used to manipulate input raster dataset</term>
          <listitem>
            <para>
              <variablelist>
              	<varlistentry>
                    <term>-C </term>
                    <listitem>
                        <para>
                            Apply raster constraints -- srid, pixelsize etc. to ensure raster is properly registered in <varname>raster_columns</varname> view.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>-s &lt;SRID&gt;</term>
                    <listitem>
                        <para>
                            Assign output raster with specified SRID.
                        </para>
                    </listitem>
                </varlistentry>
                
                <varlistentry>
                    <term>-b BAND</term>
                    <listitem>
                        <para>
                           Index (1-based) of band to extract from raster.  For more than one band index, separate with comma (,).  If unspecified,
                           all bands of raster will be extracted.
                        </para>
                    </listitem>
                </varlistentry>
                
                <varlistentry>
                    <term>-t TILE_SIZE</term>
                    <listitem>
                        Cut raster into tiles to be inserted one per table row.  <varname>TILE_SIZE</varname> is expressed as WIDTHxHEIGHT.
                    </listitem>
                </varlistentry>
                
                <varlistentry>
                    <term>-R, --register</term>
                    <listitem>
                        <para>Register the raster as a filesystem (out-db) raster.</para>
                        <para>Only the metadata of the raster and path location to the raster is stored in the database (not the pixels).</para>
                    </listitem>
                </varlistentry>
                
                <varlistentry>
                    <term>-l <varname>OVERVIEW_FACTOR</varname></term>
                    <listitem><para> -l <varname>overview factor</varname> Create overview of the raster.  For more than
     one factor, separate with comma(,).  Overview table name follows
     the pattern o_<varname>overview factor</varname>_<varname>table</varname>.  Created overview is
     stored in the database and is not affected by -R. Note that your generated sql file will contain both the main table and overview tables.</para>
                    </listitem>
                </varlistentry>
              </variablelist>
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term>Optional parameters used to manipulate database objects</term>
          <listitem>
            <para>
              <variablelist>  
              	  <varlistentry>
                  <term>-q </term>
                  <listitem>
                    <para>Wrap PostgreSQL identifiers in quotes
                    </para>
                  </listitem>
                </varlistentry>
                <varlistentry>
                  <term>-f COLUMN</term>
                  <listitem>
                    <para>Specify name of destination raster column, default is 'rast'
                    </para>
                  </listitem>
                </varlistentry>
                
                <varlistentry>
                  <term>-F</term>
                  <listitem>
                    <para>Add a column with the name of the file</para>
                  </listitem>
                </varlistentry>
               
                <varlistentry>
                  <term>-I</term>
                  <listitem>
                    <para>
                      Create a GiST index on the raster column.
                    </para>
                  </listitem>
                </varlistentry>
                
                <varlistentry>
                  <term>-M</term>
                  <listitem>
                    <para>
                      Vacuum analyze the raster table.
                    </para>
                  </listitem>
                </varlistentry>
                
                <varlistentry>
                  <term>-T <varname>tablespace</varname></term>
                  <listitem>
                    <para>
                      Specify the tablespace for the new table.
     Note that indices (including the primary key) will still use
     the default tablespace unless the -X flag is also used.
                    </para>
                  </listitem>
                </varlistentry>
                
               <varlistentry>
                  <term>-Y</term>
                  <listitem>
                    <para>
                      Use copy statements instead of insert statements.</para>
                  </listitem>
                </varlistentry>
                
              </variablelist>
            </para>
          </listitem>
        </varlistentry>
       
        <varlistentry>
            <term>-e</term>
            <listitem><para>Execute each statement individually, do not use a transaction.</para></listitem>
        </varlistentry>
        
        <varlistentry>
            <term>-E ENDIAN</term>
            <listitem><para>Control endianness of generated binary output of raster; specify 0 for XDR and 1 for NDR (default); only NDR output is supported now</para></listitem>
        </varlistentry>
       
        <varlistentry>
            <term>-V <varname>version</varname></term>
            <listitem><para>Specify version of output format.  Default  is 0.  Only 0 is supported at this time.</para></listitem>
        </varlistentry>
    </variablelist>  
    <para>An example session using the loader to create an input file and uploading it might look like this:</para>
    <programlisting>raster2pgsql -s 4236 -I -C -M *.tif -F -t myschema.demelevation > elev.sql
psql -d gisdb -f elev.sql</programlisting>
        
    <para>A conversion and upload can be done all in one step using UNIX pipes:</para>
        
    <programlisting>raster2pgsql -s 4236 -I -C -M *.tif -F -t myschema.demelevation | psql -d gisdb</programlisting>
    
    <para>Load rasters Massachusetts state plane meters aerial tiles 
    	into a schema called <varname>aerial</varname> and create a full view, 2 and 4 level overview tables and directly insert to database.  Break up the rasters into 100x100 pixel tiles and apply raster constraints. Use copy mode instead of table insert. (-F) Include a field called filename to hold the name of the file the tiles were cut from.</para>
    <programlisting>raster2pgsql -I -C -Y -F -s 26986 -t 100x100  -l 2,4 bostonaerials2008\*.jpg aerials.boston | psql -U postgres -d gisdb -h localhost -p 5432</programlisting>
 
  </sect1>
   <sect1 id="RT_Raster_Catalog"> 
   		<title>Raster Catalogs</title>
   		<para>There are two raster catalog views that come package with PostGIS.  Both views utilize information embedded in the constraints of the raster tables.  As a result
   		the catalog views are always consistent with the raster data in the tables since the constraints are enforced. </para>
   		 <orderedlist>
          <listitem>
            <para><varname>raster_columns</varname> this view catalogs all the raster tables in your database.</para>
          </listitem>
          <listitem>
            <para><varname>raster_overviews</varname> this view catalogs all the rasters tables in your database that server as overviews for a finer grained table.  Tables of this type are generated when you use the <varname>-l</varname> switch during load.</para>
          </listitem>
        </orderedlist>
        <sect2 id="RT_Raster_Columns">
        	<title>Raster Columns Catalog</title>
        	<para>The <varname>raster_columns</varname> is a catalog of all columns in the table taht are of type raster.  It is a view utilizing the constraints on the tables
        	so the information is always consistent even if you restore one raster table from a backup of another database.  The following columns exist in the <varname>raster_columns</varname> catalog.</para>
        	<para>If you created your tables not with the loader or forgot to specified the <varname>-C</varname> flag during load, you can enforce the constraints after the 
        	fact using <xref linkend="RT_AddRasterConstraints" /> so that the <varname>raster_columns</varname> catalog registers the common information after your raster tiles.</para>
        	
			 <itemizedlist>
				<listitem>
					<para><varname>r_table_catalog</varname> The database the table is in.  This will always read the current database.</para>
				</listitem>
				<listitem>
					<para><varname>r_table_schema</varname> The database schema the raster table belongs to.</para>
				</listitem>
				<listitem>
					<para><varname>r_table_name</varname> raster table</para>
				</listitem>
				<listitem>
					<para><varname>r_raster_column</varname> the column in the <varname>r_table_name</varname> table that is of type raster.  There is nothing in PostGIS preventing you from having multiple raster columns per table so its possible to have a raster table listed multiple times with a different raster column for each.</para>
				</listitem>
				<listitem>
					<para><varname>srid</varname> The spatial reference identifier of the raster.  Should be an entry in the <xref linkend="spatial_ref_sys" />.</para>
				</listitem>
				<listitem>
					<para><varname>scale_x</varname> The scaling between geometric spatial coordinates and pixel.  This is only available if all tiles in the raster column have the same <varname>scale_x</varname> and this constraint is applied. Refer to <xref linkend="RT_ST_ScaleX" /> for more details.</para>
				</listitem>
				<listitem>
					<para><varname>scale_y</varname> The scaling between geometric spatial coordinates and pixel.  This is only available if all tiles in the raster column have the same <varname>scale_y</varname> and the <varname>scale_y</varname> constraint is applied. Refer to <xref linkend="RT_ST_ScaleY" /> for more details.</para>
				</listitem>
				<listitem>
					<para><varname>blocksize_x</varname> The width (number of pixels across) of each raster tile . Refer to <xref linkend="RT_ST_Width" /> for more details.</para>
				</listitem>
				<listitem>
					<para><varname>blocksize_y</varname> The width (number of pixels down) of each raster tile . Refer to <xref linkend="RT_ST_Height" /> for more details.</para>
				</listitem>
				<listitem>
					<para><varname>same_alignment</varname> A boolean that is true if all the raster tiles have the same alignment . Refer to <xref linkend="RT_ST_SameAlignment" /> for more details.</para>
				</listitem>
				<listitem>
					<para><varname>regular_blocking</varname> This is a true/false constraint flag set on the table to denote that the tiles do not overlap, are of the same alignment, pixel size, srid etc. It is not really validated but just taken as a given so should be used for informational.  In the future we plan to properly constrain this so that this inforamtion is guaranteed to be right when it returns <varname>true</varname></para>
				</listitem>
				<listitem>
					<para><varname>num_bands</varname> The number of bands in each tile of your raster set.  This is the same information as what is provided by <xref linkend="RT_ST_NumBands" /></para>
				</listitem>
				<listitem>
					<para><varname>pixel_types</varname> An array defining the pixel type for each band.  You will have the same number of elements in this array as you have number of bands.  The pixel_types are one of the following defined in <xref linkend="RT_ST_BandPixelType" />.</para>
				</listitem>
				<listitem>
					<para><varname>nodata_values</varname> An array of double precision numbers denoting the <varname>nodata_value</varname> for each band.  You will have the same number of elements in this array as you have number of bands. These numbers define the pixel value for each band that should be ignored for most operations.  This is similar information provided by <xref linkend="RT_ST_BandNoDataValue" />.</para>
				</listitem>
				<listitem>
					<para><varname>extent</varname> This is the extent of all the raster rows in your raster set. If you plan to load more data that will change the extent of the set, you'll want to drop the <xref linkend="RT_DropRasterConstraints" /> function before load and then reapply constraints with <xref linkend="RT_AddRasterConstraints"  /> after load. </para>
				</listitem>
			 </itemizedlist>
        </sect2>
        <sect2 id="RT_Raster_Overviews">
        	<title>Raster Overviews</title>
        	<para><varname>raster_overviews</varname> catalogs information about raster table columns used for overviews and additional information about them that is useful to know when utilizing overviews. Overview tables are cataloged in both <varname>raster_columns</varname> and <varname>raster_overviews</varname> because they are rasters in their own right but also serve an additional special purpose of being a lower resolution caricature of a higher resolution table. These are generated along-side the main raster table when you use the <varname>-l</varname> switch in raster loading.</para>
        	<para>Overview tables contain the same constraints as other raster tables as well as additional informational only constraints specific to overviews.</para>
        	<note><para>The informaiton in <varname>raster_overviews</varname> does not duplicate the information in <varname>raster_columns</varname>.  IF you need the information about an overview table present in <varname>raster_columns</varname> you can join the <varname>raster_overviews</varname> and <varname>raster_columns</varname> vuews together to get the full set of information you need.</para> </note>
        	<para>Two main reasons for overviews are:</para>
        	 <itemizedlist>
        		<listitem>Low resolution representation of the core tables commonly used for fast mapping zoom-out.</listitem>
        		<listitem>Computations are generally faster to do on them than their higher resolution parents because there are fewer records and each pixel covers more territory.  Though the computations are not as accurate as the high-res tables they support, they can be sufficient in many rule-of-thumb computations.</listitem>
        	</itemizedlist>
        	
        	<para>The <varname>raster_overviews</varname> catalog contains the following columns of information.</para>
			 <itemizedlist>
				<listitem>
					<para><varname>o_table_catalog</varname> The database the overview table is in.  This will always reads the current database.</para>
				</listitem>
				<listitem>
					<para><varname>o_table_schema</varname> The database schema the overview raster table belongs to.</para>
				</listitem>
				<listitem>
					<para><varname>o_table_name</varname> raster overview table name</para>
				</listitem>
				<listitem>
					<para><varname>o_raster_column</varname> the raster column in the overview table.</para>
				</listitem>
				
				<listitem>
					<para><varname>r_table_catalog</varname> The database the raster table that this overview services is in.  This will always read the current database.</para>
				</listitem>
				<listitem>
					<para><varname>r_table_schema</varname> The database schema the raster table that this overview services belongs to.</para>
				</listitem>
				<listitem>
					<para><varname>r_table_name</varname> raster table that this overview services.</para>
				</listitem>
				<listitem>
					<para><varname>r_raster_column</varname> the raster column that this overview column services.</para>
				</listitem>
				<listitem>
					<para><varname>overview_factor</varname> - this is the pyramid level of the overview table.  The higher the number the lower the resolution of the table.</para>
				</listitem>
			 </itemizedlist>
        </sect2>
   </sect1>
</chapter>