ST_SnapToLine

Table of Contents

1. What is ST_SnapToLine?

2. Using ST_SnapToLine

Part 1: What is ST_SnapToLine?

ST_SnapToLine is a function that snaps a given point to the closest point on a given line. The function will return the newly snapped point geometry in addition to providing several metrics about the snap. These metrics include:

1. DIST_ON_LINE

2. DIST_TO_LINE

3. SNAP_SIDE

4. HEADING_ALIGN

5. SNAP_LINE_ALIGN

Because calculating these metrics can be expensive, it is recommended to use ST_Snap if only the snapped point geometry is needed without the metrics.

DIST_ON_LINE

DIST_ON_LINE is the distance from the start of the line segment to the snapped point.

DIST_TO_LINE

DIST_TO_LINE is the distance from the input point to the snapped point.

SNAP_SIDE

The SNAP_SIDE is the side of the line the point was snapped to (‘L’ for left, ‘R’ for right, and ‘O’ for on the line).

HEADING_ALIGN

HEADING_ALIGN is an alignment factor between the individual segment of the line the point is snapped to and the heading of the point. The point heading is provided as a parameter to ST_SnapToLine. This alignment factor measures the similarity of the angle of the line segment and the angle of the point heading. The alignment factor will always fall between -1.0 and 1.0 with 1.0 meaning the segment and the point heading are pointing in the same direction and -1.0 meaning they are pointing in opposite directions.

SNAP_LINE_ALIGN

SNAP_LINE_ALIGN functions similarly to HEADING_ALIGN except the similarity is instead being measured between the angle of the segment of the input line the point was snapped to and the angle of the “snap line”. The snap line is the line formed by connecting the snapped point to the original input point. This snap line can also be thought of as the path the input point travels when it is snapped to the line.

Part 2: Using ST_SnapToLine

import bdt
import math
bdt.auth("bdt.lic")
from bdt import functions as F
from pyspark.sql.functions import col

BDT has been successfully authorized!

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

BDT python version: v3.3.0-v3.3.0
BDT jar version: v3.3.0-v3.3.0

Gather input point, line, and heading values.

point_wkt = "POINT (3.0 2.0)"
line_wkt = "LINESTRING (0.0 0.0, 5.0 0.0, 10.0 0.0)"
point_heading = math.pi # 180 degrees in radians

df = spark.sql(f"""
    SELECT
        ST_FromText('{point_wkt}') AS POINT,
        ST_FromText('{line_wkt}') AS LINE,
        CAST({point_heading} AS DOUBLE) AS POINT_HEADING
    """)

df.show()

+--------------------+--------------------+-----------------+
|               POINT|                LINE|    POINT_HEADING|
+--------------------+--------------------+-----------------+
|{[01 01 00 00 00 ...|{[01 05 00 00 00 ...|3.141592653589793|
+--------------------+--------------------+-----------------+

Call ST_SnapToLine. Expand the returned struct with .*

snap_df = (
    df.select(
        F.st_snapToLine(col("POINT"), col("LINE"), col("POINT_HEADING")).alias("SNAP_RESULT")
    ).select("SNAP_RESULT.*")
)

snap_df.show(truncate=False)

+--------------------------------------------------------------------------------------+------------+------------+---------+-------------+---------------+
|SHAPE                                                                                 |DIST_ON_LINE|DIST_TO_LINE|SNAP_SIDE|HEADING_ALIGN|SNAP_LINE_ALIGN|
+--------------------------------------------------------------------------------------+------------+------------+---------+-------------+---------------+
|{[01 01 00 00 00 00 00 00 00 00 00 08 40 00 00 00 00 00 00 00 00], 3.0, 0.0, 3.0, 0.0}|3.0         |2.0         |L        |-1.0         |0.0            |
+--------------------------------------------------------------------------------------+------------+------------+---------+-------------+---------------+