geodesicUtils

AMD: require(["esri/geometry/support/geodesicUtils"], (geodesicUtils) => { /* code goes here */ });
ESM: import * as geodesicUtils from "@arcgis/core/geometry/support/geodesicUtils.js";
Object: esri/geometry/support/geodesicUtils
Since: ArcGIS Maps SDK for JavaScript 4.12

This class performs geodetic computations for Earth and 70+ non-Earth spheroids. Methods include geodesic length, area, point-distance and point-to-point computations.

Method Overview

Name Return Type Summary Object
Number[]

Geodetically computes the area for one or more polygons.

geodesicUtils
Polyline|Polygon

Computes and returns a densified polyline or polygon.

geodesicUtils
GeodesicDistanceResult

Geodetically computes the direction and distance between two known locations.

geodesicUtils
Number[]

Geodetically computes polygon perimeter or polyline length for one or more geometries.

geodesicUtils
Point

Geodetically computes the location at a defined distance and direction from a known location.

geodesicUtils

Method Details

geodesicAreas

Method
geodesicAreas(polygons, unit){Number[]}static

Geodetically computes the area for one or more polygons.

Parameters
polygons Polygon[]

The polygons to compute the area for.

unit String
optional
Default Value: "square-meters"

Output area units.

Possible Values:"square-millimeters"|"square-centimeters"|"square-decimeters"|"square-meters"|"square-kilometers"|"square-inches"|"square-feet"|"square-yards"|"square-miles"|"square-us-feet"|"acres"|"ares"|"hectares"

Returns
Type Description
Number[] An array of areas corresponding to the source polygons.
Example
// Display the area of the Bermuda Triangle.
const MIAMI    = { lat: 25.775278, lon: -80.208889 };  // Florida
const HAMILTON = { lat: 32.293, lon: -64.782 };        // Bermuda
const SANJUAN  = { lat: 18.406389, lon:  -66.063889 }; // Puerto Rico
const polygon = new Polygon({
  rings: [[
    [MIAMI.lon, MIAMI.lat],
    [HAMILTON.lon, HAMILTON.lat],
    [SANJUAN.lon, SANJUAN.lat],
    [MIAMI.lon, MIAMI.lat]
  ]]
});
const areas = geodesicUtils.geodesicAreas([polygon], "square-kilometers");
const area = Math.round(areas[0]);
console.log("Area: ", area, " km²"); // Area: 1150498 km²

geodesicDensify

Method
geodesicDensify(geometry, maxSegmentLength){Polyline|Polygon}static

Computes and returns a densified polyline or polygon.

Parameters
geometry Polyline|Polygon

The input polyline or polygon.

maxSegmentLength Number

The maximum length (in meters) between vertices.

Returns
Type Description
Polyline | Polygon The densified polyline or polygon.
Example
// Densify the polygon representing Bermuda Triangle with maximum segment size of 100km.
const MIAMI    = { lat: 25.775278, lon: -80.208889 };  // Florida
const HAMILTON = { lat: 32.293, lon: -64.782 };        // Bermuda
const SANJUAN  = { lat: 18.406389, lon:  -66.063889 }; // Puerto Rico
const polygon = new Polygon({
  rings: [[
    [MIAMI.lon, MIAMI.lat],
    [HAMILTON.lon, HAMILTON.lat],
    [SANJUAN.lon, SANJUAN.lat],
    [MIAMI.lon, MIAMI.lat]
  ]]
});
const densifiedPolygon = geodesicUtils.geodesicDensify(polygon, 100000);
const vertexCountBefore = polygon.rings[0].length;
const vertexCountAfter = densifiedPolygon.rings[0].length;
console.log("Before: ", vertexCountBefore, ", After: ", vertexCountAfter); // Before: 4, After: 51

geodesicDistance

Method
geodesicDistance(from, to, unit){GeodesicDistanceResult}static

Geodetically computes the direction and distance between two known locations. Both input points must have the same geographic coordinate system.

Parameters
from Point

The origin location.

to Point

The destination location.

unit String
optional
Default Value: "meters"

Output linear units.

Possible Values:"millimeters"|"centimeters"|"decimeters"|"meters"|"kilometers"|"inches"|"feet"|"yards"|"miles"|"nautical-miles"|"us-feet"

Returns
Type Description
GeodesicDistanceResult Computed distance and direction between the two known locations.
Name Type Description
distance number The distance between the two locations.
azimuth number The azimuth (or "bearing") in degrees. Values range from 0° to 360°.
reverseAzimuth number The reverse azimuth in degrees. Values range from 0° to 360°.
Example
// Display the distance and direction between Los Angeles and New York City.
const LA = {
  latitude: 34.05,
  longitude: -118.25
};
const NY = {
  latitude: 40.7127,
  longitude: -74.0059
};
const join = geodesicUtils.geodesicDistance(
  new Point({ x: LA.longitude, y: LA.latitude }),
  new Point({ x: NY.longitude, y: NY.latitude }),
  "kilometers"
);
const { distance, azimuth } = join;
console.log("Distance: ", distance, ", Direction: ", azimuth);

geodesicLengths

Method
geodesicLengths(geometries, unit){Number[]}static

Geodetically computes polygon perimeter or polyline length for one or more geometries.

Parameters
geometries Polyline[]|Polygon[]

The input polylines or polygons.

unit String
optional
Default Value: "meters"

Output linear units.

Possible Values:"millimeters"|"centimeters"|"decimeters"|"meters"|"kilometers"|"inches"|"feet"|"yards"|"miles"|"nautical-miles"|"us-feet"

Returns
Type Description
Number[] An array of lengths/perimeters corresponding to the input geometries.
Example
// Display the perimeter of the Bermuda Triangle.
const MIAMI    = { lat: 25.775278, lon: -80.208889 };  // Florida
const HAMILTON = { lat: 32.293, lon: -64.782 };        // Bermuda
const SANJUAN  = { lat: 18.406389, lon:  -66.063889 }; // Puerto Rico
const polygon = new Polygon({
  rings: [[
    [MIAMI.lon, MIAMI.lat],
    [HAMILTON.lon, HAMILTON.lat],
    [SANJUAN.lon, SANJUAN.lat],
    [MIAMI.lon, MIAMI.lat]
  ]]
});
const perimeters = geodesicUtils.geodesicLengths([polygon], "kilometers");
const perimeter = Math.round(perimeters[0]);
console.log("Perimeter: ", perimeter, " km"); // Perimeter: 4879 km

pointFromDistance

Method
pointFromDistance(point, distance, azimuth){Point}static

Geodetically computes the location at a defined distance and direction from a known location.

Parameters
point Point

Origin location.

distance Number

Distance from the origin in meters.

azimuth Number

Direction from the origin in degrees.

Returns
Type Description
Point The computed point.
Example
// Display the location of a point 10km East of Los Angeles.
const LA = {
  latitude: 34.05,
  longitude: -118.25
};
const destination = geodesicUtils.pointFromDistance(
  new Point({ x: LA.longitude, y: LA.latitude }),
  10000,
  90
);
const { latitude, longitude } = destination;
console.log("Latitude: ", latitude, ", Longitude: ", longitude);

Type Definitions

GeodesicDistanceResult

Type Definition
GeodesicDistanceResult

Computed distance and direction between two known locations.

Properties
distance Number
optional

The distance between the two locations.

azimuth Number
optional

The azimuth (or "bearing") in degrees. Value will be in the range of 0-360°.

reverseAzimuth Number
optional

The azimuth in degrees in the reverse direction. Value will be in the range of 0-360°.

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