第二章：快速开始指南

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 性能建议

1. 复用操作符实例：操作符已是单例，直接使用 Instance 属性
2. 避免频繁创建几何对象：尽量复用几何对象
3. 使用简单几何类型：Point 比 MultiPoint 更高效
4. 合理使用简化：大数据量时先简化再处理

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 下一步

恭喜您完成了快速开始指南！接下来，您可以：

1. 阅读 第三章：核心几何类型详解，深入了解各种几何类型
2. 阅读 第四章：空间关系操作符，掌握空间关系测试
3. 查看 samples/Esri.Geometry.Samples 目录中的更多示例
4. 运行测试用例，了解各功能的预期行为

2.8 小结

本章我们学习了：

1. 如何搭建开发环境和构建项目
2. 如何创建第一个使用 geometry-api-net 的程序
3. 核心 API 的快速预览
4. 五个常见使用场景的代码示例
5. API 使用建议和常见错误

geometry-api-net 的 API 设计简洁直观，通过 GeometryEngine 可以快速上手大多数几何计算任务。在后续章节中，我们将深入探讨每个功能模块的详细用法和实现原理。

---