[[TOC]]

= '''GDAL PostGIS Raster driver documentation''' =

Last update: '''February 2014'''

'''Note for users:''' Thanks to the last improvements made by Jorge Arévalo and Even Rouault, the driver is now much faster and stable. But it's not in the stable branch yet. If you want to use this improved version, should download the [http://www.gisinternals.com/sdk/ nightly builds for Windows], or donwload and compile [http://trac.osgeo.org/gdal/wiki/DownloadSource#NightlySnapshots the last snapshots from trunk]

With this version, you will enjoy those new and exciting features:

 * Implemented multi-tile caching if cache size is big enough
 * Implemented multi-tile multi-band caching if cache size is big enough
 * Avoided initial full scan table in some situations (no where, PKID index, GIST index)
 * Added a AVERAGE_APPROX_RESOLUTION strategy that is now the default, and
  is used to compute quickly the dataset resolution on a small sample of rows,
  when resolution isn't advertized in raster_columns
 * Fixed caching of connexions in PostGISRasterDriver::GetConnection() to take
  into account database name (and thread)
 * Revised how overviews are handled.
 * Fixed quadtree insertion.
 * Fixed handling of positive y resolution (ungeoreferenced rasters)
 * Optimized retrieval of tiles per PKID (with a map)
 * Made driver work when called from non C locale (e.g. QGIS)
 * Accepted connection strings that have no host=, port= or user= (like OGR PG driver)
 * Added tolerance when fetching tiles per coordinates.

If you prefer a stable version, without those new features, '''choose the 1.10.1 branch'''. Previous versions were buggy and unstable.


[[BR]]

= '''1 - Introduction''' =

PostGIS Raster (previously known as '''WKT Raster''') is the project that provides '''raster support on PostGIS'''. Since September 26st, 2010, is an official part of PostGIS project. Further information [http://libregis.org/2010/10/01/wkt-raster-is-now-postgis-raster/ here].

This driver was started during the [http://socghop.appspot.com/ Google Summer of Code] 2009, and improved since then, being under development at same time than PostGIS Raster extension itself. So far, this is a '''read-only driver'''. The next version of the driver will include these features:
  * Out-db raster support.
  * Create and modify raster on PostGIS database.

Take into account that:
  * GDAL doesn't require PostgreSQL/PostGIS installed in your machine to work. But...
  * PostGIS 2.0 (the version of PostGIS that includes PostGIS Raster) DOES require GDAL.

So, if you want to use GDAL PostGIS Raster driver:
 * ALWAYS use GDAL version 1.10.1 or trunk version.
 * Apart from this, if you want to use the driver against your own PostGIS version, use PostGIS 2.0
== '''1.1 - Credits''' ==

'''Development '''
 * '''Jorge Arévalo''' (jorgearevalo at libregis.org)
 * '''David Zwarg''' (dzwarg at azavea.com)
 * '''Even Rouault''' (even.rouault at mines-paris.org)


== '''1.2 - More information''' ==
  * PostGIS Raster documentation page [http://trac.osgeo.org/postgis/wiki/WKTRaster/Documentation01 here]
  * Introduction to PostGIS Raster format and description of the work done during the Google Summer of Code 2009 [http://trac.osgeo.org/gdal/wiki/WKTRasterDriver here]
  * Search for "WKT Raster" in the [http://postgis.refractions.net/pipermail/postgis-users/ PostGIS-users] and [http://postgis.refractions.net/pipermail/postgis-devel/ PostGIS-devel] forums archives or in [http://www.nabble.com/PostGIS-f1221.html Nabble] or write to these forums.


[[BR]]

= '''2 - Installation''' =

== '''2.1 - Installing prerequisites''' ==

You don't need special requisites in your machine for using GDAL driver, apart from GDAL library itself. Anyway, you might want to set an enviroment with PostgreSQL/PostGIS/PostGIS Raster support. In that case, you'll need:
 
 * [http://www.postgresql.org/ PostgreSQL] version 8.3 or higher
 * [http://trac.osgeo.org/proj Proj4 library] version 4.5.0 or higher
 * [http://trac.osgeo.org/geos GEOS library] version 3.1.0 or higher
 * [http://www.python.org Python] version 2.5 or higher
 * [http://postgis.refractions.net/download/ PostGIS] versión 2.0 or higher

Linux users can install PostGIS 2.0 following the classical ''./configure & make & make install'' way. Windows users can follow [http://libregis.org/2011/03/10/how-to-install-and-configure-postgis-raster-on-windows/ these instructions]. Mac user can consult [http://www.kyngchaos.com/software:postgres William Kyngesburye instructions]
== '''2.2 - Installing GDAL''' ==

=== '''2.2.1 - From binaries''' ===

You can find GDAL binaries for Linux/Windows/Mac at [http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries GDAL download page]. Please, until the official release of GDAL 1.10, use the binaries compiled from development version.

=== '''2.2.2 - From sources''' ===

You can download daily GDAL snapshots from [http://www.gdal.org/daily/ here], or checkout the code directly from SVN with any subversion client. The examples of this documentation are using Linux console client, but they're easily reproducible with any other client, simply using the same URLs

{{{
>$ svn checkout https://svn.osgeo.org/gdal/trunk/gdal gdal
}}}

After that, you have to build GDAL library with Python support:

{{{
>$ ./configure --with-python & make & make install
}}}

Further instructions [http://trac.osgeo.org/gdal/wiki/BuildHints here].

[[BR]]

= '''3 - Using GDAL PostGIS Raster driver''' =

== '''3.1 - Loading raster data in the database''' ==

The GDAL PostGIS Raster driver does not support writing raster to the database yet. But you can load raster data in the database in 2 ways:

 * [http://postgis.refractions.net/documentation/manual-svn/using_raster.xml.html#RT_Raster_Loader Using raster2pgsql to load rasters]
 * [http://postgis.refractions.net/documentation/manual-svn/using_raster.xml.html#RT_Creating_Rasters Creating rasters using PostGIS Raster functions]

The write support to GDAL PostGIS Raster driver is under development.
== '''3.2 - Reading raster data from the database''' ==

If you want to use the GDAL WKT Raster driver, you must provide a '''connection string''' as Dataset's name. The syntax of this connection string is (the quotes may be ommitted):


{{{
 PG:"host='<host>' port:'<port>' dbname='<dbname>' user='<user>' password='<password>' [schema='<schema>'] [table='<raster_table>'] [where='<sql_where>'] [mode='<working_mode>']"
}}}

Note that the string, up to the part starting with "table='" is a libpq-style [http://www.gdal.org/ogr/drv_pg.html connection string]. That means that you can leave out unnecessary fields (like password, in some cases). 

The "table" option requires the name of a PostGIS Raster table. This table was created when the roaster was loaded.

The "where" option is used to filter the results of the raster table. Any SQL-WHERE expression is valid. The "mode" option is used to know the expected arrangement of the raster table. There are 2 possible values:

 * mode = 1. Also called ''ONE_RASTER_PER_ROW'' mode. In this case, a raster table is considered as a bunch of different raster files. This mode is intended for raster tables storing different raster files. It's the default mode if you don't provide this field in connection string.
 * mode = 2. Also called ''ONE_RASTER_PER_TABLE'' mode. In this case, a raster table is considered as a unique raster file, even if the table has more than one row. This mode is intended for reading tiled rasters from database.

Three important notes here:
 * If a table stores a tiled raster and you execute the driver with mode = 1, each image tile will be considered as a different image, and will be reported as a subdataset.
 * There are use cases the driver can't still work with. For example: non-regular blocked rasters. That cases are detected and an error is raised. Anyway, as I've said, the driver is under development, and will work with more raster arrangements ASAP.
 * There's an additional working mode. If you don't provide a table name, the driver will look for existing raster tables in all allowed database' schemas, and will report each table as a subdataset.

You must use this connection string's format in all the gdal tools, like gdalinfo, gdal_translate, gdalwarp, etc.

To see examples, check the PostGIS Raster FAQ section: [http://postgis.refractions.net/documentation/manual-svn/RT_FAQ.html#id3076646 Can I export my PostGIS Raster data to other raster formats?]


== '''3.3 - Creating and modifying data''' ==

The GDAL PostGIS Raster driver does not support creation and edition of rasters yet. Check the section 3.1, to know how to load raster data in the database.


[[BR]]


= '''4 - Reporting problems''' =

To report errors and suggestions, use [/newticket New Ticket form] of this Trac system or you can use the [http://www.osgeo.org/mailman/listinfo/gdal-dev/ gdal-dev list] or write an e-mail to: 

 * Jorge Arévalo: jorgearevalo at libregis.org
 * David Zwarg: dzwarg at azavea.com

When reporting here on the Trac, please specify the the '''PostGISRaster''' driver name in the keywords field.

= Open Tickets =

[[TicketQuery(status=new|assigned|reopened&keywords~=postgis_raster|postgisraster|wktraster&order=priority)]]