projection

AMD: require(["esri/geometry/projection"], (projection) => { /* code goes here */ });
ESM: import * as projection from "@arcgis/core/geometry/projection.js";
Object: esri/geometry/projection
Since: ArcGIS Maps SDK for JavaScript 4.7

A client-side projection engine for converting geometries from one SpatialReference to another. When projecting geometries the starting spatial reference must be specified on the input geometry. You can specify a specific geographic (datum) transformation for the project operation, or accept the default transformation if one is needed.

Known Limitations

Method Overview

Name Return Type Summary Object

Returns the default geographic transformation used to convert the geometry from the input spatial reference to the output spatial reference.

projection

Returns a list of all geographic transformations suitable to convert geometries from the input spatial reference to the specified output spatial reference.

projection

Indicates if all dependencies of this module have been loaded.

projection
Promise

Loads this module's dependencies.

projection

Projects a geometry or an array of geometries to the specified output spatial reference.

projection

Method Details

getTransformation

Method
getTransformation(inSpatialReference, outSpatialReference, extent){GeographicTransformation}

Returns the default geographic transformation used to convert the geometry from the input spatial reference to the output spatial reference. The default transformation is used when projecting geometries where the datum transformation is required but not specified in the geographicTransformation parameter.

Known Limitations

  • This method returns equation-based geographic transformations only.
  • Geographic transformations are returned with their maximum number of steps. Currently, number of steps is limited to 2.
Parameters
inSpatialReference SpatialReference autocast
Autocasts from Object

The input spatial reference from which to project geometries. This is the spatial reference of the input geometries.

outSpatialReference SpatialReference autocast
Autocasts from Object

The spatial reference to which you are converting the geometries.

extent Extent
optional

An extent used to determine the suitability of the returned transformation. The extent will be re-projected to the inSpatialReference if it has a different spatial reference.

Returns
Type Description
GeographicTransformation Returns the default geographic transformation for the given parameters. If no transformation is required or there are no suitable transformations, then null is returned.

getTransformations

Method
getTransformations(inSpatialReference, outSpatialReference, extent){GeographicTransformation[]}

Returns a list of all 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.

Known Limitations

  • This method returns all the suitable equation-based geographic transformations.
  • Geographic transformations are returned with their maximum number of steps. Currently, number of steps is limited to 2.
Parameters
inSpatialReference SpatialReference autocast
Autocasts from Object

The spatial reference that the geometries are currently using.

outSpatialReference SpatialReference autocast
Autocasts from Object

The spatial reference to which you are converting the geometries to.

extent Extent
optional

An extent used to determine the suitability of the returned transformations. The extent will be re-projected to the input spatial reference if necessary.

Returns
Type Description
GeographicTransformation[] 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.
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
});

const geogtrans = projection.getTransformations(cs1, cs2, extent);
geogtrans.forEach(function(geogtran, index) {
  geogtran.steps.forEach(function(step, index) {
    console.log("step wkid: ", step.wkid);
  });
});

isLoaded

Method
isLoaded(){Boolean}

Indicates if all dependencies of this module have been loaded.

Returns
Type Description
Boolean Returns true if this module's dependencies have been loaded.

load

Method
load(){Promise}

Loads this module's dependencies. This method must be called before projecting geometries.

Returns
Type Description
Promise Resolves when the dependencies have been loaded.
See also
Example
projection.load().then(function() {
  // the projection module is loaded. Geometries can be re-projected.

 // projects each polygon in the array
 // project() will use the spatial reference of the first geometry in the array
 // as an input spatial reference. It will use the default transformation
 // if one is required when converting from input spatial reference
 // to the output spatial reference
 let outSpatialReference = new SpatialReference({
   wkid: 53008 //Sphere_Sinusoidal projection
 });
 polygonGraphics.forEach(function(graphic) {
   graphic.geometry = projection.project(graphic.geometry, outSpatialReference);
 });
});

project

Method
project(geometry, outSpatialReference, geographicTransformation){Geometry |Geometry[]}

Projects a geometry or an array of geometries to the specified output spatial reference. A default geographic transformation is used if not explicitly provided, but required. Use the getTransformation() method to find out which transformation is used by default for the given input and output spatial references.

Note that you must load this module before attempting to project geometries.

Known Limitations

This method uses the spatial reference of the first geometry as an input spatial reference. Therefore all geometries in the array must have the same spatial reference.

Parameters
geometry Geometry|Geometry[]

The geometry or geometries to project.

outSpatialReference SpatialReference autocast
Autocasts from Object

The spatial reference to which you are converting the geometries' coordinates.

geographicTransformation GeographicTransformation
optional

The geographic transformation used to transform the geometries. Specify this parameter to project a geometry when the default transformation is not appropriate for your requirements.

Returns
Type Description
Geometry | Geometry[] The result will be an array if an array of geometries is used as input. It will be a single geometry if a single geometry used as input.
Examples
// projects each polygon in the array
// project() will use the spatial reference of the first geometry in the array
// as an input spatial reference. It will use the default transformation
// if one is required when converting from input spatial reference
// to the output spatial reference
let outSpatialReference = new SpatialReference({
  wkid: 53008 //Sphere_Sinusoidal projection
});
polygonGraphics.forEach(function(graphic) {
  graphic.geometry = projection.project(graphic.geometry, outSpatialReference);
});
let outSpatialReference = {
  wkid: 54044
};
// projects an array of points
let projectedPoints = projection.project(wgsPoints, outSpatialReference);
projectedPoints.forEach(function(point) {
  console.log(point.x, point.y);
});

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.