---
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

title: RS_Value
description: >
  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.
kernels:
  - returns: float64
    args:
    - raster
    - name: point
      type: geometry
      description: >
        The pixel that contains this point is sampled (no resampling).
        Reprojected into the raster CRS when both carry one.
  - returns: float64
    args:
    - raster
    - name: point
      type: geometry
    - name: band
      type: int
      description: >
        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.
---

::: callout-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 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

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