Clip and mask terrain while recording the executed operation

Source: R/clip_terrain_to_aoi.R

Creates a new delivery folder containing terrain.tif, the supplied AOI geometry, an intake manifest and a machine-recorded execution receipt. Source files and saved Study Area contexts are never changed. This is actual processing, not an analyst's retrospective preparation account.

clip_terrain_to_aoi(
  dem,
  aoi,
  output_dir,
  rationale,
  touches = TRUE,
  report = FALSE
)

Arguments

dem

Existing self-contained, single-band GeoTIFF with a projected, two-dimensional CRS. Auxiliary files, compound/3D reference systems, rotated grids and categorical rasters are not qualified by this first slice.

aoi

Nonempty valid polygon sf in the same CRS as dem. Every feature is included; attributes are not retained. The AOI must lie within the DEM's rectangular extent. No automatic repair, buffering or reprojection occurs.

output_dir

New folder in an existing directory. Existing destinations are refused. Incomplete runs remain available for diagnosis, not reuse.

rationale

Nonempty explanation of why this AOI was chosen. This supplied judgment is separate from automatically observed execution evidence.

touches

Logical. TRUE (default) retains cells touched by the polygon; FALSE uses cell centers. Bounds snap outward to existing cell boundaries.

report

Logical; also render a short HTML report, default FALSE. Report failure leaves the completed terrain and receipt available for read-only retry.

Value

Invisible list with terrain, aoi, manifest, execution and report paths.

Details

Uses terra crop/mask without resampling or changing elevation units. Retained values and NoData are checked blockwise after writing Float64 terrain. NoData is an intentional mask, not a missing-data percentage or quality score. Unknown vertical references remain unknown. Known compound/3D CRS are refused rather than silently flattened. Success verifies this local operation only, not original lidar lineage, AOI suitability or change-over-time comparability. A started.json receipt is written before computation; execution.json is written only on success. Caught processing errors write failure.json; abrupt termination may leave only started.json. No script or expression is read from these files.