feat(rust/sedona-raster-gdal): add RS_FromGDALRaster

docs/reference/sql/rs_fromgdalraster.qmd

@@ -0,0 +1,47 @@
+---
+# 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_FromGDALRaster
+description: >
+  Decodes a GDAL-readable raster (e.g. a GeoTIFF) from binary content into an
+  in-database raster.
+kernels:
+  - returns: raster
+    args:
+    - name: content
+      type: binary
+      description: >
+        Raster file bytes in any format GDAL can read (GeoTIFF, PNG, …). A NULL
+        input yields a NULL raster.
+---
+
+## Description
+
+`RS_FromGDALRaster` parses raster file bytes with GDAL and returns an in-database
+raster with all band data materialised inline — the inverse of
+[`RS_AsGeoTiff`](rs_asgeotiff.qmd), and the binary counterpart of
+[`RS_FromPath`](rs_frompath.qmd) (which references a file on disk as an out-db
+raster instead). A `NULL` input yields a `NULL` raster.
+
+It is typically applied to a binary column holding encoded rasters — for example
+rasters produced by `RS_AsGeoTiff`, which round-trips back through
+`RS_FromGDALRaster`:
+
+```sql
+SELECT RS_Width(RS_FromGDALRaster(RS_AsGeoTiff(RS_Example())));
+```

rust/sedona-raster-gdal/Cargo.toml

@@ -70,6 +70,11 @@ harness = false
 name = "rs_clip"
 path = "benches/rs_clip.rs"
 
+[[bench]]
+harness = false
+name = "rs_from_gdal_raster"
+path = "benches/rs_from_gdal_raster.rs"
+
 [[bench]]
 harness = false
 name = "rs_frompath"

rust/sedona-raster-gdal/benches/rs_from_gdal_raster.rs

@@ -0,0 +1,55 @@
+// 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.
+
+//! Benchmarks for the RS_FromGDALRaster UDF (GeoTIFF bytes → in-db raster).
+
+use std::hint::black_box;
+use std::sync::Arc;
+
+use arrow_array::{ArrayRef, BinaryArray};
+use arrow_schema::DataType;
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use datafusion_expr::ScalarUDF;
+use sedona_schema::datatypes::SedonaType;
+use sedona_testing::{data::test_raster, testers::ScalarUdfTester};
+
+/// Read a fixture GeoTIFF's bytes and replicate them across `rows` (mirrors the
+/// fixture-driven inputs used by the rs_frompath / rs_metadata benchmarks).
+fn geotiff_bytes_array(name: &str, rows: usize) -> ArrayRef {
+    assert!(rows > 0, "benchmark rows must be positive");
+    let path = test_raster(name).unwrap();
+    let bytes = std::fs::read(path).unwrap();
+    Arc::new(BinaryArray::from(vec![bytes.as_slice(); rows]))
+}
+
+fn bench_rs_from_gdal_raster(c: &mut Criterion) {
+    let udf: ScalarUDF = sedona_raster_gdal::rs_from_gdal_raster_udf().into();
+    let tester = ScalarUdfTester::new(udf, vec![SedonaType::Arrow(DataType::Binary)]);
+
+    let mut group = c.benchmark_group("rs_from_gdal_raster");
+    for rows in [1usize, 32] {
+        let input = geotiff_bytes_array("test4.tiff", rows);
+        group.throughput(Throughput::Elements(rows as u64));
+        group.bench_with_input(BenchmarkId::new("decode", rows), &input, |b, input| {
+            b.iter(|| black_box(tester.invoke_arrays(vec![input.clone()]).unwrap()))
+        });
+    }
+    group.finish();
+}
+
+criterion_group!(benches, bench_rs_from_gdal_raster);
+criterion_main!(benches);

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

@@ -36,6 +36,7 @@ mod raster_loader;
 mod rs_as_geotiff;
 mod rs_as_raster;
 mod rs_clip;
+mod rs_from_gdal_raster;
 mod rs_frompath;
 mod rs_metadata;
 mod rs_polygonize;
@@ -51,6 +52,7 @@ pub use raster_loader::{GdalLoader, GDAL_FORMAT};
 pub use rs_as_geotiff::rs_as_geotiff_udf;
 pub use rs_as_raster::rs_as_raster_udf;
 pub use rs_clip::rs_clip_udf;
+pub use rs_from_gdal_raster::rs_from_gdal_raster_udf;
 pub use rs_frompath::rs_frompath_udf;
 pub use rs_metadata::rs_metadata_udf;
 pub use rs_polygonize::rs_polygonize_udf;

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

@@ -23,6 +23,7 @@ pub fn default_function_set() -> FunctionSet {
     function_set.insert_scalar_udf(crate::rs_as_geotiff::rs_as_geotiff_udf());
     function_set.insert_scalar_udf(crate::rs_as_raster::rs_as_raster_udf());
     function_set.insert_scalar_udf(crate::rs_clip::rs_clip_udf());
+    function_set.insert_scalar_udf(crate::rs_from_gdal_raster::rs_from_gdal_raster_udf());
     function_set.insert_scalar_udf(crate::rs_frompath::rs_frompath_udf());
     function_set.insert_scalar_udf(crate::rs_metadata::rs_metadata_udf());
     function_set.insert_scalar_udf(crate::rs_polygonize::rs_polygonize_udf());