SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsgeometry-api-net

geometry-api-net

Data & analytics

View repository

Updated 10-16 09:45

About this skill

Project URL: https://github.com/znlgis/geometry-api-net

This document is intended to help AI quickly understand and use the geometry-api-net library for spatial geometry development.

Project Overview

This is a .NET Standard 2.0 spatial geometry computation library that provides 6 geometry types, 25+ spatial operation operators, and 4 serialization formats.

  • Core Package: Esri.Geometry.Core
  • JSON Extension Package: Esri.Geometry.Json
  • License: LGPL-2.1-only

Quick Start

dotnet add package Esri.Geometry.Core
dotnet add package Esri.Geometry.Json    # 可选，System.Text.Json 支持

Namespaces

Namespace Purpose
OpenGIS.Esri.Geometry.Core Core entry point, GeometryEngine convenience API
OpenGIS.Esri.Geometry.Core.Geometries Geometry types (Point, Polygon, etc.)
OpenGIS.Esri.Geometry.Core.Operators Spatial operation operators
OpenGIS.Esri.Geometry.Core.SpatialReference Spatial reference / coordinate systems
OpenGIS.Esri.Geometry.Core.IO Serialization (WKT, WKB, GeoJSON, EsriJson)
OpenGIS.Esri.Geometry.Json.Converters System.Text.Json converters

Geometry Types

GeometryType Enum

public enum GeometryType
{
    Unknown = 0,
    Point = 1,
    Line = 2,
    Envelope = 3,
    MultiPoint = 4,
    Polyline = 5,
    Polygon = 6
}

Geometry Base Class (Abstract)

All geometry types inherit from Geometry, and share the following properties and methods:

// 属性
geometry.Type        // GeometryType 枚举
geometry.IsEmpty     // 是否为空
geometry.Dimension   // 维度（Point=0, Line/Polyline=1, Polygon/Envelope=2）
geometry.IsPoint     // 是否为点类型
geometry.IsLinear    // 是否为线类型
geometry.IsArea      // 是否为面类型

// 方法
geometry.GetEnvelope()       // 获取外包矩形
geometry.CalculateArea2D()   // 计算面积
geometry.CalculateLength2D() // 计算长度
geometry.Copy()              // 深拷贝
geometry.IsValid()           // 是否有效

Point

var p = new Point();               // 空点 (NaN)
var p = new Point(10, 20);         // 2D 点
var p = new Point(10, 20, 30);     // 3D 点 (带 Z)

p.X    // double, X 坐标
p.Y    // double, Y 坐标
p.Z    // double?, Z 坐标（可空）
p.M    // double?, M 值（可空）

p.Distance(otherPoint)                    // 计算两点距离
p.Equals(otherPoint, tolerance)           // 容差比较

Line — Line Segment

var line = new Line();                         // 空线段
var line = new Line(new Point(0, 0), new Point(10, 10));

line.Start    // Point, 起点
line.End      // Point, 终点
line.Length    // double, 长度

Envelope — Bounding Rectangle

var env = new Envelope();                          // 空包围盒
var env = new Envelope(0, 0, 100, 100);            // xMin, yMin, xMax, yMax

env.XMin, env.YMin, env.XMax, env.YMax   // 边界坐标
env.Width       // 宽度
env.Height      // 高度
env.Center      // Point, 中心点
env.Area        // 面积

env.Contains(point)          // 是否包含点
env.Intersects(otherEnv)     // 是否与另一个包围盒相交
env.Merge(point)             // 合并点到包围盒
env.Merge(otherEnv)          // 合并另一个包围盒

MultiPoint

var mp = new MultiPoint();
var mp = new MultiPoint(new[] { new Point(1, 2), new Point(3, 4) });

mp.Add(new Point(5, 6));     // 添加点
mp.Count                     // 点数量
mp.GetPoint(0)               // 获取指定索引的点
mp.GetPoints()               // 获取所有点 (IEnumerable<Point>)

Polyline

var polyline = new Polyline();

// 添加路径（path），每条路径是一组连续的点
polyline.AddPath(new[] {
    new Point(0, 0), new Point(10, 0), new Point(10, 10)
});

polyline.PathCount            // 路径数量
polyline.Length                // 总长度
polyline.GetPath(0)           // 获取指定索引的路径 (IReadOnlyList<Point>)
polyline.GetPaths()           // 获取所有路径

Polygon

var polygon = new Polygon();

// 添加环（ring），首尾点必须闭合
polygon.AddRing(new[] {
    new Point(0, 0), new Point(10, 0), new Point(10, 10),
    new Point(0, 10), new Point(0, 0)   // ← 首尾闭合
});

polygon.RingCount             // 环数量
polygon.Area                  // 面积（Shoelace 公式）
polygon.GetRing(0)            // 获取指定索引的环 (IReadOnlyList<Point>)
polygon.GetRings()            // 获取所有环

Two API Styles

Style 1: GeometryEngine Static Methods (Recommended)

GeometryEngine provides convenience static method entry points for all operations, and is the most concise way to use it:

using OpenGIS.Esri.Geometry.Core;

// 空间关系判断
bool result = GeometryEngine.Contains(geometry1, geometry2);
bool result = GeometryEngine.Intersects(geometry1, geometry2);
bool result = GeometryEngine.Within(geometry1, geometry2);
bool result = GeometryEngine.Disjoint(geometry1, geometry2);
bool result = GeometryEngine.Crosses(geometry1, geometry2);
bool result = GeometryEngine.Touches(geometry1, geometry2);
bool result = GeometryEngine.Overlaps(geometry1, geometry2);
bool result = GeometryEngine.Equals(geometry1, geometry2);
double dist = GeometryEngine.Distance(geometry1, geometry2);

// 集合运算
Geometry result = GeometryEngine.Union(geometry1, geometry2);
Geometry result = GeometryEngine.Intersection(geometry1, geometry2);
Geometry result = GeometryEngine.Difference(geometry1, geometry2);
Geometry result = GeometryEngine.SymmetricDifference(geometry1, geometry2);

// 几何运算
Geometry buffer   = GeometryEngine.Buffer(geometry, distance);
Geometry hull     = GeometryEngine.ConvexHull(geometry);
Geometry simple   = GeometryEngine.Simplify(geometry, tolerance);
Geometry simpleOGC = GeometryEngine.SimplifyOGC(geometry, spatialRef);
bool     isSimple = GeometryEngine.IsSimpleOGC(geometry, spatialRef);
Geometry general  = GeometryEngine.Generalize(geometry, maxDeviation);
Geometry dense    = GeometryEngine.Densify(geometry, maxSegmentLength);
Geometry clipped  = GeometryEngine.Clip(geometry, clipEnvelope);
Geometry offset   = GeometryEngine.Offset(geometry, distance);
Point    center   = GeometryEngine.Centroid(geometry);
Geometry boundary = GeometryEngine.Boundary(geometry);
double   area     = GeometryEngine.Area(geometry);
double   length   = GeometryEngine.Length(geometry);

// 大地测量
double geodesicDist = GeometryEngine.GeodesicDistance(point1, point2);
double geodesicArea = GeometryEngine.GeodesicArea(polygon);

// 邻近搜索
Proximity2DResult nearest = GeometryEngine.GetNearestCoordinate(geometry, point, testPolygonInterior);
Proximity2DResult nearest = GeometryEngine.GetNearestVertex(geometry, point);
Proximity2DResult[] results = GeometryEngine.GetNearestVertices(geometry, point, searchRadius, maxVertexCount);

// 序列化 / 反序列化
string   wkt     = GeometryEngine.GeometryToWkt(geometry);
Geometry fromWkt = GeometryEngine.GeometryFromWkt(wktString);
byte[]   wkb     = GeometryEngine.GeometryToWkb(geometry, bigEndian);
Geometry fromWkb = GeometryEngine.GeometryFromWkb(wkbBytes);
string   json    = GeometryEngine.GeometryToGeoJson(geometry);
Geometry fromJson = GeometryEngine.GeometryFromGeoJson(geoJsonString);
string   esri    = GeometryEngine.GeometryToEsriJson(geometry);
Geometry fromEsri = GeometryEngine.GeometryFromEsriJson(esriJsonString);

Style 2: Operator Singleton Pattern

Each operator is obtained through the Instance singleton property (Lazy initialization), suitable for scenarios requiring finer control:

using OpenGIS.Esri.Geometry.Core.Operators;

// 空间关系
bool contains   = ContainsOperator.Instance.Execute(geom1, geom2);
bool intersects = IntersectsOperator.Instance.Execute(geom1, geom2);
double distance = DistanceOperator.Instance.Execute(geom1, geom2);
bool equals     = EqualsOperator.Instance.Execute(geom1, geom2);
bool disjoint   = DisjointOperator.Instance.Execute(geom1, geom2);
bool within     = WithinOperator.Instance.Execute(geom1, geom2);
bool crosses    = CrossesOperator.Instance.Execute(geom1, geom2);
bool touches    = TouchesOperator.Instance.Execute(geom1, geom2);
bool overlaps   = OverlapsOperator.Instance.Execute(geom1, geom2);

// 集合运算
Geometry union        = UnionOperator.Instance.Execute(geom1, geom2);
Geometry intersection = IntersectionOperator.Instance.Execute(geom1, geom2);
Geometry difference   = DifferenceOperator.Instance.Execute(geom1, geom2);
Geometry symDiff      = SymmetricDifferenceOperator.Instance.Execute(geom1, geom2);

// 一元运算
Geometry buffer     = BufferOperator.Instance.Execute(geometry, distance);
Geometry convexHull = ConvexHullOperator.Instance.Execute(geometry);
Geometry simplified = SimplifyOperator.Instance.Execute(geometry, tolerance);
Point    centroid   = CentroidOperator.Instance.Execute(geometry);
Geometry boundary   = BoundaryOperator.Instance.Execute(geometry);
double   area       = AreaOperator.Instance.Execute(geometry);
double   length     = LengthOperator.Instance.Execute(geometry);
Geometry offset     = OffsetOperator.Instance.Execute(geometry, distance);

// 大地测量
double geodesicDist = GeodesicDistanceOperator.Instance.Execute(point1, point2);
double geodesicArea = GeodesicAreaOperator.Instance.Execute(polygon);

// 邻近搜索
Proximity2DResult result = Proximity2DOperator.Instance.GetNearestCoordinate(geometry, point, testPolygonInterior);
Proximity2DResult result = Proximity2DOperator.Instance.GetNearestVertex(geometry, point);
Proximity2DResult[] results = Proximity2DOperator.Instance.GetNearestVertices(geometry, point, searchRadius, maxVertexCount);

Serialization Formats

WKT（Well-Known Text）

using OpenGIS.Esri.Geometry.Core.IO;

// 导出
string wkt = WktExportOperator.ExportToWkt(geometry);
// "POINT (10.5 20.7)"
// "POINT Z (10.5 20.7 30.1)"
// "LINESTRING (0 0, 10 0, 10 10)"
// "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"
// "MULTIPOINT ((1 2), (3 4))"

// 导入
Geometry geometry = WktImportOperator.ImportFromWkt("POINT (10.5 20.7)");

WKB（Well-Known Binary）

// 导出（默认小端序）
byte[] wkb = WkbExportOperator.ExportToWkb(geometry);
byte[] wkb = WkbExportOperator.ExportToWkb(geometry, bigEndian: true);

// 导入（自动检测字节序）
Geometry geometry = WkbImportOperator.ImportFromWkb(wkbBytes);

GeoJSON

// 导出
string geoJson = GeoJsonExportOperator.ExportToGeoJson(geometry);
// {"type":"Point","coordinates":[10.5,20.7]}

// 导入
Geometry geometry = GeoJsonImportOperator.ImportFromGeoJson(geoJsonString);

Esri JSON

// 导出
string esriJson = EsriJsonExportOperator.Instance.Execute(geometry);
// Point:      {"x":10.5,"y":20.7}
// MultiPoint: {"points":[[1,2],[3,4]]}
// Polyline:   {"paths":[[[0,0],[10,0],[10,10]]]}
// Polygon:    {"rings":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]}
// Envelope:   {"xmin":0,"ymin":0,"xmax":10,"ymax":10}

// 导入
Geometry geometry = EsriJsonImportOperator.ImportFromEsriJson(esriJsonString);

System.Text.Json Integration

using OpenGIS.Esri.Geometry.Json.Converters;

var options = new JsonSerializerOptions();
options.Converters.Add(new PointJsonConverter());

string json = JsonSerializer.Serialize(point, options);
Point point = JsonSerializer.Deserialize<Point>(json, options);

Spatial Reference

using OpenGIS.Esri.Geometry.Core.SpatialReference;

// 预定义空间参考
var wgs84 = SpatialReference.Wgs84();          // EPSG:4326 (经纬度)
var webMercator = SpatialReference.WebMercator(); // EPSG:3857 (Web 墨卡托)

// 自定义 WKID
var sr = new SpatialReference(4490);            // CGCS2000

// 属性
sr.Wkid         // int?, WKID 编号
sr.LatestWkid   // int?, 最新 WKID
sr.Wkt          // string?, WKT 表示

// 组合几何与空间参考
var mapGeom = new MapGeometry(geometry, SpatialReference.Wgs84());
mapGeom.Geometry         // Geometry 对象
mapGeom.SpatialReference // SpatialReference 对象

Proximity2DResult (Proximity Search Result)

Proximity2DResult result = GeometryEngine.GetNearestCoordinate(geometry, point);

result.IsEmpty       // bool, 结果是否为空
result.Coordinate    // Point, 最近坐标点
result.VertexIndex   // int, 最近顶点索引
result.Distance      // double, 距离
result.IsRightSide   // bool, 是否在多路径几何的右侧

Common Development Scenarios

Scenario 1: Determine Whether a Point Is Inside a Polygon

var polygon = new Polygon();
polygon.AddRing(new[] {
    new Point(0, 0), new Point(10, 0), new Point(10, 10),
    new Point(0, 10), new Point(0, 0)
});
var point = new Point(5, 5);

bool inside = GeometryEngine.Contains(polygon, point);  // true

Scenario 2: Calculate the Geodesic Distance (in Meters) Between Two Longitude/Latitude Points

var beijing = new Point(116.4074, 39.9042);
var shanghai = new Point(121.4737, 31.2304);

double meters = GeometryEngine.GeodesicDistance(beijing, shanghai);

Scenario 3: Create a Buffer

var point = new Point(10, 20);
Geometry buffer = GeometryEngine.Buffer(point, 5.0);  // 半径为 5 的缓冲区

var envelope = buffer.GetEnvelope();
// XMin=5, YMin=15, XMax=15, YMax=25

Scenario 4: Calculate the Intersection of Two Regions

var env1 = new Envelope(0, 0, 10, 10);
var env2 = new Envelope(5, 5, 15, 15);

Geometry result = GeometryEngine.Intersection(env1, env2);
// 交集区域: (5,5) 到 (10,10)

Scenario 5: Merge Multiple Geometries

var p1 = new Point(0, 0);
var p2 = new Point(10, 10);

Geometry merged = GeometryEngine.Union(p1, p2);
// 结果为 MultiPoint，包含两个点

Scenario 6: GeoJSON Round-Trip Serialization

var polygon = new Polygon();
polygon.AddRing(new[] {
    new Point(0, 0), new Point(1, 0), new Point(1, 1),
    new Point(0, 1), new Point(0, 0)
});

string geoJson = GeometryEngine.GeometryToGeoJson(polygon);
Geometry restored = GeometryEngine.GeometryFromGeoJson(geoJson);

Scenario 7: Import a Geometry from WKT and Perform Spatial Analysis

var geom1 = GeometryEngine.GeometryFromWkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))");
var geom2 = GeometryEngine.GeometryFromWkt("POINT (5 5)");

bool contains = GeometryEngine.Contains(geom1, geom2);  // true
double distance = GeometryEngine.Distance(geom1, geom2); // 0

Scenario 8: Get the Convex Hull of a Geometry

var multiPoint = new MultiPoint(new[] {
    new Point(0, 0), new Point(10, 0), new Point(5, 10),
    new Point(3, 3), new Point(7, 2)
});

Geometry hull = GeometryEngine.ConvexHull(multiPoint);
// 结果为包围所有点的最小凸多边形

Scenario 9: Calculate the Centroid of a Polygon

var polygon = new Polygon();
polygon.AddRing(new[] {
    new Point(0, 0), new Point(10, 0), new Point(10, 10),
    new Point(0, 10), new Point(0, 0)
});

Point centroid = GeometryEngine.Centroid(polygon);
// centroid.X = 5, centroid.Y = 5

Scenario 10: Line Simplification and Densification

var polyline = new Polyline();
polyline.AddPath(new[] {
    new Point(0, 0), new Point(5, 0.1), new Point(10, 0),
    new Point(10, 5), new Point(10, 10)
});

// 简化：移除偏差小于 tolerance 的顶点
Geometry simplified = GeometryEngine.Simplify(polyline, 0.5);

// 加密：确保每段不超过 maxSegmentLength
Geometry densified = GeometryEngine.Densify(polyline, 2.0);

// 泛化：保持形状前提下减少顶点
Geometry generalized = GeometryEngine.Generalize(polyline, 1.0);

Build and Test

# 构建
dotnet build

# 运行测试（xUnit）
dotnet test

# 运行示例
dotnet run --project samples/OpenGIS.Esri.Geometry.Samples

Notes

  1. Polygon rings must be closed: the first and last points must be the same
  2. Floating-point tolerance: internally uses GeometryConstants.DefaultTolerance(1e-10) for floating-point comparison; this value is an internal constant and cannot be configured externally
  3. Return types need casting: set operations return the Geometry base class, and casting must be done according to the actual type
  4. Operator uses Lazy singleton: all Operator classes obtain singleton instances through the Instance property
  5. Collection getters return read-only views：GetRing(), GetPath() etc. return IReadOnlyList<Point>
  6. Geodesic measurement is based on WGS84：GeodesicDistance uses the Vincenty formula, andGeodesicArea uses the spherical excess formula
  7. GeoJSON export rules: a single-path Polyline is exported as LineString, multiple paths are exported as MultiLineString; Envelope is exported as Polygon