Skip to content

RS_Value

Returns the value of a single raster pixel as a double, selected by a point geometry. Returns null if the location is outside the raster or the pixel holds the band’s nodata value.

Usage

float64 RS_Value(rast: raster, point: geometry)
float64 RS_Value(rast: raster, point: geometry, band: int)
float64 RS_Value(rast: raster, colX: int, rowY: int, band: int)

Arguments

  • rast (raster): Input raster
  • colX (int): Pixel column (1-based).
  • rowY (int): Pixel row (1-based).
  • band (int): Band index (1-based). When omitted, defaults to band 1, but only for a single-band raster; sampling an unspecified band of a multiband raster is ambiguous and raises an error.
  • point (geometry): The pixel that contains this point is sampled (no resampling). Reprojected into the raster CRS when both carry one.

[!WARNING]

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

Description

RS_Value samples one pixel of a raster. The location is given as a point geometry — the value of the pixel that contains the point is returned, with no interpolation. The band defaults to 1 when omitted, but only for a single-band raster; on a multiband raster the band must be given explicitly.

The pixel can instead be addressed by its grid coordinate. Grid coordinates are 1-based, as in PostGIS ST_Value: (1, 1) is the upper-left pixel, and a column or row of 0 is outside the raster.

The result is NULL when the point falls outside the raster, or when the sampled pixel equals the band’s nodata value. Only 2-D rasters are supported.

Examples

SELECT RS_Value(RS_Example(), ST_Point(74.58, 110.57, 'OGC:CRS84'), 1);

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_value(rs_example(),st_point(Float64(74.58),Float64(110.57),Utf8("OGC:CRS8 │
│                                4")),Int64(1))…                               │
╞══════════════════════════════════════════════════════════════════════════════╡
│                                                                          1.0 │
└──────────────────────────────────────────────────────────────────────────────┘

The upper-left pixel of band 1, by grid coordinate:

SELECT RS_Value(RS_Example(), 1, 1, 1);

┌───────────────────────────────────────────────────┐
│ rs_value(rs_example(),Int64(1),Int64(1),Int64(1)) │
│                      float64                      │
╞═══════════════════════════════════════════════════╡
│                                                   │
└───────────────────────────────────────────────────┘