Build polygon-to-cube geometric weights

cube_polygon_weights() computes feature-specific geodesic intersections against the rectilinear cells of an ocean_cube(). The result is a self-contained table of merge keys and geometric weights intended for downstream consumers such as spatind. It does not read cube values, aggregate variables, or calculate spatial indicators.

Usage

cube_polygon_weights(
  x,
  polygons,
  id_col = NULL,
  crs = NULL,
  dimension = c("2d", "3d"),
  depth_bounds = NULL,
  include_zero = FALSE
)

Arguments

x

An ocean_cube() with one-dimensional longitude and latitude axes.

polygons

An sf, sfc, or polygonal sfg object in a geographic CRS.

id_col

Optional column name containing feature identifiers. It is available only when polygons is an sf object. Values and duplicates are preserved.

crs

CRS to assign only when polygons has no CRS. Existing geometry is never reinterpreted.

dimension

Generate horizontal ("2d") or volumetric ("3d") weights.

depth_bounds

Explicit vertical interfaces or paired bounds for 3-D weights. If NULL, unambiguous cube metadata is used.

include_zero

Include all feature-cell combinations, including zero intersections.

Value

A data frame with stable feature/cell keys, bounds, areas, fractions, coverage diagnostics and, when dimension = "3d", depth and volume fields.

Details

Polygon features are processed independently. Holes and multipart geometry are preserved, and overlapping features are not unioned or normalised against one another. Unlike cube_mask(), this function measures cell intersection instead of classifying cell centres and does not modify cube values. It supplies geometric inputs for downstream analysis; indicator calculation and inference remain the responsibility of packages such as spatind.