feat: add N-D raster dimension query and manipulation functions

docs/reference/sql/rs_bandtodim.qmd

@@ -0,0 +1,57 @@
+---
+# 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_BandToDim
+description: Collapses all bands into a single band with a new dimension.
+kernels:
+  - returns: raster
+    args:
+    - raster
+    - name: dim_name
+      type: utf8
+      description: Name for the new dimension (e.g., 'time', 'band').
+---
+
+## Description
+
+Collapses all bands in a raster into a single band by introducing a new
+dimension. The new dimension is prepended to the existing dimensions, with
+size equal to the number of bands. Band data is concatenated in band order.
+
+All bands must have identical dimension names, shapes, and data types. If
+they differ, an error is returned.
+
+This is the inverse of [RS_DimToBand](rs_dimtoband.qmd). A round-trip
+`RS_BandToDim(RS_DimToBand(raster, 'dim'), 'dim')` recovers the original
+data layout.
+
+This is useful for converting GeoTIFF-style multi-band rasters into a single
+N-dimensional chunk for export to formats like Zarr.
+
+## Examples
+
+```sql
+-- Collapse 3 RGB bands [y, x] into 1 band [band=3, y, x]
+SELECT RS_BandToDim(raster, 'band');
+
+-- Collapse time-step bands back into a time dimension
+SELECT RS_BandToDim(raster, 'time');
+
+-- Round-trip: split then recombine
+SELECT RS_BandToDim(RS_DimToBand(raster, 'time'), 'time');
+```

docs/reference/sql/rs_dimnames.qmd

@@ -0,0 +1,56 @@
+---
+# 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_DimNames
+description: Returns the ordered list of dimension names for a raster band.
+kernels:
+  - returns: list<utf8>
+    args: [raster]
+  - returns: list<utf8>
+    args:
+    - raster
+    - name: band
+      type: int
+      description: Band index (1-based). Defaults to 1 if not specified.
+---
+
+## Description
+
+Returns the ordered list of dimension names for a raster band. Standard 2D
+rasters have dimensions `["y", "x"]`. N-dimensional rasters may include
+additional dimensions such as `time`, `pressure`, `wavelength`, etc.
+
+The dimension names correspond to the entries in
+[RS_Shape](rs_shape.qmd) — the i-th name matches the i-th size.
+
+When the band index is omitted, returns the dimension names of band 1. If
+bands have different dimension names, an error is returned prompting the user
+to specify a band index.
+
+## Examples
+
+```sql
+-- 2D raster: returns ["y", "x"]
+SELECT RS_DimNames(raster);
+
+-- 3D raster with time: returns ["time", "y", "x"]
+SELECT RS_DimNames(raster);
+
+-- Specific band
+SELECT RS_DimNames(raster, 2);
+```

docs/reference/sql/rs_dimsize.qmd

@@ -0,0 +1,67 @@
+---
+# 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_DimSize
+description: Returns the size of a named dimension in a raster band.
+kernels:
+  - returns: int64
+    args:
+    - raster
+    - name: dim_name
+      type: utf8
+      description: Name of the dimension to query (e.g., 'x', 'y', 'time').
+  - returns: int64
+    args:
+    - raster
+    - name: dim_name
+      type: utf8
+      description: Name of the dimension to query.
+    - name: band
+      type: int
+      description: Band index (1-based). Defaults to 1 if not specified.
+---
+
+## Description
+
+Returns the size of a named dimension in a raster band. For example,
+`RS_DimSize(raster, 'x')` returns the width and `RS_DimSize(raster, 'time')`
+returns the number of time steps. Returns null if the dimension does not exist
+in the band.
+
+This is equivalent to looking up a specific entry in
+[RS_Shape](rs_shape.qmd) by name rather than by position.
+
+When the band index is omitted, returns the dimension size from band 1. If
+bands disagree on the size (or some bands are missing the dimension), an error
+is returned prompting the user to specify a band index.
+
+## Examples
+
+```sql
+-- Get the width (x dimension size)
+SELECT RS_DimSize(raster, 'x');
+
+-- Get the number of time steps
+SELECT RS_DimSize(raster, 'time');
+
+-- Returns null if the dimension doesn't exist
+SELECT RS_DimSize(raster, 'wavelength');
+
+-- Query a specific band
+SELECT RS_DimSize(raster, 'time', 2);
+```

docs/reference/sql/rs_dimtoband.qmd

@@ -0,0 +1,61 @@
+---
+# 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_DimToBand
+description: Promotes a within-band dimension into separate bands.
+kernels:
+  - returns: raster
+    args:
+    - raster
+    - name: dim_name
+      type: utf8
+      description: Name of the dimension to promote (e.g., 'wavelength', 'time').
+---
+
+## Description
+
+Promotes a named non-spatial dimension into separate bands. Each index along
+the dimension becomes its own band with that dimension removed. This bridges
+the gap between the dimension model (where all indices live in one band) and
+the band model (where each index is a separate band accessible by number).
+
+For example, a raster with 1 band of shape `[wavelength=200, y=256, x=256]`
+becomes a raster with 200 bands, each of shape `[y=256, x=256]`. Standard
+band math functions like [RS_NormalizedDifference](rs_normalizeddifference.qmd)
+can then operate on individual wavelength bands by index.
+
+Bands that do not contain the named dimension are passed through unchanged.
+
+The spatial dimensions (`x_dim` and `y_dim`) cannot be promoted.
+
+The inverse operation is [RS_BandToDim](rs_bandtodim.qmd).
+
+## Examples
+
+```sql
+-- Promote wavelength into separate bands for band math
+SELECT RS_DimToBand(raster, 'wavelength');
+
+-- Compute NDVI from specific wavelength bands
+SELECT RS_NormalizedDifference(
+  RS_DimToBand(raster, 'wavelength'), 77, 54
+);
+
+-- Promote time steps into bands
+SELECT RS_DimToBand(raster, 'time');
+```

docs/reference/sql/rs_numdimensions.qmd

@@ -0,0 +1,51 @@
+---
+# 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_NumDimensions
+description: Returns the number of dimensions in a raster band.
+kernels:
+  - returns: int32
+    args: [raster]
+  - returns: int32
+    args:
+    - raster
+    - name: band
+      type: int
+      description: Band index (1-based). Defaults to 1 if not specified.
+---
+
+## Description
+
+Returns the number of dimensions in a raster band. A standard 2D raster has 2
+dimensions (`y` and `x`). N-dimensional rasters (e.g., from Zarr or NetCDF
+sources) may have additional dimensions such as `time`, `pressure`, or
+`wavelength`.
+
+When the band index is omitted, returns the dimensionality of band 1. If
+bands have different numbers of dimensions, an error is returned prompting
+the user to specify a band index.
+
+## Examples
+
+```sql
+-- 2D raster: returns 2
+SELECT RS_NumDimensions(raster);
+
+-- Specific band
+SELECT RS_NumDimensions(raster, 2);
+```

docs/reference/sql/rs_shape.qmd

@@ -0,0 +1,57 @@
+---
+# 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_Shape
+description: Returns the shape (size of each dimension) of a raster band.
+kernels:
+  - returns: list<int64>
+    args: [raster]
+  - returns: list<int64>
+    args:
+    - raster
+    - name: band
+      type: int
+      description: Band index (1-based). Defaults to 1 if not specified.
+---
+
+## Description
+
+Returns the shape of a raster band as a list of dimension sizes. The entries
+correspond to the dimension names returned by
+[RS_DimNames](rs_dimnames.qmd).
+
+For a standard 2D raster this returns `[height, width]`. For an N-dimensional
+raster with a time dimension it might return `[12, 256, 256]` meaning 12 time
+steps at 256x256 spatial resolution.
+
+When the band index is omitted, returns the shape of band 1. If bands have
+different shapes, an error is returned prompting the user to specify a band
+index.
+
+## Examples
+
+```sql
+-- 2D raster: returns [256, 256]
+SELECT RS_Shape(raster);
+
+-- 3D raster with time: returns [12, 256, 256]
+SELECT RS_Shape(raster);
+
+-- Specific band
+SELECT RS_Shape(raster, 2);
+```