osbng.indexing.geom_to_bng#

osbng.indexing.geom_to_bng(geom: Geometry, resolution: int | str) → list[BNGReference][source]#

Returns a BNGReference list given a Shapely Geometry and resolution.

The BNGReference list returned represents the grid squares intersected by the input geometry. BNGReference objects are deduplicated in cases where two or more parts of a multi-part geometry intersect the same grid square.

This function is useful for spatial indexing and aggregation of geometries against the BNG index system.

Notes

A note on the type of the input geometry. This also applies to the parts within a multi-part geometry:

  • For Point geometries, the function returns a list comprising a single BNGReference. A BNGExtentError exception is raised if the coordinates fall outside of the BNG index system extent.

  • For LineString and Polygon geometry types, the function returns a BNGReference list representing the grid squares intersected by the geometry. When a geometry extends beyond the BNG index system extent, the function will show a feature bounding box warning but will still return a BNGReference for each of the intersected grid squares within the BNG index system extent.

Parameters:

  • geom (Geometry) – Shapely Geometry.

  • resolution (int | str) – The BNG resolution expressed either as a metre-based integer or as a string label.

Returns:

BNGReference list.

Return type:

list[BNGReference]

Raises:

  • BNGResolutionError – If an invalid resolution is provided.

  • ValueError – If the geometry type is not supported.

  • BNGExtentError – If the coordinates of a Point geometry are outside of the BNG index system extent.

Examples

>>> geom_to_bng(Point(430000, 110000), "100km")
[BNGReference(bng_ref_formatted=SU, resolution_label=100km)]
>>> geom_to_bng(
...     LineString([[430000, 110000], [430010, 110000], [430010, 110010]]), "5m"
... )
[BNGReference(bng_ref_formatted=SU 3000 1000 SE, resolution_label=5m),
 BNGReference(bng_ref_formatted=SU 3000 1000 SW, resolution_label=5m),
 BNGReference(bng_ref_formatted=SU 3000 1000 NE, resolution_label=5m)]

See also

For geometry decomposition by the BNG index system, use geom_to_bng_intersection() or gdf_to_bng_intersection_explode() instead.

On this page

This Page