TRK_DistanceAlong

TRK_DistanceAlong takes a track column and a point column and returns a float column. The float column contains the distance along the track between the track start and where the point intersects the track.

The result is returned in the units specified by output_unit. When output_unit is None, the result is in the units of the input track's spatial reference if it's projected; otherwise, the result is in meters.

If the input track and point do not have the same spatial reference, the point will be transformed to the spatial reference of the track.

You can optionally specify a max_deviation which is the maximum distance a point can be from the track while still being considered on the track. The value is in the units of the track's spatial reference. The default is 0 which means the point must intersect the track or else the function will return null. For example, if max_deviation were set to 10 for tracks in Web Mercator (3857), points within 10 meters of the track are considered on the track and the closest location to the point on the track is used to calculate the distance along.

Tracks are linestrings that represent the change in an entity's location over time. Each vertex in the linestring has a timestamp (stored as the M-value) and the vertices are ordered sequentially.

For more information on using tracks in GeoAnalytics Engine, see the core concept topic on tracks.

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

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from geoanalytics.sql import functions as ST
from geoanalytics.tracks import functions as TRK
from pyspark.sql import functions as F

data = [
    ("LINESTRING M (-117.27 34.05 1633455010, -117.22 33.91 1633456062, -116.96 33.64 1633457132)",
     "POINT (-117.2267 33.929)"),
    ("LINESTRING M (-116.89 33.96 1633575895, -116.71 34.01 1633576982, -116.66 34.08 1633577061)",
     "POINT (-116.8338 33.9756)"),
    ("LINESTRING M (-116.24 33.88 1633575234, -116.33 34.02 1633576336)",
     "POINT (-116.24 33.88)")
]

df = spark.createDataFrame(data, ["track_wkt","point_wkt"]) \
          .withColumn("track", ST.line_from_text("track_wkt", srid=4326)) \
          .withColumn("point", ST.point_from_text("point_wkt", srid=4326)) \
          .withColumn("distance_along", TRK.distance_along("track", "point", max_deviation=10, output_unit="miles"))

df.select(F.round("distance_along", 3).alias("distance_along")).show()

1
2
3
4
5
6
7
+--------------+
|distance_along|
+--------------+
|         8.702|
|         3.402|
|           0.0|
+--------------+

Version table

Related topics

• TRK_Aggr_CreateTrack
• TRK_DurationAlong
• TRK_Query
• TRK_Length