@dsh-gis/dsh-opengis-skill 0.1.3 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/CHANGELOG.md +95 -0
  2. package/README.md +68 -28
  3. package/THIRD_PARTY_NOTICES.md +9 -0
  4. package/adaptations/brutile.md +8 -0
  5. package/adaptations/cesiumjs.md +8 -0
  6. package/adaptations/common.md +19 -0
  7. package/adaptations/deck-gl.md +8 -0
  8. package/adaptations/duckdb-spatial.md +8 -0
  9. package/adaptations/gdal-api.md +8 -0
  10. package/adaptations/gdal.md +8 -0
  11. package/adaptations/geolibre.md +8 -0
  12. package/adaptations/geometry-api-java.md +8 -0
  13. package/adaptations/geometry-api-net.md +8 -0
  14. package/adaptations/geonode.md +8 -0
  15. package/adaptations/geopandas.md +8 -0
  16. package/adaptations/geopipe-agent.md +8 -0
  17. package/adaptations/geoserver-cloud.md +8 -0
  18. package/adaptations/geoserver-rest-api.md +8 -0
  19. package/adaptations/geoserver.md +8 -0
  20. package/adaptations/geotools.md +8 -0
  21. package/adaptations/grass-gis.md +8 -0
  22. package/adaptations/jts.md +8 -0
  23. package/adaptations/kepler-gl.md +8 -0
  24. package/adaptations/leaflet.md +8 -0
  25. package/adaptations/mapbox-gl-js.md +8 -0
  26. package/adaptations/mapserver.md +8 -0
  27. package/adaptations/mapsui.md +8 -0
  28. package/adaptations/nettopologysuite.md +8 -0
  29. package/adaptations/opengis-all.md +9 -0
  30. package/adaptations/opengis-daf.md +9 -0
  31. package/adaptations/opengis-utils-for-java.md +8 -0
  32. package/adaptations/opengis-utils-for-net.md +8 -0
  33. package/adaptations/openlayers.md +8 -0
  34. package/adaptations/pdal.md +8 -0
  35. package/adaptations/postgis.md +8 -0
  36. package/adaptations/proj.md +8 -0
  37. package/adaptations/projnet4geoapi.md +8 -0
  38. package/adaptations/pyqgis.md +8 -0
  39. package/adaptations/qgis-process.md +8 -0
  40. package/adaptations/qgis-server.md +8 -0
  41. package/adaptations/shapely.md +8 -0
  42. package/adaptations/sharpmap.md +8 -0
  43. package/adaptations/spatialite.md +8 -0
  44. package/adaptations/whitebox-tools.md +8 -0
  45. package/assets/brutile/SKILL.md +283 -0
  46. package/assets/cesiumjs/SKILL.md +81 -35
  47. package/assets/deck-gl/SKILL.md +26 -34
  48. package/assets/duckdb-spatial/SKILL.md +363 -0
  49. package/assets/gdal/SKILL.md +55 -33
  50. package/assets/gdal/reference/raster-tools.md +14 -0
  51. package/assets/gdal/reference/vector-tools.md +5 -0
  52. package/assets/gdal-api/SKILL.md +12 -18
  53. package/assets/gdal-api/reference/raster-api.md +7 -0
  54. package/assets/gdal-api/reference/vector-api.md +9 -0
  55. package/assets/geolibre/SKILL.md +357 -0
  56. package/assets/geometry-api-java/SKILL.md +10 -16
  57. package/assets/geometry-api-net/SKILL.md +70 -32
  58. package/assets/geometry-api-net/reference/geometry-types.md +5 -0
  59. package/assets/geonode/SKILL.md +340 -0
  60. package/assets/geopandas/SKILL.md +21 -24
  61. package/assets/geopandas/reference/core-api.md +4 -0
  62. package/assets/geopipe-agent/SKILL.md +29 -31
  63. package/assets/geopipe-agent/reference/steps-reference.md +12 -0
  64. package/assets/geopipe-agent/reference/workflows.md +8 -0
  65. package/assets/geoserver/SKILL.md +10 -15
  66. package/assets/geoserver-cloud/SKILL.md +25 -33
  67. package/assets/geoserver-rest-api/SKILL.md +17 -19
  68. package/assets/geoserver-rest-api/reference/endpoints.md +16 -0
  69. package/assets/geotools/SKILL.md +12 -17
  70. package/assets/geotools/reference/raster-rendering.md +5 -0
  71. package/assets/geotools/reference/vector-io.md +7 -0
  72. package/assets/grass-gis/SKILL.md +26 -33
  73. package/assets/jts/SKILL.md +12 -16
  74. package/assets/jts/reference/geometry-operations.md +13 -0
  75. package/assets/kepler-gl/SKILL.md +306 -0
  76. package/assets/leaflet/SKILL.md +58 -40
  77. package/assets/mapbox-gl-js/SKILL.md +26 -33
  78. package/assets/mapserver/SKILL.md +21 -29
  79. package/assets/mapsui/SKILL.md +109 -63
  80. package/assets/nettopologysuite/SKILL.md +96 -31
  81. package/assets/opengis-all/SKILL.md +91 -289
  82. package/assets/opengis-all/reference/data-stages.md +269 -4
  83. package/assets/opengis-all/reference/workflow-cheatsheets.md +7 -0
  84. package/assets/opengis-daf/SKILL.md +10 -17
  85. package/assets/opengis-utils-for-java/SKILL.md +58 -49
  86. package/assets/opengis-utils-for-java/reference/common-tasks.md +16 -12
  87. package/assets/opengis-utils-for-net/SKILL.md +109 -48
  88. package/assets/opengis-utils-for-net/reference/code-patterns.md +15 -11
  89. package/assets/opengis-utils-for-net/reference/util-classes.md +35 -26
  90. package/assets/openlayers/SKILL.md +81 -28
  91. package/assets/pdal/SKILL.md +25 -27
  92. package/assets/postgis/SKILL.md +80 -35
  93. package/assets/proj/SKILL.md +32 -41
  94. package/assets/projnet4geoapi/SKILL.md +293 -0
  95. package/assets/pyqgis/SKILL.md +33 -30
  96. package/assets/pyqgis/reference/processing-rendering.md +6 -0
  97. package/assets/pyqgis/reference/vector-raster-layers.md +6 -0
  98. package/assets/qgis-process/SKILL.md +75 -33
  99. package/assets/qgis-process/reference/algorithm-cheatsheet.md +6 -0
  100. package/assets/qgis-server/SKILL.md +25 -31
  101. package/assets/shapely/SKILL.md +136 -84
  102. package/assets/shapely/reference/operations-reference.md +12 -0
  103. package/assets/sharpmap/SKILL.md +97 -60
  104. package/assets/spatialite/SKILL.md +358 -0
  105. package/assets/whitebox-tools/SKILL.md +262 -0
  106. package/lib/adaptations.d.ts +53 -0
  107. package/lib/adaptations.js +343 -0
  108. package/lib/catalog.d.ts +7 -1
  109. package/lib/catalog.js +9 -1
  110. package/lib/index.d.ts +10 -1
  111. package/lib/index.js +34 -3
  112. package/lib/skill-file.d.ts +12 -0
  113. package/lib/skill-file.js +133 -18
  114. package/locale/en.json +1 -1
  115. package/locale/zh.json +1 -1
  116. package/package.json +12 -2
  117. package/upstream.json +73 -57
@@ -0,0 +1,283 @@
1
+ ---
2
+ name: brutile
3
+ description: "Use when fetching or enumerating map tiles in .NET with BruTile 6.0.0 — HttpTileSource over HttpClient, KnownTileSources.Create, ITileSchema.GetTileInfos for a viewport and resolution, MbTilesTileSource for offline MBTiles, or wiring tiles into Mapsui/SharpMap. Also for missing 'BruTile.Desktop' packages, CS0246 on KnownTileSources, MBTiles SQLite native load failures, and 404s from inverted TMS/OSM y-axis."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "dotnet, csharp, tiles, tms, wmts, mbtiles, openstreetmap, webmapping, http"
8
+ ---
9
+
10
+ > **项目地址:** <https://github.com/BruTile/BruTile>
11
+ >
12
+ > **最新版本:** 6.0.0(2025-10-27 发布,截至 2026-11,[GitHub Releases](https://github.com/BruTile/BruTile/releases) / NuGet `BruTile`、`BruTile.MbTiles`;目标框架 net8.0 / net9.0)
13
+ >
14
+ > **官方文档:** <https://github.com/BruTile/BruTile>
15
+ >
16
+ > **许可证:** Apache-2.0
17
+
18
+ ## 概述
19
+
20
+ BruTile 是一个只管「瓦片」的 .NET 库:给定视口范围与分辨率,算出需要哪些瓦片,再去对应服务把瓦片字节取回来。它不做渲染、不含 UI,瓦片最终由 Mapsui、SharpMap、ArcBruTile 等地图组件显示。这种职责划分让 BruTile 可以同时支撑 WPF、MAUI、Blazor、ASP.NET 等多种宿主,也是它在 .NET 地图栈中长期作为底座的原因。
21
+
22
+ - **瓦片方案(schema)**:Web 墨卡托全球网格、WMTS、TMS、WMS-C 等组织的分辨率与瓦片索引映射
23
+ - **瓦片源**:HTTP 瓦片服务(XYZ/OSM、ArcGIS、Bing 等)、MBTiles 离线文件、文件系统瓦片缓存
24
+ - **视口计算**:`ITileSchema.GetTileInfos(extent, resolution)` 求当前需要渲染的瓦片集合
25
+ - **缓存**:内存缓存与持久化缓存(MBTiles、文件系统)可组合
26
+ - **坐标系约定**:默认 Web 墨卡托(EPSG:3857),OSM 与 TMS 的 y 轴方向不同,需显式选择
27
+
28
+ > **版本提示**:BruTile 6.0.0 只发布 net8.0 / net9.0 目标。需要 netstandard2.0 的场景(例如 .NET Framework、SharpMap 1.2)只能用 5.0.6 或更早版本,详见下方版本对照表。
29
+
30
+ ---
31
+
32
+ ## 环境准备
33
+
34
+ ### 安装
35
+
36
+ ```bash
37
+ # 在线瓦片(HTTP 服务)
38
+ dotnet add package BruTile --version 6.0.0
39
+
40
+ # 离线 MBTiles 需要额外的包
41
+ dotnet add package BruTile.MbTiles --version 6.0.0
42
+
43
+ # 需要挂在 Mapsui 上时
44
+ dotnet add package Mapsui --version 5.1.0
45
+ ```
46
+
47
+ ```powershell
48
+ Install-Package BruTile -Version 6.0.0
49
+ ```
50
+
51
+ ### 验证
52
+
53
+ ```csharp
54
+ using BruTile;
55
+ using BruTile.Predefined;
56
+
57
+ var schema = new GlobalSphericalMercator();
58
+ Console.WriteLine(schema.Resolutions.Count); // 默认 0..19 级共 20 个分辨率
59
+ var tileInfos = schema.GetTileInfos(
60
+ new Extent(-20037508, -20037508, 20037508, 20037508), 156543.03392804097);
61
+ Console.WriteLine(tileInfos.Count()); // 0 级应只有 1 张
62
+ ```
63
+
64
+ ```bash
65
+ dotnet run
66
+ ```
67
+
68
+ ### 版本与目标框架对照
69
+
70
+ | BruTile 版本 | 目标框架 | 说明 |
71
+ |--------------|----------|------|
72
+ | 6.0.0 | net8.0 / net9.0 | 当前版本;`HttpTileSource.GetTileAsync` 需要传入 `HttpClient` |
73
+ | 5.0.6 | net6.0 / netstandard2.0 | 兼容 .NET Framework 4.6.1+ 与 .NET 6/7 |
74
+ | 4.0.0 / 3.1.3 | netstandard2.0 / netstandard1.1 | 老项目常用;`BruTile.Desktop` 在 4.0 起被删除,内容并入 `BruTile` |
75
+
76
+ `BruTile.Desktop`、`BruTile.Desktop.DbCache` 这两个包名在 4.0 之后已不存在,旧代码里的 `using BruTile.Desktop` 需要改命名空间。
77
+
78
+ ---
79
+
80
+ ## 核心 API
81
+
82
+ ### TileSchema 与分辨率
83
+
84
+ ```csharp
85
+ using BruTile;
86
+ using BruTile.Predefined;
87
+
88
+ // 全球 Web 墨卡托,默认 0-19 级;y 轴默认 OSM 约定
89
+ var schema = new GlobalSphericalMercator(minZoomLevel: 0, maxZoomLevel: 18);
90
+
91
+ // 自定义瓦片方案
92
+ var custom = new TileSchema
93
+ {
94
+ Name = "MyTiles",
95
+ Srs = "EPSG:3857",
96
+ Extent = new Extent(-20037508, -20037508, 20037508, 20037508),
97
+ YAxis = YAxis.OSM,
98
+ Format = "image/png",
99
+ };
100
+ custom.Resolutions.Add(0, new Resolution(0, 156543.03392804097, 256, 256));
101
+ custom.Resolutions.Add(1, new Resolution(1, 78271.51696402048, 256, 256));
102
+ ```
103
+
104
+ | 成员 | 说明 |
105
+ |------|------|
106
+ | `GlobalSphericalMercator(int min = 0, int max = 19)` | 标准 Web 墨卡托网格,最常用 |
107
+ | `TileSchema.Resolutions` | 级别 → `Resolution(level, unitsPerPixel, tileWidth, tileHeight, …)` |
108
+ | `TileSchema.YAxis` | `YAxis.OSM`(原点左上,y 向下)或 `YAxis.TMS`(原点左下,y 向上) |
109
+ | `TileSchema.Extent` / `Srs` / `Format` | 服务范围、坐标系与瓦片格式 |
110
+ | `schema.GetTileInfos(extent, unitsPerPixel)` | 按视口范围与分辨率求需要的瓦片 |
111
+ | `schema.GetTileInfos(extent, level)` | 按缩放级别求瓦片 |
112
+
113
+ ### HttpTileSource
114
+
115
+ ```csharp
116
+ using BruTile;
117
+ using BruTile.Predefined;
118
+ using BruTile.Web;
119
+
120
+ // 自定义 XYZ 服务;{s} 为子域占位,传 serverNodes 展开
121
+ var source = new HttpTileSource(
122
+ new GlobalSphericalMercator(0, 18),
123
+ "https://{s}.tile.example.com/{z}/{x}/{y}.png",
124
+ new[] {"a", "b", "c"},
125
+ name: "example");
126
+
127
+ using var http = new HttpClient();
128
+ var extent = new Extent(12900000, 4800000, 13000000, 4900000);
129
+ double resolution = extent.Width / 800; // 800 像素宽的视口
130
+
131
+ foreach (TileInfo info in source.Schema.GetTileInfos(extent, resolution))
132
+ {
133
+ byte[]? png = await source.GetTileAsync(http, info); // 6.x:显式传 HttpClient
134
+ Console.WriteLine($"{info.Index.Level}/{info.Index.Col}/{info.Index.Row}: {png?.Length ?? 0} bytes");
135
+ }
136
+ ```
137
+
138
+ | 成员 | 说明 |
139
+ |------|------|
140
+ | `HttpTileSource(ITileSchema, string urlFormatter, IEnumerable<string>? serverNodes, ...)` | 用 URL 模板构造,`{s}`/`{z}`/`{x}`/`{y}` 为占位符 |
141
+ | `HttpTileSource(ITileSchema, IUrlBuilder, ...)` | 自定义 URL 构造逻辑,适合带签名参数的商业服务 |
142
+ | `IHttpTileSource.GetTileAsync(HttpClient, TileInfo, CancellationToken?)` | 6.x 取瓦片,HttpClient 由调用方持有以便复用连接 |
143
+ | `Name` / `Attribution` | 显示名称与版权信息,出图时必须展示 |
144
+
145
+ `HttpClient` 按应用生命周期创建一次即可,每次请求 new 一个会耗尽 socket;这是 `IHttpTileSource` 把客户端作为参数传进来的主要原因。
146
+
147
+ ### KnownTileSources
148
+
149
+ ```csharp
150
+ using BruTile.Predefined;
151
+
152
+ var osm = KnownTileSources.Create(); // 默认 OpenStreetMap
153
+ var cycle = KnownTileSources.Create(KnownTileSource.OpenCycleMap);
154
+ var satellite = KnownTileSources.Create(KnownTileSource.BingAerial, apiKey: "YOUR_BING_KEY");
155
+ var noneApi = KnownTileSources.Create(KnownTileSource.EsriWorldTopo);
156
+ ```
157
+
158
+ `KnownTileSource` 覆盖 OSM/OpenCycleMap、Bing(Aerial/Hybrid/Roads 及其 Staging 变体)、Stamen 系列、Esri World 系列、BKG(德国)、Here 系列;需要密钥的服务通过 `apiKey` 传入。`Create` 还可传 `minZoomLevel` / `maxZoomLevel` 限制范围,但每个服务内部会再按自身能力截断(例如 OSM 最高 18 级、Bing 从 1 级起),实际可用级别以返回的 `Schema.Resolutions` 为准。
159
+
160
+ ### MBTiles 离线瓦片
161
+
162
+ ```csharp
163
+ using BruTile;
164
+ using BruTile.MbTiles;
165
+ using SQLite;
166
+
167
+ var connection = new SQLiteConnectionString("data/world.mbtiles", SQLiteOpenFlags.ReadOnly);
168
+ var mbTiles = new MbTilesTileSource(connection);
169
+
170
+ var tile = await mbTiles.GetTileAsync(new TileInfo {Index = new TileIndex(0, 0, 0)});
171
+ Console.WriteLine(tile?.Length);
172
+ ```
173
+
174
+ | 成员 | 说明 |
175
+ |------|------|
176
+ | `MbTilesTileSource(SQLiteConnectionString, ITileSchema?, MbTilesType, ...)` | 打开 MBTiles;schema 可从元数据读取,也可显式传入 |
177
+ | `MbTilesTileSource.GetTileAsync(TileInfo)` | 实现 `ILocalTileSource`,本地读取不需要 HttpClient |
178
+ | `MbTilesType` | `None` / `BaseLayer` / `Overlay` 等,用于区分图层语义 |
179
+
180
+ `SQLiteConnectionString` 来自 `sqlite-net`,6.0.0 的 MBTiles 包通过 `SQLitePCLRaw` 3.x 带原生库;发布到 AOT/裁剪环境时必须显式保留 SQLite 原生库,否则运行期报「无法加载 sqlite3」。
181
+
182
+ ---
183
+
184
+ ## 典型工作流
185
+
186
+ 把 OSM 在线底图和一个 MBTiles 离线图层组合起来,先判断视口需要哪些瓦片,再分别取图并统计缓存命中:
187
+
188
+ **输入**:视口范围(Web 墨卡托米)、屏幕像素宽度、MBTiles 文件
189
+ **输出**:控制台打印每张瓦片的来源与字节数
190
+
191
+ 1. 用 `GlobalSphericalMercator` 建立方案,按视口宽 / 像素宽算出分辨率
192
+ 2. 用 `GetTileInfos(extent, resolution)` 得到需要的瓦片列表
193
+ 3. MBTiles 优先,缺失时回落到 HTTP 源
194
+ 4. 复用同一个 `HttpClient`
195
+
196
+ ```csharp
197
+ using BruTile;
198
+ using BruTile.MbTiles;
199
+ using BruTile.Predefined;
200
+ using SQLite;
201
+
202
+ var extent = new Extent(12957000, 4852000, 12960000, 4855000);
203
+ const int viewportWidth = 1024;
204
+ double resolution = extent.Width / viewportWidth;
205
+
206
+ var http = new HttpClient();
207
+ var osm = KnownTileSources.Create(KnownTileSource.OpenStreetMap);
208
+
209
+ var offline = new MbTilesTileSource(
210
+ new SQLiteConnectionString("data/region.mbtiles", SQLiteOpenFlags.ReadOnly));
211
+
212
+ int fromCache = 0, fromWeb = 0;
213
+ foreach (TileInfo info in osm.Schema.GetTileInfos(extent, resolution))
214
+ {
215
+ byte[]? bytes = await offline.GetTileAsync(info);
216
+ if (bytes is {Length: > 0})
217
+ {
218
+ fromCache++;
219
+ continue;
220
+ }
221
+
222
+ bytes = await osm.GetTileAsync(http, info);
223
+ if (bytes is {Length: > 0}) fromWeb++;
224
+ }
225
+
226
+ Console.WriteLine($"cache={fromCache} web={fromWeb}");
227
+ ```
228
+
229
+ **检查点**:瓦片数量随缩放级别呈 4 倍增长,`fromWeb` 异常大通常说明 MBTiles 的 y 轴约定与 schema 不一致(OSM 与 TMS 相反),可在 `MbTilesTileSource` 构造时显式传 schema 验证。
230
+
231
+ ---
232
+
233
+ ## 最佳实践
234
+
235
+ 1. **复用 HttpClient 与 TileSource**:瓦片源与 HttpClient 都是无状态可复用的对象,放在字段或 DI 单例里
236
+ 2. **明确 y 轴约定**:OSM 原点在左上、TMS 在左下;瓦片行列整体错位一整屏,先把 `YAxis` 对齐再排查网络
237
+ 3. **缓存分两层**:内存缓存应对快速平移缩放,MBTiles 或文件系统缓存应对离线与省钱;构造 `HttpTileSource` 时传 `persistentCache`
238
+ 4. **限制缩放级别**:`GlobalSphericalMercator(min, max)` 与服务实际级别一致,超出范围只会拿到 404
239
+ 5. **尊重版权与速率限制**:OSM 等公共服务有使用政策,生产环境用商业或自建瓦片服务,`Attribution` 要显示出来
240
+ 6. **MBTiles 只读打开**:`SQLiteOpenFlags.ReadOnly` + 单例连接,避免多线程写锁
241
+ 7. **按目标框架选版本**:net8+ 用 6.0.0;netstandard2.0 或 SharpMap 1.2 场景降到 5.0.6/4.0.0
242
+
243
+ ---
244
+
245
+ ## 常见问题
246
+
247
+ | 问题 | 原因与解决 |
248
+ |------|------------|
249
+ | 编译报 `CS0246: 找不到类型 KnownTileSources` | 缺少 `using BruTile.Predefined;`;6.x 中该类型命名空间是 `BruTile.Predefined` |
250
+ | 找不到 `BruTile.Desktop` 包 | 该包在 4.0 起被删除,内容并入 `BruTile`:改用 `BruTile` 主包与 `BruTile.MbTiles` |
251
+ | `HttpTileSource.GetTileAsync(tileInfo)` 编译失败 | 6.x 改为 `IHttpTileSource.GetTileAsync(httpClient, tileInfo, cancellationToken)`:传入复用的 `HttpClient`,或降到 5.0.6 |
252
+ | 瓦片全部 404 | 缩放级别超出服务范围,或 `{z}/{x}/{y}` 模板与服务的路径顺序不符;先用浏览器直接请求一张瓦片验证模板 |
253
+ | 瓦片内容上下颠倒 / 行列错位 | OSM(原点左上)与 TMS(原点左下)的 y 轴相反:调整 `TileSchema.YAxis` 或改用 `YAxis.TMS` 的方案 |
254
+ | MBTiles 打开报「无法加载 sqlite3」 | 原生库未随应用发布:确认 `SQLitePCLRaw` 相关包被复制到输出目录,AOT/裁剪时显式保留 |
255
+ | 拉取大量瓦片后程序卡死或连接耗尽 | 每次请求 new `HttpClient`:改为共享实例,并配合并发上限(如 `SemaphoreSlim`) |
256
+ | 地图上瓦片模糊或偏移 | 分辨率计算用了错误的视口宽度,或瓦片尺寸不是 256:`Resolution` 的 `tileWidth`/`tileHeight` 必须与服务一致 |
257
+
258
+ ---
259
+
260
+ ## AI 使用建议
261
+
262
+ - **执行环境**:`dotnet add package` / `dotnet build` / `dotnet run` 在终端中执行,首次 restore 需访问 NuGet。
263
+ - **先探测版本**:`dotnet list package` 确认 `BruTile` 是 6.0.0 还是 5.x——两者的 `GetTileAsync` 签名不同,写代码前必须确认;目标框架须为 net8.0/net9.0 才能用 6.0.0。
264
+ - **验证产物**:先跑「schema + GetTileInfos 计数」的最小用例(0 级应为 1 张瓦片),再验证网络取图;取图结果检查字节长度大于 0,不要只看是否抛异常。
265
+ - **网络与权限**:抓取第三方瓦片服务前确认其使用政策与是否需要 key;不要在示例里写死真实密钥。
266
+ - **失败信号**:404 先查模板与级别;行列错位查 `YAxis`;`DllNotFoundException`/无法加载 sqlite3 查 MBTiles 原生库复制。
267
+ - **排错顺序**:先离线验证 schema 计算,再接网络层,最后接 UI;把三层分开验证能快速定位是坐标、网络还是渲染问题。
268
+
269
+ ## 相关技能
270
+
271
+ - **mapsui** — 现代跨平台 .NET 地图组件,直接用 BruTile 作瓦片源:[../mapsui/SKILL.md](../mapsui/SKILL.md)
272
+ - **sharpmap** — 旧版渲染库,通过 `SharpMap.Layers.BruTile` 使用 BruTile(版本受限):[../sharpmap/SKILL.md](../sharpmap/SKILL.md)
273
+ - **nettopologysuite** — 空间几何与坐标,常与瓦片坐标换算配合:[../nettopologysuite/SKILL.md](../nettopologysuite/SKILL.md)
274
+ - **projnet4geoapi** — 坐标变换,处理非 Web 墨卡托瓦片时使用:[../projnet4geoapi/SKILL.md](../projnet4geoapi/SKILL.md)
275
+ - **leaflet** — Web 端瓦片地图,便于对照 XYZ 模板与 y 轴约定:[../leaflet/SKILL.md](../leaflet/SKILL.md)
276
+
277
+ ## 参考资源
278
+
279
+ - 源码与示例(`Samples/BruTile.GettingStarted`):<https://github.com/BruTile/BruTile>
280
+ - 预定义瓦片源定义:<https://github.com/BruTile/BruTile/blob/master/BruTile/Predefined/KnownTileSources.cs>
281
+ - NuGet:<https://www.nuget.org/packages/BruTile>
282
+ - MBTiles 规范:<https://github.com/mapbox/mbtiles-spec>
283
+ - OSM 瓦片使用政策:<https://operations.osmfoundation.org/policies/tiles/>
@@ -1,16 +1,10 @@
1
1
  ---
2
2
  name: cesiumjs
3
- description: "Use when building browser-based 3D globes, 3D Tiles, CZML/time-dynamic data, or glTF models with npm cesium 1.146.0 — Viewer, Cesium3DTileset, Ion token (Cesium.Ion.defaultAccessToken), CESIUM_BASE_URL for Workers/Assets/Widgets, GCJ-02 tile offset, or debugging a black screen after a Vite/Webpack build."
4
- tags:
5
- - javascript
6
- - webgl
7
- - 3d
8
- - 3d-tiles
9
- - gltf
10
- - earth
11
- - map
12
- - web
13
- - visualization
3
+ description: "Use when building browser-based 3D globes, 3D Tiles, CZML/time-dynamic data, or glTF models with npm cesium 1.147.0 — Viewer, Cesium3DTileset, Ion token (Cesium.Ion.defaultAccessToken), CESIUM_BASE_URL for Workers/Assets/Widgets, GCJ-02 tile offset, or debugging a black screen after a Vite/Webpack build."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "javascript, webgl, 3d, 3d-tiles, gltf, earth, map, web, visualization"
14
8
  ---
15
9
 
16
10
  > **项目地址:** <https://github.com/CesiumGS/cesium>
@@ -21,7 +15,7 @@ tags:
21
15
  >
22
16
  > **Sandcastle:** <https://sandcastle.cesium.com/>
23
17
  >
24
- > **最新版本:** 1.146.0(截至2026-10,npm `cesium`)
18
+ > **最新版本:** 1.147.0(截至 2026-11,npm `cesium`;1.146 起新增 `@cesium/core` 包)
25
19
  >
26
20
  > **许可证:** Apache-2.0
27
21
 
@@ -40,28 +34,40 @@ CesiumJS 提供:
40
34
 
41
35
  ## 安装
42
36
 
37
+ ### 方式一:npm
38
+
43
39
  ```bash
44
40
  npm install cesium
41
+ npm ls cesium # 验证:应显示 cesium@1.147.0
45
42
  ```
46
43
 
47
- ```html
48
- <link href="https://cdn.jsdelivr.net/npm/cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
49
- <script src="https://cdn.jsdelivr.net/npm/cesium/Build/Cesium/Cesium.js"></script>
50
- ```
51
-
52
- > **1.146 变更:** 数学/几何/时间/工具类被拆分为新包 `@cesium/core`(`cesium@1.146.0` 依赖 `@cesium/core@^0.1.0`)。从 `cesium` 主包导入的代码不受影响;直接按子路径引用 `@cesium/engine` 的代码需改从 `@cesium/core` 导入(旧导出计划在后续版本移除,1.146 仍可用)。
53
-
54
- ### Vite 集成
55
-
56
44
  ```js
57
45
  import { defineConfig } from 'vite';
58
46
  import cesium from 'vite-plugin-cesium';
47
+
59
48
  export default defineConfig({ plugins: [cesium()] });
60
49
  ```
61
50
 
62
- ### Webpack 集成
51
+ ### 方式二:CDN
63
52
 
64
- 需将 `node_modules/cesium/Build/Cesium/{Workers,Assets,Widgets}` 拷贝到输出目录,并设置 `window.CESIUM_BASE_URL`。
53
+ ```html
54
+ <link href="https://cdn.jsdelivr.net/npm/cesium@1.147.0/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
55
+ <script src="https://cdn.jsdelivr.net/npm/cesium@1.147.0/Build/Cesium/Cesium.js"></script>
56
+ ```
57
+
58
+ ```bash
59
+ # 验证 CDN 版本可达
60
+ curl.exe -I https://cdn.jsdelivr.net/npm/cesium@1.147.0/Build/Cesium/Cesium.js # 期望 200
61
+ ```
62
+
63
+ ### 打包器接入
64
+
65
+ - **Vite**:用 `vite-plugin-cesium`,按上面的 `vite.config.js` 注册,插件负责拷贝静态资源
66
+ - **Webpack**:将 `node_modules/cesium/Build/Cesium/{Workers,Assets,Widgets}` 拷到输出目录,并在入口最早处设置 `window.CESIUM_BASE_URL`
67
+
68
+ > **1.146 起的包拆分(1.147 仍适用):** 数学/几何/时间/工具类已拆到 `@cesium/core`(1.147 的 `cesium` 依赖 `@cesium/core@^0.1.1`)。从 `cesium` 主包导入的代码不受影响;从 `@cesium/engine` 导入这些类的代码需改从 `@cesium/core` 导入。`@cesium/engine` 的旧导出已弃用,官方计划在 1.150 移除。
69
+ >
70
+ > **1.147 变更(2026-11-02):** 主要修复 `Cesium3DTileset` 在 `cacheBytes` 边界反复加载同一瓦片、椭球面附近模型动态环境光等问题;新增 glTF `KHR_materials_emissive_strength` 扩展支持与实验性 `IonAssetElementService`。无破坏性 API 变更。
65
71
 
66
72
  ---
67
73
 
@@ -231,11 +237,51 @@ viewer.trackedEntity = entity;
231
237
 
232
238
  ## 典型工作流
233
239
 
234
- 1. **初始化 Viewer**:使用 `Cesium.Viewer` 创建三维地球,设置地形和影像提供者
235
- 2. **加载数据**:根据数据类型选择合适 API——GeoJSON/CZML 用 `DataSource`,3D 瓦片用 `Cesium3DTileset`,单模型用 `Entity.model`
236
- 3. **设置相机**:使用 `camera.flyTo()` 定位到目标区域
237
- 4. **添加交互**:通过 `ScreenSpaceEventHandler` 处理点击拾取
238
- 5. **性能优化**:根据场景复杂度启用 `requestRenderMode`、调整 `maximumScreenSpaceError`
240
+ 以「GeoJSON 点位 + 倾斜摄影 3D Tiles」为例,输入 `data/poi.geojson` 与 `/tiles/tileset.json`,输出可点击拾取的三维场景。
241
+
242
+ 1. **初始化 Viewer**:`new Cesium.Viewer('cesiumContainer', { terrainProvider: await Cesium.createWorldTerrainAsync() })`
243
+ 2. **加载矢量数据**:`GeoJsonDataSource.load()` → `viewer.dataSources.add(ds)` → `viewer.flyTo(ds)`
244
+ 3. **加载 3D Tiles**:`Cesium3DTileset.fromUrl()` → `scene.primitives.add(tileset)` → `viewer.zoomTo(tileset)`
245
+ 4. **添加交互**:`ScreenSpaceEventHandler` + `scene.pick()` 取 `picked.id`,`camera.pickEllipsoid()` 取经纬度
246
+ 5. **性能与释放**:静态要素用 Primitive,`requestRenderMode = true`,卸载时 `tileset.destroy()` / `viewer.destroy()`
247
+
248
+ ```js
249
+ import * as Cesium from 'cesium';
250
+ import 'cesium/Build/Cesium/Widgets/widgets.css';
251
+
252
+ Cesium.Ion.defaultAccessToken = import.meta.env.VITE_CESIUM_ION_TOKEN;
253
+
254
+ const viewer = new Cesium.Viewer('cesiumContainer', {
255
+ terrainProvider: await Cesium.createWorldTerrainAsync(),
256
+ timeline: false,
257
+ animation: false
258
+ });
259
+
260
+ // 1) GeoJSON 点位:统一改成扁平圆点,避免默认图钉遮挡
261
+ const ds = await Cesium.GeoJsonDataSource.load('/data/poi.geojson', { clampToGround: true });
262
+ viewer.dataSources.add(ds);
263
+ for (const entity of ds.entities.values) {
264
+ entity.billboard = undefined;
265
+ entity.point = new Cesium.PointGraphics({ pixelSize: 8, color: Cesium.Color.ORANGE });
266
+ }
267
+ await viewer.flyTo(ds);
268
+
269
+ // 2) 3D Tiles:加载倾斜摄影并飞到数据范围
270
+ const tileset = await Cesium.Cesium3DTileset.fromUrl('/tiles/tileset.json', {
271
+ maximumScreenSpaceError: 16
272
+ });
273
+ viewer.scene.primitives.add(tileset);
274
+ await viewer.zoomTo(tileset);
275
+
276
+ // 3) 点击拾取:先试 3D Tiles / 点要素,再回退到椭球面坐标
277
+ const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
278
+ handler.setInputAction((e) => {
279
+ const picked = viewer.scene.pick(e.position);
280
+ console.log('picked:', Cesium.defined(picked) ? picked.id : null);
281
+ }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
282
+ ```
283
+
284
+ **验证产物**:`npm run build` 后 `python -m http.server 5173 -d dist`,`curl.exe -I http://localhost:5173/Cesium/Workers/createVerticesFromHeightmap.js` 返回 200 才说明 Workers 已随产物发布。
239
285
 
240
286
  ---
241
287
 
@@ -255,20 +301,20 @@ viewer.trackedEntity = entity;
255
301
 
256
302
  | 问题 | 解决 |
257
303
  |------|------|
258
- | 黑屏 | 检查 `CESIUM_BASE_URL` 与静态资源 |
304
+ | 黑屏 / 资源 404 | 控制台报 `Unable to determine Cesium base URL automatically, try defining a global variable called CESIUM_BASE_URL.` 时,在入口最早处设 `window.CESIUM_BASE_URL = '/Cesium'`,并确认 `Workers/Assets/Widgets` 已随构建产物发布 |
259
305
  | 模型贴地不准 | `HeightReference.CLAMP_TO_GROUND` 或地形采样 |
260
- | 性能卡顿 | 启用 `requestRenderMode`,降低 `maximumScreenSpaceError` |
306
+ | 性能卡顿 | 启用 `requestRenderMode`,降低 `maximumScreenSpaceError`;静态要素改 Primitive |
307
+ | 报 `WebGL 2 context is required` | 浏览器/环境未提供 WebGL2(无头浏览器、远程桌面软件渲染);开启硬件加速或改用支持 WebGL2 的环境 |
261
308
  | 国内瓦片偏移 | 使用 GCJ02→WGS84 纠偏 |
262
309
  | Token 过期 | 不需要 ion 时不设置 token;或自托管 |
263
310
 
264
311
  ---
265
312
 
266
- ## DeepSeek Harness 使用建议
313
+ ## AI 使用建议
267
314
 
268
- - **加载与引用**:用 `skill("cesiumjs")` 加载(用户也可输入 `/cesiumjs`);本技能无 reference 子目录,示例代码直接落到会话工作区的工程里,技能目录只读。
269
- - **执行环境**:`npm install`、`npm run build` 交给 `pwsh`;Windows 下 `npm` 实为 `npm.cmd`,脚本里写 `cmd /c npm run build` 更稳;装包和大构建用后台作业,输出重定向到文件再分段读。
270
- - **先探测版本**:`npm ls cesium`(未安装时 `npm view cesium version`)。本技能按 1.146.0 编写:该版本依赖 `@cesium/core@^0.1.0`,数学/几何/时间/工具类已拆到 `@cesium/core`,低于 1.146 的工程不要照搬这条迁移建议。
271
- - **验证产物**:`npm run build` 通过后用 `npx serve dist` 或 `python -m http.server 5173 -d dist` 起静态服务,用 `curl.exe -I` 检查 `http://localhost:5173/Cesium.js` 与 `.../Cesium/Widgets/widgets.css` 返回 200(404 或 text/html 说明资源没拷贝);DSH 不打开浏览器,把 URL 和预期画面交给用户,有截图再用 `read_image` 核对。
315
+ - **执行环境**:`npm install`、`npm run build` 在终端中执行;Windows 下 `npm` 实为 `npm.cmd`,脚本里写 `cmd /c npm run build` 更稳;装包和大构建放后台运行,输出重定向到文件再分段读。
316
+ - **先探测版本**:`npm ls cesium`(未安装时 `npm view cesium version`)。本技能按 1.147.0 编写:1.146 起依赖 `@cesium/core@^0.1.x`,数学/几何/时间/工具类已拆到 `@cesium/core`,低于 1.146 的工程不要照搬这条迁移建议;旧 `@cesium/engine` 导出计划在 1.150 移除。
317
+ - **验证产物**:`npm run build` 通过后用 `npx serve dist` 或 `python -m http.server 5173 -d dist` 起静态服务,用 `curl.exe -I` 检查 `http://localhost:5173/Cesium.js` 与 `.../Cesium/Widgets/widgets.css` 返回 200(404 或 text/html 说明资源没拷贝);AI 助手通常看不到浏览器画面,把 URL 和预期画面交给用户,环境支持读图时用截图核对。
272
318
  - **Ion 与部署**:`Cesium.Ion.defaultAccessToken` 从环境变量注入(Vite 用 `import.meta.env.VITE_CESIUM_ION_TOKEN`),不要写进源码或提交;黑屏先查 `window.CESIUM_BASE_URL` 与 `Workers/Assets/Widgets` 是否随构建产物发布。
273
319
  - **坐标与性能**:定位一律 `Cesium.Cartesian3.fromDegrees(lon, lat, height)`;大量静态要素用 Primitive,少量动态要素才用 Entity;`clampToGround` 只在需要贴地时开启。
274
320
  - **常见症状**:瓦片整体错位是国内底图的 GCJ-02 偏移,需先纠偏;ion 服务 401/403 多为 token 未设置或失效;`tileset.destroy()`、`viewer.dataSources.remove()` 不调用会持续占用显存。
@@ -1,26 +1,19 @@
1
1
  ---
2
2
  name: deck-gl
3
- description: "Use when visualizing large geospatial datasets in the browser with deck.gl 9.4.0 — ScatterplotLayer/GeoJsonLayer, HexagonLayer/ScreenGridLayer aggregation, MVTLayer/TileLayer, @deck.gl/mapbox MapboxOverlay over MapLibre, or debugging blank canvases, stale data props and mismatched @deck.gl/* subpackage versions."
4
- tags:
5
- - javascript
6
- - web
7
- - webgl
8
- - webgpu
9
- - data-visualization
10
- - geospatial
11
- - map-layers
12
- - aggregation
13
- - maplibre
14
- - mapbox
3
+ description: "Use when visualizing large geospatial datasets in the browser with deck.gl 9.4.1 — ScatterplotLayer/GeoJsonLayer, HexagonLayer/ScreenGridLayer aggregation, MVTLayer/TileLayer, @deck.gl/mapbox MapboxOverlay over MapLibre, or debugging blank canvases, stale data props and mismatched @deck.gl/* subpackage versions."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "javascript, web, webgl, webgpu, data-visualization, geospatial, map-layers, aggregation, maplibre, mapbox"
15
8
  ---
16
9
 
17
10
  > **项目地址:** <https://github.com/visgl/deck.gl>
18
11
  >
19
12
  > **官方文档:** <https://deck.gl/>
20
13
  >
21
- > **最新版本:** 9.4.0(截至 2026-10,npm `deck.gl` 与 GitHub Release 一致)
14
+ > **最新版本:** 9.4.1(截至 2026-11,npm `deck.gl` dist-tag `latest`)
22
15
  >
23
- > **许可证:** MIT(`gh api repos/visgl/deck.gl --jq '.license.spdx_id'` 核实)
16
+ > **许可证:** MIT
24
17
 
25
18
  ## 概述
26
19
 
@@ -58,7 +51,7 @@ npm install @deck.gl/mapbox maplibre-gl # 与 MapLibre / Mapbox 底图集成
58
51
  ### CDN 快速试用
59
52
 
60
53
  ```html
61
- <script src="https://unpkg.com/deck.gl@9.4.0/dist.min.js"></script>
54
+ <script src="https://unpkg.com/deck.gl@9.4.1/dist.min.js"></script>
62
55
  ```
63
56
 
64
57
  ### 验证
@@ -99,7 +92,7 @@ const deck = new Deck({
99
92
  controller: true, // 设为 true 启用拖拽/缩放/旋转
100
93
  layers: [],
101
94
  getTooltip: ({object}) => object,
102
- useDevicePixels: true // 关闭可显著降低高分屏下的像素开销
95
+ useDevicePixels: true // 设 false 可显著降低高分屏下的像素开销
103
96
  });
104
97
 
105
98
  deck.setProps({layers: []}); // 后续增量更新,勿重建 Deck 实例
@@ -360,7 +353,7 @@ deck.pickObject({x: 100, y: 100, radius: 4, layerIds: ['stations']}); // 程序
360
353
  4. 需要矢量瓦片数据时叠加 `MVTLayer`
361
354
  5. 绑定 `getTooltip` 与 `onClick` 实现悬停与点击反馈
362
355
  6. 数据刷新时调用 `overlay.setProps({layers: [...]})`,保持 `data` 引用稳定
363
- 7. 组件卸载时调用 `overlay.finalize()` 释放 GPU 资源
356
+ 7. 组件卸载时 `map.removeControl(overlay)`(MapboxOverlay 无公开 `finalize()`,由 onRemove 释放内部 Deck)
364
357
 
365
358
  ```javascript
366
359
  import {MapboxOverlay} from '@deck.gl/mapbox';
@@ -422,15 +415,15 @@ map.addControl(overlay);
422
415
 
423
416
  ---
424
417
 
425
- ## 参考资源
418
+ ## AI 使用建议
426
419
 
427
- - 官方文档与示例:<https://deck.gl/>
428
- - 独立模式快速上手:<https://deck.gl/docs/get-started/using-standalone>
429
- - 与底图集成:<https://deck.gl/docs/get-started/using-with-map>
430
- - 图层目录:<https://deck.gl/docs/api-reference/layers>
431
- - `MapboxOverlay` API:<https://deck.gl/docs/api-reference/mapbox/mapbox-overlay>
432
- - 性能调优指南:<https://deck.gl/docs/developer-guide/performance>
433
- - 源码与发布记录:<https://github.com/visgl/deck.gl>
420
+ - **执行环境**:`npm install`、`npm run build` 在终端中执行;子包多、安装输出长,重定向到文件再分段读。
421
+ - **先探测版本**:`npm ls deck.gl @deck.gl/core @deck.gl/layers @deck.gl/geo-layers`;所有 `@deck.gl/*` 必须是同一版本 9.4.1,混版会报 `Cannot read properties of undefined`。本技能按 9.4.1 编写。
422
+ - **验证产物**:`npm run build` 后 `npx serve dist`,`curl.exe -I http://localhost:5173/` 确认入口;WebGL 是否真出图只能由浏览器确认,AI 助手通常看不到浏览器画面,请用户看画面和控制台,环境支持读图时用截图核对。
423
+ - **无 GPU 环境**:无头/CI 环境无法验证 WebGL,构建通过不等于渲染正确,不要据此报告“已渲染”。
424
+ - **数据与坐标**:位置一律 `[经度, 纬度]`;保持 `data` 引用稳定,不要在渲染路径里 `filter`/`map` 生成新数组,否则 GPU 缓冲反复重建。
425
+ - **常见症状**:空白画布先查容器高度与底图;数据变了画面不变用 `updateTriggers`;tooltip 无反应是 `pickable` 默认 false。
426
+ - **安全与权限**:装包、起 dev server 前先征得用户同意;用 Mapbox 底图时提醒 token 与计费。
434
427
 
435
428
  ## 相关技能
436
429
 
@@ -439,13 +432,12 @@ map.addControl(overlay);
439
432
  - **leaflet** — 轻量 2D 瓦片地图,适合中小数据量与简单场景:[../leaflet/SKILL.md](../leaflet/SKILL.md)
440
433
  - **cesiumjs** — 三维地球与 3D Tiles 可视化:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
441
434
 
442
- ## DeepSeek Harness 使用建议
435
+ ## 参考资源
443
436
 
444
- - **加载与引用**:用 `skill("deck-gl")` 加载(用户也可输入 `/deck-gl`);本技能无 reference 子目录,示例代码写入会话工作区工程,技能目录只读。
445
- - **执行环境**:`npm install`、`npm run build` 交给 `pwsh`;子包多、安装输出长,重定向到文件再分段读。
446
- - **先探测版本**:`npm ls deck.gl @deck.gl/core @deck.gl/layers @deck.gl/geo-layers`;所有 `@deck.gl/*` 必须是同一版本 9.4.0,混版会报 `Cannot read properties of undefined`。本技能按 9.4.0 编写。
447
- - **验证产物**:`npm run build` 后 `npx serve dist`,`curl.exe -I http://localhost:5173/` 确认入口;WebGL 是否真出图只能由浏览器确认,DSH 不打开浏览器,请用户看画面和控制台,有截图再用 `read_image`。
448
- - **无 GPU 环境**:无头/CI 环境无法验证 WebGL,构建通过不等于渲染正确,不要据此报告“已渲染”。
449
- - **数据与坐标**:位置一律 `[经度, 纬度]`;保持 `data` 引用稳定,不要在渲染路径里 `filter`/`map` 生成新数组,否则 GPU 缓冲反复重建。
450
- - **常见症状**:空白画布先查容器高度与底图;数据变了画面不变用 `updateTriggers`;tooltip 无反应是 `pickable` 默认 false。
451
- - **安全与权限**:装包、起 dev server 前先征得用户同意;用 Mapbox 底图时提醒 token 与计费。
437
+ - 官方文档与示例:<https://deck.gl/>
438
+ - 独立模式快速上手:<https://deck.gl/docs/get-started/using-standalone>
439
+ - 与底图集成:<https://deck.gl/docs/get-started/using-with-map>
440
+ - 图层目录:<https://deck.gl/docs/api-reference/layers>
441
+ - `MapboxOverlay` API:<https://deck.gl/docs/api-reference/mapbox/mapbox-overlay>
442
+ - 性能调优指南:<https://deck.gl/docs/developer-guide/performance>
443
+ - 源码与发布记录:<https://github.com/visgl/deck.gl>