|Version 13 (modified by jorgearevalo, 4 years ago)|
GDAL WKT Raster driver documentation
1 - Introduction
WKT Raster is the project that provides raster support on PostGIS.
This driver was developed during the Google Summer of Code 2009. The driver only supports reading of regularly blocked in-db rasters. There are other functionalities under development:
- Reading of non-regular blocked rasters.
- Out-db raster support.
- Create and modify rasters.
- Full integration with the GDAL utility programs.
1.1 - Credits
- Jorge Arévalo develops the driver
1.2 - More information
- WKT Raster documentation page here
- Introduction to WKT 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 - Requirements
For using GDAL WKT Raster driver, you will first need to install:
- PostgreSQL version 8.3 or higher
- Proj4 library version 4.4 or higher
- GEOS library version 3.2.0 or higher
- PostGIS version 1.4.0 or higher
- WKTRaster PostGIS extension version 0.1.6SVN or higher
- Python version 2.5 or higher and GDAL for Python version 1.6.0 or higher for the loader (gdal2wktraster.py).
2.2 - Installed precompiled binaries
For the moment, there is no precompiled binaries. You can find precompiled binaries for the whole GDAL library here. The driver will be part of the version 1.7.0 of the library.
2.3 - Compiling and installing from sources
2.3.1 - Compiling on GNU/Linux
Follow the instructions to compile the requisites here (only the 5 first steps). After this, you will have to get the code of the fork of GDAL version 1.7.0SVN developed for the Google Summer of Code 2009. You can export the source code with Subversion from here by:
>$ svn export http://www.gis4free.org/gdal_wktraster
The fork version of GDAL is compiled like the official one. You can find instructions on how to build GDAL library on UNIX-like systems here.
Once the driver is added to the official GDAL trunk, you should get the source code of GDAL from official's GDAL repository.
2.3.2 - Compiling on Windows
The GDAL library with the WKT Raster driver hasn't been yet compiled on Windows.
3 - Using GDAL WKT Raster driver
3.1 - Loading raster data
The GDAL WKT Raster driver isn't able to load raster data yet. For this proposal, you'll have to use gdal2wktraster script. This loader script is included with the WKT Raster extension installation, under the scripts subdirectory. To check the syntax of the script, execute this command from $WKT_RASTER/scripts subdirectory:
>$ python gdal2wktraster.py --help
Important: If you want to load raster data with out-db storage system, you'll have to apply this patch to the gdal2wktraster script. Please, take into account that this patch has not been included to the gdal2wktraster version on official WKT Raster extension. It's only a beta version.
Load this one-band grayscale image (utm.tif) to PostGIS using loader script:
>$ python gdal2wktraster.py -r utm.tif -t utm -l 1 -k 100x100 -o utm.sql -s 26711 -I -M
In this example, the script generates a SQL output (redirected to the file utm.sql). This SQL code adds the image utm.tif to PostGIS, using a regular blocking arrangement with blocks of 100x100px. To execute the code, you must run this command as postgres user:
>$ psql -d <wktraster_database> -f utm.sql
The wktraster_database must be a PostgreSQL database with PostGIS and WKT Raster extensions enabled.
Load this RGB image (small_world.tif) to PostGIS using loader script:
>$ python gdal2wktraster.py -r small_world.tif -t utm -l 1 -k 40x20 -o small_world.sql -s 4326 -I -M
As in Example 1, this code generates a SQL file, called small_world.sql with the SQL code to add the image small_world.tif to PostGIS using a regular blocking arrangement with blocks of 40x20px. To execute the code, as postgres user, run:
>$ psql -d <wktraster_database> -f small_world.sql
Using the first image (utm.tif), let's create an overview of the image of half size (meaning image dimensions, not file size) in PostGIS.
>$ python gdal2wktraster.py -r utm.tif -t utm -l 2 -V -k 100x100 -o utm_ov2.sql -s 26711 -I -M
The key concept here is the -V flag. This flag allows loader script to create a new table to store the overviews' metadata. If you want to load several images with overviews, you'll have to use this flag only the first time the loader script is called, to create the overviews' metadata table only once.
The -l 2 flag represents the overview level. 2 means an overview of the 50% of the original image size.
As usual, to execute the generated SQL code, run as postgres this command:
>$ psql -d <wktraster_database> -f utm_ov2.sql
3.2 - Reading data
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 (respect the quotes):
PG":host='<host>' dbname='<dbname>' user='<user>' password='<password>' table='<raster_table>' [where='<sql_where>' mode='<working_mode>']"
Note that the string, until the part that starts with "table='" is a libpq-style connection string. That means that you can change the order of these fields (dbname, user, password, host), or leave out unnecessary ones (like password, in some cases). But the rest of the connection string must have the syntax and order shown above.
The "table" option requires the name of a WKT Raster table. This table only can be created by using the script gdal2tiles, from WKTRaster code
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. As the driver is currently working with only one table arrangement (regularly blocked tables), you can omit this option, or use it with value "REGULARLY_TILED_MODE". Otherwise, the driver won't work.
You must use this dataset's format in all the gdal tools, like gdalinfo, gdal_translate, gdalwarp, etc.
To get info about utm.tif file stored in database (see section 3.1) run this command:
>$ gdalinfo -mm -stats -checksum "PG:host='localhost' dbname='<wktraster_database>' user='<wktraster_user>' password='<wktraster_password>' table='utm'"
As user / password, in a typical installation, you can use postgres / postgres
To get an overview of the original image with half size run this command:
>$ gdal_translate -outsize 50% 50% "PG:host='localhost' dbname='<wktraster_database>' user='<wktraster_user>' password='<wktraster_password>' table='utm'" utm_half_size.tif
This will create a file called utm_half_size.tif like the original utm.tif but half size.
3.3 - Creating and modifying data
The GDAL WKT Raster driver is not able to create and modify rasters yet. You'll have to use gdal2wktraster loader to create new ones.
4 - GDAL WKT Raster driver reference
5 - Reporting problems
Take into account this driver is not part of the official GDAL library yet. Anyway, if you use it and find any error, if you want to suggest something or if you simply want to say hello :-), write a mail to jorgearevalo at gis4free dot org