Traversal

Provides functionality for traversing the British National Grid (BNG) index system.

It supports spatial analyses such as distance-constrained nearest neighbour searches and ‘distance within’ queries by offering:

• Grid traversal: Generate k-discs and k-rings around a given grid square.

• Neighbourhood operations: Identify neighbouring grid squares and checking adjacency.

• Distance computation: Calculate the distance between grid square centroids.

• Proximity queries: Retrieve all grid squares within a specified absolute distance.

osbng.traversal.bng_distance(bng_ref1: BNGReference, bng_ref2: BNGReference, *, edge_to_edge: bool = False) → float

Returns the euclidean distance between two BNGReference objects.

When edge_to_edge is False, the distance is the centroid-to-centroid distance in metres. When edge_to_edge is True, the distance is the shortest distance between any two parts of the grid squares.

Notes

Note that the two BNGReference objects do not necessarily need to share a common resolution. When edge_to_edge = True and bng_ref1 and bng_ref2 have a parent-child relationship, the returned distance is 0.

Parameters:

• bng_ref1 (BNGReference) – A BNGReference object.

• bng_ref2 (BNGReference) – A BNGReference object.

Keyword Arguments:

edge_to_edge (bool, optional) – If False (default), distance will be centroid-to-centroid distance. If True, distance will be the shortest distance between any point in the grid squares. Keyword only.

Returns:

The euclidean distance between the two BNGReference objects.

Return type:

float

Raises:

TypeError – If the first or second argument is not a BNGReference object.

Examples

>>> bng_distance(BNGReference("SE1433"), BNGReference("SE1533"))
1000.0
>>> bng_distance(
...     BNGReference("SE1433"), BNGReference("SE1533"), edge_to_edge=True
... )
0.0
>>> bng_distance(BNGReference("SE1433"), BNGReference("SE1631"))
2828.42712474619
>>> bng_distance(BNGReference("SE1433"), BNGReference("SE"))
39147.158262126766
>>> bng_distance(BNGReference("SE1433"), BNGReference("SENW"))
42807.709586007986
>>> bng_distance(BNGReference("SE"), BNGReference("OV"))
141421.35623730952
>>> bng_distance(BNGReference("SU"), BNGReference("SU2345"), edge_to_edge=True)
0.0

See also

• The equivalent osbng.bng_reference.BNGReference.bng_distance() instance method.

• The bng_dwithin() function and osbng.bng_reference.BNGReference.bng_dwithin() instance method for obtaining all BNGReference objects within a defined distance of an input BNGReference object.

osbng.traversal.bng_dwithin(bng_ref: BNGReference, d: int | float) → list[BNGReference]

Returns a list of BNGReference objects within an absolute distance d.

All squares will be returned for which any part of its boundary is within distance d of any part of the input BNGReference’s boundary.

Parameters:

• bng_ref (BNGReference) – A BNGReference object.

• d (int or float) – The absolute distance d in metres.

Returns:

All grid squares which have any part of their geometry within distance d of bng_ref’s geometry

Return type:

list[BNGReference]

Examples

>>> bng_dwithin(BNGReference("SU1234"), 1000)
[
BNGReference(bng_ref_formatted=SU 11 33, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 12 33, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 33, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 11 34, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 12 34, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 34, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 11 35, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 12 35, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 35, resolution_label=1km)
]
>>> bng_dwithin(BNGReference("SU1234"), 1001)
[list of 21 BNGReference objects]

See also

• The equivalent osbng.bng_reference.BNGReference.bng_dwithin() instance method.

• The bng_distance() function and osbng.bng_reference.BNGReference.bng_distance() instance method for calculating the distance between two input BNGReference objects.

osbng.traversal.bng_is_neighbour(bng_ref1: BNGReference, bng_ref2: BNGReference) → bool

Tests whether two BNGReference objects are neighbours.

Returns True if the two BNGReference objects are neighbours, otherwise False. Neighbours are defined as grid squares that share an edge with the first BNGReference object.

Parameters:

• bng_ref1 (BNGReference) – A BNGReference object.

• bng_ref2 (BNGReference) – A BNGReference object.

Returns:

True if the two BNGReference objects are neighbours, otherwise False.

Return type:

bool

Raises:

• TypeError – If the first or second argument is not a BNGReference object.

• BNGNeighbourError – If the two BNGReference objects are not at the same resolution.

Examples

>>> bng_is_neighbour(BNGReference("SE1921"), BNGReference("SE1821"))
True
>>> bng_is_neighbour(BNGReference("SE1922"), BNGReference("SE1821"))
False
>>> bng_is_neighbour(BNGReference("SU1234"), BNGReference("SU1234"))
False

See also

• The equivalent osbng.bng_reference.BNGReference.bng_is_neighbour() instance method.

• The bng_neighbours() function and osbng.bng_reference.BNGReference.bng_neighbours() instance method for obtaining all neighbouring BNGReference objects of an input BNGReference object.

osbng.traversal.bng_kdisc(bng_ref: BNGReference, k: int, *, return_relations: bool = False) → list[BNGReference] | list[tuple[BNGReference, int, int]]

Returns a filled disc of BNGReference objects around a BNGReference.

Returns all BNGReference objects up to a grid distance k, including the given central BNGReference object.

Notes

Returned BNGReference objects are ordered North to South then West to East.

Parameters:

• bng_ref (BNGReference) – A BNGReference object.

• k (int) – Grid distance in units of grid squares.

Keyword Arguments:

return_relations (bool, optional) – If True, returns a list of (BNGReference, dx, dy) tuples where dx, dy are integer offsets in grid units. If False (default), returns a list of BNGReference objects. Keyword only.

Returns:

If return_relations is False (default), returns all BNGReference objects representing grid squares in a square ring of radius k. If return_relations is True, returns a list of (BNGReference, dx, dy) tuples, where dx and dy are the x and y offsets between bng_ref and each returned BNGReference object in units of grid squares.

Return type:

list[BNGReference]

Examples

>>> bng_kdisc(BNGReference("SU1234"), 1)
[
BNGReference(bng_ref_formatted=SU 11 35, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 12 35, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 35, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 11 34, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 12 34, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 34, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 11 33, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 12 33, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 33, resolution_label=1km)
]
>>> bng_kdisc(BNGReference("SU1234"), 1, return_relations=True)
[(BNGReference(bng_ref_formatted=SU 11 35, resolution_label=1km), -1, 1),
(BNGReference(bng_ref_formatted=SU 12 35, resolution_label=1km), 0, 1),
(BNGReference(bng_ref_formatted=SU 13 35, resolution_label=1km), 1, 1),
(BNGReference(bng_ref_formatted=SU 11 34, resolution_label=1km), -1, 0),
(BNGReference(bng_ref_formatted=SU 12 34, resolution_label=1km), 0, 0),
(BNGReference(bng_ref_formatted=SU 13 34, resolution_label=1km), 1, 0),
(BNGReference(bng_ref_formatted=SU 11 33, resolution_label=1km), -1, -1),
(BNGReference(bng_ref_formatted=SU 12 33, resolution_label=1km), 0, -1),
(BNGReference(bng_ref_formatted=SU 13 33, resolution_label=1km), 1, -1)]
>>> bng_kdisc(BNGReference("SU1234"), 3)
[list of 49 BNGReference objects]

See also

• The equivalent osbng.bng_reference.BNGReference.bng_kdisc() instance method.

• The bng_kring() function and osbng.bng_reference.BNGReference.bng_kring() instance method for finding all BNGReference objects at a specific distance d from an input BNGReference object.

osbng.traversal.bng_kring(bng_ref: BNGReference, k: int, *, return_relations: bool = False) → list[BNGReference] | list[tuple[BNGReference, int, int]]

Returns a hollow ring of BNGReference objects around a BNGReference object.

Returns all BNGReference objects at a grid distance k.

Notes

Returned BNGReference objects are ordered North to South then West to East, therefore not in ring order.

Parameters:

• bng_ref (BNGReference) – A BNGReference object.

• k (int) – Grid distance in units of grid squares.

Keyword Arguments:

return_relations (bool, optional) – If True, returns a list of (BNGReference, dx, dy) tuples where dx, dy are integer offsets in grid units. If False (default), returns a list of BNGReference objects. Keyword only.

Returns:

If return_relations is False (default), returns all BNGReference objects representing squares in a square ring of radius k. If return_relations is True, returns a list of (BNGReference, dx, dy) tuples, where dx and dy are the x and y offsets between bng_ref and each returned BNGReference object in units of grid squares.

Return type:

list[BNGReference]

Examples

>>> bng_kring(BNGReference("SU1234"), 1)
[
BNGReference(bng_ref_formatted=SU 11 35, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 12 35, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 35, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 11 34, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 34, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 11 33, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 12 33, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 33, resolution_label=1km)
]
>>> bng_kring(BNGReference("SU1234"), 1, return_relations=True)
[(BNGReference(bng_ref_formatted=SU 11 35, resolution_label=1km), -1, 1),
(BNGReference(bng_ref_formatted=SU 12 35, resolution_label=1km), 0, 1),
(BNGReference(bng_ref_formatted=SU 13 35, resolution_label=1km), 1, 1),
(BNGReference(bng_ref_formatted=SU 11 34, resolution_label=1km), -1, 0),
(BNGReference(bng_ref_formatted=SU 13 34, resolution_label=1km), 1, 0),
(BNGReference(bng_ref_formatted=SU 11 33, resolution_label=1km), -1, -1),
(BNGReference(bng_ref_formatted=SU 12 33, resolution_label=1km), 0, -1),
(BNGReference(bng_ref_formatted=SU 13 33, resolution_label=1km), 1, -1)]
>>> bng_kring(BNGReference("SU1234"), 3)
[list of 24 BNGReference objects]

See also

• The equivalent osbng.bng_reference.BNGReference.bng_kring() instance method.

• The bng_kdisc() function and osbng.bng_reference.BNGReference.bng_kdisc() instance method for finding all BNGReference objects within a distance d from an input BNGReference object.

osbng.traversal.bng_neighbours(bng_ref: BNGReference) → list[BNGReference]

Returns the four BNGReference object neighbours of a BNGReference.

The neighbours are defined as the grid squares immediately North, East, South and West of the input grid square sharing an edge with the input BNGReference object.

Parameters:

bng_ref (BNGReference) – A BNGReference object.

Returns:

The grid squares immediately North, East, South and West of bng_ref, in that order.

Return type:

list[BNGReference]

Examples

>>> bng_neighbours(BNGReference("SU1234"))
[
BNGReference(bng_ref_formatted=SU 12 35, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 13 34, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 12 33, resolution_label=1km),
BNGReference(bng_ref_formatted=SU 11 34, resolution_label=1km)
]

See also

• The equivalent osbng.bng_reference.BNGReference.bng_neighbours() instance method.

• The bng_is_neighbour() function and osbng.bng_reference.BNGReference.bng_is_neighbour() instance method for testing whether two BNGReference objects are neighbours.