st_pointonsurface

Applies to: Databricks Runtime 18 LTS and above

Important

This feature is in Public Preview.

Returns a point that is guaranteed to lie on or inside the input Geometry value.

For the corresponding Databricks SQL function, see st_pointonsurface function.

Syntax

from pyspark.databricks.sql import functions as dbf

dbf.st_pointonsurface(col=<col>)

Parameters

Parameter	Type	Description
col	pyspark.sql.Column or str	A Geometry value.

Returns

pyspark.sql.Column: A column of 2D point Geometry values, each guaranteed to lie on or inside the corresponding input geometry. More precisely:

• If the input geometry is empty, the 2D empty point is returned.
• If the input geometry is a non-empty point, the 2D projection of the point is returned.
• If the input geometry is a non-empty linestring, the median vertex is returned.
• If the input geometry is a non-empty polygon, a point in the interior of the polygon is returned when possible; otherwise a point on its boundary.
• If the input geometry is a multipoint, the non-empty point closest to the bounding box center is returned.
• If the input geometry is a multilinestring, a point on the surface of the linestring with the largest length is returned.
• If the input geometry is a multipolygon, a point on the surface of the polygon with the largest area is returned.
• If the input geometry is a geometry collection, a point on the surface of one of the maximum-dimensional elements of the collection is returned.

The SRID of the returned geometry is the same as that of the input geometry.

The function returns None if the input is None.

Examples

# Returns a point inside a 2D polygon.
from pyspark.databricks.sql import functions as dbf
df = spark.createDataFrame([('POLYGON((0 0,10 0,10 10,0 10,0 0))',)], ['wkt'])
df.select(dbf.st_asewkt(dbf.st_pointonsurface(dbf.st_geomfromtext('wkt'))).alias('result')).collect()

[Row(result='POINT(5 5)')]

# For a polygon with a hole, the result lies in the donut region.
from pyspark.databricks.sql import functions as dbf
df = spark.createDataFrame([('POLYGON((0 0,30 0,30 30,0 30,0 0),(5 5,25 5,25 25,5 25,5 5))',)], ['wkt'])
df.select(dbf.st_asewkt(dbf.st_pointonsurface(dbf.st_geomfromtext('wkt'))).alias('result')).collect()

[Row(result='POINT(3.75 3.75)')]

# For a 3DZ linestring, the median vertex is returned and the Z coordinate is dropped.
from pyspark.databricks.sql import functions as dbf
df = spark.createDataFrame([('LINESTRING Z (1 2 -1,3 4 -2,5 6 -3)',)], ['wkt'])
df.select(dbf.st_asewkt(dbf.st_pointonsurface(dbf.st_geomfromtext('wkt'))).alias('result')).collect()

[Row(result='POINT(3 4)')]

# For a multipolygon, a point on the polygon with the largest area is returned.
from pyspark.databricks.sql import functions as dbf
df = spark.createDataFrame([('MULTIPOLYGON(((0 0,10 0,10 10,0 10,0 0)),((100 100,101 100,101 101,100 101,100 100)))',)], ['wkt'])
df.select(dbf.st_asewkt(dbf.st_pointonsurface(dbf.st_geomfromtext('wkt'))).alias('result')).collect()

[Row(result='POINT(5 5)')]

# The SRID of the input geometry is preserved.
from pyspark.databricks.sql import functions as dbf
df = spark.createDataFrame([('POLYGON((0 0,10 0,10 10,0 10,0 0))',)], ['wkt'])
df.select(dbf.st_asewkt(dbf.st_pointonsurface(dbf.st_geomfromtext('wkt', 3857))).alias('result')).collect()

[Row(result='SRID=3857;POINT(5 5)')]