適用於：
執行時間 18 LTS 及以上
Note
Databricks Runtime 18 比 Databricks Runtime 18.0、18.1 和 18.2 更新。 原本會以後期編號版本推出的功能，現在改為以 Databricks Runtime 18 的更新形式提供。 詳情請參見 關於統一發布說明。
重要
這項功能目前處於 公開預覽版。
回傳一個保證位於輸入 幾何 值上或其內的點。
關於對應的 Databricks SQL 函式，請參見 st_pointonsurface 函數。
Syntax
from pyspark.databricks.sql import functions as dbf
dbf.st_pointonsurface(col=<col>)
Parameters
| 參數 | 類型 | 描述 |
|---|---|---|
col |
pyspark.sql.Column 或 str |
幾何的值。 |
Returns
pyspark.sql.Column：一列二維點 幾何 值，每個點都保證位於對應輸入幾何體上或其內。 更準確地說：
- 若輸入幾何體為空，則回傳二維空點。
- 若輸入幾何體為非空點，則返回該點的二維投影。
- 若輸入幾何體為非空線條，則回傳中位頂點。
- 若輸入幾何體為非空多邊形，則盡可能回傳多邊形內部的點;否則為其邊界上的一點。
- 若輸入幾何為多點，則返回最接近包圍盒中心的非空點。
- 若輸入幾何為多線串，則回傳線條曲面上長度最大的一點。
- 若輸入幾何為多邊形，則回傳多邊形表面面積最大的一點。
- 若輸入幾何為幾何集合，則返回集合中最大維元素之一曲面上的一點。
回傳幾何體的 SRID 與輸入幾何體相同。
如果輸入為 None，則函式會傳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)')]