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

docs/reference/sql/_render_meta.py

@@ -187,6 +187,8 @@ def to_str(v):
             return " "
         elif v["t"] == "Para":
             return "".join(to_str(item) for item in v["c"])
+        elif v["t"] == "RawInline":
+            return v["c"][1]
         if v["t"] == "Quoted":
             quote_type = v["c"][0]["t"]
             if quote_type == "SingleQuote":

docs/reference/sql/rs_bandtodim.qmd

@@ -0,0 +1,64 @@
+---
+# 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, data types, and
+nodata values. If any of these differ, an error is returned — collapsing
+bands with different nodata sentinels would silently lose information
+about which sentinel applies where.
+
+The new dimension name must not already exist on the input bands. For
+example, `RS_BandToDim(raster_with_y_x, 'y')` is rejected because the
+output would carry duplicate `y` dimensions and the round-trip through
+[RS_DimToBand](rs_dimtoband.qmd) cannot recover the original layout.
+
+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
+
+```
+-- 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,49 @@
+---
+# 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, all bands must agree on their dimension
+names; if they disagree, an error is returned prompting the user to specify
+a band index.
+
+## Examples
+
+```sql
+SELECT RS_DimNames(RS_Example());
+```

docs/reference/sql/rs_dimsize.qmd

@@ -0,0 +1,73 @@
+---
+# 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. For example,
+`RS_DimSize(raster, 'x')` returns the width and `RS_DimSize(raster, 'time')`
+returns the number of time steps.
+
+This is equivalent to looking up a specific entry in
+[RS_Shape](rs_shape.qmd) by name rather than by position.
+
+### Heterogeneous rasters
+
+Bands within a raster can have different dimensionality. When the band index
+is omitted, `RS_DimSize` considers only the bands that carry the named
+dimension ("pass-through"):
+
+- If at least one band carries the dimension and they all agree on its
+  size, that size is returned.
+- If the bands that carry the dimension disagree on its size, an error is
+  returned prompting the user to specify a band index.
+- If **no** band carries the dimension, an error is returned. This usually
+  signals a typo'd dimension name.
+
+When the band index is supplied explicitly, returns the size of the
+dimension in that band, or `NULL` if the band does not carry it.
+
+## Examples
+
+```sql
+-- RS_Example() produces a 2-D raster, so 'x' and 'y' are the only dims.
+SELECT RS_DimSize(RS_Example(), 'x');
+```
+
+```sql
+SELECT RS_DimSize(RS_Example(), 'y');
+```

docs/reference/sql/rs_dimtoband.qmd

@@ -0,0 +1,63 @@
+---
+# 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 can then operate on individual wavelength bands by
+index.
+
+Bands that do not contain the named dimension are passed through unchanged.
+If **no** band carries the named dimension, the function errors — that
+condition usually signals a typo'd dimension name.
+
+The spatial dimensions (`x_dim` and `y_dim`) cannot be promoted.
+
+The inverse operation is [RS_BandToDim](rs_bandtodim.qmd).
+
+## Examples
+
+```
+-- 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,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_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, all bands must agree on the number of
+dimensions; if they disagree, an error is returned prompting the user to
+specify a band index.
+
+## Examples
+
+```sql
+SELECT RS_NumDimensions(RS_Example());
+```

docs/reference/sql/rs_shape.qmd

@@ -0,0 +1,50 @@
+---
+# 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, all bands must agree on their shape; if
+they disagree, an error is returned prompting the user to specify a band
+index.
+
+## Examples
+
+```sql
+SELECT RS_Shape(RS_Example());
+```