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">
        	<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="AddRasterConstraints" /> so that the <varname>raster_columns</varname> catalog registers the common information after your raster tiles.</para>
        	
			<orderedlist>
				<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 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 if the tiles form a complete rectangle. It is not really validated but just taken as a given.</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>
			</orderedlist>
        </sect2>
   </sect1>
</chapter>