@arcgis/core/geometry/operators/support/geographicTransformationUtils.d.ts

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

/**
 * A set of utilities for working with geographic transformations.
 *
 * > [!WARNING]
 * >
 * > **Notes**
 * >
 * > Verify that `isLoaded()` returns `true` before using this module.
 * > Use `load()` to load this module's dependencies.
 *
 * @since 4.32
 */
import type Extent from "../../Extent.js";
import type SpatialReference from "../../SpatialReference.js";
import type GeographicTransformation from "./GeographicTransformation.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/support/geographicTransformationUtils/#isLoaded)
 */
export function load(): Promise<void>;

/**
 * Returns the default equation-based, geographic transformation used to convert a geometry
 * from the input spatial reference to the output spatial reference.
 * The default transformation is used when projecting geometries using the [projectOperator](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/projectOperator/)
 * where the datum transformation is required but not specified in the operator's `geographicTransformation` parameter.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > This method returns only equation-based geographic transformations.
 * > Geographic transformations are returned with their maximum number of [GeographicTransformation.steps](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/support/GeographicTransformation/#steps).
 * > Currently, the number of steps is limited to 2.
 *
 * @param inSpatialReference - The input spatial reference from which to project geometries.
 *   This is the spatial reference of the input geometries.
 * @param outSpatialReference - The spatial reference to which you are converting the geometries.
 * @param areaOfInterestExtent - An extent used to determine the suitability of the returned transformation.
 * The extent's spatial reference should be the same as `inSpatialReference`.
 * @returns Returns the default geographic transformation for the given parameters.
 * If no transformation is required or there are no suitable transformations, then `null` is returned.
 * @example
 * const cs1 = new SpatialReference({
 *   wkid: 4272 //PE_GCS_ED_1950
 * });
 *
 * const cs2 = new SpatialReference({
 *   wkid: 4167
 * });
 *
 * const extent = new Extent({
 *   xmin: -186.0,
 *   ymin: -42.0,
 *   xmax: -179.0,
 *   ymax: -38.0,
 *   spatialReference: cs1
 * });
 *
 * if (!geographicTransformationUtils.isLoaded()) {
 *   await geographicTransformationUtils.load();
 * }
 *
 * const geogtrans = projection.getTransformation(cs1, cs2, extent);
 */
export function getTransformation(inSpatialReference: SpatialReference, outSpatialReference: SpatialReference, areaOfInterestExtent?: Extent | null): GeographicTransformation | null | undefined;

/**
 * Returns a list of all equation-based, geographic transformations suitable to convert geometries from the input spatial reference
 * to the specified output spatial reference. The list is ordered in descending order by suitability, with the
 * most suitable being first in the list.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > This method returns only equation-based geographic transformations.
 * > Geographic transformations are returned with their maximum number of [GeographicTransformation.steps](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/support/GeographicTransformation/#steps).
 * >   Currently, number of steps is limited to 2.
 *
 * @param inSpatialReference - The spatial reference that the geometries are currently using.
 * @param outSpatialReference - The spatial reference to which you are converting the geometries to.
 * @param areaOfInterestExtent - An extent used to help pick the correct transform.
 * The extent's spatial reference should be the same as `inSpatialReference`.
 * @returns Returns an array containing the maximum number the suitable
 * geographic transformations that can be used to convert geometries between input and output spatial references.
 * The list will be empty if the provided extent lies out of the area of use for the input spatial reference, or if no transformation is required, or there are no suitable transformations.
 * @example
 * const cs1 = new SpatialReference({
 *   wkid: 4272 //PE_GCS_ED_1950
 * });
 *
 * const cs2 = new SpatialReference({
 *   wkid: 4167
 * });
 *
 * const extent = new Extent({
 *   xmin: -186.0,
 *   ymin: -42.0,
 *   xmax: -179.0,
 *   ymax: -38.0,
 *   spatialReference: cs1
 * });
 *
 * if (!geographicTransformationUtils.isLoaded()) {
 *   await geographicTransformationUtils.load();
 * }
 *
 * const geogtrans = projection.getTransformations(cs1, cs2, extent);
 * geogtrans.forEach((geogtran, index) => {
 *   geogtran.steps.forEach((step, index) => {
 *     console.log("step wkid: ", step.wkid);
 *   });
 * });
 */
export function getTransformations(inSpatialReference: SpatialReference, outSpatialReference: SpatialReference, areaOfInterestExtent?: Extent | null): GeographicTransformation[];