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

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

/**
 * Find the closest vertices of the 2D geometry.
 *
 * ![Proximity operator](https://developers.arcgis.com/javascript/latest/assets/references/core/operators/proximity.png "Proximity operator")
 *
 * @since 4.31
 * @see ![Sample - Geometry operator - proximity analysis](https://developers.arcgis.com/javascript/latest/sample-code/geometry-operator-proximity/)
 */
import type Point from "../Point.js";
import type { LengthUnit } from "../../core/units.js";
import type { GeometryUnion } from "../types.js";
import type { ProximityResult } from "./types.js";

export interface Options {
  /**
   * The length unit of the search radius and result distances.
   * The default is the input geometry's spatial reference unit.
   * An error will be thrown if this is set for Geographic Coordinate Systems.
   */
  unit?: LengthUnit;
}

export interface GetNearestCoordinateOptions extends Options {
  /**
   * When the parameter is set to true, this function will calculate the left/right side of a polyline or polygon.
   * Look for the result in the `isRightSide` property of the returned `ProximityResult` object.
   *
   * @default false
   */
  calculateLeftRightSide?: boolean;
  /**
   * When `geometry` is a polygon, the function will test if `point` is inside of the polygon.
   * Points that are inside of the polygon have zero distance to the polygon.
   * When set to false, the function will not check if the point is inside of the polygon, but will only determine proximity to the boundary.
   *
   * @default true
   */
  testPolygonInterior?: boolean;
}

/**
 * Returns the nearest coordinate on the geometry to the given input point.
 *
 * @param geometry - The input geometry.
 * @param point - The point used to search for the nearest coordinate in `geometry`.
 * @param options - Additional options.
 * @returns Returns the proximity result which contains the nearest coordinate on the input `geometry` to the given `inputPoint`.
 * @example
 * // Return the nearest result on a polygon to the given point
 * const proximityResult = proximityOperator.getNearestCoordinate(polygon, point);
 */
export function getNearestCoordinate(geometry: GeometryUnion, point: Point, options?: GetNearestCoordinateOptions): ProximityResult;

/**
 * Returns the nearest vertex on the geometry.
 *
 * @param geometry - The input geometry.
 * @param point - The point used to search for the nearest coordinate in the input `geometry`.
 * @param options - Additional options.
 * @returns Returns the proximity result which contains the nearest vertex on the `geometry` to the given `inputPoint`.
 * @example
 * // Return the nearest vertex on a polygon to the given point
 * const proximityResult = proximityOperator.getNearestVertex(polygon, point);
 */
export function getNearestVertex(geometry: GeometryUnion, point: Point, options?: Options): ProximityResult;

/**
 * Returns vertices of the geometry that are closer to the given point than the given radius.
 *
 * @param geometry - The input geometry.
 * @param point - The point used to search for the nearest coordinate in `geometry`.
 * @param searchRadius - The planar distance from the `inputPoint` to search for vertices.
 * Unless the `unit` option is set, the default is the geometry's spatial reference unit.
 * @param maxVertexCountToReturn - The maximum number of vertices that will be returned. Must be a positive number.
 * @param options - Additional options.
 * @returns Returns an array of proximity results which contain the nearest vertices on `geometry` to the given `inputPoint` that are less than or equal to the planar distance of search radius.
 * The array is sorted by distance to the `inputPoint` with the closest point first.
 * When there are more than the `maxVertexCountToReturn` vertices to return, it returns the closest vertices.
 * The array will be empty when `geometry` is empty.
 * @example
 * // Return the nearest vertices on a polygon to the given point
 * const proximityResultsArray = proximityOperator.getNearestVertices(polygon, point, 100, 5);
 */
export function getNearestVertices(geometry: GeometryUnion, point: Point, searchRadius: number, maxVertexCountToReturn: number, options?: Options): ProximityResult[];

/**
 * Indicates if the operator supports input geometries that contain curves.
 * The value will always be `true`.
 */
export const supportsCurves: boolean;