PostGIS Raster Working Specifications for PostGIS 2.0

Quick Links

• PostGIS Raster Home Page
• Planning & Funding

• Beta Documentation

• Working Specifications for Future Versions

• Old Final Specifications for Beta 0.1.6

---

Objective 2.0.01 - Being able to get and set the rotation of a raster

ST_SetRotation(raster, angle)

Set the rotation of the raster. This method actually derive values for pixelsizex, pixelsizey, skewx and skewy based on the provided rotation angle.

Open Question:

PR: The angle should be provided in radian or in degree?

ST_Rotation(raster) -> float64

Return the georeference's rotation angle in (degree or radiant?) derived from the pixel size and the skew.

PR: I think getting the rotation get no sence since the result of pixelsizes and skew is not necessarily a rotation. It make sence to set it though.

---

Objective 2.0.02 - Being able to create a raster as the expression of another raster

ST_MapAlgebra

Returns a one band raster which pixel values are the mathematical expression of another raster band.

The expression is any PostgreSQL valid expression returning a number. This expression can contain conditional expressions like CASE or any user-defined function. In the one raster version of ST_MapAlgebra, the value of the current pixel is expressed in the expression by "rast". E.g. 'cos(rast)' or 'rast / 2'

An extra nodata value expression, applying only to nodata values pixel, can be provided.

It is not possible yet to refer to neighbour pixel values.

In the one raster version of ST_MapAlgebra, the resulting raster conserve the size, the georeference, the alignment and the SRID of the provided raster.

The pixel type of the resulting raster can be specified as '1BB', '2BUI', '4BUI', '8BSI', '8BUI', '16BSI', '16BUI', '32BSI', '32BUI', '32BF' or '64BF'. If the expression results in a value out of the range of the specified pixel type, it is truncated.

Variants

First series of variant with band specifier.

1) ST_MapAlgebra(rast raster, band integer, expression text, nodatavalueexpr text, pixeltype text)

2) ST_MapAlgebra(rast raster, band integer, expression text, nodatavalueexpr text)

3) ST_MapAlgebra(rast raster, band integer, expression text, pixeltype text)

4) ST_MapAlgebra(rast raster, band integer, expression text)

Second series of variant without band specifier (band number defaults to 1).

5) ST_MapAlgebra(rast raster, expression text, nodatavalueexpr text, pixeltype text)

6) ST_MapAlgebra(rast raster, expression text, nodatavalueexpr text)

7) ST_MapAlgebra(rast raster, expression text, pixeltype text)

8) ST_MapAlgebra(rast raster, expression text)

Implementation details

Only the first variant should be implemented in C. Others are pl/pgSQL variants. The C implementation should follow the plpgsql script of the one raster version of ST_MapAlgebra implemented at the top of http://trac.osgeo.org/postgis/browser/spike/wktraster/scripts/plpgsql/st_mapalgebra.sql

Optimizations should be implemented in many situations:

-When the raster is only no data values (tested with ST_BandIsNoDataValue() to be implemented)

-When the expression resume to the provided raster 'rast'.

Specifications for the two rasters version of ST_MapAlgebra are descibed in Objective 2.0.03.

---

Objective 2.0.03 - Being able to create a raster as the expression of two rasters

ST_MapAlgebra

---

Objective 2.0.04 - Implement better support for NULL, Empty, HasNoBand(rast), HasNoBand(rast, band) and BandIsNoData rasters in all functions.

Each function should better handle NULL rasters, empty rasterm rasters with no band and bands only filled with nodata values.

1) Generally, when NULL rasters are provided, return NULL. If the function involves a second non NULL raster and something can be done with it, do it.

2) Generally, when empty rasters are provided (ST_IsEmpty, width=0 or height=0), return an empty raster. If the function involves a second non empty raster and something can be done with it, do it.

2) Generally, when a HasNoBand(rast) or a HasNoBand(rast, band) raster is provided return a raster with no band but with the right extent. If the function involves a second raster having a band or the band, treat the first missing band like a BandIsNoData.

4) A BandIsNoData raster is a normal raster but many functions can be optimized with this type of raster.

5) All functions having missing the requested information (about its extent when it is a NULL or an empty raster or about its band when it is a HasNoBand(rast) or a HasNoBand(rast, band) raster) should return NULL or a documented value.

6) Try as less as possible to return EXCEPTION (or ERROR).

ST_IsEmpty(rast) -> boolean

Returns TRUE if the raster width or the raster height is 0.

ST_HasNoBand

Variants

1) ST_HasNoBand(rast, band) -> boolean

2) ST_HasNoBand(rast) -> boolean

Returns TRUE if the the raster does not have this band.

Variant 2 returns TRUE if the the raster does not have any band.

ST_BandIsNoData

Variants

1) ST_BandIsNoData(rast, band) -> boolean

2) ST_BandIsNoData(rast) -> boolean

Returns TRUE if the specified raster band is only filled with no data value.

Variant 2 default to band 1.

Implementation details

This require a new flag to be set in the core at import and at edition.

---

Objective 2.0.05 - Being able to set and get values for part of a raster.

ST_SetValues

TBD

ST_Clip

Returns the subset of a raster as a raster.

All metadata are copied from the source raster (except ulx, uly, width and height which must be computed).

Variants

1) ST_Clip(raster, ulx float8, uly float8, width int, height int) -> raster

2) ST_Clip(raster, geometry) -> raster

3) ST_Clip(raster, geometry, 'EXACT') -> raster

Variant 1 takes the upper left corner, the width and the height of the desired zone. Variant 2 determine the extent of this zone from the extent of a geometry. Variant 3 determine the extent of this zone from the extent of a geometry and set all pixel outside the geometry to no data values.

If the geometry is totally included into one pixel (a point for example), only this pixel is kept in the returned raster.

Implementation details

Implemented as a wrapper around ST_MapAlgebra.

newrast := ST_AddBand(ST_MakeEmptyRaster(x2 - x1, y2 - y1, ST_Raster2WorldCoordX(rast, x1, y2), ST_Raster2WorldCoordY(rast, x1, y2), ST_PixelSizeX(rast), ST_PixelSizeY(rast),ST_SkewX(rast),ST_SkewY(rast), ST_SRID(rast)), ‘1BB’, 1, 0) newrast := ST_MultiBandMapAlgebra(rast, newrast, ‘rast1’, ‘INTERSECTION’)

Could also be implemented as ST_Intersection -> ST_Band(ST_Intersection(geometry, raster, band, “TRIM”), 1) Would require some kind of TRIM and would be slower.

This function is necessary to optimize ST_Intersection. The raster to be polygonised before proceeding to a vector intersection should first be clipped to the minimal intersecting area using ST_Clip().

---

Objective 2.0.06 - Being able to add a band to a raster as a copy of the band of another raster.

ST_AddBand(rast1 raster, rast2 raster, band int, index int)

Copy band of rast2 into rast1 at the specified index.

This function is useful in a number of plpgsql functions and to optimize ST_MapAlgebra.