Relabel segments to a global consecutive ID scheme (streaming-safe)

Reassigns all non-`NA` segment IDs in a segmentation raster to a consecutive integer sequence `1..K` and writes the result to disk using streaming I/O. This is useful after merging/reconciliation steps to produce compact, stable IDs for downstream feature extraction and polygonization.

Usage

relabel_segments_global(seg, out_file, block_nrows = 1024L)

Arguments

seg

A `SpatRaster` containing integer segment labels.

out_file

Character. Output file path (GeoTIFF recommended).

block_nrows

Integer. Number of rows per streaming block when reading and writing.

Value

A file-backed `SpatRaster` pointing to `out_file`.

Details

The function first ensures `seg` is file-backed (written to a temporary GeoTIFF) to support robust streaming reads. It then computes the set of unique segment IDs using `terra::freq(..., bylayer = FALSE)` and maps them in sorted order to `1..K`. `NA` values are ignored and preserved.

The relabeling is applied block-wise using `readValues()` / `writeValues()`, avoiding full in-memory materialization. Output is written as `INT4S` with the package's default GDAL creation options.

**Determinism.** Because unique IDs are sorted before mapping, the resulting labels are deterministic for a given raster (subject to identical numeric values in `seg`).

See also

`apply_merge_map()`, freq, readValues, writeValues