Skip to content

RS_ReplaceBandNoDataValue

Moves a band’s nodata value to a new value, carrying the nodata pixels with it: every pixel that reads as nodata is rewritten to the new value, which then becomes the band’s nodata, so the same pixels read as nodata before and after.

Usage

raster RS_ReplaceBandNoDataValue(rast: raster, band: int, nodata: float64)

Arguments

  • rast (raster): Input raster
  • band (int): Band index (1-based).
  • nodata (float64): The new nodata value. It must fit the band’s data type exactly.

Description

RS_SetBandNoDataValue changes only the declared nodata value, so pixels that held the old value become ordinary data. RS_ReplaceBandNoDataValue also rewrites those pixels, so they keep reading as nodata.

A pixel reads as nodata by the same rules sampling uses: exactly for integer bands, and numerically for float bands, so -0.0 matches a 0.0 nodata and any NaN matches a NaN nodata. Other bands are unchanged.

The band must already have a nodata value; otherwise there is nothing to replace and the call is an error. A null raster, band or nodata value gives a null raster. Only 2-D rasters are supported.

Examples

Band 1 of RS_Example() has a nodata value of 127, held by one of its 2048 pixels. Replacing the nodata value keeps that pixel as nodata, so 2047 pixels stay valid; merely setting a new nodata value with RS_SetBandNoDataValue turns it into ordinary data, leaving 2048 valid:

SELECT
  RS_SummaryStats(RS_ReplaceBandNoDataValue(RS_Example(), 1, 200), 'count', 1),
  RS_SummaryStats(RS_SetBandNoDataValue(RS_Example(), 1, 200), 'count', 1);

┌───────────────────────────────────────┬──────────────────────────────────────┐
│ rs_summarystats(rs_replacebandnodatav ┆ rs_summarystats(rs_setbandnodatavalu │
│ alue(rs_example(),Int64(1),Int64(200… ┆ e(rs_example(),Int64(1),Int64(200))… │
╞═══════════════════════════════════════╪══════════════════════════════════════╡
│                                2047.0 ┆                               2048.0 │
└───────────────────────────────────────┴──────────────────────────────────────┘

SELECT RS_BandNoDataValue(RS_ReplaceBandNoDataValue(RS_Example(), 1, 200), 1);

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_bandnodatavalue(rs_replacebandnodatavalue(rs_example(),Int64(1),Int64(200 │
│                                 )),Int64(1))…                                │
╞══════════════════════════════════════════════════════════════════════════════╡
│                                                                        200.0 │
└──────────────────────────────────────────────────────────────────────────────┘