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>
-
- <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. More usage examples can be found at <ulink url="http://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html">GDAL PostGIS Raster Driver Usage</ulink>
- </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 parameters:</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 [<schema>.]<table> 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 <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 -t 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 -t myschema.demelevation | psql -d gisdb</programlisting>
-
-
+ <para>For loading rasters from raster files please refere to <xref linkend="RT_Loading_Rasters" /></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)
-- Raster: 5 x 5 pixels, 3 bands, PT_8BUI pixel type, NODATA = 0
(2, ('01000003009A9999999999A93F9A9999999999A9BF000000E02B274A' ||
'41000000007719564100000000000000000000000000000000FFFFFFFF050005000400FDFEFDFEFEFDFEFEFDF9FAFEF' ||
-'EFCF9FBFDFEFEFDFCFAFEFEFE04004E627AADD16076B4F9FE6370A9F5FE59637AB0E54F58617087040046566487A1506CA2E3FA5A6CAFFBFE4D566DA4CB3E454C5665')::raster);</programlisting>
- </sect1>
-
+'EFCF9FBFDFEFEFDFCFAFEFEFE04004E627AADD16076B4F9FE6370A9F5FE59637AB0E54F58617087040046566487A1506CA2E3FA5A6CAFFBFE4D566DA4CB3E454C5665')::raster);</programlisting>
<sect1 id="Raster_Types">
<title>Raster Support Data types</title>
<sect1info>
--- /dev/null
+<?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.
+
+ Note that the older version of this tool waas 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>
+
+ <para>EXAMPLE USAGE:
+ <programlisting>raster2pgsql <varname>raster_options_go_here</varname> <varname>raster_file</varname> <varname>someschema</varname>.<varname>sometable</varname> > 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 <SRID></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>
+
+ </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>
+
+ </sect1>
+</chapter>
projects / postgis / commitdiff