第二章：快速开始指南
2.1 环境准备
2.1.1 前提条件
在开始使用 geometry-api-net 之前，请确保您的开发环境满足以下条件：
- .NET SDK：8.0 或更高版本（推荐使用最新 LTS 版本）
- IDE：Visual Studio 2022、VS Code 或 JetBrains Rider
- 操作系统：Windows、macOS 或 Linux
2.1.2 验证 .NET SDK 安装
打开终端或命令提示符，运行以下命令验证 .NET SDK 是否正确安装：
dotnet --version
预期输出类似于：
8.0.100
2.1.3 获取源代码
geometry-api-net 目前托管在 GitHub 上，可以通过以下方式获取：
# 克隆仓库
git clone https://github.com/znlgis/geometry-api-net.git# 进入项目目录
cd geometry-api-net
2.2 构建项目
2.2.1 还原依赖项
# 还原所有项目的依赖项
dotnet restore
2.2.2 编译项目
# 编译整个解决方案
dotnet build
成功编译后，您将看到类似以下输出：
Microsoft (R) Build Engine version 17.x.x
...
Build succeeded.0 Warning(s)0 Error(s)
2.2.3 运行测试
# 运行所有测试
dotnet test# 运行测试并显示详细输出
dotnet test --logger "console;verbosity=detailed"
2.2.4 运行示例程序
# 进入示例项目目录
cd samples/Esri.Geometry.Samples# 运行示例
dotnet run
2.3 创建第一个项目
2.3.1 创建控制台应用程序
# 创建新的控制台项目
dotnet new console -n GeometryDemo# 进入项目目录
cd GeometryDemo
2.3.2 添加项目引用
如果 geometry-api-net 已发布为 NuGet 包，可以直接添加包引用：
dotnet add package Esri.Geometry.Core
或者，添加本地项目引用：
<!-- 编辑 GeometryDemo.csproj -->
<ItemGroup><ProjectReference Include="../path/to/Esri.Geometry.Core/Esri.Geometry.Core.csproj" />
</ItemGroup>
2.3.3 编写第一个程序
编辑 Program.cs 文件：
using Esri.Geometry.Core;
using Esri.Geometry.Core.Geometries;
using Esri.Geometry.Core.Operators;
using Esri.Geometry.Core.IO;Console.WriteLine("=== geometry-api-net 快速开始 ===\n");// 1. 创建点
var point = new Point(116.4074, 39.9042);
Console.WriteLine($"创建了一个点：({point.X}, {point.Y})");
Console.WriteLine($"这是北京市中心的经纬度坐标\n");// 2. 创建包络矩形
var envelope = new Envelope(116.2, 39.7, 116.6, 40.1);
Console.WriteLine($"创建了一个包络矩形：");
Console.WriteLine($" 左下角：({envelope.XMin}, {envelope.YMin})");
Console.WriteLine($" 右上角：({envelope.XMax}, {envelope.YMax})");
Console.WriteLine($" 宽度：{envelope.Width}");
Console.WriteLine($" 高度：{envelope.Height}\n");// 3. 测试空间关系
bool contains = envelope.Contains(point);
Console.WriteLine($"包络矩形是否包含该点？{(contains ? "是" : "否")}\n");// 4. 创建多边形
var polygon = new Polygon();
polygon.AddRing(new List<Point>
{new Point(116.3, 39.8),new Point(116.5, 39.8),new Point(116.5, 40.0),new Point(116.3, 40.0),new Point(116.3, 39.8) // 闭合环
});
Console.WriteLine($"创建了一个矩形多边形");
Console.WriteLine($" 面积：{polygon.Area:F6} 平方度\n");// 5. 使用操作符测试包含关系
var containsOp = ContainsOperator.Instance;
bool pointInPolygon = containsOp.Execute(polygon, point);
Console.WriteLine($"多边形是否包含该点？{(pointInPolygon ? "是" : "否")}\n");// 6. 导出为 WKT
string wkt = WktExportOperator.ExportToWkt(polygon);
Console.WriteLine($"多边形的 WKT 表示：\n{wkt}\n");// 7. 导出为 GeoJSON
string geoJson = GeoJsonExportOperator.ExportToGeoJson(point);
Console.WriteLine($"点的 GeoJSON 表示：\n{geoJson}\n");// 8. 使用 GeometryEngine（简化 API）
var point2 = new Point(116.3976, 39.9095);
double distance = GeometryEngine.Distance(point, point2);
Console.WriteLine($"两点之间的距离：{distance:F6} 度");// 计算大地测量距离
double geodesicDistance = GeometryEngine.GeodesicDistance(point, point2);
Console.WriteLine($"两点之间的大地测量距离：{geodesicDistance:F2} 米\n");Console.WriteLine("=== 演示完成 ===");
2.3.4 运行程序
dotnet run
预期输出：
=== geometry-api-net 快速开始 ===创建了一个点：(116.4074, 39.9042)
这是北京市中心的经纬度坐标创建了一个包络矩形：左下角：(116.2, 39.7)右上角：(116.6, 40.1)宽度：0.4高度：0.4包络矩形是否包含该点？是创建了一个矩形多边形面积：0.040000 平方度多边形是否包含该点？是多边形的 WKT 表示：
POLYGON ((116.3 39.8, 116.5 39.8, 116.5 40, 116.3 40, 116.3 39.8))点的 GeoJSON 表示：
{"type":"Point","coordinates":[116.4074,39.9042]}两点之间的距离：0.013096 度
两点之间的大地测量距离：1232.45 米=== 演示完成 ===
2.4 核心 API 快速预览
2.4.1 几何对象创建
// 点
var point = new Point(x, y);
var point3D = new Point(x, y, z);// 多点
var multiPoint = new MultiPoint();
multiPoint.Add(new Point(x1, y1));
multiPoint.Add(new Point(x2, y2));// 折线
var polyline = new Polyline();
polyline.AddPath(new List<Point> { p1, p2, p3 });// 多边形
var polygon = new Polygon();
polygon.AddRing(new List<Point> { p1, p2, p3, p4, p1 }); // 必须闭合// 包络矩形
var envelope = new Envelope(xMin, yMin, xMax, yMax);
2.4.2 空间关系测试
// 使用 GeometryEngine（推荐）
bool contains = GeometryEngine.Contains(polygon, point);
bool intersects = GeometryEngine.Intersects(g1, g2);
double distance = GeometryEngine.Distance(g1, g2);
bool equals = GeometryEngine.Equals(g1, g2);
bool disjoint = GeometryEngine.Disjoint(g1, g2);
bool within = GeometryEngine.Within(g1, g2);
bool crosses = GeometryEngine.Crosses(g1, g2);
bool touches = GeometryEngine.Touches(g1, g2);
bool overlaps = GeometryEngine.Overlaps(g1, g2);// 使用操作符（高级用法）
var op = ContainsOperator.Instance;
bool result = op.Execute(geometry1, geometry2);
2.4.3 几何运算
// 缓冲区
var buffer = GeometryEngine.Buffer(point, distance);// 凸包
var hull = GeometryEngine.ConvexHull(multiPoint);// 质心
var centroid = GeometryEngine.Centroid(polygon);// 面积和长度
double area = GeometryEngine.Area(polygon);
double length = GeometryEngine.Length(polyline);// 简化
var simplified = GeometryEngine.Simplify(polyline, tolerance);// 概化
var generalized = GeometryEngine.Generalize(polyline, maxDeviation);// 密化
var densified = GeometryEngine.Densify(polyline, maxSegmentLength);
2.4.4 集合运算
// 并集
var union = GeometryEngine.Union(g1, g2);// 交集
var intersection = GeometryEngine.Intersection(g1, g2);// 差集
var difference = GeometryEngine.Difference(g1, g2);// 对称差
var symDiff = GeometryEngine.SymmetricDifference(g1, g2);
2.4.5 数据格式转换
// WKT
string wkt = GeometryEngine.GeometryToWkt(geometry);
var geom = GeometryEngine.GeometryFromWkt(wkt);// WKB
byte[] wkb = GeometryEngine.GeometryToWkb(geometry);
var geom2 = GeometryEngine.GeometryFromWkb(wkb);// GeoJSON
string json = GeometryEngine.GeometryToGeoJson(geometry);
var geom3 = GeometryEngine.GeometryFromGeoJson(json);// Esri JSON
string esriJson = GeometryEngine.GeometryToEsriJson(geometry);
var geom4 = GeometryEngine.GeometryFromEsriJson(esriJson);
2.5 常见使用场景
2.5.1 场景一：判断点是否在区域内
using Esri.Geometry.Core;
using Esri.Geometry.Core.Geometries;// 定义服务区域（北京五环内）
var serviceArea = new Polygon();
serviceArea.AddRing(new List<Point>
{new Point(116.1, 39.7),new Point(116.7, 39.7),new Point(116.7, 40.1),new Point(116.1, 40.1),new Point(116.1, 39.7)
});// 用户位置
var userLocation = new Point(116.4074, 39.9042);// 判断用户是否在服务区域内
bool inServiceArea = GeometryEngine.Contains(serviceArea, userLocation);if (inServiceArea)
{Console.WriteLine("您在服务区域内，可以正常使用服务");
}
else
{Console.WriteLine("抱歉，您不在服务区域内");
}
2.5.2 场景二：计算两个城市之间的距离
using Esri.Geometry.Core;
using Esri.Geometry.Core.Geometries;// 城市坐标（经度, 纬度）
var beijing = new Point(116.4074, 39.9042); // 北京
var shanghai = new Point(121.4737, 31.2304); // 上海// 计算大地测量距离
double distanceMeters = GeometryEngine.GeodesicDistance(beijing, shanghai);
double distanceKm = distanceMeters / 1000;Console.WriteLine($"北京到上海的直线距离：{distanceKm:F2} 公里");
// 输出：北京到上海的直线距离：1067.89 公里
2.5.3 场景三：创建地理围栏缓冲区
using Esri.Geometry.Core;
using Esri.Geometry.Core.Geometries;// 商店位置
var storeLocation = new Point(116.4074, 39.9042);// 创建 1 公里（约 0.01 度）的配送范围
var deliveryZone = GeometryEngine.Buffer(storeLocation, 0.01);// 顾客位置
var customerLocation = new Point(116.41, 39.905);// 判断是否可配送
bool canDeliver = GeometryEngine.Contains(deliveryZone, customerLocation);
Console.WriteLine($"是否可配送：{(canDeliver ? "是" : "否")}");
2.5.4 场景四：轨迹数据简化
using Esri.Geometry.Core;
using Esri.Geometry.Core.Geometries;// 原始 GPS 轨迹（包含大量点）
var track = new Polyline();
track.AddPath(new List<Point>
{new Point(116.400, 39.900),new Point(116.401, 39.901),new Point(116.402, 39.902),new Point(116.403, 39.903),new Point(116.404, 39.904),// ... 更多点
});Console.WriteLine($"原始轨迹点数：{track.GetPath(0).Count}");// 使用 Douglas-Peucker 算法简化
var simplifiedTrack = GeometryEngine.Simplify(track, tolerance: 0.001);if (simplifiedTrack is Polyline simplified)
{Console.WriteLine($"简化后点数：{simplified.GetPath(0).Count}");
}
2.5.5 场景五：从 WKT 加载地理数据
using Esri.Geometry.Core;
using Esri.Geometry.Core.IO;// 从数据库或文件读取的 WKT 字符串
string wkt = "POLYGON ((116.3 39.8, 116.5 39.8, 116.5 40.0, 116.3 40.0, 116.3 39.8))";// 解析 WKT
var geometry = WktImportOperator.ImportFromWkt(wkt);if (geometry is Polygon polygon)
{Console.WriteLine($"加载了一个多边形");Console.WriteLine($"环数：{polygon.RingCount}");Console.WriteLine($"面积：{polygon.Area}");// 导出为 GeoJSON 供前端使用string geoJson = GeoJsonExportOperator.ExportToGeoJson(polygon);Console.WriteLine($"GeoJSON：{geoJson}");
}
2.6 API 使用建议
2.6.1 GeometryEngine vs 操作符
| 场景 | 推荐方式 | 原因 |
|---|---|---|
| 日常开发 | GeometryEngine | 代码简洁，易于理解 |
| 批量处理 | 操作符 | 避免方法调用开销 |
| 需要传递空间参考 | 操作符 | GeometryEngine 不支持 |
| 单元测试 | 操作符 | 更容易模拟和测试 |
2.6.2 性能建议
- 复用操作符实例：操作符已是单例，直接使用
Instance属性 - 避免频繁创建几何对象：尽量复用几何对象
- 使用简单几何类型：Point 比 MultiPoint 更高效
- 合理使用简化：大数据量时先简化再处理
2.6.3 常见错误
// ❌ 错误：多边形环未闭合
var polygon = new Polygon();
polygon.AddRing(new List<Point>
{new Point(0, 0),new Point(10, 0),new Point(10, 10),new Point(0, 10) // 缺少闭合点
});// ✅ 正确：确保环闭合
polygon.AddRing(new List<Point>
{new Point(0, 0),new Point(10, 0),new Point(10, 10),new Point(0, 10),new Point(0, 0) // 闭合
});// ❌ 错误：直接比较几何对象
if (point1 == point2) { } // 可能不如预期// ✅ 正确：使用操作符比较
if (GeometryEngine.Equals(point1, point2)) { }
2.7 下一步
恭喜您完成了快速开始指南！接下来，您可以：
- 阅读 第三章：核心几何类型详解，深入了解各种几何类型
- 阅读 第四章：空间关系操作符，掌握空间关系测试
- 查看
samples/Esri.Geometry.Samples目录中的更多示例 - 运行测试用例，了解各功能的预期行为
2.8 小结
本章我们学习了：
- 如何搭建开发环境和构建项目
- 如何创建第一个使用 geometry-api-net 的程序
- 核心 API 的快速预览
- 五个常见使用场景的代码示例
- API 使用建议和常见错误
geometry-api-net 的 API 设计简洁直观，通过 GeometryEngine 可以快速上手大多数几何计算任务。在后续章节中，我们将深入探讨每个功能模块的详细用法和实现原理。
