Skip to contents

Stack many sources into one band-separated raster (buildvrt -separate)

Source: R/ck_stack.R
ck_stack.Rd

ck_stack() fetches a window from several sources through cptkirk's single global concurrency pool (every source opened concurrently, every tile fetched through one io budget) and writes them stacked as separate bands: source i contributes consecutive band(s) of the output, in input order. It is the streaming-remote analogue of gdalbuildvrt -separate followed by a materialising read.

Usage

ck_stack(
  src,
  dst,
  t_srs = NULL,
  te = NULL,
  te_srs = NULL,
  tr = NULL,
  ts = NULL,
  tap = TRUE,
  r = c("near", "bilinear", "cubic", "cubicspline", "lanczos", "average", "rms", "mode",
    "max", "min", "med", "q1", "q3", "sum"),
  bands = NULL,
  band_names = NULL,
  cl_arg = character(0),
  num_threads = "ALL_CPUS",
  warp_memory = "auto",
  cache_max = "auto",
  co = c("COMPRESS=DEFLATE", "TILED=YES", "NUM_THREADS=ALL_CPUS", "BIGTIFF=IF_SAFER"),
  config = NULL,
  skip_nosource = TRUE,
  overview = NULL,
  margin = 8L,
  io_concurrency = 16L,
  max_bytes = NULL,
  sanitise = TRUE
)

Arguments

src

Path/URL to a source GeoTIFF / COG, a cog_source() handle, or a character vector of several sources to mosaic (each tile's overlapping window is fetched and the set is reprojected/mosaicked in one warp; non-overlapping tiles are skipped). Passing a cog_source() reuses its already-open handle, skipping the metadata re-read – worthwhile when warping many AOIs from the same source.

dst

Output filename (a regular path, a /vsimem/ path, or anything GDAL can write). The format is inferred by GDAL or set with -of in cl_arg.

t_srs

Target SRS (e.g. "EPSG:3857"). If NULL, the source CRS is used (no reprojection).

te

Target extent c(xmin, ymin, xmax, ymax), in te_srs if given, otherwise in t_srs. When supplied this is the AOI that drives the fetch.

te_srs

SRS of te (defaults to t_srs).

tr

Target resolution c(xres, yres) in target CRS units. Takes precedence over ts: if both are given, ts is ignored (with a warning).

ts

Target size c(width, height) in pixels. Ignored if tr is also supplied.

tap

If TRUE (default) and tr is given, align output pixel boundaries to the tr grid (gdalwarp -tap), anchored at the CRS origin, so outputs at the same resolution share a grid and stack cleanly. This snaps the output extent outward, so it is no longer exactly te. No effect with ts or on the copy path. An explicit -tap in cl_arg is always honoured. (warp_remote() never adds this; pass -tap yourself.)

r

Resampling method (used only on the warp path; a native-window copy ignores it). Either a single method applied to every source, or a vector of length length(src) giving a per-source method (e.g. "near" for a mask band, "bilinear" for reflectance).

bands

1-based source bands to read (default: all). Subsetting happens during the fetch, so only those bands' bytes are streamed.

band_names

Optional character vector naming the output bands, length equal to the total number of output bands (sum of selected bands across sources). NULL (default) derives a name per band from the source file name (a _b<k> suffix is added for multi-band sources). Names are written as GDAL band descriptions; they carry identity only, not data.

cl_arg

Character vector of extra raw gdalwarp flags, forwarded verbatim to gdalraster::warp() (e.g. c("-et", "0")). These are merged with the flags cptkirk builds from the named arguments above.

num_threads

Value for GDAL's warp NUM_THREADS warp option and the GDAL_NUM_THREADS config (default "ALL_CPUS"), parallelising the resampling computation and GeoTIFF (de)compression. NULL sets neither, deferring to the ambient GDAL_NUM_THREADS (env / session).

warp_memory

Warp working memory in MB (GDAL -wm). "auto" (default) uses ~25% of system RAM, clamped to 256-2048 MB (bigger means fewer, larger chunks); NULL defers to GDAL's own default; a number sets it explicitly.

cache_max

GDAL block cache in MB for this call. "auto" (default) uses ~25% of RAM, clamped to 256-2000 MB; NULL defers to the ambient GDAL_CACHEMAX (env / gdalraster::set_config_option()); a number sets it explicitly. Any value is restored to the previous setting afterwards.

co

GDAL output creation options, defaulting to a cloud-friendly GeoTIFF set: c("COMPRESS=DEFLATE", "TILED=YES", "NUM_THREADS=ALL_CPUS", "BIGTIFF=IF_SAFER") — losslessly compressed, tiled (so the output can be re-read by cptkirk and any other COG reader), compressed in parallel, and promoted to BigTIFF when it might exceed 4 GB. Pass your own to override (e.g. add "PREDICTOR=2" for integer data, or "COMPRESS=ZSTD" on a GDAL built with it), or NULL for no creation options. These target the GTiff/COG drivers; set co yourself for other output formats.

config

Named character vector / list of extra GDAL config options to set for the duration of the call (restored on exit).

skip_nosource

If TRUE (default), pass SKIP_NOSOURCE=YES + INIT_DEST so the warper skips output chunks with no source coverage (e.g. nodata margins from reprojection). No effect when output is fully covered. Ignored on the copy fast-path.

overview

Force a 1-based IFD/overview level instead of auto-selecting from the output resolution. 1 = full resolution.

margin

Source-pixel margin added around the computed window to cover the resampling kernel and reprojection slop (default 8).

io_concurrency

Number of concurrent tile reads – the width of the single global fetch pool shared across all source tiles. Default 16, which suits object stores that throttle around that many simultaneous range requests (e.g. S3 / source.coop). Raise (24-32) on a fast, stable link; lower if a store rate-limits.

max_bytes

Safety ceiling (bytes) on the staged in-memory window (width * height * bands * <native dtype bytes>). NULL (default) uses ~1/3 of system RAM. It only guards against the foot-gun of warping a whole large multi-band raster at native resolution; narrow the request, coarsen tr/ts, or raise this to allow it.

sanitise

If TRUE (default), validate the warp arguments against a tiny metadata-derived stand-in before fetching, so a bad CRS, resampling method, creation option or unknown flag fails in milliseconds instead of after a remote read. Set FALSE to skip the check.

Value

dst, invisibly. dst may be a file path or any /vsi* path GDAL can write (e.g. /vsimem/stack.tif).

Details

This differs from passing several sources to ck_warp(), which mosaics them (overlapping pixels blend, last source wins). Use ck_stack() to bring, e.g., the per-band single-band assets of one acquisition into a single multi-band raster.

Two internal paths, chosen automatically:

  • Stack (the usual case – sources already share a grid and no reprojection/resolution change is requested): the fetched native windows are stacked directly with -separate and written out. Sources are assumed aligned; supply t_srs/te/tr to force a common grid otherwise.

  • Warp-then-stack: when a reprojection or resolution change is requested, each source is warped to the common target grid first, then stacked, so the bands register exactly.

See also

ck_stack_read() for the array-returning sugar, ck_warp() to mosaic instead of stack.