Tech.Spatial 2026.4.4

Tech.Spatial API 文档

Tech.Spatial 是基于 NetTopologySuite 和 ProjNET 的空间数据处理库，提供坐标类型、GeoJSON 读写、Shapefile 读写、坐标系统管理、要素转换等 GIS 能力。

Tech.Spatial 依赖 Tech.Core，安装时会自动引入。

Geometries

Tech.Spatial.Geometries 命名空间定义坐标结构体和几何工厂。

坐标类型

Coordinate

通用坐标，[StructLayout(LayoutKind.Sequential)]，适用于内存密集型场景。

public readonly record struct Coordinate(double X, double Y, double Z = double.NaN)

var coord = Coordinate.Create(116.4, 39.9);
var coord3D = Coordinate.Create(116.4, 39.9, 50.0);

// 验证有效性
bool valid = coord.IsValid;

// 隐式转换
Coordinate c = new GeographicCoordinate(116.4, 39.9, 50.0);  // Lon→X, Lat→Y, H→Z
Coordinate c = new ProjectedCoordinate(500000, 4400000);     // E→X, N→Y

GeographicCoordinate

地理坐标（经纬度）。

public readonly record struct GeographicCoordinate(
    double Longitude, double Latitude, double Height = double.NaN)

var geo = GeographicCoordinate.Create(116.4, 39.9);
bool valid = geo.IsValid;  // 经度 [-180,180]，纬度 [-90,90]

// 从 Coordinate 隐式转换
GeographicCoordinate geo = new Coordinate(116.4, 39.9);

ProjectedCoordinate

投影坐标（东移、北移）。

public readonly record struct ProjectedCoordinate(
    double Easting, double Northing, double Up = double.NaN)

var proj = ProjectedCoordinate.Create(500000, 4400000);
bool valid = proj.IsValid;

GeometryType 枚举

GeometryFactory

// 创建带 SRID 的几何工厂
var factory = new GeometryFactory(4326);
int srid = factory.SRID; // 4326

// 从 WKB / WKT 创建几何对象
var geom = GeometryFactory.CreateFromWKB(wkbBytes);
var geom = GeometryFactory.CreateFromWKT("POINT(116.4 39.9)");

Geometry 扩展方法

using Tech.Spatial.Geometries;

// Geometry → WKB / WKT
byte[] wkb = geometry.ToWkb();
string wkt = geometry.ToWkt();

// Coordinate[] → CoordinateArray
var coordArray = coordinates.ToCoordinateArray();

GeoJson

Tech.Spatial.GeoJson 命名空间提供 GeoJSON 序列化与反序列化。

GeoJSON 静态类

using Tech.Spatial.GeoJson;
using NetTopologySuite.Geometries;

// 序列化（支持 Geometry / Feature / FeatureCollection）
string json = GeoJSON.Serialize(point);

// 反序列化
var geometry = GeoJSON.Deserialize<Geometry>(json);
var feature = GeoJSON.Deserialize<Feature>(json);
var collection = GeoJSON.Deserialize<FeatureCollection>(json);

// 异步
string json = await GeoJSON.SerializeAsync(feature);
var geom = await GeoJSON.DeserializeAsync<Geometry>(json, cancellationToken: ct);

序列化选项

// 使用默认选项
var json = GeoJSON.Serialize(obj);

// 使用美化打印
var json = GeoJSON.Serialize(obj, GeoJSON.PrettyPrintOptions);

// 自定义选项
var options = GeoJSON.CreateOptions(writeIndented: true, opt =>
{
    opt.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
});
var json = GeoJSON.Serialize(obj, options);

GeoJsonReader / GeoJsonWriter

// Reader
var reader = new GeoJsonReader();
var point = reader.ReadGeometry(geoJson);
var feature = reader.ReadFeature(geoJson);
var collection = reader.ReadFeatureCollection(geoJson);

// 流式读取
var point = reader.ReadGeometry(stream);

// 异步读取
var feature = await reader.ReadFeatureAsync(geoJson, ct);

// TryParse
if (reader.TryReadGeometry(geoJson, out var geometry))
{
    // 解析成功
}

// Writer
var writer = new GeoJsonWriter();
string json = writer.Write(geometry);
string json = writer.Write(feature);
string json = writer.Write(collection);

// 美化打印
var writer = new GeoJsonWriter(prettyPrint: true);

// 流式写入
writer.Write(geometry, stream);

// 异步
string json = await writer.WriteAsync(feature, ct);

GeoJsonHelper 验证

// 验证是否为 GeoJSON
bool isGeoJson = GeoJsonHelper.IsGeoJson(json);

// 验证并获取类型
if (GeoJsonHelper.IsGeoJson(json, out var type))
{
    Console.WriteLine(type); // GeoJsonType.Point, Feature, FeatureCollections 等
}

// 支持字符串、Span、字节等多种输入
bool valid = GeoJsonHelper.IsGeoJson(utf8Bytes.AsSpan());

GeoJsonType 枚举

扩展方法

string json = geometry.ToJson();
var geometry = json.ToObject<Geometry>();

Shapefiles

Tech.Spatial.Shapefiles 命名空间提供 Shapefile 文件的读取与写入。

Shapefile 静态类

using Tech.Spatial.Shapefiles;

// 读取所有要素
var features = Shapefile.ReadAllFeatures("data.shp");

// 读取所有几何
var geometries = Shapefile.ReadAllGeometries("data.shp");

// 安全读取
if (Shapefile.TryReadAllFeatures("data.shp", out var collection))
{
    // 读取成功
}

// 打开 Reader 进行逐条读取
using var reader = Shapefile.OpenRead("data.shp");
while (reader.Read(out _, out var feature))
{
    ProcessFeature(feature);
}

// 写入
using var writer = Shapefile.OpenWrite("output.shp", featureCollection);
writer.Write(feature);
writer.Write(features);

// 快捷写入
Shapefile.WriteAllFeatures(features, "output.shp", projection: "EPSG:4326");

ShapefileReader 属性

reader.GeometryType   // 几何类型
reader.ShapePath      // 文件路径
reader.Encoding       // 编码
reader.Projection     // 投影
reader.BoundingBox    // 边界范围
reader.Fields         // 字段列表
reader.RecordCount    // 记录数
reader.Restart()      // 重置到起始位置

ShapefileHelper 工具

// 文件验证
bool isShp = ShapefileHelper.IsShpFile("data.shp");
bool hasPrj = ShapefileHelper.HasPrjFile("data.shp");
bool isValid = ShapefileHelper.ValidateShapeFileGroup("data.shp");

// 获取文件组
var (shp, shx, dbf, prj) = ShapefileHelper.GetShapefileGroup("data.shp");

// 读取 .prj 文件
string? wkt = ShapefileHelper.ReadPrjFile("data.shp");

// 删除 Shapefile 文件组
ShapefileHelper.DeleteShapefile("data.shp");

CoordinateSystems

Tech.Spatial.CoordinateSystems 命名空间管理坐标系统定义。

预定义坐标系统

var wgs84      = CoordinateSystem.WGS84;           // EPSG:4326
var mercator   = CoordinateSystem.WebMercator;     // EPSG:3857
var cgcs2000   = CoordinateSystem.CGCS2000;        // EPSG:4490
var gk117      = CoordinateSystem.CGCS2000_GK_CM_117E; // EPSG:4548
var tj2000     = CoordinateSystem.CGCS2000_GK_TJ2000;  // EPSG:90117

自定义坐标系统

// 从 SRID 创建
var cs = CoordinateSystem.Create(4326);

// CGCS2000 高斯-克吕格投影
var cs = CoordinateSystem.CGCS2000_GK(centralMeridian: 117.0);
var cs = CoordinateSystem.CGCS2000_GK_WithZoneNumber(117.0, zoneNumber: 39);

CoordinateSystem 属性

int srid    = cs.Srid;    // EPSG 编号
string wkt  = cs.Wkt;     // WKT 定义
string name = cs.Name;    // 名称
string remarks = cs.Remarks; // 备注

CoordinateSystemFactory

using var factory = CoordinateSystemFactory.Default;

// 从 WKT 创建
var cs = factory.CreateFromWkt(wktString);

// 从 SRID 创建
var cs = factory.CreateFromSrid(4490);

SRID 工具

// 获取 WKT
string? wkt = SRID.GetWkt(4326);

// 注册自定义 SRID
SRID.SetWkt(9999, customWkt);

// 遍历支持的 SRID
foreach (var (srid, wkt) in SRID.SupportedSrids)
{
    Console.WriteLine($"EPSG:{srid}");
}

// 重置为默认
SRID.Reset();

ProjectionZone 投影带

using Tech.Spatial.CoordinateSystems;

// 3 度带
var zone3 = ProjectionZone.CreateThreeDegreeZone(39);       // 中央经线 117°

// 6 度带
var zone6 = ProjectionZone.CreateSixDegreeZone(20);          // 中央经线 117°

// 自定义中央经线
var zone = ProjectionZone.CreateCustomCentralMeridian(117.0);

// 自动计算投影带
var zone3 = ProjectionZone.AutoThreeDegreeZone(116.5);  // 自动匹配 3 度带
var zone6 = ProjectionZone.AutoSixDegreeZone(116.5);    // 自动匹配 6 度带

WktHelper

// 验证 WKT
bool isWkt = WktHelper.IsWkt(wktString);

// 生成高斯-克吕格 WKT
string wkt = WktHelper.CreateGaussKrugerWkt(centralMeridian: 117.0);
string wkt = WktHelper.CreateGaussKrugerWktWithZoneNumber(117.0, 39);

Features

Tech.Spatial.Features.Transformers 命名空间提供要素级别的坐标批量转换。

FeatureTransformer

using Tech.Spatial.Features.Transformers;

var transformer = FeatureTransformer.Create(
    CoordinateSystem.WGS84,
    CoordinateSystem.CGCS2000_GK_CM_117E
);

// 转换单个几何
var transformed = transformer.Transform(geometry);

// 转换要素
var transformedFeature = transformer.Transform(feature);

// 批量转换要素集合
var transformedCollection = transformer.Transform(featureCollection);

// 反向转换
var original = transformer.Transform(geometry, inverse: true);

FeatureTransformerOptions

var options = new FeatureTransformerOptions
{
    IsParallelFeatureEnabled = true,       // 启用要素并行转换
    ParallelFeatureThreshold = 50,         // 并行阈值
    UseBatchCoordinateTransform = true,    // 使用批量坐标转换
    SmallArrayThreshold = 24,              // 小数组阈值
    UseMultiGeometryBatchTransform = true, // 多几何类型批量优化
    ValidateSourceSrid = true              // 验证源 SRID
};

var transformer = FeatureTransformer.Create(sourceCS, targetCS, options);

扩展方法

var transformedFeature = feature.TransformCoordinates(transformer);
var transformedCollection = collection.TransformCoordinates(transformer);

Transformers

Tech.Spatial.Geometries.Transformers 命名空间提供坐标级别的转换器。

CoordinateTransformer

using Tech.Spatial.Geometries.Transformers;

var transformer = CoordinateTransformer.Create(
    CoordinateSystem.WGS84,
    CoordinateSystem.CGCS2000_GK_CM_117E
);

// 转换单个坐标
var coord = transformer.Transform(new Coordinate(116.4, 39.9));

// 批量转换
var coords = new Coordinate[] { new(116.4, 39.9), new(117.2, 39.1) };
var results = transformer.Transform(coords.AsMemory());

// 安全转换
if (transformer.TryTransform(coord, out var result))
{
    Console.WriteLine($"X={result.X}, Y={result.Y}");
}

// 反向转换
var original = transformer.Transform(coord, inverse: true);

CoordinateTransformerOptions

var options = new CoordinateTransformerOptions
{
    IsParallelEnabled = true,
    ParallelThreshold = 500
};

var transformer = CoordinateTransformer.Create(sourceCS, targetCS, options);

CoordinateTransformerFactory

using var factory = CoordinateTransformerFactory.Default;

// 从坐标系统创建
var transformer = factory.CreateFromCoordinateSystems(sourceCS, targetCS);

// 从 SRID 创建
var transformer = factory.CreateFromSrid(4326, 4548);

// 带自定义选项
var transformer = factory.CreateFromSrid(4326, 4548, options =>
{
    options.IsParallelEnabled = true;
});

扩展方法

var result = coordinate.TransformCoordinates(transformer);
var results = coordinateArray.TransformCoordinates(transformer);

Collections

Tech.Spatial.Collections 命名空间提供专用的坐标数组。

CoordinateArray

继承 MemoryArray<Coordinate>，提供坐标转换、筛选、边界计算等空间操作。

using Tech.Spatial.Collections;

// 创建
var array = new CoordinateArray(1000);
var array = new CoordinateArray(new[] { new Coordinate(1, 2), new Coordinate(3, 4) });

// 零拷贝包装
var array = CoordinateArray.Wrap(existingArray);

// 空数组
var empty = CoordinateArray.Empty;

坐标转换

var transformer = CoordinateTransformer.Create(sourceCS, targetCS);
var transformed = array.Transform(transformer);

集合操作

// 筛选
var filtered = array.Filter(c => c.X > 0 && c.Y > 0);

// 映射
var projected = array.Select(c => new Coordinate(c.X * 2, c.Y * 2));

// 边界
var bounds = array.GetBounds();
if (bounds.HasValue)
{
    Console.WriteLine($"Min: ({bounds.Value.MinX}, {bounds.Value.MinY})");
    Console.WriteLine($"Max: ({bounds.Value.MaxX}, {bounds.Value.MaxY})");
}

// 合并
var combined = array1.Concat(array2);

转换

// 转 Coordinate[]
var coords = array.ToArray();

// 转 NTS Coordinate[]
var ntsCoords = array.ToNTSCoordinateArray();

// 转 GeoAPI Coordinate[]
var geoApiCoords = array.ToGeoAPICoordinateArray();

// 属性
bool isEmpty = array.IsEmpty;