= '''PostGIS WKT Raster Beta 0.1.6 Documentation''' =

[[BR]]

= '''1 - Introduction''' =

WKT Raster is an extension of PostGIS aiming at aiming at developing support for raster. It is a new project very different from the previous PGRaster project and also very different from Oracle !GeoRaster...

WKT Raster's goal is to implement the RASTER type as much as possible like the GEOMETRY type is implemented in PostGIS and to offer a single set of overlay SQL functions (like ST_Intersects) operating seamlessly on vector and raster coverages.


'''WKT Raster...'''


'''...is as simple as PostGIS...'''[[BR]]
[[BR]]
  Load your raster data using gdal2wktraster.py and make your queries! In WKT Raster...

  * RASTER is a new column type (like the PostGIS GEOMETRY type)
  * one table with a column of type raster = one raster coverage (like a one table PostGIS vector coverage)
  * one table row with a column of type raster = one tile (like a one row PostGIS vector geometry feature)
  * each raster tile has: a pixel size, a width and a height, a georeference, a variable number of band, a pixeltype per band and a nodata value per band; everything essential to do basic GIS raster operations.

'''...is an extension of PostGIS to be installed separately...'''

  * installable over any version of PostGIS higher than 1.3.5.
  * merge with PostGIS might occur in the future...

'''...has a loader similar to shp2pgsql.exe (gdal2wktraster.py)...'''

  * allowing loading of a single raster or a set of rasters (using wildcard) into a tiled coverage.
  * supporting [http://www.gdal.org/formats_list.html as many file format as GDAL does].

'''...allows easy conversion from raster to geometry...'''

  * RT_AsPolygon(raster) -> geometry

'''...introduces raster/geometry seamless geometry constructors...'''

  * so you don't have to bother whether the layers you are working with are in raster or vector form when using analysis functions.

  * RT_Intersection(raster|geometry, raster|geometry, "raster"|"geometry") -> raster/geometry

'''...and seamless geometry operators...'''

  * raster|geometry && raster|geometry -> boolean
  * RT_Intersects(raster|geometry, raster|geometry) -> boolean

'''...allows raster storage INSIDE the database (as WKB)...'''

  * for efficient overlay analysis operations between vector and raster layers...

'''...or OUTSIDE the database (as JPEG or TIFF)...'''

  * so desktop and web applications can quickly access and load raster tiles and nevertheless benefits from the powerful PostGIS GiST spatial index. Every WKT Raster SQL functions working with in-the-db raster tiles work seamlessly with out-the-db raster tiles.

'''...introduces the concept of raster objects...'''
  * geographic features are stored as variable size raster tiles instead of polygons.
  * allows vector to raster conversion without lost of information. 


'''...is much more simple than PGRaster and Oracle !GeoRaster! WKT Raster supports...'''

  * only one type (instead of two in Oracle Spatial: SDO_GEORASTER & SDO_RASTER). In WKT Raster there are no differences between rasters and tiles: a tile is a raster and a raster is a tile. i.e. one row = one tile = one raster; one table = one raster coverage.
  * no metadata (like PostGIS)
  * no masks (you can create a mask as a band)
  * no multiple dimensions (only two: x, y). Not to be confused with bands; WKT Raster DO supports multiband raster...
  * no pyramids (reduced resolution coverages can be stored as a separate layer)

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


'''Sponsoring'''

 * '''[http://www.cef-cfr.ca/index.php?n=Membres.StevenGCumming Steve Cumming], University Laval,''' sponsored project management kick-start and core implementation.

 * '''[http://www.cadcorp.com CadCorp]''' sponsored WKB and datum format design and implementation.

 * '''[http://www.mtrinstitute.com/ The Michigan Tech Research Institute]''' sponsored spatial operators implementation.

 * '''[http://www.osgeo.org/ OSGeo]''' provides svn repository.


'''Development'''

 * '''Pierre Racine''' designed the functionality.

 * '''Sandro Santilli''' wrote the in-memory api, build scripts and postgresql connectors.

 * '''Mateusz Loskot''' wrote the loader (gdal2wktraster.py) and most "getter" functions.



== '''1.2 - More Information''' ==


 * For more information see [http://postgis.refractions.net/support/wiki/index.php?WKTRasterHomePage WKT Raster Home Page].

 * 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.



= '''2 - Installation''' =


== '''2.1 - Requirements''' ==


WKT Raster is dependent on:

 * [http://www.postgresql.org/ PostgreSQL] version 7.2 or higher.
 * [http://trac.osgeo.org/proj PROJ] 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.3.5 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).
 * GDAL library. This driver is planned to be included in the official GDAL release for version 1.7.0. Until that moment, you'll need to use the ''fork'' version of GDAL library developed for the Google Summer of Code 2009 [http://www.gis4free.org/gdal_wktraster here]. This version is based in the 1.7.0SVN version.


== '''2.2 - Installing Precompiled Binaries''' ==


Windows and Linux binaries should be available soon on the [http://postgis.refractions.net/support/wiki/index.php?WKTRasterHomePage WKT Raster Home Page].

== '''2.3 - Compiling and Installing from Sources''' ==


'''2.3.1 - Compiling on Linux'''[[BR]][[BR]]
 1. Follow the [http://postgis.refractions.net/documentation/manual-1.3/ch02.html instructions to compile PostGIS].
 2. Using a SVN client, retrieve the WKT Raster source from http://svn.osgeo.org/postgis/spike/wktraster
 3. From the wktraster directory, run: 

{{{
>./configure

}}}
 
 4. Run the compile and install commands:


{{{
>make & make install

}}}


 PostgreSQL provides a utility called pg_config to enable extensions like PostGIS to locate the PostgreSQL installation directory. If ./configure didn't find pg_config, try using the --with-pgconfig=/path/to/pg_config switch to specify a particular PostgreSQL installation.

 All files are installed using information provided by pg_config:

   * Core functionality (rtpostgis shared library) is installed in [pkglibdir]/lib/

   * SQL function file (rtpostgis.sql) is installed in [prefix]/share/contrib

   * Loader (gdal2wktraster.py) is installed in [bindir]/




'''2.3.2 - Compiling on Windows using MSYS/MinGW'''

 1. Compile PostGIS [wiki:UsersWikiWinCompile using these instructions].

 2. From the wktraster folder, do:

{{{
>./configure --with-postgis-sources=/usr/src/postgis-svn
>$ make

}}}

 Note that the 'configure' script isn't there if you fetched the code from the SVN repository. In that case running ./autogen.sh should create it for you.

 Under MinGW you might have to add "--with-pgconfig=/usr/local/pgsql/bin/pg_config" if configure can't find your pgsql path.


'''2.3.3 - Compiling on Windows using Visual Studio'''



'''2.3.4 - Final Installation'''

 1. Load the PostGIS WKT Raster object and function definitions into your database by loading the rtpostgis.sql definitions file.

{{{
>psql -d [yourdatabase] -f rtpostgis.sql

}}}

  The PostGIS WKT Raster extensions should now be loaded and ready to use.


= '''3 - Using PostGIS WKT Raster''' =


== '''3.1 - The PostGIS WKT Raster Type''' ==

Like the PostGIS "geometry" type, WKT Raster "raster" type is a new PostgreSQL type. This mean each raster or raster tile is stored as a row of data in a database table. It is a complex type embedding many informations about each raster (width, height, number of band, pixeltype for each band and nodatavalue for each band) and its geolocalisation (pixelsize, upper left pixel center, rotation and SRID).


== '''3.2 - Integration with PostGIS''' ==


== '''3.3 - Loader/Dumper''' ==


== '''3.4 - Building Indexes''' ==


== '''3.5 - Examples''' ==


= '''4 - Uploading Strategy & Performance Tips''' =

[[BR]]

= '''5 - PostGIS WKT Raster Reference''' =


== '''5.1 - Management Functions''' ==


== '''5.2 - Raster Relationship Functions''' ==


== '''5.3 - Raster Processing Functions''' ==


== '''5.4 - Raster Accessors''' ==


== '''5.5 - Raster Constructors''' ==


== '''5.6 - Raster Operators''' ==


== '''5.7 - Raster Outputs''' ==


== '''5.8 - Raster Editors''' ==


= '''6 - Reporting Problems''' =

[[BR]]

= '''Appendix''' =