]> granicus.if.org Git - postgis/commitdiff
Add new section on loading rasters. will eventually copy some content from gdal...
authorRegina Obe <lr@pcorp.us>
Fri, 11 Feb 2011 08:56:03 +0000 (08:56 +0000)
committerRegina Obe <lr@pcorp.us>
Fri, 11 Feb 2011 08:56:03 +0000 (08:56 +0000)
git-svn-id: http://svn.osgeo.org/postgis/trunk@6799 b70326c6-7e19-0410-871a-916f4a2858ee

doc/reference_raster.xml

index c1734d82e04b46cba346ae027d6d2d7439a76e09..01d50809ba72fe3fde818d9d04fb97adc6fc2fec 100644 (file)
@@ -7,8 +7,234 @@
   functions to the raster objects which are not of use to a general
   user.</para>
   <para><varname>raster</varname> is a new PostGIS type for storing and analyzing raster data. </para>
-  <para>For more information about Raster, please refer to <ulink url="http://trac.osgeo.org/postgis/wiki/WKTRaster">PostGIS 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>
+  <para>For more information about Raster, please refer to <ulink url="http://trac.osgeo.org/postgis/wiki/WKTRaster">PostGIS Raster Home Page</ulink>.</para>  
+    <sect1 id="RT_Loading_Rasters"> 
+        <title>Loading and Creating Rasters</title>
+        <p>For most use cases, you will create PostGIS rasters by loading existing raster files using the packaged <varname>raster2pgsql</varname> raster loader.</p>
+        <sect2 id="raster2pgsql_usage">
+         <title>Using the raster2pgsql Raster Loader</title>
+          <para>
+            The <filename>raster2pgsql.py</filename> is a raster loader python script that utilizes Python, PyGDAL, and NumPy to convert any GDAL supported raster format 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>
+          
+          <variablelist>
+             <varlistentry>
+              <term>--help, -h</term>
+              <listitem>
+                <para>
+                  Display help screen.
+                </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>-o OUTPUT, --output=OUTPUT</term>
+                <listitem><para>Specify output file, otherwise send to stdout.</para></listitem>
+            </varlistentry>
+            
+           <varlistentry>
+              <term>--version</term>
+              <listitem>
+                <para>
+                  Shows program version
+                </para>
+              </listitem>
+            </varlistentry>
+            
+            <varlistentry>
+              <term>Mandatory paramters:</term>
+              <listitem>
+                <para>
+                  <variablelist>
+                    <varlistentry>
+                      <term>-r RASTER, --raster=RASTER</term>
+                      <listitem>
+                        <para>
+                         Append raster to list of input files, at least one raster file required. You may use wildcards (?,*) for specifying multiple files.
+                        </para>
+                      </listitem>
+                    </varlistentry>
+            
+                    <varlistentry>
+                      <term> -t TABLE, --table=TABLE</term>
+                      <listitem>
+                        <para>
+                            Raster destination in form of [&lt;schema&gt;.]&lt;table&gt; or base raster table for overview level>1, required
+                        </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>-s &lt;SRID&gt;</term>
+                        <listitem>
+                            <para>
+                                Assign output raster with specified SRID.
+                            </para>
+                        </listitem>
+                    </varlistentry>
+                    
+                    <varlistentry>
+                        <term>-b BAND, --band=BAND</term>
+                        <listitem>
+                            <para>
+                                Specify number of band to be extracted from raster.  If not specified all bands are added.
+                            </para>
+                        </listitem>
+                    </varlistentry>
+                    
+                    <varlistentry>
+                        <term>-k BLOCK_SIZE, --block-size=BLOCK_SIZE</term>
+                        <listitem>
+                            <para>Cut raster(s) into tiles to be inserted one by table row.BLOCK_SIZE is expressed as WIDTHxHEIGHT. Incomplete tiles are completed with nodata values.</para>
+                            <para>Each tile is stored as a separate record in the raster table.  If no block size is specified, then each raster file is brought in as an individual record.</para>
+                        </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 OVERVIEW_LEVEL, --overview-level=OVERVIEW_LEVEL</term>
+                        <listitem><para> create overview tables named as
+                             o_&lt;LEVEL&gt;_&lt;RASTER_TABLE&gt; and populate with GDAL-provided overviews (regular blocking only)</para>
+                        </listitem>
+                    </varlistentry>
+                  </variablelist>
+                </para>
+              </listitem>
+            </varlistentry>
+            
+            <varlistentry>
+              <term>  Optional parameters used to manipulate database objects</term>
+              <listitem>
+                <para>
+                  <variablelist>            
+                    <varlistentry>
+                      <term>-f COLUMN, --field=COLUMN</term>
+                      <listitem>
+                        <para>Specify name of destination raster column, default is 'rast'
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                    
+                    <varlistentry>
+                      <term>-F, --filename</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, --vacuum</term>
+                      <listitem>
+                        <para>
+                          Vacuum analyze the raster table.
+                        </para>
+                      </listitem>
+                    </varlistentry>
+                    
+                    <varlistentry>
+                      <term>-V, --create-raster-overviews</term>
+                      <listitem>
+                        <para>Create RASTER_OVERVIEWS table used to store overviews metadata.</para>
+                      </listitem>
+                    </varlistentry>  
+                  </variablelist>
+                </para>
+              </listitem>
+            </varlistentry>
+        
+            <varlistentry>
+                <term>-e ENDIAN, --endian=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, --verbose</term>
+                <listitem><para>Specify output file, otherwise send to stdout verbose mode. Useful for debugging</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>python raster2pgsql.py -s 4269 -I -r *.tif -F myschema.demelevation -o 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>python raster2pgsql.py -s 4269 -I -r *.tif -F myschema.demelevation | psql -d gisdb</programlisting>
+        </sect2>
+        
+        <sect2 id="Raster_Creation">
+          <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)
@@ -43,6 +269,9 @@ VALUES (1,
 '41000000007719564100000000000000000000000000000000FFFFFFFF050005000400FDFEFDFEFEFDFEFEFDF9FAFEF' ||
 'EFCF9FBFDFEFEFDFCFAFEFEFE04004E627AADD16076B4F9FE6370A9F5FE59637AB0E54F58617087040046566487A1506CA2E3FA5A6CAFFBFE4D566DA4CB3E454C5665')::raster);
   </programlisting>
+        </sect2>
+  </sect1>
+
   <sect1 id="Raster_Management_Functions">
        <title>Raster Management Functions</title>
        <refentry id="RT_AddRasterColumn">