Edit

Share via

geo_line_locate_point()

  • Article

Applies to: ✅ Microsoft Fabric ✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel

Calculates fraction value as a ratio of a line length from line start till a point on a line which is closest to a given point and a whole line length on Earth.

Syntax

geo_line_locate_point(lineString, longitude,latitude,[ use_spheroid ])

Learn more about syntax conventions.

Parameters

Name Type Required Description
lineString dynamic ✔️ A line in the GeoJSON format.
longitude real ✔️ The geospatial coordinate longitude value in degrees. A valid value is in the range [-180, +180].
latitude real ✔️ The geospatial coordinate latitude value in degrees. A valid value is in the range [-90, +90].
use_spheroid bool If false will use a sphere as geodetic datum for measuring distance. If true will measure distance using spheroid. If unspecified, the default value false is used.

Returns

Line fraction value between 0 and 1 (0 - 100%) as a ratio of a line from start till a point on a line which is closest to a given point and a whole line on Earth. If the line or coordinate value is invalid, the query produces a null result.

Note

  • The geospatial coordinates are interpreted as represented by the WGS-84 coordinate reference system.
  • Line segments are geodesics on the sphere, if 'use_spheroid' = false. If 'use_spheroid' = true, line segments will be geodesics on spheroid. Most applications should measure distance using sphere which is more performant
  • If input line edges are straight cartesian lines, consider using geo_line_densify() in order to convert planar edges to geodesics.
  • The input shouldn't contain more than a single line string.
  • If the input line string has more than single point on the line at equal distances from the input point, it isn't guaranteed which one is selected.
  • In order to calculate a point at fraction on a line use geo_line_interpolate_point()

LineString definition and constraints

dynamic({"type": "LineString","coordinates": [[lng_1,lat_1], [lng_2,lat_2], ..., [lng_N,lat_N]]})

  • LineString coordinates array must contain at least two entries.
  • Coordinates [longitude, latitude] must be valid where longitude is a real number in the range [-180, +180] and latitude is a real number in the range [-90, +90].
  • Edge length must be less than 180 degrees. The shortest edge between the two vertices is chosen.

Examples

The following example calculates a fraction value.

Run the query

let line = dynamic({"type":"LineString","coordinates":[[-73.95796, 40.80042], [-73.97317, 40.764486]]});
print fraction = geo_line_locate_point(line, -73.965, 40.792);

Output

fraction
0.25560135100307552

The following example returns true because of the invalid line.

Run the query

print is_bad_line = isnull(geo_line_locate_point(dynamic({"type":"LineString","coordinates":[[1, 1]]}), 1, 1))

Output

is_bad_line
true