Changes between Version 105 and Version 106 of WKTRaster/Documentation01


Ignore:
Timestamp:
09/17/10 12:33:08 (14 years ago)
Author:
pracine
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WKTRaster/Documentation01

    v105 v106  
    1 = '''PostGIS WKT Raster Beta 0.1.6 Documentation''' =
     1= '''PostGIS Raster Beta Documentation''' =
    22
    33[[BR]]
    … …  
    55= '''1 - Introduction''' =
    66
    7 WKT Raster is an extension of PostGIS 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...
    8 
    9 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.
     7PostGIS Raster is an extension of PostGIS 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...
     8
     9PostGIS 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.
    1010
    1111For a list and description of already implemented functions and examples of using them, please
    12 also refer to [http://www.postgis.org/documentation/manual-svn/RT_reference.html WKT Raster Functions Reference].
    13 
    14 '''WKT Raster...'''
     12also refer to [http://www.postgis.org/documentation/manual-svn/RT_reference.html PostGIS Raster Functions Reference].
     13
     14'''PostGIS Raster...'''
    1515
    1616
    1717'''...is as simple as PostGIS...'''[[BR]]
    1818[[BR]]
    19   Load your raster data using gdal2wktraster.py and make your queries! In WKT Raster...
     19  Load your raster data using gdal2wktraster.py and make your queries! In PostGIS Raster...
    2020
    2121  * RASTER is a new column type (like the PostGIS GEOMETRY type)
    … …  
    5555'''...or OUTSIDE the database (as JPEG or TIFF)...'''
    5656
    57   * 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.
     57  * so desktop and web applications can quickly access and load raster tiles and nevertheless benefits from the powerful PostGIS GiST spatial index. Every PostGIS Raster SQL functions working with in-the-db raster tiles work seamlessly with out-the-db raster tiles.
    5858
    5959'''...introduces the concept of raster objects...'''
    … …  
    6262
    6363
    64 '''...is much more simple than PGRaster and Oracle !GeoRaster! WKT Raster supports...'''
    65 
    66   * 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.
     64'''...is much more simple than PGRaster and Oracle !GeoRaster! PostGIS Raster supports...'''
     65
     66  * only one type (instead of two in Oracle Spatial: SDO_GEORASTER & SDO_RASTER). In PostGIS 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.
    6767  * no metadata (like PostGIS)
    6868  * no masks (you can create a mask as a band)
    69   * no multiple dimensions (only two: x, y). Not to be confused with bands; WKT Raster DO supports multiband raster...
     69  * no multiple dimensions (only two: x, y). Not to be confused with bands; PostGIS Raster DO supports multiband raster...
    7070  * no pyramids (reduced resolution coverages can be stored as a separate layer)
    7171
    … …  
    107107
    108108
    109  * For more information see [wiki:WKTRaster WKT Raster Home Page].
     109 * For more information see [wiki:WKTRaster PostGIS Raster Home Page].
    110110
    111111 * 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.
    … …  
    119119
    120120
    121 WKT Raster is dependent on:
     121PostGIS Raster is dependent on:
    122122
    123123 * [http://www.postgresql.org/ PostgreSQL] version 7.2 or higher.
    … …  
    127127 * [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).
    128128
    129  * [http://www.gdal.org/ GDAL] version 1.6.0 or higher, for some of the [http://trac.osgeo.org/postgis/wiki/WKTRaster/SpecificationWorking01#Objective0.1.6e-Beingabletointersectvectorandrastertoproducevector. Objective 0.1.6e] features. This features are under development, and must be enabled during configure to use it. See section 2.3.1 - Compiling on Linux, to know how to enable them
     129 * [http://www.gdal.org/ GDAL] version 1.6.0 or higher.
    130130
    131131== '''2.2 - Installing Precompiled Binaries''' ==
    132132
    133133
    134 Windows and Linux binaries are available in the [wiki:WKTRaster WKT Raster Home Page].
     134Windows and Linux binaries are available in the [wiki:WKTRaster PostGIS Raster Home Page].
    135135
    136136== '''2.3 - Compiling and Installing from Sources''' ==
    … …  
    140140 1. Follow the [http://postgis.refractions.net/documentation/manual-1.3/ch02.html instructions to compile PostGIS].
    141141
    142  2. Get the WKT Raster source code. You have two options:
     142 2. Get the PostGIS Raster source code. You have two options:
    143143
    144144  * Download the latest development snapshot from http://postgis.refractions.net/download/
    145145
    146   * Using a SVN client, retrieve the very last WKT Raster source from http://svn.osgeo.org/postgis/spike/wktraster. In this case you will have to generate the "configure" script with autogen:
     146  * Using a SVN client, retrieve the very last PostGIS Raster source from http://svn.osgeo.org/postgis/spike/wktraster. In this case you will have to generate the "configure" script with autogen:
    147147
    148148{{{
    … …  
    206206
    207207
    208  7. Get the WKT Raster source code. You have two options:
     208 7. Get the PostGIS Raster source code. You have two options:
    209209
    210210  * Download the latest development snapshot from http://postgis.refractions.net/download/
    211211
    212   * Using a SVN client, retrieve the very last WKT Raster source from http://svn.osgeo.org/postgis/spike/wktraster. In this case you will have to generate the "configure" script with autogen:
     212  * Using a SVN client, retrieve the very last PostGIS Raster source from http://svn.osgeo.org/postgis/spike/wktraster. In this case you will have to generate the "configure" script with autogen:
    213213
    214214{{{
    … …  
    241241'''2.3.4 - Final Installation'''
    242242
    243  1. Load the PostGIS WKT Raster object and function definitions into your database by loading the rtpostgis.sql definitions file.
     243 1. Load the PostGIS Raster object and function definitions into your database by loading the rtpostgis.sql definitions file.
    244244
    245245{{{
    … …  
    249249 You can also do this directly in a pgAdmin III query dialog box if you administer your database using this software.
    250250 
    251  The PostGIS WKT Raster extensions should now be loaded and ready to use.
     251 The PostGIS Raster extension should now be loaded and ready to use.
    252252
    253253 All files are installed using information provided by pg_config:
    … …  
    260260
    261261
    262 = '''3 - Using PostGIS WKT Raster''' =
    263 
    264 
    265 == '''3.1 - The PostGIS WKT Raster Type''' ==
    266 
    267 Like the PostGIS "geometry" type, the PostGIS WKT "raster" type is a new PostgreSQL type. This means each raster or raster tile is stored as a row of data in a PostgreSQL database table. It is a complex type, embedding information about the raster itself (width, height, number of bands, pixeltype for each band and nodata value for each band) along with its geolocalisation (pixelsize, upper left pixel center, rotation and SRID).
    268 
    269 '''3.1.1 - PostGIS WKT Raster Rationale'''
    270 
    271 WKT Raster was designed with many objectives, to accommodate a myriad of dataset structures and a diversity of applications:
    272 
    273 '''Objective 1: Simplicity, Complementarity and Functionality -''' PostGIS WKT Raster provides a "raster" type that complements the existing PostGIS vectorial "geometry" type.  This new extension offers operators and functions that are similar to those available with the existing geometry type. They work in the same user-friendly manner, but are associated with a matricial geospatial data structure to support the use of rasters. PostGIS WKT Raster also includes a simple loader to import many raster formats into the database.
    274 
    275 '''Objective 2: Seamless Integration with the PostGIS geometry type -''' PostGIS WKT Raster enables PostGIS operators and functions to work seamlessly on both raster and geometry types, so that users:
     262= '''3 - Using PostGIS Raster''' =
     263
     264
     265== '''3.1 - The PostGIS Raster Type''' ==
     266
     267Like the PostGIS "geometry" type, the PostGIS "raster" type is a new PostgreSQL type. This means each raster or raster tile is stored as a row of data in a PostgreSQL database table. It is a complex type, embedding information about the raster itself (width, height, number of bands, pixeltype for each band and nodata value for each band) along with its geolocalisation (pixelsize, upper left pixel center, rotation and SRID).
     268
     269'''3.1.1 - PostGIS Raster Rationale'''
     270
     271PostGIS Raster was designed with many objectives, to accommodate a myriad of dataset structures and a diversity of applications:
     272
     273'''Objective 1: Simplicity, Complementarity and Functionality -''' PostGIS Raster provides a "raster" type that complements the existing PostGIS vectorial "geometry" type.  This new extension offers operators and functions that are similar to those available with the existing geometry type. They work in the same user-friendly manner, but are associated with a matricial geospatial data structure to support the use of rasters. PostGIS Raster also includes a simple loader to import many raster formats into the database.
     274
     275'''Objective 2: Seamless Integration with the PostGIS geometry type -''' PostGIS Raster enables PostGIS operators and functions to work seamlessly on both raster and geometry types, so that users:
    276276
    277277 * may use their prior knowledge of PostGIS in general, and of its geometry type operators and functions, when building SQL queries;
    … …  
    281281 * expect existing applications to work with new data loaded as rasters without (many) changes (to a certain conceptual limit).
    282282
    283 This makes PostGIS WKT Raster an abstraction level, not only over the raster format (like GDAL) or over the vector format (like OGR), but more generally over the two most used data structures in the geospatial industry (raster AND vector). Even if many operations performed on a vector object (e.g. all the functions working only on LINESTRING geometries) are not really possible to apply to raster objects, and if there are also some raster specific functions (e.g. ST_Resample() or ST_SetBandNoDataValue()) not working on vector objects, we think, and we will demonstrate as we extend PostGIS WKT Raster in the future, that most operations have their equivalent in both raster and vector worlds (e.g. ST_Intersections(), ST_Accum(), ST_Area(), ST_MapAlgebra()), even if this does not appear obvious at first sight.
     283This makes PostGIS Raster an abstraction level, not only over the raster format (like GDAL) or over the vector format (like OGR), but more generally over the two most used data structures in the geospatial industry (raster AND vector). Even if many operations performed on a vector object (e.g. all the functions working only on LINESTRING geometries) are not really possible to apply to raster objects, and if there are also some raster specific functions (e.g. ST_Resample() or ST_SetBandNoDataValue()) not working on vector objects, we think, and we will demonstrate as we extend PostGIS Raster in the future, that most operations have their equivalent in both raster and vector worlds (e.g. ST_Intersections(), ST_Accum(), ST_Area(), ST_MapAlgebra()), even if this does not appear obvious at first sight.
    284284
    285285We think that providing a single paradigm (SQL) for dealing with both rasters and vectors should allow developers to write better GIS applications, by simplifying graphical user interfaces and softening the learning curves. Developers should be able to build a unique graphical user interface to deal with raster and vector data, making users having to learn only one set of operators to work with vector data and raster data, instead of two. We think this should generally enhance users’ experiences with geospatial applications and allow them to focus on real geographic problems rather than struggling with data formats and structures.
    … …  
    287287We also think that this approach is compliant (at least in philosophy) with the ISO 19123 "Abstract Specification Schema for Coverage Geometry and Functions" specification (not to be confused with the OCG Web Coverage Service) in which a coverage can be represented as a point layer, a polygon layer, a TIN layer or a raster layer, and in which any positional value of the coverage is accessible without having to know the data structure upon which the coverage is based.
    288288
    289 '''Objective 3: Storage Flexibility (in-db & out-db storage) -''' PostGIS WKT Raster enables the user to simply "register" basic metadata (pixeltype, with, height, georeference, etc…) of images stored in the filesystem, without having to actually load their data values into the database. This way, web or desktop applications:
     289'''Objective 3: Storage Flexibility (in-db & out-db storage) -''' PostGIS Raster enables the user to simply "register" basic metadata (pixeltype, with, height, georeference, etc…) of images stored in the filesystem, without having to actually load their data values into the database. This way, web or desktop applications:
    290290
    291291 * do not have to retrieve images from the database but might instead access them directly from the filesystem (e.g. as JPEG files);
    292292
    293  * can nevertheless use most PostGIS WKT Raster operators and functions on those rasters, transparently.
     293 * can nevertheless use most PostGIS Raster operators and functions on those rasters, transparently.
    294294
    295295This is "out-db" storage as opposed to the more natural "in-db" storage.
    296296
    297 '''Objective 4: Interoperability –''' WKT Raster uses GDAL (http://www.gdal.org/) as its main connector to filesystem raster files. GDAL is involved when loading rasters into the database (using the loader) and when working with out-db rasters. It enables WKT Raster to work with nearly a hundred different file formats. (For a complete list of supported file formats see http://www.gdal.org/formats_list.html). (GDAL is also used to implement some raster processing functions, but this is another matter.)
    298 
    299 Objectives 2 and 3 respond to the most discussed idea that "storing rasters in the database is slower and useless if it does not benefit from specific databases’ features". Objective 2 makes WKT Raster an analytical toolkit, going beyond the simple data format. Objective 3 ensures storage flexibility, retrieval efficiency and transparency to users. Both objectives benefit greatly from the indexing of raster data in the database.
    300 
    301 We believe that these additional functionalities (over other raster-in-the-database implementations) make WKT Raster much more than just a new raster format, but also a necessary complement to PostGIS.
    302 
    303 '''3.1.2 - PostGIS WKT Raster Implementation'''
    304 
    305 To fulfill these objectives, PostGIS WKT Raster implements a minimalistic yet complete raster data structure, and adopts a simple single-type and single-table relational schema. This data structure is very similar to the PostGIS geometry vector type structure, and very different, for example, from the Oracle Spatial SDO_GEORASTER and SDO_RASTER raster types.
    306 
    307  * '''A single raster type -''' In PostGIS WKT Raster there is no such thing as a raster and its raster tiles or an image and its image tiles. Even though single raster attributes may be considered tiles of a coverage or tiles of an image, any attribute of type raster is a complete and self sufficient georeferenced raster. It is not necessarily related to other rasters in the same table, and not necessarily located in a specific grid. This choice makes everything very simple and flexible, letting users and applications decide how they structure their data and how they name their raster elements (rasters, images, bitmap, blocks, tiles, etc…).
    308 
    309  * '''A single table relational schema –''' Similarly, in PostGIS WKT Raster there is not one table for storing the raster data (like Oracle Spatial SDO_RASTER) and another table for storing the georeference and the metadata (like Oracle Spatial SDO_GEORASTER). Everything is stored in a single raster attribute, and raster attributes composing a table are not necessarily related to each other to form a significant coverage.
     297'''Objective 4: Interoperability –''' PostGIS Raster uses GDAL (http://www.gdal.org/) as its main connector to filesystem raster files. GDAL is involved when loading rasters into the database (using the loader) and when working with out-db rasters. It enables PostGIS Raster to work with nearly a hundred different file formats. (For a complete list of supported file formats see http://www.gdal.org/formats_list.html). (GDAL is also used to implement some raster processing functions, but this is another matter.)
     298
     299Objectives 2 and 3 respond to the most discussed idea that "storing rasters in the database is slower and useless if it does not benefit from specific databases’ features". Objective 2 makes PostGIS Raster an analytical toolkit, going beyond the simple data format. Objective 3 ensures storage flexibility, retrieval efficiency and transparency to users. Both objectives benefit greatly from the indexing of raster data in the database.
     300
     301We believe that these additional functionalities (over other raster-in-the-database implementations) make PostGIS Raster much more than just a new raster format, but also a necessary complement to PostGIS.
     302
     303'''3.1.2 - PostGIS Raster Implementation'''
     304
     305To fulfill these objectives, PostGIS Raster implements a minimalistic yet complete raster data structure, and adopts a simple single-type and single-table relational schema. This data structure is very similar to the PostGIS geometry vector type structure, and very different, for example, from the Oracle Spatial SDO_GEORASTER and SDO_RASTER raster types.
     306
     307 * '''A single raster type -''' In PostGIS Raster there is no such thing as a raster and its raster tiles or an image and its image tiles. Even though single raster attributes may be considered tiles of a coverage or tiles of an image, any attribute of type raster is a complete and self sufficient georeferenced raster. It is not necessarily related to other rasters in the same table, and not necessarily located in a specific grid. This choice makes everything very simple and flexible, letting users and applications decide how they structure their data and how they name their raster elements (rasters, images, bitmap, blocks, tiles, etc…).
     308
     309 * '''A single table relational schema –''' Similarly, in PostGIS Raster there is not one table for storing the raster data (like Oracle Spatial SDO_RASTER) and another table for storing the georeference and the metadata (like Oracle Spatial SDO_GEORASTER). Everything is stored in a single raster attribute, and raster attributes composing a table are not necessarily related to each other to form a significant coverage.
    310310
    311311These choices make the PostGIS raster structure very similar to the existing PostGIS vector structure in which a layer can be geometrically topological or not, depending on the user data and their choices of application.
    … …  
    325325 * a "complete image" (e.g. Landsat),
    326326 * an image "tile",
    327  * a "raster object"; a new kind of raster object introduced by PostGIS WKT Raster resulting from the rasterization of a vector feature.
     327 * a "raster object"; a new kind of raster object introduced by PostGIS Raster resulting from the rasterization of a vector feature.
    328328
    329329All these objects are different terminologies and concepts related to the general concept of "raster". We will use the latter term throughout the rest of this documentation.
    … …  
    343343 f) '''a raster object coverage resulting from the rasterization of a vector coverage.''' Each vector feature becomes a small raster with the same extent as the original vector feature. This type of coverage is not necessarily complete, nor rectangular; tiles should be of different sizes and might overlap. It all depends on the characteristics of the vector layer being rasterized. An exhaustive (or continuous) layer of mutually exclusive geometries (without gaps or holes like a forest cover) would result in a raster object coverage in which significant pixels (withdata values) would not overlap, but non-significant pixels (nodata values) would. On the other end of the spectrum, a discontinuous layer of mutually exclusive geometries (like a lake or building layer) would result in a coverage of mostly disjoint raster objects.
    344344
    345 '''''Table 1 - Characteristics of different possible raster table arrangements in PostGIS WKT Raster'''''
     345'''''Table 1 - Characteristics of different possible raster table arrangements in PostGIS Raster'''''
    346346
    347347|| '''Arrangement''' || '''Global shape of[[BR]]composing raster''' || '''Missing tiles[[BR]]possible''' || '''Same size[[BR]]tiles''' || '''Tile overlap[[BR]]possible''' || '''Form a[[BR]]coverage?''' ||
    … …  
    353353||'''f) raster object coverage''' || any || no real tiles || no real tiles || yes || yes ||
    354354
    355 '''''Figure 1 - Different possible raster table arrangements in PostGIS WKT Raster'''''
     355'''''Figure 1 - Different possible raster table arrangements in PostGIS Raster'''''
    356356
    357357[[Image(WKTRasterArrangements.gif)]]
    358358
    359 All these arrangements are possible, and as for a geometry layer which can be implicitly topological or not, PostGIS WKT Raster does not impose one over the other (even though types c) and d) and f) are the most practical for a GIS analyst). The fact that users of a database might (contrary to a raster file format) add or delete rows (or “tiles”) in a table, along with the fact that we must support variable-sized tiles (for vector to raster conversion), makes it very difficult to enforce a certain type of configuration.
     359All these arrangements are possible, and as for a geometry layer which can be implicitly topological or not, PostGIS Raster does not impose one over the other (even though types c) and d) and f) are the most practical for a GIS analyst). The fact that users of a database might (contrary to a raster file format) add or delete rows (or “tiles”) in a table, along with the fact that we must support variable-sized tiles (for vector to raster conversion), makes it very difficult to enforce a certain type of configuration.
    360360
    361361'''Regularly Blocked Table'''
    … …  
    369369Some blocks (or tiles) can be missing in a regularly blocked table. Missing tiles are assumed to be filled with the proper nodata value for each band as determined in the raster_columns table.
    370370
    371 This regular tiling (or regular blocking) is expected from arrangements c) d) and e) in figure 1. PostGIS WKT Raster provides this mechanism because raster applications are often optimized to deal with these arrangements. There is, however, no mechanism to enforce (constrain) these criteria and, as mentioned above, adding, modifying or deleting a row from the table might break this regular blocking, and the regular_blocking attribute will not be automatically updated.
     371This regular tiling (or regular blocking) is expected from arrangements c) d) and e) in figure 1. PostGIS Raster provides this mechanism because raster applications are often optimized to deal with these arrangements. There is, however, no mechanism to enforce (constrain) these criteria and, as mentioned above, adding, modifying or deleting a row from the table might break this regular blocking, and the regular_blocking attribute will not be automatically updated.
    372372
    373373'''Structure of the "raster" Type'''
    … …  
    411411 * "64 bits double" are -1.7*10-308 and 1.7*10308.
    412412
    413 PostGIS WKT Raster is expressed in different forms, depending on the level at which it is referred:
     413PostGIS Raster is expressed in different forms, depending on the level at which it is referred:
    414414
    415415 * '''WKT -''' "Well Known Text" refers to the human readable text format used when inserting a raster with ST_RasterFromText() (not yet implemented) and retrieving a raster with ST_AsText() (not yet implemented). This format can result in the loss of precision when used with floating point values. This is why the HEXWKB form is preferred when importing/exporting in textual form.
    … …  
    423423'''The raster_columns Table'''
    424424
    425 Like the PostGIS "geometry_column" table, the PostGIS WKT Raster "raster_columns" table is a way for applications to get a quick overview of which tables have a raster column, and to get the main characteristics (metadata) of the rasters stored in these columns. Applications should maintain this table using the !AddRasterColumn() and !DropRasterColumn() functions, as there is no automatic mechanism in the database to keep this table up to date with every raster column created or deleted.
     425Like the PostGIS "geometry_column" table, the PostGIS Raster "raster_columns" table is a way for applications to get a quick overview of which tables have a raster column, and to get the main characteristics (metadata) of the rasters stored in these columns. Applications should maintain this table using the !AddRasterColumn() and !DropRasterColumn() functions, as there is no automatic mechanism in the database to keep this table up to date with every raster column created or deleted.
    426426
    427427Table 3 summarizes the attributes of the raster_columns table.
    … …  
    445445'''3.1.3 - Storing in-db raster or registering out-db raster?'''
    446446
    447 One of the major PostGIS WKT Raster features is the ability to store raster data in the database or merely register them as external files residing in the filesystem. When registering a raster, only the raster metadata are stored in the database (width, height, number of band, georeference and path to the actual raster file), not the values associated with the pixels. Registering is done via the loader’s –R option.
     447One of the major PostGIS Raster features is the ability to store raster data in the database or merely register them as external files residing in the filesystem. When registering a raster, only the raster metadata are stored in the database (width, height, number of band, georeference and path to the actual raster file), not the values associated with the pixels. Registering is done via the loader’s –R option.
    448448{{{
    449449>gdal2wktraster.py –r c:/imagesets/landsat/image01.tif –t landsat -R
    … …  
    484484[[BR]]
    485485
    486 = '''5 - PostGIS WKT Raster Reference''' =
     486= '''5 - PostGIS Raster Reference''' =
    487487
    488488