@3clear/basegis 0.1.0 → 0.1.1

package/README.md

@@ -1,10 +1,10 @@
 # @3clear/basegis
 
 `@3clear/basegis` 是 3clear 一张图项目抽出的 GIS 能力包。它提供一个统一入口 `BaseGIS`，把 Cesium / Leaflet 的差异收敛到适配层里；业务页面优先只操作 `BaseGIS`，复杂图层能力通过 `methods` 控制器组合 `BaseGIS` 公共方法完成。
-
+把leaflet cesium 常用方法做了二次封装统一了api 使同一套代码可以适配2套地图引擎
 当前包包含：
 
-- `BaseGIS`：地图初始化、引擎切换、视角控制、底图切换、绘制、图层显隐、DEM、点击事件等基础能力。
+- `BaseGIS`：地图初始化、引擎切换、视角控制、底图切换、绘制、图层显隐、DEM、点击事件、三维体渲染、三维切片/剖面渲染等基础能力。
 - `methods`：图片图层、网格图层、海量点、点位抽稀、等值线、等压线、风场、图形组等高级控制器。
 - `layers`：天地图、GeoServer 金字塔瓦片、WMS、WMTS 图层配置快捷构造器。
 - `assets`：GIS 示例资源。
@@ -22,8 +22,7 @@ npm install @3clear/basegis leaflet axios pixi.js leaflet-pixi-overlay
 import '@3clear/basegis/style.css'
 ```
 
-Cesium 当前不随 npm 包发布，宿主项目需要按原项目方式把 Cesium 静态资源放到 `public/lib/Cesium`，并保证初始化前能访问 `window.Cesium`。默认配置会从 `${BASE_URL}lib/Cesium/Cesium.js` 和 `${BASE_URL}lib/Cesium/Widgets/widgets.css` 加载。
-
+Cesium 当前不随 npm 包发布，宿主项目需要按原项目方式把 Cesium 静态资源放到 `public/lib/Cesium`，并保证初始化前能访问 `window.Cesium`。
 如果需要加载 GeoTIFF 网格，需要宿主项目提前提供 `window.GeoTIFF`。
 
 ## 出口
@@ -91,6 +90,12 @@ onMounted(() => {
           pitch: -90,
         },
       },
+      basemap: {
+        // 默认内置值：tianditu-imagery。
+        defaultVisibleId: 'tianditu-imagery',
+        // 默认内置值：tianditu-vector-label。
+        defaultAnnotationId: 'tianditu-vector-label',
+      },
     },
   })
 
@@ -133,263 +138,526 @@ onBeforeUnmount(() => {
   message: 'error message',
   code: 'NOT_INITIALIZED'
 }
+
 ```
 
-Leaflet 不支持 3D、DEM 等能力时，会返回失败结果或控制台提示，不应直接打断页面。
+说明：
+
+- `containerId` 和 `container` 二选一即可；`init()` 时也可以再次传入。
+- 页面传入的 `config` 会覆盖内置默认配置。
+- `basemap.list` 和 `dem.list` 是数组，外部传入时会整体覆盖内置列表；如果要使用内置默认底图，不要传空数组覆盖。
+- Cesium 默认视角 `pitch: -90`，表示垂直俯视。
+- `BaseGIS` 只保存运行时配置，调用 `setConfig()` 不会自动重建地图，需要重新 `init()` 才会创建新地图实例。
+
+### 默认底图配置
 
-## BaseGIS 配置
+不传 `config.basemap` 时，内置默认配置如下：
 
 ```js
-const mapCore = new BaseGIS({
-  engineType: 'cesium',
-  containerId: 'map',
-  config: {
-    engine: {
-      active: 'cesium',
-      cesium: {
-        // 本地 Cesium 静态资源地址。
-        scriptUrl: '/lib/Cesium/Cesium.js',
-        cssUrl: '/lib/Cesium/Widgets/widgets.css',
-      },
-      leaflet: {
-        sourceType: 'npm',
-      },
-    },
-    view: {
-      defaultSceneMode: '3d',
-      initialView: {
-        center: [121.4737, 31.2304],
-        height: 1800000,
-        zoom: 7,
-        heading: 0,
-        pitch: -90,
-        roll: 0,
-      },
-    },
-    basemap: {
-      defaultVisibleId: 'tianditu-imagery',
-      defaultAnnotationId: 'tianditu-vector-label',
-      list: [],
-    },
-    dem: {
-      defaultEnabled: true,
-      defaultVisibleId: 'ellipsoid-flat',
-      list: [],
-    },
+basemap: {
+  defaultVisibleId: 'tianditu-imagery',
+  defaultAnnotationId: 'tianditu-vector-label',
+}
+```
+
+默认底图列表：
+
+| id | 名称 | category | enabled | type | provider | resourceKey | 默认用途 | 引擎支持 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `tianditu-vector` | 天地图矢量底图 | `basemap` | `true` | `wmts` | `tianditu` | `vector` | 可作为 `defaultVisibleId` | Cesium / Leaflet |
+| `tianditu-imagery` | 天地图影像底图 | `basemap` | `true` | `wmts` | `tianditu` | `imagery` | 内置 `defaultVisibleId` | Cesium / Leaflet |
+| `tianditu-terrain` | 天地图地形底图 | `basemap` | `true` | `wmts` | `tianditu` | `terrain` | 可作为 `defaultVisibleId` | Cesium / Leaflet |
+| `tianditu-vector-label` | 天地图矢量注记 | `annotation` | `true` | `wmts` | `tianditu` | `vectorLabel` | 内置 `defaultAnnotationId` | Cesium / Leaflet |
+| `tianditu-terrain-label` | 天地图地形注记 | `annotation` | `true` | `wmts` | `tianditu` | `terrainLabel` | 可作为 `defaultAnnotationId` | Cesium / Leaflet |
+
+可用于 `defaultVisibleId` 的内置底图 id：
+
+- `tianditu-vector`
+- `tianditu-imagery`
+- `tianditu-terrain`
+
+可用于 `defaultAnnotationId` 的内置注记 id：
+
+- `tianditu-vector-label`
+- `tianditu-terrain-label`
+
+说明：
+
+- `defaultVisibleId` 应指向 `category: 'basemap'` 的底图。
+- `defaultAnnotationId` 应指向 `category: 'annotation'` 的注记层。
+- `tianditu-terrain` 是天地图地形底图瓦片，不是 Cesium 的 DEM 高程地形；如果要控制 Cesium terrainProvider，请看后文 DEM。
+- `geoserver-wmts-sample` 和 `geoserver-wms-sample` 默认 `enabled: false`，只是配置格式示例；如果要作为默认底图，需要替换真实服务地址并改为 `enabled: true`。
+- 天地图 provider 内置资源还包括 `imageryLabel`；默认 `basemap.list` 没有单独注册影像注记 id，但 `resourceKey: 'imagery'` 会自动推断使用 `imageryLabel` 注记。
+
+###  底图切换
+
+底图可以来自 `config.basemap.list`，也可以直接传配置对象。当前适配层支持：
+
+- 天地图：`provider: 'tianditu'` 或传 `resourceKey`
+- URL 模板瓦片：`type: 'wmts' / 'xyz' / 'tile'`
+- WMS：`type: 'wms'`
+
+按配置 id 切换：
+
+```js
+const result = mapCore.setBasemapById('tianditu-imagery')
+if (!result.success) {
+  console.warn(result.message)
+}
+```
+
+直接传底图配置：
+
+```js
+
+mapCore.setBasemap({
+  id: 'custom-xyz',
+  name: '自定义 XYZ',
+  category: 'basemap',
+  type: 'xyz',
+  provider: 'custom',
+  url: 'https://example.com/tiles/{z}/{x}/{y}.png',
+  minZoom: 0,
+  maxZoom: 18,
+  subdomains: ['a', 'b', 'c'],
+})
+
+mapCore.setBasemap({
+  id: 'custom-wms',
+  name: '自定义 WMS',
+  category: 'basemap',
+  type: 'wms',
+  provider: 'custom',
+  serviceUrl: 'https://example.com/geoserver/wms',
+  layers: 'workspace:layer',
+  parameters: {
+    transparent: true,
+    format: 'image/png',
+    version: '1.1.1',
   },
 })
 ```
 
-说明：
 
-- `containerId` 和 `container` 二选一即可；`init()` 时也可以再次传入。
-- 页面传入的 `config` 会覆盖内置默认配置。
-- Cesium 默认视角 `pitch: -90`，表示垂直俯视。
-- `BaseGIS` 只保存运行时配置，调用 `setConfig()` 不会自动重建地图，需要重新 `init()` 才会创建新地图实例。
+方法说明：
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `setBasemapById(id)` | 底图 id | 从 `config.basemap.list` 查找底图并切换。会校验 `category / engineSupport / enabled`。 |
+| `setBasemap(payload)` | 底图配置对象 | 直接切换到底图配置。 |
+
+常用底图参数：
+
+| 参数 | 是否必填 | 说明 |
+| --- | --- | --- |
+| `id` | 建议必填 | 底图唯一 id。 |
+| `name` | 选填 | 底图名称。 |
+| `category` | 建议传 `basemap` | `setBasemapById` 会拒绝非 `basemap` 分类。 |
+| `type` | 自定义服务必填 | `wmts`、`xyz`、`tile`、`wms`。 |
+| `provider` | 选填 | 天地图传 `tianditu`，自定义服务传 `custom`。 |
+| `resourceKey` | 天地图必填 | `vector`、`imagery`、`terrain` 等。 |
+| `annotationResourceKey` | 选填 | 天地图注记资源，如 `vectorLabel`、`imageryLabel`。 |
+| `url` | URL 模板必填 | `wmts/xyz/tile` 使用，支持 `{z}/{x}/{y}` 模板。 |
+| `serviceUrl` | WMS 必填 | WMS 服务地址；也可用 `url`。 |
+| `layers` | WMS 必填 | WMS 图层名。 |
+| `parameters` | 选填 | WMS 附加参数。 |
+| `engineSupport` | 选填 | 支持的引擎列表，如 `['cesium', 'leaflet']`。 |
+
 
 ## BaseGIS 基础能力
 
-### 生命周期与实例
+这一节列的是 `BaseGIS` 主入口直接提供的基础能力。业务页面优先调用这些方法；图片图层、网格图层、海量点、点位抽稀、等值线、风场等更复杂能力，建议使用后文 `methods` 中对应的 Controller。
+
+### 1. 生命周期、实例与引擎切换
+
+`BaseGIS` 支持 `cesium` 和 `leaflet` 两种引擎。引擎可以在构造时指定，也可以在 `init()` 时指定。
 
 ```js
-mapCore.init({ containerId: 'map', engineType: 'leaflet' })
-mapCore.destroy()
+const mapCore = new BaseGIS({
+  engineType: 'cesium',
+  containerId: 'map',
+})
+
+// 创建地图实例。
+mapCore.init()
+
+// 只修改当前运行时引擎配置，不会自动重建地图实例。
+mapCore.setEngine('leaflet')
+
+// 真正切换地图引擎，需要再次 init。
+// init 内部会先销毁旧 adapter，再按新 engineType 创建新地图实例。
+mapCore.init({
+  engineType: 'leaflet',
+  containerId: 'map',
+})
 
-mapCore.setEngine('cesium')
+// 覆盖运行时配置，不会自动重建地图。
 mapCore.setConfig({ view: { defaultSceneMode: '2d' } })
 
+// 读取当前地图引擎
 mapCore.getEngineType()
+//获取当前地图配置
 mapCore.getConfig()
+//获取地图实例
 mapCore.getMapInstance()
+// 销毁当前地图实例。
+mapCore.destroy()
+```
+
+方法说明：
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `init(options)` | `{ container, containerId, engineType }` | 初始化地图。`container` 可传 DOM，`containerId` 可传 DOM id。 |
+| `destroy()` | 无 | 销毁当前地图实例和 adapter。 |
+| `setEngine(engineType)` | `'cesium'/'leaflet'` | 修改当前引擎类型；不自动重建地图。 |
+| `setConfig(config)` | `Object` | 合并运行时配置；不自动重建地图。 |
+| `getEngineType()` | 无 | 返回当前引擎类型。 |
+| `getConfig()` | 无 | 返回当前运行时配置。 |
+| `getMapInstance()` | 无 | 返回底层地图实例：Cesium `viewer` 或 Leaflet `map`。 |
+
+#### 推荐的引擎切换写法
+
+页面上做 Cesium / Leaflet 切换时，建议把切换动作收敛成一个函数。`setEngine()` 用来更新 `BaseGIS` 内部引擎类型，`init()` 才是真正重建地图。
+
+```js
+async function switchEngine(engineType) {
+  if (!mapCore || mapCore.getEngineType() === engineType) {
+    return
+  }
+
+  const result = mapCore.init({
+    engineType,
+    containerId: 'map',
+  })
+
+  if (!result.success) {
+    console.warn(result.message)
+    return
+  }
+
+  // 地图实例已经重建，业务图层需要用自己的数据源重新加载。
+  await reloadBusinessLayers()
+}
+```
+
+也可以显式先调用 `setEngine()`：
+
+```js
+mapCore.setEngine('leaflet')
+const result = mapCore.init({
+  containerId: 'map',
+})
+```
+
+两种写法效果一致；如果 `init({ engineType })` 已经传了目标引擎，可以不单独调用 `setEngine()`。
+
+#### 切换后的图层处理
+
+引擎切换不是把 Cesium 图层“搬到” Leaflet，也不是把 Leaflet 图层“搬到” Cesium。`init()` 重建地图时会销毁旧引擎实例，因此：
+
+- `BaseGIS` 的配置会保留，例如 `config / initialView / basemap`。
+- 业务数据应由页面或 store 保存，例如站点数组、图片地址、等值线数据、风场数据。
+- 切换成功后，用这些业务数据重新调用对应 Controller 的 `load/update`，或重新调用 `BaseGIS` 图层方法。
+- Cesium 专有能力在 Leaflet 下不可用，例如 DEM、三维体渲染、三维切片/剖面渲染。
+- 页面层不应直接依赖 Cesium / Leaflet 分支；如果确实要访问底层实例，只在边界很清楚的地方使用 `getMapInstance()`。
+
+常见重载示例：
+
+```js
+async function reloadBusinessLayers() {
+  await imageLayer.update(currentImagePayload)
+  await pointLayer.load({ points: currentPoints })
+  await contour.load(currentContourPayload)
+
+  if (mapCore.getEngineType() === 'cesium') {
+    mapCore.upsertVolumeLayer(currentVolumePayload)
+  }
+}
 ```
 
-### 视角与场景
+
+### 2. 视角控制与场景模式
+
+视角控制分为缩放、重置视角、设置初始视角、场景模式切换、视图状态读取和视图变化监听。
 
 ```js
+// 放大 / 缩小。
+// Cesium 可传 { distance }，Leaflet 可传 { step }。
 mapCore.zoomIn()
 mapCore.zoomOut()
-mapCore.resetView()
+mapCore.zoomIn({ distance: 300000 })
+mapCore.zoomOut({ step: 1 })
 
-mapCore.setSceneMode('2d')
-mapCore.setSceneMode('2.5d')
-mapCore.setSceneMode('3d')
-mapCore.getSceneMode()
+// 回到配置中的 initialView，也可以传入目标视角覆盖。
+mapCore.resetView()
+mapCore.resetView({
+  center: [104, 35],
+  height: 3000000,
+  zoom: 5,
+  pitch: -90,
+})
 
+// 设置视角。center / position 均为 [经度, 纬度]。
 mapCore.setInitialView({
   center: [104, 35],
+  // Cesium 使用 height。
   height: 3000000,
+  // Leaflet 使用 zoom。
   zoom: 5,
+  // Cesium 使用 heading / pitch / roll，单位是度。
+  heading: 0,
   pitch: -90,
+  roll: 0,
+})
+
+// 场景模式。Cesium 支持 2d / 2.5d / 3d；Leaflet 只支持 2d。
+mapCore.setSceneMode('3d')
+mapCore.setSceneMode({
+  mode: '2d',
+  // Cesium morph 动画时长，单位秒。
+  duration: 0.4,
+  // Cesium 场景切换后是否尽量恢复原视野，默认 true。
+  preserveView: true,
+})
+mapCore.getSceneMode()
+
+// 获取当前视图边界。
+const boundsResult = mapCore.getViewBounds()
+// boundsResult.data: { west, south, east, north }
+
+// 获取当前视图状态。
+const viewStateResult = mapCore.getViewState()
+// Cesium 通常包含 center / bounds / height / heading / pitch / roll / engineType。
+// Leaflet 通常包含 center / bounds / zoom / engineType。
+
+// 经纬度转地图容器像素坐标，常用于自定义 HTML 浮层定位。
+const pointResult = mapCore.projectToContainerPoint({
+  longitude: 104,
+  latitude: 35,
+  height: 0,
 })
+// pointResult.data: { x, y }
 ```
 
-### 底图与普通图层
+视图变化监听：
 
 ```js
-mapCore.setBasemapById('tianditu-imagery')
+const viewListener = mapCore.onViewChange({
+  // Cesium: camera.moveStart / morphStart；Leaflet: movestart / zoomstart。
+  onStart() {},
 
-mapCore.setBasemap({
-  id: 'custom-wmts',
-  name: '自定义 WMTS',
-  type: 'wmts',
-  provider: 'custom',
-  url: 'https://example.com/wmts?...',
+  // Cesium: camera.changed；Leaflet: move / zoom / resize。
+  // 缩放过程中要实时刷新点位样式时，优先用 onChange。
+  onChange() {},
+
+  // Cesium: camera.moveEnd / morphComplete；Leaflet: moveend / zoomend / resize。
+  onEnd() {},
+
+  // Cesium onEnd 延迟，默认 120ms。
+  endDelay: 120,
 })
 
-mapCore.addLayer(layerConfig)
-mapCore.showLayer({ layerId: 'custom-wmts' })
-mapCore.hideLayer({ layerId: 'custom-wmts' })
-mapCore.removeLayer({ layerId: 'custom-wmts' })
+// 组件卸载时移除监听。
+viewListener.data?.off?.()
 ```
 
-### 点线面文字
+方法说明：
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `zoomIn(payload)` | Cesium `{ distance }`；Leaflet `{ step }` | 放大地图。 |
+| `zoomOut(payload)` | Cesium `{ distance }`；Leaflet `{ step }` | 缩小地图。 |
+| `resetView(payload)` | 视角对象，可选 | 回到初始视角或传入的目标视角。 |
+| `setInitialView(payload)` | `{ center, height, zoom, heading, pitch, roll }` | 设置当前视角。 |
+| `setSceneMode(payload)` | `'2d'/'2.5d'/'3d'` 或 `{ mode, duration, preserveView }` | 切换场景模式。 |
+| `getSceneMode()` | 无 | 获取当前场景模式。 |
+| `getViewBounds()` | 无 | 获取当前视图经纬度边界。 |
+| `getViewState()` | 无 | 获取当前视图状态。 |
+| `onViewChange(payload)` | `{ onStart, onChange, onEnd, endDelay }` | 监听视图变化，返回 `{ off }`。 |
+| `projectToContainerPoint(payload)` | `{ longitude, latitude, height }` | 经纬度投影到地图容器像素坐标。 |
+
+### 4. 绘制点、线、面、文字和 Marker
+
+这些方法用于轻量绘制和样例验证。大量点位或复杂业务图层请优先使用后文的 `PointLargeLayerController`、`PointDensityController`、`GraphicGroupController` 等控制器。
+
+点：
 
 ```js
 mapCore.drawPoint({
   id: 'point-1',
-  longitude: 104,
-  latitude: 35,
-  style: {
-    color: '#ff4d4f',
-    pixelSize: 10,
-  },
+  name: '点位',
+  // 必填建议：[经度, 纬度]。
+  position: [104, 35],
+  height: 0,
+  // Cesium 使用 pixelSize；Leaflet 使用 radius。
+  pixelSize: 10,
+  radius: 7,
+  color: '#ff4d4f',
 })
+```
 
+线：
+
+```js
 mapCore.drawLine({
   id: 'line-1',
+  name: '连线',
   positions: [
     [103, 34],
     [105, 36],
   ],
-  style: {
-    color: '#1677ff',
-    width: 3,
-  },
+  width: 3,
+  color: '#1677ff',
 })
+```
 
+面：
+
+```js
 mapCore.drawPolygon({
   id: 'polygon-1',
+  name: '区域',
   positions: [
     [102, 33],
     [106, 33],
     [106, 36],
     [102, 36],
   ],
-  style: {
-    color: 'rgba(22, 119, 255, 0.25)',
-    outlineColor: '#1677ff',
-  },
+  // Cesium 使用 fillColor；Leaflet 主要使用 color / fillOpacity。
+  fillColor: 'rgba(22, 119, 255, 0.25)',
+  color: '#1677ff',
+  outlineWidth: 2,
+  fillOpacity: 0.35,
+  // Cesium 默认贴地；显式传 height 时按非贴地面绘制。
+  height: 0,
 })
+```
 
+文字：
+
+```js
 mapCore.drawText({
   id: 'text-1',
-  longitude: 104,
-  latitude: 35,
+  name: '文字',
+  position: [104, 35],
   text: '示例文字',
-  style: {
-    color: '#ffffff',
-    font: '14px sans-serif',
+  font: '16px Microsoft YaHei',
+  color: '#0f2d4d',
+  backgroundColor: 'rgba(255,255,255,0.7)',
+  // 默认 center/bottom，也可以传 left/top/right/bottom。
+  textAnchor: {
+    horizontal: 'center',
+    vertical: 'bottom',
   },
+  textOffset: [0, 0],
 })
+```
 
+图片 Marker：
+
+```js
 mapCore.addMarker({
   id: 'marker-1',
-  longitude: 104,
-  latitude: 35,
-  image: '/marker.png',
-  width: 32,
-  height: 32,
+  name: '站点',
+  position: [104, 35],
+  iconUrl: '/marker.png',
+  iconSize: [32, 32],
+  // 也支持 iconWidth / iconHeight。
+  iconAnchor: [16, 32],
+  iconOffset: [0, 0],
+  label: '站点名称',
 })
+```
+
+清理图形：
 
+```js
 mapCore.removeGraphic({ id: 'marker-1' })
+mapCore.removeGraphic('marker-1')
 mapCore.clearGraphics()
 ```
 
-### 点击事件与投影
+方法说明：
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `drawPoint(payload)` | 点配置 | 绘制点。 |
+| `drawLine(payload)` | 线配置 | 绘制线。 |
+| `drawPolygon(payload)` | 面配置 | 绘制面。 |
+| `drawText(payload)` | 文字配置 | 绘制文字。 |
+| `addMarker(payload)` | Marker 配置 | 绘制图片 Marker；未传 `iconUrl` 时降级为点。 |
+| `removeGraphic(payload)` | 图形 id 或 `{ id }` | 删除指定图形。 |
+| `clearGraphics()` | 无 | 清空通过基础绘制方法创建的图形。 |
+
+
+
+### 6. 点击事件
+
+`onClick` 注册地图点击事件；`offClick` 移除当前点击监听。当前每个 adapter 只保留一个基础点击监听，重复调用 `onClick` 会先移除旧监听。
 
 ```js
-const clickResult = mapCore.onClick({
-  id: 'station-click',
+mapCore.onClick({
   callback(event) {
-    // event 中通常包含 longitude / latitude / pickedObject 等信息，具体字段与引擎有关。
     console.log(event)
   },
 })
 
-mapCore.offClick({ id: 'station-click' })
-
-const point = mapCore.projectToContainerPoint({
-  longitude: 104,
-  latitude: 35,
-  height: 0,
-})
-
-const bounds = mapCore.getViewBounds()
-const viewListener = mapCore.onViewChange({
-  onStart() {},
-  onEnd() {},
-})
-viewListener.data?.off?.()
+mapCore.offClick()
 ```
 
-### DEM
+Cesium 点击空地时的事件结构：
 
 ```js
-mapCore.loadDefaultDEM()
-mapCore.loadDEMById('ellipsoid-flat')
-mapCore.loadDEM({
-  id: 'custom-dem',
-  sourceType: 'url',
-  url: 'https://example.com/terrain',
-  options: {},
-})
+{
+  clickType: 'coordinate',
+  engineType: 'cesium',
+  coordinates: {
+    longitude: 104,
+    latitude: 35,
+    height: 0,
+  },
+}
 ```
 
-DEM 当前主要面向 Cesium；Leaflet 调用会返回不支持结果。
+Cesium 点击 Entity 时的事件结构：
 
-## 图层构造器
+```js
+{
+  clickType: 'entity',
+  engineType: 'cesium',
+  coordinates: {
+    longitude: 104,
+    latitude: 35,
+    height: 0,
+  },
+  target: {
+    id: 'point-1',
+    name: '点位',
+    entityType: 'entity',
+  },
+}
+```
 
-构造器只返回标准配置对象，通常传给 `config.basemap.list` 或 `mapCore.addLayer()`。
+Leaflet 当前返回坐标点击：
 
 ```js
-import {
-  createTiandituLayer,
-  createGeoserverPyramidLayer,
-  createWmsLayer,
-  createWmtsLayer,
-} from '@3clear/basegis/layers'
-
-const tianditu = createTiandituLayer({
-  id: 'tdt-img',
-  name: '天地图影像',
-  resourceKey: 'imagery',
-  category: 'basemap',
-  engineSupport: ['cesium', 'leaflet'],
-})
+{
+  clickType: 'coordinate',
+  engineType: 'leaflet',
+  coordinates: {
+    longitude: 104,
+    latitude: 35,
+    height: 0,
+  },
+}
+```
 
-const geoserverTile = createGeoserverPyramidLayer({
-  id: 'geoserver-tile',
-  name: 'GeoServer 瓦片',
-  url: 'https://example.com/tiles/{z}/{x}/{y}.png',
-})
+说明：
 
-const wms = createWmsLayer({
-  id: 'wms-layer',
-  serviceUrl: 'https://example.com/geoserver/wms',
-  layers: 'workspace:layer',
-  parameters: {
-    transparent: true,
-    format: 'image/png',
-  },
-})
+- 基础 `onClick` 适合地图空白点击、简单 Entity 点击。
+- 海量点、点位抽稀等图层自己的点击事件，应使用对应 Controller 的 `onClick` 参数。
 
-const wmts = createWmtsLayer({
-  id: 'wmts-layer',
-  url: 'https://example.com/wmts?...TILEMATRIX={z}&TILEROW={y}&TILECOL={x}',
-  layer: 'workspace:layer',
-  tileMatrixSet: 'EPSG:3857',
-})
-```
 
 ## GraphicGroupController
 
@@ -430,205 +698,1466 @@ graphics.getState()
 
 ## ImageLayerController
 
-用于加载图片覆盖层或 TIF 图片集合，并提供上一张、下一张、显隐和销毁能力。
+用于管理一个图片覆盖层。所有更新都走 `update(payload)`；页面有很多时次数据时，自己维护数据列表，然后把当前时次的数据传给 `update`。
+
+先创建控制器。这里是控制器级默认参数，后续每次 `update(payload)` 都可以覆盖这些默认值：
 
 ```js
 import { ImageLayerController } from '@3clear/basegis/methods'
 
 const imageLayer = new ImageLayerController({
+  // 必填：BaseGIS 实例。也可以写 baseGIS: mapCore。
   mapCore,
+
+  // 选填：图层 id。不传时默认 image-layer-default。
+  // 后续 show / hide / destroy 会按这个 id 找图层。
   layerId: 'radar-image',
+
+  // 选填：默认透明度，范围通常是 0 - 1。不传时默认 0.85。
   opacity: 0.85,
+
+  // 选填：默认图片四至范围。
+  // 如果 update(payload) 里传 imageUrl，但没有传 area，就会使用这里的 defaultArea。
   defaultArea: {
     startLon: 73,
     startLat: 18,
     endLon: 135,
     endLat: 54,
   },
+
+  // 选填：默认图片类型。color 表示图片已经填色；grayscale 表示灰度图需要运行时着色。
+  imageSourceType: 'color',
+
+  // 选填：默认小数位，网格标注或探针显示数值时使用。
+  decimalPlaces: 2,
 })
+```
 
-await imageLayer.load([
-  {
-    id: 'radar-001',
-    name: '雷达 001',
-    imageUrl: '/data/radar/001.png',
-    area: {
-      startLon: 73,
-      startLat: 18,
+### 1. 普通图片
+
+只显示一张已经处理好的 PNG/JPG。适合雷达图、云图、已填色格点图。
+
+```js
+await imageLayer.update({
+  // 选填：当前数据 id，用于控制器内部记录 activeItem。
+  id: 'radar-202607010800',
+
+  // 选填：当前数据名称，用于状态展示。
+  name: '08:00 雷达',
+
+  // 必填：图片地址。普通图片模式必须传 imageUrl。
+  imageUrl: '/data/radar/202607010800.png',
+
+  // 必填：图片四至范围。只要传 imageUrl，就必须能确定 area。
+  area: {
+    // 必填：左边界经度。
+    startLon: 73,
+    // 必填：下边界纬度。
+    startLat: 18,
+    // 必填：右边界经度。
+    endLon: 135,
+    // 必填：上边界纬度。
+    endLat: 54,
+  },
+
+  // 选填：color 表示图片本身已经填色，不需要再按色带处理。
+  imageSourceType: 'color',
+
+  // 选填：透明度，覆盖控制器默认 opacity。
+  opacity: 0.8,
+
+  // 选填：是否显示图层。不传时使用控制器当前 visible 状态。
+  visible: true,
+})
+```
+
+### 2. 图片 + TIF
+
+图片负责显示，TIF 负责鼠标探针、网格取值、网格注记。
+
+```js
+await imageLayer.update({
+  // 选填：当前数据 id。
+  id: 'temper-202607010900',
+
+  // 选填：当前数据名称。
+  name: '09:00 温度图',
+
+  // 必填：显示用图片地址。
+  imageUrl: '/data/temper/202607010900.png',
+
+  // 必填：取值用 TIF 地址。开启探针或注记时必须有可取值数据。
+  tifUrl: '/data/temper/202607010900.tif',
+
+  // 必填：图片四至范围。
+  area: {
+    startLon: 73,
+    startLat: 18,
+    endLon: 135,
+    endLat: 54,
+  },
+
+  // 选填：显示图是已经填色的图片。
+  imageSourceType: 'color',
+
+  // 选填：是否开启鼠标探针。依赖 tifUrl。
+  showProbe: true,
+
+  // 选填：是否显示网格注记。依赖 tifUrl。
+  showLabel: true,
+
+  // 选填：探针或注记数值的小数位。
+  decimalPlaces: 1,
+
+  // 选填：透明度。
+  opacity: 0.85,
+})
+```
+
+### 3. 灰度图 + 色带
+
+灰度图不是已经填好颜色的图，需要传 `imageSourceType: 'grayscale'` 和 `colorize`。
+
+```js
+await imageLayer.update({
+  // 选填：当前数据 id。
+  id: 'pressure-gray',
+
+  // 选填：当前数据名称。
+  name: '气压灰度图',
+
+  // 必填：灰度图地址。
+  imageUrl: '/data/pressure-gray.png',
+
+  // 必填：灰度图四至范围。
+  area: {
+    startLon: -180,
+    startLat: -90,
+    endLon: 180,
+    endLat: 90,
+  },
+
+  // 必填：灰度图必须声明为 grayscale，适配层才会按 colorize 着色。
+  imageSourceType: 'grayscale',
+
+  // 选填：是否按切片方式处理大图。大范围灰度图建议开启。
+  isSplit: true,
+
+  // 选填：切分网格数量，isSplit 为 true 时使用。
+  gridTotal: 4,
+
+  // 选填：探针或注记数值的小数位。
+  decimalPlaces: 1,
+
+  // 必填：灰度图着色配置。
+  colorize: {
+    // 必填：灰度值或数据值最小值。
+    minValue: 960,
+    // 必填：灰度值或数据值最大值。
+    maxValue: 1040,
+    // 选填：无效值，命中该值时不参与着色。
+    noDataValue: 255,
+    // 必填：色带颜色。支持 16 进制字符串、rgb 字符串或 RGB 数组。
+    colors: ['#2639a7', '#2faaf3', '#8ee5b2', '#fd9919', '#fb422d'],
+  },
+})
+```
+
+`loadGrayImage` 的灰度值换算规则：
+
+```js
+业务值 = (灰度值 - grayMinValue) / (grayMaxValue - grayMinValue) * (maxValue - minValue) + minValue
+```
+
+所以灰度图要表达真实业务值时，建议显式传 `minValue / maxValue`。如果只写 `colorize: true`，会使用默认范围 `minValue: 0`、`maxValue: 1`、`grayMinValue: 1`、`grayMaxValue: 254`，只适合临时预览，不适合正式业务图层。
+
+`loadGrayImage` 支持两种写法：
+
+```js
+await gridLayer.loadGrayImage({
+  imageUrl: '/data/grid/temp-gray.png',
+  area,
+  colorize: {
+    minValue: -20,
+    maxValue: 50,
+    colors: ['#2639a7', '#2faaf3', '#8ee5b2', '#fd9919', '#fb422d'],
+  },
+})
+
+await gridLayer.loadGrayImage({
+  imageUrl: '/data/grid/temp-gray.png',
+  area,
+  minValue: -20,
+  maxValue: 50,
+  grayMinValue: 1,
+  grayMaxValue: 254,
+  colors: ['#2639a7', '#2faaf3', '#8ee5b2', '#fd9919', '#fb422d'],
+})
+```
+### 4. 纯 TIF
+
+只传 TIF，不传图片。适合数据本身带地理范围、需要按 TIF 渲染的场景。
+
+```js
+await imageLayer.update({
+  // 选填：当前数据 id。
+  id: 'rain-tif',
+
+  // 必填建议：纯 TIF 模式下显式清空 imageUrl，避免沿用上一次图片。
+  imageUrl: '',
+
+  // 必填：TIF 地址。
+  tifUrl: '/data/rain.tif',
+
+  // 选填：是否按默认色带着色。需要更精细控制时传 colorize 对象。
+  colorize: true,
+
+  // 选填：是否开启鼠标探针。
+  showProbe: true,
+})
+```
+
+### 5. 很多时次数据怎么更新
+
+很多数据不要用 `next()`。页面维护数组，点击或时间轴变化时，把当前项传给 `update()`。
+
+```js
+const imageDataSources = [
+  {
+    // 必填：业务自己的时次 key。
+    key: '202607010800',
+    // 必填：当前时次图片地址。
+    imageUrl: '/data/radar/202607010800.png',
+  },
+  {
+    key: '202607010900',
+    imageUrl: '/data/radar/202607010900.png',
+  },
+]
+
+async function updateImageByTime(timeKey) {
+  const source = imageDataSources.find((item) => item.key === timeKey)
+  if (!source) return
+
+  await imageLayer.update({
+    // 选填：用时次 key 作为当前数据 id。
+    id: source.key,
+
+    // 必填：当前时次图片地址。
+    imageUrl: source.imageUrl,
+
+    // 必填：图片四至范围。
+    area: {
+      startLon: 73,
+      startLat: 18,
       endLon: 135,
       endLat: 54,
     },
-    opacity: 0.8,
+
+    // 选填：普通已填色图片使用 color。
+    imageSourceType: 'color',
+
+    // 选填：更新时间后直接显示图层。
+    visible: true,
+  })
+}
+```
+
+### 6. 控制方法
+
+`ImageLayerController` 除了 `update(payload)`，还提供显隐、销毁、状态读取和兼容旧集合模式的方法。
+
+```js
+// 创建或更新当前图片图层。
+await imageLayer.update({
+  imageUrl: '/data/radar/202607010800.png',
+  area: {
+    startLon: 73,
+    startLat: 18,
+    endLon: 135,
+    endLat: 54,
+  },
+})
+
+// 隐藏当前控制器对应的图片图层。
+imageLayer.hide()
+
+// 重新显示当前控制器对应的图片图层。
+imageLayer.show()
+
+// 读取当前控制器状态。
+const state = imageLayer.getState()
+
+// 移除地图上的图片图层，并清空控制器本地状态。
+imageLayer.destroy()
+```
+
+如果一个控制器需要临时操作其他图片图层，可以传入 `layerId`；也可以直接传字符串：
+
+```js
+imageLayer.show({ layerId: 'radar-image' })
+imageLayer.hide('radar-image')
+imageLayer.destroy({ layerId: 'radar-image' })
+```
+
+方法总表：
+
+| 方法 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| `mount(target)` | `BaseGIS` 实例 | `Result` | 绑定 `BaseGIS`。构造时已传 `mapCore/baseGIS` 时通常不需要手动调用。 |
+| `update(payload)` | 图片图层数据 | `Promise<Result>` | 推荐主入口。创建或更新当前图片图层，支持普通图片、图片+TIF、灰度图+色带、纯 TIF。 |
+| `show(payload)` | 可选 `layerId` 或 `{ layerId }` | `Result` | 显示图片图层。成功后控制器 `visible` 变为 `true`。 |
+| `hide(payload)` | 可选 `layerId` 或 `{ layerId }` | `Result` | 隐藏图片图层。成功后控制器 `visible` 变为 `false`。 |
+| `destroy(payload)` | 可选 `layerId` 或 `{ layerId }` | `Result` | 移除图片图层，并清空 `items / activeIndex / layerType / currentPayload`。如果地图已销毁，只清本地状态。 |
+| `getState()` | 无 | `Object` | 获取控制器状态。 |
+| `load(items, options)` | 图片数组、可选 `{ index, visible }` | `Promise<Result>` | 兼容旧的图片集合加载方式，会加载 `items[index]`。 |
+| `switchTo(target)` | 图片索引或图片 id | `Promise<Result>` | 在 `load` 后的本地图片集合中切换当前图片。 |
+| `next()` | 无 | `Promise<Result>` | 切到下一张本地图片。只适合本地小数组演示，不推荐作为业务时次更新主路径。 |
+| `prev()` | 无 | `Promise<Result>` | 切到上一张本地图片。只适合本地小数组演示，不推荐作为业务时次更新主路径。 |
+
+`getState()` 返回结构：
+
+```js
+{
+  mounted: true,
+  engineType: 'cesium',
+  layerType: 'image',
+  visible: true,
+  total: 1,
+  activeIndex: 0,
+  activeItem: {
+    id: 'radar-202607010800',
+    imageUrl: '/data/radar/202607010800.png',
+  },
+  payload: {
+    layerId: 'radar-image',
+    imageUrl: '/data/radar/202607010800.png',
+    opacity: 0.85,
+  },
+}
+```
+
+### 参数总表
+
+| 参数 | 是否必填 | 说明 |
+| --- | --- | --- |
+| `mapCore` / `baseGIS` | 创建控制器必填 | `BaseGIS` 实例。 |
+| `layerId` | 选填 | 图层 id，不传默认 `image-layer-default`。 |
+| `defaultArea` | 选填 | 默认图片范围，`update` 未传 `area` 时使用。 |
+| `id` | 选填 | 当前数据 id，便于状态记录。 |
+| `name` | 选填 | 当前数据名称，便于页面展示。 |
+| `imageUrl` | 普通图片、灰度图、图片+TIF 必填 | 图片地址。纯 TIF 模式建议传空字符串清掉旧图片。 |
+| `tifUrl` | 纯 TIF、图片+TIF 必填 | GeoTIFF 地址，用于渲染、探针或网格注记。 |
+| `area` | 传 `imageUrl` 时必填 | 图片范围：`startLon / startLat / endLon / endLat`。 |
+| `imageSourceType` | 灰度图必填，其他选填 | `color` 表示已填色图片；`grayscale` 表示灰度图。 |
+| `colorize` | 灰度图必填，TIF 着色选填 | 色带配置，或传 `true` 使用默认着色。 |
+| `colorize.minValue` | 灰度图必填 | 色带映射最小值。 |
+| `colorize.maxValue` | 灰度图必填 | 色带映射最大值。 |
+| `colorize.noDataValue` | 选填 | 无效值。 |
+| `colorize.colors` | 灰度图必填 | 色带颜色数组。 |
+| `opacity` | 选填 | 透明度，通常 0 - 1。 |
+| `visible` | 选填 | 是否显示图层。 |
+| `showProbe` | 选填 | 是否开启鼠标探针，通常依赖 `tifUrl`。 |
+| `showLabel` | 选填 | 是否显示网格注记，通常依赖 `tifUrl`。 |
+| `decimalPlaces` | 选填 | 探针或注记数值小数位。 |
+| `isSplit` | 选填 | 是否切片处理大图。 |
+| `gridTotal` | 选填 | 切片网格数量。 |
+| `tileSize` | 选填 | 切片尺寸。 |
+
+兼容方法：
+
+- `load(items, { index, visible })`：兼容旧的图片集合加载方式，会把 `items[index]` 写入当前图层。
+- `switchTo(idOrIndex)`：在已加载的 `items` 内切换到某一项。
+- `next() / prev()`：只适合本地小数组演示，不推荐作为业务时次更新主路径。
+
+## GridLayerController
+
+用于 TIF 网格、灰度图网格、外部数值网格。
+
+```js
+import { GridLayerController } from '@3clear/basegis/methods'
+
+const gridLayer = new GridLayerController({
+  mapCore,
+  layerId: 'temperature-grid',
+  showLabel: true,
+  showProbe: true,
+  decimalPlaces: 1,
+})
+
+await gridLayer.loadTif({
+  tifUrl: '/data/grid/temp.tif',
+  colorize: true,
+})
+
+await gridLayer.loadGrayImage({
+  imageUrl: '/data/grid/temp-gray.png',
+  area: {
+    startLon: 73,
+    startLat: 18,
+    endLon: 135,
+    endLat: 54,
+  },
+  // 灰度图需要把灰度值映射成业务值，再按业务值找色带。
+  colorize: {
+    // 必填建议：业务值最小值。
+    minValue: -20,
+    // 必填建议：业务值最大值。
+    maxValue: 50,
+    // 选填：灰度有效最小值，不传默认 1。
+    grayMinValue: 1,
+    // 选填：灰度有效最大值，不传默认 254。
+    grayMaxValue: 254,
+    // 选填：无效灰度值，不传默认 255。
+    noDataValue: 255,
+  },
+})
+
+await gridLayer.loadData({
+  imageGridData: [
+    [12.1, 13.4],
+    [14.2, 15.6],
+  ],
+  area: {
+    startLon: 100,
+    startLat: 30,
+    endLon: 110,
+    endLat: 40,
+  },
+})
+
+gridLayer.update({ opacity: 0.7 })
+gridLayer.hide()
+gridLayer.show()
+gridLayer.destroy()
+```
+
+## 三维体渲染
+
+三维体渲染是 Cesium 专有能力，直接通过 `BaseGIS` 调用。Leaflet 调用时会返回不支持结果，不会抛出破坏页面的异常。
+
+适合体数据云图、污染物三维浓度、气象三维场等需要在一个三维盒子内做体积采样的场景。
+
+### 基础用法
+
+```js
+const result = mapCore.upsertVolumeLayer({
+  // 建议必填：图层唯一 id。再次使用同一个 layerId 调用会覆盖旧体渲染层。
+  layerId: 'volume-demo',
+
+  // 必填：体数据一维数组，长度通常为 rows * cols * heights。
+  data: volumeValues,
+
+  // 必填：体数据范围和网格尺寸。
+  option: {
+    // 经度范围。
+    xmin: 110,
+    xmax: 120,
+    // 纬度范围。
+    ymin: 30,
+    ymax: 40,
+    // 高度范围，单位按业务数据约定。
+    zmin: 0,
+    zmax: 10000,
+    // 纬向、经向、高度向网格数量。
+    rows: 100,
+    cols: 100,
+    heights: 30,
+  },
+
+  // 选填：体渲染 shader 参数，可后续单独更新。
+  parameters: {
+    // 采样阈值。值越小，通常显示范围越少；具体效果和数据归一化有关。
+    threshold: 0.3,
+    // 光线步进采样次数。越大越细腻，也越耗性能。
+    steps: 100,
+    // x/y/z 三个方向裁切位置，默认 -0.5 表示不裁切。
+    xCut: -0.5,
+    yCut: -0.5,
+    zCut: -0.5,
+  },
+
+  // 选填：初始是否显示。
+  visible: true,
+})
+
+if (!result.success) {
+  console.warn(result.message)
+}
+```
+
+### 更新参数
+
+更新透明阈值、步进数、裁切面时，不需要重新加载体数据，直接更新参数即可。
+
+```js
+mapCore.updateVolumeLayerParameters({
+  layerId: 'volume-demo',
+  parameters: {
+    threshold: 0.5,
+    steps: 180,
+    zCut: 0.1,
+  },
+})
+```
+
+### 更新数据
+
+更新数据或空间范围时，继续使用同一个 `layerId` 调用 `upsertVolumeLayer`。适配层会先移除旧 Primitive，再创建新的体渲染层。
+
+```js
+mapCore.upsertVolumeLayer({
+  layerId: 'volume-demo',
+  data: nextVolumeValues,
+  option: nextVolumeOption,
+  parameters: currentParameters,
+})
+```
+
+### 显隐、定位和移除
+
+```js
+mapCore.hideVolumeLayer({ layerId: 'volume-demo' })
+mapCore.showVolumeLayer({ layerId: 'volume-demo' })
+mapCore.flyToVolumeLayer({ layerId: 'volume-demo', duration: 0.8 })
+mapCore.removeVolumeLayer({ layerId: 'volume-demo' })
+
+const stateResult = mapCore.getVolumeLayerState({ layerId: 'volume-demo' })
+console.log(stateResult.data)
+```
+
+### 方法总表
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `upsertVolumeLayer(payload)` | 体渲染配置 | 创建或更新体渲染层。同 `layerId` 会覆盖旧图层。 |
+| `updateVolumeLayerParameters(payload)` | `{ layerId, parameters }` | 更新体渲染 shader 参数，不重新加载体数据。 |
+| `showVolumeLayer(payload)` | `{ layerId }` | 显示体渲染层。 |
+| `hideVolumeLayer(payload)` | `{ layerId }` | 隐藏体渲染层。 |
+| `removeVolumeLayer(payload)` | `{ layerId }` | 移除体渲染层并释放 Primitive。 |
+| `flyToVolumeLayer(payload)` | `{ layerId, duration }` | 飞到体渲染层经纬度范围。 |
+| `getVolumeLayerState(payload)` | `{ layerId }` | 获取图层状态。 |
+
+### 参数总表
+
+| 参数 | 是否必填 | 说明 |
+| --- | --- | --- |
+| `layerId` / `volumeLayerId` / `id` | 建议必填 | 体渲染图层 id，不传默认 `volume-default`。 |
+| `data` / `value` / `values` | 必填 | 体数据一维数组，通常按层、行、列展开。 |
+| `option` | 必填 | 体数据空间范围和网格尺寸。 |
+| `option.xmin / xmax` | 必填 | 经度最小值和最大值。 |
+| `option.ymin / ymax` | 必填 | 纬度最小值和最大值。 |
+| `option.zmin / zmax` | 必填 | 高度最小值和最大值。 |
+| `option.rows` | 必填 | 纬向网格数量。 |
+| `option.cols` | 必填 | 经向网格数量。 |
+| `option.heights` | 必填 | 高度层数量。 |
+| `parameters.threshold` | 选填 | 采样阈值。 |
+| `parameters.steps` | 选填 | 光线步进采样次数。 |
+| `parameters.xCut / yCut / zCut` | 选填 | 三个方向的裁切位置，默认 `-0.5`。 |
+| `colorRamp` / `colors` / `colorKeys` | 选填 | 自定义色带配置。 |
+| `geometry` / `dim` | 选填 | 自定义体渲染几何或维度，普通业务通常不需要传。 |
+| `visible` | 选填 | 初始是否显示，默认显示。 |
+
+## 三维切片 / 剖面渲染
+
+三维切片/剖面渲染也是 Cesium 专有能力，直接通过 `BaseGIS` 调用。它把三维网格数据按 X、Y、Z 三个方向切出剖面，适合气象温度、湿度、风场标量、污染物浓度等三维格点数据查看。
+
+这里的“切片”指三维数据剖面，不是 `ImageLayerController` 里的大图切片。
+
+### 数据格式
+
+```js
+const sectionData = {
+  Bound: [
+    1000,      // 0: LayerMax，最高气压层或起始层值。
+    108.68,    // 1: LonMin，经度最小值。
+    28.59,     // 2: LatMin，纬度最小值。
+    10,        // 3: LayerNums，层数。
+    147,       // 4: LonNums，经向格点数。
+    198,       // 5: LatNums，纬向格点数。
+    900,       // 6: DLayer 或 LayerMin 相关值，按数据生成规则提供。
+    16.74,     // 7: DLon，经度跨度。
+    16.71,     // 8: DLat，纬度跨度。
+    1,         // 9: ValueScale，数值缩放。
+    1,         // 10: 预留/数据标记。
+    [1000, 925, 850, 700, 600, 500, 400, 300, 200, 100], // 11: LayerList，气压层列表。
+  ],
+  // 必填：三维格点值一维数组，长度通常为 LayerNums * LatNums * LonNums。
+  DataAry: valueList,
+}
+
+const optionData = {
+  Item: 'TEMP',
+  Values: [-30, -20, -10, 0, 10, 20, 30],
+  Colors: [
+    [30, 80, 180],
+    [50, 160, 220],
+    [120, 220, 180],
+    [250, 230, 120],
+    [240, 150, 80],
+    [220, 80, 60],
+    [160, 30, 30],
+  ],
+}
+```
+
+### 加载或更新数据
+
+同一个 `layerId` 重复调用 `upsertSectionLayer` 就是更新数据。适配层会清理旧切片，再加载新数据。
+
+```js
+const result = mapCore.upsertSectionLayer({
+  // 建议必填：切片图层唯一 id。
+  layerId: 'section-demo',
+
+  // 必填：包含 Bound / DataAry 的三维剖面数据。
+  dataInfo: sectionData,
+
+  // 选填：数据类型，传给色标取色逻辑。
+  itemType: optionData.Item,
+
+  // 必填建议：色标配置。
+  colorInfo: {
+    valueAry: optionData.Values,
+    rgbAry: optionData.Colors,
+  },
+
+  // 选填：是否显示坐标轴和刻度。
+  showAxis: false,
+})
+
+if (!result.success) {
+  console.warn(result.message)
+  return
+}
+
+const state = result.data.state
+console.log(state.XRange, state.YRange, state.ZRange)
+```
+
+### 渲染 X / Y / Z 切片
+
+```js
+// X 经度方向切片。
+mapCore.renderSectionLayer({
+  layerId: 'section-demo',
+  sectionType: 0,
+  value: 116.4,
+})
+
+// Y 纬度方向切片。
+mapCore.renderSectionLayer({
+  layerId: 'section-demo',
+  sectionType: 1,
+  value: 39.9,
+})
+
+// Z 高度/气压方向切片。
+mapCore.renderSectionLayer({
+  layerId: 'section-demo',
+  sectionType: 2,
+  value: 850,
+})
+```
+
+`sectionType` 含义：
+
+| 值 | 含义 | `value` |
+| --- | --- | --- |
+| `0` | 经度方向剖面 | 经度值。 |
+| `1` | 纬度方向剖面 | 纬度值。 |
+| `2` | 高度/气压方向剖面 | 气压层或高度层值。 |
+| `3` | 全量剖面 | 可不传 `value`。 |
+
+### 显隐、移除和定位
+
+```js
+// 隐藏或显示全部切片。
+mapCore.hideSectionLayer({ layerId: 'section-demo' })
+mapCore.showSectionLayer({ layerId: 'section-demo' })
+
+// 只移除 Z 切片，X/Y 不受影响。
+mapCore.removeSectionLayer({
+  layerId: 'section-demo',
+  sectionType: 2,
+})
+
+// 移除整个切片图层。
+mapCore.removeSectionLayer({ layerId: 'section-demo' })
+
+// 飞到切片数据范围。
+mapCore.flyToSectionLayer({ layerId: 'section-demo', duration: 0.8 })
+```
+
+### hover 取值
+
+页面先用 Cesium 拾取得到鼠标所在三维点，再交给 `sampleSectionLayerValue` 计算当前切片上的数值。
+
+```js
+const result = mapCore.sampleSectionLayerValue({
+  layerId: 'section-demo',
+  lon: 116.4,
+  lat: 39.9,
+  hpa: 850,
+  // 选填：Z 切片关闭时传 false，避免 hover 命中已隐藏的 Z 切片。
+  showZLayer: true,
+})
+
+if (result.success) {
+  console.log(result.data)
+  // { lon, lat, hpa, sectionType, value }
+}
+```
+
+### 方法总表
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `upsertSectionLayer(payload)` | 切片数据与色标配置 | 创建或更新切片图层。同 `layerId` 会覆盖旧图层。 |
+| `renderSectionLayer(payload)` | `{ layerId, sectionType, value }` | 渲染指定方向切片。 |
+| `showSectionLayer(payload)` | `{ layerId, sectionType }` | 显示切片。不传 `sectionType` 时显示全部。 |
+| `hideSectionLayer(payload)` | `{ layerId, sectionType }` | 隐藏切片。不传 `sectionType` 时隐藏全部。 |
+| `removeSectionLayer(payload)` | `{ layerId, sectionType }` | 移除切片。不传 `sectionType` 时移除整个图层。 |
+| `flyToSectionLayer(payload)` | `{ layerId, duration }` | 飞到切片数据范围。 |
+| `getSectionLayerState(payload)` | `{ layerId }` | 获取切片图层状态。 |
+| `sampleSectionLayerValue(payload)` | `{ layerId, lon, lat, hpa, showZLayer }` | 根据拾取位置计算当前切片数值。 |
+
+### 参数总表
+
+| 参数 | 是否必填 | 说明 |
+| --- | --- | --- |
+| `layerId` / `sectionLayerId` / `id` | 建议必填 | 切片图层 id，不传默认 `section-default`。 |
+| `dataInfo` / `data` | 必填 | 三维切片数据，必须包含 `Bound / DataAry`。 |
+| `dataInfo.Bound` | 必填 | 数据范围、网格数量、层级列表等元信息。 |
+| `dataInfo.DataAry` | 必填 | 三维格点值一维数组。 |
+| `itemType` | 选填 | 数据类型，传给色标取色逻辑。 |
+| `colorInfo.valueAry` | 建议必填 | 色标分级值数组。 |
+| `colorInfo.rgbAry` | 建议必填 | 色标 RGB 数组。 |
+| `boxInfo` | 选填 | 自定义剖面盒子范围。不传时根据 `dataInfo` 自动生成。 |
+| `showAxis` | 选填 | 是否显示坐标轴和刻度。 |
+| `sectionType` | 渲染、显隐、移除单个切片时必填 | `0` 经度，`1` 纬度，`2` 高度/气压，`3` 全量。 |
+| `value` / `param` | `sectionType` 为 `0/1/2` 时必填 | 切片位置值。 |
+| `lon / lat / hpa` | hover 取值必填 | Cesium 拾取得到的经度、纬度、气压高度。 |
+| `showZLayer` | hover 取值选填 | Z 切片是否参与 hover 命中，默认参与。 |
+
+## PointLargeLayerController
+
+用于海量点位渲染。它会尽量把传入的有效点位全部渲染出来，适合站点、设备、告警、监测点等需要保留全部点位并支持点击、高亮、删除、显隐的场景。
+
+如果业务目标是“地图缩小时按屏幕网格抽稀，只显示代表点”，应使用后文的 `PointDensityController`。
+
+### Demo 位置
+
+仓库内已有对应 demo：
+
+- 路由：`/test-page-5`
+- 页面：`src/views/test-page-5/index.vue`
+- 当前 demo 覆盖能力：加载、更新、显隐、高亮、取消高亮、删除点位、清空、销毁、状态读取、视角复位。
+
+demo 源码内部使用：
+
+```js
+import { BaseGIS } from '@/gis'
+import { PointLargeLayerController } from '@/gis/methods'
+```
+
+npm 包外部项目使用：
+
+```js
+import { BaseGIS } from '@3clear/basegis'
+import { PointLargeLayerController } from '@3clear/basegis/methods'
+```
+
+### 使用方式一：构造时传入 mapCore
+
+这是业务页面里最常用的写法。地图初始化完成后创建控制器，再调用 `load` 加载点位。
+
+```js
+const mapCore = new BaseGIS({
+  engineType: 'leaflet',
+  containerId: 'map',
+})
+
+const initResult = mapCore.init()
+if (!initResult.success) {
+  console.warn(initResult.message)
+}
+
+const pointLayer = new PointLargeLayerController({
+    // 必填：BaseGIS 实例。
+    mapCore,
+    // 建议必填：图层唯一 ID，后续显隐、高亮、删除都基于这个图层。
+    layerId: 'station-large',
+    // 选填：点位唯一值字段，不传默认使用 id。
+    idKey: 'stationCode',
+
+    // 点位数据。也可以使用 data/items 字段；推荐统一使用 points。
+    points,
+
+    // 初始是否显示图层。不传时默认 true。
+    visible: true,
+
+    // 默认普通状态图标。支持图片 URL、base64、data URL。
+    icon: normalPointIcon,
+
+    // 默认高亮状态图标。调用 setHighlight(id) 后使用。
+    highlightIcon: highlightPointIcon,
+
+    // 样式规则读取的字段名。下面 styleRules 里的 gt/default 会基于 value 判断。
+    styleField: 'value',
+
+    // 点位样式规则。从上到下匹配，命中后使用该规则里的 icon/highlightIcon/style 等配置。
+    styleRules: [
+        {
+            // value < 300 时命中
+            lt: 300,
+            icon: lowPointIcon,
+            highlightIcon: highlightPointIcon,
+        },
+        {
+            // value > 780 时命中
+            gt: 780,
+            icon: warningPointIcon,
+            highlightIcon: highlightPointIcon,
+        },
+        {
+            // 300 <= value < 780
+            gte: 300,
+            lt: 780,
+            icon: normalPointIcon,
+            highlightIcon: highlightPointIcon,
+        },
+        {
+            // 兜底规则。没有命中前面规则的点位使用普通图标。
+            default: true,
+            icon: normalPointIcon,
+            highlightIcon: highlightPointIcon,
+        },
+    ],
+
+    // 普通图标宽度，单位像素。
+    width: 18,
+
+    // 普通图标高度，单位像素。
+    height: 18,
+
+    // 普通图标缩放比例。
+    scale: 1,
+
+    // 未传 icon 时，可以使用内置圆点图标。下面这些配置用于控制圆点样式。
+    // color: '#19d3a2',
+    // outlineColor: '#ffffff',
+    // outlineWidth: 2,
+
+    // 未传 highlightIcon 时，可以使用内置高亮圆点图标。下面这些配置用于控制高亮圆点样式。
+    // highlightColor: '#ffcf33',
+    // highlightOutlineColor: '#ffffff',
+    // highlightWidth: 20,
+    // highlightHeight: 20,
+    // highlightScale: 1.18,
+
+    // 分帧构建批量大小。点位很多时可以调大或调小，默认 5000。
+    // chunkSize: 10000,
+
+    // Cesium 专用：禁用深度检测距离。需要点位不被地形或模型遮挡时可使用。
+    // disableDepthTestDistance: Number.POSITIVE_INFINITY,
+
+    // Cesium 专用：按相机距离缩放图标。
+    // 数组含义：[近距离, 近距离缩放, 远距离, 远距离缩放]。
+    // scaleByDistance: [50000, 1, 9000000, 0.34],
+
+    // 点击点位回调。event.data 是原始点位数据。
+    onClick: ({ id, data }) => {`点击点位：${data || id}。`},
+    
+})
+
+await pointLayer.load({
+  points: [
+    {
+      stationCode: 'A001',
+      name: '站点 A001',
+      longitude: 104,
+      latitude: 35,
+      value: 86,
+    },
+  ],
+})
+```
+
+`styleRules` 常用匹配方式：
+
+| 写法                                                | 说明 |
+|---------------------------------------------------| --- |
+| `{ field: 'aqi', min: 51, max: 100 }`             | 指定字段并按区间匹配。 |
+| `{ gt: 780 }`                                     | 使用 `styleField` 指定的字段做大于判断。 |
+| `{ gte: 51, lt: 101 }`                            | 使用 `styleField` 指定的字段做区间判断。 |
+| `{ values: ['优', '良'] }`                          | 命中指定值集合。 |
+| `{ operator: '>', value: 100 }`                   | 使用操作符匹配，支持 `> / >= / < / <= / == / === / != / !== / in`。 |
+| `{ when:(point, index, record) { return true } }` | 完全自定义匹配函数。 |
+| `{ default: true }`                               | 兜底规则。 |
+
+
+
+
+### 使用方式：更新数据或样式
+
+时间轴、实时刷新等场景中，建议复用同一个控制器实例，不要每次刷新都重新 `new PointLargeLayerController()`。
+
+```js
+await pointLayer.load({
+  points: firstPoints,
+  icon: normalIcon,
+})
+
+// 替换下一批点位。
+await pointLayer.update({
+  points: nextPoints,
+})
+
+// 只更新样式规则。
+await pointLayer.update({
+  styleField: 'value',
+  styleRules: nextStyleRules,
+})
+```
+
+
+### 点位数据格式
+
+默认支持以下坐标字段：
+
+- 经度：`longitude / lon / lng / x`
+- 纬度：`latitude / lat / y`
+- 高度：`height / altitude / z`
+- 唯一值：默认 `id`，可通过 `idKey` 指定
+
+```js
+const points = [
+  {
+    id: 'large-point-1',
+    name: '点位 1',
+    longitude: 104.1234,
+    latitude: 35.1234,
+    height: 0,
+    value: 820,
+    level: '高',
+  },
+]
+```
+
+### 事件回调
+
+```js
+await pointLayer.load({
+  points,
+  onClick(event) {
+    console.log(event.id)
+    console.log(event.data)
   },
-  {
-    id: 'tif-001',
-    name: 'TIF 001',
-    tifUrl: '/data/grid/001.tif',
-    colorize: true,
+  onHover(event) {
+    console.log(event.id)
   },
-])
-
-await imageLayer.switchTo('radar-001')
-await imageLayer.next()
-await imageLayer.prev()
-imageLayer.hide()
-imageLayer.show()
-imageLayer.destroy()
+  onHoverIn(event) {
+    console.log('进入点位', event.id)
+  },
+  onHoverOut(event) {
+    console.log('离开点位', event.id)
+  },
+  tooltipFormatter(event) {
+    return `${event.data.name}：${event.data.value}`
+  },
+})
 ```
 
-常用字段：
+事件对象常用字段：
 
-- `imageUrl`：普通图片地址。
-- `tifUrl`：GeoTIFF 地址。
-- `area`：图片四至范围，字段为 `startLon / startLat / endLon / endLat`。
-- `opacity`：透明度。
-- `showLabel / showProbe`：显示网格标注或探针。
-- `colorize / colorStops / colors`：色带渲染配置。
+| 字段 | 说明 |
+| --- | --- |
+| `layerId` | 图层 ID。 |
+| `id` | 点位唯一值。 |
+| `key` | 内部点位 key，通常与 `id` 一致。 |
+| `index` | 点位在当前数据中的索引。 |
+| `data` | 原始点位数据。 |
+| `record` | 标准化后的点位记录。 |
+| `layer` | 引擎侧海量点图层实例。 |
+| `movement` | Cesium 鼠标事件对象。 |
+| `mapEvent` | Leaflet 鼠标事件对象。 |
+| `picked` / `billboard` / `sprite` | 引擎拾取结果，按当前引擎返回。 |
 
-## GridLayerController
-
-用于 TIF 网格、灰度图网格、外部数值网格。
+### 常用方法
 
 ```js
-import { GridLayerController } from '@3clear/basegis/methods'
+// 显示 / 隐藏 / 切换显隐。
+pointLayer.show()
+pointLayer.hide()
+pointLayer.toggle()
+pointLayer.toggle(true)
 
-const gridLayer = new GridLayerController({
-  mapCore,
-  layerId: 'temperature-grid',
-  showLabel: true,
-  showProbe: true,
-  decimalPlaces: 1,
-})
+// 高亮 / 取消高亮。
+pointLayer.setHighlight('A001')
+pointLayer.highlight('A001')
+pointLayer.clearHighlight()
 
-await gridLayer.loadTif({
-  tifUrl: '/data/grid/temp.tif',
-  colorize: true,
-})
+// 删除单点 / 批量删除。
+pointLayer.removePoint('A001')
+pointLayer.deletePoint('A001')
+await pointLayer.removePoints(['A001', 'A002'])
 
-await gridLayer.loadGrayImage({
-  imageUrl: '/data/grid/temp-gray.png',
-  area: {
-    startLon: 73,
-    startLat: 18,
-    endLon: 135,
-    endLat: 54,
-  },
-  colorize: true,
-})
+// 清空点位，但保留图层实例。
+pointLayer.clear()
 
-await gridLayer.loadData({
-  imageGridData: [
-    [12.1, 13.4],
-    [14.2, 15.6],
-  ],
-  area: {
-    startLon: 100,
-    startLat: 30,
-    endLon: 110,
-    endLat: 40,
-  },
-})
+// 从引擎侧重新读取状态。
+pointLayer.refreshState()
 
-gridLayer.update({ opacity: 0.7 })
-gridLayer.hide()
-gridLayer.show()
-gridLayer.destroy()
+// 销毁图层。
+pointLayer.destroy()
+
+// 读取当前状态。
+pointLayer.getState()
 ```
 
-## PointLargeLayerController
+方法说明：
+
+| 方法 | 说明 |
+| --- | --- |
+| `mount(mapCore)` | 挂载 `BaseGIS` 实例。构造时已传 `mapCore/baseGIS` 时通常不需要手动调用。 |
+| `load(payload, options)` | 加载或覆盖海量点数据。支持 `load(points, options)` 和 `load({ points, ...options })`。 |
+| `upsert(payload, options)` | `load` 的别名。 |
+| `update(payload)` | 基于当前配置合并更新。可替换点位，也可只更新样式、图标、显隐参数。 |
+| `show(payload)` | 显示图层。 |
+| `hide(payload)` | 隐藏图层。 |
+| `toggle(visible)` | 切换显隐。不传 `visible` 时按当前状态取反。 |
+| `setHighlight(id, payload)` | 高亮指定点位。别名：`highlight`、`setHighlighted`。 |
+| `clearHighlight(payload)` | 清除当前高亮。别名：`clearHighlighted`。 |
+| `removePoint(id, payload)` | 删除单个点位。别名：`deletePoint`、`removeById`。 |
+| `removePoints(ids, payload)` | 批量删除点位。别名：`deletePoints`、`removeByIds`。 |
+| `clear(payload)` | 清空图层点位数据，但保留图层实例。 |
+| `refreshState(payload)` | 从引擎侧重新读取图层状态。 |
+| `destroy(payload)` | 销毁图层并释放资源。别名：`removeLayer`。 |
+| `getState()` | 读取控制器状态。 |
+
+### 构造和加载参数
+
+| 参数 | 是否必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `mapCore` / `baseGIS` | 构造时建议必填 | - | `BaseGIS` 实例。也可以后续通过 `mount(mapCore)` 挂载。 |
+| `layerId` / `pointLargeLayerId` / `largeLayerId` / `id` | 否 | `point-large-default` | 海量点图层 ID。 |
+| `visible` | 否 | `true` | 初始是否显示。 |
+| `idKey` | 否 | `id` | 点位唯一值字段。高亮、删除单点依赖该值。 |
+| `points` / `data` / `items` | 加载时必填其一 | - | 点位数组。 |
+| `longitudeKeys` | 否 | `['longitude', 'lon', 'lng', 'x']` | 经度字段候选列表。 |
+| `latitudeKeys` | 否 | `['latitude', 'lat', 'y']` | 纬度字段候选列表。 |
+| `heightKeys` | 否 | `['height', 'altitude', 'z']` | 高度字段候选列表。 |
+| `image` / `icon` / `iconUrl` / `imageUrl` | 否 | - | 普通状态图标。未传时使用内置圆点图标。 |
+| `highlightImage` / `highlightIcon` / `highlightIconUrl` / `highlightImageUrl` | 否 | - | 高亮状态图标。未传时使用高亮圆点图标。 |
+| `width` / `height` | 否 | `32` | 普通图标尺寸。 |
+| `scale` | 否 | `1` | 普通图标缩放比例。 |
+| `color` / `outlineColor` / `outlineWidth` | 否 | `#1e88e5` / `#fff` / `2` | 未传图标时的内置圆点样式。 |
+| `highlightColor` / `highlightOutlineColor` / `highlightOutlineWidth` | 否 | `#ffcc00` / `#fff` / `3` | 未传高亮图标时的高亮圆点样式。 |
+| `highlightWidth` / `highlightHeight` / `highlightScale` | 否 | `36` / `36` / `scale * 1.35` | 高亮图标尺寸和缩放。 |
+| `styleField` / `valueKey` | 否 | `value` | `styleRules` 默认读取的业务值字段。 |
+| `styleRules` | 否 | `[]` | 点位分级样式规则。 |
+| `imageCallback` | 否 | - | 自定义返回点位图标。 |
+| `styleCallback` | 否 | - | 自定义返回普通状态样式。 |
+| `highlightStyleCallback` | 否 | - | 自定义返回高亮状态样式。 |
+| `showTooltip` | 否 | `true` | 是否显示内置悬浮提示。 |
+| `tooltipFormatter` | 否 | - | 自定义悬浮提示内容。 |
+| `tooltipOffset` | 否 | `[14, 14]` | 悬浮提示偏移。 |
+| `tooltipClassName` | 否 | - | 悬浮提示 DOM class。 |
+| `onClick` / `onHover` / `onHoverIn` / `onHoverOut` | 否 | - | 点位事件回调。 |
+| `chunkSize` | 否 | `5000` | 分帧构建时每批处理数量。 |
+| `chunkFrameBudget` | 否 | `0` | 分帧构建每帧预算，单位毫秒。 |
+| `pickRadius` | 否 | `10` | Leaflet / Pixi 模式下的拾取半径。 |
+| `keepSize` | 否 | `true` | Cesium 下是否尽量保持屏幕像素尺寸。 |
+| `clampToGround` | 否 | `false` | Cesium 点位是否贴地。 |
+| `disableDepthTestDistance` | 否 | - | Cesium 深度检测距离。 |
+| `pixelOffset` / `eyeOffset` | 否 | - | Cesium 图标偏移。 |
+| `scaleByDistance` | 否 | - | Cesium 按距离缩放。 |
+| `translucencyByDistance` | 否 | - | Cesium 按距离透明。 |
+| `distanceDisplayCondition` | 否 | - | Cesium 按距离显示隐藏。 |
+| `useParticleContainer` | 否 | `false` | Leaflet 下是否使用 Pixi 粒子容器能力。 |
+| `pixiOptions` | 否 | - | Leaflet / Pixi 渲染参数。 |
+
+### 状态返回
+
+```js
+const state = pointLayer.getState()
+
+console.log(state)
+// {
+//   mounted: true,
+//   engineType: 'leaflet',
+//   layerType: 'leaflet-point-large-layer',
+//   visible: true,
+//   layerId: 'station-large',
+//   total: 20000,
+//   renderedCount: 20000,
+//   highlightedId: 'A001',
+//   building: false,
+//   destroyed: false,
+//   payload: {}
+// }
+```
+
+
+## PointDensityController
+
+用于点位密度抽稀。地图移动、缩放后会按当前视野和屏幕网格重新计算可见点，适合站点、设备、告警、空气质量监测点等高密度点位。
+
+它和 `PointLargeLayerController` 的区别是：`PointLargeLayerController` 尽量渲染全部有效点；`PointDensityController` 会根据视野、屏幕网格、优先级和最大显示数量筛选一部分点显示。
+
+### Demo 位置
 
-用于海量点位渲染，支持显隐、高亮、删除单点、批量删除、清空和状态读取。
+仓库内已有多个点位抽稀 demo：
+
+- `/test-page-6`：站点 ICON 抽稀，使用 `imageCallback` 按数据绘制站点图标。
+- `/test-page-8`：空气质量站点抽稀，使用固定 `image` 图标。
+- `/test-page-13`：空气质量业务页里的城市点位抽稀。
+
+### 基础用法
 
 ```js
-import { PointLargeLayerController } from '@3clear/basegis/methods'
+import { PointDensityController } from '@3clear/basegis/methods'
 
-const largePoints = new PointLargeLayerController({
+const density = new PointDensityController({
+  // 必填：BaseGIS 实例。
   mapCore,
-  layerId: 'station-large',
+
+  // 建议必填：图层唯一 ID。
+  layerId: 'station-density',
+
+  // 点位唯一值字段。不传默认 id。
   idKey: 'staNum',
+
+  // 抽稀网格大小，单位屏幕像素。同一网格内只保留一个点。
+  gridSize: 150,
+
+  // 最多显示点数。不传默认不限制。
+  maxCount: 500,
+
+  // 同一网格内保留哪个点。字段值越大越优先显示。
+  priorityKey: 'level',
+
+  // 默认图标。
   image: '/icons/station.png',
-  width: 24,
-  height: 24,
+
+  // 图标尺寸。
+  width: 28,
+  height: 28,
+
+  // 点击点位回调。第一个参数是原始点位数据。
   onClick(point) {
-    console.log('点击站点', point)
+    console.log(point)
+  },
+
+  // 状态变化回调。地图移动、缩放或数据更新后会触发。
+  onStateChange(state) {
+    console.log(state.visibleCount, state.hiddenCount)
   },
 })
 
-await largePoints.load({
+await density.load({
   points: [
-    { staNum: 'A001', longitude: 104, latitude: 35, name: 'A001' },
-    { staNum: 'A002', longitude: 105, latitude: 36, name: 'A002' },
+    { staNum: 'A001', longitude: 104, latitude: 35, level: 5 },
+    { staNum: 'A002', longitude: 104.01, latitude: 35.01, level: 3 },
   ],
 })
-
-largePoints.setHighlight('A001')
-largePoints.clearHighlight()
-largePoints.removePoint('A002')
-largePoints.removePoints(['A001', 'A003'])
-largePoints.hide()
-largePoints.show()
-largePoints.clear()
-largePoints.destroy()
-largePoints.getState()
 ```
 
-点位字段默认支持：
-
-- 经度：`longitude / lon / lng / x`
-- 纬度：`latitude / lat / y`
-- 高度：`height / altitude / z`
-- 唯一值：默认 `id`，可通过 `idKey` 指定
-
-## PointDensityController
+### 完整配置模板
 
-用于点位密度抽稀。地图移动、缩放后按屏幕网格重新计算可见点，适合站点、设备、告警等高密度点位。
+下面的配置接近 `test-page-6` 的写法，字段已加注释。业务中按需保留即可。
 
 ```js
-import { PointDensityController } from '@3clear/basegis/methods'
-
 const density = new PointDensityController({
+  // BaseGIS 实例。控制器只通过 BaseGIS 调用当前引擎能力，不直接依赖 Cesium / Leaflet。
   mapCore,
+
+  // 图层唯一标识。后续 update/show/hide/clear/destroy 都按该 id 定位图层。
   layerId: 'station-density',
+
+  // 点位唯一值字段。默认 id；如果点位唯一值在 properties 中，也会尝试读取 properties[idKey]。
   idKey: 'staNum',
+
+  // 初始是否显示图层。不传默认 true。
+  visible: true,
+
+  // 原始点位数据。也可以不在构造时传，后续 density.load({ points }) 传入。
+  points: stationList,
+
+  // 经度字段候选列表。默认已支持 longitude/lon/lng/x。
+  longitudeKeys: ['longitude', 'lon', 'lng', 'x'],
+
+  // 纬度字段候选列表。默认已支持 latitude/lat/y。
+  latitudeKeys: ['latitude', 'lat', 'y'],
+
+  // 高度字段候选列表。默认已支持 height/altitude/z。
+  heightKeys: ['height', 'altitude', 'z'],
+
+  // 是否开启抽稀。true 时会按屏幕网格去重；false 时只做视野过滤，不做网格碰撞去重。
+  enableThinning: true,
+
+  // 抽稀网格大小，单位屏幕像素。值越大，保留点越少；值越小，保留点越多。
   gridSize: 150,
+
+  // gridSize 的别名。如果同时传 gridSize 和 pixelRange，以 gridSize 为准。
+  // pixelRange: 150,
+
+  // 最多显示点数量。超过后会按优先级截断。不传默认 Infinity。
   maxCount: 500,
+
+  // 同一网格内点位优先级字段。字段值越大越优先保留。
   priorityKey: 'level',
+
+  // 自定义优先级函数。返回值越大越优先保留；传了它后优先级逻辑可完全由业务决定。
+  // priorityCallback(point, markerOrBillboard, index) {
+  //   return point.level * 100 + point.value
+  // },
+
+  // 默认图标地址。支持图片 URL、base64、data URL。
   image: '/icons/station.png',
+
+  // 图标地址别名，和 image 作用一致。
+  // icon: '/icons/station.png',
+  // iconUrl: '/icons/station.png',
+
+  // 按点位动态生成图标。适合空气质量、告警等级等需要每个点图标不同的场景。
+  // 返回值可以是图片地址、base64、data URL。
+  // imageCallback(point, index) {
+  //   return createStationIcon(point)
+  // },
+
+  // 图标宽度，单位像素。
   width: 28,
+
+  // 图标高度，单位像素。
   height: 28,
+
+  // 地图移动、缩放后重新计算抽稀的节流时间，单位毫秒。
+  throttleTime: 120,
+
+  // Cesium 专用：视野过滤缓冲，单位屏幕像素。
+  // 值越大，视野边缘附近的点越不容易在移动时频繁出现/消失。
+  viewportBuffer: 100,
+
+  // Cesium 专用：3D 场景下是否剔除地球背面的点。
+  cullByGlobe: true,
+
+  // Cesium 专用：Billboard 是否贴地。
+  clampToGround: false,
+
+  // Cesium 专用：Billboard 缩放比例。
+  scale: 1,
+
+  // Cesium 专用：禁用深度检测距离。
+  disableDepthTestDistance: Number.POSITIVE_INFINITY,
+
+  // Cesium 专用：平滑更新，减少刷新抽稀结果时的突兀感。
+  smoothUpdate: true,
+  smoothUpdateFrames: 2,
+
+  // Leaflet 专用：视野 bounds 扩展比例。
+  // 例如 0.1 表示在当前视野基础上向外扩展 10% 后再过滤点位。
+  boundsBufferRatio: 0,
+
+  // Leaflet 专用：Marker 层级偏移。
+  zIndexOffset: 0,
+
+  // 点位点击回调。第一个参数是原始点位数据。
   onClick(point) {
     console.log(point)
   },
+
+  // 状态变化回调。每次抽稀刷新、显隐、清空后会尽量触发。
   onStateChange(state) {
     console.log(state.visibleCount, state.hiddenCount)
   },
 })
+```
 
+### 点位数据格式
+
+`load` 支持直接传数组，也支持传对象。对象中点位字段支持 `points / data / items`，推荐统一使用 `points`。
+
+```js
 await density.load({
   points: [
     { staNum: 'A001', longitude: 104, latitude: 35, level: 5 },
     { staNum: 'A002', longitude: 104.01, latitude: 35.01, level: 3 },
   ],
 })
+```
+
+也可以写成：
+
+```js
+await density.load([
+  { id: 'A001', lon: 104, lat: 35, value: 86 },
+  { id: 'A002', lon: 104.01, lat: 35.01, value: 120 },
+])
+
+await density.load({
+  data: [
+    { id: 'A001', x: 104, y: 35 },
+  ],
+})
+```
+
+默认坐标字段：
+
+- 经度：`longitude / lon / lng / x`
+- 纬度：`latitude / lat / y`
+- 高度：`height / altitude / z`
+- 唯一值：默认 `id`，可通过 `idKey` 指定。
+
+### 抽稀规则
+
+核心规则：
+
+1. 先按当前地图视野过滤点位。
+2. `enableThinning: true` 时，再按屏幕像素网格抽稀。
+3. 同一网格内默认保留优先级更高的点。
+4. 如果设置了 `maxCount`，最终显示数量不会超过该值。
+
+优先级规则：
+
+```js
+const density = new PointDensityController({
+  mapCore,
+  layerId: 'station-density',
+  points,
+  gridSize: 120,
+
+  // 简单写法：按字段值排序，值越大越优先显示。
+  priorityKey: 'value',
+})
+```
+
+复杂优先级可以用 `priorityCallback`：
+
+```js
+const density = new PointDensityController({
+  mapCore,
+  layerId: 'station-density',
+  points,
+  gridSize: 120,
+  priorityCallback(point, markerOrBillboard, index) {
+    const alarmWeight = point.alarm ? 10000 : 0
+    return alarmWeight + Number(point.value || 0) - index * 0.001
+  },
+})
+```
+
+### 更新配置
 
+地图上已经有图层后，可以通过 `update` 或 `setConfig` 更新数据或抽稀参数。
+
+```js
+// 更新抽稀网格。
 density.update({ gridSize: 120 })
+
+// 关闭抽稀，只做视野过滤。
+density.update({ enableThinning: false })
+
+// 替换点位数据。
+density.update({
+  points: nextPoints,
+})
+
+// setConfig 是 update 的别名，更适合只表达“改配置”的场景。
+density.setConfig({
+  gridSize: 180,
+  maxCount: 300,
+})
+```
+
+### 显隐、清空和销毁
+
+```js
 density.hide()
 density.show()
 density.toggle()
+density.toggle(true)
 density.refreshState()
 density.clear()
 density.destroy()
 ```
 
-常用参数：
+方法说明：
+
+| 方法 | 说明 |
+| --- | --- |
+| `mount(mapCore)` | 挂载 `BaseGIS` 实例。构造时已传 `mapCore/baseGIS` 时通常不需要手动调用。 |
+| `load(payload, options)` | 加载或覆盖抽稀点位数据。支持 `load(points, options)` 和 `load({ points, ...options })`。 |
+| `upsert(payload, options)` | `load` 的别名。 |
+| `update(payload)` | 合并当前配置后重新加载。可更新点位、抽稀参数、图标、事件等。 |
+| `setConfig(payload)` | `update` 的别名。适合只更新抽稀参数。 |
+| `show(payload)` | 显示图层。 |
+| `hide(payload)` | 隐藏图层。 |
+| `toggle(visible)` | 切换显隐。不传 `visible` 时按当前状态取反。 |
+| `clear(payload)` | 清空图层点位数据，但保留图层实例。 |
+| `refreshState(payload)` | 从引擎侧重新读取图层状态。 |
+| `destroy(payload)` | 销毁图层并释放资源。别名：`removeLayer`。 |
+| `getState()` | 读取控制器状态。 |
+
+### 参数总表
+
+| 参数 | 是否必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `mapCore` / `baseGIS` | 构造时建议必填 | - | `BaseGIS` 实例。也可以后续调用 `mount(mapCore)`。 |
+| `layerId` / `pointDensityLayerId` / `densityLayerId` / `id` | 否 | `point-density-default` | 点位抽稀图层 ID。 |
+| `points` / `data` / `items` | 加载时必填其一 | - | 点位数据数组，也支持 GeoJSON FeatureCollection。 |
+| `idKey` | 否 | `id` | 点位唯一标识字段。 |
+| `longitudeKeys` | 否 | `['longitude', 'lon', 'lng', 'x']` | 经度字段候选名。 |
+| `latitudeKeys` | 否 | `['latitude', 'lat', 'y']` | 纬度字段候选名。 |
+| `heightKeys` | 否 | `['height', 'altitude', 'z']` | 高度字段候选名。 |
+| `visible` | 否 | `true` | 初始是否显示图层。 |
+| `enableThinning` | 否 | `true` | 是否开启抽稀；关闭后只做视野过滤。 |
+| `gridSize` | 否 | `150` | 抽稀网格大小，单位屏幕像素。 |
+| `pixelRange` | 否 | `150` | `gridSize` 的别名。 |
+| `maxCount` | 否 | `Infinity` | 单次最多显示的点数量。 |
+| `priorityKey` | 否 | - | 同一网格内点位优先级字段，值越大越优先显示。 |
+| `priorityCallback` | 否 | - | 自定义优先级函数，返回值越大越优先显示。 |
+| `image` / `icon` / `iconUrl` | 否 | - | 默认图标地址。 |
+| `imageCallback` | 否 | - | 图标生成函数，适合每个点图标不同的场景。 |
+| `width` | 否 | `32` | 图标宽度，单位像素。 |
+| `height` | 否 | `32` | 图标高度，单位像素。 |
+| `throttleTime` | 否 | `120` | 地图移动、缩放后刷新抽稀的节流时间，单位毫秒。 |
+| `onClick` | 否 | - | 点位点击回调。第一个参数为原始点位数据。 |
+| `onStateChange` | 否 | - | 图层状态变化回调。 |
+| `viewportBuffer` | 否 | `100` | Cesium 专用：视野过滤缓冲，单位屏幕像素。 |
+| `cullByGlobe` | 否 | `true` | Cesium 专用：3D 场景下是否剔除地球背面点。 |
+| `clampToGround` | 否 | `false` | Cesium 专用：Billboard 是否贴地。 |
+| `scale` | 否 | `1` | Cesium 专用：Billboard 缩放比例。 |
+| `disableDepthTestDistance` | 否 | `Infinity` | Cesium 专用：禁用深度检测距离。 |
+| `smoothUpdate` | 否 | `true` | Cesium 专用：是否平滑更新抽稀结果。 |
+| `smoothUpdateFrames` | 否 | `2` | Cesium 专用：平滑更新保留旧集合的帧数。 |
+| `boundsBufferRatio` | 否 | `0` | Leaflet 专用：视野 bounds 扩展比例。 |
+| `zIndexOffset` | 否 | `0` | Leaflet 专用：Marker 层级偏移。 |
+
+### 状态返回
+
+`getState()` 和 `onStateChange(state)` 返回的状态结构基本一致：
 
-- `enableThinning`：是否开启抽稀，默认开启。
-- `gridSize / pixelRange`：屏幕网格大小，单位像素。
-- `maxCount`：最多显示点数。
-- `priorityKey / priorityCallback`：同网格内优先显示哪个点。
-- `viewportBuffer`：Cesium 屏幕视野缓冲。
-- `cullByGlobe`：Cesium 3D 下是否剔除地球背面点。
-- `boundsBufferRatio`：Leaflet bounds 扩展比例。
+```js
+const state = density.getState()
+
+console.log(state)
+// {
+//   mounted: true,
+//   engineType: 'cesium',
+//   layerType: 'cesium-point-density-layer',
+//   visible: true,
+//   layerId: 'station-density',
+//   sourceCount: 10000,
+//   visibleCount: 420,
+//   hiddenCount: 9580,
+//   gridCount: 420,
+//   gridSize: 150,
+//   destroyed: false,
+//   payload: {}
+// }
+```
 
 ## ContourLayerController
 
@@ -676,40 +2205,69 @@ contour.destroy()
 
 数据别名支持 `contours / isolines / isoline / lines / data / items`。
 
-## PressureContourLayer
+[//]: # ()
+[//]: # (## PressureContourLayer)
 
-用于等压线和高低压中心标注。`buildPressureRenderData()` 可把 Windy 风格的 `press.json` 数据整理成渲染结构，`createPressureDataResolver()` 提供简单缓存。
+[//]: # ()
+[//]: # (用于等压线和高低压中心标注。`buildPressureRenderData&#40;&#41;` 可把 Windy 风格的 `press.json` 数据整理成渲染结构，`createPressureDataResolver&#40;&#41;` 提供简单缓存。)
 
-```js
-import {
-  PressureContourLayer,
-  createPressureDataResolver,
-} from '@3clear/basegis/methods'
+[//]: # ()
+[//]: # (```js)
 
-const resolvePressureData = createPressureDataResolver({
-  default: pressJson,
-  next: pressJson2,
-})
+[//]: # (import {)
 
-const pressureLayer = new PressureContourLayer({
-  mapCore,
-  layerId: 'pressure',
-  color: 'rgba(255,255,255,0.82)',
-  width: 1.15,
-  smoothFactor: 0.2,
-  // Cesium 场景下用于定位容器尺寸，Leaflet 场景也可以传同一个地图容器 id。
-  mapContainerId: 'map',
-  // 标注层通过该函数读取当前数据，便于地图缩放后重建标签。
-  getData: () => resolvePressureData('default'),
-  isAnnotationVisible: () => true,
-})
+[//]: # (  PressureContourLayer,)
 
-pressureLayer.mount()
-await pressureLayer.load(resolvePressureData('default'))
-await pressureLayer.update(resolvePressureData('next'))
-pressureLayer.hide()
-pressureLayer.destroy()
-```
+[//]: # (  createPressureDataResolver,)
+
+[//]: # (} from '@3clear/basegis/methods')
+
+[//]: # ()
+[//]: # (const resolvePressureData = createPressureDataResolver&#40;{)
+
+[//]: # (  default: pressJson,)
+
+[//]: # (  next: pressJson2,)
+
+[//]: # (}&#41;)
+
+[//]: # ()
+[//]: # (const pressureLayer = new PressureContourLayer&#40;{)
+
+[//]: # (  mapCore,)
+
+[//]: # (  layerId: 'pressure',)
+
+[//]: # (  color: 'rgba&#40;255,255,255,0.82&#41;',)
+
+[//]: # (  width: 1.15,)
+
+[//]: # (  smoothFactor: 0.2,)
+
+[//]: # (  // Cesium 场景下用于定位容器尺寸，Leaflet 场景也可以传同一个地图容器 id。)
+
+[//]: # (  mapContainerId: 'map',)
+
+[//]: # (  // 标注层通过该函数读取当前数据，便于地图缩放后重建标签。)
+
+[//]: # (  getData: &#40;&#41; => resolvePressureData&#40;'default'&#41;,)
+
+[//]: # (  isAnnotationVisible: &#40;&#41; => true,)
+
+[//]: # (}&#41;)
+
+[//]: # ()
+[//]: # (pressureLayer.mount&#40;&#41;)
+
+[//]: # (await pressureLayer.load&#40;resolvePressureData&#40;'default'&#41;&#41;)
+
+[//]: # (await pressureLayer.update&#40;resolvePressureData&#40;'next'&#41;&#41;)
+
+[//]: # (pressureLayer.hide&#40;&#41;)
+
+[//]: # (pressureLayer.destroy&#40;&#41;)
+
+[//]: # (```)
 
 说明：
 
@@ -749,58 +2307,138 @@ wind.clearWindFields()
 wind.getState()
 ```
 
-## 直接使用 BaseGIS 图层方法
-
-控制器适合页面长期维护状态。如果只是一次调用，也可以直接用 `BaseGIS` 方法。
+### 构造参数
 
 ```js
-await mapCore.upsertImageLayer({
-  layerId: 'image-layer',
-  imageUrl: '/data/image.png',
-  area: {
-    startLon: 73,
-    startLat: 18,
-    endLon: 135,
-    endLat: 54,
-  },
-})
-mapCore.hideImageLayer({ layerId: 'image-layer' })
-mapCore.showImageLayer({ layerId: 'image-layer' })
-mapCore.removeImageLayer({ layerId: 'image-layer' })
+const wind = new WindFieldMethods({ mapCore })
+// 等价写法：
+// const wind = new WindFieldMethods({ baseGIS: mapCore })
+// const wind = new WindFieldMethods(mapCore)
+```
 
-await mapCore.upsertGridLayer({
-  layerId: 'grid-layer',
-  tifUrl: '/data/grid.tif',
-})
-mapCore.removeGridLayer({ layerId: 'grid-layer' })
+| 参数 | 类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| `mapCore` | `BaseGIS` | 是 | `BaseGIS` 实例。构造时传入会自动 `mount`。 |
+| `baseGIS` | `BaseGIS` | 是 | `mapCore` 的别名。 |
 
-await mapCore.upsertPointLargeLayer({
-  layerId: 'large-points',
-  points: [{ id: '1', longitude: 104, latitude: 35 }],
-})
-mapCore.setPointLargeHighlight({ layerId: 'large-points', pointId: '1' })
-mapCore.clearPointLargeHighlight({ layerId: 'large-points' })
-mapCore.removePointLargePoint({ layerId: 'large-points', pointId: '1' })
-mapCore.clearPointLargeLayer({ layerId: 'large-points' })
-mapCore.removePointLargeLayer({ layerId: 'large-points' })
+如果构造时没有传 `mapCore / baseGIS`，可以后续调用 `wind.mount(mapCore)`。目标实例必须提供 `getMapInstance / getMapContainer / projectToContainerPoint / getViewBounds / onViewChange` 等 `BaseGIS` 公共方法。
 
-await mapCore.upsertPointDensityLayer({
-  layerId: 'density-points',
-  points: [{ id: '1', longitude: 104, latitude: 35 }],
-  gridSize: 150,
-})
-mapCore.getPointDensityLayerState({ layerId: 'density-points' })
-mapCore.removePointDensityLayer({ layerId: 'density-points' })
+### 风场数据格式
 
-await mapCore.upsertContourLayer({
-  layerId: 'contour',
-  contours: [],
-})
-await mapCore.updateContourLayer({ layerId: 'contour', contours: [] })
-mapCore.getContourLayerState({ layerId: 'contour' })
-mapCore.removeContourLayer({ layerId: 'contour' })
+`addWindField` 的 `data` 和 `updateWindField` 的 `data` 使用项目约定的 `Bound / DataAry` 结构：
+
+```js
+const windData = {
+  // [经度最小值, 纬度最小值, 经向网格数, 纬向网格数, 经度跨度, 纬度跨度, 数值缩放]
+  Bound: [70, 15, 121, 81, 60, 40, 10],
+  // 从左下角开始，按行平铺；每个格点两个值：[u, v]
+  DataAry: [
+    // u0, v0, u1, v1, ...
+  ],
+}
 ```
 
+| 字段 | 类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| `Bound[0]` | `number` | 是 | `lonMin`，风场网格西边界经度。 |
+| `Bound[1]` | `number` | 是 | `latMin`，风场网格南边界纬度。 |
+| `Bound[2]` | `number` | 是 | `lonCount`，经向格点数量，必须大于等于 `2`。 |
+| `Bound[3]` | `number` | 是 | `latCount`，纬向格点数量，必须大于等于 `2`。 |
+| `Bound[4]` | `number` | 是 | `lonSpan`，经度跨度，东边界为 `lonMin + lonSpan`。 |
+| `Bound[5]` | `number` | 是 | `latSpan`，纬度跨度，北边界为 `latMin + latSpan`。 |
+| `Bound[6]` | `number` | 否 | `valueScale`，数值缩放系数，默认 `1`；实际风速分量为 `DataAry / valueScale`。 |
+| `DataAry` | `number[]` | 是 | 风矢量数组，长度必须等于 `lonCount * latCount * 2`。每个格点依次存 `u / v` 两个分量。 |
+
+数据按“左下角开始、从南到北逐行、每行从西到东”的顺序平铺。渲染时会对 `u / v` 做双线性插值，粒子速度使用 `Math.hypot(u, v)`。
+
+### addWindField / updateWindField 参数
+
+`addWindField(payload)` 用于新增风场；如果同 id 已存在，会先移除旧风场再创建。`updateWindField(payload)` 用于更新已有风场的参数或数据。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string` | `wind-field-default` | 风场 id。后续 start/stop/show/hide/remove 都按该 id 查找。 |
+| `layerId` | `string` | `wind-field-default` | `id` 的别名。`id` 优先级更高。 |
+| `data` | `object` | - | 风场数据。`addWindField` 必填；`updateWindField` 可选，传入时会替换旧数据。 |
+| `windData` | `object` | - | `data` 的别名。 |
+| `options` | `object` | `{}` | 渲染参数集合。会和 payload 顶层其它参数合并，顶层参数优先级低于 `options` 内同名参数。 |
+| `visible` | `boolean` | `true` | 初始是否显示 Canvas。隐藏后仍保留图层实例。 |
+| `running` | `boolean` | `true` | 初始是否播放粒子动画。 |
+| `zIndex` | `number` | `30` | 风场 Canvas 层级。速度底图使用该值，粒子层使用 `zIndex + 1`。 |
+| `height` | `number` | `0` | 投影时使用的高度，主要影响 Cesium 场景。 |
+| `devicePixelRatio` | `number` | `window.devicePixelRatio` | Canvas 渲染倍率，内部会限制在 `1 ~ 2`。 |
+
+### 粒子动画参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `particleCount` | `number` | `1400` | 粒子总数。数值越大越密，渲染开销越高。 |
+| `maxFrameParticles` | `number` | `1200` | 单帧最多推进和绘制的粒子数。 |
+| `frameParticleLimit` | `number` | `1200` | `maxFrameParticles` 的别名。 |
+| `sceneModeMaxFrameParticles` | `number` | `0` | 场景模式相关帧粒子上限预留参数。当前未作为主路径使用。 |
+| `maxAge` | `number` | `58` | 粒子最大生命周期，超过后重新随机出生。 |
+| `frameRate` | `number` | `30` | 粒子动画目标帧率，内部限制在 `1 ~ 60`。 |
+| `velocityScale` | `number` | `900` | 风速到粒子位移的缩放系数。数值越大粒子移动越快。 |
+| `lineWidth` | `number` | `0.85` | 粒子轨迹基础线宽。 |
+| `color` | `string` | `rgba(230, 248, 255, 0.52)` | 粒子单色兜底颜色。传了 `particleColorScale` 时优先按风速分级着色。 |
+| `particleOpacity` | `number` | `0.58` | 粒子轨迹透明度。 |
+| `fadeOpacity` | `number` | `0.86` | 拖尾淡出强度，越接近 `1` 轨迹残留越长。 |
+| `blendMode` | `string` | `lighter` | Canvas 合成模式，例如 `source-over`、`lighter`。 |
+| `particleColorScale` | `Array` | 内置色标 | 粒子颜色分级。支持 `{ value, color }`、`{ speed, color }`、`[value, color]`。 |
+
+### 速度底图参数
+
+风场默认会额外绘制一层速度底图，用于表达风速强弱；只想显示粒子时可以关闭。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `velocityOverlay` | `boolean` | `true` | 是否绘制速度底图。 |
+| `velocityOverlayOpacity` | `number` | `0.22` | 速度底图透明度。 |
+| `velocityOverlayCellSize` | `number` | `54` | 速度底图采样网格像素大小。 |
+| `velocityOverlayEdgeFade` | `number` | `0.12` | 速度底图边缘淡出比例。 |
+| `colorScale` | `Array` | 内置色标 | 速度底图颜色分级。支持 `{ value, color }`、`{ speed, color }`、`[value, color]`。 |
+
+`color` 可以写成 `#4ab3ff`、`rgb(80, 180, 255)`、`rgba(80, 180, 255, 0.8)` 或 `[80, 180, 255]`。
+
+### 交互与投影参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `interactionResumeDelay` | `number` | `80` | 地图交互结束后恢复动画的延迟，单位毫秒。交互过程中会暂停粒子绘制。 |
+| `projectionGrid` | `boolean` | `true` | 2D / 2.5D 场景是否启用投影网格缓存。 |
+| `projectionGridCols` | `number` | `32` | 投影网格列数，内部限制在 `8 ~ 96`。 |
+| `projectionGridRows` | `number` | `20` | 投影网格行数，内部限制在 `6 ~ 64`。 |
+| `reset` | `boolean` | `false` | `updateWindField` 时传 `true` 会强制重置粒子。 |
+
+`container / project / getViewBounds / getSceneMode` 由 `WindFieldMethods` 根据 `BaseGIS` 自动注入，业务侧不要传这些字段作为主路径。
+
+### 控制方法
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `mount(mapCore)` | `BaseGIS` 实例 | 后挂载 `BaseGIS`。 |
+| `addWindField(payload)` | 风场数据与渲染参数 | 新增风场。`data / windData` 必填。 |
+| `updateWindField(payload)` | `{ id, ...options }` | 更新已有风场。可只更新样式、粒子参数，也可传 `data / windData` 替换数据。 |
+| `startWindField(idOrPayload)` | `string` 或 `{ id / layerId }` | 启动粒子动画。 |
+| `stopWindField(idOrPayload)` | `string` 或 `{ id / layerId }` | 停止粒子动画，图层仍可见。 |
+| `showWindField(idOrPayload)` | `string` 或 `{ id / layerId }` | 显示风场 Canvas。 |
+| `hideWindField(idOrPayload)` | `string` 或 `{ id / layerId }` | 隐藏风场 Canvas。 |
+| `removeWindField(idOrPayload)` | `string` 或 `{ id / layerId }` | 移除指定风场并解绑视图监听。 |
+| `clearWindFields()` | 无 | 移除全部风场。 |
+| `getState()` | 无 | 返回 `{ mounted, count, layers }`。 |
+
+单个风场状态包含：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 风场 id。 |
+| `valid` | 数据网格是否合法。 |
+| `visible` | 当前是否显示。 |
+| `running` | 当前是否播放动画。 |
+| `particleCount` | 当前粒子数量。 |
+| `bounds` | 风场数据范围 `{ west, south, east, north }`。 |
+| `center` | 风场中心 `{ lon, lat }`。 |
+
 ## 在 Vue 中封装 Hook
 
 推荐页面用 hook 管理生命周期，组件只处理 UI。
@@ -822,8 +2460,20 @@ export function useBaseGIS(options = {}) {
     mapCore.value = null
   })
 
+  function switchEngine(engineType) {
+    if (!mapCore.value || mapCore.value.getEngineType() === engineType) {
+      return { success: true }
+    }
+
+    return mapCore.value.init({
+      ...options,
+      engineType,
+    })
+  }
+
   return {
     mapCore,
+    switchEngine,
   }
 }
 ```
@@ -838,13 +2488,22 @@ export function useBaseGIS(options = {}) {
 <script setup>
 import { useBaseGIS } from './useBaseGIS'
 
-const { mapCore } = useBaseGIS({
+const { mapCore, switchEngine } = useBaseGIS({
   engineType: 'cesium',
   containerId: 'map',
 })
 </script>
 ```
 
+如果页面有业务图层，`switchEngine()` 成功后要重新加载图层数据：
+
+```js
+const result = switchEngine('leaflet')
+if (result.success) {
+  await reloadBusinessLayers()
+}
+```
+
 ## 能力支持说明
 
 | 能力 | Cesium | Leaflet |
@@ -861,6 +2520,8 @@ const { mapCore } = useBaseGIS({
 | 等值线 | 支持 | 支持 |
 | 等压线标注 | 支持 | 支持 |
 | 风场 Canvas 动画 | 支持 | 支持 |
+| 三维体渲染 | 支持 | 不支持 |
+| 三维切片 / 剖面渲染 | 支持 | 不支持 |
 | DEM 地形 | 支持 | 不支持 |
 
 ## 本地开发与打包
@@ -970,3 +2631,21 @@ mapCore.init()
 ```
 
 `init()` 内部会先销毁旧适配器，再创建新实例。
+
+### 切换引擎后图层没了
+
+这是预期行为。Cesium 和 Leaflet 的图层对象不能互相复用，`init({ engineType })` 会销毁旧地图实例并创建新地图实例。
+
+处理方式是：页面或 store 保存业务数据，切换成功后重新调用对应的加载方法。
+
+```js
+const result = mapCore.init({
+  engineType: 'leaflet',
+  containerId: 'map',
+})
+
+if (result.success) {
+  await imageLayer.update(currentImagePayload)
+  await pointLayer.load({ points: currentPoints })
+}
+```