Changes between Version 24 and Version 25 of WKTRaster/SpecificationFinal01

Timestamp:

Aug 27, 2010, 11:51:11 AM (14 years ago)

Author:

pracine

Comment:

—

WKTRaster/SpecificationFinal01

@@ -110 +110 @@
 '''ST_BandNoDataValue(raster, integer) -> float32'''[[BR]]
 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.
+
+----
+== '''Objective 0.1.6e - Being able to intersect vector and raster to produce vector.''' ==
+
+List of PostGIS functions similar or related to ST_GetBBox(), ST_Envelope() and ST_Polygon():
+
+[http://postgis.refractions.net/documentation/manual-1.4/ST_Boundary.html ST_Boundary(geometry)] (not really - always return a geometry a dimension lower - i.e. the boundary of a polygon is a polyline.)
+
+ST_box(geometry) (return a PostgreSQL box object)
+
+[http://postgis.refractions.net/documentation/manual-1.4/ST_Box2D.html ST_box2d(geometry)] (return a box2d object)
+
+[http://postgis.refractions.net/documentation/manual-1.4/ST_Box3D.html ST_box3d(geometry)] (return a box3d object)
+
+getBBOX(geometry) (Deprecation in 1.2.3)
+
+[http://postgis.refractions.net/documentation/manual-1.4/ST_Envelope.html ST_Envelope(geometry)] Returns the minimum bounding box for the supplied geometry, as a geometry. The polygon is defined by the corner points of the bounding box ((MINX, MINY), (MINX, MAXY), (MAXX, MAXY), (MAXX, MINY), (MINX, MINY)). (PostGIS will add a ZMIN/ZMAX coordinate as well). In PostGIS, the bounding box of a geometry is represented internally using float4s instead of float8s that are used to store geometries. The bounding box coordinates are floored, guarenteeing that the geometry is contained entirely within its bounds. This has the advantage that a geometry's bounding box is half the size as the minimum bounding rectangle, which means significantly faster indexes and general performance. But it also means that the bounding box is NOT the same as the minimum bounding rectangle that bounds the geometry.
+
+envelope(geometry) (Deprecation in 1.2.3)
+
+[http://postgis.refractions.net/documentation/manual-1.4/ST_Extent.html ST_extent(geometry set)]
+
+[http://postgis.refractions.net/documentation/manual-1.4/ST_ExteriorRing.html ST_ExteriorRing(geometry)]
+
+[http://postgis.refractions.net/documentation/manual-1.4/ST_ConvexHull.html ST_ConvexHull(geometry)]
+
+'''Function definitions for WKT Raster 0.1.6'''
+
+ST_GetBBox(raster) (not yet implemented but planned) is replaced with ST_Envelope() since there is no more an equivalent ST_GetBBox function in PostGIS.
+
+ST_Raster_to_box2d(raster) should be renamed ST_box2d(raster).
+
+'''ST_Box2D(raster) -> BOX2D''' - Returns a BOX2D representing the extent of the raster.
+
+ If the raster is rotated, the result is a box2d enclosing the rotated raster.
+
+ The only difference with ST_Envelope(raster) is that ST_Box2D(raster) returns a BOX2D, not a geometry.
+
+ '''Implementation details'''
+
+ This function is not anymore available in PostGIS 1.5 and is therefore probably not worth implementing.
+
+ This function replaces ST_Raster_to_box2d() and should be used for the "raster AS box2d" cast. It should also be used instead of ST_raster_envelope() when creating indexes in gdal2wktraster.py (to be tested).
+
+'''ST_Envelope(raster) -> polygon geometry''' - Returns the minimum bounding box for the supplied raster, as a geometry. 
+
+ If the raster is rotated, the envelope is a non-rotated box enclosing the rotated raster.
+
+ The only difference with ST_Box2D(raster) is that ST_Envelope(raster) returns a geometry, not a BOX2D.
+
+
+ '''Implementation details'''
+
+ This function should be implemented as a SQL or a PL/pgSQL function looking like: 'SELECT ST_geometry(ST_Box2D(rast))'
+
+ There is already a ST_raster_envelope() function but this has actually the behavior of the ST_ConvexHull(raster) described below. There is also a ticket (#348) related to this function: http://trac.osgeo.org/postgis/ticket/348
+
+[[Image(WKTRasterEnvelopeConvexHullAndPolygon.gif)]]
+
+'''ST_ConvexHull(raster) -> polygon geometry''' - Returns the minimum convex geometry that encloses every pixel from the raster. 
+
+ The resulting polygon DOES NOT TAKE the NODATA values into account. The resulting polygon enclose every pixel, even those containing NODATA values. The resulting polygon can be rotated or not depending on the rotation of the raster. If the raster is not rotated ST_ConvexHull(geometry) is (almost) equivalent to ST_Envelope(raster) (ST_Envelope floor the coordinates and hence add a little buffer around the raster).
+
+ '''Implementation details'''
+
+ This function is actually already implemented by the ST_raster_envelope() function which is wrongly named. There is also a ticket (#348) related to this function: http://trac.osgeo.org/postgis/ticket/348
+
+'''ST_Polygon(raster, integer) -> polygon geometry''' - Returns a geometry encomparsing every pixel having a significant value (different than the NODATA value) for the provided band.
+
+ This polygon geometry might contain holes if some internal areas of the raster contain pixels with NODATA values.
+
+ Variant 1: ST_Polygon(raster) -> polygon geometry -- default to band # 1
+
+ '''Implementation details'''
+
+ Could also be named ST_Outline().
+
+ This function could be roughly implemented as a SQL function looking like 'SELECT ST_Collect((ST_DumpAsPolygons(raster)).geom)'. For sure a more specialised version could be faster than ST_AsPolygon.
+
+'''ST_DumpAsPolygons(raster, integer) -> geomval set''' - Returns a set of "geomval" value, one for each contiguous group of pixel sharing the same value for the provided band.
+
+ This is a set-returning function (SRF). A "geomval" value is a complex type composed of a polygon geometry (one for each contiguous group of pixel sharing the same value) and the value associated with this geometry. These values are always returned as a value of type double precision. The shape of each polygon follow pixels edges.
+
+ Variant 1: ST_DumpAsPolygons(raster) -> geomval set -- default to band # 1
+
+ This function should be used with precaution on raster with float pixel type as it could return one "geomval" (or polygon) per pixel. This kind of raster should be reclassified (using the planned ST_Reclassify(raster,...) function) before using ST_DumpAsPolygons().
+
+ '''Implementation details'''
+ 
+ This function is at the base of the first version of ST_Intersection which compute the intersection between a raster and a geometry.
+
+ To avoid linking directly with PostGIS (see "Why avoid to link with PostGIS?" below) It should be implemented as a SQL wrapper around DumpAsWKTPolygons() looking something like this:
+
+ CREATE TYPE geomval AS (geom geometry, val float8);[[BR]]
+ CREATE TYPE wktgeomval AS (wktgeom text, val float8);
+
+ CREATE OR REPLACE FUNCTION ST_DumpAsPolygons(rast raster) RETURNS SETOF geomval AS $$[[BR]]
+     SELECT ST_GeomFromText(wktgeomval.wktgeom), wktgeomval.val FROM DumpAsWKTPolygons(%1) AS wktgeomval;[[BR]]
+ $$ LANGUAGE SQL;
+
+ It should then be used like this:
+
+ SELECT (gv).val, (gv).geom FROM (SELECT ST_DumpAsPolygons(rast) gv FROM sometable) foo
+
+[[Image(WKTRasterAsPolygon.gif)]]
+
+'''DumpAsWKTPolygons(raster, integer) -> wktgeomval set''' - Returns a set of "geomval" value, one for each group of pixel sharing the same value for the provided band.
+
+ Variant 1: DumpAsWKTPolygons(raster) -> wktgeomval set -- default to band # 1
+
+ This is a set-returning function (SRF). A "wktgeomval " value is a complex type composed of a the wkt representation of a geometry (one for each group of pixel sharing the same value) and the value associated with this geometry. These values are always returned as a value of type double precision. The shape of each polygon follow pixels edges. Areas with NODATA values are not included in the resulting set.
+
+ This function should be used with precaution on raster with float pixel type as it could return one "geomval" (or polygon) per pixel. This kind of raster should be reclassified (using the planned ST_Reclassify(raster,...) function) before using DumpAsWKTPolygons().
+
+ DumpAsWKTPolygons() should not be used directly. Use ST_DumpAsPolygons() instead.
+
+ '''Implementation details'''
+ 
+ This function construct the WKT strings representing the geometries grouping pixels of a raster having the same value. It does not directly construct geometries and therefore prevent WKT Raster from having to link with liblwgeom.a (see "Why avoid to link with PostGIS?" below) It should also return the value associated with this WKT polygon.
+
+ It should be implemented as a C function passing the raster to GDAL and converting each polygon produced by the [http://www.gdal.org/gdal__alg_8h.html GDALPolygonize function] to a WKT string accompagned by its corresponding value in a wktgeomval type. See http://www.postgresql.org/docs/8.4/interactive/xfunc-c.html#AEN44970 on how to return rows and sets in a C function.
+
+
+'''ST_Intersects(raster, integer, geometry) -> boolean''' - Returns TRUE if the geometry and the raster "spatially intersect" - (share any portion of space) and FALSE if they don't (they are disjoint). 
+
+ Variant 1: ST_Intersects(geometry, raster, integer) -> boolean -- the third parameter is the raster band number
+
+ Variant 2: ST_Intersects(geometry, raster) -> boolean -- default to band # 1
+ 
+ Variant 3: ST_Intersects(raster, geometry) -> boolean -- default to band # 1
+
+ Variant 4: ST_Intersects(raster, raster) -> boolean
+
+ This function permform a full intersection test and proceed in three steps to determine if the raster intersects with the geometry:
+
+ 1) First, it checks if the bounding box of the raster intersects with the bounding box of the geometry.
+
+ 2) If the first test returns TRUE, it checks if the geometry returned by ST_ConvexHull(raster) intersects with the geometry.
+
+ 3) If the second test returns TRUE, it checks if the geometry returned by ST_Polygon(raster, integer) intersects with the geometry. This test is slower since it involve the computation of the raster shape and it might involve the geometry shape. This test takes NODATA values into account. i.e. A geometry intersecting only with a NODATA value area of a raster is NOT actually not intersecting with this raster. This behavior may be controled by limiting the test to certain conditions as stated below. 
+
+ Variant 4 proceeds in a very similar way except that convex hulls of both rasters are computed and compared in step 2) and both shape of raster are computed and compared in step 3).
+
+ If you want to limit the intersection test to the first condition, simply use the && operator. The raster and the geometry will be casted to their respective bounding box (box2d objects):
+
+  raster && geometry
+
+ If you want to limit the intersection test to the second condition you can write:
+
+  ST_Intersects(ST_ConvexHull(raster), geometry)
+
+ '''Implementation details'''
+ 
+ This function should be implemented as a pl/pgSQL function performing the three test described one after and conditionally to the other.
+
+ It might be faster to skip test 2) if this test is not signicantly faster than test 3).
+
+'''ST_Intersection(raster, integer, geometry) -> geometry''' - Returns a set of "geomval" value representing the shared portion of the geometry and the raster band areas sharing a common meaningfull values. The integer parameter is the band number of the raster.
+
+ Variant 1: 
+
+  ST_Intersection(raster, geometry) -> geometry -- default to band # 1[[BR]]
+  ST_Intersection(geometry, raster, integer) -> geometry -- the integer parameter is the band number of the raster[[BR]]
+  ST_Intersection(geometry, raster) -> geometry -- default to band # 1
+
+ Variant 2: 
+
+  ST_Intersection(raster, integer, geometry, 'raster') -> raster -- the integer parameter is the band number of the raster[[BR]] 
+  ST_Intersection(raster, geometry, 'raster') -> raster -- default to band # 1
+
+ Variant 3: 
+
+  ST_Intersection(geometry, raster, integer, 'raster') -> raster -- the integer parameter is the band number of the raster[[BR]]
+  ST_Intersection(geometry, raster, 'raster') -> raster -- default to band # 1
+
+ Variant 4: 
+
+  ST_Intersection(raster, integer, raster, integer) -> raster -- the integer parameters are the band number of the rasters[[BR]]
+  ST_Intersection(raster, raster, integer) -> raster -- default first raster to band # 1[[BR]]
+  ST_Intersection(raster, integer, raster) -> raster -- default second raster to band # 1[[BR]]
+  ST_Intersection(raster, raster) -> raster -- default both rasters to band # 1
+
+ Variant 5: 
+
+  ST_Intersection(raster, integer, raster, integer, 'geometry') -> geometry[[BR]]
+  ST_Intersection(raster, raster, integer, 'geometry') -> geometry -- default first raster to band # 1[[BR]]
+  ST_Intersection(raster, integer, raster, 'geometry') -> geometry -- default second raster to band # 1[[BR]]
+  ST_Intersection(raster, raster, 'geometry') -> geometry -- default both raster to band # 1
+
+ This is a set-returning function (SRF). It returns a set of "geomval" representing the point set intersection of the geometry and the areas of the raster sharing a common meaningfull value (NODATA values ARE taken into account). The raster is first polygonised using ST_DumpAsPolygons(raster) and ST_Intersection(geometry, geometry) is then performed between the provided geometry and all the geometries resulting from the polygonisation of the raster.
+
+ If the geometries do not share any space (are disjoint), then an empty geometry collection is returned.
+
+ ST_Intersection in conjunction with ST_Intersects is very useful for clipping geometries such as in bounding box, buffer, region queries where you only want to return that portion of a geometry that sits in a country or region of interest.
+
+ If you only want to compute the intersection between the convex hull of the raster without polygonising it to group of pixels sharing a common value, do:
+
+  ST_Intersection(ST_ConvexHull(raster), geometry)
+
+ If you only want to compute the intersection between the shape of the raster without polygonising it to group of pixels sharing a common value, do:
+
+  ST_Intersection(ST_Polygon(raster), geometry)
+
+ '''Implementation details'''
+
+ This function should be implemented as a pl/pgSQL function (possibly only a SQL function) performing the intersection between the provided geometry and the table generated by ST_DumpAsPolygons(raster).
+
+ Priority 1 should be given to the raster/geometry variants (original and variant 1) returning a geometry. 
+
+ Priority 2 should be given to the raster/raster variants (5) returning a geometry. 
+
+ Priority 3 should be given to the other variants (2, 3 & 4) returning a raster. Variant 2 & 3 should be implemented after the planned ST_AsRaster(geometry) function. What should be the raster result of the intersection of two rasters is still to be specified.
+
 
 ----