RS_BandToDim

Collapses all bands into a single band with a new dimension.

Usage

raster RS_BandToDim(rast: raster, dim_name: utf8)

Arguments

• rast (raster): Input raster
• dim_name (utf8): Name for the new dimension (e.g., ‘time’, ‘band’).

[!WARNING]

Experimental. This function is experimental; its behavior may change without notice.

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 cannot recover the original layout.

This is the inverse of RS_DimToBand. 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 RS_Example()'s bands into a single band carrying a new 'band'
-- dimension, e.g. [y, x] bands become one [band, y, x] band.
SELECT RS_BandToDim(RS_Example(), 'band');

┌─────────────────────────────────────────────────────────────────────────────┐
│                   rs_bandtodim(rs_example(),Utf8("band"))                   │
│                                    raster                                   │
╞═════════════════════════════════════════════════════════════════════════════╡
│ [64x32/1] @ [43.08 79.07 203.07999999999998 207.07] skew=(1, 1) / OGC:CRS84 │
└─────────────────────────────────────────────────────────────────────────────┘

-- The inverse RS_DimToBand recovers the original bands, so the round-trip
-- returns to the starting layout.
SELECT RS_DimToBand(RS_BandToDim(RS_Example(), 'band'), 'band');

┌─────────────────────────────────────────────────────────────────────────────┐
│      rs_dimtoband(rs_bandtodim(rs_example(),Utf8("band")),Utf8("band"))     │
│                                    raster                                   │
╞═════════════════════════════════════════════════════════════════════════════╡
│ [64x32/3] @ [43.08 79.07 203.07999999999998 207.07] skew=(1, 1) / OGC:CRS84 │
└─────────────────────────────────────────────────────────────────────────────┘