Projnet4geoapi

项目地址： https://github.com/NetTopologySuite/ProjNet4GeoAPI

NuGet（2.x）： ProjNet 2.1.0（netstandard2.0 / netstandard2.1，截至 2026-10）

NuGet（1.x，旧版）： ProjNet4GeoAPI 1.4.1（面向 GeoAPI 接口的项目，如 SharpMap 1.2）

官方文档： https://github.com/NetTopologySuite/ProjNet4GeoAPI/wiki

许可证： LGPL-2.1-or-later

维护状态： 上游 README 明确说明维护资源不足，官方给出的替代方案是 SharpProj、DotSpatial.Projections、GDAL；新项目在需要完整 EPSG 支持时应优先考虑这些方案。

概述

ProjNet 是 SharpMap 时代延续下来的 .NET 坐标参考系与投影引擎，按 OGC Simple Features 模型描述坐标系，负责「点对点」的坐标转换：源坐标系 → 目标坐标系，中间可能包含基准面转换（datum transformation）。它不提供地图渲染，也不自带 EPSG 数据库，坐标系定义要么用内置常量（WGS84、WebMercator），要么由调用方提供 WKT。

• 坐标系模型：地理坐标系、地心坐标系、投影坐标系、垂直坐标系、复合坐标系
• 转换能力：基准面转换、地理↔投影、投影↔投影，支持 Albers、Mercator、Transverse Mercator、Lambert Conformal Conic、Polar Stereographic、Krovak 等常用投影
• 定义读写：WKT 与 XML 互转（CreateFromWkt / CreateFromXml）
• 服务容器：CoordinateSystemServices 维护 SRID → 坐标系映射与转换工厂，默认只注册 EPSG:4326 与 EPSG:3857
• 两代包：2.x 用自带类型体系（ProjNet.CoordinateSystems），1.x 实现 GeoAPI 接口供 SharpMap 等老库使用

环境准备

安装（.NET 6+ / netstandard2.0 兼容项目）

bashCopy code
# 2.x 系列（推荐）
dotnet add package ProjNet --version 2.1.0

# 1.x 系列：只在必须实现 GeoAPI 接口的老项目里使用（如 SharpMap 1.2）
dotnet add package ProjNet4GeoAPI --version 1.4.1

powershellCopy code
# Package Manager Console
Install-Package ProjNet -Version 2.1.0

两个包的程序集名都是 ProjNET.dll，不能同时引用；同时引用会出现类型冲突与「找到多个同名类型」的编译错误。

验证

csharpCopy code
using ProjNet.CoordinateSystems;
using ProjNet.CoordinateSystems.Transformations;

var src = GeographicCoordinateSystem.WGS84;
var tgt = ProjectedCoordinateSystem.WebMercator;
var transform = new CoordinateTransformationFactory()
    .CreateFromCoordinateSystems(src, tgt);

double[] xy = transform.MathTransform.Transform(new[] {116.397, 39.908});
Console.WriteLine($"{xy[0]:F2}, {xy[1]:F2}");   // 约 12957254.80, 4852582.10

bashCopy code
dotnet run   # 能打印出 Web Mercator 米制坐标即环境正常

目标框架

核心 API

坐标系工厂

csharpCopy code
using ProjNet.CoordinateSystems;

var factory = new CoordinateSystemFactory();

// 从 WKT 解析（EPSG 官网、GDAL 的 projinfo、QGIS 都能导出 WKT）
CoordinateSystem wgs84Utm50 = factory.CreateFromWkt(wktText);

// 从 XML 解析
CoordinateSystem fromXml = factory.CreateFromXml(xmlText);

// 组合式构造：以已有地理坐标系 + 投影参数创建投影坐标系
var gcs = GeographicCoordinateSystem.WGS84;

内置常量只有少数几个：GeographicCoordinateSystem.WGS84、ProjectedCoordinateSystem.WebMercator。其余坐标系必须自带 WKT。

坐标转换

csharpCopy code
using ProjNet.CoordinateSystems;
using ProjNet.CoordinateSystems.Transformations;

var ctFactory = new CoordinateTransformationFactory();
ICoordinateTransformation ct = ctFactory.CreateFromCoordinateSystems(
    sourceCS: factory.CreateFromWkt(wgs84Wkt),
    targetCS: factory.CreateFromWkt(cgcs2000GaussKrugerWkt));

MathTransform mt = ct.MathTransform;

// 单点
double[] projected = mt.Transform(new[] {116.397, 39.908});

// 单点（元组重载，免去数组分配）
var (x, y) = mt.Transform(116.397, 39.908);

// 多点：一次调用处理整批，比循环 new 数组快得多
double[][] points = {new[] {116.0, 39.0}, new[] {117.0, 40.0}};
IList<double[]> projectedPoints = mt.TransformList(points);

坐标按 x, y 顺序解释（经度/东坐标在前，纬度/北坐标在后），ProjNet 不做轴序交换；若拿到的 WKT 声明了 AXIS["Latitude", NORTH] 之类的轴序，需要调用方自行判断是否交换。

CoordinateSystemServices：SRID 与转换缓存

csharpCopy code
using ProjNet.CoordinateSystems;
using ProjNet.CoordinateSystems.Transformations;

var services = new CoordinateSystemServices();

// 默认只有 4326 与 3857
var wgs84 = services.GetCoordinateSystem(4326);
var mercator = services.GetCoordinateSystem(3857);

// 注册任意 EPSG 编码（值为 WKT 字符串）
var defs = new[]
{
    new KeyValuePair<int, string>(4490, cgcs2000Wkt),
    new KeyValuePair<int, string>(4547, cgcs2000GkCmwWkt),
};
var withDefs = new CoordinateSystemServices(defs);

ICoordinateTransformation ct = withDefs.CreateTransformation(4490, 4547);
double[] xy = ct.MathTransform.Transform(new[] {116.397, 39.908});

失败的 WKT 会被静默跳过：CreateCoordinateSystem 内部捕获异常并返回 null，因此「注册了但查不到」优先怀疑 WKT 本身不被支持（例如带 ELLIPSOID 关键字或使用了未实现的投影）。

典型工作流

把一批 WGS84 经纬度点位转换到 CGCS2000 3 度带高斯-克吕格投影（EPSG:4547），并写回 CSV：

输入：points.csv（lon,lat） 输出：points_projected.csv（lon,lat,x,y）

1. 用 projinfo（PROJ 命令行）导出目标坐标系的 WKT，避免手写投影参数
2. 在代码里用 CoordinateSystemServices 注册 4490 与 4547
3. 批量读取点位，调用 MathTransform.Transform 逐点或打包转换
4. 输出前校验坐标量级（高斯投影的东坐标通常在 6 位数字量级）

bashCopy code
# 导出 WKT（PROJ 9.x）
projinfo EPSG:4547 -o WKT2:2019

csharpCopy code
using System.Globalization;
using ProjNet.CoordinateSystems;
using ProjNet.CoordinateSystems.Transformations;

var cgcs2000 = File.ReadAllText("wkt/epsg4490.wkt");
var gk3d = File.ReadAllText("wkt/epsg4547.wkt");

var services = new CoordinateSystemServices(new[]
{
    new KeyValuePair<int, string>(4490, cgcs2000),
    new KeyValuePair<int, string>(4547, gk3d),
});

var ct = services.CreateTransformation(4490, 4547);
var mt = ct.MathTransform;

using var reader = new StreamReader("points.csv");
using var writer = new StreamWriter("points_projected.csv");
writer.WriteLine("lon,lat,x,y");

reader.ReadLine();   // 跳过表头
string? line;
while ((line = reader.ReadLine()) is not null)
{
    var parts = line.Split(',');
    double lon = double.Parse(parts[0], CultureInfo.InvariantCulture);
    double lat = double.Parse(parts[1], CultureInfo.InvariantCulture);

    double[] xy = mt.Transform(new[] {lon, lat});
    writer.WriteLine(string.Join(",",
        lon.ToString(CultureInfo.InvariantCulture),
        lat.ToString(CultureInfo.InvariantCulture),
        xy[0].ToString("F3", CultureInfo.InvariantCulture),
        xy[1].ToString("F3", CultureInfo.InvariantCulture)));
}

检查点：转换后东坐标应是 6 位数（含带号则 8 位），北坐标在 0–5000000 量级；若数值仍是 116 / 39 这样的量级，说明取错了坐标系或 WKT 解析失败被静默跳过。

最佳实践

1. WKT 由专业工具生成：用 projinfo、gdalsrsinfo 或 EPSG 官网导出，不要手写 PROJCS 字符串，参数顺序错一位结果就偏
2. 一次构造、复用实例：CoordinateTransformationFactory、CoordinateSystemFactory 与 MathTransform 都可复用，避免在循环里重复解析 WKT
3. 批量用 TransformList 或 Span 重载：MathTransform.TransformList(IList<double[]>) 一次处理整批点；SOA 结构的大数组用 Transform(Span<double> xs, Span<double> ys) 避免装箱
4. 校验转换前后的量级与范围：投影坐标是米，经纬度是度；写一条断言比肉眼检查可靠
5. 明确轴序：ProjNet 只做 x, y 算术，不理会 WKT 的 AXIS 声明，跨系统交换数据时显式约定顺序
6. 坐标是数值不是几何：ProjNet 只处理点数组，几何对象的转换要自己遍历坐标（或用 NTS 的坐标过滤器）
7. 考虑替代方案：需要完整 EPSG 库、网格文件（NTv2/GTX）或 3D 基准转换时，用 SharpProj 或 GDAL，不要指望 ProjNet 覆盖

常见问题

AI 使用建议

• 执行环境：dotnet add package、dotnet build、dotnet run 在终端中执行；首次 restore 需要访问 NuGet，失败时先看是否离线。
• 先探测版本：dotnet list package 确认是 ProjNet 2.1.0 还是 ProjNet4GeoAPI 1.4.1——两者的命名空间与接口完全不同，写代码前必须确认，不要凭 using ProjNet.CoordinateSystems 猜。
• WKT 来源：让用户提供或先跑 projinfo EPSG:xxxx -o WKT2:2019 生成，再写进示例；不要凭空编造 PROJCS 参数。
• 验证产物：编译后运行最小断言（如 116.397, 39.908 → Web Mercator 约 (12957254.8, 4852582.1)），数值量级不对就说明坐标系或轴序取错。
• 失败信号：null 返回值优先怀疑 WKT 解析；结果偏差固定为几十米量级，是缺少网格文件而非代码错误。
• 安全与权限：新建工程、装包前征得用户同意；示例里的 WKT 文件路径用占位符，不要写入用户真实数据路径。

相关技能

• nettopologysuite — .NET 几何运算，常与 ProjNet 搭配做「几何转换 + 空间分析」：../nettopologysuite/SKILL.md
• sharpmap — 旧版 .NET 地图渲染库，坐标变换依赖 ProjNet/ProjNet4GeoAPI：../sharpmap/SKILL.md
• mapsui — 现代跨平台 .NET 地图组件，新项目优先考虑：../mapsui/SKILL.md
• proj — PROJ 命令行，用于导出 WKT 与核对转换结果：../proj/SKILL.md
• gdal — GDAL/OGR 命令行，可做高精度重投影与批量转换：../gdal/SKILL.md

参考资源

• Wiki（FAQ、常用 WKT）：https://github.com/NetTopologySuite/ProjNet4GeoAPI/wiki
• 源码：https://github.com/NetTopologySuite/ProjNet4GeoAPI
• NuGet（2.x）：https://www.nuget.org/packages/ProjNet
• NuGet（1.x）：https://www.nuget.org/packages/ProjNet4GeoAPI
• EPSG 坐标系查询：https://epsg.org/（EPSG 官方注册库；https://spatialreference.org/ 可查 OGC WKT）