Geospatial applications frequently encounter data in various coordinate systems. Effectively managing these spatial references, especially through projection transformations, is crucial for accurate data display and analysis. The ArcGIS JavaScript API provides several methods to handle geometry projections, catering to different scenarios, from common client-side conversions to more complex server-side operations.

Client-Side Web Mercator Transformation

For one of the most common projection needs—converting between geographic coordinates (WGS84, typically EPSG:4326) and Web Mercator (EPSG:3857)—the API offers a convenient utility. The webMercatorUtils.geographicToWebMercator() method is specifically designed for this transformation, performing the calculation direct in the browser.

Here’s an example:

import * as webMercatorUtils from '@arcgis/core/geometry/support/webMercatorUtils';
import Point from '@arcgis/core/geometry/Point';
import SpatialReference from '@arcgis/core/geometry/SpatialReference';

// Assuming an input point in WGS84 (EPSG:4326)
const originalPoint4326 = new Point({
 x: -118.2437,
 y: 34.0522,
 spatialReference: new SpatialReference({ wkid: 4326 })
});

// Perform the client-side conversion to Web Mercator (EPSG:3857)
const projectedPoint3857 = webMercatorUtils.geographicToWebMercator(originalPoint4326);

console.log('Original Point (WGS84):', originalPoint4326.toJSON());
console.log('Projected Point (Web Mercator):', projectedPoint3857.toJSON());

Server-Side Projection for Complex Transfomrations

While client-side utilities are efficient for standard transformations like WGS84 to Web Mercator, not all projection pairs can be handled in the browser. For instance, transforming geometries from custom or less common spatial references, such as EPSG:4490 (China Geodetic Coordinaet System 2000), to EPSG:3857 typically requires server-side processing.

Checking Client-Side Capability

You can use webMercatorUtils.canProject() to determine if a specific transformation can be performed client-side. This is useful before attempting a projection that might fail.

import * as webMercatorUtils from '@arcgis/core/geometry/support/webMercatorUtils';
import SpatialReference from '@arcgis/core/geometry/SpatialReference';

const sourceSR = new SpatialReference({ wkid: 4490 });
const targetSR = new SpatialReference({ wkid: 3857 }); // SpatialReference.WebMercator

const canProjectClientSide = webMercatorUtils.canProject(sourceSR, targetSR);
console.log(`Can project from ${sourceSR.wkid} to ${targetSR.wkid} client-side: ${canProjectClientSide}`); // Expected: false

Leveraging the Geometry Service for Projection

When client-side projection is not feasible, the ArcGIS Geometry Service becomes indispensable. This service, accessed via esri/rest/geometryService, performs complex geometric operations, including projection, on the server.

To use it, you'll define ProjectParameters specifying the input geometries and the desired output spatial reference, then send them to a Geometry Service URL.

import ProjectParameters from '@arcgis/core/rest/support/ProjectParameters';
import * as geometryService from '@arcgis/core/rest/geometryService';
import SpatialReference from '@arcgis/core/geometry/SpatialReference';
import Point from '@arcgis/core/geometry/Point';

// Example point in EPSG:4490 (CGCS2000)
const inputGeometry4490 = new Point({
 x: 116.4074,
 y: 39.9042,
 spatialReference: new SpatialReference({ wkid: 4490 })
});

const projectionRequestParams = new ProjectParameters({
 geometries: [inputGeometry4490],
 outSpatialReference: new SpatialReference({ wkid: 3857 }) // Target: Web Mercator
});

const geometryServiceUrl = 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Utilities/Geometry/GeometryServer';

geometryService.project(geometryServiceUrl, projectionRequestParams)
 .then((projectedGeometries) => {
   // projectedGeometries is an array of transformed geometries
   console.log('Server-projected geometries:', projectedGeometries.map(geom => geom.toJSON()));
 })
 .catch((error) => {
   console.error('Error during server-side projection:', error);
 });

Requesting Projected Data Directly from Feature Services

A common and efficient method to obtain geometries in a desired spatial reference is to request them directly from an ArcGIS Feature Service. When querying a FeatureLayer, you can specify the outSpatialReference property in your Query object. The feature service will then perform the projection on the server before returning the data to the client, eliminating the need for separate projection steps.

import FeatureLayer from '@arcgis/core/layers/FeatureLayer';
import Query from '@arcgis/core/rest/support/Query';
import SpatialReference from '@arcgis/core/geometry/SpatialReference';

// Initialize your feature layer
const boundaryLayer = new FeatureLayer({
 url: 'https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/Cities_by_population/FeatureServer/0'
});

// Create a query object
const layerQuery = new Query({
 where: 'POPULATION > 1000000',
 returnGeometry: true,
 outFields: ['NAME', 'POPULATION'],
 // Request geometries in Web Mercator (EPSG:3857)
 outSpatialReference: SpatialReference.WebMercator
});

// Execute the query
boundaryLayer.queryFeatures(layerQuery)
 .then(function(queryResults) {
   console.log('Features returned in Web Mercator:', queryResults.features);
   // Each feature's geometry will already be in EPSG:3857
   if (queryResults.features.length > 0) {
     console.log('First feature geometry SR:', queryResults.features[0].geometry.spatialReference.wkid);
   }
 })
 .catch(function(error) {
   console.error('Error querying features:', error);
 });