Skip to main content

GridX

GridX

Full API reference

For the complete list of GridX (BNG) functions with parameters and examples, see the GridX Function Reference.

GridX is GeoBrix's grid indexing package, providing discrete global grid indexing capabilities with a focus on the British National Grid (BNG) system.

Registration and import path

GridX BNG functions are under gridx.bng. Use gridx.bng when importing from databricks.labs.gbx.gridx.bng (Python) or com.databricks.labs.gbx.gridx.bng (Scala).

Overview​

GridX is a refactor of Mosaic discrete global grid indexing functions. The current focus has been on porting BNG (British National Grid) for Great Britain customers, providing specialized grid operations for UK-based spatial data.

British National Grid (BNG)​

The British National Grid is the national coordinate system for Great Britain. It is based on the Ordnance Survey National Grid (OSGB36) and divides the UK into grid squares with letter-based prefixes and numeric coordinates.

BNG Structure​

  • Grid Squares: 100km × 100km squares identified by two letters (e.g., "TQ", "SU")
  • Eastings & Northings: Numeric coordinates within each grid square
  • Precision: Supports various precision levels (1m, 10m, 100m, 1km, etc.)

Key Features​

  • Grid Cell Operations: Create, manipulate, and query BNG grid cells
  • Area Calculations: Calculate areas of grid cells at different precisions
  • Coordinate Conversion: Convert between grid references and coordinates
  • Spatial Indexing: Use BNG for efficient spatial indexing
  • Multi-Resolution Support: Work with different grid resolutions

Function Categories​

Cell operations and geometry​

  • gbx_bng_cellarea - Area of a BNG grid cell (square kilometres)
  • gbx_bng_distance - Grid distance between two cells
  • gbx_bng_euclideandistance - Euclidean distance between cell centers
  • gbx_bng_cellintersection - Intersection of two cells (geometry)
  • gbx_bng_cellunion - Union of two cells (geometry)
  • gbx_bng_centroid - Centroid of a BNG cell (point geometry)
  • gbx_bng_aswkt - BNG cell as WKT polygon
  • gbx_bng_aswkb - BNG cell as WKB polygon

Point and coordinate conversion​

  • gbx_bng_pointascell - Convert point geometry to BNG cell reference (point as WKT or WKB)
  • gbx_bng_eastnorthasbng - Create BNG cell from easting/northing and resolution

K-ring and k-loop​

  • gbx_bng_kring - K-ring of cells around a center cell
  • gbx_bng_kloop - K-loop (hollow ring) around a center cell
  • gbx_bng_geomkring - K-ring for a geometry at a given resolution
  • gbx_bng_geomkloop - K-loop for a geometry
  • gbx_bng_kringexplode - Explode k-ring into rows
  • gbx_bng_kloopexplode - Explode k-loop into rows
  • gbx_bng_geomkringexplode - Explode geometry k-ring into rows
  • gbx_bng_geomkloopexplode - Explode geometry k-loop into rows

Tessellation and polyfill​

  • gbx_bng_tessellate - Tessellate geometry into BNG cells
  • gbx_bng_polyfill - Polyfill geometry with BNG cells
  • gbx_bng_tessellateexplode - Explode tessellation into rows

Aggregations​

  • gbx_bng_cellintersection_agg - Aggregate intersection of cells
  • gbx_bng_cellunion_agg - Aggregate union of cells

Usage Examples​

Python/PySpark​

from databricks.labs.gbx.gridx.bng import functions as bx

bx.register(spark)

# London (TQ area) in BNG: easting 530000, northing 180000
# Resolution: BNG resolution index (3 = 1 km) or string ('1km'). gbx_bng_cellarea returns km².
bng_cells = spark.sql(
    """
    SELECT
      gbx_bng_pointascell('POINT(530000 180000)', '1km') as bng_cell,
      gbx_bng_cellarea(gbx_bng_pointascell('POINT(530000 180000)', '1km')) as cell_area_km2
    """
)
bng_cells.show()
Example output
+----------+--------------+
|bng_cell  |cell_area_km2 |
+----------+--------------+
|TQ3080    |1.0           |
+----------+--------------+

Scala​

import com.databricks.labs.gbx.gridx.bng.{functions => bx}
import org.apache.spark.sql.functions._

// Register functions
bx.register(spark)

// Calculate cell area
val areaDf = spark.sql("SELECT gbx_bng_cellarea('TQ', 1000) as area")
areaDf.show()

// Create BNG cells from points (point as WKT; GeoBrix does not accept st_point)
val pointsDf = Seq(
  (51.5074, -0.1278)
).toDF("lat", "lon")

val bngCells = pointsDf.select(
  col("lat"),
  col("lon"),
  expr("gbx_bng_pointascell(concat('POINT(', cast(lon as string), ' ', cast(lat as string), ')'), 1000)").alias("bng_cell")
)

bngCells.show()
Example output
+-----------+
|area       |
+-----------+
|1000000.0  |
+-----------+

+-------+-------+----------+
|lat    |lon    |bng_cell  |
+-------+-------+----------+
|51.5074|-0.1278|TQ 30 80  |
+-------+-------+----------+

SQL​

-- Register functions first in Python/Scala notebook

-- Point in BNG coordinates (eastings, northings, EPSG:27700). Resolution: BNG resolution string ('1km') or index (3).
-- gbx_bng_cellarea returns square kilometres.
SELECT
  gbx_bng_pointascell('POINT(530000 180000)', '1km') as bng_cell_1km,
  gbx_bng_cellarea(gbx_bng_pointascell('POINT(530000 180000)', '1km')) as area_km2;
Example output
+------------+----------+
|bng_cell_1km|area_km2  |
+------------+----------+
|TQ3080      |1.0       |
+------------+----------+

BNG Grid Reference Format​

Standard Format​

BNG references follow the format: [Letters][Eastings][Northings]

Examples:

  • TQ 38 80 - 1km precision (Tower of London area)
  • TQ 3800 8000 - 100m precision
  • TQ 38000 80000 - 10m precision
  • SU 12 34 - Different grid square

Precision Levels​

PrecisionGrid SizeUse Case
100000m100km × 100kmRegional analysis
10000m10km × 10kmDistrict-level
1000m1km × 1kmLocal area analysis
100m100m × 100mNeighborhood level
10m10m × 10mBuilding level
1m1m × 1mPrecise location

Next Steps​