项目地址: https://github.com/znlgis/opengis-utils-for-net
官方文档: https://github.com/znlgis/opengis-utils-for-net#readme
NuGet 包:
OpenGIS.Utils最新版本: 1.1.2(截至 2026-10,NuGet)
许可证: LGPL-2.1-or-later
概述
OGU4N (OpenGIS Utils for .NET) 是一个面向 .NET 的 GIS 实用工具集,提供矢量数据读写、几何运算、坐标系管理等能力。核心特性:
- 统一数据读写:
OguLayerUtil一站式读取/写出 Shapefile、GeoJSON、FileGDB、GeoPackage、KML、DXF、PostGIS、TXT 等格式 - 几何运算:
GeometryUtil提供 50+ 静态方法(空间关系、集合运算、属性查询、拓扑验证) - 坐标系管理:
CrsUtil支持 CGCS2000 系列坐标系变换与分区计算 - 辅助工具:编码检测、文件压缩、自然排序、数字格式化等
- GDAL 引擎实现:.NET 版本全部基于 GDAL/OGR 实现(
GisEngineType.GEOTOOLS仅为兼容保留并重定向到 GDAL;Java 版本为 GeoTools 与 GDAL 双引擎)
环境要求: .NET Standard 2.0+(兼容 .NET Core 2.0+、.NET 5+、.NET Framework 4.6.1+)
环境准备
方式一:dotnet CLI
dotnet add package OpenGIS.Utils --version 1.1.2
方式二:手写 csproj 的 PackageReference
<ItemGroup>
<PackageReference Include="OpenGIS.Utils" Version="1.1.2" />
</ItemGroup>
验证
dotnet --version # 库为 netstandard2.0,.NET Core 2.0+ / .NET 5+ 均可引用
dotnet restore # 能解析 OpenGIS.Utils 1.1.2 即包可用
dotnet list package --include-transitive | findstr OpenGIS.Utils
GDAL 原生运行时由
MaxRev.Gdal.Universal随包分发,无需手动GdalConfiguration.ConfigureGdal();DllNotFoundException通常来自 RID 不匹配,见常见问题。
构建与测试
dotnet build OpenGIS.Utils.sln
dotnet test tests/OpenGIS.Utils.Tests/
项目结构
src/OpenGIS.Utils/
├── Configuration/ # GdalConfiguration, LibrarySettings
├── DataSource/ # OguLayerUtil (high-level I/O), GtTxtUtil (National Land Survey TXT)
├── Engine/
│ ├── Enums/ # GeometryType, FieldDataType, DataFormatType, GisEngineType, TopologyValidationErrorType
│ ├── IO/ # ILayerReader, ILayerWriter
│ ├── Model/
│ │ └── Layer/ # OguLayer, OguFeature, OguField, OguFieldValue, OguCoordinate, OguLayerMetadata
│ ├── Util/ # CrsUtil, OgrUtil, ShpUtil, PostgisUtil, GdalCmdUtil
│ ├── GdalEngine.cs # GDAL implementation of GisEngine
│ ├── GdalReader.cs # ILayerReader implementation
│ ├── GdalWriter.cs # ILayerWriter implementation
│ ├── GisEngine.cs # Abstract base class
│ └── GisEngineFactory.cs
├── Exception/ # OguException, DataSourceException, FormatParseException, etc.
├── Geometry/ # GeometryUtil (50+ static methods)
└── Utils/ # EncodingUtil, NumUtil, SortUtil, ZipUtil
核心 API:命名空间与主要类型
| Namespace | Key Classes |
|---|---|
OpenGIS.Utils.Configuration |
GdalConfiguration, LibrarySettings |
OpenGIS.Utils.DataSource |
OguLayerUtil, GtTxtUtil |
OpenGIS.Utils.Engine |
GisEngine, GisEngineFactory, GdalEngine, GdalReader, GdalWriter |
OpenGIS.Utils.Engine.Enums |
GeometryType, FieldDataType, DataFormatType, GisEngineType, TopologyValidationErrorType |
OpenGIS.Utils.Engine.IO |
ILayerReader, ILayerWriter |
OpenGIS.Utils.Engine.Model |
DbConnBaseModel, GdbGroupModel, TopologyValidationResult, SimpleGeometryResult |
OpenGIS.Utils.Engine.Model.Layer |
OguLayer, OguFeature, OguField, OguFieldValue, OguCoordinate, OguLayerMetadata |
OpenGIS.Utils.Engine.Util |
CrsUtil, OgrUtil, ShpUtil, PostgisUtil, GdalCmdUtil |
OpenGIS.Utils.Exception |
OguException, DataSourceException, FormatParseException, EngineNotSupportedException, LayerValidationException, TopologyException |
OpenGIS.Utils.Geometry |
GeometryUtil |
OpenGIS.Utils.Utils |
EncodingUtil, NumUtil, SortUtil, ZipUtil |
枚举
GeometryType
POINT, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION, UNKNOWN
FieldDataType
STRING, INTEGER, LONG, DOUBLE, FLOAT, BOOLEAN, DATE, DATETIME, BINARY, UNKNOWN
DataFormatType
SHP, GEOJSON, FILEGDB, POSTGIS, TXT, GEOPACKAGE, KML, DXF, UNKNOWN
GisEngineType
GEOTOOLS, GDAL
注意: .NET 版本的
GEOTOOLS仅为兼容保留(GisEngineFactory将其重定向到 GDAL 实现),所有格式实际都由 GDAL/OGR 处理;Java 版本为 GeoTools 与 GDAL 双引擎。
TopologyValidationErrorType
ERROR, REPEATED_POINT, HOLE_OUTSIDE_SHELL, NESTED_HOLES, DISCONNECTED_INTERIOR,
SELF_INTERSECTION, RING_SELF_INTERSECTION, NESTED_SHELLS, DUPLICATE_RINGS,
TOO_FEW_POINTS, INVALID_COORDINATE, RING_NOT_CLOSED
核心模型类
OguLayer
using OpenGIS.Utils.Engine.Model.Layer;
using OpenGIS.Utils.Engine.Enums;
| Property | Type | Description |
|---|---|---|
Name |
string |
Layer name |
Wkid |
int? |
Coordinate system WKID (e.g. 4326 for WGS84) |
GeometryType |
GeometryType |
Geometry type |
Fields |
IList<OguField> |
Field definitions |
Features |
IList<OguFeature> |
Feature collection |
Metadata |
OguLayerMetadata? |
Optional metadata |
| Method | Returns | Description |
|---|---|---|
Validate() |
void |
Validates layer integrity; throws LayerValidationException |
Filter(Func<OguFeature, bool>) |
IList<OguFeature> |
Filters features by predicate |
GetFeatureCount() |
int |
Feature count |
ToJson() |
string |
Serializes to JSON |
FromJson(string json) |
OguLayer? |
static — Deserializes from JSON |
Clone() |
OguLayer |
Deep copy |
GetField(string fieldName) |
OguField? |
Gets field by name |
AddField(OguField field) |
void |
Adds a field definition |
AddFeature(OguFeature feature) |
void |
Adds a feature |
RemoveFeature(int fid) |
bool |
Removes feature by FID |
OguFeature
| Property | Type | Description |
|---|---|---|
Fid |
int |
Feature ID |
Wkt |
string? |
Geometry in WKT format |
Attributes |
Dictionary<string, OguFieldValue> |
Attribute values |
| Method | Returns | Description |
|---|---|---|
GetValue(string fieldName) |
object? |
Gets raw attribute value |
SetValue(string fieldName, object? value) |
void |
Sets attribute value |
GetAttribute(string fieldName) |
OguFieldValue? |
Gets field value object |
HasAttribute(string fieldName) |
bool |
Checks if attribute exists |
ToJson() |
string |
Serializes to JSON |
FromJson(string json) |
OguFeature? |
static — Deserializes from JSON |
Clone() |
OguFeature |
Deep copy |
OguField
| Property | Type | Description |
|---|---|---|
Name |
string |
Field name |
Alias |
string? |
Display alias |
DataType |
FieldDataType |
Data type |
Length |
int? |
String length |
Precision |
int? |
Numeric precision |
Scale |
int? |
Decimal places |
IsNullable |
bool |
Whether nullable |
DefaultValue |
object? |
Default value |
Methods: ToJson(), FromJson(string), Clone()
OguFieldValue
| Property | Type |
|---|---|
Value |
object? |
IsNull |
bool |
Type-safe getters: GetStringValue(), GetIntValue(), GetLongValue(), GetDoubleValue(), GetFloatValue(), GetBoolValue(), GetDateTimeValue(), GetDecimalValue()
OguCoordinate
| Property | Type | Description |
|---|---|---|
X |
double |
X coordinate (longitude) |
Y |
double |
Y coordinate (latitude) |
Z |
double? |
Z coordinate (elevation, optional) |
PointNumber |
string? |
Point number |
RingNumber |
string? |
Ring number |
Remark |
string? |
Remark text |
Methods: ToWkt() → string, FromWkt(string wkt) → OguCoordinate (static)
OguLayerMetadata
| Property | Type |
|---|---|
DataSource |
string? |
CoordinateSystemName |
string? |
ZoneDivision |
string? |
ProjectionType |
string? |
MeasureUnit |
string? |
ExtendedProperties |
Dictionary<string, object> |
CreateTime |
DateTime? |
ModifyTime |
DateTime? |
OguLayerUtil、GeometryUtil、CrsUtil、ShpUtil、PostgisUtil、GtTxtUtil 等工具类与 GDAL 配置的完整 API 见 reference/util-classes.md
引擎架构
using OpenGIS.Utils.Engine;
// Abstract base
public abstract class GisEngine
{
public abstract GisEngineType EngineType { get; }
public abstract IList<DataFormatType> SupportedFormats { get; }
public abstract ILayerReader CreateReader();
public abstract ILayerWriter CreateWriter();
public virtual bool SupportsFormat(DataFormatType format);
}
// Factory
GisEngine engine = GisEngineFactory.GetEngine(GisEngineType.GDAL);
GisEngine engine = GisEngineFactory.GetEngine(DataFormatType.SHP);
bool ok = GisEngineFactory.TryGetEngine(DataFormatType.GEOJSON, out GisEngine? engine);
ILayerReader / ILayerWriter
public interface ILayerReader
{
OguLayer Read(string path, string? layerName = null, string? attributeFilter = null,
string? spatialFilterWkt = null, Dictionary<string, object>? options = null);
IList<string> GetLayerNames(string path);
}
public interface ILayerWriter
{
void Write(OguLayer layer, string path, string? layerName = null,
Dictionary<string, object>? options = null);
void Append(OguLayer layer, string path, string? layerName = null,
Dictionary<string, object>? options = null);
}
通用工具
EncodingUtil
using OpenGIS.Utils.Utils;
Encoding EncodingUtil.GetFileEncoding(string filePath)
Encoding EncodingUtil.GetFileEncoding(Stream stream)
Encoding EncodingUtil.DetectEncoding(byte[] buffer)
Encoding EncodingUtil.DetectEncoding(byte[] buffer, int length)
void EncodingUtil.ConvertFileEncoding(string filePath, Encoding targetEncoding)
ZipUtil
void ZipUtil.Zip(string folderPath, string zipPath)
void ZipUtil.Zip(string folderPath, string zipPath, Encoding encoding)
void ZipUtil.Unzip(string zipPath, string destPath)
void ZipUtil.Unzip(string zipPath, string destPath, Encoding encoding)
void ZipUtil.CompressFiles(IEnumerable<string> filePaths, string zipPath)
SortUtil
int SortUtil.CompareString(string a, string b) // Natural sort comparison
IOrderedEnumerable<T> SortUtil.NaturalSort<T>(IEnumerable<T> source, Func<T, string> keySelector)
NumUtil
string NumUtil.GetPlainString(double number) // No scientific notation
string NumUtil.GetPlainString(decimal number)
double NumUtil.Round(double value, int decimals)
string NumUtil.FormatNumber(double value, int decimals)
异常层次
System.Exception
└── OguException (ErrorCode, Context)
├── DataSourceException — Data source access errors
├── EngineNotSupportedException — Unsupported engine type
├── FormatParseException — Format parsing errors
├── LayerValidationException — Layer validation failures
└── TopologyException — Topology validation/operation errors
结果模型
TopologyValidationResult
| Property | Type |
|---|---|
IsValid |
bool |
ErrorType |
TopologyValidationErrorType? |
ErrorMessage |
string? |
ErrorLocation |
string? (WKT) |
SimpleGeometryResult
| Property | Type |
|---|---|
IsSimple |
bool |
Reason |
string? |
NonSimpleLocation |
string? (WKT) |
DbConnBaseModel
Properties: Host, Port, Database, Username, Password, Schema, ConnectionString (all nullable)
GdbGroupModel
Properties: GdbPath (string?), LayerNames (List<string>)
常用代码模式完整示例见 reference/code-patterns.md
常见问题
| 问题 | 解决 |
|---|---|
找不到 OguLayer 等类型 |
安装 NuGet 包 OpenGIS.Utils,并引用命名空间 OpenGIS.Utils.Engine.Model.Layer |
| GDAL 相关加载错误 | 无需手动初始化(库自动调用且线程安全);确认已引用 OpenGIS.Utils 包(MaxRev.Gdal.Universal 运行时随包分发) |
| Shapefile 中文乱码 | 读取时传入 Encoding(如 Encoding.GetEncoding("GBK"));.NET Core 上先注册 Encoding.RegisterProvider(CodePagesEncodingProvider.Instance) |
| FileGDB 打不开 | 需 GDAL FileGDB 驱动,且路径指向 .gdb 目录,格式使用 DataFormatType.FILEGDB |
Geojson2Wkt/Geojson2Geometry 抛 ArgumentException |
仅接受裸几何、Feature 或 FeatureCollection 字符串;空串或无法解析会抛错,整文件请走 OguLayerUtil.ReadLayer |
| OGR 几何内存管理 | OgrGeometry 实现 IDisposable,用完及时 Dispose();或用 *Wkt 便捷方法避免手动管理 |
AI 编码约定
- GDAL auto-initializes — No manual
GdalConfiguration.ConfigureGdal()call needed. - GeoJSON string parsing is supported —
Geojson2Wkt()/Geojson2Geometry()parse bare geometry,Feature, orFeatureCollectionstrings (first feature's geometry wins) via the GDAL GeoJSON driver and throwArgumentExceptionfor unparseable input. For whole files useGdalReaderorOguLayerUtil.ReadLayer(DataFormatType.GEOJSON, path). - Geometry uses WKT strings —
OguFeature.Wktstores geometry as WKT. UseGeometryUtilfor conversions and operations. - Thread safety — GDAL initialization is thread-safe. Individual GDAL geometry objects are NOT thread-safe.
- Cross-platform — .NET Standard 2.0: works on .NET Core 2.0+, .NET 5+, .NET Framework 4.6.1+.
- Encoding support —
EncodingUtildetects UTF-8, UTF-16 LE/BE, GBK, GB2312. Register CodePages withEncoding.RegisterProvider(CodePagesEncodingProvider.Instance)if needed. - WKT convenience methods — Most
GeometryUtilmethods have*Wktvariants that accept/return WKT strings directly, avoiding the need to manageOgrGeometryobjects.
典型工作流
以「Shapefile → 属性筛选 → 缓冲区 → 投影 → GeoPackage」为例:输入 data/parcels.shp(EPSG:4326),输出 data/parcels_4528.gpkg。
- 读取数据:
OguLayerUtil.ReadLayer(DataFormatType.SHP, path)统一入口读取各类矢量格式 - 几何运算:
GeometryUtil.Wkt2Geometry()转换后操作,或直接用*Wkt后缀方法 - 坐标转换:
CrsUtil.Transform()只接受 WKT 或OgrGeometry,整层变换需逐要素处理后改layer.Wkid - 写出结果:
OguLayerUtil.WriteLayer()写出为目标格式 - 格式转换:
OguLayerUtil.ConvertFormat()一步完成 - 回读验证:重新读取产物,核对要素数与
Wkid
using OpenGIS.Utils.DataSource;
using OpenGIS.Utils.Engine.Enums;
using OpenGIS.Utils.Engine.Model.Layer;
using OpenGIS.Utils.Geometry;
// 1. 读:完整重载见 reference/code-patterns.md
OguLayer layer = OguLayerUtil.ReadLayer(DataFormatType.SHP, "data/parcels.shp");
Console.WriteLine($"{layer.Wkid} / {layer.GetFeatureCount()}");
// 2. 筛选 + 缓冲:几何以 WKT 字符串存放,OgrGeometry 需要 Dispose
var large = layer.Filter(f =>
{
using var g = GeometryUtil.Wkt2Geometry(f.Wkt!);
return GeometryUtil.Area(g) > 10000;
});
foreach (var f in large)
{
using var g = GeometryUtil.Wkt2Geometry(f.Wkt!);
using var buffered = GeometryUtil.Buffer(g, 50);
f.Wkt = GeometryUtil.Geometry2Wkt(buffered);
}
// 3. 投影到 CGCS2000 3 度带(EPSG:4528)。
// CrsUtil 只有 WKT / OgrGeometry 两个重载,没有整层变换,必须逐要素处理并改 Wkid
int sourceWkid = layer.Wkid ?? 4326;
foreach (var f in layer.Features)
f.Wkt = CrsUtil.Transform(f.Wkt!, sourceWkid, 4528);
layer.Wkid = 4528;
// 4. 写出 GeoPackage
OguLayerUtil.WriteLayer(DataFormatType.GEOPACKAGE, layer, "data/parcels_4528.gpkg");
// 6. 回读验证
OguLayer check = OguLayerUtil.ReadLayer(DataFormatType.GEOPACKAGE, "data/parcels_4528.gpkg");
Console.WriteLine($"{check.Wkid} / {check.GetFeatureCount()}");
验收:打印的 WKID 应为 4528、要素数与筛选结果一致;再用 ogrinfo -so data/parcels_4528.gpkg 复核。dotnet build 成功不代表能跑——GDAL 原生库是运行期才加载的。
AI 使用建议
- 本技能的组织:主文件给高频用法,完整参数表与高级示例在
reference/code-patterns.md、reference/util-classes.md,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。 - 执行环境:先
dotnet --version;库目标 .NET Standard 2.0,可被 .NET Core 2.0+ / .NET 5+ / .NET Framework 4.6.1+ 引用,Windows 用 PowerShell;用dotnet new console -o demo && cd demo起最小工程。 - 依赖坐标:
dotnet add package OpenGIS.Utils --version 1.1.2(NuGet 最新 1.1.2),原生 GDAL 运行时随包分发(MaxRev.Gdal.Universal);用dotnet list package --include-transitive | Select-String OpenGIS.Utils核对解析出的版本,NU1101/NU1102表示源或版本不可用,如实报告而不是改版本号重试。 - 平台与原生库:运行时与 RID 绑定,
DllNotFoundException或Unable to load DLL 'gdal'多因-r win-x64/linux-x64与运行环境不一致;dotnet publish -r win-x64后跑发布目录,不要只跑bin/Debug里的半成品。 - 验证产物:最小程序
OguLayerUtil.ReadLayer(DataFormatType.SHP, path)读入(完整重载见reference/code-patterns.md)→ 打印layer.GetFeatureCount()与layer.Wkid,再WriteLayer写出 GeoJSON 并重新读回,核对要素数与 CRS;dotnet build成功只说明编译通过,GDAL 原生库是运行期才加载的。 - 常见误操:
Geojson2Wkt()只接受裸几何 /Feature/FeatureCollection字符串,传整文件内容会抛ArgumentException,整文件走OguLayerUtil.ReadLayer;OgrGeometry是IDisposable,用完Dispose();GEOTOOLS枚举仅为兼容,在 .NET 版实际重定向到 GDAL。 - 构建与测试:在仓库 checkout 内
dotnet build OpenGIS.Utils.sln、dotnet test tests/OpenGIS.Utils.Tests/,输出在bin/、obj/(不要提交);只看某一条测试时加--filter FullyQualifiedName~关键字。 - 安全与权限:写入 Shapefile/GeoPackage 会覆盖同名文件,执行前确认目标路径;PostGIS 连接串与 GDAL 配置里的密码不要回显;
dotnet restore、安装 SDK 或改NuGet.config前先征得用户同意。
相关技能
- nettopologysuite — .NET 几何计算核心:../nettopologysuite/SKILL.md
- geometry-api-net — Esri Geometry API for .NET:../geometry-api-net/SKILL.md
- gdal — 命令行数据处理:../gdal/SKILL.md
- gdal-api — GDAL 编程 API:../gdal-api/SKILL.md
参考资源
- GitHub 仓库: https://github.com/znlgis/opengis-utils-for-net
- NuGet: https://www.nuget.org/packages/OpenGIS.Utils
- GDAL 绑定(MaxRev.Gdal.Universal): https://github.com/MaxRev-Dev/gdal.netcore
- 中文教程(znlgis): https://znlgis.github.io/gis/tutorial/opengis-utils-for-net/