arcgis-coordinates-projection

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ArcGIS Coordinates and Projection

ArcGIS 坐标与投影

Use this skill for coordinate conversion, projection transformations, and spatial reference handling.

Important: The
projection
module is deprecated as of version 4.32 and
geodesicUtils
is deprecated as of version 4.33. Use the projectOperator and geometry operators instead. See the Deprecation Notice section for migration guidance.

使用此技能进行坐标转换、投影变换和空间参考处理。

重要提示： 从4.32版本开始，
projection
模块已弃用；从4.33版本开始，
geodesicUtils
已弃用。请改用projectOperator和几何操作器。有关迁移指导，请参阅弃用通知部分。

Coordinate Conversion Component

坐标转换组件

Basic Coordinate Conversion

基础坐标转换

html

<arcgis-map basemap="topo-vector" center="-117.049, 34.485" zoom="12">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-coordinate-conversion slot="bottom-left"></arcgis-coordinate-conversion>
</arcgis-map>

html

<arcgis-map basemap="topo-vector" center="-117.049, 34.485" zoom="12">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-coordinate-conversion slot="bottom-left"></arcgis-coordinate-conversion>
</arcgis-map>

Coordinate Conversion Widget (Core API)

坐标转换部件（核心API）

javascript

import CoordinateConversion from "@arcgis/core/widgets/CoordinateConversion.js";

const ccWidget = new CoordinateConversion({
  view: view
});

view.ui.add(ccWidget, "bottom-left");

javascript

import CoordinateConversion from "@arcgis/core/widgets/CoordinateConversion.js";

const ccWidget = new CoordinateConversion({
  view: view
});

view.ui.add(ccWidget, "bottom-left");

Custom Coordinate Formats

自定义坐标格式

javascript

import CoordinateConversion from "@arcgis/core/widgets/CoordinateConversion.js";
import Format from "@arcgis/core/widgets/CoordinateConversion/support/Format.js";

// Create custom format
const customFormat = new Format({
  name: "Custom XY",
  conversionInfo: {
    spatialReference: { wkid: 4326 },
    reverseConvert: (string) => {
      const parts = string.split(",");
      return [parseFloat(parts[0]), parseFloat(parts[1])];
    }
  },
  coordinateSegments: [
    { alias: "Lon", description: "Longitude", searchPattern: "X" },
    { alias: "Lat", description: "Latitude", searchPattern: "Y" }
  ],
  defaultPattern: "X°, Y°"
});

const ccWidget = new CoordinateConversion({
  view: view,
  formats: [customFormat]
});

javascript

import CoordinateConversion from "@arcgis/core/widgets/CoordinateConversion.js";
import Format from "@arcgis/core/widgets/CoordinateConversion/support/Format.js";

// 创建自定义格式
const customFormat = new Format({
  name: "Custom XY",
  conversionInfo: {
    spatialReference: { wkid: 4326 },
    reverseConvert: (string) => {
      const parts = string.split(",");
      return [parseFloat(parts[0]), parseFloat(parts[1])];
    }
  },
  coordinateSegments: [
    { alias: "Lon", description: "Longitude", searchPattern: "X" },
    { alias: "Lat", description: "Latitude", searchPattern: "Y" }
  ],
  defaultPattern: "X°, Y°"
});

const ccWidget = new CoordinateConversion({
  view: view,
  formats: [customFormat]
});

Spatial Reference

空间参考

Create Spatial Reference

创建空间参考

javascript

import SpatialReference from "@arcgis/core/geometry/SpatialReference.js";

// By WKID
const wgs84 = new SpatialReference({ wkid: 4326 });
const webMercator = new SpatialReference({ wkid: 102100 });

// By WKT
const customSR = new SpatialReference({
  wkt: 'PROJCS["NAD_1983_StatePlane_California_VI_FIPS_0406_Feet"...'
});

javascript

import SpatialReference from "@arcgis/core/geometry/SpatialReference.js";

// 通过WKID创建
const wgs84 = new SpatialReference({ wkid: 4326 });
const webMercator = new SpatialReference({ wkid: 102100 });

// 通过WKT创建
const customSR = new SpatialReference({
  wkt: 'PROJCS["NAD_1983_StatePlane_California_VI_FIPS_0406_Feet"...'
});

Common Spatial References

常用空间参考

javascript

// WGS 84 (Geographic)
const wgs84 = { wkid: 4326 };

// Web Mercator (Projected)
const webMercator = { wkid: 102100 };  // or 3857

// UTM Zone 11N
const utm11n = { wkid: 32611 };

// State Plane (example)
const statePlane = { wkid: 2230 };

javascript

// WGS 84（地理坐标系）
const wgs84 = { wkid: 4326 };

// Web墨卡托（投影坐标系）
const webMercator = { wkid: 102100 };  // 或3857

// UTM 11N带
const utm11n = { wkid: 32611 };

// 州平面坐标系（示例）
const statePlane = { wkid: 2230 };

Modern Projection Operator

现代投影操作器

Use the

projectOperator

for client-side coordinate projection (recommended).

使用

projectOperator

进行客户端坐标投影（推荐方式）。

Project Geometry

投影几何图形

javascript

import projectOperator from "@arcgis/core/geometry/operators/projectOperator.js";

// Load projection engine (required before use)
await projectOperator.load();

// Project geometry to WGS84
const projectedGeometry = projectOperator.execute(geometry, { wkid: 4326 });

javascript

import projectOperator from "@arcgis/core/geometry/operators/projectOperator.js";

// 加载投影引擎（使用前必须调用）
await projectOperator.load();

// 将几何图形投影到WGS84坐标系
const projectedGeometry = projectOperator.execute(geometry, { wkid: 4326 });

Project with Geographic Transformation

带地理变换的投影

javascript

import projectOperator from "@arcgis/core/geometry/operators/projectOperator.js";

await projectOperator.load();

// Project with specific transformation (e.g., NAD83 to WGS84)
const projectedGeometry = projectOperator.execute(geometry, { wkid: 4326 }, {
  geographicTransformation: {
    steps: [{ wkid: 108190 }]  // NAD_1983_To_WGS_1984_5
  }
});

For geodetic geometry operations (geodesicBuffer, geodesicLength, geodesicArea, etc.), see arcgis-geometry-operations.

javascript

import projectOperator from "@arcgis/core/geometry/operators/projectOperator.js";

await projectOperator.load();

// 使用特定变换进行投影（例如，从NAD83到WGS84）
const projectedGeometry = projectOperator.execute(geometry, { wkid: 4326 }, {
  geographicTransformation: {
    steps: [{ wkid: 108190 }]  // NAD_1983_To_WGS_1984_5
  }
});

有关大地测量几何操作（geodesicBuffer、geodesicLength、geodesicArea等），请参阅arcgis-geometry-operations。

Geometry Service Projection

几何服务投影

Server-Side Projection

服务器端投影

javascript

import geometryService from "@arcgis/core/rest/geometryService.js";
import ProjectParameters from "@arcgis/core/rest/support/ProjectParameters.js";

const gsUrl = "https://utility.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer";

const params = new ProjectParameters({
  geometries: [geometry],
  outSpatialReference: { wkid: 4326 }
});

const results = await geometryService.project(gsUrl, params);
const projectedGeometry = results[0];

javascript

import geometryService from "@arcgis/core/rest/geometryService.js";
import ProjectParameters from "@arcgis/core/rest/support/ProjectParameters.js";

const gsUrl = "https://utility.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer";

const params = new ProjectParameters({
  geometries: [geometry],
  outSpatialReference: { wkid: 4326 }
});

const results = await geometryService.project(gsUrl, params);
const projectedGeometry = results[0];

Coordinate Conversion Utilities

坐标转换工具

Convert Coordinates

转换坐标

javascript

import webMercatorUtils from "@arcgis/core/geometry/support/webMercatorUtils.js";

// Web Mercator to Geographic
const geographicPoint = webMercatorUtils.webMercatorToGeographic(webMercatorPoint);

// Geographic to Web Mercator
const webMercatorPoint = webMercatorUtils.geographicToWebMercator(geographicPoint);

// Check if can project
const canProject = webMercatorUtils.canProject(fromSR, toSR);

javascript

import webMercatorUtils from "@arcgis/core/geometry/support/webMercatorUtils.js";

// Web墨卡托转地理坐标系
const geographicPoint = webMercatorUtils.webMercatorToGeographic(webMercatorPoint);

// 地理坐标系转Web墨卡托
const webMercatorPoint = webMercatorUtils.geographicToWebMercator(geographicPoint);

// 检查是否可投影
const canProject = webMercatorUtils.canProject(fromSR, toSR);

Display Coordinates

坐标显示

Show Mouse Coordinates

显示鼠标坐标

javascript

view.on("pointer-move", (event) => {
  const mapPoint = view.toMap({ x: event.x, y: event.y });

  if (mapPoint) {
    document.getElementById("coords").textContent =
      `Lat: ${mapPoint.latitude.toFixed(6)}, Lon: ${mapPoint.longitude.toFixed(6)}`;
  }
});

javascript

view.on("pointer-move", (event) => {
  const mapPoint = view.toMap({ x: event.x, y: event.y });

  if (mapPoint) {
    document.getElementById("coords").textContent =
      `纬度: ${mapPoint.latitude.toFixed(6)}, 经度: ${mapPoint.longitude.toFixed(6)}`;
  }
});

Format Coordinates

格式化坐标

javascript

import coordinateFormatter from "@arcgis/core/geometry/coordinateFormatter.js";

await coordinateFormatter.load();

// To Degrees Minutes Seconds
const dms = coordinateFormatter.toLatitudeLongitude(
  point,
  "dms",  // or "dm", "dd"
  3       // decimal places
);
// Output: "34°29'06.000\"N 117°02'56.400\"W"

// To MGRS
const mgrs = coordinateFormatter.toMgrs(
  point,
  "automatic",  // conversion mode
  5,            // precision
  false         // add spaces
);
// Output: "11SNU1234567890"

// To UTM
const utm = coordinateFormatter.toUtm(
  point,
  "north-south-indicators",
  true  // add spaces
);
// Output: "11S 500000 3800000"

// From string to point
const pointFromDMS = coordinateFormatter.fromLatitudeLongitude(
  "34°29'06\"N 117°02'56\"W"
);

javascript

import coordinateFormatter from "@arcgis/core/geometry/coordinateFormatter.js";

await coordinateFormatter.load();

// 转换为度分秒格式
const dms = coordinateFormatter.toLatitudeLongitude(
  point,
  "dms",  // 或"dm"、"dd"
  3       // 小数位数
);
// 输出: "34°29'06.000\"N 117°02'56.400\"W"

// 转换为MGRS格式
const mgrs = coordinateFormatter.toMgrs(
  point,
  "automatic",  // 转换模式
  5,            // 精度
  false         // 是否添加空格
);
// 输出: "11SNU1234567890"

// 转换为UTM格式
const utm = coordinateFormatter.toUtm(
  point,
  "north-south-indicators",
  true  // 是否添加空格
);
// 输出: "11S 500000 3800000"

// 从字符串转换为点
const pointFromDMS = coordinateFormatter.fromLatitudeLongitude(
  "34°29'06\"N 117°02'56\"W"
);

USNG and MGRS

USNG与MGRS

USNG Conversion

USNG转换

javascript

import coordinateFormatter from "@arcgis/core/geometry/coordinateFormatter.js";

await coordinateFormatter.load();

// To USNG
const usng = coordinateFormatter.toUsng(point, 5, false);

// From USNG
const point = coordinateFormatter.fromUsng("11SNU1234567890");

javascript

import coordinateFormatter from "@arcgis/core/geometry/coordinateFormatter.js";

await coordinateFormatter.load();

// 转换为USNG格式
const usng = coordinateFormatter.toUsng(point, 5, false);

// 从USNG格式转换为点
const point = coordinateFormatter.fromUsng("11SNU1234567890");

Complete Example

完整示例

html

<!DOCTYPE html>
<html>
<head>
  <script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>
  <script src="https://js.arcgis.com/4.34/"></script>
  <script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>
  <style>
    html, body { height: 100%; margin: 0; }
    #coordsPanel {
      position: absolute;
      bottom: 50px;
      right: 10px;
      background: white;
      padding: 10px;
    }
  </style>
</head>
<body>
  <arcgis-map basemap="topo-vector" center="-117.049, 34.485" zoom="12">
    <arcgis-zoom slot="top-left"></arcgis-zoom>
    <arcgis-coordinate-conversion slot="bottom-left"></arcgis-coordinate-conversion>
  </arcgis-map>

  <div id="coordsPanel" class="esri-widget">
    <div id="latlon">Move mouse to see coordinates</div>
    <div id="utm"></div>
    <div id="mgrs"></div>
  </div>

  <script type="module">
    import coordinateFormatter from "@arcgis/core/geometry/coordinateFormatter.js";

    await coordinateFormatter.load();

    const viewElement = document.querySelector("arcgis-map");
    await viewElement.viewOnReady();

    viewElement.addEventListener("arcgisViewPointerMove", (event) => {
      const point = viewElement.view.toMap({
        x: event.detail.x,
        y: event.detail.y
      });

      if (point) {
        document.getElementById("latlon").textContent =
          `Lat/Lon: ${point.latitude.toFixed(6)}, ${point.longitude.toFixed(6)}`;

        document.getElementById("utm").textContent =
          `UTM: ${coordinateFormatter.toUtm(point, "north-south-indicators", true)}`;

        document.getElementById("mgrs").textContent =
          `MGRS: ${coordinateFormatter.toMgrs(point, "automatic", 5, true)}`;
      }
    });
  </script>
</body>
</html>

html

<!DOCTYPE html>
<html>
<head>
  <script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>
  <script src="https://js.arcgis.com/4.34/"></script>
  <script type="module" src="https://js.arcgis.com/4.34/map-components/"></script>
  <style>
    html, body { height: 100%; margin: 0; }
    #coordsPanel {
      position: absolute;
      bottom: 50px;
      right: 10px;
      background: white;
      padding: 10px;
    }
  </style>
</head>
<body>
  <arcgis-map basemap="topo-vector" center="-117.049, 34.485" zoom="12">
    <arcgis-zoom slot="top-left"></arcgis-zoom>
    <arcgis-coordinate-conversion slot="bottom-left"></arcgis-coordinate-conversion>
  </arcgis-map>

  <div id="coordsPanel" class="esri-widget">
    <div id="latlon">移动鼠标查看坐标</div>
    <div id="utm"></div>
    <div id="mgrs"></div>
  </div>

  <script type="module">
    import coordinateFormatter from "@arcgis/core/geometry/coordinateFormatter.js";

    await coordinateFormatter.load();

    const viewElement = document.querySelector("arcgis-map");
    await viewElement.viewOnReady();

    viewElement.addEventListener("arcgisViewPointerMove", (event) => {
      const point = viewElement.view.toMap({
        x: event.detail.x,
        y: event.detail.y
      });

      if (point) {
        document.getElementById("latlon").textContent =
          `纬度/经度: ${point.latitude.toFixed(6)}, ${point.longitude.toFixed(6)}`;

        document.getElementById("utm").textContent =
          `UTM: ${coordinateFormatter.toUtm(point, "north-south-indicators", true)}`;

        document.getElementById("mgrs").textContent =
          `MGRS: ${coordinateFormatter.toMgrs(point, "automatic", 5, true)}`;
      }
    });
  </script>
</body>
</html>

Reference Samples

参考示例

```
coordinate-conversion
```
- Converting between coordinate formats
```
client-projection
```
- Client-side projection of geometries
```
widgets-coordinateconversion
```
- CoordinateConversion widget usage

```
coordinate-conversion
```
- 坐标格式间的转换
```
client-projection
```
- 几何图形的客户端投影
```
widgets-coordinateconversion
```
- CoordinateConversion部件的使用

Common Pitfalls

常见误区

Load projection engine: Must call
```
projectOperator.load()
```
before using
Coordinate order: Geographic is (lon, lat), not (lat, lon)
WKID vs WKT: Use WKID when available, WKT for custom projections
Datum transformations: May be needed for accurate results between datums
Client vs server: Use client-side for speed, server for complex transformations

加载投影引擎：使用前必须调用
```
projectOperator.load()
```
坐标顺序：地理坐标系为（经度, 纬度），而非（纬度, 经度）
WKID与WKT：优先使用WKID，自定义投影使用WKT
基准面变换：不同基准面间转换可能需要基准面变换以保证精度
客户端与服务器端：客户端方式速度更快，服务器端适用于复杂变换

Deprecated APIs

已弃用API

DEPRECATED: The APIs below are deprecated. Use the modern alternatives shown above.

已弃用： 以下API已被弃用，请使用上文所示的现代替代方案。

Migration Guide

迁移指南

Deprecated	Modern Replacement
`projection.project(geom, sr)`	`projectOperator.execute(geom, sr)`
`projection.load()`	`projectOperator.load()`
`geodesicUtils.geodesicDistance(p1, p2, unit)`	`geodeticDistanceOperator.execute(p1, p2, { unit })`
`geodesicUtils.geodesicArea(geom, unit)`	`geodeticAreaOperator.execute(geom, { unit })`
`geodesicUtils.geodesicLength(geom, unit)`	`geodeticLengthOperator.execute(geom, { unit })`

已弃用API	现代替代方案
`projection.project(geom, sr)`	`projectOperator.execute(geom, sr)`
`projection.load()`	`projectOperator.load()`
`geodesicUtils.geodesicDistance(p1, p2, unit)`	`geodeticDistanceOperator.execute(p1, p2, { unit })`
`geodesicUtils.geodesicArea(geom, unit)`	`geodeticAreaOperator.execute(geom, { unit })`
`geodesicUtils.geodesicLength(geom, unit)`	`geodeticLengthOperator.execute(geom, { unit })`

Legacy projection Module (Deprecated since 4.32)

旧版projection模块（4.32版本起弃用）

javascript

// DEPRECATED - Use projectOperator instead
import projection from "@arcgis/core/geometry/projection.js";

await projection.load();

const projectedGeometry = projection.project(
  geometry,
  new SpatialReference({ wkid: 4326 })
);

javascript

// 已弃用 - 请改用projectOperator
import projection from "@arcgis/core/geometry/projection.js";

await projection.load();

const projectedGeometry = projection.project(
  geometry,
  new SpatialReference({ wkid: 4326 })
);

Legacy geodesicUtils (Deprecated since 4.33)

旧版geodesicUtils（4.33版本起弃用）

javascript

// DEPRECATED - Use geodesicDistanceOperator instead
import geodesicUtils from "@arcgis/core/geometry/support/geodesicUtils.js";

const distance = geodesicUtils.geodesicDistance(
  point1,
  point2,
  "kilometers"
);

javascript

// 已弃用 - 请改用geodeticDistanceOperator
import geodesicUtils from "@arcgis/core/geometry/support/geodesicUtils.js";

const distance = geodesicUtils.geodesicDistance(
  point1,
  point2,
  "kilometers"
);