GDAL PostGIS Raster driver documentation
Last update: May 2013
Note for users: The last bug fixes and improvements have been finally included in GDAL 1.10, released on April 2013. So, it's stable now. Henceforth, the bug fixes and small improvements will be added to 1.10 branch. Bigger improvements will be added to trunk.
Note for developers: There is an open discussion on GDAL driver design at PostGIS Raster wiki
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 here.
This driver was started during the 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.
Please, use GDAL 1.10. The driver packed with previous GDAL versions was buggy and unstable, and it won't work with the last versions of PostGIS Raster (since it was included in PostGIS trunk).
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 from trunk or higher.
- Apart from this, if you want to use the driver against your own PostGIS version, use PostGIS 2.0
1.1 - Credits
- Jorge Arévalo (jorgearevalo at libregis.org)
- David Zwarg (dzwarg at azavea.com)
1.2 - More information
- PostGIS Raster documentation page here
- Introduction to PostGIS Raster format and description of the work done during the Google Summer of Code 2009 here
- Search for "WKT Raster" in the PostGIS-users and PostGIS-devel forums archives or in Nabble or write to these forums.
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:
- PostgreSQL version 8.3 or higher
- Proj4 library version 4.5.0 or higher
- GEOS library version 3.1.0 or higher
- Python version 2.5 or higher
- PostGIS versión 2.0 or higher
2.2 - Installing GDAL
2.2.1 - From binaries
2.2.2 - From sources
You can download daily GDAL snapshots from 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 here.
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:
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 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: 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.
4 - Reporting problems
- 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.
- PostGIS Raster driver: allow out-db rasters
- PostGIS Raster driver: error with band metadata precission
- PostGIS Raster driver: SetRasterProperties for empty rasters
- PostGIS Raster driver: Crashes in mode 2 with two tiles, side by side (separated by one missing tile)
- PostGIS Raster driver: Crashes in mode 2 with rotated, non missign tiles, side by side
- PostGIS Raster driver: Low range pixel type band should be converted to higher range one
- PostGIS Raster driver: Add write support
- PostGIS Raster driver: make good tests
- PostGIS Raster driver: allow user to select more options
- PostGIS Raster driver: make good management of big raster data
- PostGIS Raster driver: make SQL strings safe
- Pixels with NODATA value in a PostGISRaster get reset to 0.0 by gdal_translate