第九章：邻近分析与位置服务

9.1 概述

邻近分析是 GIS 中最常用的分析类型之一，用于查找几何对象上最近的点或顶点。geometry-api-net 通过 Proximity2DOperator 提供了强大的邻近分析功能。

9.1.1 应用场景

9.1.2 核心类

// 操作符
public class Proximity2DOperator
{
    public static Proximity2DOperator Instance { get; }
    
    // 查找最近坐标（可以在边上）
    public Proximity2DResult GetNearestCoordinate(
        Geometry geometry, Point inputPoint, bool testPolygonInterior = false);
    
    // 查找最近顶点
    public Proximity2DResult GetNearestVertex(
        Geometry geometry, Point inputPoint);
    
    // 查找指定范围内的多个顶点
    public Proximity2DResult[] GetNearestVertices(
        Geometry geometry, Point inputPoint, 
        double searchRadius, int maxVertexCount = int.MaxValue);
}

// 结果类
public class Proximity2DResult
{
    public Point Coordinate { get; }     // 最近坐标
    public int VertexIndex { get; }      // 顶点索引
    public double Distance { get; }      // 距离
    public bool IsEmpty { get; }         // 是否为空结果
}

9.2 查找最近坐标

9.2.1 概念

GetNearestCoordinate 方法查找几何对象上距离查询点最近的坐标。这个坐标可以在顶点上，也可以在边的中间位置。

9.2.2 基本使用

using Esri.Geometry.Core;
using Esri.Geometry.Core.Geometries;
using Esri.Geometry.Core.Operators;

// 创建一条折线
var polyline = new Polyline();
polyline.AddPath(new List<Point>
{
    new Point(0, 0),
    new Point(10, 0),
    new Point(10, 10)
});

// 查询点
var queryPoint = new Point(5, 5);

// 查找最近坐标
var result = GeometryEngine.GetNearestCoordinate(polyline, queryPoint);

Console.WriteLine($"最近坐标：({result.Coordinate.X}, {result.Coordinate.Y})");
Console.WriteLine($"距离：{result.Distance:F4}");
Console.WriteLine($"顶点索引：{result.VertexIndex}");
// 最近坐标在 (10, 5)，是从 (10, 0) 到 (10, 10) 边上的点

9.2.3 点在多边形内测试

// 创建多边形
var polygon = new Polygon();
polygon.AddRing(new List<Point>
{
    new Point(0, 0),
    new Point(100, 0),
    new Point(100, 100),
    new Point(0, 100),
    new Point(0, 0)
});

// 测试点
var pointInside = new Point(50, 50);
var pointOutside = new Point(150, 50);

// testPolygonInterior = true 时，如果点在多边形内部，返回该点本身，距离为 0
var resultInside = GeometryEngine.GetNearestCoordinate(polygon, pointInside, testPolygonInterior: true);
Console.WriteLine($"内部点距离：{resultInside.Distance}");  // 0

var resultOutside = GeometryEngine.GetNearestCoordinate(polygon, pointOutside, testPolygonInterior: true);
Console.WriteLine($"外部点距离：{resultOutside.Distance}");  // 50

// testPolygonInterior = false（默认）时，返回边界上的最近点
var resultBoundary = GeometryEngine.GetNearestCoordinate(polygon, pointInside, testPolygonInterior: false);
Console.WriteLine($"到边界的距离：{resultBoundary.Distance}");  // 50

9.2.4 不同几何类型

// Point - 返回该点
var point = new Point(10, 10);
var result1 = GeometryEngine.GetNearestCoordinate(point, new Point(5, 5));
Console.WriteLine($"点距离：{result1.Distance:F2}");  // ~7.07

// MultiPoint - 返回最近的点
var multiPoint = new MultiPoint();
multiPoint.Add(new Point(0, 0));
multiPoint.Add(new Point(10, 10));
multiPoint.Add(new Point(20, 20));
var result2 = GeometryEngine.GetNearestCoordinate(multiPoint, new Point(12, 12));
Console.WriteLine($"最近点：({result2.Coordinate.X}, {result2.Coordinate.Y})");  // (10, 10)

// Envelope - 返回边界上的最近点
var envelope = new Envelope(0, 0, 100, 100);
var result3 = GeometryEngine.GetNearestCoordinate(envelope, new Point(50, 150));
Console.WriteLine($"最近坐标：({result3.Coordinate.X}, {result3.Coordinate.Y})");  // (50, 100)

9.3 查找最近顶点

9.3.1 概念

GetNearestVertex 方法只在几何对象的顶点中查找，不考虑边上的点。

9.3.2 使用示例

// 创建折线
var polyline = new Polyline();
polyline.AddPath(new List<Point>
{
    new Point(0, 0),
    new Point(10, 0),
    new Point(10, 10),
    new Point(0, 10)
});

var queryPoint = new Point(8, 8);

// 查找最近顶点
var result = GeometryEngine.GetNearestVertex(polyline, queryPoint);

Console.WriteLine($"最近顶点：({result.Coordinate.X}, {result.Coordinate.Y})");  // (10, 10)
Console.WriteLine($"顶点索引：{result.VertexIndex}");  // 2
Console.WriteLine($"距离：{result.Distance:F4}");

9.3.3 与 GetNearestCoordinate 比较

var polyline = new Polyline();
polyline.AddPath(new List<Point>
{
    new Point(0, 0),
    new Point(10, 0)
});

var queryPoint = new Point(5, 3);

// GetNearestCoordinate - 返回边上的点 (5, 0)
var coordResult = GeometryEngine.GetNearestCoordinate(polyline, queryPoint);
Console.WriteLine($"最近坐标：({coordResult.Coordinate.X}, {coordResult.Coordinate.Y})");
// 输出：(5, 0)

// GetNearestVertex - 返回顶点 (0, 0) 或 (10, 0)
var vertexResult = GeometryEngine.GetNearestVertex(polyline, queryPoint);
Console.WriteLine($"最近顶点：({vertexResult.Coordinate.X}, {vertexResult.Coordinate.Y})");
// 输出：(0, 0) 或 (10, 0)（取决于哪个更近）

9.4 范围内查找多个顶点

9.4.1 概念

GetNearestVertices 方法查找指定搜索半径内的所有顶点，并按距离排序返回。

9.4.2 使用示例

// 创建多点
var multiPoint = new MultiPoint();
multiPoint.Add(new Point(0, 0));
multiPoint.Add(new Point(10, 10));
multiPoint.Add(new Point(20, 20));
multiPoint.Add(new Point(30, 30));
multiPoint.Add(new Point(100, 100));

var queryPoint = new Point(15, 15);
double searchRadius = 20;

// 查找范围内的所有顶点
var results = GeometryEngine.GetNearestVertices(multiPoint, queryPoint, searchRadius);

Console.WriteLine($"找到 {results.Length} 个顶点在 {searchRadius} 范围内：");
foreach (var result in results)
{
    Console.WriteLine($"  ({result.Coordinate.X}, {result.Coordinate.Y}) - 距离：{result.Distance:F2}");
}
// 输出按距离排序

9.4.3 限制返回数量

// 只返回最近的 3 个顶点
var results = GeometryEngine.GetNearestVertices(
    multiPoint, 
    queryPoint, 
    searchRadius: 100, 
    maxVertexCount: 3);

Console.WriteLine($"最近的 {results.Length} 个顶点：");

9.4.4 折线和多边形

// 折线的顶点搜索
var polyline = new Polyline();
polyline.AddPath(new List<Point>
{
    new Point(0, 0),
    new Point(5, 0),
    new Point(10, 0),
    new Point(10, 5),
    new Point(10, 10)
});

var queryPoint = new Point(6, 3);
var results = GeometryEngine.GetNearestVertices(polyline, queryPoint, 10);

foreach (var result in results)
{
    Console.WriteLine($"顶点 {result.VertexIndex}: ({result.Coordinate.X}, {result.Coordinate.Y}) - {result.Distance:F2}");
}

9.5 实际应用案例

9.5.1 案例一：查找最近的商店

public class Store
{
    public int Id { get; set; }
    public string Name { get; set; }
    public Point Location { get; set; }
}

public class LocationService
{
    private List<Store> _stores;
    
    public Store FindNearestStore(Point userLocation)
    {
        Store nearest = null;
        double minDistance = double.MaxValue;
        
        foreach (var store in _stores)
        {
            double distance = GeometryEngine.Distance(userLocation, store.Location);
            if (distance < minDistance)
            {
                minDistance = distance;
                nearest = store;
            }
        }
        
        return nearest;
    }
    
    public List<Store> FindStoresWithinRadius(Point userLocation, double radiusDegrees)
    {
        // 将商店位置转换为 MultiPoint
        var storePoints = new MultiPoint();
        foreach (var store in _stores)
        {
            storePoints.Add(store.Location);
        }
        
        // 查找范围内的所有顶点
        var results = GeometryEngine.GetNearestVertices(
            storePoints, userLocation, radiusDegrees);
        
        // 根据顶点索引获取商店
        return results.Select(r => _stores[r.VertexIndex]).ToList();
    }
}

9.5.2 案例二：GPS 捕捉到道路

public class RoadSnapService
{
    private Polyline _roadNetwork;
    
    public Point SnapToRoad(Point gpsPoint)
    {
        // 查找道路上最近的坐标
        var result = GeometryEngine.GetNearestCoordinate(_roadNetwork, gpsPoint);
        
        if (result.Distance > 50)  // 如果距离太远，可能不在道路上
        {
            Console.WriteLine($"警告：距离道路 {result.Distance:F2} 米");
        }
        
        return result.Coordinate;
    }
    
    public Polyline SnapTrack(List<Point> gpsTrack)
    {
        var snappedPoints = new List<Point>();
        
        foreach (var gpsPoint in gpsTrack)
        {
            var result = GeometryEngine.GetNearestCoordinate(_roadNetwork, gpsPoint);
            snappedPoints.Add(result.Coordinate);
        }
        
        var snappedTrack = new Polyline();
        snappedTrack.AddPath(snappedPoints);
        return snappedTrack;
    }
}

9.5.3 案例三：编辑器顶点捕捉

public class GeometryEditor
{
    private List<Geometry> _features = new();
    private double _snapTolerance = 5.0;  // 像素或单位
    
    public Point? GetSnapPoint(Point mouseLocation)
    {
        Point? bestSnapPoint = null;
        double bestDistance = _snapTolerance;
        
        foreach (var feature in _features)
        {
            // 首先尝试捕捉到顶点
            var vertexResult = GeometryEngine.GetNearestVertex(feature, mouseLocation);
            if (vertexResult.Distance < bestDistance)
            {
                bestDistance = vertexResult.Distance;
                bestSnapPoint = vertexResult.Coordinate;
            }
            
            // 如果没有找到顶点，尝试捕捉到边
            if (bestSnapPoint == null)
            {
                var coordResult = GeometryEngine.GetNearestCoordinate(feature, mouseLocation);
                if (coordResult.Distance < bestDistance)
                {
                    bestDistance = coordResult.Distance;
                    bestSnapPoint = coordResult.Coordinate;
                }
            }
        }
        
        return bestSnapPoint;
    }
}

9.5.4 案例四：配送区域分析

public class DeliveryService
{
    private Point _warehouseLocation;
    private Polygon _deliveryZone;
    
    public (bool canDeliver, double distance) CheckDelivery(Point customerLocation)
    {
        // 检查是否在配送区域内
        bool inZone = GeometryEngine.Contains(_deliveryZone, customerLocation);
        
        // 计算距离
        var result = GeometryEngine.GetNearestCoordinate(
            new Point(_warehouseLocation.X, _warehouseLocation.Y), 
            customerLocation);
        
        // 使用大地测量距离获取实际距离
        double distance = GeometryEngine.GeodesicDistance(_warehouseLocation, customerLocation);
        
        return (inZone, distance);
    }
    
    public double CalculateDistanceToZoneBorder(Point customerLocation)
    {
        if (GeometryEngine.Contains(_deliveryZone, customerLocation))
        {
            // 客户在区域内，计算到边界的距离
            var result = GeometryEngine.GetNearestCoordinate(
                _deliveryZone, customerLocation, testPolygonInterior: false);
            return result.Distance;
        }
        else
        {
            // 客户在区域外，计算到区域的距离
            var result = GeometryEngine.GetNearestCoordinate(
                _deliveryZone, customerLocation);
            return result.Distance;
        }
    }
}

9.6 性能优化

9.6.1 空间索引建议

对于大量几何对象，应使用空间索引提高性能：

// 简单的网格索引示例
public class SpatialIndex
{
    private Dictionary<(int, int), List<int>> _grid = new();
    private List<Point> _points;
    private double _cellSize;
    
    public SpatialIndex(List<Point> points, double cellSize)
    {
        _points = points;
        _cellSize = cellSize;
        
        for (int i = 0; i < points.Count; i++)
        {
            var cell = GetCell(points[i]);
            if (!_grid.ContainsKey(cell))
                _grid[cell] = new List<int>();
            _grid[cell].Add(i);
        }
    }
    
    private (int, int) GetCell(Point p)
    {
        return ((int)(p.X / _cellSize), (int)(p.Y / _cellSize));
    }
    
    public List<Point> GetNearbyPoints(Point queryPoint, double radius)
    {
        var results = new List<Point>();
        var queryCell = GetCell(queryPoint);
        int cellRadius = (int)Math.Ceiling(radius / _cellSize);
        
        for (int dx = -cellRadius; dx <= cellRadius; dx++)
        {
            for (int dy = -cellRadius; dy <= cellRadius; dy++)
            {
                var cell = (queryCell.Item1 + dx, queryCell.Item2 + dy);
                if (_grid.TryGetValue(cell, out var indices))
                {
                    foreach (var i in indices)
                    {
                        if (GeometryEngine.Distance(_points[i], queryPoint) <= radius)
                            results.Add(_points[i]);
                    }
                }
            }
        }
        
        return results;
    }
}

9.6.2 批量处理

// 预先计算包络矩形进行快速过滤
public List<(Geometry, Proximity2DResult)> BatchNearestSearch(
    List<Geometry> geometries, Point queryPoint, double maxDistance)
{
    var queryEnvelope = new Envelope(
        queryPoint.X - maxDistance,
        queryPoint.Y - maxDistance,
        queryPoint.X + maxDistance,
        queryPoint.Y + maxDistance);
    
    var results = new List<(Geometry, Proximity2DResult)>();
    
    foreach (var geom in geometries)
    {
        // 快速过滤
        if (!geom.GetEnvelope().Intersects(queryEnvelope))
            continue;
        
        // 精确计算
        var result = GeometryEngine.GetNearestCoordinate(geom, queryPoint);
        if (result.Distance <= maxDistance)
        {
            results.Add((geom, result));
        }
    }
    
    return results.OrderBy(r => r.Item2.Distance).ToList();
}

9.7 小结

本章详细介绍了 geometry-api-net 的邻近分析功能：

1. GetNearestCoordinate：查找几何对象上最近的坐标（包括边上的点）
2. GetNearestVertex：只在顶点中查找最近点
3. GetNearestVertices：查找指定范围内的多个顶点

关键应用场景：

• 最近地点查找
• GPS 轨迹捕捉
• 编辑器顶点捕捉
• 配送区域分析

性能优化建议：

• 使用包络矩形快速过滤
• 对大数据集使用空间索引
• 批量处理时先过滤再计算

在下一章中，我们将学习高级应用与性能优化，探讨如何在实际项目中高效使用 geometry-api-net。