ST_LocatePointAlong takes a linestring column, a query m-value, and an optional offset column, and returns a point column. The input linestring must have m-values. The output represents a point located where the query m-value is equal to the input linestring's m-value.
Locations along line segments
are interpolated, so the query m-value does not need to occur at an existing vertex. If multiple locations match,
the function returns the first match in input traversal order, including when m-values are non-monotonic. If the first
match is a segment with a constant m-value, the function returns the first point of that segment. For a valid,
nonempty input linestring with m-values, the function returns an empty point if there are no matches. A positive
offset will return a point shifted to the left of the input line, while a negative offset value
will return a point shifted to the right of the input line. This function differs from ST in that it
returns a single point 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_point_along.
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_point_along", ST.locate_point_along("geometry", 25, 5))
df.select("locate_point_along").show(truncate = False)+----------------------+
|locate_point_along |
+----------------------+
|{"x":30,"y":55,"m":25}|
+----------------------+Here is a visual representation of the code snippet above.
Version table
| Release | Notes |
|---|---|
2.2.0 | Python, SQL, and Scala functions introduced |