ST_SplitAtPoints

Table of Contents

1. What is ST_SplitAtPoints

2. ST_SplitAtPoints Input Data

3. Using ST_SplitAtPoints

import bdt
bdt.auth("../bdt.lic")
import bdt.functions as F
from pyspark.sql.functions import explode

BDT has been successfully authorized!

            Welcome to
             ___    _                ___         __             ______             __   __     _   __
            / _ )  (_)  ___ _       / _ \ ___ _ / /_ ___ _     /_  __/ ___  ___   / /  / /__  (_) / /_
           / _  | / /  / _ `/      / // // _ `// __// _ `/      / /   / _ \/ _ \ / /  /  '_/ / / / __/
          /____/ /_/   \_, /      /____/ \_,_/ \__/ \_,_/      /_/    \___/\___//_/  /_/\_\ /_/  \__/
                      /___/

BDT python version: v3.4.0-53-processing-2024-36-gfc7a7d00
BDT jar version: v3.4.0-53-processing-2024-36-gfc7a7d00

Part 1: What is ST_SplitAtPoints

ST_SplitAtPoints is a function that splits a given polyline into pieces defined by a multipoint.

The function will snap each point in the multipoint to the closest point on the polyline. It will then split the polyline into pieces at each of these snapped points.

A tolerance parameter, tol is required. tol is the maximum distance a point can be away from the polyline to snap to it. If a point in the multipoint is outside of this tolerance distance, the point will not be snapped, and the polyline will not be split for this point. The tolerance is given in units of the spatial reference of the polyline and multipoint.

Part 2: ST_SplitAtPoints Input Data

The two input geometries must be a polyline and a multipoint. These must be in the same spatial reference.

polyline_wkt = "LINESTRING (0 0, 5 0)"
multipoint_wkt = "MULTIPOINT (2.5 2, 3.5 -2, 4 4)"

df = spark.sql(f"""
    SELECT
        ST_FromText('{polyline_wkt}') AS polyline_shape,
        ST_FromText('{multipoint_wkt}') AS multipoint_shape
    """)

df.show()

+--------------------+--------------------+
|      polyline_shape|    multipoint_shape|
+--------------------+--------------------+
|{[01 05 00 00 00 ...|{[01 04 00 00 00 ...|
+--------------------+--------------------+

Part 3: Using ST_SplitAtPoints

ST_SplitAtPoints returns an array polylines that resulted from the split. Call explode on this output to put each line into its own row.

split_df = (
    df.select(
        explode(F.st_split_at_points("polyline_shape", "multipoint_shape", tol=3.0, wkid=4326)).alias("split_line")
    )
)
split_df.show()

+--------------------+
|          split_line|
+--------------------+
|{[01 05 00 00 00 ...|
|{[01 05 00 00 00 ...|
|{[01 05 00 00 00 ...|
+--------------------+

Converting the output geometries to WKT to see what splits were created.

split_df.select(
    F.st_asText("split_line").alias("split_line_wkt")
).show(truncate=False)

+--------------------------------+
|split_line_wkt                  |
+--------------------------------+
|MULTILINESTRING ((0 0, 2.5 0))  |
|MULTILINESTRING ((2.5 0, 3.5 0))|
|MULTILINESTRING ((3.5 0, 5 0))  |
+--------------------------------+