Returns cell_id + pct_covered (0-100) by pure arithmetic on a grid spec: the
polygon is intersected with the 0.05-degree squares the grid defines, planar in
degrees, and pct_covered is round(area / (resx * resy) * 100) with cells
rounding to 0 dropped. No cell table is read and no raster is opened, so the
answer depends on nothing but the polygon and the six numbers in the grid
registry – which is what lets a browser reproduce it.
Arguments
- poly
an
sf,sfcorsfgpolygon / multipolygon (EPSG:4326, or transformable to it)- grid
a
grid_id("usa05","global05") or a spec list fromgrid_spec_for()
Details
Coordinates are read LITERALLY (master-plan D8 addendum, 2026-09-21). This
function guesses nothing about the antimeridian: longitudes must arrive
unwrapped, so a Bering box is 179.9 ... 180.1, and a ring written wrapped
(179.9 then -179.9) means, read literally, the 359.8-degree complement –
which is what it will return. Unwrapping is unwrap_ring(), one explicit rule
with a TypeScript twin and its own normalize-* fixtures, applied at the input
boundary before coverage is ever computed.
What the grid does do is arithmetic its own definition requires: on global05
(7200 x 0.05 = 360, a grid that closes in longitude) an out-of-range column folds
back modulo nc, so 180.1 lands in column 1; on usa05 (a 155.15-degree window
from 141.10 E) each vertex is shifted into that frame, because -90 simply IS 270
there, and a column still outside 1..nc is DROPPED, since there is no cell to
fold onto.
This is the definition, not an approximation of one. cells_in_polygon()
delegates to it for every database connection, so the drawn-polygon cell set, the
Program-Area cell set and the browser's cell set are one set.
Examples
# a rectangle snapped to cell edges: whole cells only
p <- sf::st_sfc(sf::st_polygon(list(cbind(
c(-90, -89.9, -89.9, -90, -90), c(27, 27, 27.1, 27.1, 27)))), crs = 4326)
cells_in_polygon_grid(p, "global05")
#> # A tibble: 4 × 2
#> cell_id pct_covered
#> <int> <dbl>
#> 1 9059401 100
#> 2 9059402 100
#> 3 9066601 100
#> 4 9066602 100