@dsh-gis/dsh-opengis-skill 0.1.3 → 0.2.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.
- package/CHANGELOG.md +40 -0
- package/README.md +48 -22
- package/THIRD_PARTY_NOTICES.md +9 -0
- package/adaptations/brutile.md +8 -0
- package/adaptations/cesiumjs.md +8 -0
- package/adaptations/common.md +16 -0
- package/adaptations/deck-gl.md +8 -0
- package/adaptations/duckdb-spatial.md +8 -0
- package/adaptations/gdal-api.md +8 -0
- package/adaptations/gdal.md +8 -0
- package/adaptations/geolibre.md +8 -0
- package/adaptations/geometry-api-java.md +8 -0
- package/adaptations/geometry-api-net.md +8 -0
- package/adaptations/geonode.md +8 -0
- package/adaptations/geopandas.md +8 -0
- package/adaptations/geopipe-agent.md +8 -0
- package/adaptations/geoserver-cloud.md +8 -0
- package/adaptations/geoserver-rest-api.md +8 -0
- package/adaptations/geoserver.md +8 -0
- package/adaptations/geotools.md +8 -0
- package/adaptations/grass-gis.md +8 -0
- package/adaptations/jts.md +8 -0
- package/adaptations/kepler-gl.md +8 -0
- package/adaptations/leaflet.md +8 -0
- package/adaptations/mapbox-gl-js.md +8 -0
- package/adaptations/mapserver.md +8 -0
- package/adaptations/mapsui.md +8 -0
- package/adaptations/nettopologysuite.md +8 -0
- package/adaptations/opengis-all.md +8 -0
- package/adaptations/opengis-daf.md +8 -0
- package/adaptations/opengis-utils-for-java.md +8 -0
- package/adaptations/opengis-utils-for-net.md +8 -0
- package/adaptations/openlayers.md +8 -0
- package/adaptations/pdal.md +8 -0
- package/adaptations/postgis.md +8 -0
- package/adaptations/proj.md +8 -0
- package/adaptations/projnet4geoapi.md +8 -0
- package/adaptations/pyqgis.md +8 -0
- package/adaptations/qgis-process.md +8 -0
- package/adaptations/qgis-server.md +8 -0
- package/adaptations/shapely.md +8 -0
- package/adaptations/sharpmap.md +8 -0
- package/adaptations/spatialite.md +8 -0
- package/adaptations/whitebox-tools.md +8 -0
- package/assets/brutile/SKILL.md +289 -0
- package/assets/cesiumjs/SKILL.md +73 -23
- package/assets/deck-gl/SKILL.md +19 -20
- package/assets/duckdb-spatial/SKILL.md +370 -0
- package/assets/gdal/SKILL.md +50 -21
- package/assets/gdal-api/SKILL.md +6 -4
- package/assets/geolibre/SKILL.md +364 -0
- package/assets/geometry-api-java/SKILL.md +5 -6
- package/assets/geometry-api-net/SKILL.md +65 -21
- package/assets/geonode/SKILL.md +347 -0
- package/assets/geopandas/SKILL.md +17 -15
- package/assets/geopipe-agent/SKILL.md +25 -20
- package/assets/geoserver/SKILL.md +6 -4
- package/assets/geoserver-cloud/SKILL.md +14 -15
- package/assets/geoserver-rest-api/SKILL.md +13 -8
- package/assets/geotools/SKILL.md +7 -5
- package/assets/grass-gis/SKILL.md +19 -20
- package/assets/jts/SKILL.md +7 -4
- package/assets/kepler-gl/SKILL.md +313 -0
- package/assets/leaflet/SKILL.md +41 -19
- package/assets/mapbox-gl-js/SKILL.md +18 -19
- package/assets/mapserver/SKILL.md +17 -19
- package/assets/mapsui/SKILL.md +85 -48
- package/assets/nettopologysuite/SKILL.md +91 -20
- package/assets/opengis-all/SKILL.md +78 -270
- package/assets/opengis-all/reference/data-stages.md +262 -4
- package/assets/opengis-daf/SKILL.md +6 -5
- package/assets/opengis-utils-for-java/SKILL.md +52 -39
- package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
- package/assets/opengis-utils-for-net/SKILL.md +105 -39
- package/assets/opengis-utils-for-net/reference/code-patterns.md +11 -11
- package/assets/opengis-utils-for-net/reference/util-classes.md +25 -26
- package/assets/openlayers/SKILL.md +66 -9
- package/assets/pdal/SKILL.md +21 -17
- package/assets/postgis/SKILL.md +61 -11
- package/assets/proj/SKILL.md +28 -30
- package/assets/projnet4geoapi/SKILL.md +299 -0
- package/assets/pyqgis/SKILL.md +28 -20
- package/assets/qgis-process/SKILL.md +71 -22
- package/assets/qgis-server/SKILL.md +20 -20
- package/assets/shapely/SKILL.md +132 -75
- package/assets/sharpmap/SKILL.md +93 -50
- package/assets/spatialite/SKILL.md +365 -0
- package/assets/whitebox-tools/SKILL.md +269 -0
- package/lib/adaptations.d.ts +47 -0
- package/lib/adaptations.js +268 -0
- package/lib/index.d.ts +1 -1
- package/lib/index.js +14 -2
- package/lib/skill-file.js +31 -7
- package/locale/en.json +1 -1
- package/locale/zh.json +1 -1
- package/package.json +12 -2
- package/upstream.json +56 -40
|
@@ -20,7 +20,7 @@ tags:
|
|
|
20
20
|
>
|
|
21
21
|
> **下载:** <https://geoserver.org/release/stable/>
|
|
22
22
|
>
|
|
23
|
-
> **最新版本:** 3.0.2(2026-10-
|
|
23
|
+
> **最新版本:** 3.0.2(2026-10-17 发布,安全修复版,生产应优先升级;[官方下载](https://geoserver.org/release/stable/))
|
|
24
24
|
>
|
|
25
25
|
> **运行环境:** Java 17 或 21;3.0.2 内含 GeoTools 35.2、GeoWebCache 2.0.2
|
|
26
26
|
>
|
|
@@ -205,13 +205,15 @@ curl -u admin:geoserver -XPOST \
|
|
|
205
205
|
| 图层范围空白 | 重新计算 native bounds |
|
|
206
206
|
| WFS-T 403 | Data 规则允许 `w` 权限 |
|
|
207
207
|
| 跨域 | 配置 CORS 过滤器 |
|
|
208
|
+
| 改了 SLD 但预览不变 | 图层被 GeoWebCache 缓存:Tile Caching 里 Truncate 该图层,或给 GetMap 加 `&tiled=false` |
|
|
209
|
+
| 忘记管理员密码 | 数据目录 `security/users.properties` 里恢复,改完重启;GeoServer 3.x 默认改由 security 配置文件管理 |
|
|
210
|
+
| 启动报 `UnsupportedClassVersionError` | JVM 版本低于 17:换成 JDK 17 或 21 再启动 3.0.x 分发包 |
|
|
208
211
|
|
|
209
212
|
---
|
|
210
213
|
|
|
211
|
-
##
|
|
214
|
+
## AI 使用建议
|
|
212
215
|
|
|
213
|
-
-
|
|
214
|
-
- **执行环境**:命令交给 dsh 的 shell 工具(Windows 用 `pwsh`);`wget`/`unzip` 换成 `curl.exe -LO` 与 `Expand-Archive`,`$PWD` 换成 `(Get-Location)`。
|
|
216
|
+
- **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell);`wget`/`unzip` 换成 `curl.exe -LO` 与 `Expand-Archive`,`$PWD` 换成 `(Get-Location)`。
|
|
215
217
|
- **先探测版本**:`curl -s -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json`(无 jq 时管道给 `python -m json.tool`),核对 GeoServer、GeoWebCache 与 JVM;`java -version` 必须是 17 或 21,否则 3.0.2 包直接启动失败。
|
|
216
218
|
- **验证产物**:发布后用 `curl -s -o out.png -w "%{http_code} %{size_download}\n" "http://localhost:8080/geoserver/my_ws/wms?service=WMS&version=1.1.0&request=GetMap&layers=my_ws:poi&srs=EPSG:4326&bbox=...&width=512&height=512&format=image/png"`,要 200 且字节数大于 0;再拉一次 `GetCapabilities` 确认图层已注册,不要只凭 UI 回显。
|
|
217
219
|
- **写后回读**:REST 建 workspace/store/layer 或上传 SLD 后,用同路径 GET 回读;`?recurse=true` 删除后再 GET 应得 404。
|
|
@@ -43,7 +43,7 @@ GeoServer Cloud(GS Cloud):
|
|
|
43
43
|
| 服务 | 镜像 | 用途 |
|
|
44
44
|
|------|------|------|
|
|
45
45
|
| `gateway` | `geoservercloud/geoserver-cloud-gateway` | 网关 |
|
|
46
|
-
| `discovery` | `geoservercloud/geoserver-cloud-discovery`
|
|
46
|
+
| `discovery` | —(3.x 不再发布该镜像) | 服务发现:官方 compose/K8s 改用 `hashicorp/consul`,`geoservercloud/geoserver-cloud-discovery:3.0.2` 在 Docker Hub 已 404 |
|
|
47
47
|
| `config` | `geoservercloud/geoserver-cloud-config` | 配置中心 |
|
|
48
48
|
| `web-ui` | `geoservercloud/geoserver-cloud-webui` | 管理界面 |
|
|
49
49
|
| `rest` | `geoservercloud/geoserver-cloud-rest` | REST API |
|
|
@@ -198,17 +198,6 @@ docker run -e SPRING_PROFILES_ACTIVE=datadir \
|
|
|
198
198
|
|
|
199
199
|
---
|
|
200
200
|
|
|
201
|
-
## 常见问题
|
|
202
|
-
|
|
203
|
-
| 问题 | 解决 |
|
|
204
|
-
|------|------|
|
|
205
|
-
| 配置不同步 | 检查 RabbitMQ 可达 + `GEOSERVER_BUS_ENABLED=true` |
|
|
206
|
-
| Web UI 改了 wms 没生效 | 检查事件订阅 |
|
|
207
|
-
| 启动顺序错乱 | `depends_on` + 健康检查;K8s 用 `initContainers` |
|
|
208
|
-
| OOM | 调整 `-Xmx`,按服务独立资源 |
|
|
209
|
-
| Gateway 502 / 服务不可达 | 检查目标服务健康状态与 Consul 注册(服务名解析:`wms`、`wfs` 等) |
|
|
210
|
-
| 瓦片 404 / 缓存未命中 | 确认 gwc 服务已部署、`GEOSERVER_BASE_PATH` 与请求路径一致,必要时重新 seed |
|
|
211
|
-
|
|
212
201
|
---
|
|
213
202
|
|
|
214
203
|
## 典型工作流
|
|
@@ -247,10 +236,20 @@ kubectl -n gis get deploy | grep wms
|
|
|
247
236
|
kubectl -n gis scale deploy <wms-deployment> --replicas=10
|
|
248
237
|
```
|
|
249
238
|
|
|
250
|
-
##
|
|
239
|
+
## 常见问题
|
|
240
|
+
|
|
241
|
+
| 问题 | 解决 |
|
|
242
|
+
|------|------|
|
|
243
|
+
| 配置不同步 | 检查 RabbitMQ 可达 + `GEOSERVER_BUS_ENABLED=true` |
|
|
244
|
+
| Web UI 改了 wms 没生效 | 检查事件订阅 |
|
|
245
|
+
| 启动顺序错乱 | `depends_on` + 健康检查;K8s 用 `initContainers` |
|
|
246
|
+
| OOM | 调整 `-Xmx`,按服务独立资源 |
|
|
247
|
+
| Gateway 502 / 服务不可达 | 检查目标服务健康状态与 Consul 注册(服务名解析:`wms`、`wfs` 等) |
|
|
248
|
+
| 瓦片 404 / 缓存未命中 | 确认 gwc 服务已部署、`GEOSERVER_BASE_PATH` 与请求路径一致,必要时重新 seed |
|
|
249
|
+
|
|
250
|
+
## AI 使用建议
|
|
251
251
|
|
|
252
|
-
-
|
|
253
|
-
- **执行环境**:命令交给 dsh 的 `pwsh`(Windows 无 `wget`,改 `curl.exe -LO`);先用 `docker version`、`helm version`、`kubectl version --client` 确认工具在 PATH。
|
|
252
|
+
- **执行环境**:命令在终端 / shell 中执行(Windows 无 `wget`,改 `curl.exe -LO`);先用 `docker version`、`helm version`、`kubectl version --client` 确认工具在 PATH。
|
|
254
253
|
- **先探测版本**:`curl.exe -s -u admin:geoserver http://localhost:9090/geoserver/cloud/rest/about/version.json` 读 GeoServer 版本;`curl.exe -s http://localhost:9090/actuator/health` 取 `{"status":"UP"}`(被 profile 关掉时改用 `kubectl -n gis get pods` 判活)。
|
|
255
254
|
- **验证产物**:部署后逐服务探活,再经网关 `.../rest/workspaces.json` 与一次 WMS `GetMap` 走通全链路;`docker compose ps` 显示 Up 不等于 OGC 服务可用。
|
|
256
255
|
- **排障顺序**:502 → 查 Consul 注册与目标服务健康(`kubectl -n gis logs deploy/<wms>`);配置不生效 → 查 RabbitMQ 与 `GEOSERVER_BUS_ENABLED`;瓦片 404 → 查 gwc 是否部署、`GEOSERVER_BASE_PATH` 前缀是否一致。
|
|
@@ -20,7 +20,7 @@ tags:
|
|
|
20
20
|
>
|
|
21
21
|
> **API 参考:** <https://docs.geoserver.org/stable/en/user/rest/api/index.html>
|
|
22
22
|
>
|
|
23
|
-
> **最新版本:** GeoServer 3.0.2(2026-10-
|
|
23
|
+
> **最新版本:** GeoServer 3.0.2(2026-10-17 发布,安全修复版;[官方下载](https://geoserver.org/release/stable/))
|
|
24
24
|
>
|
|
25
25
|
> **许可证:** GPL-2.0
|
|
26
26
|
|
|
@@ -47,14 +47,19 @@ REST API 的典型用途包括:
|
|
|
47
47
|
|
|
48
48
|
所有写操作(POST / PUT / DELETE)均需认证。GeoServer 默认使用 HTTP Basic Auth:
|
|
49
49
|
|
|
50
|
+
推荐用 `-u`,curl 自动生成 Basic 头;需要显式传头时用下面的等价写法(`YWRtaW46Z2Vvc2VydmVy` 是 `admin:geoserver` 的 base64):
|
|
51
|
+
|
|
50
52
|
```bash
|
|
51
|
-
# curl
|
|
52
|
-
curl -u admin:geoserver
|
|
53
|
+
# 方式 1:curl -u(推荐)
|
|
54
|
+
curl -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json
|
|
53
55
|
|
|
54
|
-
#
|
|
55
|
-
Authorization: Basic YWRtaW46Z2Vvc2VydmVy
|
|
56
|
+
# 方式 2:显式 Authorization 头
|
|
57
|
+
curl -H "Authorization: Basic YWRtaW46Z2Vvc2VydmVy" \
|
|
58
|
+
http://localhost:8080/geoserver/rest/about/version.json
|
|
56
59
|
```
|
|
57
60
|
|
|
61
|
+
> 凭据务必用环境变量传入(`curl -u "$GS_USER:$GS_PASS"`),不要写进脚本或提交到仓库。
|
|
62
|
+
|
|
58
63
|
---
|
|
59
64
|
|
|
60
65
|
## API 端点一览
|
|
@@ -354,10 +359,10 @@ await workspaceService.CreateWorkspaceAsync("myws");
|
|
|
354
359
|
|
|
355
360
|
---
|
|
356
361
|
|
|
357
|
-
##
|
|
362
|
+
## AI 使用建议
|
|
358
363
|
|
|
359
|
-
-
|
|
360
|
-
-
|
|
364
|
+
- **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/endpoints.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
|
|
365
|
+
- **执行环境**:示例在终端 / shell 中执行(显式 `curl.exe`,Windows 的 `curl` 是别名、参数不同);`\` 续行在 PowerShell 无效,压成单行;请求体先写成 `body.json`,用 `curl.exe --data "@body.json"` 传,避开各 shell 的引号差异。
|
|
361
366
|
- **先探测版本**:`curl.exe -s -u admin:geoserver http://localhost:8080/geoserver/rest/about/version.json`,确认是 3.0.2 并顺带看到组件版本;返回 401 是凭据/安全规则问题,不是版本问题。
|
|
362
367
|
- **验证产物**:写操作后立刻 GET 回读同一资源(`.../rest/workspaces/myws.json`、`.../rest/layers/myws:roads.json`),再发一次 WMS `GetMap` 取 `image/png` 确认非空图;不要只凭 201 或退出码报告成功。
|
|
363
368
|
- **幂等与坑**:同名资源重复 POST 会报已存在(重跑脚本前先 GET 判断或改 PUT);改了样式记得清 GWC 缓存,否则瓦片还是旧的。
|
package/assets/geotools/SKILL.md
CHANGED
|
@@ -36,7 +36,9 @@ GeoTools 是一个成熟、模块化的开源 Java GIS 工具库,由 OSGeo 基
|
|
|
36
36
|
- **OGC Web 服务**:WMS / WFS / WCS 客户端
|
|
37
37
|
- **几何运算**:基于 JTS Topology Suite 的全套几何计算
|
|
38
38
|
|
|
39
|
-
**环境要求:** JDK
|
|
39
|
+
**环境要求:** GeoTools 34+(当前 35.x)要求 **JDK 17**,35.x 官方构建文档另列出可选 JDK 21;更早分支的历史矩阵为 ≤28 用 JDK 8、29–33 用 JDK 11,具体以官方安装文档为准。
|
|
40
|
+
|
|
41
|
+
> 官方构建要求(实测 <https://docs.geotools.org/stable/userguide/build/install/index.html>):"Java Development Kit 17 (JDK 17)",可选 JDK 21;PR 同时用 JDK 17 与 21 测试。
|
|
40
42
|
|
|
41
43
|
---
|
|
42
44
|
|
|
@@ -386,15 +388,15 @@ store.dispose();
|
|
|
386
388
|
|
|
387
389
|
---
|
|
388
390
|
|
|
389
|
-
##
|
|
391
|
+
## AI 使用建议
|
|
390
392
|
|
|
391
|
-
-
|
|
392
|
-
-
|
|
393
|
+
- **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/raster-rendering.md`、`reference/vector-io.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
|
|
394
|
+
- **执行环境**:命令在终端 / shell 中执行;先 `java -version` 与 `mvn -v` 确认 JDK 17,35.x 在 JDK 8/11 下编译即失败。
|
|
393
395
|
- **先探测版本**:`mvn dependency:tree -Dincludes=org.geotools` 确认解析到 35.2 且未被其他依赖压回旧版;`pom.xml` 里必须有指向 `repo.osgeo.org/repository/release/` 的 `<repository>`。
|
|
394
396
|
- **验证产物**:`mvn -q -DskipTests package` 后跑最小读图层程序(`FileDataStoreFinder` → `getFeatures()` → 打印 count 与 CRS)或 `mvn -q test`;`CRS.decode("EPSG:4326")` 抛异常说明缺 `gt-epsg-hsql`。
|
|
395
397
|
- **常见失败信号**:`getDataStore()` 返回 null 或报找不到工厂,是 SPI 模块没进 classpath;出现 `com.vividsolutions.jts` 是包名没升级(GeoTools 20+ 用 `org.locationtech.jts`)。
|
|
396
398
|
- **安全与权限**:测试别全量加载要素到内存(用 `Query` 限制属性与 bbox);连接串/密码不要回显,对生产库批量写入前先向用户确认。
|
|
397
|
-
- **按需读文件**:本 SKILL
|
|
399
|
+
- **按需读文件**:本 SKILL 较长,先按章节标题定位,再按行区间分段读取,避免整篇占满上下文。
|
|
398
400
|
|
|
399
401
|
## 相关技能
|
|
400
402
|
|
|
@@ -46,9 +46,9 @@ sudo apt update && sudo apt install grass
|
|
|
46
46
|
# Conda / mamba / pixi(conda-forge 提供 Linux、macOS、Windows 64 位包)
|
|
47
47
|
conda install -c conda-forge grass
|
|
48
48
|
|
|
49
|
-
# Docker
|
|
50
|
-
docker pull osgeo/grass
|
|
51
|
-
docker run --rm osgeo/grass grass --version
|
|
49
|
+
# Docker(官方镜像名是 osgeo/grass-gis;标签形如 8.5.0-ubuntu / releasebranch_8_5-ubuntu)
|
|
50
|
+
docker pull osgeo/grass-gis:latest
|
|
51
|
+
docker run --rm osgeo/grass-gis grass --version
|
|
52
52
|
```
|
|
53
53
|
|
|
54
54
|
Windows 可通过 OSGeo4W 安装器安装,之后在 "OSGeo4W Shell" 中使用 `grass` 命令。
|
|
@@ -310,16 +310,14 @@ grass $HOME/grassdata/ndvi_project/PERMANENT --exec sh -c '
|
|
|
310
310
|
| Docker 中结果文件属主为 root | 运行时加 `--user=$(id -u):$(id -g)` 与 `--env HOME=/data/` |
|
|
311
311
|
| `t.*` 报时空数据库错误 | 时空数据库按地图集独立且自动创建;确认在正确地图集内运行并检查 `t.connect -p` 状态 |
|
|
312
312
|
|
|
313
|
-
##
|
|
313
|
+
## AI 使用建议
|
|
314
314
|
|
|
315
|
-
-
|
|
316
|
-
-
|
|
317
|
-
-
|
|
318
|
-
-
|
|
319
|
-
-
|
|
320
|
-
-
|
|
321
|
-
- **Docker 镜像说明:** <https://grass.osgeo.org/download/docker/>
|
|
322
|
-
- **官方示例数据:** <https://grass.osgeo.org/sampledata/north_carolina/nc_basic_spm_grass7.zip>
|
|
315
|
+
- **执行环境**:命令在终端 / shell 中执行(Windows 用 PowerShell)。正文里 `grass ... --exec sh -c '...'` 的多行引用在 PowerShell 下不可靠,改为把模块序列写进 `.py` 脚本(首行 `#!/usr/bin/env python3`),再 `grass --tmp-project EPSG:3857 --exec python3 analysis.py`。
|
|
316
|
+
- **先探测版本**:`grass --version`(应为 8.5.0,LTR 8.4.2)、`grass --tmp-project EPSG:3857 --exec g.region -p`;8.4 之前没有 `grass.tools`,Python 脚本改用 `gs.run_command`。
|
|
317
|
+
- **验证产物**:`--tmp-project` 内的地图最后必须导出——`r.out.gdal input=slope output=/work/slope.tif format=GTiff`,随后 `gdalinfo -json slope.tif` 核对 CRS 与范围;会话内核对用 `g.region -p format=json`、`g.list type=raster`。
|
|
318
|
+
- **区域语义优先**:栅格模块只处理计算区域内的像元,结果范围不对先看 `g.region -p`;重复运行加 `--overwrite`,否则模块报地图已存在并非零退出。
|
|
319
|
+
- **错误识别**:GRASS 模块的失败以 `ERROR:` 开头并返回非零码(如 `Raster map <x> not found`),据此区分地图名、区域为空还是输出已存在问题,不要只读最后一行日志。
|
|
320
|
+
- **安全与权限**:`g.remove`、`--overwrite`、`t.connect` 会改/删地图集数据;`--tmp-project`/`--tmp-mapset` 结束即删除目录,结果必须先导出;启动 Docker 或改文件属主(`--user=$(id -u):$(id -g)`)前先确认写入路径。
|
|
323
321
|
|
|
324
322
|
## 相关技能
|
|
325
323
|
|
|
@@ -328,12 +326,13 @@ grass $HOME/grassdata/ndvi_project/PERMANENT --exec sh -c '
|
|
|
328
326
|
- **geopandas** — Python 矢量数据分析:[../geopandas/SKILL.md](../geopandas/SKILL.md)
|
|
329
327
|
- **pyqgis** — QGIS Python 绑定:[../pyqgis/SKILL.md](../pyqgis/SKILL.md)
|
|
330
328
|
|
|
331
|
-
##
|
|
329
|
+
## 参考资源
|
|
332
330
|
|
|
333
|
-
-
|
|
334
|
-
-
|
|
335
|
-
-
|
|
336
|
-
-
|
|
337
|
-
-
|
|
338
|
-
-
|
|
339
|
-
-
|
|
331
|
+
- **GRASS GIS 源码:** <https://github.com/OSGeo/grass>
|
|
332
|
+
- **官方文档:** <https://grass.osgeo.org/>
|
|
333
|
+
- **模块手册(grass-stable):** <https://grass.osgeo.org/grass-stable/manuals/>
|
|
334
|
+
- **grass 启动器说明:** <https://grass.osgeo.org/grass-stable/manuals/grass.html>
|
|
335
|
+
- **Python 脚本 API:** <https://grass.osgeo.org/grass-stable/manuals/libpython/>
|
|
336
|
+
- **时空框架介绍:** <https://grass.osgeo.org/grass-stable/manuals/temporalintro.html>
|
|
337
|
+
- **Docker 镜像说明:** <https://grass.osgeo.org/download/docker/>
|
|
338
|
+
- **官方示例数据:** <https://grass.osgeo.org/sampledata/north_carolina/nc_basic_spm_grass7.zip>
|
package/assets/jts/SKILL.md
CHANGED
|
@@ -56,7 +56,7 @@ JTS Topology Suite(简称 JTS)是 LocationTech 项目组下的开源 Java
|
|
|
56
56
|
</dependency>
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
如需 GeoJSON 等 I/O
|
|
59
|
+
如需 GeoJSON 等 I/O 支持(注意 groupId 是 `org.locationtech.jts.io`,与 jts-core 的 `org.locationtech.jts` 不同):
|
|
60
60
|
|
|
61
61
|
```xml
|
|
62
62
|
<dependency>
|
|
@@ -66,6 +66,8 @@ JTS Topology Suite(简称 JTS)是 LocationTech 项目组下的开源 Java
|
|
|
66
66
|
</dependency>
|
|
67
67
|
```
|
|
68
68
|
|
|
69
|
+
`jts-io-common` 的 `GeoJsonWriter` 在运行期还依赖 `com.googlecode.json-simple:json-simple`(Maven/Gradle 会自动带入);手工拼 classpath 时漏掉它会在写出 GeoJSON 时抛 `NoClassDefFoundError: org/json/simple/JSONAware`。
|
|
70
|
+
|
|
69
71
|
### Gradle
|
|
70
72
|
|
|
71
73
|
```groovy
|
|
@@ -247,14 +249,15 @@ String geoJson = new GeoJsonWriter().write(buffered);
|
|
|
247
249
|
| 批量空间查询慢 | 用 `STRtree` 建索引;重复关系判断用 `PreparedGeometry`;大量合并用 `UnaryUnionOp` |
|
|
248
250
|
| 多线程复用 Reader/Writer 出错 | `GeometryFactory` 与 `Geometry` 线程安全;`WKTReader` / `WKTWriter` 等非线程安全,每线程独立创建 |
|
|
249
251
|
| 叠加运算抛 TopologyException | 优先用 `OverlayNGRobust.overlay()`,比传统叠加引擎更鲁棒 |
|
|
252
|
+
| 写 GeoJSON 抛 `NoClassDefFoundError: org/json/simple/JSONAware` | 手工 classpath 缺 `json-simple`,用 Maven/Gradle 引入 `jts-io-common` 让其传递依赖生效 |
|
|
250
253
|
| 旧代码升级后 import 报错 | JTS 1.15+ 包名由 `com.vividsolutions.jts` 迁移为 `org.locationtech.jts` |
|
|
251
254
|
|
|
252
255
|
---
|
|
253
256
|
|
|
254
|
-
##
|
|
257
|
+
## AI 使用建议
|
|
255
258
|
|
|
256
|
-
-
|
|
257
|
-
-
|
|
259
|
+
- **本技能的组织**:主文件给高频用法,完整参数表与高级示例在 `reference/geometry-operations.md`,需要时再展开;示例工程与生成的数据写到工作目录,不要改动技能目录本身。
|
|
260
|
+
- **执行环境**:命令在终端 / shell 中执行;JTS 只依赖 `jts-core`,Maven Central 直接可解析,不需要额外仓库,JDK 8+ 即可。
|
|
258
261
|
- **先探测版本**:`mvn dependency:tree -Dincludes=org.locationtech.jts` 确认解析到 1.20.0;同时确认 classpath 里没有遗留的 `com.vividsolutions.jts` 旧包。
|
|
259
262
|
- **验证产物**:`mvn -q test`,或最小 main 做 WKT 往返 + `geom.isValid()` + `buffer(0)` 断言;导出 GeoJSON 后用 `GeoJsonReader` 读回比对坐标数,别只看日志。
|
|
260
263
|
- **失败信号**:`TopologyException` 改用 `OverlayNGRobust.overlay()`;`isValid()` 为 false 先 `GeometryFixer.fix()`;结果为空多半是把坐标写成了 `(lat, lon)`。
|
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kepler-gl
|
|
3
|
+
description: "Use when building React/Redux web apps or Jupyter notebooks for large-scale geospatial visual exploration with Kepler.gl 3.3.0-alpha.16 — @kepler.gl/components KeplerGl, @kepler.gl/actions addDataToMap, @kepler.gl/processors processGeojson/processCsvData, and the Python keplergl widget. Also for fixing blank maps from a missing reducer or wrong getState (react-redux 'Could not find ... in the context of Connect(...)'), Mapbox token basemap errors, and oversized addDataToMap payloads."
|
|
4
|
+
tags:
|
|
5
|
+
- javascript
|
|
6
|
+
- react
|
|
7
|
+
- redux
|
|
8
|
+
- webgl
|
|
9
|
+
- geospatial
|
|
10
|
+
- data-visualization
|
|
11
|
+
- map-layers
|
|
12
|
+
- jupyter
|
|
13
|
+
- python
|
|
14
|
+
- maplibre
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
> **项目地址:** <https://github.com/keplergl/kepler.gl>
|
|
18
|
+
>
|
|
19
|
+
> **官方文档:** <https://docs.kepler.gl/>
|
|
20
|
+
>
|
|
21
|
+
> **npm:** `kepler.gl`(npm `latest` 标签 3.3.0-alpha.16;GitHub Release v3.3.0-alpha.18 尚未回填 `latest`,截至 2026-10)
|
|
22
|
+
>
|
|
23
|
+
> **PyPI:** `keplergl` 0.4.0(Jupyter 小组件,版本节奏落后于前端,截至 2026-10)
|
|
24
|
+
>
|
|
25
|
+
> **许可证:** MIT
|
|
26
|
+
|
|
27
|
+
## 概述
|
|
28
|
+
|
|
29
|
+
Kepler.gl 是 Uber 开源(现由社区维护)的地理数据可视化应用,同时也是可嵌入 React 应用的组件库。它把数据抽象成「字段 + 行」的表格模型,通过图层、过滤器、交互配置渲染基于 MapLibre GL 与 deck.gl 的地图,百万级点位可直接在浏览器中做过场动画与空间聚合。核心是一个 Redux 应用:组件、reducer、action、处理器相互解耦,业务方只需把数据整理成 Kepler.gl 的数据集结构即可。
|
|
30
|
+
|
|
31
|
+
- **数据无关**:CSV、GeoJSON、Pandas DataFrame、GeoPandas GeoDataFrame、Arrow 表统一转为 fields/rows
|
|
32
|
+
- **图层体系**:点、弧线、线、多边形、Hexbin、网格、热力、3D 建筑、H3、S2、瓦片(含 MVT)
|
|
33
|
+
- **交互能力**:过滤器(时间、范围、选择)、tooltip、图层可见性、时间轴动画、分屏对比
|
|
34
|
+
- **配置可序列化**:整张地图的 `mapState` / `visState` / `mapStyle` 可导出 JSON,再通过 `addDataToMap` 还原
|
|
35
|
+
- **双形态**:React 组件库(npm)与 Jupyter 小组件(PyPI),共享同一套数据与配置格式
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 环境准备
|
|
40
|
+
|
|
41
|
+
### 前端(npm)
|
|
42
|
+
|
|
43
|
+
Kepler.gl 3.x 的 peer 依赖由主包 `kepler.gl` 声明:`react` / `react-dom` >= 18.2,`styled-components` ^6.1.0。默认底图使用 MapLibre 与 CARTO 样式,不需要 Mapbox token。
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
# 方式一:整包(含 UMD、全部子包,适合 demo 与不开包优化的项目)
|
|
47
|
+
npm install kepler.gl
|
|
48
|
+
|
|
49
|
+
# 方式二:按需子包(生产项目推荐,体积更小)
|
|
50
|
+
npm install @kepler.gl/components @kepler.gl/actions @kepler.gl/reducers \
|
|
51
|
+
@kepler.gl/processors @kepler.gl/schemas @kepler.gl/styles
|
|
52
|
+
|
|
53
|
+
# 若使用 Mapbox 官方样式(非 CARTO/MapLibre 样式)
|
|
54
|
+
npm install mapbox-gl
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
子包版本必须与主包一致,Kepler.gl 各包之间存在内部耦合,混版会出现难以定位的运行时错误:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm ls kepler.gl @kepler.gl/components @kepler.gl/actions
|
|
61
|
+
python -c "import keplergl; print(keplergl.__version__)"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### 免打包(UMD)
|
|
65
|
+
|
|
66
|
+
```html
|
|
67
|
+
<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@^4/dist/maplibre-gl.css" />
|
|
68
|
+
<script src="https://unpkg.com/kepler.gl/umd/keplergl.min.js"></script>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
UMD 构建的库名为 `KeplerGl`,AMD 加载时同样以 `KeplerGl` 注册;页面可直接通过全局变量获取组件与 action,适合无构建环境的演示页。
|
|
72
|
+
|
|
73
|
+
### Python(Jupyter)
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pip install keplergl==0.4.0
|
|
77
|
+
|
|
78
|
+
# 或使用 conda
|
|
79
|
+
conda install -c conda-forge keplergl
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`keplergl` 0.4.0 要求 Python >= 3.9、JupyterLab >= 4.0 或 Notebook >= 7.0,依赖 `anywidget`、`geopandas`、`pyarrow`、`geoarrow-pandas`。验证:
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
import keplergl
|
|
86
|
+
from keplergl import KeplerGl
|
|
87
|
+
|
|
88
|
+
print(keplergl.__version__) # 0.4.0
|
|
89
|
+
m = KeplerGl(height=300) # 无数据也能创建空地图
|
|
90
|
+
print(type(m).__name__) # KeplerGl
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## 核心 API
|
|
96
|
+
|
|
97
|
+
### 数据模型:dataset 与 fields/rows
|
|
98
|
+
|
|
99
|
+
所有数据最终都归一化为下面两种形态之一,`addDataToMap` 只认这个结构:
|
|
100
|
+
|
|
101
|
+
| 形态 | 结构 | 说明 |
|
|
102
|
+
|------|------|------|
|
|
103
|
+
| 表格 | `{fields: [{name, type, format}], rows: [[...]]}` | CSV / DataFrame / Arrow,行列索引对齐 |
|
|
104
|
+
| GeoJSON | `{type, features}` | 单要素或 FeatureCollection;属性进 fields |
|
|
105
|
+
|
|
106
|
+
`type` 取值包括 `string`、`integer`、`real`、`boolean`、`timestamp`、`date`、`geojson`;经纬度字段需为数值型且列名为 `latitude` / `longitude`(或手动指定图层当前列),`timestamp` 需配 `format`,否则时间轴与时间过滤器不生效。
|
|
107
|
+
|
|
108
|
+
```javascript
|
|
109
|
+
import {processGeojson, processCsvData} from '@kepler.gl/processors';
|
|
110
|
+
|
|
111
|
+
const {fields, rows} = processCsvData(csvText);
|
|
112
|
+
const geo = processGeojson(geojsonObject); // 返回同样含 fields / rows 的对象
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Redux 接入
|
|
116
|
+
|
|
117
|
+
Kepler.gl 不是自治组件,它依赖挂载在 store 的 `keplerGl` 键下的 reducer,以及处理异步任务的 middleware。
|
|
118
|
+
|
|
119
|
+
```javascript
|
|
120
|
+
import {createStore, combineReducers, applyMiddleware, compose} from 'redux';
|
|
121
|
+
import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';
|
|
122
|
+
|
|
123
|
+
const reducers = combineReducers({
|
|
124
|
+
keplerGl: keplerGlReducer,
|
|
125
|
+
// ...其余 reducer
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
const middlewares = enhanceReduxMiddleware([
|
|
129
|
+
// ...其余 middleware
|
|
130
|
+
]);
|
|
131
|
+
|
|
132
|
+
export const store = createStore(reducers, {}, compose(applyMiddleware(...middlewares)));
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
若把 reducer 挂在别的键(例如 `state.maps`),挂载组件时必须同时传入 `getState={state => state.maps}`,否则组件取不到实例状态而渲染空白。
|
|
136
|
+
|
|
137
|
+
### KeplerGl 组件
|
|
138
|
+
|
|
139
|
+
```javascript
|
|
140
|
+
import KeplerGl from '@kepler.gl/components';
|
|
141
|
+
|
|
142
|
+
export default function MapPanel() {
|
|
143
|
+
return (
|
|
144
|
+
<KeplerGl
|
|
145
|
+
id="demo"
|
|
146
|
+
mapboxApiAccessToken="" // 仅 Mapbox 样式需要;CARTO/MapLibre 样式留空
|
|
147
|
+
width={window.innerWidth}
|
|
148
|
+
height={window.innerHeight}
|
|
149
|
+
appName="Traffic Explorer"
|
|
150
|
+
sidePanelWidth={420}
|
|
151
|
+
getState={state => state.keplerGl}
|
|
152
|
+
onViewStateChange={({longitude, latitude, zoom}) => console.log(longitude, latitude, zoom)}
|
|
153
|
+
/>
|
|
154
|
+
);
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
| Prop | 默认值 | 说明 |
|
|
159
|
+
|------|--------|------|
|
|
160
|
+
| `id` | `map` | 实例标识,对应 `state.keplerGl[id]`;多地图实例必须唯一 |
|
|
161
|
+
| `getState` | `state => state.keplerGl` | 从 store 取 Kepler.gl 子树的函数 |
|
|
162
|
+
| `mapboxApiAccessToken` | 无(类型上必填) | Mapbox 样式所需 token;只用 CARTO/MapLibre 样式时传空串 |
|
|
163
|
+
| `width` / `height` | `800` / `800` | 画布尺寸,常配合容器尺寸动态计算 |
|
|
164
|
+
| `appName` / `version` | `Kepler.Gl` / `v1.0` | 侧栏标题文字 |
|
|
165
|
+
| `sidePanelWidth` | `300` | 侧栏像素宽度 |
|
|
166
|
+
| `theme` | `{}` | 主题对象(覆盖默认主题变量),不是字符串;字符串 `'dark'`/`'light'` 只用于 Python 小组件 |
|
|
167
|
+
| `mapStyles` | 内置列表 | 自定义底图样式数组,配合 `mapStylesReplaceDefault` 替换默认列表 |
|
|
168
|
+
| `readOnly` | `false` | 隐藏侧栏,只读展示 |
|
|
169
|
+
| `onViewStateChange` | 无 | 视口变化回调,用于外部联动 |
|
|
170
|
+
| `getMapboxRef` | 无 | 拿到内部地图实例引用(分屏时按 index 区分) |
|
|
171
|
+
|
|
172
|
+
### addDataToMap
|
|
173
|
+
|
|
174
|
+
```javascript
|
|
175
|
+
import {addDataToMap, removeDataset} from '@kepler.gl/actions';
|
|
176
|
+
|
|
177
|
+
dispatch(addDataToMap({
|
|
178
|
+
datasets: {
|
|
179
|
+
info: {id: 'roads', label: '道路'},
|
|
180
|
+
data: {fields, rows}
|
|
181
|
+
},
|
|
182
|
+
options: {
|
|
183
|
+
centerMap: true,
|
|
184
|
+
padding: {left: 300, top: 24, right: 24, bottom: 24},
|
|
185
|
+
readOnly: false,
|
|
186
|
+
keepExistingConfig: false
|
|
187
|
+
},
|
|
188
|
+
config: savedConfig, // 可选:之前导出的整图配置
|
|
189
|
+
info: {title: '路网概览', description: '2026-10 快照'}
|
|
190
|
+
}));
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
- `datasets` 可传单个 dataset 或数组;配置里的 `dataId` 必须与 `datasets.info.id` 对应
|
|
194
|
+
- `options.centerMap` 会覆盖 `config.mapState` 中的视口,需要保留原视口时设为 `false`
|
|
195
|
+
- `options.keepExistingConfig` 为 `false` 时清空旧图层与过滤器,做「换图」用;追加数据集改用数组形式并设为 `true`
|
|
196
|
+
- 增量更新行数据用 `addToDataset` / `removeFromDataset`,不必重建整图;Arrow/DuckDB 表暂不支持这两个 action
|
|
197
|
+
|
|
198
|
+
### 配置导出与还原
|
|
199
|
+
|
|
200
|
+
```javascript
|
|
201
|
+
import KeplerGlSchema from '@kepler.gl/schemas';
|
|
202
|
+
|
|
203
|
+
const saved = KeplerGlSchema.getConfigToSave(store.getState().keplerGl.demo);
|
|
204
|
+
const meta = KeplerGlSchema.getMapInfo(store.getState().keplerGl.demo);
|
|
205
|
+
localStorage.setItem('kepler-config', JSON.stringify(saved));
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
还原时把 `saved` 作为 `config` 传回 `addDataToMap`,并重新提供 `datasets`;配置中只保存图层与样式,不保存数据本身。
|
|
209
|
+
|
|
210
|
+
### Python 小组件
|
|
211
|
+
|
|
212
|
+
```python
|
|
213
|
+
from keplergl import KeplerGl
|
|
214
|
+
import geopandas as gpd
|
|
215
|
+
|
|
216
|
+
gdf = gpd.read_file("data/roads.gpkg")
|
|
217
|
+
|
|
218
|
+
m = KeplerGl(height=500, theme="dark", app_name="路网概览")
|
|
219
|
+
m.add_data(data=gdf, name="roads")
|
|
220
|
+
m
|
|
221
|
+
|
|
222
|
+
# 导出为独立 HTML(从 unpkg 加载 kepler.gl,无需本地构建)
|
|
223
|
+
m.save_to_html(file_name="roads_map.html", read_only=True, center_map=True)
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
`KeplerGl.__init__` 关键参数:`data`(名称到数据的字典)、`config`(整图配置)、`height`、`mapbox_token`、`use_arrow`(DataFrame 用 Arrow IPC 序列化,大数据更快)、`theme`、`app_name`。`add_data(data, name="data", use_arrow=None)` 追加数据集,`save_to_html(...)` 支持 `read_only`、`center_map`、`json_encoder` 等参数。
|
|
227
|
+
|
|
228
|
+
---
|
|
229
|
+
|
|
230
|
+
## 典型工作流
|
|
231
|
+
|
|
232
|
+
以「GeoPandas 预处理路网 → 发布为可分享的独立 HTML」为例:
|
|
233
|
+
|
|
234
|
+
1. 用 GeoPandas 读取并裁剪数据,保持 WGS84(EPSG:4326),Kepler.gl 只认经纬度
|
|
235
|
+
2. 在 Notebook 中创建 `KeplerGl` 实例并 `add_data`,检查字段类型是否被正确识别
|
|
236
|
+
3. 在界面里调好图层颜色、半径、tooltip 字段
|
|
237
|
+
4. 通过 `m.config` 取出配置,与数据一起 `save_to_html`,得到单文件地图
|
|
238
|
+
|
|
239
|
+
```python
|
|
240
|
+
import geopandas as gpd
|
|
241
|
+
from keplergl import KeplerGl
|
|
242
|
+
|
|
243
|
+
roads = gpd.read_file("data/roads.gpkg").to_crs(4326)
|
|
244
|
+
roads = roads[roads["class"].isin(["motorway", "primary", "secondary"])]
|
|
245
|
+
roads["length_km"] = roads.length * 111.32 # 粗略换算,正式分析请用投影坐标系
|
|
246
|
+
|
|
247
|
+
m = KeplerGl(height=520, theme="dark", app_name="路网概览")
|
|
248
|
+
m.add_data(data=roads[["class", "length_km", "geometry"]], name="roads")
|
|
249
|
+
|
|
250
|
+
# 在 Notebook 中交互配置完成后,导出配置
|
|
251
|
+
config = m.config
|
|
252
|
+
m.save_to_html(file_name="roads_map.html", config=config, read_only=True)
|
|
253
|
+
print("written:", "roads_map.html")
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
输出是一个独立 HTML:内嵌数据与配置,从 unpkg 拉取 kepler.gl 运行时,可直接发给同事查看。
|
|
257
|
+
|
|
258
|
+
React 侧的等价流程是:`processGeojson` / `processCsvData` 解析 → `dispatch(addDataToMap(...))` → 用户交互 → `KeplerGlSchema.getConfigToSave` 落库 → 下次用同一 `config` 还原。
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## 最佳实践
|
|
263
|
+
|
|
264
|
+
1. **坐标系只保留 WGS84**:Kepler.gl 不做投影,其他坐标系先用 GeoPandas `to_crs(4326)` 或 GDAL 转换
|
|
265
|
+
2. **规范字段类型**:数字列不要混入空字符串,时间列统一转 `datetime` 并设置 `format`,否则过滤器表现为「无数据」
|
|
266
|
+
3. **大数据走 Arrow**:Python 侧 `use_arrow=True`,前端可先转 Arrow 表再 `processArrowTable`,比 JSON 行数组更省内存
|
|
267
|
+
4. **控制单次 payload**:一次 `addDataToMap` 传入几十万行以上时应先做聚合或后端分页,浏览器主线程会卡在数据展开
|
|
268
|
+
5. **配置与数据分离存储**:`getConfigToSave` 只存样式,数据另存;版本升级后旧配置可能引用不存在的字段,需要做字段名兜底
|
|
269
|
+
6. **多实例用 id 隔离**:一个页面放两张地图时给不同 `id`,并确认 `getState` 指向同一个根
|
|
270
|
+
7. **底图选型**:CARTO/MapLibre 样式免 token,适合内网与演示;Mapbox 官方样式需 token 且有计费风险
|
|
271
|
+
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
## 常见问题
|
|
275
|
+
|
|
276
|
+
| 问题 | 原因与解决 |
|
|
277
|
+
|------|------------|
|
|
278
|
+
| 组件渲染为空白,控制台提示 `Could not find ... in the context of Connect(...)` | reducer 未挂载或挂载键名不对:按 `combineReducers({keplerGl: keplerGlReducer})` 挂载,或给 `KeplerGl` 传正确的 `getState` |
|
|
279
|
+
| 数据已传入但地图没有图层 | `datasets.info.id` 与 `config` 里的 `dataId` 不匹配,或字段类型不是数值:先不传 `config`(`addDataToMap` 的 config 置空)确认能否自动建层 |
|
|
280
|
+
| 时间过滤器/时间轴不可用 | 时间字段未标记为 `timestamp` 或缺少 `format`:在 `fields` 中补 `{name, type: 'timestamp', format: 'YYYY-MM-DD HH:mm:ss'}` |
|
|
281
|
+
| 点位错位或全部堆在 (0,0) | 坐标不是经纬度,或列名不是 `latitude`/`longitude`:先转 EPSG:4326,并在图层里手动指定经纬度字段 |
|
|
282
|
+
| 底图不显示,提示需要 Mapbox token | 当前样式是 `mapbox://` 样式:换成默认的 CARTO/MapLibre 样式,或给 `mapboxApiAccessToken` 配置有效 token(有计费) |
|
|
283
|
+
| 导入时报 `Cannot find module '@kepler.gl/components'` | 只装了 `kepler.gl` 整包却按子包路径 import:整包用 `kepler.gl` 入口,或按需安装子包并保证版本一致 |
|
|
284
|
+
| `addDataToMap` 后页面卡死数秒 | 单次数据量过大:先聚合或抽样,或改走 Arrow 表;同时关闭不需要的图层(如六边形聚合) |
|
|
285
|
+
| Jupyter 中地图不显示 | 内核与前端版本不匹配:确认 JupyterLab >= 4 / Notebook >= 7,重启内核后重装 `keplergl==0.4.0` |
|
|
286
|
+
| `save_to_html` 报 JSON 序列化错误 | 数据中有 datetime 等非原生类型:保留默认 `json_encoder=str`,或自行传入可序列化编码函数 |
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
## AI 使用建议
|
|
291
|
+
|
|
292
|
+
- **执行环境**:`npm install` / `pnpm install`、`pip install keplergl` 在终端中执行 或 `ops_bash`,长输出重定向到文件再分段读。
|
|
293
|
+
- **先探测版本**:`npm ls kepler.gl @kepler.gl/components @kepler.gl/actions`,子包必须与主包同为 3.3.0-alpha.16;Python 侧 `python -c "import keplergl; print(keplergl.__version__)"` 应为 0.4.0。
|
|
294
|
+
- **验证产物**:前端用 `npm run build` 确认编译,再用 `npx serve dist` 起本地静态服务;是否真出图只能由浏览器确认,AI 助手通常看不到浏览器画面,请用户看画面与控制台,环境支持读图时用截图核对。
|
|
295
|
+
- **无 GPU 环境**:无头环境无法验证 WebGL 渲染,构建通过不等于地图可用,此时不要报告「已渲染」。
|
|
296
|
+
- **常见症状**:空白组件先查 reducer 与 `getState`;无图层查 `dataId` 与字段类型;token 报错查底图样式。
|
|
297
|
+
- **安全与权限**:装包、起服务、把数据写入 HTML 前先征得用户同意;配置里不要硬编码 Mapbox token。
|
|
298
|
+
|
|
299
|
+
## 相关技能
|
|
300
|
+
|
|
301
|
+
- **deck-gl** — Kepler.gl 的渲染底座,自定义图层与拾取需直接操作 deck.gl:[../deck-gl/SKILL.md](../deck-gl/SKILL.md)
|
|
302
|
+
- **mapbox-gl-js** — 使用 Mapbox 官方样式与 token 时的对应技能:[../mapbox-gl-js/SKILL.md](../mapbox-gl-js/SKILL.md)
|
|
303
|
+
- **openlayers** — 传统 2D WebGIS 方案,适合与 Kepler.gl 做能力对比:[../openlayers/SKILL.md](../openlayers/SKILL.md)
|
|
304
|
+
- **geopandas** — Python 侧数据预处理与投影转换:[../geopandas/SKILL.md](../geopandas/SKILL.md)
|
|
305
|
+
- **gdal** — 大体量数据的格式转换与切片,为前端准备输入:[../gdal/SKILL.md](../gdal/SKILL.md)
|
|
306
|
+
|
|
307
|
+
## 参考资源
|
|
308
|
+
|
|
309
|
+
- 官方文档与示例:<https://docs.kepler.gl/>
|
|
310
|
+
- 4.x 之前的旧版文档(API 名称有变化,注意甄别):<https://github.com/keplergl/kepler.gl/tree/master/docs>
|
|
311
|
+
- Jupyter 小组件指南:<https://docs.kepler.gl/docs/keplergl-jupyter>
|
|
312
|
+
- 示例工程目录:<https://github.com/keplergl/kepler.gl/tree/master/examples>
|
|
313
|
+
- 数据格式与处理函数:<https://docs.kepler.gl/docs/api-reference/processors/processors>
|