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_LocateBetween 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-valueTwo query m-values (start/end)
Returns geometry columnST_LocatePointAlongST_LocateLineBetween
Returns array columnST_LocateAlongST_LocateBetween
FunctionSyntax
Pythonlocate_line_between(linestring, start_measure, end_measure, offset = 0)
SQLST_LocateLineBetween(linestring, start_measure, end_measure, offset = 0)
ScalalocateLineBetween(linestring, startMeasure, endMeasure, offset)

For more details, go to the GeoAnalytics Engine API reference for locate_line_between.

Examples

PythonPythonSQLScala
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10

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)
Result
Use dark colors for code blocksCopy
1
2
3
4
5
+----------------------------------------------------------+
|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

ReleaseNotes

2.2.0

Python, SQL, and Scala functions introduced

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.