<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.py</varname> 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>
- <sect2 id="raster2pgsql_usage">
- <title>Using the raster2pgsql Raster Loader</title>
- <para>
- The <varname>raster2pgsql.py</varname> 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>
+ <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>
- <para>An example session using the loader to create an input file and uploading it might look like this:</para>
+ <varlistentry>
+ <term> -t TABLE, --table=TABLE</term>
+ <listitem>
+ <para>
+ Raster destination in form of [<schema>.]<table> or base raster table for overview level>1, required
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
- <programlisting>python raster2pgsql.py -s 4269 -I -r *.tif -F myschema.demelevation -o elev.sql
+
+ <varlistentry>
+ <term>Raster processing: Optional parameters used to manipulate input raster dataset</term>
+ <listitem>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>-s <SRID></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_<LEVEL>_<RASTER_TABLE> 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>
+ <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>
+ <programlisting>python raster2pgsql.py -s 4269 -I -r *.tif -F myschema.demelevation | psql -d gisdb</programlisting>
+
- <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>
+ <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,
(2, ('01000003009A9999999999A93F9A9999999999A9BF000000E02B274A' ||
'41000000007719564100000000000000000000000000000000FFFFFFFF050005000400FDFEFDFEFEFDFEFEFDF9FAFEF' ||
'EFCF9FBFDFEFEFDFCFAFEFEFE04004E627AADD16076B4F9FE6370A9F5FE59637AB0E54F58617087040046566487A1506CA2E3FA5A6CAFFBFE4D566DA4CB3E454C5665')::raster);</programlisting>
- </sect2>
</sect1>
<sect1 id="Raster_Management_Functions">
<title>Raster Management Functions</title>
projects / postgis / commitdiff