Apply a segment merge map to a segmentation raster (streaming-safe)

Applies a mapping from original segment IDs to merged (representative) IDs and writes the updated segmentation to disk using block-wise streaming. This is intended for large, file-backed rasters and avoids reading the full segmentation into memory.

Usage

apply_merge_map(seg, map, out_file, block_nrows = 1024L)

Arguments

seg

A `SpatRaster` containing integer segment labels.

map

Named integer vector defining the relabeling/merge map. Names are original segment IDs (as character strings) and values are the target IDs (typically representatives produced by `merge_by_adjacency()`).

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 streams through `seg` in row blocks, replaces values that match `names(map)`, and writes the result to `out_file`. Values not present in the map are left unchanged. `NA` values are preserved.

**terra I/O note.** In terra, `writeStart()` returns a list; this function intentionally ignores that return value and continues writing to the `SpatRaster` object used in `writeStart()`. This ensures compatibility with terra versions where writing to the returned list is incorrect.

The output is written with integer datatype (`INT4S`) and default GDAL creation options used by the package.

See also

`merge_by_adjacency()`, `relabel_segments_global()`, readValues, writeValues