Skip to main content

Scala API Reference

GeoBrix is natively written in Scala, providing the most direct and performant access to its functionality.

Import Patterns​

RasterX​

RasterX Import Pattern
import com.databricks.labs.gbx.rasterx.{functions => rx}

// Register functions
rx.register(spark)

// Use functions
val df = rasters.select(rx.rst_boundingbox(col("tile")))
Example output
df: DataFrame with bbox column from tile

GridX (BNG)​

GridX Import Pattern
import com.databricks.labs.gbx.gridx.bng.{functions => bx}

// Register functions
bx.register(spark)

// Use functions
val df = spark.sql("SELECT gbx_bng_cellarea('TQ', 1000)")
Example output
df: DataFrame with area_sqm (e.g. 1000000.0)

VectorX​

VectorX Import Pattern
import com.databricks.labs.gbx.vectorx.jts.legacy.{functions => vx}

// Register functions
vx.register(spark)

// Use functions
val df = legacyData.select(vx.st_legacyaswkb(col("mosaic_geom")))
Example output
df: DataFrame with wkb geometry column

RasterX Functions​

Accessor Functions​

RasterX Accessor Functions
import com.databricks.labs.gbx.rasterx.{functions => rx}
import org.apache.spark.sql.functions._

// Register functions
rx.register(spark)

// Read rasters (sample data path)
val rasters = spark.read.format("gdal").load("/Volumes/main/default/geobrix_samples/geobrix-examples/nyc/sentinel2/nyc_sentinel2_red.tif")

// Extract metadata
val metadata = rasters.select(
  col("path"),
  rx.rst_boundingbox(col("tile")).alias("bbox"),
  rx.rst_width(col("tile")).alias("width"),
  rx.rst_height(col("tile")).alias("height"),
  rx.rst_numbands(col("tile")).alias("num_bands"),
  rx.rst_metadata(col("tile")).alias("metadata")
)

metadata.show()
Example output
+--------------------+------------------+-----+------+---------+--------+
|path                |bbox              |width|height|num_bands|metadata|
+--------------------+------------------+-----+------+---------+--------+
|.../nyc_sentinel2...|POLYGON ((-74....)|10980|10980 |1        |{...}   |
+--------------------+------------------+-----+------+---------+--------+

Transformation Functions​

RasterX Transformation Functions
import com.databricks.labs.gbx.rasterx.{functions => rx}
import org.apache.spark.sql.functions._

rx.register(spark)

val rasters = spark.read.format("gdal").load("/Volumes/main/default/geobrix_samples/geobrix-examples/nyc/sentinel2/nyc_sentinel2_red.tif")

// Clip raster with WKT geometry (GeoBrix accepts WKT or WKB; cutlineAllTouched = true)
val clipWkt = "POLYGON((-122 37, -122 38, -121 38, -121 37, -122 37))"
val clipped = rasters.select(
  col("path"),
  rx.rst_clip(col("tile"), lit(clipWkt), lit(true)).alias("clipped_tile")
)
Example output
+--------------------+------------+
|path                |clipped_tile|
+--------------------+------------+
|...                 |[BINARY]    |
+--------------------+------------+

Complete Example​

RasterX Complete Example
import com.databricks.labs.gbx.rasterx.{functions => rx}
import org.apache.spark.sql.functions._

// Register functions
rx.register(spark)

// Read rasters (sample data path)
val rasters = spark.read.format("gdal").load("/Volumes/main/default/geobrix_samples/geobrix-examples/nyc/sentinel2/nyc_sentinel2_red.tif")

// Extract metadata and filter
val catalog = rasters.select(
  col("path"),
  rx.rst_boundingbox(col("tile")).alias("bbox"),
  rx.rst_width(col("tile")).alias("width"),
  rx.rst_height(col("tile")).alias("height"),
  rx.rst_numbands(col("tile")).alias("bands"),
  rx.rst_metadata(col("tile")).alias("metadata")
).filter(
  col("width") > 1000 && col("height") > 1000
)

// Write to Delta
catalog.write.mode("overwrite").saveAsTable("raster_catalog")
Example output
Table raster_catalog created with path, bbox, width, height, bands, metadata

GridX Functions​

BNG Functions​

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

// Register functions
bx.register(spark)

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

// Convert points to BNG cells (point as WKT; GeoBrix does not accept st_point)
val points = spark.table("uk_locations")
val bngCells = points.select(
  col("location_id"),
  expr("gbx_bng_pointascell(concat('POINT(', cast(longitude as string), ' ', cast(latitude as string), ')'), 1000)").alias("bng_cell")
)

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

+-----------+----------+
|location_id|bng_cell  |
+-----------+----------+
|1          |TQ 31 SW  |
|...        |...       |
+-----------+----------+

Complete Example​

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

// Register functions
bx.register(spark)

// Aggregate by BNG cell (point as WKT; GeoBrix does not accept st_point)
val aggregated = spark.sql("""
  SELECT
    gbx_bng_pointascell(concat('POINT(', cast(longitude as string), ' ', cast(latitude as string), ')'), 1000) as bng_cell,
    COUNT(*) as point_count,
    AVG(value) as avg_value
  FROM measurements
  WHERE country = 'GB'
  GROUP BY bng_cell
""")

aggregated.write.mode("overwrite").saveAsTable("bng_aggregated")
Example output
+----------+-----------+-----------+
|bng_cell  |point_count|avg_value  |
+----------+-----------+-----------+
|TQ 30 80  |150        |42.5       |
|TQ 31 80  |89         |38.2       |
|...       |...        |...        |
+----------+-----------+-----------+

Table bng_aggregated written to Delta.

VectorX Functions​

Complete Example​

Databricks Runtime integration

This example uses st_geomfromwkb, st_isvalid, and st_area and requires Databricks Runtime 17.1+ (or Databricks SQL with ST support). The snippet and integration tests live under docs/tests-dbr/ (Scala snippet in scala/api/; Python integration tests in python/api/).

VectorX Complete Example
import com.databricks.labs.gbx.vectorx.jts.legacy.{functions => vx}
import org.apache.spark.sql.functions._

// Register functions
vx.register(spark)

// Full migration workflow
val legacyTable = spark.table("legacy_mosaic_geometries")

// Convert and validate
val migrated = legacyTable
  .select(
    col("*"),
    expr("st_geomfromwkb(gbx_st_legacyaswkb(mosaic_geom))").alias("geometry")
  )
  .select(
    col("feature_id"),
    col("properties"),
    col("geometry"),
    expr("st_isvalid(geometry)").alias("is_valid"),
    expr("st_area(geometry)").alias("area")
  )
  .filter(col("is_valid") === true)

// Save to Delta
migrated.write.mode("overwrite").saveAsTable("migrated_features")
Example output
+----------+-----------+----------+---------+------+
|feature_id|properties |geometry  |is_valid  |area |
+----------+-----------+----------+---------+------+
|1         |{...}      |POLYGON...|true     |1250.5|
|2         |{...}      |POLYGON...|true     |890.2 |
|...       |...        |...       |...      |...   |
+----------+-----------+----------+---------+------+

Table migrated_features written to Delta.

Next Steps​