= '''PostGIS Raster Working Specifications for PostGIS 2.0''' = {{{ #!div style='background-color: #F4F4F4; padding: 5px; border: 1px solid gray; float: right; margin-left: 5px; width: 260px; font-size: small;' > '''Quick Links''' * [wiki:WKTRaster PostGIS Raster Home Page] * [wiki:WKTRaster/PlanningAndFunding Planning & Funding] * [wiki:WKTRaster/Documentation01 Beta Documentation] * [wiki:WKTRaster/SpecificationWorking03 Working Specifications for Future Versions] * [wiki:WKTRaster/SpecificationFinal01 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. See discussion in http://trac.osgeo.org/postgis/ticket/482 '''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''' The first series of variant allow specifying the number of the band used in the expression. 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) The second series of variant default the band 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 PL/pgSQL script of the one raster version of ST_MapAlgebra implemented at the top of http://trac.osgeo.org/postgis/browser/trunk/raster/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.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). See discussion in http://trac.osgeo.org/postgis/ticket/594 '''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. See discussion in http://trac.osgeo.org/postgis/ticket/593 ---- == '''Objective 2.0.05 - Being able to set and get values for part of a raster.''' == '''ST_SetValues''' Set a set of pixel to a value. Those functions are provided as a faster way to set pixels than the (future) two rasters version of ST_MapAlgebra which can also be used when more conditional flexibility is necessary. They should also be used in this version of ST_MapAlgebra to quicly set large areas to a single value. '''Variants''' The first series of variant set a defined area of the raster to a value. 1) ST_SetValues(rast raster, band int, x int, y int, width int, height int, val float8, keepdestnodata boolean) 2) ST_SetValues(rast raster, x int, y int, width int, height int, val float8, keepdestnodata boolean) 3) ST_SetValues(rast raster, x int, y int, width int, height int, val float8) 4) ST_SetValues(rast raster, band int, x int, y int, width int, height int, val float8) The second series of variant set a defined area of the raster to corresponding values of another raster. 5) ST_SetValues(rast1 raster, band1 int, x int, y int, width int, height int, rast2 raster, band2 int, keepdestnodata boolean, keepsourcenodata boolean) 6) ST_SetValues(rast1 raster, x int, y int, width int, height int, rast2 raster, keepdestnodata boolean, keepsourcenodata boolean) 7) ST_SetValues(rast1 raster, x int, y int, width int, height int, rast2 raster) x, y, width & height define the area of the raster to be edited. x & y are the raster coordinates of the upper left corner of this are. When x, y, width or height are out of the raster range, only the part of the range intersecting with the raster is set to the new value. val is the new value to be set. When keepdestnodata is TRUE, destination nodata value pixels are not set. Default is FALSE so that nodata value pixels are set. When keepsourcenodata is TRUE, source nodata value pixels are not copied. Default is FALSE so that nodata value pixels are copied. Variant 2 assume band to be 1. Variant 3 assume band to be 1 and keepdestnodata to be FALSE. Variant 4 assume only keepdestnodata to be FALSE. Variant 6 assume both bands to be 1. Variant 7 assume both bands to be 1, keepdestnodata to be FALSE and keepsourcenodata to be FALSE. '''Implementation details''' PL/pgSQL prototypes can be found in http://trac.osgeo.org/postgis/browser/trunk/raster/scripts/plpgsql/st_setvalues.sql '''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, nodata float8 DEFAULT null) -> raster 2) ST_Clip(raster, band, ulx float8, uly float8, width int, height int, nodata float8 DEFAULT null) -> raster 3) ST_Clip(raster, geometry, nodata float8 DEFAULT null, trim boolean DEFAULT false) -> raster 4) ST_Clip(raster, band, geometry, nodata float8 DEFAULT null, trim boolean DEFAULT false) -> raster Variant 1 and 2 take the upper left corner, the width and the height of the desired extent. Variant 3 and 4 set every pixels outside the provided geometry to nodata. The 'trim' parameter determines if the resulting raster extent should be the one of the original raster or the one of the intersection between the raster and the geometry, thus trimming nodata values as much as possible. Variants 2 and 4 returns only the selected band in the clipped raster. Variant 1 and 3 returns all bands. When no nodata value is provided, the resulting raster keeps its nodata value. If the raster does not have a nodata value, the minimum possible value for the pixeltype of each band is used as nodata value. If the geometry is totally included into one pixel (a point for example), only this pixel is kept in the returned raster. '''Implementation details''' All variants are implemented as a wrapper around ST_MapAlgebra(raster, ST_AsRaster(geometry)). This function is useful to optimize ST_Intersection(raster, geometry). 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''' == '''ST_AddBand''' Add a band to a raster. The new band can be filled with nodata values or comes from another raster. The index where to insert the new band, the pixel type, the initial value and the nodata value can all be specified. When the index is not specified, the raster is added as the last band of the raster. If no nodata value is provided the added band has no nodata value. If no initial value is provided the initial value is 0. '''Variants''' The first series of variant add the new band at the specified index. 1) ST_AddBand(rast raster, index int, pixeltype text, initialvalue float8, nodataval float8) 2) ST_AddBand(rast raster, index int, pixeltype text, initialvalue float8) 3) ST_AddBand(rast raster, index int, pixeltype text) The second series of variant add the new band as the last band. 4) ST_AddBand(rast raster, pixeltype text, initialvalue float8, nodataval float8) 5) ST_AddBand(rast raster, pixeltype text, initialvalue float8) 6) ST_AddBand(rast raster, pixeltype text) The third series of variant add a band as the copy of another raster band. 7) ST_AddBand(rast1 raster, rast2 raster, band int, index int) 8) ST_AddBand(rast1 raster, rast2 raster, band int) 9) ST_AddBand(rast1 raster, rast2 raster) Variant 8 and 9 add the rast2 band as the last band of rast1. '''Implementation details''' Only variant 1 should be implemented as a C functions. Others variants are PL/pgSQL variants. Variant 7 is useful to optimize ST_MapAlgebra.