osbng: Geospatial Grid Indexing and Interaction with the British National Grid

Description

Offers a streamlined programmatic interface to Ordnance Survey's British National Grid (BNG) index system, enabling efficient spatial indexing and analysis based on grid references. It supports a range of geospatial applications, including statistical aggregation, data visualisation, and interoperability across datasets. Designed for developers and analysts working with geospatial data in Great Britain, osbng simplifies integration with geospatial workflows and provides intuitive tools for exploring the structure and logic of the BNG system.

Author(s)

Maintainer: Chris Jochem chris.jochem@os.uk

Other contributors:

• Ordnance Survey Ltd [copyright holder, funder]

• Steve Kingston [contributor]

• Kate New [contributor]

• Tom Peterken [contributor]

See Also

Useful links:

• https://ordnancesurvey.github.io/osbng-r/

• https://github.com/OrdnanceSurvey/osbng-r

• Report bugs at https://github.com/OrdnanceSurvey/osbng-r/issues

BNG Reference objects

Description

Functions to support working with objects of type BNGReference.

Usage

## S3 method for class 'BNGReference'
x[i]

## S3 method for class 'BNGReference'
x[[i]]

## S3 replacement method for class 'BNGReference'
x[i] <- value

## S3 replacement method for class 'BNGReference'
x[[i]] <- value

## S3 method for class 'BNGReference'
c(...)

## S3 method for class 'BNGReference'
unique(x, incomparables = FALSE, ...)

## S3 method for class 'BNGReference'
as.data.frame(x, ...)

Arguments

Details

The BNG is structured using a hierarchical system of grid squares at various resolutions. At its highest level, the grid is divided into 100 km by 100 km squares, each of which is identified by a two-letter code. Successive levels of resolution further subdivide the grid squares into finer detail, down to individual 1-meter squares.

Value

A vector of type BNGReference.

See Also

is_valid_bng(), as_bng_reference()

Examples

x <- as_bng_reference(c("TQ1234", "SU5678"))

x[1]

x[2] <- as_bng_reference("SU56")
x

Region Boundaries for London

Description

This file (London_Regions_December_2024_Boundaries_EN_BFC.gpkg) contains the digital vector boundaries for the London Region in England as at December 2024. The boundaries available are: (BFC) Full resolution - clipped to the coastline (Mean High Water mark). The coordinate reference system is British National Grid (OSGB36; EPSG:27700). Contains both Ordnance Survey and ONS Intellectual Property Rights. Licenced under the Open Government Licence (OGLv3).

Format

GeoPackage with one layer, 1 rows and 8 columns:

fid

Row index.

RGN24CD

Character. Region GSS code.

RGN24NM

Character. Standardised Region name.

BNG_E

Centroid eastings in British National Grid.

BNG_N

Centroid northings in British National Grid.

LONG

Centroid longitude coordinate.

LAT

Centroid latitude coordinate.

GlobalID

Database management.

Source

Office for National Statistics (ONS), released 16 February 2025, Regions (December 2024) Boundaries EN BFC, ONS Open Geography Portal.

Create BNG reference objects

Description

Convert or test user input (strings) to a custom object for handling British National Grid (BNG) references.

Usage

as_bng_reference(bng_ref, ...)

## Default S3 method:
as_bng_reference(bng_ref, ...)

## S3 method for class 'BNGReference'
as_bng_reference(bng_ref, ...)

## S3 method for class 'character'
as_bng_reference(bng_ref, ...)

is_bng_reference(bng_ref)

Arguments

Details

Converts a BNG reference string into a BNGReference object, ensuring type consistency across the package. All functions accepting or returning BNG references enforce the use of this class.

The BNG is structured using a hierarchical system of grid squares at various resolutions. At its highest level, the grid is divided into 100 km by 100 km squares, each of which is identified by a two-letter code. Successive levels of resolution further subdivide the grid squares into finer detail, down to individual 1-meter squares.

The package supports the 'standard' and 'intermediate' quadtree resolutions: 100km, 50km, 10km, 5km, 1km, 500m, 100m, 50m, 10m, 5m and 1m.

Value

An object of type BNGReference.

See Also

is_valid_bng(), BNGReference

Examples

as_bng_reference("TQ1234")

as_bng_reference(c("TQ1234", "SU5678"))

Convert bounding boxes

Description

Create British National Grid reference from bounding boxes or convert grid reference objects into bounding boxes.

Usage

bbox_to_bng(...)

## S3 method for class 'numeric'
bbox_to_bng(xmin, ymin, xmax, ymax, resolution, ...)

## S3 method for class 'matrix'
bbox_to_bng(x, resolution, ...)

## S3 method for class 'data.frame'
bbox_to_bng(x, resolution, ...)

bng_to_bbox(bng_ref, ...)

bng_to_grid_geom(bng_ref, format = c("geos", "sf", "wkt"), ...)

Arguments

Details

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

If the bounding box edges align with the BNG system (e.g. xmin, ymin, xmax, ymax are multiples of the specified resolution), only the grid squares entirely contained within the bounding box are returned. Grid squares that intersect but are not fully contained within the bounding box are excluded.

If the bounding box edges are not aligned with the BNG system, grid squares that are partially overlapped by the bounding box are also included. In this case, the function ensures all relevant grid squares that the bounding box touches are returned, including those at the edges.

Validates and normalises the bounding box coordinates to the BNG index system extent. If bounding box coordinates fall outside of the BNG system extent, the coordinates are snapped to the bounds of the BNG system.

Bounding boxes are expressed as four coordinates (min x, min y, max x, max y). Coordinates must be in British National Grid projection (EPSG:27700). These functions do not support coordinate transformations.

For matrix input, the first four columns are used as xmin, ymin, xmax, and ymax, respectively. For data.frame input columns must be named "xmin", "ymin", "xmax", and "ymax" or the first columns will be assumed.

To return the BNG grid squares within the bounding box of a geometry, see geom_to_bng().

Value

• bng_to_bbox: numeric vector of bounding easting and northing coordinates. If multiple references are supplied to bng_ref then a matrix of coordinates is returned.

• bbox_to_bng: list containing vectors of BNGReference objects.

• bng_to_grid_geom converts the bounding box coordinates into a polygon geometry object.

Examples

bbox_to_bng(400000, 100000, 500000, 200000, "50km")

bbox_to_bng(285137.06, 78633.75, 299851.01, 86427.96, 5000)

bng_to_bbox(as_bng_reference("SU"))

bng_to_bbox(as_bng_reference("SU 3 1"))

bng_to_bbox(as_bng_reference("SU 3 1 NE"))

bng_to_bbox(as_bng_reference("SU 37289 15541"))

bng_to_grid_geom(as_bng_reference("SU"))

bng_to_grid_geom(as_bng_reference("SU 3 1"))

bng_to_grid_geom(as_bng_reference("SU 3 1 NE"))

bng_to_grid_geom(as_bng_reference("SU 37289 15541"))

Distance calculations

Description

Compute Euclidean distances between BNG references and distance-based neighbours lists.

Usage

bng_dwithin(bng_ref, d, ...)

bng_distance(bng_ref1, bng_ref2, by_element = FALSE, edge_to_edge = FALSE)

Arguments

Details

bng_dwithin returns all grids squares for which any part of the boundary is within the distance d of any part of bng_ref's boundary.

Value

list containing an unordered vector of BNGReference objects around a given grid square within an absolute distance d.

If by_element is FALSE bng_distance returns a dense numeric matrix of dimension length(x) by length(y); otherwise it returns a numeric vector the same length as x and y with an error raised if the lengths of x and y are unequal. Distances involving invalid references are NA.

Examples

bng_dwithin(as_bng_reference("SU1234"), 1000)

bng_dwithin(as_bng_reference("SU1234"), 1001)


ref1 <- as_bng_reference("SE1433")

bng_distance(ref1, as_bng_reference("SE1631"))

bng_distance(ref1, as_bng_reference("SENW"))

ref2 <- as_bng_reference(c("SE1533", "SE1631", "SE"))

bng_distance(ref1, ref2)

bng_distance(ref2)

ref3 <- as_bng_reference(c("SE1433", "SE1244"))

bng_distance(ref3, ref2)

bng_distance(ref3, ref2[1:2], by_element = TRUE)

bng_distance(ref1, ref2, edge_to_edge = TRUE)

Map BNG References to Spatial Objects

Description

Generate a spatial data frame of BNG references and grid square geometries.

Usage

bng_grid_100km(xmin, ymin, xmax, ymax, ...)

bng_grid_50km(xmin, ymin, xmax, ymax, ...)

bng_grid_10km(xmin, ymin, xmax, ymax, ...)

bng_grid_5km(xmin, ymin, xmax, ymax, ...)

bng_grid_1km(xmin, ymin, xmax, ymax, ...)

Arguments

Details

These convenience functions generate a spatial data frame of BNG references and grid square geometries at pre-determined resolutions. This function combines bbox_to_bng() and bng_to_grid_geom() into a data frame. Optionally, the grid can be for a defined bounding box area of interest. If the bounding box is omitted, then all grid squares within the valid bounds of the BNG are returned.

Only selected resolutions are provided to avoid excessively large data frames. For additional spatial data files of all resolutions, please see the osbng-grids GitHub repo.

The sf package is required for this function.

Value

Data frame object of type sf with the grid reference as a BNGReference object and the grid square polygon geometry.

See Also

bbox_to_bng(), geom_to_bng()

Examples

bng_grid_100km()

bng_grid_1km(529476, 179654, 532170, 181116)

Spatial neighbourhoods in the British National Grid index system

Description

Identify neighbours in a hollow ring or solid disc at grid distance 'k' from a target BNG reference.

Usage

bng_kring(bng_ref, k, ...)

bng_kdisc(bng_ref, k, ...)

Arguments

Details

K-rings are hollow rings of grid squares at a grid distance k while k-discs are filled areas around a given grid square up to a grid distance k. bng_kdisc includes the given BNG Reference (i.e. the central grid square).

In the event that bng_ref is along the edge or corner of the valid BNG area, then any return BNG references of the ring/disc outside the valid BNG range will not be returned.

Value

list containing an unordered collection of objects of type BNGReference within the neighbourhood around the given grid reference.

Examples

bng_kring(as_bng_reference("SU1234"), 1)

bng_kring(as_bng_reference("SU1234"), 3)

bng_kdisc(as_bng_reference("SU1234"), 1)

bng_kdisc(as_bng_reference("SU1234"), 3)

Identify neighbouring grid squares

Description

Find BNG references which share a grid cell edge with a target BNG reference.

Usage

bng_neighbours(bng_ref, ...)

bng_is_neighbour(bng_ref1, bng_ref2, ...)

Arguments

Details

Grid references are "neighbours" when they share a contiguous edge (i.e. corners do not define neighbours). In the event that a target reference is along the edge or corner of the valid BNG area, then 3 or 2 references, respectively, will be returned bng_is_neighbour only compares references of equal resolution.

If bng_ref1 exactly matches bng_ref2 then bng_is_neighbour returns FALSE.

Value

A list containing a set of up to four BNGReference objects that border the target reference.

a boolean identifying if the grid references share a border

Examples

bng_neighbours(as_bng_reference("SU1234"))

bng_is_neighbour(as_bng_reference("SE1921"), as_bng_reference("SE1821"))

bng_is_neighbour(as_bng_reference("SE1922"), as_bng_reference("SE1821"))

bng_is_neighbour(as_bng_reference("SU1234"), as_bng_reference("SU1234"))

Navigate the British National Grid hierarchy

Description

Identify the "parent" or "children" references which contain or are nested within a given BNG reference.

Usage

bng_to_children(bng_ref, resolution, ...)

bng_to_parent(bng_ref, resolution, ...)

Arguments

Details

The BNG is structured using a hierarchical system of grid squares at various resolutions. At its highest level, the grid divides GB into 100 km by 100 km squares, each identified by a two-letter code. Successive levels of resolution further subdivide the grid squares into finer detail, down to individual 1-meter squares. These functions allow for the traversal of this hierarchy by providing methods to return the parent and children of BNGReference objects at specified resolutions.

Definitions:

Parent

The parent of a BNGReference object is the grid square at the next higher (coarser) resolution level that contains the current reference. For example, the parent of a 1km grid square reference would be the 5km grid square that contains it.

Children

The children of a BNGReference object are the grid squares at the next lower (finer) resolution level that are contained within the current reference. For example, the children of a 10km grid square reference would be all the 5km grid squares that it contains.

Value

child references will be a list of BNGReference objects with each item in the list being the set of children for the input grid reference. Parent references will be a vector of BNGReference objects.

Examples

bng_to_children(as_bng_reference("SU"))

bng_to_children(as_bng_reference("SU36"))

bng_to_parent(as_bng_reference("SU36SW"))

bng_to_parent(as_bng_reference("SU342567"))

bng_to_parent(as_bng_reference("SU342567"), resolution = 10000)

Convert BNG References

Description

Create British National Grid references from coordinates at a specific resolution or convert grid reference objects to coordinates at a grid position.

Usage

bng_to_xy(
  bng_ref,
  position = c("lower-left", "upper-left", "upper-right", "lower-right", "centre"),
  ...
)

xy_to_bng(...)

## S3 method for class 'numeric'
xy_to_bng(easting, northing, resolution, ...)

## S3 method for class 'matrix'
xy_to_bng(x, resolution, ...)

## S3 method for class 'data.frame'
xy_to_bng(df, cols = c("eastings", "northings"), resolution, ...)

Arguments

Details

Coordinates must be in British National Grid projection (EPSG:27700) using eastings and northings in meters. These functions do not support coordinate transformations.

Value

• xy_to_bng: vector of BNGReference objects

• bng_to_xy: two-column matrix of eastings and northings

Examples

bng_to_xy(as_bng_reference("SU"), "lower-left")

bng_to_xy(as_bng_reference("SU 3 1"), "lower-left")

bng_to_xy(as_bng_reference("SU 3 1 NE"), "centre")

bng_to_xy(as_bng_reference("SU 37289 15541"), "centre")

xy_to_bng(437289, 115541, "100km")

xy_to_bng(437289, 115541, "10km")

xy_to_bng(437289, 115541, "5km")

xy_to_bng(437289, 115541, 1)
  

Spatial index for geometries

Description

Returns a set of BNG Reference objects given a geometry and a specified resolution.

Usage

geom_to_bng(geom, resolution, ...)

## S3 method for class 'geos_geometry'
geom_to_bng(geom, resolution, ...)

## S3 method for class 'sf'
geom_to_bng(geom, resolution, ...)

## S3 method for class 'sfc'
geom_to_bng(geom, resolution, ...)

geom_to_bng_intersection(
  geom,
  resolution,
  format = c("geos", "sf", "wkt"),
  ...
)

## S3 method for class 'geos_geometry'
geom_to_bng_intersection(
  geom,
  resolution,
  format = c("geos", "sf", "wkt"),
  ...
)

## S3 method for class 'sf'
geom_to_bng_intersection(
  geom,
  resolution,
  format = c("geos", "sf", "wkt"),
  ...
)

## S3 method for class 'sfc'
geom_to_bng_intersection(
  geom,
  resolution,
  format = c("geos", "sf", "wkt"),
  ...
)

Arguments

Details

The BNG Reference objects returned represent the grid squares intersected by the input geometry. BNG Reference objects are de-duplicated in cases where two or more parts of a multi-part geometry intersect the same grid square.

Unlike geom_to_bng which only returns BNG Reference objects representing the grid squares intersected by the input geometry, geom_to_bng_intersection returns list objects that store the intersection between the input geometry and the grid square geometries.

These functions are useful for spatial indexing and aggregation of geometries against the BNG. For geometry decomposition by the BNG index system, use geom_to_bng_intersection instead.

Value

geom_to_bng: list of vectors of BNGReference objects where the number of items in the list equal length(geom).

geom_to_bng_intersection: list of nested lists with length(geom). Each nested list contains three named items:

• "BNGReference" - BNGReference objects representing the grid squares corresponding to the decomposition.

• "is_core" - logical vector indicating whether the grid square geometry is entirely contained by the input geometry. This is relevant for Polygon geometries and helps distinguish between "core" (fully inside) and "edge" (partially overlapping) grid squares.

• "geom" - The geometry representing the intersection between the input geometry and the grid square. This can one of a number of geometry types depending on the overlap. When "is_core" is TRUE, "geom" is the same as the grid square geometry.

See Also

geom_to_bng_intersection_explode()

Examples

geom_to_bng(geos::geos_make_point(430000, 110000), "100km")

geom_to_bng(geos::geos_make_linestring(c(430000, 430010, 430010), c(110000,
110000, 110010)), "5m")

geom_to_bng_intersection(geos::geos_make_point(430000, 110000), "100km")

geom_to_bng_intersection(geos::geos_make_linestring(c(430000, 430010,
430010), c(110000, 110000, 110010)), "5m")

geom_to_bng_intersection(geos::geos_make_polygon(c(375480.64511692,
426949.67604058, 465166.20199588, 453762.88376729, 393510.2158297,
375480.64511692), c(144999.23691181, 160255.02751493, 153320.57724078,
94454.79935802, 91989.21703833, 144999.23691181)), "50km")

Spatial data frame for indexed geometries

Description

Generate a set of BNG Reference objects given a geometry and a specified resolution and provide results in a spatial data frame format.

Usage

geom_to_bng_intersection_explode(geom, resolution, reset_index = TRUE, ...)

## S3 method for class 'geos_geometry'
geom_to_bng_intersection_explode(geom, resolution, reset_index = TRUE, ...)

## S3 method for class 'sf'
geom_to_bng_intersection_explode(geom, resolution, reset_index = TRUE, ...)

## S3 method for class 'sfc'
geom_to_bng_intersection_explode(geom, resolution, reset_index = TRUE, ...)

Arguments

Details

The BNG Reference objects returned represent the grid squares intersected by the input geometry. This function followings the pattern of geom_to_bng_intersection(), but flattens the list structure of results into a spatial data frame. The original geometry is dropped in this process and all other columns are retained in the output.

The sf package is required to use this functionality.

Value

a spatial data frame of type sf with the coordinate reference system to British National Grid (EPSG:27700). The non-geometry columns of the input (if any) are joined with three columns for the BNGReference object, the is_core property, and the indexed geometry.

See Also

geom_to_bng_intersection()

Examples

geom_to_bng_intersection_explode(geos::geos_make_polygon(c(375480.64511692, 
426949.67604058, 465166.20199588, 453762.88376729, 393510.2158297, 
375480.64511692), c(144999.23691181, 160255.02751493, 153320.57724078, 
94454.79935802, 91989.21703833, 144999.23691181)), "50km")
 

BNG reference resolution

Description

Find the spatial resolution (i.e. grid size) of a British National Grid square, or list valid resolutions.

Usage

get_bng_resolution(bng_ref)

get_bng_resolution_string(bng_ref)

list_bng_resolution(which = c("all", "whole", "quad"), lbl = FALSE)

Arguments

Details

The integer values represent spatial resolutions in metres, while the string labels provide a human-readable descriptor for each resolution level. For example, the numeric resolution 1000 is mapped to the label '1km'.

Value

A vector of numeric values for get_bng_resolution() in metres or character strings expressing the resolution of the grid references.

vector of BNG resolutions as either numeric values or character labels.

Examples

get_bng_resolution(as_bng_reference("TQ1234"))

get_bng_resolution_string(as_bng_reference("TQ1234NE"))

list_bng_resolution(which = "all", lbl = TRUE)

List the components of the British National Grid

Description

Helper functions to provide access to the bounds and set of 100km grid reference identifiers.

Usage

list_bng_prefixes(arranged = FALSE)

list_bng_bounds(named = TRUE)

Arguments

Details

When arranged is TRUE, the matrix arrangement matches the British National Grid, but note the orientation. The first element "SV" would be mapped in the southwest corner.

Value

a character vector of 2-letter identifiers for all valid 100km grid squares. When arranged is TRUE this vector is coerced into a 2D matrix.

a numeric vector with four values for the xmin, ymin, xmax, and ymax coordinates for the valid extant of the British National Grid.

Examples

list_bng_prefixes()

list_bng_prefixes(arranged = TRUE)

list_bng_bounds()

Printing BNG References

Description

Supporting formatting and printing of BNGReference objects.

Usage

## S3 method for class 'BNGReference'
print(x, ...)

## S3 method for class 'BNGReference'
format(x, compact = FALSE, ...)

Arguments

Details

Standard spaces are added: 1) after the two-letter prefix, 2) between eastings and northings, and 3) before a quadrant suffix, when those components exist in a grid reference.

Value

• format provides a standard formatting of BNG reference objects

• print outputs the BNG references and invisibly returns the object.

Examples

x <- as_bng_reference("SU1234")
print(x)

print(x, compact = TRUE)

Check validity of a BNG Reference

Description

Validates a British National Grid reference string using a regular expression pattern.

Helper function used to verify resolutions.

Usage

is_valid_bng(bng_ref)

## S3 method for class 'character'
is_valid_bng(bng_ref)

## S3 method for class 'BNGReference'
is_valid_bng(bng_ref)

is_valid_bng_resolution(resolution)

Arguments

Details

The BNG is structured using a hierarchical system of grid squares at various resolutions. At its highest level, the grid is divided into 100 km by 100 km squares, each of which is identified by a two-letter code. Successive levels of resolution further subdivide the grid squares into finer detail, down to individual 1-meter squares.

Each reference consists of a 2-letter prefix (identifying the 100 km grid square), followed by an easting and northing value, which may be further subdivided using intermediate resolutions. Additionally, an optional suffix representing ordinal (intercardinal) directions (NE, SE, SW, NW) may be appended to the reference to account for quadtree subdivision of the grid at finer resolutions. The grid reference can be expressed at different scales, as follows:

1. 100 km: Identified by a two-letter code (e.g. 'TQ').

2. 50 km: Subdivides the 100 km grid into four quadrants. The grid reference adds an ordinal direction suffix (NE, NW, SE, SW) to indicate the quadrant within the 100 km square (e.g. 'TQSW').

3. 10 km: Adds two-digit easting and northing values (e.g. 'TQ23').

4. 5 km: Subdivides the 10 km square adding an ordinal suffix (e.g. 'TQ53SW').

5. 1 km: Adds four-digit easting and northing values (e.g. 'TQ2334').

6. 500 m: Subdivides the 1 km square adding an ordinal suffix (e.g. 'TQ2334NE').

7. 100 m: Adds six-digit easting and northing values (e.g. ' TQ238347').

8. 50 m: Subdivides the 100 m square adding an ordinal suffix (e.g. 'TQ238347SE').

9. 10 m: Adds eight-digit easting and northing values (e.g. 'TQ23863472').

10. 5 m: Subdivides the 10 m square adding an ordinal suffix (e.g. e.g. 'TQ23863472NW').

11. 1 m: Adds ten-digit easting and northing values (e.g. 'TQ2386334729').

BNG references must adhere to the following format:

• Whitespace may or may not separate the components of the reference (i.e. between the two-letter 100km grid square prefix, easting, northing, and ordinal suffix).

• If whitespace is present, it should be a single space character.

• Whitespace can be inconsistently used between components of the reference.

• The two-letter 100 km grid square prefixes and ordinal direction suffixes (NE, SE, SW, NW) should be capitalised.

At each resolution, a given location can be identified with increasing detail, allowing for variable accuracy depending on the geospatial application, from small-scale mapping to precise survey measurements.

Value

Logical vector indicating for each reference of bng_ref whether it is valid.

Logical vector testing resolution.

See Also

as_bng_reference()

Examples

is_valid_bng("TQ1234")  # TRUE

is_valid_bng("TQ123")  # FALSE

is_valid_bng("TQ 12 34")  # TRUE

is_valid_bng_resolution(1000)

is_valid_bng_resolution("1km")

is_valid_bng_resolution(0.5)