wiki:WKTRaster/SpecificationWorking03

Version 18 (modified by pracine, 15 years ago) ( diff )

PostGIS WKT Raster Beta 03 (and up) Working Specifications

Quick Links


Objective B03a - Being able to set all the properties of a raster.

ST_SetSRID(raster|geometry, integer)

Set the spatial reference on the specified raster. This corresponds with the ST_SetSRID method in regular PostGIS.

ST_SetPixelSize(raster, pixelsize)

Variant 1: ST_SetPixelSize(raster, xsize, ysize)

Variant 2: ST_SetPixelSize(raster, raster)

Set the pixel size (cell size) on the specified raster. The base method sets the X and Y pixel size to the same value. The first variant sets the pixel sizes to the individually specified x and y sizes. The second variant sets the pixel size to the pixel size of the 2nd raster parameter.

Open Question:

DZ: Should there be corresponding methods for X/Y sizes? ST_SetXPixelSize(…) and ST_SetYPixelSize(…)

PR: In addition to ST_SetPixelSize(raster, xsize, ysize) or in replacement of?

DZ: In addition to? PR: Maybe we are fine with ST_SetPixelSize(raster, xsize, ysize)…

PR: Could you provide a full SQL example of ST_SetPixelSize(raster, raster)? And in general of a function getting arguments for the first raster from another raster (like the below ST_Resample(raster, method, raster))

DZ: A SQL example for this is in the regression tests in patch #431: test/regress/rt_set_properties.sql, line 52. I can come up with some more examples, if needed.

ST_SetNoDataValue(raster, band, value)

Set the data value that corresponds to NODATA in the given raster and band.

ST_HasNoDataValue(raster, band)

Return true if the value stored as a NODATA value must be interpreted as a real NODATA value.

ST_SetGeoReference(raster, georef)

Variant 1: ST_SetGeoReference(raster, georef, format)

Set the georeference fields of the raster (pixel size, rotation, upper left location) all in one pass. The 'format' parameter is optional, and defaults to 'GDAL' georeference format if it is not specified.

If this method does not recieve a georeference string with 6 parameters (or if one of the parameters is not numeric), it raises an exception "st_setgeoreference requires a string with 6 floating point values". If this method recieves a null raster, it does nothing, and returns a null raster.

ST_SetRotation(raster, rotation)

Variant 1: ST_SetRotation(raster, rotationx, rotation y)

Variant 2: ST_SetRotation(raster, raster)

Set the rotation of the raster. The base method sets the X and Y rotation to the same value. The first variant sets the rotation to the individually specified x and y rotations. The second variant sets the rotation to the rotation taken from the 2nd raster parameter.

Open Question:

DZ: Should there be corresponding methods for X/Y rotations in addition to this general method? ST_SetXRotation(…) and ST_SetYRotation(…)?

ST_SetUpperLeft(raster, left, top)

Variant 1: ST_SetUpperLeft(raster, raster)

Set the location of the upper left pixel (cell). The base method sets the X and Y coordinates to the individually specified left and top coordinates. The first variant sets the upper left coordinate to the upper left coordinate taken from the 2nd raster parameter.

Open Question:

DZ: Should there be corresponding methods for X/Y rotations in addition to this general method? ST_SetUpperLeftX(…) and ST_SetUpperLeftY()?


Objective B03b - Being able to reproject a raster.

ST_Transform(raster|geometry, SRID) → same type as input


Objective B03c - Being able to do some base raster operations.

ST_Area(raster|geometry) → double
ST_Count(raster, value) → integer

ST_Resample(raster, method, originx, originy, pixelsizex, pixelsizey) → raster

Variant 1: ST_Resample(raster, method, raster) → raster

Recompute a raster in order to change its pixel size and/or the position of its upper left corner.

The second parameter is the resampling method performed when computing new pixel values:

1) 'NEAREST NEIGHBOR'
2) 'LINEAR'
3) 'BICUBIC'

The 3rd or 3rd-6th parameters define the pixel size of the resampling operation. For the 3rd parameter variant, the pixel size is taken from the pixel size of the raster parameter. For the 3rd-6th parameter variant, the pixel origin and dimensions are explicitly defined.

ST_SelectByValue(raster|geometry, ‘expression’) → same type as first argument
ST_Reclass(raster|geometry,string) → same type as first argument

ST_MapAlgebra(raster|geometry, [raster|geometry,…] ‘mathematical expression’, ‘raster’ |’geometry’) → raster/geometry

Variant 1: ST_MapAlgebra(raster|geometry, [raster|geometry,…] ‘mathematical expression’, ‘raster’ |’geometry’, originx, originy, pixelsizex, pixelsizey) → raster/geometry

Variant 2: ST_MapAlgebra(raster|geometry, [raster|geometry,…] 'mathematical expression', 'raster' |'geometry', integer) →raster/geometry

Variant 3: ST_MapAlgebra(raster|geometry, [raster|geometry,…] 'mathematical expression', 'raster' |'geometry', raster) →raster/geometry

ST_MapAlgebra performs the specified mathematical expression on the input rasters, returning a raster or geometry. Both rasters must have the same SRID. If both rasters do not have the same SRID, ST_MapAlgebra will return an error:

ERROR: Operation on two geometries with different SRIDs

The first raster passed to ST_MapAlgebra is the 'master' raster, unless either:

1 additional parameter specifies the index (in the parameter list) of the 'master' raster.
1 additional parameter specifies a raster whose origin and cell size should be used to compute the output raster.
4 additional parameters are passed specifying the origin, cell size, and raster rotation.

This function implicitly calls ST_Intersects(raster|geometry, [raster|geometry,…]) to detect if the rasters are overlapping before performing any computation. Additionally, the resulting raster will have the same extent as the result of ST_Intersection(raster, integer, geometry).

One of the implications of the ST_Intersects inclusion is that:

SELECT ST_MapAlgebra(rast1, rast2, mathExpr) FROM mytable WHERE ST_Intersects(rast1, rast2)

will be faster than:

SELECT ST_MapAlgebra(rast1, rast2, mathExpr) FROM mytable

Open Question:

DZ: Should ST_MapAlgebra resample rasters internally, or produce a raster that can be processed by ST_Resample? If so, variant 1 and variant 3 can be removed, and all ST_MapAlgebra results can be processed through ST_Resample, like:

ST_Resample(ST_MapAlgebra(raster, [raster,…] 'mathematical expression', integer), originx, originy, pixelsizex, pixelsizey)
ST_Resample(ST_MapAlgebra(raster, [raster,…] 'mathematical expression', integer), rastergrid)

PR: I think this would greatly contribute to simplify the API.

ST_Clip(raster|geometry,geometry) → same type as first argument
ST_Flip(raster|geometry, ’vertical’|’horizontal’) → same type as first argument


Objective B03d - Being able to quickly get raster statistics.

Add cached basic raster statistic to the base raster WKB format.


Objective B03e - Being able to refer to band by textual name.

Add 8 digit string to each band in the base raster WKB format.

Adjust gdal2wktraster.py to be able to give names to each band when importing.

Adjust/overlaod every function to be able to refer to raster band by name.


PostGIS WKT Raster Beta 0.4


Objective B04a - Being able to convert a raster to standards formats.

ST_AsKML(raster|geometry) → string
ST_AsSVG(raster|geometry) → string


Objective B04b - Being able to control the validity of a raster.

ST_IsEmpty(raster|geometry) → boolean
ST_mem_size(raster|geometry) → integer
ST_isvalid(raster|geometry) → boolean


Objective B04c - Being able to use other major topological operators

ST_Within(raster|geometry A, raster|geometry B)
ST_Contains(raster|geometry A, raster|geometry B)
ST_Overlaps(raster|geometry, raster|geometry)


PostGIS WKT Raster Beta 0.5


Objective B05a - Being able to derive a raster layer from vector layer.

ST_Interpolate(points, pixelsize, method) → raster


Objective B05b - Being able to do on rasters most operations available on geometries

ST_Centroid(raster|geometry) → point geometry
ST_PointOnSurface(raster|geometry) → point geometry
ST_Buffer(raster|geometry, double) → same type as first arg.
ST_ConvexHull(raster|geometry) → same type as input
ST_Difference(raster|geometry A, raster|geometry B) → same type as first argument
ST_SymDifference(raster|geometry,raster|geometry,‘raster’|’geometry’) → raster/geometry


PostGIS WKT Raster Beta 0.6


Objective B06a - Being able to use all the other topological operators

ST_Equals(raster|geometry, raster|geometry)
ST_Disjoint(raster|geometry, raster|geometry)
ST_Touches(raster|geometry, raster|geometry)
ST_Crosses(raster|geometry, raster|geometry)
ST_Covers(raster|geometry A, raster|geometry B)
ST_IsCoveredBy(raster|geometry A, raster|geometry B)
ST_Relate(raster|geometry, raster|geometry, intersectionPatternMatrix )


Objective B07b - Being able to edit a raster

ST_Value(raster, band, x, y) → value
Return value of a single pixel. Pixel location is specified by 1-based index of Nth band of raster and X,Y coordinates.
The X coordinate is expected to be in range of [1, ST_Width(raster)] and Y coordinate in range of [1, ST_Height(raster))]. Return value is of type of 64-bit float-point number.
TODO: mloskot: Should we return NUMERIC instead of FLOAT8?

ST_SetValue(raster, band, x, y, value)
ST_Affine(raster|geometry,…) → same type as input
ST_Translate(raster|geometry,…) → same type as input
ST_Scale(raster|geometry,…) → same type as input
ST_TransScale(raster|geometry,…) → same type as input
ST_RotateZ,Y,Z(raster|geometry, float8) → same type as input

Other functions

ST_AsBinary(raster, compression)
ST_RasterFromWKB(raster, [<srid>])
ST_RasterFromText(string, [<srid>])
ST_AsText(raster)


Note: See TracWiki for help on using the wiki.