geodesicUtils

AMD: require(["esri/geometry/support/geodesicUtils"], (geodesicUtils) => { /* code goes here */ });
ESM: import * as geodesicUtils from "@arcgis/core/geometry/support/geodesicUtils";
Object: esri/geometry/support/geodesicUtils
Since: ArcGIS API 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[]more details

Geodetically computes the area for one or more polygons.

more detailsgeodesicUtils
Polyline|Polygonmore details

Computes and returns a densified polyline or polygon.

more detailsgeodesicUtils
GeodesicDistanceResultmore details

Geodetically computes the direction and distance between two known locations.

more detailsgeodesicUtils
Number[]more details

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

more detailsgeodesicUtils
Pointmore details

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

more detailsgeodesicUtils

Method Details

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(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(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(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(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

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.