osbng.indexing.bbox_to_bng#

osbng.indexing.bbox_to_bng(xmin: int | float, ymin: int | float, xmax: int | float, ymax: int | float, resolution: int | str) → list[BNGReference][source]#

Returns a BNGReference list given a bounding box and resolution.

Validates and normalises the bounding box (BBOX) coordinates to the BNG index system extent. If BBOX coordinates fall outside of the BNG index system extent, then a warning is raised and the coordinates are snapped to the bounds of the BNG index system.

Notes

The relationship between the BBOX and the returned grid squares depends on the alignment of the BBOX with the BNG index system:

  • BNG Aligned: If the BBOX edges align with the BNG index system (xmin, ymin, xmax, ymax are multiples of the specified resolution), only the grid squares entirely contained within the BBOX are returned. Grid squares that intersect but are not fully contained within the BBOX are excluded.

  • Non-BNG Aligned: If the BBOX edges are not aligned with the BNG index system, grid squares that are partially overlapped by the BBOX are also included. In this case, the function ensures all relevant grid squares that the BBOX touches are returned, including those at the edges.

Parameters:

  • xmin (int | float) – The minimum easting coordinate of the BBOX.

  • ymin (int | float) – The minimum northing coordinate of the BBOX.

  • xmax (int | float) – The maximum easting coordinate of the BBOX.

  • ymax (int | float) – The maximum northing coordinate of the BBOX.

  • 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.

Examples

>>> bbox_to_bng(400000, 100000, 500000, 200000, "50km")
[BNGReference(bng_ref_formatted=SU SW, resolution_label=50km),
 BNGReference(bng_ref_formatted=SU SE, resolution_label=50km),
 BNGReference(bng_ref_formatted=SU NW, resolution_label=50km),
 BNGReference(bng_ref_formatted=SU NE, resolution_label=50km)]
>>> bbox_to_bng(285137.06, 78633.75, 299851.01, 86427.96, 5000)
[BNGReference(bng_ref_formatted=SX 8 7 NE, resolution_label=5km),
 BNGReference(bng_ref_formatted=SX 9 7 NW, resolution_label=5km),
 BNGReference(bng_ref_formatted=SX 9 7 NE, resolution_label=5km),
 BNGReference(bng_ref_formatted=SX 8 8 SE, resolution_label=5km),
 BNGReference(bng_ref_formatted=SX 9 8 SW, resolution_label=5km),
 BNGReference(bng_ref_formatted=SX 9 8 SE, resolution_label=5km),
 BNGReference(bng_ref_formatted=SX 8 8 NE, resolution_label=5km),
 BNGReference(bng_ref_formatted=SX 9 8 NW, resolution_label=5km),
 BNGReference(bng_ref_formatted=SX 9 8 NE, resolution_label=5km)]

See also

The bbox_to_bng_iterfeatures() function which returns an iterator of BNGReference Features given a bounding box and resolution.

On this page

This Page