webMercatorUtils | References | ArcGIS Maps SDK for JavaScript

import { canProject, project, lngLatToXY, xyToLngLat, geographicToWebMercator } from "@arcgis/core/geometry/support/webMercatorUtils.js";

Since: ArcGIS Maps SDK for JavaScript 4.0

Converts Web Mercator coordinates to geographic coordinates and vice versa.

Known Limitation

Geometry type Mesh is not supported.

See also

Sample - Coordinate Conversion component - Custom Formats

Functions

Name	Return Type	Object
`canProject`	`boolean`
`project`	`GeometryUnion \| null \| undefined`
`lngLatToXY`	`[ number, number ]`
`xyToLngLat`	`[ number, number ]`
`geographicToWebMercator`	`GeometryUnion`
`webMercatorToGeographic`	`GeometryUnion`

canProject

Function

Returns true if the source spatial reference can be projected to the target spatial reference with the project() function, or if the source and target are the same SpatialReference.

See also

project()

Signature: canProject (source: object | SpatialReference | null | undefined, target: object | SpatialReference | null | undefined): boolean

Parameters

Parameter	Type	Description	Required
source	`object \| SpatialReference \| null \| undefined`	The input SpatialReference or an object with `spatialReference` property such as Geometry or Map.
target	`object \| SpatialReference \| null \| undefined`	The target SpatialReference or an object with `spatialReference` property such as Geometry or Map.

Returns: boolean
Returns true if source can be projected to target.

project

Function

Projects the geometry clientside (if possible). You should test the input geometry in canProject() prior to using this function. If the result of canProject() is true, then proceed to project. If canProject() returns false, then project() won't return useful results. Use project() instead.

See also

Signature: project (geometry: GeometryUnion | null | undefined, spatialReference: SpatialReference | null | undefined): GeometryUnion | null | undefined

Parameters

Parameter	Type	Description	Required
geometry	`GeometryUnion \| null \| undefined`	The input geometry.
spatialReference	`SpatialReference \| null \| undefined`	The target SpatialReference or an object with `spatialReference` property such as Geometry or Map.

Returns: GeometryUnion | null | undefined
Returns the projected geometry if the projection is successful.

lngLatToXY

Function

Translates the given latitude and longitude (decimal degree) values to Web Mercator XY values.

Signature: lngLatToXY (long: number, lat: number): [ number, number ]

Parameters

Parameter	Type	Description	Required
long	`number`	The longitude value to convert.
lat	`number`	The latitude value to convert.

Returns: [ number, number ]
Returns the converted values in an array.

xyToLngLat

Function

Translates the given Web Mercator coordinates to Longitude and Latitude values (decimal degrees). By default the returned longitude is normalized so that it is within -180 and +180.

Signature: xyToLngLat (x: number, y: number): [ number, number ]

Parameters

Parameter	Type	Description	Required
x	`number`	The X coordinate value to convert.
y	`number`	The Y coordinate value to convert.

Returns: [ number, number ]
Returns the converted values in an array.

geographicToWebMercator

Function

Converts a geometry from geographic units (wkid: 4326) to Web Mercator units (wkid: 3857).

Signature: geographicToWebMercator (geometry: GeometryUnion): GeometryUnion

Parameters

Parameter	Type	Description	Required
geometry	`GeometryUnion`	The input geometry to convert.

Returns: GeometryUnion
Returns the converted geometry in Web Mercator units.

webMercatorToGeographic

Function

Converts a geometry from Web Mercator units (wkid: 3857) to geographic units (wkid: 4326).

Signature: webMercatorToGeographic (geometry: GeometryUnion, isLinear?: boolean): GeometryUnion

Parameters

Parameter	Type	Description	Required
geometry	`GeometryUnion`	The input geometry to convert.
isLinear	`boolean`	= false - Indicates whether to work with linear values, i.e., do not normalize. By default, this conversion method normalizes xmin and xmax values. If this is not desired, specify this value as `true`. Default value is `false`.

Returns: GeometryUnion
Returns the converted geometry in geographic units.