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

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

/**
 * Projects geometries (with or without Z/elevation data) from one [SpatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/SpatialReference/) to another.
 * You can specify a geographic (datum) transformation for this operation, accept the default transformation if one is needed, or set the area of interest.
 *
 * Projecting your data between coordinate systems sometimes requires transforming
 * between geographic coordinate systems. Geographic transformations are used
 * to transform coordinates between spatial references that have different geographic
 * coordinate systems, and thus different datums.
 * Using the most suitable transformation ensures the best possible accuracy when
 * converting geometries from one spatial reference to another.
 *
 * The [geographicTransformationUtils](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/support/geographicTransformationUtils/) module provides methods which
 * return the default geographic transformation for the given projection or a list of suitable geographic
 * transformations.
 *
 * The operator supports limited Z value conversion when the units of the spatial references are different
 * (for example when projecting from NAD83 to WGS84). Full vertical coordinate projection is not available and the
 * operator will throw an exception if the input and output have different vertical coordinate systems.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > This operator currently only supports [equation-based geographic transformations](https://pro.arcgis.com/en/pro-app/latest/help/mapping/properties/geographic-coordinate-system-transformation.htm).
 * > The result geometry is not guaranteed to be simple. Apply the [simplifyOperator](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/simplifyOperator/) to ensure the result is topologically simple.
 * > Projecting an Extent may return an Extent with a larger area than the input.
 * > Vertical coordinate system projections are not supported.
 *
 * > [!WARNING]
 * >
 * > **Notes**
 * >
 * > Verify that `isLoaded()` returns `true` before using this module.
 * > Use `load()` to load this module's dependencies.
 *
 * @since 4.32
 * @see [Spatial References](https://developers.arcgis.com/documentation/spatial-references/)
 * @see [Coordinate systems, map projections, and transformations](https://pro.arcgis.com/en/pro-app/latest/help/mapping/properties/coordinate-systems-and-projections.htm)
 * @see [Geographic datum transformations](https://pro.arcgis.com/en/pro-app/latest/help/mapping/properties/geographic-coordinate-system-transformation.htm)
 * @see [Sample - Client-side projection](https://developers.arcgis.com/javascript/latest/sample-code/client-projection/)
 */
import type SpatialReference from "../SpatialReference.js";
import type { GeometryUnion, GeometryWithoutMeshUnion } from "../types.js";
import type { ProjectOptions } from "./types.js";

/**
 * 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/projectOperator/#isLoaded)
 */
export function load(): Promise<void>;

/**
 * Projects a geometry to the specified output spatial reference.
 *
 * @param geometry - The geometry to project.
 * @param outSpatialReference - The spatial reference to which the input geometry is projected.
 * @param options - Additional options.
 * @returns Returns the projected geometry or null.
 * @example
 * if (!projectOperator.isLoaded()) {
 *   await projectOperator.load();
 * }
 *
 * const outSpatialReference = new SpatialReference({
 *   wkid: 53008 //Sphere_Sinusoidal projection
 * });
 *
 * // Project a geometry to a different spatial reference
 * const geometry = projectOperator.execute(polygon, outSpatialReference);
 */
export function execute(geometry: GeometryUnion, outSpatialReference: SpatialReference, options?: ProjectOptions): GeometryWithoutMeshUnion | null | undefined;

/**
 * Projects an array of geometries to the specified output spatial reference.
 *
 * @param geometries - An array of geometries to project.
 * All the geometries must have the same spatial reference.
 * @param outSpatialReference - The spatial reference to which the input geometry is projected.
 * @param options - Additional options.
 * @returns Returns the projected geometries or null.
 */
export function executeMany(geometries: GeometryUnion[], outSpatialReference: SpatialReference, options?: ProjectOptions): (GeometryWithoutMeshUnion | null | undefined)[];

/**
 * 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`.
 * This will produce densified output geometries.
 */
export const supportsCurves: boolean | null | undefined;