Indexing#

Index coordinates and Shapely geometries against the BNG index system.

Supports bi-directional conversion between easting/northing coordinate pairs and BNGReference objects at supported resolutions as defined in the Resolution module. Additionally, it enables the indexing of geometries, represented using Shapely Geometry objects, into grid squares at a specified resolution. Shapely geometries can also be decomposed into simplified representations bounded by their presence in each grid square at a specified resolution.

Indexing functionality facilitates grid-based spatial analysis, enabling applications such as statistical aggregation, data visualisation, and data interoperability.

Summary of functionality:

Encoding easting and northing coordinates into BNGReference objects at a specified resolution.
Decoding BNGReference objects back into easting/northing coordinates, bounding boxes and grid squares as Shapely geometries.
Indexing bounding boxes into grid squares at a specified resolution.
Indexing Shapely geometries into grid squares at a specified resolution.
Decomposing Shapely geometries into simplified representations bounded by their presence in each grid square at a specified resolution.

Supported resolutions:

The module supports the ‘standard’ and ‘intermediate’ quadtree resolutions: 100km, 50km, 10km, 5km, 1km, 500m, 100m, 50m, 10m, 5m and 1m.
These resolutions passed to indexing functions are validated and normalised using the resolution mapping defined in the Resolution module.

See also

The Indexing GeoPandas module which provides a gdf_to_bng_intersection_explode() function supporting the indexing of geometries in a GeoPandas GeoDataFrame against the BNG index system.

osbng.indexing.PREFIXES: ndarray[tuple[Any, ...], dtype[str_]] = array([['SV', 'SW', 'SX', 'SY', 'SZ', 'TV', 'TW'], ['SQ', 'SR', 'SS', 'ST', 'SU', 'TQ', 'TR'], ['SL', 'SM', 'SN', 'SO', 'SP', 'TL', 'TM'], ['SF', 'SG', 'SH', 'SJ', 'SK', 'TF', 'TG'], ['SA', 'SB', 'SC', 'SD', 'SE', 'TA', 'TB'], ['NV', 'NW', 'NX', 'NY', 'NZ', 'OV', 'OW'], ['NQ', 'NR', 'NS', 'NT', 'NU', 'OQ', 'OR'], ['NL', 'NM', 'NN', 'NO', 'NP', 'OL', 'OM'], ['NF', 'NG', 'NH', 'NJ', 'NK', 'OF', 'OG'], ['NA', 'NB', 'NC', 'ND', 'NE', 'OA', 'OB'], ['HV', 'HW', 'HX', 'HY', 'HZ', 'JV', 'JW'], ['HQ', 'HR', 'HS', 'HT', 'HU', 'JQ', 'JR'], ['HL', 'HM', 'HN', 'HO', 'HP', 'JL', 'JM']], dtype='<U2')#

100km BNG square letter prefixes.

Each element is a two-letter string itentifying a 100km grid square. The positional indices correspond to the 10km grid square location in the BNG index system and are used to determine the specific grid square for a given set of easting and northing coordinates.

Type:: npt.NDArray[np.str_] of shape (13, 7)

osbng.indexing.SUFFIXES: ndarray[tuple[Any, ...], dtype[str_]] = array([['SW', 'NW'], ['SE', 'NE']], dtype='<U2')#

BNG ordinal direction suffixes.

Used to identify intermediate quadtree resolutions.

Type:: npt.NDArray[np.str_] of shape (2, 2)

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.

osbng.indexing.bng_to_bbox(bng_ref: BNGReference) → tuple[int, int, int, int][source]#

Returns grid square bounding box coordinates given a BNGReference.

Parameters:: bng_ref (BNGReference) – The BNGReference.
Returns:: The grid square bounding box coordinates as a tuple.
Return type:: tuple[int, int, int, int]
Raises:: TypeError – If first argument is not a BNGReference.

Example

>>> bng_to_bbox(BNGReference("SU"))
(400000, 100000, 500000, 200000)
>>> bng_to_bbox(BNGReference("SU 3 1"))
(430000, 110000, 440000, 120000)
>>> bng_to_bbox(BNGReference("SU 3 1 NE"))
(435000, 115000, 440000, 120000)
>>> bng_to_bbox(BNGReference("SU 37289 15541"))
(437289, 115541, 437290, 115542)

See also

The equivalent osbng.bng_reference.BNGReference.bng_to_bbox() instance method.
The bng_to_grid_geom() function and bng_to_grid_geom() instance method which convert a BNGReference to a Shapely Polygon.

osbng.indexing.bng_to_grid_geom(bng_ref: BNGReference) → Polygon[source]#

Returns a grid square as a Shapely Polygon given a BNGReference.

Parameters:

bng_ref (BNGReference) – The BNGReference.

Returns:

Grid square as a Shapely Polygon object.

Return type:

Polygon

Raises:

BNGReferenceError – If the first positional argument is not a BNGReference.
TypeError – If first argument is not a BNGReference.

Examples

>>> bng_to_grid_geom(BNGReference("SU")).wkt
(
'POLYGON ((500000 100000, 500000 200000, 400000 200000, 400000 100000, '
'500000 100000))'
)
>>> bng_to_grid_geom(BNGReference("SU 3 1")).wkt
(
'POLYGON ((440000 110000, 440000 120000, 430000 120000, 430000 110000, '
'440000 110000))'
)
>>> bng_to_grid_geom(BNGReference("SU 3 1 NE")).wkt
(
'POLYGON ((440000 115000, 440000 120000, 435000 120000, 435000 115000, '
'440000 115000))'
)
>>> bng_to_grid_geom(BNGReference("SU 37289 15541")).wkt
(
'POLYGON ((437290 115541, 437290 115542, 437289 115542, 437289 115541, '
'437290 115541))'
)

See also

The equivalent osbng.bng_reference.BNGReference.bng_to_grid_geom() instance method.
The bng_to_bbox() function and osbng.bng_reference.BNGReference.bng_to_bbox() instance method which convert a BNGReference to bounding box coordinates.

osbng.indexing.bng_to_xy(bng_ref: BNGReference, *, position: str = 'lower-left') → tuple[int | float, int | float][source]#

Returns easting and northing coordinates given a BNGReference.

An optional grid square position keyword argument can be specified to return the coordinates of a specific corner or the centre of the grid square.

Parameters:

bng_ref (BNGReference) – The BNGReference.

Keyword Arguments:

position (str, optional) – The grid square position expressed as a string. One of: ‘lower-left’, ‘upper-left’, ‘upper-right’, ‘lower-right’, ‘centre’.

Returns:

Easting and northing coordinates as a tuple.

Return type:

tuple[int | float, int | float]

Raises:

BNGReferenceError – If the first positional argument is not a BNGReference.
TypeError – If the first argument is not a BNGReference.
ValueError – If an invalid position provided.

Examples

>>> bng_to_xy(BNGReference("SU"), position="lower-left")
(400000, 100000)
>>> bng_to_xy(BNGReference("SU 3 1"), position="lower-left")
(430000, 110000)
>>> bng_to_xy(BNGReference("SU 3 1 NE"), position="centre")
(437500, 117500)
>>> bng_to_xy(BNGReference("SU 37289 15541"), position="centre")
(437289.5, 115541.5)

See also

The equivalent osbng.bng_reference.BNGReference.bng_to_xy() instance method.
The xy_to_bng() function for encoding a easting and northing coordinates to a BNGReference at a given resolution.

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.

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

Returns a BNGIndexedGeometry list given a Shapely Geometry and resolution.

Decomposes a Shapely Geometry into grid squares at a specified resolution.

Unlike geom_to_bng() which only returns osbng.bng_reference.BNGReference objects representing the grid squares intersected by the input geometry, geom_to_bng_intersection returns BNGIndexedGeometry objects that store the intersection between the input geometry and the grid square geometries.

This is particularly useful for spatial indexing, aggregation and visualisation use cases that requires the decomposition of geometries into their constituent parts bounded by 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 BNGIndexedGeometry object. A BNGExtentError exception is raised if the coordinates are outside of the BNG index system extent.
For LineString and Polygon geometry types, the function returns a list of BNGIndexedGeometry objects representing the intersections between the grid squares and the geometry. When the geometry extends beyond the BNG index system extent, the function will show a feature bounding box warning but will still return the BNGIndexedGeometry objects for the intersected grid squares.

Parameters:

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

Returns:

List of BNGIndexedGeometry.

Return type:

list[BNGIndexedGeometry]

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

>>> from shapely.geometry import Point
>>> geom_to_bng_intersection(Point(430000, 110000), "100km")
[
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=SU, resolution_label=100km),
        is_core=False,
        geom=POINT (430000 110000)
    )
]
>>> from shapely.geometry import LineString
>>> geom_to_bng_intersection(
...     LineString([[430000, 110000], [430010, 110000], [430010, 110010]]), "5m"
... )
[
    BNGIndexedGeometry(
        bng_ref=BNGReference(
                    bng_ref_formatted=SU 3000 1000 SE,
                    resolution_label=5m
                ),
        is_core=False,
        geom=MULTILINESTRING (
             (430005 110000, 430010 110000),
             (430010 110000, 430010 110005)
        )
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(
                    bng_ref_formatted=SU 3000 1000 SW,
                    resolution_label=5m
        ),
        is_core=False,
        geom=LINESTRING (430000 110000, 430005 110000)
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(
                    bng_ref_formatted=SU 3000 1000 NE,
                    resolution_label=5m
        ),
        is_core=False,
        geom=LINESTRING (430010 110005, 430010 110010))
]
>>> from shapely import wkt
>>> geom_to_bng_intersection(
...     wkt.loads(
...         "POLYGON ("
...         "(375480.64511692 144999.23691181, 426949.67604058 160255.02751493,"
...         " 465166.20199588 153320.57724078, 453762.88376729 94454.79935802,"
...         " 393510.2158297 91989.21703833, 375480.64511692 144999.23691181)"
...         ")"
...     ),
...     "50km",
... )
[
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=SU SW,
                             resolution_label=50km
        ),
        is_core=True,
        geom=POLYGON (
             (450000 100000, 450000 150000, 400000 150000,
              400000 100000, 450000 100000)
        )
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=ST NE,
                             resolution_label=50km
        ),
        is_core=False,
        geom=POLYGON (
             (400000 152266.94988613573, 400000 150000,
              392351.90644475375 150000, 400000 152266.94988613573)
        )
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=ST SE,
                             resolution_label=50km
        ),
        is_core=False,
        geom=POLYGON (
             (392351.90644475375 150000, 400000 150000, 400000 100000,
              390785.6181363417 100000, 375480.64511692 144999.23691181,
              392351.90644475375 150000)
        )
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=SZ NW,
                             resolution_label=50km
        ),
        is_core=False,
        geom=POLYGON (
             (400000 92254.78365399371, 400000 100000, 450000 100000,
              450000 94300.8194596147, 400000 92254.78365399371)
        )
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=SZ NE,
                             resolution_label=50km
        ),
        is_core=False,
        geom=POLYGON (
             (453762.88376729 94454.79935802, 450000 94300.8194596147,
              450000 100000, 454837.0849387723 100000,
              453762.88376729 94454.79935802)
        )
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=SU SE,
                             resolution_label=50km
        ),
        is_core=False,
        geom=POLYGON (
             (454837.0849387723 100000, 450000 100000, 450000 150000,
              464522.9488131115 150000, 454837.0849387723 100000)
        )
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=SU NE,
                             resolution_label=50km
        ),
        is_core=False,
        geom=POLYGON (
             (465166.20199588 153320.57724078, 464522.9488131115 150000,
              450000 150000, 450000 156072.50905454965,
              465166.20199588 153320.57724078)
        )
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=SU NW,
                             resolution_label=50km
        ),
        is_core=False,
        geom=POLYGON (
             (426949.67604058 160255.02751493, 450000 156072.50905454965,
              450000 150000, 400000 150000, 400000 152266.94988613573,
              426949.67604058 160255.02751493)
        )
    ),
    BNGIndexedGeometry(
        bng_ref=BNGReference(bng_ref_formatted=SY NE,
                             resolution_label=50km
        ),
        is_core=False,
        geom=POLYGON (
             (393510.2158297 91989.21703833, 390785.6181363417 100000,
              400000 100000, 400000 92254.78365399371,
              393510.2158297 91989.21703833)
        )
    )
]

See also

The gdf_to_bng_intersection_explode() function function supporting the indexing of geometries in a GeoPandas GeoDataFrame against the BNG index system.
The geom_to_bng() function if geometry decomposition is not required and a list of BNGReference is sufficient.

osbng.indexing.xy_to_bng(easting: int | float, northing: int | float, resolution: int | str) → BNGReference[source]#

Returns a BNGReference given easting and northing coordinates and resolution.

Parameters:

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

Returns:

The BNGReference.

Return type:

BNGReference

Raises:

BNGResolutionError – If an invalid resolution is provided.
BNGExtentError – If the easting and northing coordinates are outside the BNG index system extent.

Examples

>>> xy_to_bng(437289, 115541, "100km")
BNGReference(bng_ref_formatted=SU, resolution_label=100km)
>>> xy_to_bng(437289, 115541, "10km")
BNGReference(bng_ref_formatted=SU 3 1, resolution_label=10km)
>>> xy_to_bng(437289, 115541, "5km")
BNGReference(bng_ref_formatted=SU 3 1 NE, resolution_label=5km)
>>> xy_to_bng(437289, 115541, 1)
BNGReference(bng_ref_formatted=SU 37289 15541, resolution_label=1m)

See also

The bng_to_xy() function and osbng.bng_reference.BNGReference.bng_to_xy() instance method for decoding a BNGReference to easting and northing coordinates.

`BNGIndexedGeometry`#

The BNGIndexedGeometry class stores information about the relationship between an input Shapely Geometry and the grid squares it intersects. This is particularly useful for spatial indexing and analysis of geometries against the BNG index system.

The BNGIndexedGeometry class is instantiated as part of the geom_to_bng_intersection() indexing function that decomposes a Shapely Geometry into grid squares at a specified resolution.

class osbng.indexing.BNGIndexedGeometry(bng_ref: BNGReference, is_core: bool, geom: Geometry)[source]#: Initialises a BNGIndexedGeometry.

Properties#

`BNGIndexedGeometry.bng_ref`	The `BNGReference` corresponding to this grid square.
`BNGIndexedGeometry.is_core`	Flag indicating whether this grid square is contained by the input geometry.
`BNGIndexedGeometry.geom`	The intersection geometry between the input geometry and this grid square.
`BNGIndexedGeometry.__repr__`()	String representation of the `BNGIndexedGeometry`.

Indexing#

BNGIndexedGeometry#

Properties#

This Page

`BNGIndexedGeometry`#