Skip to main content

Coverings

A covering is a set of cells at one resolution, standing for an area of the globe, possibly in disjoint parts, such as the output of polygonToCells or sphericalCap. It is stored compacted, and in general should be used with methods expecting compacted data. If the actual cells are required (for example for a JOIN operation) a covering should be uncompacted first (warning: could use a huge amount of memory).

The functions on this page combine, query and measure coverings:

Example processing flow​

// Construct coverings
let france = polygon_to_cells(&france_polygon, 18, None)?; // 944ms -> 1.09 billion cells
let germany = polygon_to_cells(&germany_polygon, 18, None)?; // 708ms -> 718 million cells
let near_bern = spherical_cap(bern, 400_000.0)?; // 302ms -> 1.02 billion cells
let near_luxembourg = spherical_cap(luxembourg, 150_000.0)?; // 113ms -> 143 million cells

// Set operations
let france_and_germany = union(&france, &germany)?; // 7.0ms -> 1.81 billion cells
let also_close_to_bern = intersect(&france_and_germany, &near_bern)?; // 5.4ms -> 646 million cells
let but_far_from_luxembourg = difference(&also_close_to_bern, &near_luxembourg)?; // 3.2ms -> 545 million cells

// Area of covering, to the nearest resolution 18 cell (~500m²)
println!("{} km²", area(&but_far_from_luxembourg)? / 1e6); // 1.4ms -> 269516 km²

// Point in polygon
println!("{}", contains(&but_far_from_luxembourg, munich)?); // 50ns -> true

Timings measured with the Rust implementation on an Apple M1 Pro.

Set operations​

union​

Returns the cells in either covering. Both must be at the same resolution, or it throws.

a5_union(a UBIGINT[], b UBIGINT[]) -> UBIGINT[]

Parameters​

  • a (bigint[] | BigUint64Array) First covering
  • b (bigint[] | BigUint64Array) Second covering

Return value​

  • (BigUint64Array) Combined covering of both input coverings

Example​

-- A multi-polygon: the union of its parts
SELECT a5_union(a5_geometry_to_cells(mainland, 10), a5_geometry_to_cells(island, 10)) AS coverage
FROM parts;

intersect​

Returns the cells in both coverings. Both must be at the same resolution, or it throws.

a5_intersect(a UBIGINT[], b UBIGINT[]) -> UBIGINT[]

Parameters​

  • a (bigint[] | BigUint64Array) First covering
  • b (bigint[] | BigUint64Array) Second covering

Return value​

  • (BigUint64Array) Covering of cells present in both input coverings

difference​

Returns the cells in the first covering but not in the second. Both must be at the same resolution, or it throws.

a5_difference(a UBIGINT[], b UBIGINT[]) -> UBIGINT[]

Parameters​

  • a (bigint[] | BigUint64Array) Covering to subtract from
  • b (bigint[] | BigUint64Array) Covering to subtract

Return value​

  • (BigUint64Array) Covering of cells present in the first covering but not the second

Example​

-- A country without the area within 50 km of its capital
SELECT a5_difference(
  a5_geometry_to_cells(geom, 10),
  a5_spherical_cap(a5_lonlat_to_cell(capital_lon, capital_lat, 10), 50000)
) AS outside
FROM countries;

Predicates​

contains​

Checks whether a cell is in a covering. The cell must be at the covering's resolution, or it throws: A5 cells don't nest geometrically across resolutions, so a finer cell isn't guaranteed to lie inside its ancestor. To test a point, index it at the covering's resolution with lonLatToCell(point, resolution).

a5_contains(cells UBIGINT[], cell UBIGINT) -> BOOLEAN

Parameters​

  • cells (bigint[] | BigUint64Array) Sorted covering
  • cell (bigint) Cell to test, at the covering's resolution

Return value​

  • (boolean) Whether the cell is in the covering

Example​

SELECT a5_contains(a5_geometry_to_cells(geom, 12), a5_lonlat_to_cell(2.35, 48.85, 12)) AS inside
FROM countries;

overlaps​

Checks whether two coverings share any cell. Both must be at the same resolution, or it throws.

a5_overlaps(a UBIGINT[], b UBIGINT[]) -> BOOLEAN

Parameters​

  • a (bigint[] | BigUint64Array) First covering
  • b (bigint[] | BigUint64Array) Second covering

Return value​

  • (boolean) Whether some cell is in both coverings

Measures​

count​

Returns the number of cells in a covering, equivalent to the length of uncompact(cells) without having to materialize the uncompacted cells. Note that this generally differs from the length of the compacted array.

a5_count(cells UBIGINT[]) -> UBIGINT

Parameters​

  • cells (bigint[] | BigUint64Array) A covering

Return value​

  • (bigint) Number of cells at the covering's resolution. A bigint, as it can exceed Number.MAX_SAFE_INTEGER at high resolutions

Example​

-- Stored compactly, as 78929 cells at mixed resolutions
SELECT a5_count(a5_geometry_to_cells(geom, 16))  -- 67995098 cells at resolution 16
FROM countries
WHERE name = 'France';

area​

Returns the area of a covering in square meters. As A5 cells are equal-area, this is exact: the number of cells times the cell area at the covering's resolution.

a5_area(cells UBIGINT[]) -> DOUBLE

Parameters​

  • cells (bigint[] | BigUint64Array) A covering

Return value​

  • (number) Area in square meters