RS_DimSize¶

Returns the size of a named dimension in a raster band.

Usage¶

int64 RS_DimSize(rast: raster, dim_name: utf8)
int64 RS_DimSize(rast: raster, dim_name: utf8, band: int)

Arguments¶

rast (raster): Input raster
dim_name (utf8): Name of the dimension to query (e.g., ‘x’, ‘y’, ‘time’).
band (int): Band index (1-based). A null or out-of-range index returns null.

[!WARNING]

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

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 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¶

-- RS_Example() produces a 2-D raster, so 'x' and 'y' are the only dims.
SELECT RS_DimSize(RS_Example(), 'x');

┌────────────────────────────────────┐
│ rs_dimsize(rs_example(),Utf8("x")) │
│                int64               │
╞════════════════════════════════════╡
│                                 64 │
└────────────────────────────────────┘

SELECT RS_DimSize(RS_Example(), 'y');

┌────────────────────────────────────┐
│ rs_dimsize(rs_example(),Utf8("y")) │
│                int64               │
╞════════════════════════════════════╡
│                                 32 │
└────────────────────────────────────┘