@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
@@ -2,7 +2,7 @@
2
2
 
3
3
  - **加载与引用**:单文件技能,无 reference。正文按 Mapsui **5.1.0**(net8.0 / net9.0,上游 5.2.0-beta.1 为预发布不计入)编写。按任务读:「安装」确认 UI 包与数据源包的组合、「WPF 入门」拿最小可运行工程、「核心概念」区分 Map/Layer/Provider、「WMS」一节的 `WmsProvider.CreateAsync` 是 5.x 硬要求、「常见问题」表覆盖空白 MapControl 与中文乱码。几何细节用 `skill` 加载 `nettopologysuite`,服务端发布用 `skill` 加载 `geoserver`,别去读兄弟目录的 SKILL.md。
4
4
  - **执行环境**:`dotnet` 命令走 `ops_bash`(Windows 下是 MSYS bash),需要看 Windows 原生产物时用 `pwsh`。先探测 `dotnet --list-sdks`:5.1.0 只支持 net8.0/net9.0(`Mapsui.Wpf` 是 net8.0-windows/net9.0-windows),只有 .NET 6/7 的机器必须先装 SDK,不能指望改个 target framework 就编译过。`dotnet add package` 与首次 `dotnet restore` 会拉 NuGet 包,属长任务,用 `ops_bash` 的 `run_in_background` 跑、`job_output` 收日志;本机没有 SDK 时退回 `docker run --rm -v "$PWD:/w" -w /w mcr.microsoft.com/dotnet/sdk:9.0 dotnet build`。新建工程 → 加包 → 编译 → 无头渲染是三步以上,先 `todo_write`。
5
- - **先探测版本**:`dotnet --list-sdks` 与 `dotnet list package` 确认 `Mapsui.Wpf`/`Mapsui.Nts`/`Mapsui.Tiling` 是否都是 5.1.0——正文强调所有 `Mapsui.*` 子包版本必须一致,混版会在运行时抛类型加载异常,编译期看不出来。差异点:5.x 起 WMS 必须用异步工厂 `WmsProvider.CreateAsync`,正文工作流 2 里还留着一处同步 `new WmsProvider(...)` 的旧写法,5.1 上不可用,以「WMS」一节的 `CreateAsync` 为准;WPF 的 NuGet 包名是 `Mapsui.Wpf`,程序集/命名空间仍是 `Mapsui.UI.Wpf`,网上 v2 教程的包名会装不上。
5
+ - **先探测版本**:`dotnet --list-sdks` 与 `dotnet list package` 确认 `Mapsui.Wpf`/`Mapsui.Nts`/`Mapsui.Tiling` 是否都是 5.1.0——正文强调所有 `Mapsui.*` 子包版本必须一致,混版会在运行时抛类型加载异常,编译期看不出来。差异点:5.x 起 WMS 必须用异步工厂 `WmsProvider.CreateAsync`,正文工作流与「WMS」节已统一成这个写法;外部教程里的同步 `new WmsProvider(...)` 在 5.1 上不可用,照抄编译不过。`CreateAsync` 会先拉 `GetCapabilities`,地址写错在这一步就抛异常;创建后 `AddLayer` 的图层名要与能力文档完全一致、`CRS` 与 `Map.CRS` 一致,否则地图空白而不报错。WPF 的 NuGet 包名是 `Mapsui.Wpf`,程序集/命名空间仍是 `Mapsui.UI.Wpf`,网上 v2 教程的包名会装不上。
6
6
  - **验证产物**:`dotnet restore`/`dotnet build` 通过只说明编译过,正文已明确要求用 `Mapsui.Rendering.Skia.MapRenderer` 把 `map` 渲染成 PNG(参数以 IntelliSense 为准,常见做法是 `RenderToBitmapStream` 写 MemoryStream 再落盘),然后用 `read_image` 真看一眼:底图瓦片有没有、点位是否在预期位置、WMS 层是否出现。桌面窗口本身 AI 看不到,需请用户运行后截图。空白的地图 PNG 与「渲染成功」是两件事,只凭 build 退出码 0 报告成功属于假验证。
7
7
  - **风险与权限**:新建 .NET 工程、装 NuGet 包、运行桌面程序都会改用户机器状态,先 `ask_user_question` 给「只新建到指定目录 / 用 Docker 构建 / 先不建」选项。连接 PostGIS 或私有 WMS 的密码、token 不要写进代码或回答,改用环境变量或用户机密存储;`Map.ZoomToExtents()` 在无数据图层上会让视图缩到无效范围,别对空 map 调用。
8
8
  - **常见失败**:窗口空白先查有没有执行 `MapControl.Map = map`,再查 NuGet 里是否缺 `Mapsui.Wpf`;MAUI 空白查 `MauiProgram` 里 `UseSkiaSharp()` 与 `UseMapsui()` 是否注册;点跑到南太平洋是漏了 `SphericalMercator.FromLonLat(lon, lat)`(视图坐标系是 EPSG:3857);Shapefile 中文乱码是 DBF 缺 `.cpg`,用 `new ShapeFile(path, true) { Encoding = ... }` 属性赋值而非构造参数;找不到 `GeometryFeature` 装 `Mapsui.Nts`,找不到瓦片类型装 `Mapsui.Tiling`。
@@ -0,0 +1,8 @@
1
+ ## DeepSeek Harness 使用建议
2
+
3
+ - **加载与引用**:单文件技能,没有 reference 目录;正文「核心命令」的参数表与预设组合是主要入口,「典型工作流」四条链路按场景取用,「常见问题」表先对症状。成果入库转换用 `skill` 加载 `gdal`,点云清洗用 `pdal`,三维发布用 `cesiumjs`;不要 `read` 兄弟目录的 SKILL.md。
4
+ - **执行环境**:全部命令在 `ops_bash` 里跑,Windows 侧依赖 Docker Desktop,动手前确认守护进程在跑(`docker info` 能出 Server 段)。正文的 `docker run -ti` 在 DSH 里会因无 TTY 报 `the input device is not a TTY`,去掉 `-t` 只留 `-i` 或直接不加;MSYS bash 会把 `-v /datasets:/datasets` 这类参数当路径改写,挂载统一写成宿主 `-v /d/datasets:/datasets` 并在命令前加 `MSYS_NO_PATHCONV=1`,或改用 `pwsh` 调 `docker run -v d:/datasets:/datasets`。整条流水线以小时计、镜像首次拉取就上 GB,必须 `run_in_background` 起作业、`job_output`(可带 `wait`)收进度与末尾日志,跑错再 `job_kill`,不要在一条前台命令里等完。
5
+ - **先探测版本**:`docker --version` 与 `docker info --format '{{.MemTotal}}'` 先看引擎与可用内存(OOM 是头号失败原因),`docker run --rm opendronemap/odm:3.6.2 --version` 确认镜像标签是正文写的 3.6.2 而不是 `latest`,第一次会先拉镜像,同样放后台。WebODM 侧 `curl -s http://localhost:8000/api/` 应返回带 version 的 JSON,起 `./webodm.sh` 前先 `curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/` 看端口有没有被占。
6
+ - **验证产物**:先数输入 `ls images | wc -l` 与预计张数一致,再看退出码——137 就是 OOM,别当普通失败。产物按正文目录约定逐项核:`gdalinfo -json odm_orthophoto/odm_orthophoto.tif` 核对 CRS 与尺寸、`gdalinfo -stats odm_dem/dsm.tif` 看高程范围是否合理,`odm_report/` 里的重叠度与重投影误差才是质量判据,只出图不代表成果可信。要肉眼确认正射影像,用 OSGeo4W 的 `gdal_translate -of PNG -outsize 1024 0 odm_orthophoto.tif preview.png` 生成缩略图后 `read_image` 看一眼,纯白或被裁成一条与空文件同罪;WebODM 的成果最终由用户在 2D/3D 查看器确认,写明「打开哪个地址、应看到什么」。
7
+ - **风险与权限**:`--rerun` 会就地重算并覆盖已有阶段产物、`./webodm.sh down` 删容器、`docker system prune` 清镜像层,都不可逆,执行前用 `ask_user_question` 给「换项目目录重跑/覆盖现有成果/取消」;WebODM 的 `admin` 密码与 JWT token 从环境变量传入、命令里只引用 `$TOKEN`,日志与回答里不回显。对外暴露 8000/3000 端口、上传航拍影像、把成果传给第三方之前,确认数据合规(测绘资质与隐私)。
8
+ - **常见失败**:`No images found` 是缺 `images/` 子目录或 `--project-path` 传成了数据集本身;空三大量未注册先查重叠度与糊片,改参数救不回来;正射空白或被裁条先去 `--auto-boundary` 再试;没有 `dsm.tif` 是没传 `--dsm`;Windows 挂载失败基本是路径写了反斜杠或 Docker Desktop 没共享该盘符。
@@ -1,6 +1,6 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:本技能是索引型入口:先按四个阶段定位工具,再用 `skill` 加载子技能读细节(`gdal`、`gdal-api`、`qgis-process`、`pyqgis`、`geoserver-rest-api`、`openlayers`、`cesiumjs`),别指望本文给全参数。两份参考要分段取:`reference/data-stages.md` 先看开头 `## Contents` 定位阶段一至阶段四的小节,再按 `offset`/`limit` 读;`reference/workflow-cheatsheets.md` 只取端到端示例、内置算法速查、GDAL 命令速查几节,用 `grep` 定位比整读快。
3
+ - **加载与引用**:本技能是索引型入口:先按四个阶段定位工具,再用 `skill` 加载子技能读细节(`gdal`、`gdal-api`、`qgis-process`、`pyqgis`、`geoserver-rest-api`、`openlayers`、`cesiumjs`、`stac-cog-titiler`),别指望本文给全参数;影像云原生链路(COG 出图、STAC 编目、TiTiler 动态切片)从 `stac-cog-titiler` 进。两份参考要分段取:`reference/data-stages.md` 先看开头 `## Contents` 定位阶段一至阶段四的小节,再按 `offset`/`limit` 读;`reference/workflow-cheatsheets.md` 只取端到端示例、内置算法速查、GDAL 命令速查几节,用 `grep` 定位比整读快。
4
4
  - **执行环境**:四个阶段的命令都在 `ops_bash` 里跑。Windows 没有 `apt-get`/`sudo`:GDAL 走 OSGeo4W 绝对路径或 conda-forge,QGIS 用官方安装包(`qgis_process` 随安装自带),GeoServer 用 Docker。`QT_QPA_PLATFORM=offscreen` 在 bash 写成单条命令前缀,在 `pwsh` 写 `$env:QT_QPA_PLATFORM = "offscreen"`。起服务用后台作业:`docker run -d -p 8080:8080 docker.osgeo.org/geoserver:3.0.2` 以 `run_in_background` 启动,再用 `job_output` 轮询就绪,别让一次调用阻塞;收尾 `job_kill`。`qgis_process` 参数多,先 `qgis_process help <id> --json`。
5
5
  - **先探测版本**:`gdalinfo --version` / `ogrinfo --version`(正文基准 GDAL 3.13.3)、`qgis_process --version`(基准 QGIS 4.2.3,LTR 3.44.15;4.x 与 3.44 的 Processing 算法 ID 和 Qt 版本不同,混用会报未知算法)、`curl -u admin:geoserver "http://localhost:8080/geoserver/rest/about/version.json"`(GeoServer 3.0.2)、`python3 -c "from osgeo import gdal; print(gdal.VersionInfo())"`。缺哪个阶段的工具就加载相邻子技能,不要硬拼整条链路。
6
6
  - **验证产物**:每阶段产物落工作区(GeoPackage/COG/GeoJSON),下一阶段只读产物。转换后 `ogrinfo -so -al`、`gdalinfo -json` 核对 CRS、范围与要素数;发布后 `curl` 回读 `layers/demo:roads_buffer.json`,要求 HTTP 200 且含 `"enabled": true`,或查 `GetCapabilities`;WMS 出图后用 `read_image` 看一眼贴图是否真有内容。要交付的 GeoJSON、地图包用 `present` 列出。任一步失败先修本阶段产物,别带坏数据往下走。
@@ -2,7 +2,7 @@
2
2
 
3
3
  - **加载与引用**:单文件技能,无 reference 目录;参数不确定时先跑 `pdal --options filters.smrf` 或 `pdal --drivers` 取运行时定义,别凭记忆写 stage 参数——正文的算子参数表与这些命令输出以实际版本为准。管线较长时用 `write` 把 JSON 存成工作区里的 `pipeline.json`,复用和逐条改动都比命令行内联可靠;复杂管线按「读取→裁剪/重投影→过滤→写出」分段拼,出错好定位。需要 DEM 后处理时用 `skill` 加载 `gdal`。
4
4
  - **执行环境**:`pdal info/translate/pipeline/--drivers` 走 `ops_bash`;`Get-Command pdal` 或带反斜杠的 Windows 路径参数走 `pwsh`。本机 Windows 无 `sudo`/`apt`:PDAL 来自 conda-forge(`conda install -c conda-forge pdal python-pdal`)、OSGeo4W,或容器 `docker run --rm -v "$PWD":/data -w /data pdal/pdal pdal pipeline pipeline.json`(容器内路径写 `/data/...`,不要传宿主 `D:\...`)。整片点云处理、DEM 全量栅格化放后台作业,用 `job_output` 收日志、`job_kill` 收尾。
5
- - **先探测版本**:`pdal --version` 与 `pdal --drivers`;正文按 2.10.2 编写,`pdal ground` 自 2.6 弃用、2.7 移出默认安装、2.8 完全移除,见到旧命令一律换 `filters.smrf` 管线写法;低版本可能没有 `filters.expression`,`filters.range` 虽在但自 2.5 起推荐 `filters.expression`、将在 3.0 弃用。Python 侧 `pip install PDAL` 依赖系统已装 PDAL 库(需 `pdal-config`),PyPI 的 `pdal` 3.5.5 与主库 2.10.2 是两套独立版本号,不要混为一谈。
6
- - **验证产物**:点云用 `pdal info --summary out.laz` 核对 `num_points`、`bounds`、`srs`(转换前后的点数差异要能解释,比如裁剪后减少、去噪后仍保留全部点仅标 Class=7);DEM 用 `gdalinfo -json dem.tif` 看波段数与范围,注意 `writers.gdal` 默认 `output_type: "all"` 会输出多波段,要单波段必须显式写 `idw`/`mean`。管线先 `pdal pipeline --validate` 再实跑,退出码 0 不能证明结果正确;DEM 或点云渲染图用 `read_image` 看一眼,成品用 `present` 交付。
7
- - **风险与权限**:`pdal translate` 与各 writer 按 `filename` 覆盖同名输出,先确认目标文件名、换名或备份;`filters.outlier`、`filters.smrf` 需要全局统计、不能流式,大点云先按 tile 拆分,别一次把整片读进内存。拉取 Docker 镜像、下载大点云、安装 PDAL、写用户目录外的路径前用 `ask_user_question` 让用户选方案;SMRF 参数(`window`、`slope`、`threshold`)改动会影响地面分类结果,交付前说明用了哪组参数。
5
+ - **先探测版本**:`pdal --version` 与 `pdal --drivers`;正文按 2.10.2 编写,`pdal ground` 自 2.6 弃用、2.7 移出默认安装、2.8 完全移除,见到旧命令一律换 `filters.smrf` 管线写法;2.10 才有的 `filters.m3c2`、`filters.radiusassign`、`writers.gdal` 的 `p<percentile>` 波段需先确认驱动列表里有;`readers.spz`/`writers.spz` 在 2.10 变成插件,标准安装的 `--drivers` 里看不到属正常,别当成损坏。低版本没有 `filters.expression` 时退回 `filters.range`(2.5 起推荐 expression、3.0 弃用 range)。Python 侧 `pip install PDAL` 依赖系统已装 PDAL 库(需 `pdal-config`),PyPI 的 `pdal` 3.5.5 与主库 2.10.2 是两套独立版本号。
6
+ - **验证产物**:点云用 `pdal info --summary out.laz` 核对 `num_points`、`bounds`、`srs`(转换前后的点数差异要能解释,比如裁剪后减少、去噪后仍保留全部点仅标 Class=7);DEM 用 `gdalinfo -json dem.tif` 看波段数与范围:`writers.gdal` 默认 `output_type: "all"` 输出多波段,`p95` 这类百分位波段不计入 `all`,要单波段必须显式写 `idw`/`mean`,`binmode: true` 时只统计落在像元内的点、值域会变。`filters.georeference` 在 2.10 输出 ECEF(EPSG:4978),要经纬度必须再接 `filters.reprojection`,否则 `pdal info` 里的 srs 会是 4978。管线先 `pdal pipeline --validate` 再实跑,退出码 0 不能证明结果正确;DEM 或点云渲染图用 `read_image` 看一眼,成品用 `present` 交付。
7
+ - **风险与权限**:`pdal translate` 与各 writer 按 `filename` 覆盖同名输出,先确认目标文件名、换名或备份;`filters.outlier`、`filters.smrf` 需要全局统计、不能流式,大点云先按 tile 拆分。拉取 Docker 镜像、下载大点云、安装 PDAL、写用户目录外的路径前用 `ask_user_question` 让用户选方案;从源码编译时 GDAL 必须 3.8+(`cmake/gdal.cmake` 硬校验,报 `Required at least GDAL version 3.8`),SMRF 参数改动会影响地面分类结果,交付前说明用了哪组参数。
8
8
  - **常见失败**:`Couldn't create <cls> stage of type '<type>'` 是 stage 名拼错或版本没有该 stage,先 `pdal --drivers` 确认;`pipeline` 解析失败用 `--validate` 定位 JSON 语法与顶层结构;`filters.reprojection` 报缺 SRS 补 `out_srs`(数据本身无坐标系时再给 `in_srs`);重投影后精度变差在 writer 设 `scale_x/y/z` 与 `offset_x/y/z: "auto"`;Python 侧 `execute()` 返回点数不是数组,数据在 `pipeline.arrays`,失败看 `pipeline.log`。
@@ -2,7 +2,7 @@
2
2
 
3
3
  - **加载与引用**:单文件技能,无 reference;正文「环境准备」教装包、「核心 API」给坐标系与转换接口、「典型工作流」给 CSV 批量转换、「常见问题」给报错对照。坐标转换的标准起手式是正文的「WKT 由专业工具生成」:先用 PROJ 导出 WKT 再写代码,不手写 `PROJCS`。需要坐标系定义与命令行核对时可 `skill` 加载 `proj`,几何运算加载 `nettopologysuite`,老项目兼容 1.4.1 时参考 `sharpmap`。
4
4
  - **执行环境**:`dotnet add package`、`dotnet build`、`dotnet run` 走 `ops_bash`(Windows 下是 MSYS bash,C# 工程路径写 `/d/work/proj-demo`);PowerShell 专有写法(`Install-Package`、`$env:` 变量)走 `pwsh`。首次 restore 必须能访问 NuGet,离线时先确认本地缓存或私有源再动工。临时工程建在会话工作区,不要写进 `assets/`。
5
- - **先探测版本**:正文按 `ProjNet` 2.1.0 编写(netstandard2.0/2.1),1.x 侧是 `ProjNet4GeoAPI` 1.4.1。先跑 `dotnet list package` 看实际装的是哪个:2.x 用 `ProjNet.CoordinateSystems` 自带类型,1.x 实现 GeoAPI 接口,两者程序集同名 `ProjNET.dll`,`using` 与接口名完全不同,项目里只应出现一个,混装会报「找到多个同名类型」。`MathTransform.TransformList` 与 `Transform(Span<double>, Span<double>)` 这批批量重载只出现在正文的 2.x 清单里,1.x 上照抄前先编译确认。
5
+ - **先探测版本**:正文按 `ProjNet` 2.1.0 编写(netstandard2.0/2.1),1.x 侧是 `ProjNet4GeoAPI` 1.4.1。先跑 `dotnet list package` 看实际装的是哪个:2.x 用 `ProjNet.CoordinateSystems` 自带类型,1.x 实现 GeoAPI 接口,两者程序集同名 `ProjNET.dll`,`using` 与接口名完全不同,项目里只应出现一个,混装会报「找到多个同名类型」。`MathTransform.TransformList` 与 `Transform(Span<double>, Span<double>, int strideX = 1, int strideY = 1)` 这批批量重载只出现在正文的 2.x 清单里,1.x 上照抄前先编译确认;数组有交错间隔时直接传 `strideX`/`strideY`,不要先手工拆成两份数组。
6
6
  - **验证产物**:编译后先跑正文的最小判据:`CreateFromCoordinateSystems(GeographicCoordinateSystem.WGS84, ProjectedCoordinateSystem.WebMercator)` 转换 `{116.397, 39.908}`,输出应约为 `12957254.80, 4852582.10`;批量转换后用高斯投影量级判断——东坐标 6 位(含带号 8 位)、北坐标 0–5000000,若仍是 116/39 量级说明坐标系取错或 WKT 解析失败被静默跳过。再拿 `projinfo EPSG:4547 -o WKT2:2019` 的 WKT 用 `CreateFromWkt` 单独解析一次,返回 `null` 就是这份 WKT 不被支持。与 QGIS/GDAL 差几十米属正文已知精度限制,不是代码错误。
7
7
  - **风险与权限**:新建工程、`dotnet add package`、在 1.x/2.x 之间换包都会改 `*.csproj` 与 `obj/`,动手前先 `read` 现有工程文件确认引用;两个包互斥且替换会自动卸载旧包,改动别人的工程依赖前用 `ask_user_question` 让用户在「只加 2.x / 保留 1.x / 先备份 csproj」之间选。`CoordinateSystemServices` 只认识传入的 SRID 与默认 4326/3857,不要当 EPSG 库用;示例里的 WKT 与数据路径用占位符,不要写进用户真实路径或凭据。
8
8
  - **常见失败**:`CreateFromCoordinateSystems` 返回 `null` 或抛异常,多半是「两个地理坐标系只差基准面而缺转换参数」,改成地理→投影两段式;`GetCoordinateSystem(4490)` 返回 `null` 是默认只注册 4326/3857,用 `KeyValuePair<int, string>` 构造函数注册;整列结果反号是输入按 `[x, y]` 解释,把 `[lat, lon]` 改成 `[lon, lat]`;转换极慢是工厂与 `MathTransform` 建在循环里,提到循环外并改用批量重载。
@@ -1,7 +1,7 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
3
  - **加载与引用**:单文件技能,无 reference;部署方式看「环境准备」(Debian 包 / OSGeo4W / Docker),请求示例看「核心 API / 命令」,变量与排查看「服务端环境变量」「常见问题」。服务端插件逻辑与项目自动化用 `skill` 加载 `pyqgis`,另一套 OGC 方案加载 `geoserver`,数据源侧加载 `postgis`。
4
- - **执行环境**:服务端部署在 Linux/容器,本机是 Windows 会话,所以默认路径是 Docker:`docker run -d --name qgis-server ... qgis/qgis:ltr` 起容器再用 `curl`(Windows 下必须写 `curl.exe`)打请求,容器与端口用后台作业或独立 shell 保持运行,`job_output` 收日志、`job_kill` 停容器。正文的 `sudo apt install qgis-server`、`/usr/lib/cgi-bin/qgis_mapserv.fcgi`、Apache/Nginx 片段都是目标服务器写法,本机会话改不了远端主机,要么在主机上执行,要么全部在容器里验证;OSGeo4W 路线在本机装 `QGIS Desktop + QGIS Server + apache + mod_fcgid` 后才可用。`SetEnv`/`fastcgi_param` 属于服务器配置,别当本地命令跑。
4
+ - **执行环境**:`docker`、`curl.exe` 走 `ops_bash`(Windows 是 MSYS bash),原生 Windows 写法与 `$env:` 变量走 `pwsh`,多步编排可用 `run_code` 串起来。服务端部署在 Linux/容器,本机是 Windows 会话,所以默认路径是 Docker:`docker run -d --name qgis-server ... qgis/qgis:ltr` 起容器再用 `curl`(Windows 下必须写 `curl.exe`)打请求,容器与端口用 `ops_bash` 的 `run_in_background` 起、`job_output` 收日志、`job_kill` 停容器。正文的 `sudo apt install qgis-server`、`/usr/lib/cgi-bin/qgis_mapserv.fcgi`、Apache/Nginx 片段都是目标服务器写法,本机会话改不了远端主机,要么在主机上执行,要么全部在容器里验证;OSGeo4W 路线在本机装 `QGIS Desktop + QGIS Server + apache + mod_fcgid` 后才可用。`SetEnv`/`fastcgi_param` 属于服务器配置,别当本地命令跑。
5
5
  - **先探测版本**:正文按 QGIS Server 4.2.3(最新)与 LTR 3.44.15 编写。先确认服务端版本:`qgis --version`、`qgis_process --version`、`dpkg -l qgis-server` 或看镜像 tag;生成项目的 QGIS Desktop 与服务端应同一主版本,否则旧项目可能打不开。直接执行 `qgis_mapserv.fcgi`(无参数)在 Linux 上应返回含 `ServiceExceptionReport` 的 XML,这是「装上且能跑」的最低判据,Windows/Docker 下用功能更全的 `GetCapabilities` 代替。
6
6
  - **验证产物**:`curl.exe -sS "http://localhost/cgi-bin/qgis_mapserv.fcgi?MAP=/data/world.qgz&SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities" -o caps.xml` 存盘后 `grep -n "<Layer>" caps.xml` 核对图层清单(名字、CRS、样式),确认不是空文档或异常报告;再发 `GetMap` 拿 PNG 用 `read_image` 真看一眼是否空白、范围是否正确,`GetFeature` 取 GeoJSON 检查要素字段。只看到 HTTP 200 不算通过,正文明确 `GetMap` 的 500/空白要回查 `MAP` 路径可读性、图层 `published` 勾选与 CRS/`BBOX`。
7
7
  - **风险与权限**:启动容器、映射 80 端口、改 Web 服务器配置、把服务暴露到非回环地址之前必须用 `ask_user_question` 让用户确认(尤其本机已有 Apache/Nginx 占用端口时);工程文件可能含数据库连接串与口令,命令行、日志与回复里不要回显,二进制用 `QGIS_PROJECT_FILE` 环境变量引用而不是把密码拼进 URL。`GetPrint` 在无 X 的 Linux 上要 `Xvfb`(`DISPLAY=:99`),别指望它直接出图;`QGIS_SERVER_LOG_FILE` 已废弃,统一 `QGIS_SERVER_LOG_STDERR=1` 交给日志系统。
@@ -2,7 +2,7 @@
2
2
 
3
3
  - **加载与引用**:正文主文件给类型、双 API、创建与常见问题,完整构造操作、谓词、集合运算、度量、STRtree、仿射与线性参考在 `reference/operations-reference.md`。先用 `read` 读该文件开头的小节目录定位,再 `offset`/`limit` 分段取用,或 `grep` 搜函数名(如 `coverage_clean`),不要整份读进上下文。矢量表读写用 `skill` 加载 `geopandas`,坐标投影按正文「坐标投影」一节用 pyproj,QGIS 内几何计算加载 `pyqgis`。
4
4
  - **执行环境**:命令走 `ops_bash`(Windows 是 MSYS bash),Python 解释器要用装了 shapely 的那一个,先 `python -c "import sys; print(sys.executable, sys.version)"` 确认不是 QGIS/GDAL 自带环境,否则可能装到别的 site-packages。正文的 `pip install shapely` 在 Windows 上同样可用(wheel 自带 GEOS),但装包前需用户同意;纯命令行的 Windows 专有操作(`Get-ChildItem`、`$env:PATH`)走 `pwsh`。批量处理十万级几何用后台作业跑,`job_output` 收进度、`job_kill` 收尾。
5
- - **先探测版本**:正文按 Shapely 2.2.0 编写(Python 3.11+、NumPy >= 1.26、GEOS >= 3.10,PyPI wheel 内嵌 GEOS 3.14)。先跑 `python -c "import shapely; print(shapely.__version__, shapely.geos_version)"` 拿到两个版本:GEOS 低于门槛的函数会直接报错或缺失——`concave_hull`/`remove_repeated_points` 要 3.11,`coverage_simplify`/`has_m`/`get_m` 要 3.12,`coverage_clean` 要 3.14,顶层 `shapely.split` 要 3.15(低版本回退 `shapely.ops.split`);`multithreading_enabled` 与 `shapely.ops.transform` 在 2.2 已弃用,改 `shapely.transform`/`shapely.transform_coordseq`。
5
+ - **先探测版本**:正文按 Shapely 2.2.0 编写(Python 3.11+、NumPy >= 1.26、GEOS >= 3.10,PyPI wheel 内嵌 GEOS 3.14.1;2.1.2 的 wheel 才是 3.13.1)。先跑 `python -c "import shapely; print(shapely.__version__, shapely.geos_version)"` 拿到两个版本:GEOS 低于门槛的函数会直接报错或缺失——`concave_hull`/`remove_repeated_points` 要 3.11,`coverage_simplify`/`has_m`/`get_m` 要 3.12,`coverage_clean` 要 3.14,顶层 `shapely.split` 要 3.15(低版本自动回退 `shapely.ops.split`)。`minimum_width`、`get_segments`、`transform_coordseq` 是 2.2 才有的顶层函数,缺失说明装的是旧版。`shapely.ops.transform` 与 `multithreading_enabled` 在 2.2 已弃用,改 `shapely.transform`/`shapely.transform_coordseq`。
6
6
  - **验证产物**:先用 `shapely.is_valid(g)` 与 `shapely.is_valid_reason(g)` 报出无效原因,再断言面积/长度量级;序列化回读 `shapely.from_wkt(shapely.to_wkt(g, rounding_precision=-1)).equals(g)`,改过几何后再核对 `geom_type` 与 `get_num_geometries()`。正文的端到端验收标准可直接照用:`clipped.geojson` 每个 Feature 能被 `shapely.from_geojson()` 读回、`is_valid()` 全为 True、面积与输入同阶。产出的图(`shapely.plotting` 或后续渲染)用 `read_image` 真看一眼,成品用 `present` 交付。
7
7
  - **风险与权限**:`pip install shapely`、升级 GEOS 环境、改共享 conda 环境前用 `ask_user_question` 确认;`set_coordinates()`/`shapely.prepare()` 是原地修改,动手前先 `.copy()`,覆盖用户数据文件前先备份或换输出名。WKT/坐标导出前确认数据敏感度(精确坐标可反推位置),大几何别 dump 到终端刷屏,写到文件再 `read` 分段看。
8
- - **常见失败**:`TopologyException: side location conflict` 基本是输入自相交,先 `make_valid()` 再算,不要用 `buffer(0)` 糊过去;面积/距离为 0 或极小是地理坐标系按度算,先投影到米制;`contains` 对边界点返回 False,改用 `covers()`;OOP 与函数式结果不同是 `buffer` 默认 `quad_segs` 不同(16 vs 8),比较前显式传参;`STRtree` 查空先排除 `None`/`Empty` 与 CRS 不一致。
8
+ - **常见失败**:`TopologyException: side location conflict` 基本是输入自相交,先 `make_valid()` 再算,不要用 `buffer(0)` 糊过去;`UnsupportedGEOSVersionError` 是底层 GEOS 太旧,核对 `shapely.geos_version`,升级 wheel(自带 GEOS)而不是只升级系统 GEOS;面积/距离为 0 或极小是地理坐标系按度算,先投影到米制;`contains` 对边界点返回 False,改用 `covers()`;OOP 与函数式结果不同是 `buffer` 默认 `quad_segs` 不同(16 vs 8),比较前显式传参;`STRtree` 查空先排除 `None`/`Empty` 与 CRS 不一致。
@@ -1,8 +1,8 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;加载方式见「环境准备」,DDL 与函数表见「核心 API」,端到端导入查询导出见「典型工作流」,报错对照见「常见问题」。GDAL 侧的导入导出用 `skill` 加载 `gdal`,Python 侧读写用 `skill` 加载 `geopandas`,坐标转换细节加载 `proj`。
4
- - **执行环境**:命令走 `ops_bash`(Windows 是 MSYS bash);Linux 的 `sudo apt install libsqlite3-mod-spatialite` 在 Windows 不可用,改用 conda-forge:`conda install -c conda-forge libspatialite`(会同时给出 `mod_spatialite.dll` 与 `sqlite3`),或解压官方 Windows 包后把 DLL 目录加进 PATH。`.load mod_spatialite` 是 sqlite shell 的内置命令而不是 SQL,Windows 下要写成 `.load mod_spatialite.dll` 并注意 shell 与 DLL 位数一致。批量导入与大表建索引放后台作业,`job_output` 收进度、`job_kill` 收尾。
5
- - **先探测版本**:正文按 libspatialite 5.1.0(2023-08-04)与 spatialite-tools 5.1.0a 编写,截至 2026-11 仍为最新。先用正文那三条验证依次过一遍:文件是否存在、`spatialite :memory: "SELECT spatialite_version();"`、Python 侧 `c.load_extension("mod_spatialite")` 后查同一函数。发行版包常落后(如 bookworm 是 5.0.1),4.x 与 5.x 的函数集不同(`GeosMakeValid`、`InitSpatialMetaData` 重载都是 5.x 才齐全),拿到版本号后再决定用哪个函数名,拿不准查官方 SQL 函数页。
6
- - **验证产物**:导入或建索引后回读 `geometry_columns`:`SELECT f_table_name, f_geometry_column, geometry_type, srid, spatial_index_enabled FROM geometry_columns;` 确认几何列、SRID 与索引开关;再跑 `SELECT CheckSpatialIndex('表','geom');` 确认 RTree 与主表同步,返回 -1 就是没建好。导出的 GPKG 用 `ogrinfo -so out.gpkg 图层名` 核对要素数与 CRS。查询结果表先 `SELECT count(*)` 再抽样几行,确认单位没有混用(度 vs 米)(4326 下 `ST_Distance` 返回度,米制要 `ST_Transform` 到 3857)。成品库文件用 `present` 交付。
7
- - **风险与权限**:`DROP TABLE`、`DisableSpatialIndex`、批量 `DELETE`/`UPDATE` 都改不回旧状态(事务只保护单次会话),执行前先备份 `.sqlite` 文件或复制成新路径,并用 `ask_user_question` 给「先备份 / 换新库 / 直接改」三个选项。GDAL 的 `-dsco SPATIALITE=YES` 会重建库结构,覆盖已有输出前先确认;`ST_Transform` 依赖 PROJ,跨环境时先探测。
8
- - **常见失败**:`no such function: InitSpatialMetaData` 是扩展没加载或加载的是空壳库,先 `.load` 再用 `spatialite_version()` 验证;`no such module: mod_spatialite` 给绝对路径加载;`CreateSpatialIndex` 返回 -1 是表里有名为 `rowid` 的物理列遮蔽了真 ROWID,重命名后再建;`geometry has invalid SRID` 是混入 SRID -1/0 的几何,用 `GeomFromText(wkt, 4326)` 赋回;查询慢是只用 `ST_Distance` 没加 `MbrWithin` 粗筛。
3
+ - **加载与引用**:单文件技能,无 reference;加载方式见「环境准备」与「核心 API → 加载扩展」,DDL 与函数表见「核心 API」,端到端导入查询导出见「典型工作流」,报错对照见「常见问题」。GDAL 侧的导入导出用 `skill` 加载 `gdal`,Python 侧读写用 `skill` 加载 `geopandas`,坐标转换细节加载 `proj`。
4
+ - **执行环境**:命令走 `ops_bash`(Windows 是 MSYS bash);Linux 的 `sudo apt install libsqlite3-mod-spatialite` 在 Windows 不可用,改用 conda-forge:`conda install -c conda-forge libspatialite`(会同时给出 `mod_spatialite.dll` 与 `sqlite3`),或解压官方 Windows 包后把 DLL 目录加进 PATH。`.load mod_spatialite` 是 sqlite shell 的内置命令而不是 SQL,Windows 下要写成 `.load mod_spatialite.dll` 并注意 shell 与 DLL 位数一致。一次性执行按正文写法把选项放库文件之前:`spatialite -cmd ".load mod_spatialite" mydb.sqlite "SELECT spatialite_version();"`;多条语句用 heredoc 从 stdin 送 `.load` + SQL,比转义引号稳。批量导入与大表建索引放后台作业,`job_output` 收进度、`job_kill` 收尾。
5
+ - **先探测版本**:正文按 libspatialite 5.1.0(2023-08-04)与 spatialite-tools 5.1.0a 编写,截至 2026-11 仍为最新。先按正文三条验证依次过:库文件是否存在(Windows 是 `mod_spatialite.dll`)、CLI 能否加载并报版本 `spatialite -cmd ".load mod_spatialite" :memory: "SELECT spatialite_version();"`(Windows 上把库名写成 `mod_spatialite.dll`)、Python 侧 `python -c "import sqlite3; c=sqlite3.connect(':memory:'); c.enable_load_extension(True); c.load_extension('mod_spatialite'); print(c.execute('SELECT spatialite_version()').fetchone())"`;三条任一失败先解决加载问题,再动 SQL。发行版包常落后(如 bookworm 是 5.0.1),4.x 与 5.x 函数集不同(`GeosMakeValid`、`InitSpatialMetaData` 重载 5.x 才齐全),拿到版本号再决定用哪个函数名。
6
+ - **验证产物**:导入或建索引后回读 `geometry_columns`:`SELECT f_table_name, f_geometry_column, geometry_type, srid, spatial_index_enabled FROM geometry_columns;` 确认几何列、SRID 与索引开关;再跑 `SELECT CheckSpatialIndex('表','geom');` 确认 RTree 与主表同步,返回 -1 就是没建好。导出的 GPKG 用 `ogrinfo -so out.gpkg 图层名` 核对要素数与 CRS。查询结果先 `SELECT count(*)` 再抽样几行,确认单位没有混用(4326 下 `ST_Distance` 返回度,米制要 `ST_Transform` 到 3857)。成品库文件用 `present` 交付。
7
+ - **风险与权限**:`DROP TABLE`、`DisableSpatialIndex`、批量 `DELETE`/`UPDATE` 都改不回旧状态(事务只保护单次会话),执行前先备份 `.sqlite` 文件或复制成新路径,并用 `ask_user_question` 给「先备份 / 换新库 / 直接改」三个选项。GDAL 的 `-dsco SPATIALITE=YES` 会重建库结构,覆盖已有输出前先确认;`InitSpatialMetaData` 对已初始化库重复调用返回 0、不破坏数据,但仍应只跑一次。
8
+ - **常见失败**:`no such function: InitSpatialMetaData` 是扩展没加载或加载的是空壳库,先 `.load` 再用 `spatialite_version()` 验证;`no such module: mod_spatialite` 给绝对路径加载;CLI 里 `.load` 报失败先查 shell 与库位数/构建是否匹配,再改用 Python 或 `ogrinfo` 路径;`CreateSpatialIndex` 返回 -1 是表里有名为 `rowid` 的物理列遮蔽了真 ROWID,重命名后再建;`geometry has invalid SRID` 是混入 SRID -1/0 的几何,用 `GeomFromText(wkt, 4326)` 赋回;查询慢是只用 `ST_Distance` 没加 `MbrWithin` 粗筛。
@@ -0,0 +1,8 @@
1
+ ## DeepSeek Harness 使用建议
2
+
3
+ - **加载与引用**:单文件技能,没有 reference 目录;正文「核心概念与命令」的 COG/STAC/TiTiler 三段与「典型工作流」三条链路是主线,「常见问题」按症状查。COG 侧命令与校验的通用细节用 `skill` 加载 `gdal`,pgstac 的库侧知识用 `postgis`,前端消费 TileJSON 用 `maplibre-gl-js`;不要 `read` 兄弟目录的 SKILL.md。
4
+ - **执行环境**:Python 依赖装进会话工作区的 venv(`python -m venv .venv` 后 `.venv/Scripts/python -m pip install ...`,MSYS bash 里路径写 `/d/work/.venv/Scripts/python.exe`)。不要拿 `load_workspace_dependencies` 返回的随包 Python 试 `import rasterio`:那套解释器有 numpy/Pillow,但没有 GDAL/rasterio 绑定,`rio cogeo` 直接起不来。Windows 没有系统 GDAL 时装 conda-forge(`conda install -c conda-forge gdal rio-cogeo`)或跑官方镜像。`uvicorn` 与 docker 起的 TiTiler 都是常驻服务,必须 `run_in_background`,`job_output` 读到 `Uvicorn running on http://127.0.0.1:8000` 再发请求,收尾 `job_kill`;起服务前先 `curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8000/` 探端口。
5
+ - **先探测版本**:`rio cogeo --version` 应为 7.0.4,`python -c "import rasterio; print(rasterio.__version__, rasterio.__gdal_version__)"` 一次确认绑定与底层 GDAL 都在,`python -c "import titiler.core, stac_fastapi.api as m; print(titiler.core.__version__, m.__version__)"` 对 2.4.0 与 7.1.1。`pip install titiler` 装出来是停在 0.25.0 的旧元包、入口完全不同,看到这个版本号就卸掉改装 `titiler.application==2.4.0`;正文要求 Python >= 3.11,`python -V` 低于就先换解释器。
6
+ - **验证产物**:COG 以 `rio cogeo validate output_cog.tif` 的返回内容为准(要 valid),再 `rio cogeo info output_cog.tif` 看 overviews 与 blocksize。服务用 `curl -s -o tile.png -w '%{http_code} %{content_type} %{size_download}\n'` 打 `/cog/tiles/WebMercatorQuad/8/210/98.png?url=...`,必须 200 + `image/png` + 非零字节,再用 `read_image` 看瓦片不是全黑或全透明(bidx 与 rescale 错位就长这样)。对象存储的 Range 能力单独验:`curl -s -r 0-1023 -o /dev/null -w '%{http_code}' <cog-url>` 要 206,回 200 说明 CDN 忽略了 Range,后续 416 与出图慢都从这里来。
7
+ - **风险与权限**:对象存储凭据只放环境变量(`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` 由外部注入,命令里只引用变量名),不写进脚本、不贴进汇报;pgstac 迁移要超级用户且会改库结构,连生产库前用 `ask_user_question` 确认。对外暴露 8000/8080、把 COG 传到第三方桶、发布别人的影像之前确认许可,STAC 只描述数据、不改变版权;`cogeo-mosaic create` 会覆盖同名 `mosaic.json`,先换名输出。
8
+ - **常见失败**:416 是文件没按 tile 组织或被截断,回 `rio cogeo validate` 重转;瓦片全黑先查 `bidx` 顺序与 `rescale`,单波段没拉伸也会全白;403 是服务进程没拿到桶凭据,改用预签名 URL 或配 IAM;`/stac/tiles` 400 多为 `url` 没做 URL 编码或 `assets` 键名与 Item 不符,先 `curl` 打开 Item JSON 核对。
@@ -1,8 +1,8 @@
1
1
  ## DeepSeek Harness 使用建议
2
2
 
3
- - **加载与引用**:单文件技能,无 reference;命令骨架与常用工具参数看「核心命令」,DEM→河网→流域的完整流程看「典型工作流」,报错对照看「常见问题」。前后处理(重投影、栅格裁剪、格式转换)用 `skill` 加载 `gdal`,点云格式转换加载 `pdal`,交叉验证结果加载 `grass-gis`。
3
+ - **加载与引用**:单文件技能,无 reference;命令骨架与常用工具参数看「核心命令」,DEM→河网→流域的完整流程看「典型工作流」,报错对照看「常见问题」,完整工具清单按正文给的「工具索引」链接查。前后处理(重投影、栅格裁剪、格式转换)用 `skill` 加载 `gdal`,点云格式转换加载 `pdal`,交叉验证结果加载 `grass-gis`。
4
4
  - **执行环境**:`whitebox_tools` 二进制命令走 `ops_bash`(Windows 是 MSYS bash,写 `/d/tools/WBT/whitebox_tools.exe` 并整体加引号);正文里的 `cd /opt/WBT` 是 Linux 路径,Windows 下先 `pwsh` 里确认解压目录(`Get-ChildItem C:\Tools\WBT`)再用绝对路径调用。`python build.py` 源码编译要 Rust 工具链且耗时数分钟,必须用后台作业跑(`run_in_background` + `job_output` 看进度);`pip install whitebox` 首次调用会联网下载二进制,离线环境要手动放置 WBT 目录。
5
- - **先探测版本**:核心库正文按 2.4.0 编写(conda-forge 的 `whitebox_tools` 同为 2.4.0),PyPI 前端 `whitebox` 是 2.3.6,两者版本号不一致属正常。先跑 `whitebox_tools --version` 拿二进制版本,再跑 `python -c "import whitebox; print(whitebox.__version__)"` 拿封装版本;工具能力以二进制为准,回答里要说明按哪个版本写。上游 README 已标 legacy、新开发转向 `whitebox_next_gen`,但 2.4.0 仍是当前稳定版,不要把未发布的新仓库当依据。
5
+ - **先探测版本**:核心库正文按 2.4.0 编写(conda-forge 的 `whitebox_tools` 同为 2.4.0),PyPI 前端 `whitebox` 是 2.3.6,两者版本号不一致属正常。先跑 `whitebox_tools --version` 拿二进制版本,再跑 `python -c "import whitebox; print(whitebox.__version__)"` 拿封装版本;工具能力以二进制为准,回答里要说明按哪个版本写。查工具与参数用正文那组封装方法,不要猜:`wbt.list_tools()`(可按关键词过滤)、`wbt.tool_help("Slope")`、`wbt.tool_parameters("Slope")`、`wbt.version()`;CLI 侧对应 `--listtools`、`--toolhelp`、`--toolparameters`、`--toolbox`、`--viewcode`(在浏览器打开该工具源码页,远程会话里慎用)。
6
6
  - **验证产物**:退出码 0 不算完成。先 `gdalinfo -json accum.tif` 看极值:流量累积的最大值应与流域面积/像元数同量级,若全是 1 说明 DEM 未决口或单位不一致;坡度在 0–90 度、坡向在 0–360;再 `ogrinfo -so streams.shp` 核对河网要素数与 CRS。渲染或阴影产物(`Hillshade`、`LidarHillshade`)用 `read_image` 真看一眼是否通体灰或空白。多步水文流水线用 `todo_write` 列「探测 → 决口 → 流向/累积 → 提河网 → 流域」并逐项核对中间文件。
7
- - **风险与权限**:`--wd` 之后的相对路径与 `--output=` 指向已有文件会直接覆盖,跑批量前先备份或换输出名,并用 `ask_user_question` 让用户在「换名输出 / 覆盖 / 先备份」之间选;下载二进制、源码编译装 Rust、改动 PATH 前也要先征得同意。大 DEM 内存占用高,先 `Clip` 到研究区或分块处理;`--toolparameters` 输出的 JSON 先写文件再 `read`/`grep`,不要整段刷进上下文。
8
- - **常见失败**:`whitebox_tools: command not found` 是目录没进 PATH,`cd` 到 WBT 目录或写绝对路径(Windows 记得 `.exe`);跑完既无输出也无报错,几乎都是相对路径没对上 `--wd`,改用绝对路径重跑一次;`--run` 提示工具不存在是工具名大小写不对(必须是 `FlowAccumulationFullWorkflow` 这种 CamelCase),用 `--listtools` 确认真名;参数被忽略是照抄了别的工具的参数名,用 `--toolparameters=<Tool>` 取真实定义。
7
+ - **风险与权限**:`--wd` 之后的相对路径与 `--output=` 指向已有文件会直接覆盖,跑批量前先备份或换输出名,并用 `ask_user_question` 让用户在「换名输出 / 覆盖 / 先备份」之间选;下载二进制、源码编译装 Rust、改动 PATH 前也要先征得同意。大 DEM 内存占用高,先 `Clip` 到研究区或分块处理;`--toolparameters` 或 `wbt.tool_parameters()` 的 JSON 先写文件再 `read`/`grep`,不要整段刷进上下文。
8
+ - **常见失败**:`whitebox_tools: command not found` 是目录没进 PATH,`cd` 到 WBT 目录或写绝对路径(Windows 记得 `.exe`);跑完既无输出也无报错,几乎都是相对路径没对上 `--wd`,改用绝对路径重跑一次;CLI 的 `--run` 与 Python 便捷方法命名不同:CLI 用 CamelCase(`FillDepressions`),`wbt` 便捷方法是 snake_case(`wbt.fill_depressions()`),`wbt.run_tool` 两种都接受但参数仍是 `--flag=value` 列表;工具名不存在先用 `wbt.list_tools()` 或 `--listtools` 确认真名;参数被忽略是照抄了别的工具的参数名,用 `wbt.tool_parameters()` / `--toolparameters` 取真实定义。
@@ -427,6 +427,7 @@ map.addControl(overlay);
427
427
 
428
428
  ## 相关技能
429
429
 
430
+ - **maplibre-gl-js** — 开源免 token 的矢量瓦片底图,`MapboxOverlay` 的默认搭档:[../maplibre-gl-js/SKILL.md](../maplibre-gl-js/SKILL.md)
430
431
  - **mapbox-gl-js** — 矢量瓦片底图与 Style Spec,deck.gl 的常见底图搭档:[../mapbox-gl-js/SKILL.md](../mapbox-gl-js/SKILL.md)
431
432
  - **openlayers** — 开源 2D WebGIS 库,投影、MVT 与高级交互:[../openlayers/SKILL.md](../openlayers/SKILL.md)
432
433
  - **leaflet** — 轻量 2D 瓦片地图,适合中小数据量与简单场景:[../leaflet/SKILL.md](../leaflet/SKILL.md)
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: duckdb-spatial
3
- description: "Use when doing spatial analysis inside a DuckDB database or SQL pipeline — INSTALL spatial / LOAD spatial, ST_Read over Shapefile/GeoPackage/GeoJSON, ST_Point/ST_GeomFromText, ST_Intersects/ST_Contains/ST_Buffer joins, ST_Area_Spheroid, ST_AsMVT tiles, DuckDB-WASM in the browser; also for 'Extension spatial is not installed' or spatial function does not exist, GEOMETRY vs WKB_BLOB friction, and exporting query results to GeoParquet. DuckDB 2.0 built-in spatial extension."
3
+ description: "Use when doing spatial analysis inside a DuckDB database or SQL pipeline — INSTALL spatial / LOAD spatial, ST_Read over Shapefile/GeoPackage/GeoJSON, ST_Point/ST_GeomFromText, ST_Intersects/ST_Contains/ST_Buffer joins, ST_Area_Spheroid, ST_AsMVT tiles, DuckDB-WASM; also for 'Extension spatial is not installed' or spatial function does not exist, GEOMETRY vs WKB_BLOB friction, CRS type modifiers, and exporting query results to GeoParquet. GEOMETRY became a built-in type in DuckDB 1.5."
4
4
  license: MIT
5
5
  metadata:
6
6
  category: gis
@@ -13,15 +13,17 @@ metadata:
13
13
  >
14
14
  > **函数参考:** <https://duckdb.org/docs/stable/core_extensions/spatial/functions>
15
15
  >
16
+ > **GEOMETRY 类型:** <https://duckdb.org/docs/stable/sql/data_types/geometry>
17
+ >
16
18
  > **最新版本:** DuckDB 2.0.0(截至 2026-11,[PyPI](https://pypi.org/project/duckdb/) / [GitHub Releases](https://github.com/duckdb/duckdb/releases))
17
19
  >
18
- > **扩展分发:** 随 DuckDB 版本自动匹配,INSTALL spatial 从 extensions.duckdb.org 拉取(无独立版本号)
20
+ > **扩展分发:** 随 DuckDB 版本自动匹配,INSTALL spatial 从 extensions.duckdb.org 拉取(无独立版本号);GEOMETRY 类型自 DuckDB 1.5 起内置,空间函数仍由 spatial 扩展提供
19
21
  >
20
22
  > **许可证:** MIT
21
23
 
22
24
  ## 概述
23
25
 
24
- DuckDB Spatial 是 DuckDB 官方的核心扩展,把列式分析数据库变成可读写地理数据的空间分析工具。它基于 OGC Simple Features 模型增加 GEOMETRY 类型,底层用 GEOS 做拓扑运算、用 PROJ 做坐标转换、用 GDAL 读文件。
26
+ DuckDB Spatial 是 DuckDB 官方的核心扩展(core extension),把列式分析数据库变成可读写地理数据的空间分析工具。它按 OGC Simple Features 模型提供空间函数,底层用 GEOS 做拓扑运算、用 PROJ 做坐标转换、用 GDAL 读文件;GEOMETRY 数据类型自 DuckDB 1.5 起已是内置类型,但**绝大多数空间函数(ST_Area、ST_Buffer、ST_Intersects 等)仍然装在 spatial 扩展里**,装扩展这一步不能省。
25
27
 
26
28
  - **零服务依赖**:进程内运行,扩展按需安装,无需 PostGIS 或服务器
27
29
  - **轻量几何类型**:POINT_2D / LINESTRING_2D / POLYGON_2D / BOX_2D 有原生函数重载,比通用 GEOMETRY 路径快
@@ -29,8 +31,9 @@ DuckDB Spatial 是 DuckDB 官方的核心扩展,把列式分析数据库变成
29
31
  - **SQL 即分析**:空间谓词、聚合(ST_Union_Agg、ST_Extent_Agg)、瓦片编码(ST_AsMVT)
30
32
  - **与 Parquet/CSV/JSON 同库联查**:空间表可直接 JOIN 普通表,无须导入导出
31
33
  - **WASM 可用**:同一扩展编译为 WebAssembly,GeoLibre 与 DuckDB-WASM 前端都靠它
34
+ - **内建与扩展分层**:内置的只有 ST_GeomFromWKB、ST_AsWKB、ST_AsWKT(别名 ST_AsText)、ST_Intersects_Extent(别名 `&&`)、ST_CRS、ST_SetCRS 这少数几个;其余 ST_* 函数要 LOAD spatial 才有
32
35
 
33
- 扩展自带 GEOS/PROJ/GDAL 静态链接版本,机器上不需要另外安装 GDAL。
36
+ 官方发布的扩展二进制(`INSTALL spatial` 拉的那种)已经把 GEOS、PROJ、GDAL 等依赖静态链接进扩展,机器上不需要另外安装 GDAL;只有从源码自建时才需要系统里备好这些库(`vcpkg.json` 里声明了 geos、proj、gdal>=3.12.4 等)。
34
37
 
35
38
  ## 环境准备
36
39
 
@@ -51,18 +54,22 @@ conda install -c conda-forge duckdb
51
54
  ### 安装 spatial 扩展
52
55
 
53
56
  ```sql
57
+ -- DuckDB 2.0 起可用一条语句完成安装 + 加载
58
+ INSTALL AND LOAD spatial;
59
+
60
+ -- 等价的分两步写法(旧版本也支持)
54
61
  INSTALL spatial;
55
62
  LOAD spatial;
56
63
  ```
57
64
 
58
- INSTALL 会把扩展写入用户目录(~/.duckdb/extensions/<version>/<platform>/),只需一次;之后每次会话 LOAD spatial 即可。spatial 不属于 autoloadable 扩展,忘记 LOAD 时所有 ST_* 函数都会报"不存在"。
65
+ INSTALL 会把扩展写入用户目录(~/.duckdb/extensions/<version>/<platform>/),只需一次;之后每次会话 LOAD spatial 即可。spatial 不属于 autoloadable 扩展,忘记 LOAD 时空函数都会报"不存在"(内置的 ST_CRS / ST_SetCRS / ST_AsWKT 等除外)。
59
66
 
60
67
  ### 验证
61
68
 
62
69
  ```python
63
70
  import duckdb
64
71
  con = duckdb.connect()
65
- con.execute("INSTALL spatial; LOAD spatial;")
72
+ con.execute("INSTALL AND LOAD spatial;") # 2.0 一条语句;旧版可拆成 INSTALL + LOAD
66
73
  print(con.execute("SELECT duckdb_version()").fetchone())
67
74
  print(con.execute("SELECT ST_AsText(ST_Point(116.39, 39.90))").fetchone())
68
75
  print(con.execute("SELECT extension_version FROM duckdb_extensions() WHERE extension_name='spatial'").fetchone())
@@ -83,7 +90,8 @@ print(con.execute("SELECT duckdb_proj_version()").fetchone())
83
90
  | ST_GeomFromWKB(blob) / ST_AsWKB(geom) | WKB 互转 | GEOMETRY / WKB_BLOB |
84
91
  | ST_MakeEnvelope(minx, miny, maxx, maxy) | 矩形面 | GEOMETRY |
85
92
  | ST_MakeLine(list_of_points) / ST_MakePolygon(ring) | 线/面构造 | GEOMETRY |
86
- | ST_AsText(geom) | 输出 WKT | VARCHAR |
93
+ | ST_AsText(geom) / ST_AsWKT(geom) | 输出 WKT(ST_AsText 是 ST_AsWKT 的别名,两者内置) | VARCHAR |
94
+ | ST_CRS(geom) / ST_SetCRS(geom, crs) | 读取 / 设置几何的 CRS 标识(内置,DuckDB 1.5+) | VARCHAR / GEOMETRY |
87
95
 
88
96
  ```sql
89
97
  SELECT ST_AsText(ST_Point(116.39, 39.90)) AS pt,
@@ -91,7 +99,14 @@ SELECT ST_AsText(ST_Point(116.39, 39.90)) AS pt,
91
99
  ST_AsWKB('POINT(1 2)'::GEOMETRY)::BLOB AS wkb;
92
100
  ```
93
101
 
94
- 字符串可以直接带类型转换写成 'POINT(...)'::GEOMETRY,这是最短路径。DuckDB Spatial 的 GEOMETRY 不保存 SRID,因此没有 ST_SetSRID 这类函数。
102
+ 字符串可以直接带类型转换写成 'POINT(...)'::GEOMETRY,这是最短路径。CRS 在 DuckDB 里是**类型的一部分**而不是行内隐藏属性:`GEOMETRY('OGC:CRS84')`、`GEOMETRY('EPSG:4326')` 声明列的 CRS,用 ST_CRS / ST_SetCRS 读写,没有 PostGIS 那种 ST_SRID / ST_SetSRID 函数名。
103
+
104
+ ```sql
105
+ SELECT ST_CRS('POINT(1 2)'::GEOMETRY('OGC:CRS84')); -- OGC:CRS84
106
+ SELECT typeof(ST_SetCRS('POINT(1 2)'::GEOMETRY, 'OGC:CRS84')); -- GEOMETRY('OGC:CRS84')
107
+ ```
108
+
109
+ CRS 标识必须已在系统目录注册:内置只注册少数常见 CRS(如 OGC:CRS84、OGC:CRS83),加载 spatial 后才会注册 EPSG 全量 7000+ 套,可用 `SELECT * FROM duckdb_coordinate_systems();` 查看。带 CRS 的 GEOMETRY 列要求存储版本 v1.5.0 及以上(DuckDB 2.0 的默认存储版本已满足)。
95
110
 
96
111
  ### 空间关系谓词
97
112
 
@@ -226,7 +241,7 @@ SELECT * FROM 'data/roads.shp' LIMIT 5;
226
241
  import duckdb
227
242
 
228
243
  con = duckdb.connect("analysis.duckdb")
229
- con.execute("INSTALL spatial; LOAD spatial;")
244
+ con.execute("INSTALL AND LOAD spatial;") # 2.0 一条语句;旧版可拆成 INSTALL + LOAD
230
245
 
231
246
  # 1) 读入并落到持久表(避免每次查询重复解析 Shapefile)
232
247
  con.execute("CREATE OR REPLACE TABLE roads AS SELECT * FROM ST_Read('data/roads.shp');")
@@ -282,7 +297,7 @@ print(con.execute("SELECT * FROM road_length_by_district LIMIT 10").fetchall())
282
297
  import duckdb, geopandas as gpd
283
298
 
284
299
  con = duckdb.connect()
285
- con.execute("INSTALL spatial; LOAD spatial;")
300
+ con.execute("INSTALL AND LOAD spatial;") # 2.0 一条语句;旧版可拆成 INSTALL + LOAD
286
301
 
287
302
  # 查询结果直接转 DataFrame
288
303
  rows = con.execute("SELECT name, ST_AsText(geom) FROM ST_Read('data/cities.shp')").fetchdf()
@@ -320,7 +335,7 @@ SELECT ST_AsMVT(tile, 'cities', 4096, 'geom') FROM tile;
320
335
  ## 性能优化
321
336
 
322
337
  1. **落表再查**:对同一文件重复 ST_Read 会反复走 GDAL 解析,先 CREATE TABLE AS 物化。GDAL 是单线程的,ST_Read 无法并行。
323
- 2. **没有空间索引,先做包围盒粗筛**:DuckDB Spatial 不提供 R-Tree 索引,join 前用 ST_Intersects_Extent 缩小候选集,再用 ST_Intersects 精确判断。
338
+ 2. **先做包围盒粗筛,再看要不要空间索引**:join 前用 ST_Intersects_Extent(或等价的 `&&` 运算符)缩小候选集,再用 ST_Intersects 精确判断 —— 这一步在任何版本都有效,而且 `&&` 在 2.0 里还能吃到 GEOMETRY 列的 row-group 统计信息。DuckDB 2.0 的索引文档写明「spatial 扩展可为空间列提供 R-tree」,`CREATE INDEX` 也支持可选的 index type;但具体能否建、建了是否被选中,取决于扩展版本与查询形态,落地前先 `EXPLAIN ANALYZE` 实测对比,别假设它一定生效。
324
339
  3. **优先用轻量类型**:能落成 POINT_2D / POLYGON_2D 的列走原生实现,必要时用 ST_Force2D 去掉 Z/M。
325
340
  4. **面积/长度单位要有依据**:经纬度下 ST_Area 的单位是平方度,应改用 ST_Area_Spheroid 或先投影。
326
341
  5. **投影一次即可**:ST_Transform 是 CPU 热点,放在建表阶段,不要写在 WHERE 里逐行算。
@@ -337,14 +352,19 @@ SELECT ST_AsMVT(tile, 'cities', 4096, 'geom') FROM tile;
337
352
  | ST_Transform 报 CRS 解析失败 | 源/目标 CRS 字符串拼错或 PROJ 未识别 | 用 'EPSG:4326' 这类标准写法;SELECT duckdb_proj_version() 确认 PROJ 可用 |
338
353
  | 读 GeoPackage 只拿到第一个图层 | 多图层文件未指定 layer | 用 ST_Read_Meta 先看 layers,再 ST_Read(..., layer := '...') |
339
354
  | Shapefile 中文属性乱码 | DBF 编码与默认 UTF-8 不一致 | 用 ST_ReadSHP(path, encoding := 'GBK'),或在 open_options 里给驱动指定编码 |
340
- | 空间 join 极慢 | 没有空间索引,也没做包围盒粗筛 | 先 ST_Intersects_Extent 粗筛,再 ST_Intersects 精筛 |
355
+ | 空间 join 极慢 | 没做包围盒粗筛,也没利用任何索引 | 先 ST_Intersects_Extent(`&&`)粗筛再 ST_Intersects 精筛;仍慢再试 `CREATE INDEX` 并 `EXPLAIN ANALYZE` 核对是否真的用上 |
341
356
  | 写出的 Parquet 没有 CRS | ST_AsWKB 只写几何,不写 CRS 元数据 | 落盘后用 GeoPandas/GDAL 补写 crs,或用 ogr2ogr 转出 |
342
357
  | ST_ReadOSM 只返回 node/way 原始表 | 该函数不做几何装配 | 需要成品几何时改用 ST_Read 的 OSM 驱动 |
358
+ | Unknown coordinate system / unrecognized coordinate system | CRS 标识未注册:EPSG 全集由 spatial 扩展注册,只装了 DuckDB 没 LOAD spatial 时只剩少数内置 CRS | 先 LOAD spatial 再写 `GEOMETRY('EPSG:4326')`;仍失败则 `SELECT * FROM duckdb_coordinate_systems()` 核对标识,必要时 `SET ignore_unknown_crs = true` 显式丢弃未知 CRS |
359
+ | GEOMETRY columns with coordinate reference system identifiers are not supported in storage versions prior v1.5.0 | 带 CRS 的 GEOMETRY 列要求存储版本 v1.5.0+,旧库文件读不了 | 用 `ATTACH 'file.db' (STORAGE_VERSION 'v1.5.0')` 重建库,或先用 EXPORT DATABASE / IMPORT DATABASE 迁移存储格式 |
360
+ | pip install duckdb 装到 1.x、没有 2.0 的新行为 | DuckDB 2.0 要求 Python 3.11+,3.10 上 pip 只会解析到 1.x | 升级 Python 到 3.11+ 后重装;`python -c "import duckdb; print(duckdb.__version__)"` 确认 |
343
361
 
344
362
  ## AI 使用建议
345
363
 
346
364
  - **先验扩展再写 SQL**:执行前跑 SELECT extension_name, loaded FROM duckdb_extensions() WHERE extension_name='spatial'; 确认 loaded=true;未加载就先 LOAD,不要把"函数不存在"当语法错误去改。
347
- - **版本敏感**:2.0.0 与旧版函数集合有差异(ST_Area_Spheroid、ST_CoverageUnion_Agg 属较新函数)。写示例前用 SELECT function_name FROM duckdb_functions() WHERE function_name LIKE 'ST_%'; 探测实际可用函数。
365
+ - **版本敏感**:2.0.0 与旧版函数集合有差异(ST_Area_Spheroid、ST_CoverageUnion_Agg 属较新函数;GEOMETRY 类型自 1.5 起内置,ST_CRS / ST_SetCRS 也随之内置)。写示例前用 SELECT function_name FROM duckdb_functions() WHERE function_name LIKE 'ST_%'; 探测实际可用函数。
366
+ - **2.0 迁移要先看存储格式**:DuckDB 2.0 默认写 storage version 69,旧版本(如 1.5.x)读不了;跨版本共享库文件前先用 `duckdb my.db -storage-version v1.5.6` 或 `config={"storage_compatibility_version": "v1.5.0"}` 指定存储版本,迁移方法见官方 Migrating to DuckDB 2.0。
367
+ - **CRS 是类型的一部分**:`GEOMETRY('EPSG:4326')` 与无 CRS 的 GEOMETRY 是不同的类型,多数二元空间函数要求两侧 CRS 一致;跨 CRS 先 ST_Transform,不要只靠 SET 全局开关去改轴序。
348
368
  - **大文件不要整读进内存**:优先用 ST_Read 的 spatial_filter_box / layer 参数与 Parquet 列裁剪;反复查询时先落表。
349
369
  - **验证产物**:写完 Parquet/MVT 后回读核对 count、ST_IsValid、ST_GeometryType 分布,以及坐标范围是否落在预期 CRS 内。
350
370
  - **写操作确认**:COPY ... TO、CREATE OR REPLACE TABLE、DROP TABLE 会覆盖文件或表;执行前确认目标路径已被授权覆盖。
@@ -360,4 +380,7 @@ SELECT ST_AsMVT(tile, 'cities', 4096, 'geom') FROM tile;
360
380
  ## 参考资源
361
381
  - 扩展仓库:<https://github.com/duckdb/duckdb-spatial>
362
382
  - 函数总表:<https://duckdb.org/docs/stable/core_extensions/spatial/functions>
383
+ - GEOMETRY 数据类型:<https://duckdb.org/docs/stable/sql/data_types/geometry>
384
+ - 内置几何函数:<https://duckdb.org/docs/stable/sql/functions/geometry>
385
+ - DuckDB 2.0 迁移指南:<https://duckdb.org/docs/stable/operations_manual/migration>
363
386
  - DuckDB 文档:<https://duckdb.org/docs/stable/>
@@ -103,12 +103,12 @@ gdal <command> <subcommand> [options] <inputs>
103
103
 
104
104
  ```bash
105
105
  # 矢量重投影 + 格式转换(等价 ogr2ogr -t_srs ... -f GPKG)
106
- gdal vector reproject --output-crs EPSG:3857 -o out.gpkg in.shp
106
+ gdal vector reproject --output-crs EPSG:3857 in.shp out.gpkg --overwrite
107
107
 
108
108
  # 栅格镶嵌(等价 gdal_merge.py / gdalwarp 多输入)
109
- gdal raster mosaic -o mosaic.tif tile1.tif tile2.tif tile3.tif
109
+ gdal raster mosaic tile1.tif tile2.tif tile3.tif mosaic.tif --overwrite
110
110
 
111
- # 数据集体检(3.13+)
111
+ # 数据集体检(3.13+,有错时退出码为 1)
112
112
  gdal dataset check data.gpkg
113
113
  ```
114
114
 
@@ -162,8 +162,8 @@ ogr2ogr -t_srs EPSG:3857 output.shp input.shp
162
162
  # 属性过滤
163
163
  ogr2ogr output.shp input.shp -where "area > 1000"
164
164
 
165
- # 选择特定字段
166
- ogr2ogr output.shp input.shp -select "id,name,geometry"
165
+ # 选择特定字段(几何默认保留;列表里写 geometry 只在几何被登记为字段名时有效)
166
+ ogr2ogr output.shp input.shp -select "id,name"
167
167
  ```
168
168
 
169
169
  ---
@@ -210,7 +210,7 @@ COG 是带内部金字塔和分块的 GeoTIFF,便于 HTTP Range 按需读取
210
210
  gdal_translate -of COG -co COMPRESS=DEFLATE -co OVERVIEWS=AUTO input.tif output_cog.tif
211
211
 
212
212
  # 3.11+ 新式 CLI 等价写法
213
- gdal raster convert --of COG -o output_cog.tif input.tif
213
+ gdal raster convert --of COG -co COMPRESS=DEFLATE input.tif output_cog.tif --overwrite
214
214
 
215
215
  # 校验:分块、金字塔、是否被识别为 COG
216
216
  gdalinfo -json output_cog.tif | grep -E 'COMPRESSION|LAYOUT|BLOCK'
@@ -27,8 +27,8 @@ metadata:
27
27
 
28
28
  GDAL 是地理空间数据处理的事实标准库,由 OSGeo 基金会维护。它提供:
29
29
 
30
- - **200+ 栅格驱动**:GeoTIFF、NetCDF、HDF5、COG、JPEG2000 等
31
- - **100+ 矢量驱动**:Shapefile、GeoJSON、GeoPackage、PostGIS、FlatGeobuf 等
30
+ - **上百个栅格驱动**:GeoTIFF、NetCDF、HDF5、COG、JPEG2000 等(完整清单见 [Raster drivers](https://gdal.org/en/stable/drivers/raster/index.html))
31
+ - **近百个矢量驱动**:Shapefile、GeoJSON、GeoPackage、PostGIS、FlatGeobuf 等(完整清单见 [Vector drivers](https://gdal.org/en/stable/drivers/vector/index.html))
32
32
  - **坐标参考系统**:基于 PROJ 的坐标变换与投影转换
33
33
  - **栅格分析**:重采样、镶嵌、裁剪、波段运算、DEM 分析等
34
34
  - **矢量操作**:空间过滤、属性查询、要素创建与编辑等
@@ -344,6 +344,7 @@ python -c "import json;d=json.load(open('beijing.geolibre.json'));print(len(d.ge
344
344
  ## 相关技能
345
345
 
346
346
  - **duckdb-spatial** — SQL 工作区背后的空间分析引擎:[../duckdb-spatial/SKILL.md](../duckdb-spatial/SKILL.md)
347
+ - **maplibre-gl-js** — GeoLibre 默认的矢量瓦片渲染引擎:[../maplibre-gl-js/SKILL.md](../maplibre-gl-js/SKILL.md)
347
348
  - **openlayers** — 自建 Web 地图前端时的核心库:[../openlayers/SKILL.md](../openlayers/SKILL.md)
348
349
  - **cesiumjs** — GeoLibre 的 3D 球渲染引擎之一:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
349
350
  - **qgis-process** — 桌面 GIS 的另一种无头批处理路径:[../qgis-process/SKILL.md](../qgis-process/SKILL.md)
@@ -129,8 +129,8 @@ python manage.py runserver 0.0.0.0:8000
129
129
  ### 验证
130
130
 
131
131
  ```bash
132
- # 版本
133
- curl -s http://localhost/version.txt
132
+ # 版本:容器内读 Django 应用版本(Docker 部署最可靠)
133
+ docker compose exec django python -c "import geonode; print(geonode.get_version())"
134
134
 
135
135
  # API 是否可用(公开资源无需认证)
136
136
  curl -s "http://localhost/api/v2/resources?page_size=1" | head -c 300
@@ -318,7 +318,7 @@ print(requests.get(wms, params={
318
318
 
319
319
  ## AI 使用建议
320
320
 
321
- - **先确认版本与入口**:`curl -s http://localhost/version.txt` 确认 5.1.1;Docker 部署优先用 `docker compose exec` 而不是宿主机的 `manage.py`,避免环境错位。
321
+ - **先确认版本与入口**:Docker 部署用 `docker compose exec django python -c "import geonode; print(geonode.get_version())"` 确认 5.1.1;优先用 `docker compose exec` 而不是宿主机的 `manage.py`,避免环境错位。
322
322
  - **API 用 `/api/v2/`**:旧 Tastypie 的 `/api/*` 仍在,但新代码一律用 `/api/v2/resources` 与 `/api/v2/uploads/upload`;两者返回结构不同,不要混用。
323
323
  - **认证信息不要进日志**:用环境变量传 `Authorization`,示例里出现的 `<base64>` 必须替换,不要把真实凭据写进脚本或报告。
324
324
  - **验证产物**:上传后回读资源详情,核对 `subtype`、`alternate`、`links[]` 与 `download_url`,再对 WMS 发一次 `GetMap`;只看 201 响应不构成"发布成功"。
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: geopandas
3
- description: "Use when doing vector spatial analysis in Python — gpd.read_file/to_file via pyogrio (GPKG, Shapefile, GeoParquet), sjoin/sjoin_nearest, overlay, clip, dissolve, to_crs vs set_crs, gdf.plot choropleth; also for CRSError from a missing PROJ data dir, area/distance computed in degrees, or GeoDataFrame geometry-column conflicts. GeoPandas 1.2.0 extends pandas DataFrames with geometry columns."
3
+ description: "Use when doing vector spatial analysis in Python — gpd.read_file/to_file via pyogrio (GPKG, Shapefile, GeoParquet 2.0), sjoin/sjoin_nearest, overlay, clip, dissolve, make_grid, to_crs vs set_crs, gdf.plot choropleth; also for CRSError from a missing PROJ data dir, area/distance computed in degrees, or GeoDataFrame geometry-column conflicts. GeoPandas 1.2.0 extends pandas DataFrames with geometry columns."
4
4
  license: MIT
5
5
  metadata:
6
6
  category: gis
@@ -13,7 +13,7 @@ metadata:
13
13
  >
14
14
  > **官网:** <https://geopandas.org>
15
15
  >
16
- > **最新版本:** 1.2.0(截至 2026-11,PyPI)
16
+ > **最新版本:** 1.2.0(截至 2026-11,[PyPI](https://pypi.org/project/geopandas/) / [Release notes](https://geopandas.org/en/stable/docs/changelog.html))
17
17
  >
18
18
  > **许可证:** BSD-3-Clause
19
19
 
@@ -34,7 +34,8 @@ pip install geopandas
34
34
  # 可选依赖(绘图/交互地图/分类/Parquet 等)
35
35
  pip install "geopandas[all]"
36
36
 
37
- # 验证
37
+ # 验证(版本 + 默认 IO 引擎)
38
+ python -c "import geopandas as gpd; print(gpd.__version__, gpd.options.io_engine)"
38
39
  python -c "import geopandas as gpd; gpd.show_versions()"
39
40
  ```
40
41
 
@@ -44,11 +45,14 @@ python -c "import geopandas as gpd; gpd.show_versions()"
44
45
 
45
46
  | 核心依赖 | 最低版本 | 用途 |
46
47
  |----------|---------|------|
47
- | `pandas` | >= 2.2.0 | DataFrame 基类 |
48
+ | `pandas` | >= 2.2.0 | DataFrame 基类(1.2) |
48
49
  | `shapely` | >= 2.1.0 | 几何对象与运算 (GEOS) |
49
50
  | `pyproj` | >= 3.7.0 | CRS 处理与坐标变换 |
50
- | `pyogrio` | >= 0.8 | 默认文件 IO 引擎 (GDAL/OGR) |
51
+ | `pyogrio` | >= 0.8 | 默认文件 IO 引擎 (GDAL/OGR);`read_file_info` 与 `fid_as_index` 也由它提供 |
51
52
  | `numpy` | >= 2 | 数组运算 |
53
+ | `packaging` | — | 版本解析 |
54
+
55
+ 以上为 1.2.0 `pyproject.toml` 的实测下限。
52
56
 
53
57
  | 可选依赖 | 用途 |
54
58
  |----------|------|
@@ -60,6 +64,7 @@ python -c "import geopandas as gpd; gpd.show_versions()"
60
64
  | `geopy` | 地理编码 |
61
65
  | `SQLAlchemy` >= 2.0 + `GeoAlchemy2` | PostGIS 读写 |
62
66
  | `xyzservices` | 瓦片底图服务 |
67
+ | `contextily` | `plot(tiles=...)` 叠加在线底图(1.2 新增用法) |
63
68
 
64
69
  ## 全局配置
65
70
 
@@ -80,9 +85,14 @@ gpd.options.io_engine # None|"pyogrio"|"fiona"
80
85
  ```python
81
86
  gpd.read_file(filename, bbox=None, mask=None, columns=None, rows=None, engine=None, **kwargs)
82
87
  gdf.to_file(filename, driver=None, schema=None, index=None, **kwargs)
83
- gpd.list_layers(filename) # → DataFrame (layer_name, geometry_type)
88
+ gpd.list_layers(filename) # → DataFrame (layer_name, geometry_type)
89
+ gpd.read_file_info(filename, layer=None) # → dict(1.2 新增,pyogrio.read_info 的别名)
84
90
  ```
85
91
 
92
+ - `engine="pyogrio"`(默认,装了就用)或 `"fiona"`;可用 `gpd.options.io_engine` 全局指定
93
+ - `read_file(..., fid_as_index=True)`(pyogrio)把文件内的 feature id 用作索引 —— GeoPackage 的 fid 默认不在列里
94
+ - `read_file(..., use_arrow=True)`(pyogrio + pyarrow)走 Arrow 通道,官方称读速可提升 2–4 倍
95
+
86
96
  **支持的文件格式(扩展名 → 驱动):**
87
97
 
88
98
  | 扩展名 | 驱动 |
@@ -110,7 +120,9 @@ gdf.to_parquet(path, compression="snappy", geometry_encoding="WKB",
110
120
  gdf.to_feather(path, compression=None, schema_version=None, **kwargs)
111
121
  ```
112
122
 
113
- GeoParquet 规范版本:`"1.0.0"`, `"1.1.0"` 等。几何编码:`"WKB"`(默认)、`"geoarrow"`。
123
+ GeoParquet 规范版本:`schema_version` 可取 `"0.1.0"`、`"0.4.0"`、`"1.0.0"`、`"1.1.0"`、`"2.0.0"`,不传时默认写最新的稳定版 1.1.0。几何编码:`"WKB"`(默认)、`"geoarrow"`(GeoParquet 1.1 起,实验性)。
124
+
125
+ 1.2 的变化:`read_parquet` / `to_parquet` 支持(当时定义中的)GeoParquet 2.0 规范;`read_parquet` 可直接读 HTTP/HTTPS 上的文件(`storage_options` 透传给 urllib);`to_parquet` 写入的 `attrs` 会在 `read_parquet` 时读回;`write_covering_bbox=True` 写出的 `bbox` 列可让后续 `read_parquet(bbox=...)` 做过滤读取。
114
126
 
115
127
  ### Arrow (GeoArrow)
116
128
 
@@ -175,7 +187,7 @@ gpd.overlay(df1, df2, how="intersection", keep_geom_type=None, make_valid=True)
175
187
  gpd.clip(gdf, mask, keep_geom_type=False, sort=False)
176
188
  ```
177
189
 
178
- - `mask`: GeoDataFrame、GeoSeries、(Multi)Polygon 或 `(minx, miny, maxx, maxy)` 元组
190
+ - `mask`: GeoDataFrame、GeoSeries、(Multi)Polygon 或 `(minx, miny, maxx, maxy)` 元组;传入四元素列表时走更快的矩形裁剪(`clip_by_rect()`),结果不保证拓扑有效,边角情形可能与多边形裁剪略有差异
179
191
 
180
192
  ### 地理编码
181
193
 
@@ -186,6 +198,25 @@ gpd.tools.reverse_geocode(points, provider=None, **kwargs) # → GeoDataFrame
186
198
 
187
199
  需要 `geopy`。默认 provider: `"photon"`。返回含 `geometry` 和 `address` 列的 GeoDataFrame。
188
200
 
201
+ ### 网格与聚合
202
+
203
+ ```python
204
+ # 1.2 新增:按输入范围生成正方形或蜂窝网格(返回 GeoSeries)
205
+ gpd.make_grid(input_geometry, cell_size=1000, grid_type="square",
206
+ feature_type="polygons", offset=None, intersect=True, flat_topped=False)
207
+ gs.make_grid(...) # GeoSeries 上的同名方法
208
+
209
+ # 1.2 起 GeoSeries 的二元集合运算新增 grid_size(精度栅格,顶点吸附到该格网)
210
+ gs_left.union(gs_right, grid_size=1e-6)
211
+ gs_left.intersection(gs_right, grid_size=1e-6)
212
+ gs_left.difference(gs_right, grid_size=1e-6)
213
+ gs_left.symmetric_difference(gs_right, grid_size=1e-6)
214
+ ```
215
+
216
+ - `grid_type`:`"square"` 或 `"hexagon"`
217
+ - `feature_type`:`"polygons"`(面)、`"centers"`(点)、`"corners"`(顶点)
218
+ - `intersect=True` 只保留与输入几何相交的网格单元;要整块外接矩形填满网格传 `False`
219
+
189
220
  ### 其他工具
190
221
 
191
222
  ```python
@@ -362,6 +393,9 @@ m = gdf.explore(column="population", cmap="viridis",
362
393
  | `buffer(resolution=...)` 出现弃用警告 | 1.2 起 `resolution` 被弃用,向 shapely 命名惯例对齐 | 改用 `quad_segs` 参数 |
363
394
  | `DriverError` 无法写入 | 驱动不支持或文件被占用 | 检查驱动名拼写、关闭已打开的文件 |
364
395
  | `align=True` 导致意外 NaN | 二元操作默认按索引对齐 | 传入 `align=False` 或重置索引 |
396
+ | `AttributeError: module 'geopandas' has no attribute 'make_grid'` / `read_file_info` | 装的是 1.2 之前的版本(`make_grid`、`read_file_info` 均为 1.2 新增) | `python -c "import geopandas; print(geopandas.__version__)"` 确认,升级到 1.2.0+ |
397
+ | `CRSError: Invalid projection` / PROJ 数据目录缺失 | pyproj 自带 PROJ data 未生效,或混用了 conda/pip 两套环境 | `pyproj.datadir.get_data_dir()` 查目录;重装 pyproj/pyogrio 或统一用 conda-forge 环境 |
398
+ | `to_parquet` 写了 `schema_version="2.0.0"` 但下游读不了 | GeoParquet 2.0 仍新,部分读者只认 1.0/1.1 | 不传 `schema_version` 用默认 1.1.0,或显式写 `"1.0.0"` 兼容老读者 |
365
399
 
366
400
  ## AI 使用建议
367
401