@arcgis/core/geometry/operators/geodeticDistanceOperator.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * Calculates the shortest geodetic distance between two 2D geometries.
 *
 * > [!WARNING]
 * >
 * > **Notes**
 * >
 * > Verify that `isLoaded()` returns `true` before using this module.
 * > Use `load()` to load this module's dependencies.
 *
 * ![Geodetic distance operator](https://developers.arcgis.com/javascript/latest/assets/references/core/operators/geodeticDistance.png "Geodetic distance operator")
 *
 * @since 4.31
 * @see [Blog - Geodesic or planar: which to use for distance analysis](https://www.esri.com/arcgis-blog/products/arcgis-pro/analytics/geodesic-or-planar-which-to-use-for-distance-analysis)
 */
import type { LengthUnit } from "../../core/units.js";
import type { GeometryUnion, GeodeticCurveType } from "../types.js";

export interface Options {
  /**
   * The type of geodetic curve used to determine the distance.
   *
   * @default "geodesic"
   */
  curveType?: Exclude<GeodeticCurveType, "shape-preserving">;
  /**
   * The length unit of the distance.
   *
   * @default "meters"
   */
  unit?: LengthUnit;
}

/**
 * Indicates if all dependencies of this module have been loaded.
 *
 * @returns Returns `true` if this module's dependencies have been loaded.
 */
export function isLoaded(): boolean;

/**
 * Loads this module's dependencies. This method must be called first if `isLoaded` returns `false`.
 *
 * @returns Resolves when the dependencies have been loaded.
 * @see [isLoaded()](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/geodeticDistanceOperator/#isLoaded)
 */
export function load(): Promise<void>;

/**
 * Calculates the shortest geodetic distance between two geometries.
 * Unless the `unit` option is set, the default is meters.
 *
 * @param geometry1 - The first input geometry.
 * @param geometry2 - The second input geometry.
 * @param options - Additional options.
 * @returns Returns the distance between the two geometries. Can return NaN for empty geometries.
 * @example
 * if (!geodeticDistanceOperator.isLoaded()) {
 *   await geodeticDistanceOperator.load();
 * }
 *
 * // Calculate the geodetic distance between two geometries
 * const distance = geodeticDistanceOperator.execute(polyline1, polyline2);
 */
export function execute(geometry1: GeometryUnion, geometry2: GeometryUnion, options?: Options): number;

/**
 * Indicates if the operator supports input geometries that contain curves.
 * The value is `null` or `undefined` until the operator is loaded, then it will always be `true`.
 */
export const supportsCurves: boolean | null | undefined;