arcgis-geometry-operations

ArcGIS 几何运算

使用此技能创建几何图形，并使用几何运算符执行空间操作。

重要提示： geometryEngine 和 geometryEngineAsync 模块已在 v5.0 中移除（自 4.29 起弃用）。请仅使用几何运算符。

导入方式

直接 ESM 导入

import Point from "@arcgis/core/geometry/Point.js";
import Polygon from "@arcgis/core/geometry/Polygon.js";
import bufferOperator from "@arcgis/core/geometry/operators/bufferOperator.js";
import unionOperator from "@arcgis/core/geometry/operators/unionOperator.js";

动态导入（CDN）

const Point = await $arcgis.import("@arcgis/core/geometry/Point.js");
const [bufferOperator, unionOperator] = await $arcgis.import([
  "@arcgis/core/geometry/operators/bufferOperator.js",
  "@arcgis/core/geometry/operators/unionOperator.js",
]);

几何类概览

类	用途	导入路径
Point	单个位置（x、y、z、m）	geometry/Point.js
Polyline	线和路径	geometry/Polyline.js
Polygon	带环的区域	geometry/Polygon.js
Multipoint	点的集合	geometry/Multipoint.js
Extent	边界框	geometry/Extent.js
Circle	圆形几何图形	geometry/Circle.js
Mesh	带顶点和面的 3D 网格	geometry/Mesh.js

创建几何图形

Point

// Using autocast (plain object)
const point = {
  type: "point",
  longitude: -118.80657,
  latitude: 34.02749,
  z: 1000,
  spatialReference: { wkid: 4326 },
};

// Using x, y coordinates (projected)
const point = {
  type: "point",
  x: -13044706,
  y: 4036320,
  spatialReference: { wkid: 102100 },
};

Polyline

const polyline = {
  type: "polyline",
  paths: [
    [
      [-118.821, 34.014],
      [-118.815, 34.014],
      [-118.809, 34.01],
    ],
  ],
  spatialReference: { wkid: 4326 },
};

// Multi-path
const multiPath = {
  type: "polyline",
  paths: [
    [
      [-118.821, 34.014],
      [-118.815, 34.014],
    ],
    [
      [-118.815, 34.022],
      [-118.813, 34.022],
    ],
  ],
};

Polygon

const polygon = {
  type: "polygon",
  rings: [
    // Outer ring (clockwise)
    [
      [-118.818, 34.02],
      [-118.807, 34.02],
      [-118.807, 34.029],
      [-118.818, 34.029],
      [-118.818, 34.02],
    ],
    // Inner ring/hole (counter-clockwise)
    [
      [-118.815, 34.022],
      [-118.81, 34.022],
      [-118.81, 34.026],
      [-118.815, 34.026],
      [-118.815, 34.022],
    ],
  ],
  spatialReference: { wkid: 4326 },
};

Extent

const extent = {
  type: "extent",
  xmin: -118.82,
  ymin: 34.01,
  xmax: -118.8,
  ymax: 34.03,
  spatialReference: { wkid: 4326 },
};

Circle

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

const circle = new Circle({
  center: [-118.80657, 34.02749],
  radius: 1000,
  radiusUnit: "meters",
  geodesic: true,
  spatialReference: { wkid: 4326 },
});

Multipoint

const multipoint = {
  type: "multipoint",
  points: [
    [-118.821, 34.014],
    [-118.815, 34.014],
    [-118.809, 34.01],
  ],
  spatialReference: { wkid: 4326 },
};

几何运算符

每个运算符都单独导入，以便进行摇树优化。某些运算符在使用前需要调用 await operator.load()。

缓冲区操作

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

await bufferOperator.load();

// Simple buffer (distance in meters by default)
const buffered = bufferOperator.execute(point, 1000);

// Buffer with unit
const buffered = bufferOperator.execute(point, 500, { unit: "meters" });

// Geodesic buffer (for geographic coordinates)
import geodesicBufferOperator from "@arcgis/core/geometry/operators/geodesicBufferOperator.js";

await geodesicBufferOperator.load();
const geoBuffered = geodesicBufferOperator.execute(point, 1000, {
  unit: "meters",
});

空间关系

所有关系运算符均返回布尔值。

import containsOperator from "@arcgis/core/geometry/operators/containsOperator.js";
import withinOperator from "@arcgis/core/geometry/operators/withinOperator.js";
import intersectsOperator from "@arcgis/core/geometry/operators/intersectsOperator.js";
import crossesOperator from "@arcgis/core/geometry/operators/crossesOperator.js";
import overlapsOperator from "@arcgis/core/geometry/operators/overlapsOperator.js";
import touchesOperator from "@arcgis/core/geometry/operators/touchesOperator.js";
import disjointOperator from "@arcgis/core/geometry/operators/disjointOperator.js";
import equalsOperator from "@arcgis/core/geometry/operators/equalsOperator.js";

// Contains - geometry1 completely contains geometry2
containsOperator.execute(polygon, point); // boolean

// Within - geometry1 is completely within geometry2
withinOperator.execute(point, polygon); // boolean

// Intersects - geometries share any space
intersectsOperator.execute(polygon1, polygon2); // boolean

// Crosses, Overlaps, Touches, Disjoint, Equals
crossesOperator.execute(line, polygon);
overlapsOperator.execute(polygon1, polygon2);
touchesOperator.execute(polygon1, polygon2);
disjointOperator.execute(polygon1, polygon2);
equalsOperator.execute(geom1, geom2);

集合操作

import unionOperator from "@arcgis/core/geometry/operators/unionOperator.js";
import intersectionOperator from "@arcgis/core/geometry/operators/intersectionOperator.js";
import differenceOperator from "@arcgis/core/geometry/operators/differenceOperator.js";
import symmetricDifferenceOperator from "@arcgis/core/geometry/operators/symmetricDifferenceOperator.js";
import clipOperator from "@arcgis/core/geometry/operators/clipOperator.js";

// Union - combine geometries
const combined = unionOperator.execute([polygon1, polygon2, polygon3]);

// Intersection - common area
const common = intersectionOperator.execute(polygon1, polygon2);

// Difference - subtract geometry2 from geometry1
const diff = differenceOperator.execute(polygon1, polygon2);

// Symmetric Difference - areas in either but not both
const symDiff = symmetricDifferenceOperator.execute(polygon1, polygon2);

// Clip - clip geometry by extent
const clipped = clipOperator.execute(polygon, extent);

测量

import areaOperator from "@arcgis/core/geometry/operators/areaOperator.js";
import geodeticAreaOperator from "@arcgis/core/geometry/operators/geodeticAreaOperator.js";
import lengthOperator from "@arcgis/core/geometry/operators/lengthOperator.js";
import geodeticLengthOperator from "@arcgis/core/geometry/operators/geodeticLengthOperator.js";
import distanceOperator from "@arcgis/core/geometry/operators/distanceOperator.js";
import geodeticDistanceOperator from "@arcgis/core/geometry/operators/geodeticDistanceOperator.js";

// Area (polygons)
const area = areaOperator.execute(polygon);
const geoArea = geodeticAreaOperator.execute(polygon, {
  unit: "square-kilometers",
});

// Length (polylines)
const length = lengthOperator.execute(polyline);
const geoLength = geodeticLengthOperator.execute(polyline, {
  unit: "kilometers",
});

// Distance between geometries
const dist = distanceOperator.execute(point1, point2);
const geoDist = geodeticDistanceOperator.execute(point1, point2, {
  unit: "kilometers",
});

几何图形操作

import simplifyOperator from "@arcgis/core/geometry/operators/simplifyOperator.js";
import generalizeOperator from "@arcgis/core/geometry/operators/generalizeOperator.js";
import densifyOperator from "@arcgis/core/geometry/operators/densifyOperator.js";
import offsetOperator from "@arcgis/core/geometry/operators/offsetOperator.js";
import convexHullOperator from "@arcgis/core/geometry/operators/convexHullOperator.js";
import centroidOperator from "@arcgis/core/geometry/operators/centroidOperator.js";
import labelPointOperator from "@arcgis/core/geometry/operators/labelPointOperator.js";

// Simplify - remove self-intersections
const simplified = simplifyOperator.execute(polygon);

// Generalize - reduce vertices
const generalized = generalizeOperator.execute(polyline, {
  maxDeviation: 100,
  unit: "meters",
});

// Densify - add vertices
const densified = densifyOperator.execute(polyline, {
  maxSegmentLength: 100,
  unit: "meters",
});

// Offset - create parallel geometry
const offsetGeom = offsetOperator.execute(polyline, {
  distance: 50,
  unit: "meters",
  joinType: "round",
});

// Convex Hull
const hull = convexHullOperator.execute(polygon);

// Centroid
const center = centroidOperator.execute(polygon);

// Label Point (guaranteed inside polygon)
const label = labelPointOperator.execute(polygon);

可用运算符

类别	运算符
关系	containsOperator、crossesOperator、disjointOperator、equalsOperator、intersectsOperator、isNearOperator、overlapsOperator、relateOperator、touchesOperator、withinOperator
集合操作	clipOperator、cutOperator、differenceOperator、intersectionOperator、symmetricDifferenceOperator、unionOperator
缓冲区	bufferOperator、geodesicBufferOperator、graphicBufferOperator
形状	autoCompleteOperator、boundaryOperator、convexHullOperator、simplifyOperator、simplifyOGCOperator、alphaShapeOperator、minimumBoundingCircleOperator
测量	areaOperator、geodeticAreaOperator、lengthOperator、geodeticLengthOperator、distanceOperator、geodeticDistanceOperator
变换	densifyOperator、geodeticDensifyOperator、generalizeOperator、offsetOperator、affineTransformOperator、reshapeOperator、extendOperator
分析	centroidOperator、labelPointOperator、proximityOperator、geodesicProximityOperator
投影	projectOperator、shapePreservingProjectOperator
转换	linesToPolygonsOperator、multiPartToSinglePartOperator、polygonSlicerOperator、polygonOverlayOperator

投影（projectOperator）

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

await projectOperator.load();

// Project to new spatial reference
const projected = projectOperator.execute(geometry, { wkid: 4326 });

// With geographic transformation
const projected = projectOperator.execute(
  geometry,
  { wkid: 4326 },
  {
    geographicTransformation: {
      steps: [{ wkid: 108190 }],
    },
  },
);

有关坐标系和转换的详细信息，请参阅 arcgis-coordinates-projection。

Web Mercator 工具

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

const webMercatorGeom =
  webMercatorUtils.geographicToWebMercator(geographicPoint);
const geoGeom = webMercatorUtils.webMercatorToGeographic(webMercatorPoint);
const canProject = webMercatorUtils.canProject(
  geom1.spatialReference,
  geom2.spatialReference,
);

网格（3D 几何）

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

const box = Mesh.createBox(location, {
  size: { width: 100, height: 100, depth: 50 },
  material: { color: "red" },
});

const sphere = Mesh.createSphere(location, {
  size: 50,
  material: { color: "blue" },
});

const cylinder = Mesh.createCylinder(location, {
  size: { width: 50, height: 100 },
  material: { color: "green" },
});

// Load from glTF/GLB
const mesh = await Mesh.createFromGLTF(location, "model.glb");

JSON 工具

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

// Create geometry from JSON
const geometry = jsonUtils.fromJSON({
  rings: [
    [
      [-118.8, 34.0],
      [-118.7, 34.0],
      [-118.7, 34.1],
      [-118.8, 34.1],
      [-118.8, 34.0],
    ],
  ],
  spatialReference: { wkid: 4326 },
});

// Get JSON from geometry
const json = geometry.toJSON();

常见模式

检查点是否位于多边形内

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

function isPointInPolygon(point, polygon) {
  return containsOperator.execute(polygon, point);
}

缓冲区和查询

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

async function queryWithinDistance(point, distance, layer) {
  await geodesicBufferOperator.load();
  const bufferGeom = geodesicBufferOperator.execute(point, distance, {
    unit: "meters",
  });
  const query = layer.createQuery();
  query.geometry = bufferGeom;
  query.spatialRelationship = "contains";
  return await layer.queryFeatures(query);
}

计算总面积

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

function calculateTotalArea(polygons) {
  const combined = unionOperator.execute(polygons);
  return geodeticAreaOperator.execute(combined, { unit: "square-kilometers" });
}

常见问题

1. 空间参考不匹配：操作前，请始终确保几何位于相同的空间参考中：

   import projectOperator from "@arcgis/core/geometry/operators/projectOperator.js";
   await projectOperator.load();
   if (!geom1.spatialReference.equals(geom2.spatialReference)) {
     geom2 = projectOperator.execute(geom2, geom1.spatialReference);
   }
   

2. 测地线与平面：对于地理坐标（WGS84/4326），请使用测地线运算符。对于投影坐标系，请使用平面运算符：

   const bufferOp = geometry.spatialReference.isGeographic
     ? geodesicBufferOperator
     : bufferOperator;
   

3. 环方向：外环必须为顺时针方向，孔洞必须为逆时针方向。如不确定，请使用 simplifyOperator。

4. 自相交多边形：对用户绘制的多边形执行操作前，请使用 simplifyOperator.execute(polygon)。

5. 忘记加载运算符：某些运算符在调用 .execute() 前需要执行 await operator.load()。请查阅运算符文档。

6. 使用已移除的 geometryEngine：geometryEngine 和 geometryEngineAsync 模块已在 5.0 中移除。请改用单独的运算符。

参考示例

• ge-geodesicbuffer - 测地线缓冲区操作
• gx-geodesicbuffer - 测地线缓冲区（替代方案）
• geometry-operator-centroid - 计算几何质心
• geometry-operator-offset-visualizer - 可视化几何偏移
• geometry-operator-proximity - 使用几何运算符进行邻近分析
• geometry-operator-worker - 在 Web Worker 中运行几何操作
• geometry-mesh-primitives - 创建 3D 网格基元
• geometry-mesh-elevation - 带高程的 3D 网格

相关技能

• 有关坐标系、投影详情和坐标格式化，请参阅 arcgis-coordinates-projection。
• 有关通过几何服务执行服务器端几何操作，请参阅 arcgis-rest-services。
• 有关分析对象和要素缩减，请参阅 arcgis-spatial-analysis。