@dsh-gis/dsh-opengis-skill 0.1.2 → 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 +71 -0
- package/README.md +79 -43
- 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 +78 -29
- package/assets/deck-gl/SKILL.md +20 -20
- package/assets/duckdb-spatial/SKILL.md +370 -0
- package/assets/gdal/SKILL.md +50 -55
- package/assets/gdal-api/SKILL.md +12 -29
- package/assets/geolibre/SKILL.md +364 -0
- package/assets/geometry-api-java/SKILL.md +11 -19
- package/assets/geometry-api-net/SKILL.md +66 -29
- package/assets/geonode/SKILL.md +347 -0
- package/assets/geopandas/SKILL.md +22 -28
- package/assets/geopipe-agent/SKILL.md +25 -30
- package/assets/geoserver/SKILL.md +21 -24
- package/assets/geoserver-cloud/SKILL.md +23 -34
- package/assets/geoserver-rest-api/SKILL.md +18 -23
- package/assets/geotools/SKILL.md +13 -21
- package/assets/grass-gis/SKILL.md +19 -20
- package/assets/jts/SKILL.md +12 -17
- package/assets/kepler-gl/SKILL.md +313 -0
- package/assets/leaflet/SKILL.md +42 -17
- package/assets/mapbox-gl-js/SKILL.md +19 -18
- package/assets/mapserver/SKILL.md +18 -18
- package/assets/mapsui/SKILL.md +87 -58
- package/assets/nettopologysuite/SKILL.md +96 -27
- package/assets/opengis-all/SKILL.md +80 -292
- package/assets/opengis-all/reference/data-stages.md +262 -4
- package/assets/opengis-daf/SKILL.md +12 -14
- package/assets/opengis-utils-for-java/SKILL.md +52 -47
- package/assets/opengis-utils-for-java/reference/common-tasks.md +12 -12
- package/assets/opengis-utils-for-net/SKILL.md +106 -40
- 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 +71 -14
- package/assets/pdal/SKILL.md +21 -15
- package/assets/postgis/SKILL.md +66 -18
- package/assets/proj/SKILL.md +29 -42
- package/assets/projnet4geoapi/SKILL.md +299 -0
- package/assets/pyqgis/SKILL.md +28 -54
- package/assets/qgis-process/SKILL.md +67 -39
- package/assets/qgis-server/SKILL.md +21 -32
- package/assets/shapely/SKILL.md +133 -84
- package/assets/sharpmap/SKILL.md +96 -61
- 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
|
@@ -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>
|
package/assets/leaflet/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: leaflet
|
|
3
|
-
description: "Use when adding lightweight
|
|
3
|
+
description: "Use when adding lightweight 2D tile maps to web pages with leaflet 1.9.4 — L.map/L.tileLayer, markers, popups, GeoJSON overlays, layer control, [lat, lng] ordering, or debugging blank maps, broken default marker icons after bundling, and sizing fixed by invalidateSize()."
|
|
4
4
|
tags:
|
|
5
5
|
- javascript
|
|
6
6
|
- web
|
|
@@ -22,7 +22,7 @@ tags:
|
|
|
22
22
|
>
|
|
23
23
|
> **示例:** <https://leafletjs.com/examples.html>
|
|
24
24
|
>
|
|
25
|
-
> **最新版本:** 1.9.4(截至2026-10,npm `leaflet`)
|
|
25
|
+
> **最新版本:** 1.9.4(截至 2026-10,npm `leaflet`)
|
|
26
26
|
>
|
|
27
27
|
> **许可证:** BSD-2-Clause
|
|
28
28
|
|
|
@@ -187,19 +187,42 @@ map.off('mousemove', handler); // 显式移除,避免内存泄漏
|
|
|
187
187
|
|
|
188
188
|
## 典型工作流
|
|
189
189
|
|
|
190
|
+
以「底图 + GeoJSON 点位 + 弹窗 + 图层切换」为例:输入 `data/poi.geojson`(`[lng, lat]`),输出可缩放、可点选、可切层的单页地图。
|
|
191
|
+
|
|
190
192
|
1. **初始化地图**:`L.map('map', { center, zoom })`,容器须有确定高度
|
|
191
193
|
2. **添加底图**:`L.tileLayer(urlTemplate, { attribution }).addTo(map)`
|
|
192
|
-
3. **叠加数据**:`L.
|
|
194
|
+
3. **叠加数据**:`L.geoJSON(data, { style, pointToLayer, onEachFeature })`
|
|
193
195
|
4. **绑定交互**:`layer.bindPopup()` / `map.on('click', fn)`
|
|
194
196
|
5. **图层管理**:`L.control.layers(baseLayers, overlays).addTo(map)`
|
|
195
197
|
6. **自适应视图**:`map.fitBounds(layer.getBounds())`
|
|
196
198
|
7. **销毁清理**:组件卸载时调用 `map.remove()`
|
|
197
199
|
|
|
198
200
|
```javascript
|
|
199
|
-
const
|
|
200
|
-
|
|
201
|
+
const map = L.map('map', { center: [39.9042, 116.4074], zoom: 11 });
|
|
202
|
+
|
|
203
|
+
const osm = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
|
|
204
|
+
maxZoom: 19,
|
|
205
|
+
attribution: '© OpenStreetMap contributors'
|
|
206
|
+
}).addTo(map);
|
|
207
|
+
|
|
208
|
+
// GeoJSON 坐标是 [lng, lat],Leaflet 需要 [lat, lng]
|
|
209
|
+
fetch('/data/poi.geojson')
|
|
210
|
+
.then((r) => r.json())
|
|
211
|
+
.then((geojson) => {
|
|
212
|
+
const poiLayer = L.geoJSON(geojson, {
|
|
213
|
+
pointToLayer: (feature, latlng) => L.circleMarker(latlng, { radius: 6, color: '#e74c3c' }),
|
|
214
|
+
onEachFeature: (feature, layer) => {
|
|
215
|
+
layer.bindPopup(feature.properties.name);
|
|
216
|
+
}
|
|
217
|
+
}).addTo(map);
|
|
218
|
+
|
|
219
|
+
map.fitBounds(poiLayer.getBounds(), { padding: [20, 20] });
|
|
220
|
+
L.control.layers({ OSM: osm }, { POI: poiLayer }).addTo(map);
|
|
221
|
+
});
|
|
201
222
|
```
|
|
202
223
|
|
|
224
|
+
**验收**:页面先出现 OSM 底图,数据加载后视野自动收缩到点位范围,点击圆点弹出名称;右上角图层控件可切换 POI 显隐。
|
|
225
|
+
|
|
203
226
|
---
|
|
204
227
|
|
|
205
228
|
## 插件生态
|
|
@@ -327,13 +350,15 @@ export default function MapView() {
|
|
|
327
350
|
|
|
328
351
|
---
|
|
329
352
|
|
|
330
|
-
##
|
|
353
|
+
## AI 使用建议
|
|
331
354
|
|
|
332
|
-
-
|
|
333
|
-
-
|
|
334
|
-
-
|
|
335
|
-
-
|
|
336
|
-
-
|
|
355
|
+
- **执行环境**:`npm install`、`npm run build` 在终端中执行;纯静态页面可用 `python -m http.server 5173` 起服务(`python` 不存在时用 `py -3`)。
|
|
356
|
+
- **先探测版本**:`npm ls leaflet`(未装则 `npm view leaflet version`);本技能按 1.9.4 编写,CDN 的 `integrity` SRI 哈希只对应 1.9.4,换版本必须同步换哈希。
|
|
357
|
+
- **验证产物**:构建后 `curl.exe -I http://localhost:5173/assets/<入口>.js` 确认 200;联网时还可 `curl.exe -I https://unpkg.com/leaflet@1.9.4/dist/leaflet.js` 核对 CDN 版本;AI 助手通常看不到浏览器画面,把 URL 和“应看到瓦片与标记”交给用户,环境支持读图时用截图核对。
|
|
358
|
+
- **图标与坐标**:npm + 打包器下默认 marker 图标会 404,需显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`;坐标一律 `[lat, lng]`,GeoJSON 是 `[lng, lat]`。
|
|
359
|
+
- **生命周期**:SPA 卸载必须 `map.remove()` 并解绑自定义事件;容器隐藏或尺寸变化后 `map.invalidateSize()`。
|
|
360
|
+
- **常见症状**:地图区域空白多为容器没设高度;`L is not defined` 是脚本顺序或 CDN 失败;漏引 `leaflet.css` 会导致控件错位。
|
|
361
|
+
- **安全与权限**:装包、起服务、改端口前先征得用户同意;天地图等瓦片服务的 `tk` 不要硬编码进提交的前端代码。
|
|
337
362
|
|
|
338
363
|
## 相关技能
|
|
339
364
|
|
|
@@ -341,10 +366,10 @@ export default function MapView() {
|
|
|
341
366
|
- **cesiumjs** — 三维地球与 3D Tiles 可视化:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
|
|
342
367
|
- **geoserver** — 发布 WMS/WFS/瓦片服务作为 Leaflet 数据源:[../geoserver/SKILL.md](../geoserver/SKILL.md)
|
|
343
368
|
|
|
344
|
-
##
|
|
369
|
+
## 参考资源
|
|
345
370
|
|
|
346
|
-
-
|
|
347
|
-
-
|
|
348
|
-
-
|
|
349
|
-
-
|
|
350
|
-
-
|
|
371
|
+
- 官方文档:<https://leafletjs.com/>
|
|
372
|
+
- API 参考:<https://leafletjs.com/reference.html>
|
|
373
|
+
- 官方示例:<https://leafletjs.com/examples.html>
|
|
374
|
+
- 插件列表:<https://leafletjs.com/plugins.html>
|
|
375
|
+
- 源码仓库:<https://github.com/Leaflet/Leaflet>
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: mapbox-gl-js
|
|
3
|
-
description: "Use when building
|
|
3
|
+
description: "Use when building vector web maps with mapbox-gl 3.33.0 — WebGL rendering, Style Spec layers, data-driven expressions, setTerrain raster-dem, fill-extrusion, or debugging 401 'A valid Mapbox access token is required', 'Style is not done loading', and pk./sk. token handling. Note: v2+ is proprietary under Mapbox TOS and requires a token; MapLibre GL JS is the open-source fork."
|
|
4
4
|
tags:
|
|
5
5
|
- javascript
|
|
6
6
|
- web
|
|
@@ -19,7 +19,7 @@ tags:
|
|
|
19
19
|
>
|
|
20
20
|
> **API 参考:** <https://docs.mapbox.com/mapbox-gl-js/api/>
|
|
21
21
|
>
|
|
22
|
-
> **最新版本:** 3.33.0(截至2026-10,npm `mapbox-gl` 与 GitHub Release 一致)
|
|
22
|
+
> **最新版本:** 3.33.0(截至 2026-10,npm `mapbox-gl` 与 GitHub Release 一致)
|
|
23
23
|
>
|
|
24
24
|
> **许可证:** v2+ 为 Mapbox 专有许可(v1.x 为 BSD-3-Clause;需 Mapbox 账号 access token)
|
|
25
25
|
|
|
@@ -406,16 +406,15 @@ map.on('load', () => {
|
|
|
406
406
|
|
|
407
407
|
---
|
|
408
408
|
|
|
409
|
-
##
|
|
409
|
+
## AI 使用建议
|
|
410
410
|
|
|
411
|
-
-
|
|
412
|
-
-
|
|
413
|
-
-
|
|
414
|
-
-
|
|
415
|
-
-
|
|
416
|
-
-
|
|
417
|
-
-
|
|
418
|
-
- 价格说明:<https://www.mapbox.com/pricing>
|
|
411
|
+
- **执行环境**:`npm install`、`npm run build` 在终端中执行;Windows 下用 `npm.cmd`,长构建放后台运行。
|
|
412
|
+
- **先探测版本**:`npm ls mapbox-gl`(未装则 `npm view mapbox-gl version`);本技能按 3.33.0 编写,CDN 的 JS 与 CSS 必须同为 `v3.33.0`,联网时 `curl.exe -I https://api.mapbox.com/mapbox-gl-js/v3.33.0/mapbox-gl.js` 应为 200。
|
|
413
|
+
- **验证产物**:`npm run build` 后 `npx serve dist`,`curl.exe -I http://localhost:5173/` 确认入口;地图是否真加载、有没有 401 只能看浏览器 Network(`api.mapbox.com`),AI 助手通常看不到浏览器画面,请用户确认或提供截图后再判断。
|
|
414
|
+
- **token 安全**:前端只允许 `pk.` 公开 token,`sk.` 绝不能进构建产物;用 `VITE_MAPBOX_TOKEN` 等环境变量注入,提交前用 agent 的 `grep` 搜 `sk.` 与硬编码 `pk.`,回答和日志里不要回显 token。
|
|
415
|
+
- **许可提醒**:v2+ 是 Mapbox 专有许可并受配额计费约束;用户要求开源或免 token 时改写为 MapLibre(`maplibregl` 替代 `mapboxgl`,`mapbox://` 样式换成自建瓦片)。
|
|
416
|
+
- **常见症状**:`Style is not done loading` 是 `load` 事件前调了 `addSource`/`addLayer`;空白先查容器高度和 `map.resize()`;`e.features` 只在回调内有效。
|
|
417
|
+
- **安全与权限**:装包、起 dev server、调用计费接口前先征得用户同意,并说明可能产生费用。
|
|
419
418
|
|
|
420
419
|
## 相关技能
|
|
421
420
|
|
|
@@ -424,11 +423,13 @@ map.on('load', () => {
|
|
|
424
423
|
- **cesiumjs** — 三维地球与 3D Tiles 可视化:[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
|
|
425
424
|
- **geoserver** — 发布 WMS/WFS/MVT 服务作为矢量瓦片数据源:[../geoserver/SKILL.md](../geoserver/SKILL.md)
|
|
426
425
|
|
|
427
|
-
##
|
|
426
|
+
## 参考资源
|
|
428
427
|
|
|
429
|
-
-
|
|
430
|
-
-
|
|
431
|
-
-
|
|
432
|
-
-
|
|
433
|
-
-
|
|
434
|
-
-
|
|
428
|
+
- 官方文档:<https://docs.mapbox.com/mapbox-gl-js/>
|
|
429
|
+
- API 参考:<https://docs.mapbox.com/mapbox-gl-js/api/>
|
|
430
|
+
- 官方示例:<https://docs.mapbox.com/mapbox-gl-js/examples/>
|
|
431
|
+
- Style Spec 样式规范:<https://docs.mapbox.com/style-spec/>
|
|
432
|
+
- Expressions 表达式参考:<https://docs.mapbox.com/style-spec/reference/expressions/>
|
|
433
|
+
- 源码仓库与发布记录:<https://github.com/mapbox/mapbox-gl-js>
|
|
434
|
+
- 开源替代 MapLibre GL JS:<https://github.com/maplibre/maplibre-gl-js>
|
|
435
|
+
- 价格说明:<https://www.mapbox.com/pricing>
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: mapserver
|
|
3
|
-
description: "Use when publishing
|
|
3
|
+
description: "Use when publishing WMS/WFS/WCS/OGC API Features from a MapServer 8.6.6 .map mapfile — MAP/LAYER/CLASS/STYLE objects, STATUS/PROJECTION/EXTENT errors, WEB.METADATA wms_enable_request and wfs_enable_request, SLD binding, FastCGI plus MS_MAP_PATTERN hardening, and blank GetMap / \"No query information to decode\" symptoms."
|
|
4
4
|
tags:
|
|
5
5
|
- c
|
|
6
6
|
- server
|
|
@@ -17,7 +17,7 @@ tags:
|
|
|
17
17
|
>
|
|
18
18
|
> **官方文档:** <https://mapserver.org/>
|
|
19
19
|
>
|
|
20
|
-
> **最新版本:** 8.6.6(rel-8-6-6,[发布记录](https://github.com/MapServer/MapServer/releases))
|
|
20
|
+
> **最新版本:** 8.6.6(rel-8-6-6,2026-09-06 发布,截至 2026-10;[发布记录](https://github.com/MapServer/MapServer/releases))
|
|
21
21
|
>
|
|
22
22
|
> **许可证:** MIT
|
|
23
23
|
|
|
@@ -52,12 +52,13 @@ sudo systemctl restart apache2
|
|
|
52
52
|
|
|
53
53
|
### 方式二:源码编译(CMake)
|
|
54
54
|
|
|
55
|
-
MapServer 8.
|
|
55
|
+
MapServer 8.0 起需要支持 C++11/C99 的编译器;8.4.0 起要求 CMake 3.16+(官方 Unix 安装文档实测)。先装依赖(GDAL、PROJ、libpng、FreeType、zlib、libcurl 为常用项):
|
|
56
56
|
|
|
57
57
|
```bash
|
|
58
58
|
sudo apt install -y build-essential cmake libgdal-dev libproj-dev \
|
|
59
59
|
libpng-dev libfreetype6-dev zlib1g-dev libcurl4-openssl-dev
|
|
60
60
|
|
|
61
|
+
curl -fLO https://download.osgeo.org/mapserver/mapserver-8.6.6.tar.gz
|
|
61
62
|
tar -zxvf mapserver-8.6.6.tar.gz
|
|
62
63
|
cd mapserver-8.6.6 && mkdir build && cd build
|
|
63
64
|
cmake -DCMAKE_INSTALL_PREFIX=/opt \
|
|
@@ -265,16 +266,14 @@ ogr2ogr -f GPKG clip.gpkg countries.gpkg -clipsrc 100 20 130 50
|
|
|
265
266
|
|
|
266
267
|
---
|
|
267
268
|
|
|
268
|
-
##
|
|
269
|
-
|
|
270
|
-
- 官方文档:<https://mapserver.org/>
|
|
271
|
-
- Unix 编译安装:<https://mapserver.org/installation/unix.html>
|
|
272
|
-
- Mapfile 参考:<https://mapserver.org/mapfile/index.html>
|
|
273
|
-
- WMS Server:<https://mapserver.org/ogc/wms_server.html>
|
|
274
|
-
- WFS Server:<https://mapserver.org/ogc/wfs_server.html>
|
|
275
|
-
- 在线示例服务:<https://demo.mapserver.org/>
|
|
269
|
+
## AI 使用建议
|
|
276
270
|
|
|
277
|
-
|
|
271
|
+
- **执行环境**:命令在终端 / shell 中执行(Windows 用 OSGeo4W 的 `mapserv.exe`);`sudo apt`、`tar -zxvf` 不跨平台,Windows 改 `Expand-Archive`,装包或改系统目录前先问用户。
|
|
272
|
+
- **先探测版本**:`mapserv -v`,确认输出含 `MapServer version 8.6.6` 且 `SUPPORTS=` 里有需要的 `WMS_SERVER`/`WFS_SERVER`;缺项说明该构建没编进对应库,改 mapfile 无用。
|
|
273
|
+
- **验证产物**:先离线 `map2img -m demo.map -o out.png -s 600 400` 看渲染,再 `mapserv -nh "QUERY_STRING=map=/abs/demo.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities"` 抓能力文档,最后才 `curl -sI "http://host/cgi-bin/mapserv?map=...&REQUEST=GetMap..."` 确认 200 与 `Content-Type: image/png`。
|
|
274
|
+
- **排障分流**:空白图查 `EXTENT`/`BBOX`/`PROJECTION`/`STATUS ON`;能力文档缺图层查 `wms_enable_request`、`wfs_enable_request` 与 `NAME` 是否字母开头;WFS 无属性字段是 8.x 默认行为,补 `gml_include_items`。
|
|
275
|
+
- **安全与权限**:`map=` 可读任意路径是 MapServer 最典型误配置,生产必须设 `MS_MAP_PATTERN`/`MS_MAP_NO_PATH`;重启 Apache/nginx 或改 CGI 权限前先向用户确认。
|
|
276
|
+
- **改一处验一处**:改 `WEB.METADATA` 后只重跑 `GetCapabilities`,改 `LAYER` 样式后只重跑 `map2img`,缩小排查范围。
|
|
278
277
|
|
|
279
278
|
## 相关技能
|
|
280
279
|
|
|
@@ -285,10 +284,11 @@ ogr2ogr -f GPKG clip.gpkg countries.gpkg -clipsrc 100 20 130 50
|
|
|
285
284
|
|
|
286
285
|
---
|
|
287
286
|
|
|
288
|
-
##
|
|
287
|
+
## 参考资源
|
|
289
288
|
|
|
290
|
-
-
|
|
291
|
-
-
|
|
292
|
-
-
|
|
293
|
-
-
|
|
294
|
-
-
|
|
289
|
+
- 官方文档:<https://mapserver.org/>
|
|
290
|
+
- Unix 编译安装:<https://mapserver.org/installation/unix.html>
|
|
291
|
+
- Mapfile 参考:<https://mapserver.org/mapfile/index.html>
|
|
292
|
+
- WMS Server:<https://mapserver.org/ogc/wms_server.html>
|
|
293
|
+
- WFS Server:<https://mapserver.org/ogc/wfs_server.html>
|
|
294
|
+
- 在线示例服务:<https://demo.mapserver.org/>
|