RS_AsRaster¶

Introduction: RS_AsRaster converts a vector geometry into a raster dataset by assigning a specified value to all pixels covered by the geometry. Unlike RS_Clip, which extracts a subset of an existing raster while preserving its original values, RS_AsRaster generates a new raster where the geometry is rasterized onto a raster grid. The function supports all geometry types and takes the following parameters:

geom: The geometry to be rasterized.
raster: The reference raster to be used for overlaying the geom on.
pixelType: Defines data type of the output raster. This can be one of the following, D (double), F (float), I (integer), S (short), US (unsigned short) or B (byte).
allTouched (Since: v1.7.1): Decides the pixel selection criteria. If set to true, the function selects all pixels touched by the geometry, else, selects only pixels whose centroids intersect the geometry. Defaults to false. As in GDAL, pixels are half-open: a pixel contains its first edges in pixel order (the left and top edges on a north-up raster) but not its last, so a pixel the geometry touches only on its boundary is not selected, and a polygon whose edges lie on pixel grid lines selects only the pixels inside it. For lines and polygon boundaries, when a vertex maps exactly to a pixel grid line, a neighboring pixel contacted only at that endpoint is not selected unless the segment enters it. POINT geometries burn the single pixel that contains the point under the same rule, whatever allTouched is: a point on a pixel edge or corner burns the pixel after it in pixel order, and a point on the raster's last edge burns nothing.
value: The value to be used for assigning pixels covered by the geometry. Defaults to using 1.0 if not provided.
noDataValue: The no data value of the resultant raster. Every pixel the geometry does not cover (including interior holes) is filled with the resolved no data value, which is also recorded as the output band's no data metadata. The value must be representable in pixelType: an out-of-range or fractional value for an integer pixelType, or a value that is not exactly representable in a floating-point pixelType (for example 0.1 in a 32-bit float band), is rejected with an error rather than silently coerced. NaN is supported as a no data value for F and D pixel types; infinite no data values are not supported. When noDataValue is not provided, it is inherited from the reference raster's first band, and RS_AsRaster errors if that band has no no data value. The programmatic API additionally accepts an explicit null noDataValue, which produces a raster with no no data value and a 0 background.
useGeometryExtent: Defines the extent of the resultant raster. When set to true, it corresponds to the extent of geom, and when set to false, it corresponds to the extent of raster. Default value is true if not set. When set to true and geom neither burns nor overlaps any pixel of raster, for example a polygon that only touches its boundary or a line along its right or bottom edge, there is nothing to crop to and RS_AsRaster returns null. A polygon that overlaps a pixel without covering its centre still returns its cropped, unburned raster.

Format:

RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String)

RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, allTouched: Boolean)

RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, allTouched: Boolean, value: Double)

RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, allTouched: Boolean, value: Double, noDataValue: Double)

RS_AsRaster(geom: Geometry, raster: Raster, pixelType: String, allTouched: Boolean, value: Double, noDataValue: Double, useGeometryExtent: Boolean)

Return type: Raster

Since: v1.5.0

Note

The function doesn't support rasters that have any one of the following properties:

ScaleX < 0
SkewX != 0
SkewY != 0

If a raster is provided with any one of these properties, then an IllegalArgumentException is thrown.

For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the Affine Transformations section.

SQL Example

SELECT RS_AsRaster(
        ST_GeomFromWKT('POLYGON((15 15, 18 20, 15 24, 24 25, 15 15))'),
        RS_MakeEmptyRaster(2, 255, 255, 3, -215, 2, -2, 0, 0, 4326),
        'D', false, 255.0, 0d
    )

Output:

GridCoverage2D["g...

SQL Example

With the noDataValue omitted, the output inherits the reference band's no data value (here 0, set on the empty reference raster) and fills uncovered pixels with it:

SELECT RS_AsRaster(
        ST_GeomFromWKT('POLYGON((15 15, 18 20, 15 24, 24 25, 15 15))'),
        RS_SetBandNoDataValue(RS_MakeEmptyRaster(2, 255, 255, 3, -215, 2, -2, 0, 0, 4326), 1, 0),
        'D'
    )

Output:

GridCoverage2D["g...

SQL Example

SELECT RS_AsRaster(
        ST_GeomFromWKT('POLYGON((15 15, 18 20, 15 24, 24 25, 15 15))'),
        RS_MakeEmptyRaster(2, 255, 255, 3, 215, 2, -2, 0, 0, 0),
       'D', true, 255, 0d, false
)

Output:

GridCoverage2D["g...