feat(rust/sedona-raster-functions): add RS_Value for spatial 2d rasters

docs/reference/sql/rs_value.qmd

@@ -0,0 +1,85 @@
+---
+# 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 either by a
+  point geometry or by 1-based grid coordinates. 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). Defaults to 1 if not specified.
+  - returns: float64
+    args:
+    - raster
+    - name: colX
+      type: int
+      description: Column index (1-based).
+    - name: rowY
+      type: int
+      description: Row index (1-based).
+  - returns: float64
+    args:
+    - raster
+    - name: colX
+      type: int
+    - name: rowY
+      type: int
+    - name: band
+      type: int
+      description: Band index (1-based). Defaults to 1 if not specified.
+---
+
+## Description
+
+`RS_Value` samples one pixel of a raster. The location is given either as a
+point geometry — the value of the pixel that contains the point is returned, with
+no interpolation — or as 1-based `(colX, rowY)` grid coordinates. The band
+defaults to 1.
+
+The result is `NULL` when the point or grid cell 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(), 2, 1);
+```
+
+```sql
+SELECT RS_Value(RS_Example(), 2, 1, 2);
+```
+
+```sql
+SELECT RS_Value(RS_Example(), ST_SetCRS(ST_Point(74.58, 110.57), 'OGC:CRS84'));
+```

python/sedonadb/tests/functions/test_raster_functions.py

@@ -98,3 +98,52 @@ def test_rs_ensureloaded(con, sedona_testing):
     assert arr.shape == (512, 512)
     assert arr.dtype == "uint16"
     assert arr[0, 0] == 2324
+
+
+# RS_Example fills band `b` with the constant value `b`, except the top-left
+# pixel (colX=1, rowY=1) which is set to the nodata value (127). Grid
+# coordinates are 1-based. (The `needs_pixels` -> RS_EnsureLoaded planner path
+# is covered against a real OutDb raster by `test_rs_ensureloaded`.)
+@pytest.mark.parametrize(
+    ("expr", "expected"),
+    [
+        ("RS_Value(RS_Example(), 2, 1)", 1.0),  # band 1, away from the nodata corner
+        ("RS_Value(RS_Example(), 64, 32)", 1.0),  # bottom-right pixel, in bounds
+        ("RS_Value(RS_Example(), 2, 1, 1)", 1.0),  # explicit band 1 == the default
+        ("RS_Value(RS_Example(), 2, 1, 2)", 2.0),  # band 2
+        ("RS_Value(RS_Example(), 2, 1, 3)", 3.0),  # band 3
+        ("RS_Value(RS_Example(), 1, 1)", None),  # top-left pixel is nodata
+        ("RS_Value(RS_Example(), 1, 1, 2)", None),  # nodata on band 2 too
+        ("RS_Value(RS_Example(), 65, 1)", None),  # colX past the width (64)
+        ("RS_Value(RS_Example(), 1, 33)", None),  # rowY past the height (32)
+        ("RS_Value(RS_Example(), 0, 1)", None),  # colX 0 -> off the left edge
+        ("RS_Value(RS_Example(), 2, 1, CAST(NULL AS INT))", None),  # NULL band -> NULL
+    ],
+)
+def test_rs_value_grid(expr, expected):
+    SedonaDB().assert_query_result(f"SELECT {expr}", expected)
+
+
+# Point sampling. (74.58, 110.57) is the centroid of pixel (10, 10) (0-based)
+# in the raster's OGC:CRS84 space; the point and raster share a CRS so no
+# reprojection happens. A point far outside the footprint yields NULL.
+@pytest.mark.parametrize(
+    ("expr", "expected"),
+    [
+        (
+            "RS_Value(RS_Example(), ST_SetCRS(ST_Point(74.58, 110.57), 'OGC:CRS84'))",
+            1.0,
+        ),
+        (
+            "RS_Value(RS_Example(), ST_SetCRS(ST_Point(74.58, 110.57), 'OGC:CRS84'), 2)",
+            2.0,
+        ),
+        (
+            "RS_Value(RS_Example(), ST_SetCRS(ST_Point(74.58, 110.57), 'OGC:CRS84'), 3)",
+            3.0,
+        ),
+        ("RS_Value(RS_Example(), ST_SetCRS(ST_Point(0.0, 0.0), 'OGC:CRS84'))", None),
+    ],
+)
+def test_rs_value_point(expr, expected):
+    SedonaDB().assert_query_result(f"SELECT {expr}", expected)

rust/sedona-raster-functions/Cargo.toml

@@ -37,6 +37,7 @@ arrow-buffer = { workspace = true }
 async-trait = { workspace = true }
 datafusion-common = { workspace = true }
 datafusion-expr = { workspace = true }
+geo-traits = { workspace = true }
 sedona-common = { workspace = true }
 sedona-expr = { workspace = true }
 sedona-geometry = { workspace = true }
@@ -49,7 +50,6 @@ wkb = { workspace = true }
 
 [dev-dependencies]
 criterion = { workspace = true }
-geo-traits = { workspace = true }
 sedona-testing = { workspace = true, features = ["criterion"] }
 sedona-proj = { workspace = true, features = ["proj-sys"] }
 rstest = { workspace = true }

rust/sedona-raster-functions/benches/native-raster-functions.rs

@@ -214,6 +214,38 @@ fn criterion_benchmark(c: &mut Criterion) {
         ),
     );
 
+    // RS_Value(raster, colX, rowY) - grid sampling
+    benchmark::scalar(
+        c,
+        &f,
+        "native-raster",
+        "rs_value",
+        BenchmarkArgs::ArrayScalarScalar(Raster(64, 64), Int32(1, 64), Int32(1, 64)),
+    );
+    // RS_Value(raster, point)
+    benchmark::scalar(
+        c,
+        &f,
+        "native-raster",
+        "rs_value",
+        BenchmarkArgs::ArrayArray(
+            Raster(64, 64),
+            Transformed(Box::new(Point), sd_apply_default_crs_udf().into()),
+        ),
+    );
+    // RS_Value(raster, point, band)
+    benchmark::scalar(
+        c,
+        &f,
+        "native-raster",
+        "rs_value",
+        BenchmarkArgs::ArrayArrayScalar(
+            Raster(64, 64),
+            Transformed(Box::new(Point), sd_apply_default_crs_udf().into()),
+            Int32(1, 2),
+        ),
+    );
+
     // RS_Intersects(raster, geometry) - point
     benchmark::scalar(
         c,

rust/sedona-raster-functions/src/lib.rs

@@ -38,4 +38,5 @@ pub mod rs_size;
 pub mod rs_slice;
 pub mod rs_spatial_predicates;
 pub mod rs_srid;
+pub mod rs_value;
 pub mod rs_worldcoordinate;

rust/sedona-raster-functions/src/register.rs

@@ -77,6 +77,7 @@ pub fn default_function_set() -> FunctionSet {
         crate::rs_spatial_predicates::rs_within_udf,
         crate::rs_srid::rs_crs_udf,
         crate::rs_srid::rs_srid_udf,
+        crate::rs_value::rs_value_udf,
         crate::rs_worldcoordinate::rs_rastertoworldcoord_udf,
         crate::rs_worldcoordinate::rs_rastertoworldcoordx_udf,
         crate::rs_worldcoordinate::rs_rastertoworldcoordy_udf,