@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,420 @@
1
+ ---
2
+ name: stac-cog-titiler
3
+ description: "Use when building cloud-native imagery pipelines with STAC 1.1.0, Cloud Optimized GeoTIFF and TiTiler 2.4.0 — rio cogeo create/validate, pystac-client search, stac-fastapi 7.1.1 with stac-fastapi-pgstac 7.2.1, uvicorn stac_fastapi.pgstac.app:app, titiler.application /cog and /stac tilejson endpoints, MosaicJSON mosaics, or debugging HTTP 416 range errors, blank tiles from band index mismatch and 403 on private object storage."
4
+ license: MIT
5
+ metadata:
6
+ category: gis
7
+ tags: "stac, cog, titiler, raster, cloud-native, geotiff, fastapi, object-storage, mosaicjson, imagery"
8
+ ---
9
+
10
+ > **项目地址:**
11
+ >
12
+ > - STAC 规范:<https://github.com/radiantearth/stac-spec>(STAC API 规范:<https://github.com/radiantearth/stac-api-spec>)
13
+ > - stac-fastapi:<https://github.com/stac-utils/stac-fastapi>(PostgreSQL 后端 <https://github.com/stac-utils/stac-fastapi-pgstac>)
14
+ > - pgstac:<https://github.com/stac-utils/pgstac>
15
+ > - COG 规范:<https://github.com/cogeotiff/cog-spec>;rio-cogeo:<https://github.com/cogeotiff/rio-cogeo>
16
+ > - TiTiler:<https://github.com/developmentseed/titiler>
17
+ >
18
+ > **官方文档:** <https://stacspec.org/> / <https://stac-utils.github.io/stac-fastapi/> / <https://cogeotiff.github.io/rio-cogeo/> / <https://developmentseed.org/titiler/>
19
+ >
20
+ > **最新版本:** STAC 1.1.0(2024-09)、STAC API 1.0.0;stac-fastapi 7.1.1、stac-fastapi-pgstac 7.2.1、pgstac v0.10.1;rio-cogeo 7.0.4、cogeo-mosaic 9.2.0;titiler.core / titiler.application 2.4.0、titiler-pgstac 3.2.0;pystac 1.16.0、pystac-client 0.9.1(截至 2026-11,逐个实测 PyPI 与 [GitHub Releases](https://github.com/stac-utils/stac-fastapi/releases)、[TiTiler Releases](https://github.com/developmentseed/titiler/releases))
21
+ >
22
+ > **许可证:** STAC 规范 Apache-2.0;stac-fastapi / pgstac / TiTiler / rio-cogeo / pystac 均 MIT
23
+
24
+ ## 概述
25
+
26
+ 这条链路解决的是「影像不下载、按需出图」:原始影像转成 **COG**(云优化 GeoTIFF,带内部分块与金字塔,支持 HTTP Range 随机读)放到对象存储,用 **STAC** 元数据把资产编目成可检索的条目,再交给 **TiTiler** 按瓦片请求动态读窗口、重采样、配色并输出 PNG/JPEG。三者各自独立,组合起来才能做到入库即服务。
27
+
28
+ - **STAC**:Item/Collection/Catalog 三层 JSON 元数据模型,统一描述时空范围与资产链接,跨厂商可交换
29
+ - **COG**:内部按 512×512 分块、带 overview 金字塔、头部元数据在前,服务端只需几次 Range 请求就能取到任意窗口
30
+ - **stac-fastapi + pgstac**:STAC API 的 Python 实现,pgstac 把 JSONB 条目与空间索引放进 PostGIS,支持 CQL2 过滤与分页
31
+ - **TiTiler**:基于 FastAPI + rio-tiler 的动态切片服务,`/cog` 直接对单个 COG 出图,`/stac` 对 STAC Item 的资产出图,`/mosaicjson` 把多景拼成虚拟镶嵌
32
+ - **零预处理出图**:换波段组合、拉伸方式、色带、重采样都通过 URL 查询参数完成,不用重跑切片任务
33
+ - **标准接口**:OGC Tiles / WMTS 兼容端点,可直接作为 OpenLayers、MapLibre、Leaflet 的瓦片源
34
+
35
+ 与相邻技术的差异:传统方案是 GeoServer + ImageMosaic 预先切片,改样式要重切片;本方案把「切片」推迟到请求时,样式灵活但依赖对象存储的 Range 性能与 CDN。
36
+
37
+ ---
38
+
39
+ ## 环境准备
40
+
41
+ ### Python 依赖
42
+
43
+ 本链路是纯 Python 生态,要求 **Python >= 3.11**(stac-fastapi、rio-cogeo、TiTiler 2.x 均要求 3.11+)。
44
+
45
+ ```bash
46
+ python -m venv .venv
47
+ # Linux/macOS
48
+ source .venv/bin/activate
49
+ # Windows PowerShell
50
+ # .venv\Scripts\Activate.ps1
51
+
52
+ python -m pip install -U pip
53
+ python -m pip install "rio-cogeo==7.0.4" "pystac==1.16.0" "pystac-client==0.9.1"
54
+ python -m pip install "stac-fastapi.api==7.1.1" "stac-fastapi.types==7.1.1" \
55
+ "stac-fastapi.extensions==7.1.1" "stac-fastapi-pgstac==7.2.1" \
56
+ "titiler.application==2.4.0" uvicorn
57
+ ```
58
+
59
+ > **注意:** 不要 `pip install titiler`。TiTiler 在 2025 年末已停止维护该元包(PyPI 上停留在 0.25.0),必须按命名空间安装 `titiler.core`、`titiler.application` 等子包([官方说明](https://github.com/developmentseed/titiler/pull/1244))。
60
+
61
+ ### COG 生成需要 GDAL
62
+
63
+ `rio-cogeo` 依赖 rasterio 与系统 GDAL 库:
64
+
65
+ ```bash
66
+ # Ubuntu / Debian
67
+ sudo apt-get install -y gdal-bin libgdal-dev
68
+
69
+ # macOS
70
+ brew install gdal
71
+
72
+ # Conda(推荐,自动解决 C 库版本)
73
+ conda install -c conda-forge gdal rio-cogeo
74
+ ```
75
+
76
+ ### 服务端组件
77
+
78
+ ```bash
79
+ # 只用 TiTiler 的官方镜像(COG/STAC/MosaicJSON 端点齐全)
80
+ docker run --rm -p 8000:8000 ghcr.io/developmentseed/titiler:latest \
81
+ uvicorn titiler.application.main:app --host 0.0.0.0 --port 8000
82
+
83
+ # STAC API 需要 PostgreSQL + PostGIS + pgstac
84
+ docker run --rm -p 5439:5432 -e POSTGRES_USER=username \
85
+ -e POSTGRES_PASSWORD=password -e POSTGRES_DB=postgis postgis/postgis:16-3.4
86
+ ```
87
+
88
+ ### 验证
89
+
90
+ ```bash
91
+ rio cogeo --version # 应显示 7.0.4
92
+ python -c "import stac_fastapi.api, titiler.core; print('ok')"
93
+ curl -s http://localhost:8000/ | head -c 200 # TiTiler 落地页 JSON
94
+ curl -s http://localhost:8000/api.html -o /dev/null -w '%{http_code}\n' # OpenAPI 文档
95
+ ```
96
+
97
+ ---
98
+
99
+ ## 核心概念与命令
100
+
101
+ ### COG:为什么它能按需出图
102
+
103
+ 普通 GeoTIFF 的行按整幅宽存储,读一个小窗口也要下载大段数据。COG 做了三件事:
104
+
105
+ | 特性 | 作用 |
106
+ |------|------|
107
+ | 内部 tile(默认 512×512) | 任意窗口只需读少数几个 tile |
108
+ | 内部 overview 金字塔 | 缩小时直接读低分辨率层,不用全量重采样 |
109
+ | 头部元数据前置 | 客户端读前几百字节即可知道尺寸、分块、概览信息 |
110
+
111
+ 因此服务端只需 `Range: bytes=...` 请求几次,就能取出渲染一片瓦片所需的数据——这是 TiTiler 能做到「不落盘、不预切」的前提。
112
+
113
+ ### rio-cogeo:生成与校验
114
+
115
+ ```bash
116
+ # 生成 COG(deflate 压缩,默认 512 分块,自动建 overview)
117
+ rio cogeo create input.tif output_cog.tif
118
+
119
+ # 常用选项
120
+ rio cogeo create input.tif output_cog.tif \
121
+ --cog-profile deflate \ # deflate | zstd | lzw | jpeg | webp
122
+ --overview-resampling bilinear \ # 建 overview 用的重采样算法(默认 nearest)
123
+ --overview-level 6 \ # 从第 6 级开始建 overview;省略则自动选到最小 overview 小于 blocksize
124
+ --blocksize 512 \ # 覆盖 profile 的内部 tile 尺寸
125
+ --nodata 0 # 显式声明 nodata
126
+
127
+ # 校验是否符合 COG 规范
128
+ rio cogeo validate output_cog.tif
129
+
130
+ # 查看栅格与 COG 结构信息
131
+ rio cogeo info output_cog.tif
132
+ ```
133
+
134
+ `validate` 通过是上云前的硬门槛;报错会指出缺失 overview、分块顺序不合法或未按 tile 组织。注意 `--overview-level` 是**从第几级开始建 overview**,不是"建几级金字塔";省略时 rio-cogeo 自动建到最小 overview 小于内部 blocksize 为止。
135
+
136
+ ### STAC:元数据模型
137
+
138
+ 三层模型,逐层收窄:
139
+
140
+ ```text
141
+ Catalog(目录,可嵌套)
142
+ └── Collection(数据集,定义时空范围与许可)
143
+ └── Item(单景,一个 datetime + 几何 + assets)
144
+ ```
145
+
146
+ Item 的关键字段是 `id`、`bbox`、`geometry`、`properties.datetime`,以及 `assets`——资产用 `href` 指向对象存储里的 COG:
147
+
148
+ ```json
149
+ {
150
+ "type": "Feature",
151
+ "stac_version": "1.1.0",
152
+ "id": "S2B_32TMT_20260101",
153
+ "bbox": [116.1, 39.7, 116.6, 40.1],
154
+ "geometry": { "type": "Polygon", "coordinates": [[]] },
155
+ "properties": { "datetime": "2026-01-01T03:20:00Z", "eo:cloud_cover": 3.2 },
156
+ "assets": {
157
+ "visual": {
158
+ "href": "s3://bucket/cogs/S2B_32TMT_20260101.tif",
159
+ "type": "image/tiff; application=geotiff; profile=cloud-optimized",
160
+ "roles": ["data"]
161
+ }
162
+ },
163
+ "links": []
164
+ }
165
+ ```
166
+
167
+ 用 pystac 构造与校验,避免手写 JSON 出错:
168
+
169
+ ```python
170
+ import pystac
171
+
172
+ item = pystac.Item(
173
+ id="S2B_32TMT_20260101",
174
+ geometry=footprint,
175
+ bbox=bbox,
176
+ datetime=dt,
177
+ properties={"eo:cloud_cover": 3.2},
178
+ )
179
+ item.add_asset("visual", pystac.Asset(
180
+ href="s3://bucket/cogs/S2B_32TMT_20260101.tif",
181
+ media_type=pystac.MediaType.COG,
182
+ roles=["data"],
183
+ ))
184
+ item.set_self_href("./S2B_32TMT_20260101/S2B_32TMT_20260101.json")
185
+ item.save_object()
186
+ ```
187
+
188
+ ### STAC API:stac-fastapi + pgstac
189
+
190
+ ```bash
191
+ # 配置连接(.env 或环境变量)
192
+ export PGUSER=username PGPASSWORD=password PGDATABASE=postgis PGHOST=localhost PGPORT=5439
193
+ export STAC_FASTAPI_TITLE="My STAC API"
194
+ export STAC_FASTAPI_DESCRIPTION="Imagery catalog"
195
+
196
+ # 启动
197
+ uvicorn stac_fastapi.pgstac.app:app --host 0.0.0.0 --port 8080
198
+ ```
199
+
200
+ 数据库需先安装 pgstac 结构(`pgstac-migrate migrate`,需超级用户权限),并授权:
201
+
202
+ ```bash
203
+ psql -d postgres://username@localhost:5439/postgis -c "GRANT pgstac_admin TO username"
204
+ ```
205
+
206
+ 检索走标准 STAC API:
207
+
208
+ ```bash
209
+ # 集合与条目
210
+ curl -s 'http://localhost:8080/collections' | head -c 300
211
+ curl -s 'http://localhost:8080/collections/sentinel-2/items?limit=5'
212
+
213
+ # bbox + 时间 + 字段过滤(CQL2 需对应扩展)
214
+ curl -s 'http://localhost:8080/search?bbox=116,39,117,41&datetime=2026-01-01/2026-12-31&limit=10'
215
+ ```
216
+
217
+ Python 客户端(推荐,处理分页与重试):
218
+
219
+ ```python
220
+ from pystac_client import Client
221
+
222
+ catalog = Client.open("http://localhost:8080")
223
+ search = catalog.search(
224
+ collections=["sentinel-2"],
225
+ bbox=[116, 39, 117, 41],
226
+ datetime="2026-01-01/2026-12-31",
227
+ max_items=20,
228
+ )
229
+ items = list(search.items())
230
+ ```
231
+
232
+ ### TiTiler:动态切片
233
+
234
+ `/cog` 端点直接对一个 COG 出图,`url` 为查询参数(需 URL 编码):
235
+
236
+ ```bash
237
+ COG='https%3A%2F%2Fexample.com%2Fcog%2Fdem.tif'
238
+
239
+ # TileJSON(前端地图直接用的配置)
240
+ curl "http://localhost:8000/cog/WebMercatorQuad/tilejson.json?url=${COG}"
241
+
242
+ # 单张瓦片
243
+ curl "http://localhost:8000/cog/tiles/WebMercatorQuad/8/210/98.png?url=${COG}" -o tile.png
244
+
245
+ # 基础信息与统计
246
+ curl "http://localhost:8000/cog/info?url=${COG}"
247
+ curl "http://localhost:8000/cog/statistics?url=${COG}"
248
+
249
+ # 预览图(不切瓦片)
250
+ curl "http://localhost:8000/cog/preview.png?url=${COG}&max_size=512" -o preview.png
251
+ ```
252
+
253
+ `/stac` 端点直接对 **STAC Item JSON 的 URL** 出图,`url` 指向 Item 本身的 JSON 地址,`assets` 指定要读的资产名(必填):
254
+
255
+ ```bash
256
+ ITEM='https%3A%2F%2Fexample.com%2Fstac%2FS2B_32TMT_20260101.json'
257
+
258
+ curl "http://localhost:8000/stac/tiles/WebMercatorQuad/10/420/196.png?url=${ITEM}&assets=visual"
259
+ curl "http://localhost:8000/stac/WebMercatorQuad/tilejson.json?url=${ITEM}&assets=visual"
260
+ ```
261
+
262
+ 多资产组合(如多波段分别存放在不同资产)用重复的 `assets` 参数:`assets=red&assets=green&assets=blue`。
263
+
264
+ 常用渲染参数(对所有 `/tiles` 端点通用):
265
+
266
+ | 参数 | 作用 | 示例 |
267
+ |------|------|------|
268
+ | `bidx` | 波段组合 | `bidx=1&bidx=2&bidx=3` |
269
+ | `rescale` | 线性拉伸区间 | `rescale=0,4000` |
270
+ | `colormap_name` | 命名色带 | `colormap_name=terrain` |
271
+ | `resampling` | 重采样算法 | `resampling=bilinear` |
272
+ | `nodata` | 覆盖 nodata | `nodata=0` |
273
+ | `max_size` | 预览最大边长 | `max_size=512` |
274
+
275
+ ### MosaicJSON:多景虚拟镶嵌
276
+
277
+ 当范围跨多景时,用 MosaicJSON 把多个 COG 组织成一张虚拟镶嵌图,TiTiler 的 `/mosaicjson` 端点按瓦片动态挑选数据源:
278
+
279
+ ```bash
280
+ python -m pip install "cogeo-mosaic==9.2.0"
281
+
282
+ # 由 COG 列表生成 MosaicJSON
283
+ cogeo-mosaic create cogs.txt -o mosaic.json --minzoom 8 --maxzoom 14
284
+ ```
285
+
286
+ ```bash
287
+ curl "http://localhost:8000/mosaicjson/WebMercatorQuad/tilejson.json?url=https%3A%2F%2Fexample.com%2Fmosaic.json"
288
+ ```
289
+
290
+ ---
291
+
292
+ ## 典型工作流
293
+
294
+ ### 链路一:单景影像从 TIFF 到可浏览瓦片
295
+
296
+ 输入:`input.tif`(任意 GeoTIFF);输出:可通过 TileJSON 浏览的 COG 服务。
297
+
298
+ 1. **转 COG**:`rio cogeo create input.tif output_cog.tif --cog-profile deflate`
299
+ 2. **校验**:`rio cogeo validate output_cog.tif`,必须返回 valid
300
+ 3. **上传对象存储**:`aws s3 cp output_cog.tif s3://bucket/cogs/`(或 MinIO/OSS 等价命令)
301
+ 4. **确认 Range 可读**:`curl -s -r 0-1023 -o /dev/null -w '%{http_code}' https://.../output_cog.tif` 应返回 206
302
+ 5. **构造 STAC Item**:用 pystac 写入 `bbox`、`datetime`、`assets.visual.href`
303
+ 6. **取 TileJSON**:`/cog/WebMercatorQuad/tilejson.json?url=...`,把返回的 `tiles` 填进前端地图
304
+ 7. **校验产物**:瓦片图片非空白、`/cog/info` 的尺寸与波段与原图一致
305
+
306
+ ```bash
307
+ rio cogeo create input.tif output_cog.tif --cog-profile deflate --blocksize 512
308
+ rio cogeo validate output_cog.tif
309
+ curl -s -r 0-1023 -o /dev/null -w 'range status: %{http_code}\n' "https://cdn.example.com/output_cog.tif"
310
+ ```
311
+
312
+ ### 链路二:批量入库 STAC API 并按需检索
313
+
314
+ 输入:COG 列表 + 元数据表;输出:可按 bbox/时间检索的 STAC API。
315
+
316
+ 1. **批量转 COG**:脚本遍历原始影像,逐个 `rio cogeo create` 并 `validate`
317
+ 2. **生成 Item**:pystac 按集合模板逐景生成 Item JSON
318
+ 3. **入库**:写入 pgstac(`INSERT INTO pgstac.items(content)` 或 pgstac 提供的批量导入工具)
319
+ 4. **起服务**:`uvicorn stac_fastapi.pgstac.app:app`
320
+ 5. **检索验证**:`/search?bbox=...&datetime=...` 返回预期条目,`/collections` 能看到集合
321
+ 6. **接出图**:把检索到的 Item JSON 地址交给 TiTiler 的 `/stac/tiles?url=...&assets=...` 出图(TiTiler 直接读 Item JSON,不需要额外配置 STAC API 连接)
322
+
323
+ ```python
324
+ from pystac_client import Client
325
+ from rio_cogeo.cogeo import cog_validate
326
+
327
+ assert cog_validate("output_cog.tif")[0], "COG 校验未通过,先修正再入库"
328
+
329
+ catalog = Client.open("http://localhost:8080")
330
+ items = list(catalog.search(collections=["sentinel-2"], bbox=[116, 39, 117, 41]).items())
331
+ print(len(items), items[0].assets["visual"].href)
332
+ ```
333
+
334
+ ### 链路三:多景镶嵌 + 前端地图接入
335
+
336
+ 输入:跨多景的 COG 集合;输出:一张连续的镶嵌底图。
337
+
338
+ 1. **列 COG 清单**:`cogs.txt` 每行一个 COG URL
339
+ 2. **生成 MosaicJSON**:`cogeo-mosaic create cogs.txt -o mosaic.json --minzoom 8 --maxzoom 14`
340
+ 3. **上传 mosaic.json** 到对象存储
341
+ 4. **取 TileJSON**:`/mosaicjson/WebMercatorQuad/tilejson.json?url=...`
342
+ 5. **前端接入**:OpenLayers/MapLibre 用返回的 `tiles` 模板建瓦片图层
343
+ 6. **校验**:拼接处无明显接缝、边缘景号覆盖正确、缩到 minzoom 不出现空白
344
+
345
+ ```javascript
346
+ // 前端:把 TileJSON 的 tiles 直接给 MapLibre
347
+ const tilejson = await fetch(
348
+ 'http://localhost:8000/mosaicjson/WebMercatorQuad/tilejson.json?url=' + encodeURIComponent(mosaicUrl)
349
+ ).then(r => r.json());
350
+
351
+ map.addSource('mosaic', { type: 'raster', tiles: tilejson.tiles, tileSize: 256 });
352
+ map.addLayer({ id: 'mosaic', type: 'raster', source: 'mosaic' });
353
+ ```
354
+
355
+ ---
356
+
357
+ ## 性能与工程实践
358
+
359
+ 1. **COG 内部块别太小**:512×512 是通用最优;256 会增加请求次数,1024 会放大单次读取量
360
+ 2. **对象存储必须支持 Range**:S3/OSS/MinIO/GCS 都支持;某些 CDN 或代理会忽略 `Range` 返回 200 全量,导致出图极慢
361
+ 3. **CDN 缓存瓦片而非 COG**:瓦片 URL 带 `url` 参数,可对 `/cog/tiles/...` 做短期缓存;COG 本体交给对象存储直读
362
+ 4. **限定 `maxzoom`**:超过数据实际分辨率继续放大只是插值,浪费算力,用源的真实分辨率推导上限
363
+ 5. **服务端并发出图是 CPU 密集**:TiTiler 的瓶颈在重采样与编码,多 worker 部署(`--workers N`)比单进程调参有效
364
+ 6. **MosaicJSON 分层**:超大范围按 maxzoom 分块生成多个 mosaics,避免单个 mosaic.json 过大
365
+ 7. **私有数据用签名 URL**:不要在前端暴露永久凭据;TiTiler 支持通过环境变量注入 S3 凭据或前置签名
366
+ 8. **入库前必须 `cog_validate`**:不合规的 COG 会在检索正常的情况下出图失败,排查成本高
367
+
368
+ ---
369
+
370
+ ## 常见问题
371
+
372
+ | 问题 | 原因 | 处置 |
373
+ |------|------|------|
374
+ | 瓦片请求返回 416 Range Not Satisfiable | COG 未按 tile 组织,或文件被部分上传/截断 | `rio cogeo validate` 重新校验;确认上传对象大小与本地一致;必要时重转 COG |
375
+ | 出图全黑或全白 | `bidx` 波段顺序错误,或缺 `rescale` 拉伸 | 用 `/cog/info` 看波段数与 dtype;单波段加 `rescale=min,max`,多波段用 `bidx=1&bidx=2&bidx=3` |
376
+ | 403 Forbidden 或 Access Denied | 对象存储桶/对象私有,TiTiler 没拿到凭据 | 给服务进程配置 AWS 凭据或 IAM 角色;或改用预签名 URL 作为 `url` 参数 |
377
+ | `pip install titiler` 装出来的东西不对 | TiTiler 已弃用该元包,PyPI 上停在 0.25.0 | 改装 `titiler.application==2.4.0` 或按需装 `titiler.core` 等子包 |
378
+ | `/stac/tiles` 报 400 或读不到资产 | `url` 指向的 Item JSON 不可访问,或 `assets` 名称与 Item 里的 `assets` 键不一致 | `curl` 打开 Item JSON 核对 `assets` 的键名;`url` 必须指向 Item 文件而不是 Collection 或 API 检索页 |
379
+ | stac-fastapi 启动报缺少 pgstac 表 | 数据库未执行 pgstac 迁移,或用户无权限 | 用 `pgstac-migrate migrate` 建结构,并 `GRANT pgstac_admin` 给连接用户 |
380
+ | 瓦片拼接处有明显接缝 | 多景镶嵌的重采样/色彩不一致 | 统一 `rescale` 与 `colormap`,或先做色彩一致性处理再生成 MosaicJSON |
381
+ | 预览图比预期模糊 | 默认预览尺寸受限,或源没有 overview | 设 `max_size`;确认 COG 带 overview(`rio cogeo info` 的 overviews 字段) |
382
+ | 前端加载瓦片很慢但服务端正常 | CDN/代理忽略 Range,或未缓存瓦片 | 检查 `curl -r 0-1023` 是否返回 206;对瓦片端点加缓存层 |
383
+
384
+ ---
385
+
386
+ ## AI 使用建议
387
+
388
+ - **执行环境**:`pip install`、`docker run` 在终端执行;本链路组件多,装包输出长,重定向到文件再分段读。Windows 下 Docker 需先确认守护进程在运行。
389
+ - **先探测版本**:`rio cogeo --version`、`python -c "import stac_fastapi.api as m; print(m.__version__)"`、`curl -s localhost:8000/ | head -c 200`。本技能按 rio-cogeo 7.0.4、stac-fastapi 7.1.1、TiTiler 2.4.0 编写;TiTiler 2.x 与 0.x 的包名和入口完全不同,别混用旧教程。
390
+ - **验证产物**:COG 用 `rio cogeo validate` 的返回值为准,不只看命令是否退出 0;瓦片用 `curl -o tile.png` 后检查文件大小与是否全透明;前端能否出图必须由浏览器确认,AI 助手通常看不到画面。
391
+ - **无 GPU/无对象存储环境**:可用本地 `file://` 或 `http.server` 充当 COG 源验证逻辑,但 Range 行为与真实对象存储不同,不要据此判断生产性能。
392
+ - **参数顺序**:`/cog/tiles/{tileMatrixSetId}/{z}/{x}/{y}.png?url=...` 中 `tileMatrixSetId` 缺省为 `WebMercatorQuad`;`url` 必须 URL 编码,否则带查询串的对象地址会被截断。
393
+ - **常见症状**:400 多为参数名拼错或 `bidx` 越界;404 是路由或 item 不存在;416 是文件不是合法 COG;500 先看服务端日志里的 rasterio 异常。
394
+ - **安全与权限**:不要在前端或汇报里回显云凭据;公开服务前确认影像的许可与分发范围,个别数据源禁止二次发布。
395
+
396
+ ## 相关技能
397
+
398
+ - **gdal** — COG 生成与校验的底层工具链(`gdal_translate -of COG`):[../gdal/SKILL.md](../gdal/SKILL.md)
399
+ - **pdal** — 点云/高程数据的处理,与 DEM 类 COG 配合:[../pdal/SKILL.md](../pdal/SKILL.md)
400
+ - **postgis** — pgstac 的空间检索基础(PostGIS 索引与查询):[../postgis/SKILL.md](../postgis/SKILL.md)
401
+ - **openlayers** — 前端接入 TileJSON 瓦片源:[../openlayers/SKILL.md](../openlayers/SKILL.md)
402
+ - **maplibre-gl-js** — 矢量/栅格瓦片前端渲染:[../maplibre-gl-js/SKILL.md](../maplibre-gl-js/SKILL.md)
403
+ - **cesiumjs** — 影像与地形在三维地球上的叠加:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
404
+
405
+ ## 参考资源
406
+
407
+ - STAC 规范:<https://stacspec.org/>
408
+ - STAC 规范仓库:<https://github.com/radiantearth/stac-spec>
409
+ - STAC API 规范:<https://github.com/radiantearth/stac-api-spec>
410
+ - stac-fastapi 文档:<https://stac-utils.github.io/stac-fastapi/>
411
+ - pgstac:<https://github.com/stac-utils/pgstac>
412
+ - COG 规范:<https://github.com/cogeotiff/cog-spec>
413
+ - rio-cogeo 文档:<https://cogeotiff.github.io/rio-cogeo/>
414
+ - rio-cogeo CLI:<https://cogeotiff.github.io/rio-cogeo/CLI/>
415
+ - TiTiler 文档:<https://developmentseed.org/titiler/>
416
+ - TiTiler COG 端点:<https://developmentseed.org/titiler/endpoints/cog/>
417
+ - TiTiler STAC 端点:<https://developmentseed.org/titiler/endpoints/stac/>
418
+ - TiTiler 镜像:<https://github.com/developmentseed/titiler/pkgs/container/titiler>
419
+ - pystac-client 文档:<https://pystac-client.readthedocs.io/>
420
+ - 中文教程:<https://znlgis.github.io/gis/tutorial/STAC-COG-TiTiler/>
@@ -9,7 +9,7 @@ metadata:
9
9
 
10
10
  > **项目地址:** <https://github.com/jblindsay/whitebox-tools>
11
11
  >
12
- > **官方文档:** 用户手册 <https://jblindsay.github.io/wbt_book/intro.html>(GHRG 手册站镜像;上游 README 里的 `www.whiteboxgeo.com/manual/wbt_book/preface.html` 实测 404,改用本地址)
12
+ > **官方文档:** 用户手册 <https://jblindsay.github.io/wbt_book/intro.html>(GHRG 手册站镜像,实测可用;上游 README 指向的 `www.whiteboxgeo.com/manual/wbt_book/preface.html` 与 `www.whiteboxgeo.com/download-whiteboxtools/` 均实测 404,以本地址和 GitHub Releases 为准)
13
13
  >
14
14
  > **最新版本:** 2.4.0(截至 2026-11,[GitHub Release](https://github.com/jblindsay/whitebox-tools/releases);conda-forge `whitebox_tools` 亦为 2.4.0)
15
15
  >
@@ -17,7 +17,7 @@ metadata:
17
17
  >
18
18
  > **许可证:** MIT
19
19
  >
20
- > **注意:** 上游仓库 README 已标记为 legacy,新开发转向 <https://github.com/jblindsay/whitebox_next_gen>;但 2.4.0 仍是当前稳定可用的开源版本,本文以其为基准。
20
+ > **注意:** 上游仓库 README 已标记为 legacy,新开发转向 <https://github.com/jblindsay/whitebox_next_gen>(Whitebox Workflows,Rust 全栈重写,仓库目前没有公开 release);WhiteboxTools Open Core 2.4.0 仍是当前可用的稳定开源版本,本文以其为基准。
21
21
 
22
22
  ## 概述
23
23
 
@@ -35,7 +35,7 @@ WhiteboxTools 是圭尔夫大学 GHRG 实验室(John Lindsay)用 Rust 编写
35
35
 
36
36
  ### 方式一:下载预编译二进制(推荐)
37
37
 
38
- 到 <https://github.com/jblindsay/whitebox-tools/releases> 下载对应平台的预编译压缩包,解压后目录内含 `whitebox_tools`(Windows 为 `whitebox_tools.exe`)与 `WBT` 插件目录。
38
+ 到 <https://github.com/jblindsay/whitebox-tools/releases> 下载对应平台的预编译压缩包(Open Core 2.4.0),解压后目录内含 `whitebox_tools`(Windows 为 `whitebox_tools.exe`)与 `WBT/` 插件目录。上游 README 里给出的 `whiteboxgeo.com/download-whiteboxtools/` 实测已 404,不要再去那里下载。
39
39
 
40
40
  ```bash
41
41
  cd /opt/WBT # 解压后的 WBT 目录
@@ -99,7 +99,9 @@ whitebox_tools --wd="data/" --run=Slope --dem=input.tif --output=slope.tif --uni
99
99
  | `-v` | 详细模式,打印进度与耗时;`-v=false` 关闭 |
100
100
  | `--listtools [关键词]` | 列出工具及描述,可按关键词过滤 |
101
101
  | `--toolhelp=<Tool>` | 打印某工具的使用帮助 |
102
- | `--toolparameters=<Tool>` | 以 JSON 输出参数定义,适合脚本动态组装参数 |
102
+ | `--toolparameters=<Tool>` | 输出该工具的参数定义(Python 封装里对应 `wbt.tool_parameters("Slope")`) |
103
+ | `--toolbox=<Tool>` | 输出该工具所属的工具箱 |
104
+ | `--viewcode=<Tool>` | 在浏览器打开该工具的源码页 |
103
105
  | `--version` | 版本信息 |
104
106
 
105
107
  **不要凭记忆写参数名**:不同工具的参数差异很大(例如坡度用 `--units`,流量累积工作流用五个 `--out_*` 参数)。写脚本前先 `--toolparameters` 取 JSON,再据此拼参数。
@@ -146,6 +148,20 @@ wbt.run_tool("FillDepressions", ["--dem=dem.tif", "--output=dem_filled.tif", "--
146
148
 
147
149
  `run_tool(tool_name, args)` 的 `args` 是 `--flag=value` 字符串列表,适合官方封装尚未覆盖的新工具;两种方式可混用。
148
150
 
151
+ 查工具与参数用这三个方法,不要凭记忆写参数:
152
+
153
+ ```python
154
+ print(wbt.list_tools()) # 全部工具名与描述
155
+ print(wbt.list_tools(["lidar", "LAS"])) # 按关键词过滤
156
+ print(wbt.tool_help("Slope")) # 单个工具的帮助(描述、参数、示例)
157
+ print(wbt.tool_parameters("Slope")) # 参数定义(脚本动态组装参数用)
158
+ print(wbt.version()) # 底层二进制版本
159
+ ```
160
+
161
+ 工具名在 CLI/帮助里是 CamelCase(`Slope`、`FillDepressions`),Python 便捷方法用 snake_case(`wbt.slope()`、`wbt.fill_depressions()`);`run_tool` 的 `tool_name` 同样接受 snake_case 并由封装转成 CamelCase。
162
+
163
+ 完整工具清单(按主题分组,含每个工具的参数)见手册的工具索引:<https://jblindsay.github.io/wbt_book/tool_index.html>。
164
+
149
165
  ---
150
166
 
151
167
  ## 典型工作流
@@ -16,12 +16,24 @@ export declare const SKILL_SEPARATOR: string;
16
16
  /** Labels every per-skill guidance must keep, in this order. */
17
17
  export declare const REQUIRED_LABELS: readonly string[];
18
18
 
19
- /** DeepSeek Harness tools the guidance may name, used to prove harness specificity. */
19
+ /** Labels whose bullet must carry a concrete command or tool in backticks. */
20
+ export declare const CONCRETE_LABELS: readonly string[];
21
+
22
+ /** DeepSeek Harness tools every supported build exposes; the citation minimums count these. */
23
+ export declare const CORE_TOOLS: readonly string[];
24
+
25
+ /** Optional-plugin tools the guidance may name, but only with a documented fallback. */
26
+ export declare const OPTIONAL_TOOLS: readonly string[];
27
+
28
+ /** Every DeepSeek Harness tool name the guidance may cite: the union of CORE_TOOLS and OPTIONAL_TOOLS. */
20
29
  export declare const DSH_TOOLS: readonly string[];
21
30
 
22
31
  /** List the distinct DeepSeek Harness tool names cited in backticks, in citation order. */
23
32
  export declare function citedTools(text: string): string[];
24
33
 
34
+ /** List the distinct core tool names cited in backticks, in citation order. */
35
+ export declare function citedCoreTools(text: string): string[];
36
+
25
37
  /** Build the path of one per-skill adaptation file. */
26
38
  export declare function adaptationFile(root: string, name: string): string;
27
39