@dsh-gis/dsh-opengis-skill 0.3.0 → 0.4.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 (63) hide show
  1. package/CHANGELOG.md +71 -1
  2. package/README.md +27 -15
  3. package/adaptations/common.md +12 -8
  4. package/adaptations/deck-gl.md +1 -1
  5. package/adaptations/duckdb-spatial.md +6 -6
  6. package/adaptations/gdal.md +4 -4
  7. package/adaptations/geolibre.md +1 -1
  8. package/adaptations/geonode.md +1 -1
  9. package/adaptations/geopandas.md +3 -3
  10. package/adaptations/geos.md +8 -0
  11. package/adaptations/geoserver.md +1 -1
  12. package/adaptations/grass-gis.md +3 -3
  13. package/adaptations/kepler-gl.md +1 -1
  14. package/adaptations/leaflet.md +1 -1
  15. package/adaptations/mapbox-gl-js.md +1 -1
  16. package/adaptations/maplibre-gl-js.md +8 -0
  17. package/adaptations/maplibre-native.md +8 -0
  18. package/adaptations/mapserver.md +2 -2
  19. package/adaptations/mapsui.md +1 -1
  20. package/adaptations/opendronemap.md +8 -0
  21. package/adaptations/opengis-all.md +1 -1
  22. package/adaptations/pdal.md +3 -3
  23. package/adaptations/projnet4geoapi.md +1 -1
  24. package/adaptations/qgis-server.md +1 -1
  25. package/adaptations/shapely.md +2 -2
  26. package/adaptations/spatialite.md +6 -6
  27. package/adaptations/stac-cog-titiler.md +8 -0
  28. package/adaptations/whitebox-tools.md +4 -4
  29. package/assets/deck-gl/SKILL.md +1 -0
  30. package/assets/duckdb-spatial/SKILL.md +36 -13
  31. package/assets/gdal/SKILL.md +6 -6
  32. package/assets/gdal-api/SKILL.md +2 -2
  33. package/assets/geolibre/SKILL.md +1 -0
  34. package/assets/geonode/SKILL.md +3 -3
  35. package/assets/geopandas/SKILL.md +42 -8
  36. package/assets/geopandas/reference/core-api.md +51 -0
  37. package/assets/geos/SKILL.md +372 -0
  38. package/assets/geoserver/SKILL.md +1 -1
  39. package/assets/geoserver-cloud/SKILL.md +0 -2
  40. package/assets/grass-gis/SKILL.md +31 -7
  41. package/assets/kepler-gl/SKILL.md +1 -0
  42. package/assets/leaflet/SKILL.md +2 -2
  43. package/assets/mapbox-gl-js/SKILL.md +1 -0
  44. package/assets/maplibre-gl-js/SKILL.md +478 -0
  45. package/assets/maplibre-native/SKILL.md +383 -0
  46. package/assets/mapserver/SKILL.md +7 -5
  47. package/assets/mapsui/SKILL.md +4 -2
  48. package/assets/opendronemap/SKILL.md +309 -0
  49. package/assets/opengis-all/SKILL.md +1 -0
  50. package/assets/pdal/SKILL.md +9 -1
  51. package/assets/projnet4geoapi/SKILL.md +1 -1
  52. package/assets/shapely/SKILL.md +24 -4
  53. package/assets/shapely/reference/operations-reference.md +30 -0
  54. package/assets/spatialite/SKILL.md +8 -2
  55. package/assets/stac-cog-titiler/SKILL.md +420 -0
  56. package/assets/whitebox-tools/SKILL.md +20 -4
  57. package/lib/adaptations.d.ts +13 -1
  58. package/lib/adaptations.js +102 -20
  59. package/lib/index.js +28 -2
  60. package/locale/en.json +1 -1
  61. package/locale/zh.json +1 -1
  62. package/package.json +8 -3
  63. package/upstream.json +36 -26
@@ -0,0 +1,383 @@
1
+ ---
2
+ name: maplibre-native
3
+ description: "Use when embedding GPU-accelerated vector maps natively in Android, iOS, macOS, Linux, Windows or Node.js with MapLibre Native (C++ core, BSD-2-Clause) — org.maplibre.gl:android-sdk MapView/MapLibre.getInstance/getMapAsync, CocoaPods MapLibre MLNMapView, @maplibre/maplibre-gl-native mbgl.Map render, offline caching, Bazel/CMake builds, or debugging green map screens, missing submodules and NDK build failures."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "cpp, android, ios, macos, linux, nodejs, vector-tiles, opengl, metal, offline"
8
+ ---
9
+
10
+ > **项目地址:** <https://github.com/maplibre/maplibre-native>
11
+ >
12
+ > **开发者文档:** <https://maplibre.org/maplibre-native/docs/book/>(架构、构建与贡献指南)
13
+ >
14
+ > **最新版本:** Android `13.5.4`([GitHub Latest](https://github.com/maplibre/maplibre-native/releases)、[Maven](https://central.sonatype.com/artifact/org.maplibre.gl/android-sdk/versions),13.x 特性线同时有 `13.7.1`)/ iOS `7.0.0`(CocoaPods `MapLibre`)/ Node `@maplibre/maplibre-gl-native` `6.4.1`(截至 2026-11,[发布记录](https://github.com/maplibre/maplibre-native/releases);另有 `*-YYYY.MM.DD-globe` 实验线,非稳定版)
15
+ >
16
+ > **许可证:** BSD-2-Clause(含部分 FreeType 等第三方组件,见 `LICENSES.core.md`)
17
+
18
+ ## 概述
19
+
20
+ MapLibre Native 是 Mapbox GL Native 的非商业许可分叉(2020-12 上游改为专有许可后分出),核心是一套 C++ 渲染引擎:解析 MapLibre Style Spec,按需拉取矢量/栅格瓦片,在 GPU 上批量绘制标注与几何。各平台只是同一内核的绑定层,因此样式、瓦片与交互语义在 Android/iOS/桌面/Node 之间保持一致。
21
+
22
+ - **GPU 矢量渲染**:OpenGL ES(Android)、Metal(iOS/macOS)等后端驱动,支持连续缩放与运行时样式切换
23
+ - **Style Spec 驱动**:与 maplibre-gl-js 共用样式规范,同一份 JSON 可在前端与原生端复用
24
+ - **平台绑定**:Android(`org.maplibre.gl:android-sdk`)、iOS/macOS(CocoaPods `MapLibre`、SPM)、Node.js(`@maplibre/maplibre-gl-native`)、Qt(maplibre-native-qt)、Compose Multiplatform(maplibre-compose)
25
+ - **离线能力**:瓦片缓存与离线区域下载,弱网/移动端场景可预置底图
26
+ - **可嵌入 C++**:Linux/Windows 构建产出 `.a`/库文件与渲染工具,可嵌入自有 C++ 应用
27
+ - **免 token**:不依赖商业账号,底图可用 demotiles 或自建瓦片服务
28
+
29
+ 与相邻技术的差异:maplibre-gl-js 是浏览器端 JS 实现,适合网页;MapLibre Native 面向原生应用与离线场景,性能与内存控制更贴近移动端;CesiumJS/Cesium Native 偏三维地球,MapLibre Native 以二维矢量地图为主(三维地形为辅助能力)。
30
+
31
+ ---
32
+
33
+ ## 环境准备
34
+
35
+ ### Android
36
+
37
+ Maven 坐标在 Maven Central,版本以 [Maven 元数据](https://repo1.maven.org/maven2/org/maplibre/gl/android-sdk/maven-metadata.xml) 为准。2026-11 时 `13.x` 特性线最新为 `13.7.1`,而 GitHub 标为 Latest 的是更晚发布的维护版 `13.5.4`——两者都在维护,按项目策略选用并保持一致。
38
+
39
+ ```gradle
40
+ dependencies {
41
+ implementation 'org.maplibre.gl:android-sdk:13.5.4'
42
+ }
43
+ ```
44
+
45
+ ```xml
46
+ <org.maplibre.android.maps.MapView
47
+ android:id="@+id/mapView"
48
+ android:layout_width="match_parent"
49
+ android:layout_height="match_parent" />
50
+ ```
51
+
52
+ ```kotlin
53
+ import org.maplibre.android.MapLibre
54
+ import org.maplibre.android.camera.CameraPosition
55
+ import org.maplibre.android.geometry.LatLng
56
+ import org.maplibre.android.maps.MapView
57
+
58
+ class MainActivity : AppCompatActivity() {
59
+ private lateinit var mapView: MapView
60
+
61
+ override fun onCreate(savedInstanceState: Bundle?) {
62
+ super.onCreate(savedInstanceState)
63
+ MapLibre.getInstance(this) // 必须在 MapView 之前初始化
64
+ setContentView(R.layout.activity_main)
65
+
66
+ mapView = findViewById(R.id.mapView)
67
+ mapView.getMapAsync { map ->
68
+ map.setStyle("https://demotiles.maplibre.org/style.json")
69
+ map.cameraPosition = CameraPosition.Builder()
70
+ .target(LatLng(0.0, 0.0))
71
+ .zoom(1.0)
72
+ .build()
73
+ }
74
+ }
75
+
76
+ override fun onStart() { super.onStart(); mapView.onStart() }
77
+ override fun onResume() { super.onResume(); mapView.onResume() }
78
+ override fun onPause() { super.onPause(); mapView.onPause() }
79
+ override fun onStop() { super.onStop(); mapView.onStop() }
80
+ override fun onLowMemory() { super.onLowMemory(); mapView.onLowMemory() }
81
+ override fun onDestroy() { super.onDestroy(); mapView.onDestroy() }
82
+ }
83
+ ```
84
+
85
+ `MapView` 的生命周期回调必须逐一转发,漏掉 `onDestroy()` 会泄漏原生渲染线程与显存。
86
+
87
+ ### iOS / macOS
88
+
89
+ CocoaPods 或 Swift Package Index 均可接入,模块名为 `MapLibre`。
90
+
91
+ ```ruby
92
+ # Podfile
93
+ pod 'MapLibre', '7.0.0'
94
+ ```
95
+
96
+ ```swift
97
+ import MapLibre
98
+
99
+ class SimpleMap: UIViewController, MLNMapViewDelegate {
100
+ var mapView: MLNMapView!
101
+
102
+ override func viewDidLoad() {
103
+ super.viewDidLoad()
104
+ mapView = MLNMapView(frame: view.bounds)
105
+ mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
106
+ mapView.delegate = self
107
+ view.addSubview(mapView)
108
+ }
109
+
110
+ func mapView(_ mapView: MLNMapView, didFinishLoading style: MLNStyle) {
111
+ // 样式就绪后再加 source / layer
112
+ }
113
+ }
114
+ ```
115
+
116
+ iOS 7.0.0 是破坏性版本:最低 iOS 提高到 15.5,伞头文件由 `Mapbox.h` 改为 `MapLibre.h`,`MapLibre.xcframework` 不再附带 `Mapbox.h`。Objective-C 代码需把 `#import <Mapbox/Mapbox.h>` 改为 `#import <MapLibre/MapLibre.h>`。
117
+
118
+ ### Node.js
119
+
120
+ 预编译二进制在安装时下载,支持 Ubuntu 24.04、macOS、Windows(amd64/arm64)与 Node.js 22/24/26。
121
+
122
+ ```bash
123
+ npm install @maplibre/maplibre-gl-native
124
+ npm ls @maplibre/maplibre-gl-native # 验证:6.4.1
125
+ ```
126
+
127
+ ```javascript
128
+ const mbgl = require('@maplibre/maplibre-gl-native');
129
+ const sharp = require('sharp');
130
+
131
+ const map = new mbgl.Map({ request: (req, callback) => { /* 自定义瓦片/样式加载 */ } });
132
+ map.load(require('./style.json'));
133
+
134
+ map.render({ width: 512, height: 512, zoom: 2, center: [0, 0] }, (err, buffer) => {
135
+ if (err) throw err;
136
+ map.release();
137
+ sharp(buffer, { raw: { width: 512, height: 512, channels: 4 } }).toFile('tile.png');
138
+ });
139
+ ```
140
+
141
+ Node 端适合服务端静态出图、瓦片预生成与 CI 中的样式回归,不提供交互。
142
+
143
+ ### C++ 核心(Linux/Windows)
144
+
145
+ 贡献级构建需要带子模块克隆,Linux 以 Ubuntu 22.04+ 为目标:
146
+
147
+ ```bash
148
+ git clone --recurse-submodules -j8 https://github.com/maplibre/maplibre-native.git
149
+ cd maplibre-native
150
+ ```
151
+
152
+ Android 侧可直接用 Android Studio 打开 `platform/android`,或在仓库根用 Nix:`nix develop .#android`。iOS 用 Bazel(`brew install bazelisk`)生成 Xcode 工程:
153
+
154
+ ```bash
155
+ bazel run //platform/ios:xcodeproj --@rules_xcodeproj//xcodeproj:extra_common_flags="--//:renderer=metal"
156
+ xed platform/ios/MapLibre.xcodeproj
157
+ ```
158
+
159
+ 完整依赖与构建选项见 [开发者文档](https://maplibre.org/maplibre-native/docs/book/)。
160
+
161
+ ### 验证
162
+
163
+ ```bash
164
+ # Android:确认依赖树里的 SDK 版本
165
+ ./gradlew :app:dependencies --configuration debugRuntimeClasspath | grep maplibre
166
+ # Node:确认二进制与版本
167
+ node -e "const m=require('@maplibre/maplibre-gl-native'); console.log(typeof m.Map)"
168
+ ```
169
+
170
+ 地图能显示 demotiles 世界地图且可拖拽缩放,即接入成功。
171
+
172
+ ---
173
+
174
+ ## 核心 API
175
+
176
+ ### 平台 API 对照
177
+
178
+ | 能力 | Android | iOS / macOS | Node.js |
179
+ |------|---------|-------------|---------|
180
+ | 地图视图 | `MapView` + `getMapAsync` | `MLNMapView` | `mbgl.Map` |
181
+ | 初始化 | `MapLibre.getInstance(context)` | 直接创建视图 | `new mbgl.Map(options)` |
182
+ | 样式 | `map.setStyle(json or url)` | `styleURL` / `MLNStyle` | `map.load(style)` |
183
+ | 相机 | `map.cameraPosition = ...` | `setCenterCoordinate` 等 | `render({center, zoom, bearing, pitch})` |
184
+ | 数据源 | `GeoJsonSource` / `VectorSource` | `MLNShapeSource` / `MLNVectorTileSource` | 通过 `request` 回调供给 |
185
+ | 出图 | `MapSnapshotter` | `MLNMapSnapshotter` | `map.render(callback)` |
186
+ | 生命周期 | `onStart/onResume/onPause/onStop/onDestroy` | UIViewController 生命周期 | `map.release()` |
187
+
188
+ ### 样式与图层
189
+
190
+ 原生端与 maplibre-gl-js 共用 Style Spec,样式 JSON 可以直接复用。运行时改样式的三种方式:
191
+
192
+ ```kotlin
193
+ // Android:整体换样式(会重建图层)
194
+ map.setStyle("https://demotiles.maplibre.org/style.json")
195
+
196
+ // 用 builder 构造样式,便于插入自定义字体与图层
197
+ val style = Style.Builder()
198
+ .fromUri("https://demotiles.maplibre.org/style.json")
199
+ .withSource(GeoJsonSource("pois", GeoJsonSourceOptions().data(geojson)))
200
+ .withLayer(CircleLayer("pois-layer", "pois"))
201
+ map.setStyle(style)
202
+ ```
203
+
204
+ ```swift
205
+ // iOS:通过 MLNStyle 追加 source 与 layer
206
+ let source = MLNShapeSource(identifier: "pois", shape: shape, options: nil)
207
+ style.addSource(source)
208
+ let layer = MLNCircleStyleLayer(identifier: "pois-layer", source: source)
209
+ layer.circleRadius = NSExpression(forConstantValue: 6)
210
+ style.addLayer(layer)
211
+ ```
212
+
213
+ ### 相机与交互
214
+
215
+ ```kotlin
216
+ import org.maplibre.android.camera.CameraUpdateFactory
217
+
218
+ map.animateCamera(CameraUpdateFactory.newLatLngZoom(LatLng(39.91, 116.39), 10.0), 1000)
219
+ map.cameraPosition = CameraPosition.Builder()
220
+ .target(LatLng(39.91, 116.39))
221
+ .zoom(12.0).tilt(45.0).bearing(30.0)
222
+ .build()
223
+ ```
224
+
225
+ ```swift
226
+ mapView.setCenter(CLLocationCoordinate2D(latitude: 39.91, longitude: 116.39), zoomLevel: 10, animated: true)
227
+ mapView.setDirection(30, animated: false)
228
+ ```
229
+
230
+ 手势(平移、缩放、旋转、倾斜)默认开启;`MapView` 的点击/长按回调在 Android 侧通过 `map.addOnMapClickListener` 等注册,iOS 侧走 `MLNMapViewDelegate`。
231
+
232
+ ### 离线地图与缓存
233
+
234
+ Android 的 `OfflineManager` / `OfflineRegion` 可把指定 bbox 与缩放范围的瓦片预下载到本地数据库,之后无网仍可渲染。要点:
235
+
236
+ 1. 定义 `OfflineTilePyramidRegionDefinition`(样式 URL + bbox + min/max zoom + 像素比)
237
+ 2. `OfflineManager.createOfflineRegion` 提交下载任务,监听进度回调
238
+ 3. 下载受瓦片服务端的 `Cache-Control` 与服务条款约束,公共底图不保证允许批量离线
239
+ 4. 清理用 `deleteOfflineRegion`,避免移动端存储长期膨胀
240
+
241
+ ### 自定义图层与扩展
242
+
243
+ C++ 内核支持自定义图层钩子,但各平台暴露程度不同。实际项目更常见的是:
244
+
245
+ - 用 Style Spec 的 `symbol` / `fill-extrusion` 等原生图层满足需求,避免自写渲染代码
246
+ - 标注与交互覆盖物用平台原生控件叠加(Android `SymbolManager`、iOS annotation)
247
+ - 需要真正自定义 GPU 绘制时,走 C++ 层并在目标平台重新绑定,成本高,先确认没有样式层解法
248
+
249
+ ---
250
+
251
+ ## 典型工作流
252
+
253
+ ### 链路一:Android 离线底图 + 业务点位
254
+
255
+ 输入:底图样式 URL、业务点位 GeoJSON、目标区域 bbox;输出:可离线使用的点位地图。
256
+
257
+ 1. `MapLibre.getInstance(context)` 初始化(单例,早于任何 MapView)
258
+ 2. 建立 `MapView` 并转发全部生命周期回调
259
+ 3. `getMapAsync` 中 `setStyle`,再加 `GeoJsonSource` 与 `CircleLayer`
260
+ 4. 用 `OfflineManager` 按 bbox + zoom 范围创建离线区域,展示下载进度
261
+ 5. 断网重启应用验证:底图与点位仍可见
262
+ 6. 校验:`adb logcat` 无渲染线程崩溃、`MapView.onDestroy()` 已调用
263
+
264
+ ```kotlin
265
+ mapView.getMapAsync { map ->
266
+ map.setStyle("https://demotiles.maplibre.org/style.json")
267
+ map.addOnStyleLoadedListener {
268
+ val source = GeoJsonSource("pois", GeoJsonSourceOptions().data(poiGeoJson))
269
+ map.addSource(source)
270
+ map.addLayer(CircleLayer("pois-layer", "pois").withProperties(
271
+ PropertyFactory.circleRadius(6f),
272
+ PropertyFactory.circleColor("#d7301f")
273
+ ))
274
+ }
275
+ }
276
+ ```
277
+
278
+ ### 链路二:iOS 样式热切换 + 标注
279
+
280
+ 输入:两套样式 JSON;输出:运行时可切换主题、标注不丢的地图。
281
+
282
+ 1. 首次进入用远程样式 URL 加载,`didFinishLoading style` 回调里补业务 source/layer
283
+ 2. 换主题时再次设置 `mapView.styleURL`,在回调里重新补业务图层(换样式会清空自定义图层)
284
+ 3. 标注用 `MLNPointAnnotation` 或 ShapeSource,注意换样式后的重建
285
+ 4. 校验:切换两次主题后业务图层不重复、不消失,无内存增长
286
+
287
+ ```swift
288
+ func mapView(_ mapView: MLNMapView, didFinishLoading style: MLNStyle) {
289
+ guard style.source(withIdentifier: "pois") == nil else { return } // 防重复添加
290
+ let source = MLNShapeSource(identifier: "pois", shape: poiShape, options: nil)
291
+ style.addSource(source)
292
+ let layer = MLNCircleStyleLayer(identifier: "pois-layer", source: source)
293
+ style.addLayer(layer)
294
+ }
295
+ ```
296
+
297
+ ### 链路三:Node 服务端瓦片出图
298
+
299
+ 输入:样式 JSON 与 z/x/y 瓦片坐标;输出:PNG 图片文件(CI 回归或离线切片)。
300
+
301
+ 1. `new mbgl.Map({ request })`,`request` 里返回本地或远程的样式/瓦片数据
302
+ 2. `map.load(style)` 载入样式
303
+ 3. `map.render({ width, height, zoom, center }, cb)` 拿 RGBA 缓冲
304
+ 4. 用 sharp 等库编码为 PNG 落盘,务必 `map.release()` 释放原生资源
305
+ 5. 校验:输出图片尺寸与坐标范围符合预期,多瓦片循环时无内存持续上涨
306
+
307
+ ```javascript
308
+ const mbgl = require('@maplibre/maplibre-gl-native');
309
+
310
+ function renderTile(z, x, y) {
311
+ const map = new mbgl.Map({ request: (req, cb) => cb(null, loadResource(req.url)) });
312
+ map.load(styleJson);
313
+ return new Promise((resolve, reject) => {
314
+ map.render({ width: 512, height: 512, zoom: z, center: tileCenter(x, y, z) }, (err, buf) => {
315
+ map.release();
316
+ err ? reject(err) : resolve(buf);
317
+ });
318
+ });
319
+ }
320
+ ```
321
+
322
+ ---
323
+
324
+ ## 性能与工程实践
325
+
326
+ 1. **生命周期别漏**:Android 少转发一个回调就可能让渲染线程常驻;`onDestroy` 必须调用
327
+ 2. **样式切换会重建图层**:`setStyle` 后自定义 source/layer 消失,需在回调里幂等重建(先查 `source(withIdentifier:)`)
328
+ 3. **缓存要设上限**:默认磁盘缓存随浏览增长,长时间运行的 kiosk/车载应用要显式管理离线区域与缓存大小
329
+ 4. **大 GeoJSON 预先切片**:客户端解析 GeoJSON 会把要素展开进内存,超过数万要素改用矢量瓦片源
330
+ 5. **出图复用 Map 实例**:Node 端每次渲染都新建 Map 会重复解析样式,批量出图时按样式复用并在结束时统一 `release()`
331
+ 6. **控制标注数量**:原生端标注布局在 CPU 侧,密集标注要依赖 `text-allow-overlap`/`symbol-sort-key` 收敛
332
+ 7. **按平台选版本线**:`13.x` 与 `*-globe` 实验线不要混用,升级前看 release notes 的破坏性变更段
333
+
334
+ ---
335
+
336
+ ## 常见问题
337
+
338
+ | 问题 | 原因 | 处置 |
339
+ |------|------|------|
340
+ | Android 地图为绿屏或纯色块 | `MapLibre.getInstance()` 未调用、或在 `MapView` 之后才调用,渲染初始化失败 | 在 `onCreate` 最前面调用 `MapLibre.getInstance(this)`,再 `setContentView` 与创建 MapView |
341
+ | Android 退出后崩溃 / 内存持续增长 | `MapView` 生命周期回调未全部转发,原生资源未释放 | 在 `onStart/onResume/onPause/onStop/onLowMemory/onDestroy` 中逐一调用同名 `mapView.*` 方法 |
342
+ | 编译报找不到 `org.maplibre.android.*` | 依赖坐标或版本写错,仍用旧的 Mapbox 包名 | 依赖应为 `org.maplibre.gl:android-sdk`,包名 `org.maplibre.android`;`./gradlew :app:dependencies` 核对实际版本 |
343
+ | 克隆后编译报缺少子模块头文件 | 仓库依赖 git submodules,普通 clone 没拉取 | `git clone --recurse-submodules`,或补 `git submodule update --init --recursive` |
344
+ | iOS 升级 7.0.0 后 `Mapbox.h` 找不到 | 伞头文件改名,xcframework 不再附带 `Mapbox.h` | Objective-C 改为 `#import <MapLibre/MapLibre.h>`;Swift 继续 `import MapLibre` |
345
+ | iOS 7.0.0 起要求更高系统版本 | 该版本把最低 iOS 提高到 15.5 | 提升部署目标,或暂时停留在 6.x 线 |
346
+ | 换样式后业务图层消失 | `setStyle` 会替换整份样式,自定义 source/layer 被清空 | 在 `didFinishLoading`(iOS)/`addOnStyleLoadedListener`(Android)里幂等重建 |
347
+ | Node 渲染报找不到模块或二进制 | 预编译二进制只覆盖特定平台与 Node 版本(22/24/26) | 确认操作系统与 Node 大版本在支持列表内;换 Node LTS 或自行编译 |
348
+ | 地图整块空白且无瓦片请求 | 样式 URL 不可达,或 `request` 回调没有正确返回数据 | 先确认样式 JSON 能下载,再检查自定义 `request` 是否对每种 `kind` 都 `callback` |
349
+ | 离线区域下载失败 | 底图服务端的 `Cache-Control` 或服务条款不允许批量抓取 | 改用允许离线的自建瓦片服务,并遵守其条款 |
350
+
351
+ ---
352
+
353
+ ## AI 使用建议
354
+
355
+ - **执行环境**:Android 构建用 `./gradlew`,iOS 用 Bazel 或 Xcode,Node 用 `npm`;这些都需要各自 SDK,AI 助手应先用 `java -version`、`xcodebuild -version`、`node -v` 探测环境,缺失时不要臆造构建成功。
356
+ - **先探测版本**:Android 查依赖树(`./gradlew :app:dependencies`)或 Maven 元数据;iOS 查 `Podfile.lock`;Node 用 `npm ls @maplibre/maplibre-gl-native`。本技能按 Android 13.x、iOS 7.0.0、Node 6.4.1 编写。
357
+ - **验证产物**:Android 用模拟器/真机看画面并 `adb logcat` 查渲染报错;iOS 用 Simulator;Node 直接检查输出 PNG 的尺寸与内容;构建通过不等于渲染正确。
358
+ - **无设备环境**:CI/无头机器无法验证 GPU 渲染,不要报告"地图已显示";只能验证编译与产物生成。
359
+ - **坐标顺序**:经纬度按平台类型使用(`LatLng(lat, lng)` 在 Android 是纬度在前,`CLLocationCoordinate2D(latitude:longitude:)` 亦然),与 JS 的 `[lng, lat]` 相反,跨端复用时最容易出错。
360
+ - **版本线选择**:`13.x` 为常规线,`*-globe` 是实验线(球体投影);回答先给出目标平台与所需版本线,再给依赖坐标。
361
+ - **安全与权限**:安装 SDK/NDK、跑模拟器、下载依赖前先征得用户同意;离线批量抓取瓦片需确认底图服务条款允许。
362
+
363
+ ## 相关技能
364
+
365
+ - **maplibre-gl-js** — 同体系的浏览器端实现,样式 JSON 可共用:[../maplibre-gl-js/SKILL.md](../maplibre-gl-js/SKILL.md)
366
+ - **mapbox-gl-js** — 上游血统的商业版本,概念对应关系可参考:[../mapbox-gl-js/SKILL.md](../mapbox-gl-js/SKILL.md)
367
+ - **cesiumjs** — 三维地球与 3D Tiles,三维场景的另一条路线:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
368
+ - **gdal** — 瓦片与栅格数据的前置处理(切片、重投影、COG):[../gdal/SKILL.md](../gdal/SKILL.md)
369
+ - **pdal** — 点云数据处理,与地形/高程数据配合:[../pdal/SKILL.md](../pdal/SKILL.md)
370
+ - **postgis** — 矢量瓦片的数据源与空间查询后端:[../postgis/SKILL.md](../postgis/SKILL.md)
371
+
372
+ ## 参考资源
373
+
374
+ - 源码仓库:<https://github.com/maplibre/maplibre-native>
375
+ - 开发者文档:<https://maplibre.org/maplibre-native/docs/book/>
376
+ - Android API:<https://maplibre.org/maplibre-native/android/api/>
377
+ - Android 入门示例:<https://maplibre.org/maplibre-native/android/examples/getting-started/>
378
+ - iOS 文档:<https://maplibre.org/maplibre-native/ios/latest/documentation/maplibre/>
379
+ - C++ API(不稳定):<https://maplibre.org/maplibre-native/cpp/api/>
380
+ - Maven 版本列表:<https://central.sonatype.com/artifact/org.maplibre.gl/android-sdk/versions>
381
+ - CocoaPods:<https://cocoapods.org/pods/MapLibre>
382
+ - 发布记录:<https://github.com/maplibre/maplibre-native/releases>
383
+ - 中文教程:<https://znlgis.github.io/gis/tutorial/maplibre-native/>
@@ -42,7 +42,9 @@ sudo a2enmod authnz_fcgi cgi
42
42
  sudo systemctl restart apache2
43
43
  ```
44
44
 
45
- `cgi-mapserver` 提供 CGI 可执行程序,`mapserver-bin` 提供 `mapserv`、`map2img`、`shp2img`、`legend` 等命令行工具。
45
+ `cgi-mapserver` 提供 CGI 可执行程序,`mapserver-bin` 提供 `mapserv`、`map2img`、`legend`、`shptree` 等命令行工具。
46
+
47
+ > **注意:** 旧版教程常用的 `shp2img` 在 MapServer 8.0 起已更名为 `map2img`,8.x 上直接调 `shp2img` 会报命令不存在;详见 [MIGRATION_GUIDE](https://mapserver.org/MIGRATION_GUIDE.html)。
46
48
 
47
49
  ### 方式二:源码编译(CMake)
48
50
 
@@ -216,7 +218,7 @@ ogr2ogr -f GPKG clip.gpkg countries.gpkg -clipsrc 100 20 130 50
216
218
 
217
219
  1. 确认图层 `NAME` 以字母开头且 `TYPE` 为矢量类型。
218
220
  2. 在 `WEB/METADATA` 写入 `wfs_title`、`wfs_onlineresource`、`wfs_enable_request`、`wfs_srs`。
219
- 3. 图层级补充 `wfs_title`、`wfs_srs`、`gml_featureid`;如需输出属性,设置 `gml_include_items`(8.x 默认不暴露任何属性)。
221
+ 3. 图层级补充 `wfs_title`、`wfs_srs`、`gml_featureid`;如需输出属性,设置 `gml_include_items`(默认不暴露任何属性)。
220
222
  4. 用 `GetFeature` 请求并指定 `OUTPUTFORMAT`(如 `application/json`)取回要素。
221
223
  5. 用 `GetCapabilities` 核对服务声明的图层与格式是否与预期一致。
222
224
 
@@ -235,7 +237,7 @@ ogr2ogr -f GPKG clip.gpkg countries.gpkg -clipsrc 100 20 130 50
235
237
  - **用 FastCGI 而非纯 CGI**:FastCGI 常驻进程避免每次请求重复初始化,显著降低延迟。
236
238
  - **锁定 mapfile 路径**:设置 `MS_MAP_PATTERN`、`MS_MAP_NO_PATH` 或包装脚本,避免任意 `map=` 路径被利用。
237
239
  - **显式声明 `wms_enable_request` / `wfs_enable_request`**:不设置时不会启用任何请求,用 `!` 前缀可禁用单个请求。
238
- - **显式设置 `gml_include_items`**:MapServer 8.x 默认不输出要素属性,需按需开放字段。
240
+ - **显式设置 `gml_include_items`**:默认不输出要素属性(自 MapServer 4.6 起),需按需开放字段。
239
241
  - **PostGIS 图层建空间索引**,并在 mapfile 中正确设置 `PROJECTION` 与 `EXTENT`。
240
242
  - **图像格式按需选择**:`image/png` 适合线面,`image/jpeg` 适合影像,`image/png; mode=8bit` 可减小体积。
241
243
  - **配合 MapCache** 缓存瓦片,或在前端做预切片以承接高并发。
@@ -253,7 +255,7 @@ ogr2ogr -f GPKG clip.gpkg countries.gpkg -clipsrc 100 20 130 50
253
255
  | GetMap 返回空白图像 | 检查 `EXTENT` 与请求 `BBOX` 是否匹配、`PROJECTION` 是否与数据一致、图层 `STATUS` 是否为 `ON` |
254
256
  | WMS 提示未启用请求 | `wms_enable_request` 未设置或未包含该请求类型;设为 `*` 或列出具体请求 |
255
257
  | GetFeatureInfo 无返回 | 图层缺少 `TEMPLATE`(如 `empty`)或 `wms_include_items` 未配置 |
256
- | WFS 返回结果不含属性字段 | 8.x 默认不暴露属性,设置 `gml_include_items "all"` 或列出字段名 |
258
+ | WFS 返回结果不含属性字段 | 默认不暴露属性(MapServer 4.6 起的默认行为),设置 `gml_include_items "all"` 或列出字段名 |
257
259
  | 中文注记显示为方框 | mapfile 需 UTF-8 编码,且 `FONT` 指向包含中文字形的字体集 |
258
260
  | 图层名不符合 WFS 发布要求 | `NAME` 必须以字母开头,且 `TYPE` 为 POINT/LINE/POLYGON |
259
261
  | SLD 未生效 | `NamedLayer/Name` 与图层 `NAME` 不匹配,或 `CLASSITEM` 字段名错误 |
@@ -265,7 +267,7 @@ ogr2ogr -f GPKG clip.gpkg countries.gpkg -clipsrc 100 20 130 50
265
267
  - **执行环境**:命令在终端 / shell 中执行(Windows 用 OSGeo4W 的 `mapserv.exe`);`sudo apt`、`tar -zxvf` 不跨平台,Windows 改 `Expand-Archive`,装包或改系统目录前先问用户。
266
268
  - **先探测版本**:`mapserv -v`,确认输出含 `MapServer version 8.6.6` 且 `SUPPORTS=` 里有需要的 `WMS_SERVER`/`WFS_SERVER`;缺项说明该构建没编进对应库,改 mapfile 无用。
267
269
  - **验证产物**:先离线 `map2img -m demo.map -o out.png -s 600 400` 看渲染,再 `mapserv -nh "QUERY_STRING=map=/abs/demo.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities"` 抓能力文档,最后才 `curl -sI "http://host/cgi-bin/mapserv?map=...&REQUEST=GetMap..."` 确认 200 与 `Content-Type: image/png`。
268
- - **排障分流**:空白图查 `EXTENT`/`BBOX`/`PROJECTION`/`STATUS ON`;能力文档缺图层查 `wms_enable_request`、`wfs_enable_request` 与 `NAME` 是否字母开头;WFS 无属性字段是 8.x 默认行为,补 `gml_include_items`。
270
+ - **排障分流**:空白图查 `EXTENT`/`BBOX`/`PROJECTION`/`STATUS ON`;能力文档缺图层查 `wms_enable_request`、`wfs_enable_request` 与 `NAME` 是否字母开头;WFS 无属性字段是默认行为(4.6 起),补 `gml_include_items`。
269
271
  - **安全与权限**:`map=` 可读任意路径是 MapServer 最典型误配置,生产必须设 `MS_MAP_PATTERN`/`MS_MAP_NO_PATH`;重启 Apache/nginx 或改 CGI 权限前先向用户确认。
270
272
  - **改一处验一处**:改 `WEB.METADATA` 后只重跑 `GetCapabilities`,改 `LAYER` 样式后只重跑 `map2img`,缩小排查范围。
271
273
 
@@ -266,8 +266,10 @@ using Mapsui.Providers.Wms;
266
266
  var shpProvider = new ShapeFile("data/china.shp", true);
267
267
  map.Layers.Add(new Layer("China") { DataSource = shpProvider });
268
268
 
269
- // 2. WMS 栅格层:构造参数依次为服务地址,图层名数组
270
- var wmsProvider = new WmsProvider("https://geo.example.com/wms?", new[] { "rivers" });
269
+ // 2. WMS 栅格层:5.x 起同步构造已移除,必须用异步工厂 CreateAsync(会先拉 GetCapabilities)
270
+ var wmsProvider = await WmsProvider.CreateAsync("https://geo.example.com/wms?", userAgent: "MyApp");
271
+ wmsProvider.CRS = "EPSG:3857"; // 需与 Map.CRS 一致,否则地图空白而非报错
272
+ wmsProvider.AddLayer("rivers"); // 图层名必须与能力文档完全一致
271
273
  map.Layers.Add(new ImageLayer("Rivers") { DataSource = wmsProvider });
272
274
 
273
275
  map.ZoomToExtents();