PostGIS WKT Raster Beta 0.1 Final Specifications

Quick Links

• WKT Raster Home Page
• Planning & Funding

• Beta 0.1.6 Working Specifications
• Beta 0.1.6 Documentation

• Beta 0.2.4 Working Specifications
• Working Specifications for Future Versions

---

Objective 0.1.6c - Being able to load rasters in the database

gdal2wktraster.py - A prototype of the translation utility implemented in Python and with use of ​GDAL and its bindings to Python. Create an SQL commands output to create a table of raster. As input raster file, all GDAL formats are accepted. The script is available as gdal2wktraster.py script.

USAGE:
gdal2wktraster.py -r <RASTERFILE> -t [<SCHEMA>].<TABLE> [<OPTIONS>]

-r <RASTERFILE> Specifies input raster file. Multiple -r options can be specified for a number of input files or wildcards can be used (? and *).
-t [<SCHEMA>.]<TABLE> Name of destination table in with or without target schema specified.

OPTIONS:

Raster processing: Optional parameters used to manipulate input raster dataset

-s <SRID> Set the SRID field of output raster. Default is -1.
-b <NBBAND> Specify the band number of the band to be extracted from input raster file.
-k <BLOCK_SIZE> Specify the size of the block of the input raster, assuming regular blocking mode. Must be specified as WIDTHxHEIGHT.
-R Register the raster as a filesystem (out-db) raster. Only the absolute path to the raster and its georeferencing informations are stored. Raster pixel values stay in the filesystem raster file and are not stored in the database.
-l <OVERVIEW_LEVEL> Create overview tables named as o_<LEVEL>_<RASTER_TABLE> and populate it with GDAL-provided overviews. Regular blocking only.

Database processing: Optional parameters used to manipulate database objects

-c Creates a new table and populates it with raster input file(s), this is the default if you do not specify any options.
-d Drops the table, then recreates it and populates it with current raster file(s) data.
-f <COLUMN> Name of target column for raster data. Default column name is rast.
-F Add a "filename" column containing the original name of the loaded raster file.
-I Create a GiST index on the raster column.
-M Issue VACUUM command against all generated tables.
-V Create RASTER_OVERVIEWS table used to store overviews metadata.

Miscellanous: Other optional parameters

-e <ENDIAN> Control endianness of generated binary output of raster; specify 0 for XDR (big-endian) and 1 for NDR (little-endian). Only NDR output is supported right now.
-w <VERSION> Specify version of WKT Raster protocol. Default is 0; only this value is supported right now.
-o <FILE> Output file for generated SQL commands. If not specified, stdout is assumed.
-v Switch on excessively verbose mode, useful for debugging.
-h Display this help screen.

---

Objective 0.1.6d - Being able to get all the properties of a raster (all the “Get” functions).

ST_SRID(raster|geometry) -> integer
Return the SRID associated with the raster.

ST_Width(raster) -> integer
Return the width of the raster.

ST_Height(raster) -> integer
Return the height of the raster.

ST_PixelSizeX(raster) -> float64
Return the georeference's X pixel size of the raster. ​See.

ST_PixelSizeY(raster) -> float64
Return the georeference's Y pixel size of the raster. ​See.

ST_RotationX(raster) -> float64
Return the georeference's X rotation.

ST_RotationY(raster) -> float64
Return the georeference's Y rotation. ​See.

ST_UpperLeftX(raster) -> float64
Return the georeference's X-coordinate of the upper left corner of the upper left pixel. ​See.

ST_UpperLeftY(raster) -> float64
Return the georeference's Y-coordinate of the upper left corner of the upper left pixel. ​See.

ST_Georeference(raster, text) -> string
Returns the georeference meta data in GDAL or ESRI format as commonly seen in a world file. For ESRI, ​see for GDAL, ​see.

ST_NumBands(raster) -> integer
Return the number of band included in the raster.

ST_BandPixelType(raster, integer) -> string
Return the pixel type of the specified 1-based Nth band of raster. Band index is 1-based. The function returns one of the following values:

• 1BB - 1-bit boolean
• 2BUI - 2-bit unsigned integer
• 4BUI - 4-bit unsigned integer
• 8BSI - 8-bit signed integer
• 8BUI - 8-bit unsigned integer
• 16BSI - 16-bit signed integer
• 16BUI - 16-bit unsigned integer
• 32BSI - 32-bit signed integer
• 32BUI - 32-bit unsigned integer
• 32BF - 32-bit float
• 64BF - 64-bit float

ST_BandNoDataValue(raster, integer) -> float32
Return the NoDataValue of the specified 1-based Nth band of raster. Band index is 1-based. The value is always returned as a float32 even if the pixel type is integer.

ST_Metadata(raster) -> record
Returns all the metadata associated with a raster (upper left x, upper left y, width, height, pixelsize x, pixelsize y, skew x, skew y, srid, numbands in this order). Does not include any band metadata. If you want band metadata, add ST_BandMetadata(raster, integer) to your query.

It should be used like this: "SELECT (md).* FROM (SELECT ST_Metadata(rast) AS md FROM myrastertable) foo"

ST_BandMetadata(raster, integer) -> record
Returns all the metadata associated with a raster band (pixeltype, has nodata value, nodata value, is stored out-db, path, in this order). Does not include embedding raster metadata. If you want embedding raster metadata, add ST_Metadata(raster) to your query.

It should be used like this: "SELECT (bmd).* FROM (SELECT ST_BandMetadata(rast) AS bmd FROM myrastertable) foo"

---

RASTER_COLUMNS Metadata Table

The following metadata table provides external applications and possibly internal tools the ability to discover tables with raster data, and to learn various information about those datasets.

Column Name	Type	Constraints	Comments
r_table_catalog	character varying(256)	NOT NULL
r_table_schema	character varying(256)	NOT NULL
r_table_name	character varying(256)	NOT NULL
r_column	character varying(256)	NOT NULL
srid	integer	NOT NULL	Use 0 for unknown SRID
pixel_types	ARRAY=VARCHAR=	NOT NULL	An array of pixeltypes, one per band. The band count is implicit in the size of this array.
out_db	ARRAY=BOOLEAN=	NOT NULL	An array of boolean values, one per band. "false" if internal tiles, "true" if tiles are references to raster files outside the database.
regular_blocking	boolean	NOT NULL	False by default, true if all blocks are equal sized, abutted and non-overlapping, started at top left origin (see below).
nodata_values	ARRAY=DOUBLE=		An array of nodata values, one per band. The entry may be NULL to indicate no nodata values.
pixelsize_x	double		Width of a pixel in geounits (per SRID).
pixelsize_y	double		Height of a pixel in geounits (per SRID).
blocksize_x	integer		The width of a block in pixels (NULL if irregular).
blocksize_y	integer		The height of a block in pixels (NULL if irregular).
extent	GEOMETRY		A polygon geometry containing all raster tiles, or NULL if predefined bounds are not known. For "regular_blocking" cases this geometry will be a simple rectangle. In other cases it might be an irregular polygon.

If the regular_blocking field is true a number of restrictions are placed on the raster column that is defined:

1. All tiles must have the same size (blocksize_x and blocksize_y).
2. All tiles must be non-overlapping, and appear on regular block grid.
3. The top left block must start at the top left corner of the extent.
4. The right most column, and bottom row of blocks may have portions that extend beyond the raster extent. These areas will be assumed to be nodata and not part of the described raster.
5. The extent field must be a simple rectangle (non-rotated).

It is permissable to for regular_blocking rasters to omit some blocks/tiles (sparse rasters) in which case the missing tiles should be assumed to be all nodata or zero valued.

---