ST_LocateLineBetween takes a linestring column, a start m-value and end m-value, and an optional offset column, and returns a linestring column. The input linestring must have m-values. The function clips the input to the inclusive range between the start and end m-values, splits the result where m-values reverse direction, and returns the first matching line portion. This applies to non-monotonic m-values as well as ascending or descending m-values. The returned geometry can contain multiple segments and multiple paths. Adjacent paths can be included in the same result when their endpoint m-values match and their m-value directions are compatible.
Locations along line segments are interpolated. Neither query boundary needs to occur at an existing vertex or
within the input's m-value range; an overlapping line portion can still be returned. Point-only intersections are
discarded. For a valid, nonempty input linestring with m-values, the function returns an empty linestring if no
matching segment exists. Providing a start m-value greater than the end m-value will not change the order or direction of the output
linestring. A positive offset value will return a linestring shifted to the left of the input line, while a negative
offset value will return a linestring shifted to the right of the input line. This function differs from
ST in that it returns a single linestring instead of an array of geometries.
Here is a table describing the different locate functions and their primary differences.
| One query m-value | Two query m-values (start/end) | |
|---|---|---|
| Returns geometry column | ST_LocatePointAlong | ST_LocateLineBetween |
| Returns array column | ST_LocateAlong | ST_LocateBetween |
| Function | Syntax |
|---|---|
| Python | locate |
| SQL | ST |
| Scala | locate |
For more details, go to the GeoAnalytics Engine API reference for locate_line_between.
Examples
from geoanalytics.sql import functions as ST
LINE_M_WKT = [('LINESTRING M (10 10 10, 10 50 20, 50 50 30, 50 10 40)',)]
df = spark.createDataFrame(LINE_M_WKT, ["wkt"]) \
.withColumn("geometry", ST.line_from_text("wkt")) \
.withColumn("locate_line_between", ST.locate_line_between("geometry", 15, 25, -5))
df.select("locate_line_between").show(truncate = False)+----------------------------------------------------------+
|locate_line_between |
+----------------------------------------------------------+
|{"hasM":true,"paths":[[[15,30,15],[15,45,20],[30,45,25]]]}|
+----------------------------------------------------------+Here is a visual representation of the code snippet above.
Version table
| Release | Notes |
|---|---|
2.2.0 | Python, SQL, and Scala functions introduced |