Skip to content

RS_Clip

Clips a raster to a geometry, setting pixels outside the geometry to nodata and (by default) cropping to the geometry’s bounding box.

Usage

raster RS_Clip(rast: raster, band: integer, geom: geometry)
raster RS_Clip(rast: raster, band: integer, geom: geometry, all_touched: boolean)
raster RS_Clip(rast: raster, band: integer, geom: geometry, all_touched: boolean, no_data_value: double)
raster RS_Clip(rast: raster, band: integer, geom: geometry, all_touched: boolean, no_data_value: double, crop: boolean)
raster RS_Clip(rast: raster, band: integer, geom: geometry, all_touched: boolean, no_data_value: double, crop: boolean, lenient: boolean)

Arguments

  • rast (raster): Input raster
  • band (integer)
  • geom (geometry)
  • all_touched (boolean)
  • no_data_value (double)
  • crop (boolean)
  • lenient (boolean): If true, a geometry that does not intersect the raster yields NULL; if false, it raises an error. Defaults to true.

[!WARNING]

Experimental. This function is experimental; its behavior may change without notice.

Description

RS_Clip clips a raster to a geometry, in the spirit of PostGIS ST_Clip. Pixels of the selected band that fall outside the geometry are set to the band’s nodata value (or no_data_value if given); pixels inside are kept. When crop is true (the default) the output is cropped to the geometry’s bounding box intersected with the raster extent, snapped to the pixel grid; unselected pixels within that window remain as nodata padding. Otherwise the original extent is preserved.

The geometry is reprojected into the raster’s CRS when both carry one. If exactly one side has a CRS, the call errors; if neither does, the geometry is used as-is.

A pixel is selected only when its center falls inside the geometry. A geometry smaller than a pixel, or a thin sliver, can therefore select no pixels even though it overlaps the raster; set all_touched to true to keep every pixel the geometry touches instead.

The clip is a 2-D (y, x) operation. For an N-D raster (bands with extra dimensions such as time), the same mask and crop window are broadcast across every non-spatial plane, so the non-spatial dimensions are preserved and only the (y, x) extent changes.

Examples

SELECT RS_Width(
  RS_Clip(
    RS_Example(),
    1,
    ST_GeomFromText('POLYGON ((60 90, 160 90, 160 190, 60 190, 60 90))', 'OGC:CRS84')
  )
);

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_width(rs_clip(rs_example(),Int64(1),st_geomfromtext(Utf8("POLYGON ((60 90 │
│          , 160 90, 160 190, 60 190, 60 90))"),Utf8("OGC:CRS84"))))…          │
╞══════════════════════════════════════════════════════════════════════════════╡
│                                                                           64 │
└──────────────────────────────────────────────────────────────────────────────┘

SELECT RS_Width(
  RS_Clip(
    RS_Example(),
    1,
    ST_GeomFromText('POLYGON ((60 90, 160 90, 160 190, 60 190, 60 90))', 'OGC:CRS84'),
    false,
    0.0,
    false
  )
);

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_width(rs_clip(rs_example(),Int64(1),st_geomfromtext(Utf8("POLYGON ((60 90 │
│ , 160 90, 160 190, 60 190, 60 90))"),Utf8("OGC:CRS84")),Boolean(false),Floa… │
╞══════════════════════════════════════════════════════════════════════════════╡
│                                                                           64 │
└──────────────────────────────────────────────────────────────────────────────┘