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

[[BR]]

= '''1 - Introduction''' =

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

This driver was developed during the [http://socghop.appspot.com/ Google Summer of Code] 2009. The driver only supports reading of regularly blocked in-db rasters. 

The next version of the driver will be released during October 2010, and will include these features:
  * Out-db raster support.
  * Reading of non-regular blocked rasters.

In further versions: create and modify PostGIS rasters.

This new version will have 3 raster reading working modes:
  * Browse Mode: If the user only provides dabatase name (and optionally, schema name), the driver searches for raster tables in that database.
  * ONE_RASTER_PER_ROW mode: The default mode, if the user provides a table name. Each of the raster table rows is considered as a different raster.
  * ONE_RASTER_PER_TABLE mode: If the user specify a table name and this mode (still not defined the way of doing it. Probably, as an additional parameter in connection string), all the rows of the table will be considered as tiles of the same raster coverage. The whole raster extent will be calculated. The driver will deal with things like rows with different srid, or snapping to different grids.

The rest of the documentation is referred to the current driver version, and will be updated as soon as the new version of the driver will be released.

== '''1.1 - Credits''' ==

'''Development '''
 * '''Jorge Arévalo''' develops the driver


== '''1.2 - More information''' ==
  * WKT Raster documentation page [http://trac.osgeo.org/postgis/wiki/WKTRaster/Documentation01 here]
  * Introduction to WKT 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 - Requirements''' ==

For using GDAL WKT Raster driver, you will first need to install:

 * [http://www.postgresql.org/ PostgreSQL] version 8.3 or higher
 * [http://trac.osgeo.org/proj Proj4 library] version 4.4 or higher
 * [http://trac.osgeo.org/geos GEOS library] version 3.2.0 or higher
 * [http://postgis.refractions.net/ PostGIS] version 1.4.0 or higher
 * [http://trac.osgeo.org/postgis/wiki/WKTRaster WKTRaster PostGIS extension] version 0.1.6SVN or higher
 * [http://www.python.org/ Python] version 2.5 or higher and [http://pypi.python.org/pypi/GDAL/ GDAL for Python] version 1.6.0 or higher for the loader (gdal2wktraster.py).

 
== '''2.2 - Installed precompiled binaries''' ==

This driver is part of the GDAL library. You can find ready to use binaries [http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries here].

== '''2.3 - Compiling and installing from sources''' ==

=== '''2.3.1 - Downloading source''' ===

Follow the instructions to compile the requisites [http://www.gis4free.org/blog/2009/05/30/gsoc-09-weekly-report-1-2305-2905/ here] '''(only the 5 first steps)'''. After this, you can download and install GDAL library as usual. But please, take into account that the driver isn't included in stable version yet. You'll have to checkout the code from SVN:

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

Or, if you prefer it, download one of the [http://download.osgeo.org/gdal/daily/ GDAL daily builds]


=== '''2.3.2 - Building''' ===

You can find instructions on how to build GDAL library [http://trac.osgeo.org/gdal/wiki/BuildHints here].


[[BR]]

= '''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:''' The out-db raster support for WKT Raster is still under development. Please, don't use this option.

'''Example 1''': 

Load [http://www.gis4free.org/gdal_wktraster_autotest/autotest/gdrivers/data/utm.tif this one-band grayscale image] (utm.tif) on 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.

'''Example 2''':

Load [http://www.gis4free.org/gdal_wktraster_autotest/autotest/gdrivers/data/small_world.tif this RGB image] (small_world.tif) on 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
}}}


'''Example 3''':

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 (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, until the part that starts with "table='" is a libpq-style [http://www.gdal.org/ogr/drv_pg.html 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).

The "table" option requires the name of a WKT Raster table. This table only can be created by using the script gdal2tiles, from [http://trac.osgeo.org/postgis/wiki/WKTRaster 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.

'''Example 1:'''

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'''


'''Example 2:'''

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.


[[BR]]

= '''4 - GDAL WKT Raster driver reference''' =

TODO

[[BR]]

= '''5 - Reporting problems''' =

If you find any error, want to suggest something or if simply want to say ''hello'' :-), write a mail to ''jorgearevalo at deimos-space dot com''