Description

Returns a raster or a set of geometry-pixelvalue pairs representing the shared portion of two rasters or the geometrical intersection of a vectorization of the raster and a geometry.

The first three variants, returning a setof geomval, works in vector space. The raster is first vectorized (using ST_DumpAsPolygons) into a set of geomval rows and those rows are then intersected with the geometry using the ST_Intersection (geometry, geometry) PostGIS function. Geometries intersecting only with a nodata value area of a raster returns an empty geometry. They are normally excluded from the results by the proper usage of ST_Intersects in the WHERE clause.

You can access the geometry and the value parts of the resulting set of geomval by surrounding them with parenthesis and adding '.geom' or '.val' at the end of the expression. e.g. (ST_Intersection(rast, geom)).geom

The other variants, returning a raster, works in raster space. They are using the two rasters version of ST_MapAlgebraExpr to perform the intersection.

The extent of the resulting raster corresponds to the geometrical intersection of the two raster extents. The resulting raster includes 'BAND1', 'BAND2' or 'BOTH' bands, following what is passed as the returnband parameter. Nodata value areas present in any band results in nodata value areas in every bands of the result. In other words, any pixel intersecting with a nodata value pixel becomes a nodata value pixel in the result.

Rasters resulting from ST_Intersection must have a nodata value assigned for areas not intersecting. You can define or replace the nodata value for any resulting band by providing a nodataval[] array of one or two nodata values depending if you request 'BAND1', 'BAND2' or 'BOTH' bands. The first value in the array replace the nodata value in the first band and the second value replace the nodata value in the second band. If one input band do not have a nodata value defined and none are provided as an array, one is chosen using the ST_MinPossibleValue function. All variant accepting an array of nodata value can also accept a single value which will be assigned to each requested band.

In all variants, if no band number is specified band 1 is assumed. If you need an intersection between a raster and geometry that returns a raster, refer to ST_Clip.

	To get more control on the resulting extent or on what to return when encountering a nodata value, use the two rasters version of ST_MapAlgebraExpr.

	To compute the intersection of a raster band with a geometry in raster space, use ST_Clip. ST_Clip works on multiple bands rasters and does not return a band corresponding to the rasterized geometry.

	ST_Intersection should be used in conjunction with ST_Intersects and an index on the raster column and/or the geometry column.

Enhanced: 2.0.0 - Intersection in the raster space was introduced. In earlier pre-2.0.0 versions, only intersection performed in vector space were supported.

Examples: Geometry, Raster -- resulting in geometry vals

SELECT
	foo.rid,
	foo.gid,
	ST_AsText((foo.geomval).geom) As geomwkt,
	(foo.geomval).val
FROM (
	SELECT
		A.rid,
		g.gid,
		ST_Intersection(A.rast, g.geom) As geomval
	FROM dummy_rast AS A
	CROSS JOIN (
		VALUES
			(1, ST_Point(3427928, 5793243.85) ),
			(2, ST_GeomFromText('LINESTRING(3427927.85 5793243.75,3427927.8 5793243.75,3427927.8 5793243.8)')),
			(3, ST_GeomFromText('LINESTRING(1 2, 3 4)'))
	) As g(gid,geom)
	WHERE A.rid = 2
) As foo;

 rid | gid |      geomwkt												| val
-----+-----+---------------------------------------------------------------------------------------------
   2 |   1 | POINT(3427928 5793243.85)									| 249
   2 |   1 | POINT(3427928 5793243.85)									| 253
   2 |   2 | POINT(3427927.85 5793243.75)								| 254
   2 |   2 | POINT(3427927.8 5793243.8)									| 251
   2 |   2 | POINT(3427927.8 5793243.8)									| 253
   2 |   2 | LINESTRING(3427927.8 5793243.75,3427927.8 5793243.8)	| 252
   2 |   2 | MULTILINESTRING((3427927.8 5793243.8,3427927.8 5793243.75),...) | 250
   2 |   3 | GEOMETRYCOLLECTION EMPTY
					

See Also

geomval, ST_Intersects, ST_MapAlgebraExpr, ST_Clip, ST_AsText