@3clear/basegis 0.1.2 → 0.1.4

package/README.md

@@ -4,12 +4,196 @@
 把leaflet cesium 常用方法做了二次封装统一了api 使同一套代码可以适配2套地图引擎
 当前包包含：
 
-- `BaseGIS`：地图初始化、引擎切换、视角控制、底图切换、绘制、图层显隐、DEM、点击事件、三维体渲染、三维切片/剖面渲染等基础能力。
-- `methods`：图片图层、网格图层、海量点、点位抽稀、等值线、等压线、风场、图形组等高级控制器。
+- `BaseGIS`：地图初始化、引擎切换、视角控制、底图切换、绘制、图层显隐、DEM、点击事件、Cesium / Leaflet 统一粒子风场、GPU 粒子风场、三维体渲染、三维切片/剖面渲染等基础能力。
+- `methods`：独立线图层、图片图层、网格图层、海量点、点位聚合、点位抽稀、等值线、风场、图形组等高级控制器。
 - `layers`：天地图、GeoServer 金字塔瓦片、WMS、WMTS 图层配置快捷构造器。
 - `assets`：GIS 示例资源。
 - `style.css`：Leaflet、GIS 图层和标注相关基础样式。
 
+## 能力总览
+
+以下按类型展示 `@3clear/basegis` 的主要业务能力；工具型辅助函数不单独作为能力卡展示。点击名称可跳转到下方详细说明，完整导入方式见[出口](#出口)。
+
+### Core 核心（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#base-gis"><strong>BaseGIS</strong></a><br>
+        <small>Cesium / Leaflet 统一 GIS 主入口 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Graphics 图形与点位（4）
+
+<table>
+  <tbody>
+    <tr>
+      <td width="50%">
+        <a href="#graphic-group-controller"><strong>GraphicGroupController</strong></a><br>
+        <small>点、线、面、文字与 Marker 图形组 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+      <td width="50%">
+        <a href="#point-large-layer-controller"><strong>PointLargeLayerController</strong></a><br>
+        <small>海量点 · <a href="http://61.50.111.214:31166/lgmap/test-page-5" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+    <tr>
+      <td width="50%">
+        <a href="#point-cluster-controller"><strong>PointClusterController</strong></a><br>
+        <small>点位聚合 · <a href="http://61.50.111.214:31166/lgmap/test-page-29" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+      <td width="50%">
+        <a href="#point-density-controller"><strong>PointDensityController</strong></a><br>
+        <small>点位视野裁剪抽稀 · <a href="http://61.50.111.214:31166/lgmap/test-page-8" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Line 线图层（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#line-layer-controller"><strong>LineLayerController</strong></a><br>
+        <small>独立线图层、实线/虚线、固定/流动渐变与沿线动画 · <a href="http://61.50.111.214:31166/lgmap/test-page-34" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
+        <small>支持：一条或多条经纬度折线，可选图标引领的逐步出线</small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Image 图片图层（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#image-layer-controller"><strong>ImageLayerController</strong></a><br>
+        <small>图片覆盖层与时次切换 · <a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
+        <small>支持：PNG / JPG / WebP 等浏览器图片、灰度图；可配套 GeoTIFF 取值</small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Grid 数值网格（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#grid-layer-controller"><strong>GridLayerController</strong></a><br>
+        <small>栅格数值注记与鼠标探针 · <a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
+        <small>支持：GeoTIFF、灰度图、直接数值网格</small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Contour 通用等值线与中心标注（2）
+
+<table>
+  <tbody>
+    <tr>
+      <td width="50%">
+        <a href="#contour-layer-controller"><strong>ContourLayerController</strong></a><br>
+        <small>已有等值线、线值标签与中心标注 · <a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+      <td width="50%">
+        <a href="#raster-contour-controller"><strong>RasterContourController</strong></a><br>
+        <small>从栅格追线，可选自动检测 H/L 中心 · <a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Volume 三维体渲染（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#volume-rendering"><strong>BaseGIS.upsertVolumeLayer</strong></a><br>
+        <small>Cesium 专有；三维标量场体积采样与裁切 · <a href="http://61.50.111.214:31166/lgmap/test-page-14" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
+        <small>支持：一维体数据 + rows / cols / heights 网格维度</small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Section 三维切片 / 剖面（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#section-rendering"><strong>BaseGIS.upsertSectionLayer</strong></a><br>
+        <small>Cesium 专有；按经度、纬度、高度/气压层切片 · <a href="http://61.50.111.214:31166/lgmap/test-page-15" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
+        <small>支持：{ Bound, DataAry } 三维格点数据</small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Wind 风场（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#wind-field-methods"><strong>WindFieldMethods</strong></a><br>
+        <small>Cesium / Leaflet 统一粒子风场 · <a href="http://61.50.111.214:31166/lgmap/test-page-21" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Layers 图层构造器（4）
+
+<table>
+  <tbody>
+    <tr>
+      <td width="50%">
+        <a href="#layer-config-builders"><strong>createTiandituLayer</strong></a><br>
+        <small>天地图图层配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+      <td width="50%">
+        <a href="#layer-config-builders"><strong>createGeoserverPyramidLayer</strong></a><br>
+        <small>GeoServer 金字塔瓦片配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+    <tr>
+      <td width="50%">
+        <a href="#layer-config-builders"><strong>createWmsLayer</strong></a><br>
+        <small>WMS 图层配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+      <td width="50%">
+        <a href="#layer-config-builders"><strong>createWmtsLayer</strong></a><br>
+        <small>WMTS 图层配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Assets 示例资源（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#gis-marker-sample"><strong>gisMarkerSample</strong></a><br>
+        <small>GIS Marker 示例资源 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
 ## 安装
 
 ```bash
@@ -36,15 +220,15 @@ import { BaseGIS } from '@3clear/basegis'
 // 高级能力控制器
 import {
   GraphicGroupController,
+  LineLayerController,
   ImageLayerController,
+  toImageLayerArea,
   GridLayerController,
   PointLargeLayerController,
+  PointClusterController,
   PointDensityController,
   ContourLayerController,
   RasterContourController,
-  PressureContourLayer,
-  createPressureDataResolver,
-  buildPressureRenderData,
   WindFieldMethods,
 } from '@3clear/basegis/methods'
 
@@ -266,10 +450,74 @@ mapCore.setBasemap({
 | `parameters` | 选填 | WMS 附加参数。 |
 | `engineSupport` | 选填 | 支持的引擎列表，如 `['cesium', 'leaflet']`。 |
 
+<a id="layer-config-builders"></a>
+
+## 图层配置构造器
+
+`layers` 出口提供四个快捷构造器，只负责生成标准图层配置，不会直接操作地图。构造结果可以放入 `config.basemap.list`，也可以传给 `setBasemap()`。
+
+```js
+import { BaseGIS } from '@3clear/basegis'
+import {
+  createGeoserverPyramidLayer,
+  createTiandituLayer,
+  createWmsLayer,
+  createWmtsLayer,
+} from '@3clear/basegis/layers'
+
+const basemapList = [
+  createTiandituLayer({
+    id: 'tianditu-imagery',
+    name: '天地图影像',
+    category: 'basemap',
+    resourceKey: 'imagery',
+    annotationResourceKey: 'imageryLabel',
+  }),
+  createGeoserverPyramidLayer({
+    id: 'geoserver-pyramid',
+    name: 'GeoServer 金字塔瓦片',
+    category: 'basemap',
+    url: 'https://example.com/tiles/{z}/{x}/{y}.png',
+  }),
+  createWmsLayer({
+    id: 'weather-wms',
+    name: '气象 WMS',
+    category: 'basemap',
+    serviceUrl: 'https://example.com/geoserver/wms',
+    layers: 'workspace:weather',
+    parameters: {
+      transparent: true,
+      format: 'image/png',
+    },
+  }),
+  createWmtsLayer({
+    id: 'weather-wmts',
+    name: '气象 WMTS',
+    category: 'basemap',
+    url: 'https://example.com/wmts',
+    layer: 'weather',
+    tileMatrixSet: 'EPSG:3857',
+  }),
+]
+
+const mapCore = new BaseGIS({
+  containerId: 'map',
+  config: {
+    basemap: {
+      list: basemapList,
+      defaultVisibleId: 'tianditu-imagery',
+    },
+  },
+})
+```
+
+四个构造器都会保留额外传入字段，便于继续配置 `engineSupport`、缩放级别、注记资源或服务参数。
+
+<a id="base-gis"></a>
 
 ## BaseGIS 基础能力
 
-这一节列的是 `BaseGIS` 主入口直接提供的基础能力。业务页面优先调用这些方法；图片图层、网格图层、海量点、点位抽稀、等值线、风场等更复杂能力，建议使用后文 `methods` 中对应的 Controller。
+这一节列的是 `BaseGIS` 主入口直接提供的基础能力。业务页面优先调用这些方法；图片图层、网格图层、海量点、点位聚合、点位抽稀、等值线、风场等更复杂能力，建议使用后文 `methods` 中对应的 Controller。
 
 ### 1. 生命周期、实例与引擎切换
 
@@ -370,7 +618,7 @@ if (result.success) {
 
 引擎切换不是把 Cesium 图层对象“搬到” Leaflet，也不是把 Leaflet 图层对象“搬到” Cesium。BaseGIS 会保存托管图层的业务参数，并在新 adapter 中重新创建图层。
 
-- 自动恢复范围包括图片、网格、海量点、点位抽稀、等值线和三维体图层，对应 `upsert*Layer` 方法及 Controller。
+- 自动恢复范围包括图片、网格、海量点、点位聚合、点位抽稀、独立线、等值线、统一风场和三维体图层，对应 `upsert*Layer` 方法及 Controller。
 - 图层最新的数据参数、显隐、清空、删除、海量点删除和高亮状态会同步到 BaseGIS 快照。
 - 快照只保存业务参数引用，不复制大数组，不保存任何底层引擎对象。
 - 三维体图层切到 Leaflet 时会返回不支持结果，但快照仍保留，切回 Cesium 后会继续恢复。
@@ -488,7 +736,7 @@ viewListener.data?.off?.()
 
 ### 4. 绘制点、线、面、文字和 Marker
 
-这些方法用于轻量绘制和样例验证。大量点位或复杂业务图层请优先使用后文的 `PointLargeLayerController`、`PointDensityController`、`GraphicGroupController` 等控制器。
+这些方法用于轻量绘制和样例验证。大量点位或复杂业务图层请优先使用后文的 `PointLargeLayerController`、`PointClusterController`、`PointDensityController`、`GraphicGroupController` 等控制器。
 
 点：
 
@@ -579,6 +827,25 @@ mapCore.addMarker({
 })
 ```
 
+<a id="gis-marker-sample"></a>
+
+#### 使用 gisMarkerSample 示例资源
+
+`gisMarkerSample` 是可直接导入的 Marker 图片资源，适合快速验证 `addMarker()` 或控制器图标配置。
+
+```js
+import { gisMarkerSample } from '@3clear/basegis/assets'
+
+mapCore.addMarker({
+  id: 'marker-sample',
+  name: '示例站点',
+  position: [104, 35],
+  iconUrl: gisMarkerSample,
+  iconSize: [42, 50],
+  iconAnchor: [21, 50],
+})
+```
+
 清理图形：
 
 ```js
@@ -665,9 +932,11 @@ Leaflet 当前返回坐标点击：
 说明：
 
 - 基础 `onClick` 适合地图空白点击、简单 Entity 点击。
-- 海量点、点位抽稀等图层自己的点击事件，应使用对应 Controller 的 `onClick` 参数。
+- 海量点、点位聚合、点位抽稀等图层自己的点击事件，应使用对应 Controller 的点击回调参数。
 
 
+<a id="graphic-group-controller"></a>
+
 ## GraphicGroupController
 
 用于一次性加载一组点、线、面、文字、marker。它只调用 `BaseGIS.drawPoint / drawLine / drawPolygon / drawText / addMarker`。
@@ -705,10 +974,180 @@ graphics.clear()
 graphics.getState()
 ```
 
+<a id="line-layer-controller"></a>
+
+## LineLayerController
+
+独立管理一组折线，支持整体更新、显隐、清空、销毁和引擎切换恢复。每条线必须提供唯一 `id` 和至少两个 `[longitude, latitude, height?]` 坐标点。第一版可以加载多条线，但同一控制器只播放一条线的动画。
+
+### 实线、虚线与纯色
+
+```js
+import { LineLayerController } from '@3clear/basegis/methods'
+
+const lineLayer = new LineLayerController({
+  mapCore,
+  layerId: 'flight-route',
+  style: {
+    color: '#00d8ff',
+    width: 4,
+    opacity: 0.9,
+    pattern: 'dashed', // solid | dashed
+    dashLength: 14,
+    gapLength: 8,
+  },
+})
+
+await lineLayer.load({
+  lines: [{
+    id: 'route-1',
+    positions: [
+      [116.4, 39.9],
+      [117.8, 37.5],
+      [121.5, 31.2],
+    ],
+  }],
+})
+```
+
+单条线的 `style` 可以覆盖控制器的顶层默认样式。
+
+### 固定渐变与流动渐变
+
+`style.color` 可以是 CSS 颜色字符串，也可以是渐变配置。`stops` 的 `offset` 按 `0～1` 升序排列；配置 `flow` 后渐变会沿线路循环流动。
+
+```js
+const gradientStyle = {
+  width: 5,
+  pattern: 'solid',
+  color: {
+    type: 'gradient',
+    stops: [
+      { offset: 0, color: '#00e5ff' },
+      { offset: 0.5, color: '#2563eb' },
+      { offset: 1, color: '#a855f7' },
+    ],
+    flow: {
+      enabled: true,
+      durationMs: 2400,
+      direction: 'forward', // forward | reverse
+    },
+  },
+}
+```
+
+渐变与虚线可以同时配置。Cesium 和 Leaflet 的底层绘制机制不同，虚线端点和颜色交界处可能有轻微视觉差异。
+
+### 飞机引领的逐步出线
+
+飞机不是单独的类，而是通用 `animation.icon` 配置。省略 `icon` 时只播放线路逐步出现。
+
+```js
+// BaseGIS 不内置飞机图片，替换成业务项目自己的资源地址。
+const planeIconUrl = '/your-app/plane.svg'
+
+const flightLine = new LineLayerController({
+  mapCore,
+  layerId: 'flight-route',
+  style: gradientStyle,
+  animation: {
+    enabled: true,
+    lineId: 'route-1',
+    mode: 'reveal',
+    durationMs: 12000,
+    autoplay: true,
+    loop: true,
+    icon: {
+      url: planeIconUrl,
+      size: [36, 36],
+      rotateToPath: true,
+      rotationOffsetDeg: 0,
+    },
+  },
+})
+
+await flightLine.load({
+  lines: [{
+    id: 'route-1',
+    positions: [
+      [116.4, 39.9],
+      [117.8, 37.5],
+      [121.5, 31.2],
+    ],
+  }],
+})
+
+flightLine.pauseAnimation()
+flightLine.playAnimation()
+flightLine.restartAnimation()
+```
+
+动画按照各段实际地理距离插值。`hide()` 暂停帧更新并记录播放状态，`show()` 恢复隐藏前正在运行的动画；`clear()` 和 `destroy()` 会取消动画。切换引擎会恢复播放/暂停意图，但不会保存逐帧进度，动画从起点重新计算。
+
+### 参数
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `layerId` | `line-default` | 独立线图层 id。 |
+| `visible` | `true` | 初始是否可见。 |
+| `style.color` | `#2f80ff` | 纯色字符串或渐变对象。 |
+| `style.width` / `style.opacity` | `3` / `1` | 线宽和透明度。 |
+| `style.pattern` | `solid` | `solid` 或 `dashed`。 |
+| `style.dashLength` / `gapLength` | `12` / `8` | 虚线实段和间隔长度。 |
+| `animation.enabled` | `false` | 是否启用逐步出线。 |
+| `animation.lineId` | 单线时自动选择 | 多条线启用动画时必填。 |
+| `animation.durationMs` | `10000` | 从起点到终点的时长。 |
+| `animation.autoplay` / `loop` | `true` / `false` | 自动播放与循环。 |
+| `animation.icon` | - | 可选的飞机、车辆或船舶图标配置。 |
+
+### 方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `mount(mapCore)` | 后挂载 BaseGIS。 |
+| `load(payload, options?)` / `update(payload)` | 加载或更新线、样式和动画。 |
+| `show()` / `hide()` / `toggle()` | 控制显隐。 |
+| `playAnimation()` / `pauseAnimation()` / `restartAnimation()` | 控制沿线动画。 |
+| `clear()` | 清空线和动画，保留控制器。 |
+| `refreshState()` / `getState()` | 获取线数量、点数和动画状态。 |
+| `destroy()` | 删除图层、动画和引擎恢复快照。 |
+
+页面卸载时先执行 `lineLayer.destroy()`，再执行 `mapCore.destroy()`。
+
+在线示例：[查看 LineLayerController 双引擎应用 Demo](http://61.50.111.214:31166/lgmap/test-page-34)。
+
+<a id="image-layer-controller"></a>
+
 ## ImageLayerController
 
 用于管理一个图片覆盖层。所有更新都走 `update(payload)`；页面有很多时次数据时，自己维护数据列表，然后把当前时次的数据传给 `update`。
 
+### 支持的数据格式
+
+| 数据模式 | 核心字段 | 用途 |
+| --- | --- | --- |
+| 普通图片 | `imageUrl + area` | 浏览器可解码的图片，常用 PNG、JPG/JPEG、WebP；用作雷达、云图或已填色格点图覆盖层。 |
+| 灰度图 | `imageUrl + area + imageSourceType: 'grayscale' + colorize` | 把像素灰度映射成业务值，再按色带生成可见图片。 |
+| 图片 + GeoTIFF | `imageUrl + tifUrl + area` | 图片负责显示，GeoTIFF 为网格注记和鼠标探针提供数值。 |
+
+`ImageLayerController` 不会把单独的 GeoTIFF 渲染成彩色图片底图。只有 TIF 数值数据时，优先使用 [`GridLayerController`](#grid-layer-controller)；需要由栅格生成等值线时使用 [`RasterContourController`](#raster-contour-controller)。
+
+`toImageLayerArea()` 可以把经纬度数组、Leaflet Bounds 或常见范围对象统一转换成 `{ startLon, startLat, endLon, endLat }`：
+
+```js
+import {
+  ImageLayerController,
+  toImageLayerArea,
+} from '@3clear/basegis/methods'
+
+const area = toImageLayerArea({
+  west: 73,
+  south: 18,
+  east: 135,
+  north: 54,
+})
+```
+
 先创建控制器。这里是控制器级默认参数，后续每次 `update(payload)` 都可以覆盖这些默认值：
 
 ```js
@@ -872,57 +1311,28 @@ await imageLayer.update({
 })
 ```
 
-`loadGrayImage` 的灰度值换算规则：
-
-```js
-业务值 = (灰度值 - grayMinValue) / (grayMaxValue - grayMinValue) * (maxValue - minValue) + minValue
-```
+Leaflet 会对经度跨度达到 360° 的全球图片按当前视野自动补充相邻世界副本，全球 TIF / 灰度格点的注记和鼠标探针也会使用同一套经度循环，因此业务页面不需要手动创建 `±360°` 图片层。原始图片按 `0° ~ 360°` 排列时传 `isSplit: true`，适配层会在交换左右半幅的同时把显示范围统一为 `-180° ~ 180°`，确保图片与格点值落在同一经度位置。
 
-所以灰度图要表达真实业务值时，建议显式传 `minValue / maxValue`。如果只写 `colorize: true`，会使用默认范围 `minValue: 0`、`maxValue: 1`、`grayMinValue: 1`、`grayMaxValue: 254`，只适合临时预览，不适合正式业务图层。
+### 4. 仅 TIF 数值层
 
-`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 渲染的场景。
+只传 TIF 时不会生成彩色图片底图，仅能使用 TIF 数值显示网格注记或鼠标探针。这种场景更推荐直接使用 `GridLayerController`。
 
 ```js
 await imageLayer.update({
   // 选填：当前数据 id。
   id: 'rain-tif',
 
-  // 必填建议：纯 TIF 模式下显式清空 imageUrl，避免沿用上一次图片。
+  // 必填建议：仅 TIF 模式下显式清空 imageUrl，避免沿用上一次图片。
   imageUrl: '',
 
   // 必填：TIF 地址。
   tifUrl: '/data/rain.tif',
 
-  // 选填：是否按默认色带着色。需要更精细控制时传 colorize 对象。
-  colorize: true,
-
   // 选填：是否开启鼠标探针。
   showProbe: true,
+
+  // 选填：是否显示网格数值注记。
+  showLabel: true,
 })
 ```
 
@@ -1014,7 +1424,7 @@ imageLayer.destroy({ layerId: 'radar-image' })
 | 方法 | 参数 | 返回值 | 说明 |
 | --- | --- | --- | --- |
 | `mount(target)` | `BaseGIS` 实例 | `Result` | 绑定 `BaseGIS`。构造时已传 `mapCore/baseGIS` 时通常不需要手动调用。 |
-| `update(payload)` | 图片图层数据 | `Promise<Result>` | 推荐主入口。创建或更新当前图片图层，支持普通图片、图片+TIF、灰度图+色带、纯 TIF。 |
+| `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`。如果地图已销毁，只清本地状态。 |
@@ -1055,19 +1465,19 @@ imageLayer.destroy({ layerId: 'radar-image' })
 | `defaultArea` | 选填 | 默认图片范围，`update` 未传 `area` 时使用。 |
 | `id` | 选填 | 当前数据 id，便于状态记录。 |
 | `name` | 选填 | 当前数据名称，便于页面展示。 |
-| `imageUrl` | 普通图片、灰度图、图片+TIF 必填 | 图片地址。纯 TIF 模式建议传空字符串清掉旧图片。 |
-| `tifUrl` | 纯 TIF、图片+TIF 必填 | GeoTIFF 地址，用于渲染、探针或网格注记。 |
+| `imageUrl` | 普通图片、灰度图、图片+TIF 必填 | 图片地址。仅 TIF 模式建议传空字符串清掉旧图片。 |
+| `tifUrl` | 仅 TIF、图片+TIF 必填 | GeoTIFF 数值地址，用于鼠标探针或网格注记，不会单独生成彩色图片底图。 |
 | `area` | 传 `imageUrl` 时必填 | 图片范围：`startLon / startLat / endLon / endLat`。 |
 | `imageSourceType` | 灰度图必填，其他选填 | `color` 表示已填色图片；`grayscale` 表示灰度图。 |
-| `colorize` | 灰度图必填，TIF 着色选填 | 色带配置，或传 `true` 使用默认着色。 |
+| `colorize` | 灰度图必填 | 灰度图业务值和色带配置。 |
 | `colorize.minValue` | 灰度图必填 | 色带映射最小值。 |
 | `colorize.maxValue` | 灰度图必填 | 色带映射最大值。 |
 | `colorize.noDataValue` | 选填 | 无效值。 |
 | `colorize.colors` | 灰度图必填 | 色带颜色数组。 |
 | `opacity` | 选填 | 透明度，通常 0 - 1。 |
 | `visible` | 选填 | 是否显示图层。 |
-| `showProbe` | 选填 | 是否开启鼠标探针，通常依赖 `tifUrl`。 |
-| `showLabel` | 选填 | 是否显示网格注记，通常依赖 `tifUrl`。 |
+| `showProbe` | 选填 | 是否开启鼠标探针，需要 `tifUrl` 或灰度图数值。 |
+| `showLabel` | 选填 | 是否显示网格注记，需要 `tifUrl` 或灰度图数值。 |
 | `decimalPlaces` | 选填 | 探针或注记数值小数位。 |
 | `isSplit` | 选填 | 是否切片处理大图。 |
 | `gridTotal` | 选填 | 切片网格数量。 |
@@ -1079,9 +1489,19 @@ imageLayer.destroy({ layerId: 'radar-image' })
 - `switchTo(idOrIndex)`：在已加载的 `items` 内切换到某一项。
 - `next() / prev()`：只适合本地小数组演示，不推荐作为业务时次更新主路径。
 
+<a id="grid-layer-controller"></a>
+
 ## GridLayerController
 
-用于 TIF 网格、灰度图网格、外部数值网格。
+用于 GeoTIFF、灰度图和外部数值网格的采样、数值注记和鼠标探针。它不绘制彩色栅格底图；`showLabel` 和 `showProbe` 都为 `false` 时，数据会被读取，但地图上没有可见内容。
+
+### 支持的数据格式
+
+| 数据模式 | 核心字段 | 数据契约 |
+| --- | --- | --- |
+| GeoTIFF | `tifUrl` | `.tif/.tiff` 地址；读取第一个栅格波段及文件地理范围。 |
+| 灰度图 | `imageUrl/grayImageUrl + area` | 浏览器可解码的灰度图；通过 `grayMinValue/grayMaxValue/minValue/maxValue/noDataValue` 换算业务值。 |
+| 直接数值网格 | `imageGridData` | `{ values, width, height, area }` 或 `{ values, width, height, bbox }`；`values` 必须是长度不小于 `width * height` 的一维数组或 TypedArray。 |
 
 ```js
 import { GridLayerController } from '@3clear/basegis/methods'
@@ -1096,7 +1516,6 @@ const gridLayer = new GridLayerController({
 
 await gridLayer.loadTif({
   tifUrl: '/data/grid/temp.tif',
-  colorize: true,
 })
 
 await gridLayer.loadGrayImage({
@@ -1107,7 +1526,7 @@ await gridLayer.loadGrayImage({
     endLon: 135,
     endLat: 54,
   },
-  // 灰度图需要把灰度值映射成业务值，再按业务值找色带。
+  // 灰度图需要把灰度值映射成业务值。
   colorize: {
     // 必填建议：业务值最小值。
     minValue: -20,
@@ -1123,24 +1542,206 @@ await gridLayer.loadGrayImage({
 })
 
 await gridLayer.loadData({
-  imageGridData: [
-    [12.1, 13.4],
-    [14.2, 15.6],
-  ],
-  area: {
-    startLon: 100,
-    startLat: 30,
-    endLon: 110,
-    endLat: 40,
+  imageGridData: {
+    values: [12.1, 13.4, 14.2, 15.6],
+    width: 2,
+    height: 2,
+    area: {
+      startLon: 100,
+      startLat: 30,
+      endLon: 110,
+      endLat: 40,
+    },
   },
 })
 
-gridLayer.update({ opacity: 0.7 })
+gridLayer.update({ decimalPlaces: 2 })
 gridLayer.hide()
 gridLayer.show()
 gridLayer.destroy()
 ```
 
+灰度值换算规则：
+
+```text
+业务值 = (灰度值 - grayMinValue) / (grayMaxValue - grayMinValue)
+       * (maxValue - minValue) + minValue
+```
+
+灰度图要表达真实业务值时，应显式传入 `minValue / maxValue`。数值图层不使用色带绘制背景；如果需要同时显示彩色图片，请使用 `ImageLayerController`。
+
+## 统一粒子风场
+
+同一组 API 会根据当前引擎自动选择渲染器：Cesium 使用 GPU 粒子风场，Leaflet 使用迁自 one-map 的 Canvas 粒子风场。
+
+```js
+const windData = await fetch('/mock/uv.json').then((response) => response.json())
+
+await mapCore.upsertWindLayer({
+  layerId: 'surface-wind',
+  windData,
+  maxParticles: 6400,
+  speedFactor: 0.15,
+  lineWidth: 2,
+  fadeOpacity: 0.92,
+  color: '#b7d9ff',
+  particleOpacity: 0.72,
+})
+
+await mapCore.updateWindLayer({
+  layerId: 'surface-wind',
+  speedFactor: 0.2,
+})
+mapCore.hideWindLayer({ layerId: 'surface-wind' })
+mapCore.showWindLayer({ layerId: 'surface-wind' })
+mapCore.flyToWindLayer({ layerId: 'surface-wind', duration: 0.8 })
+const stateResult = mapCore.getWindLayerState({ layerId: 'surface-wind' })
+mapCore.removeWindLayer({ layerId: 'surface-wind' })
+```
+
+| 方法 | 说明 |
+| --- | --- |
+| `upsertWindLayer(payload)` | 创建或更新当前引擎的风场 |
+| `updateWindLayer(payload)` | 更新数据或部分参数 |
+| `showWindLayer(payload)` / `hideWindLayer(payload)` | 显隐风场 |
+| `flyToWindLayer(payload)` | 定位到风场数据范围 |
+| `getWindLayerState(payload)` | 获取渲染器、粒子数量、范围和显隐状态 |
+| `removeWindLayer(payload)` | 删除风场并释放资源 |
+
+跨引擎统一使用 `Bound / DataAry` 数据格式。公共参数包括 `maxParticles`、`speedFactor`、`lineWidth`、`fadeOpacity`、`particleOpacity`、`color` 和 `visible`；适配层会统一速度、帧率拖尾、屏幕线宽、设备像素比和粒子视觉密度。`maxParticles` 表示跨引擎视觉预算：Cesium 的实际粒子数会按 GPU 纹理向上取整为整数平方，Leaflet 会按 Canvas 拖尾覆盖率换算实际粒子数，均可通过图层状态查看；算法和投影不同，因此不保证逐像素完全一致。Leaflet 还支持 `particleGap`、`maxAge`、`frameRate`、`minSpeed`。统一风场属于 BaseGIS 托管图层，`setEngine()` 切换引擎时会自动使用原数据和最新参数恢复。
+
+## GPU 粒子风场
+
+GPU 粒子风场是 Cesium 专有能力，直接通过 `BaseGIS` 调用。它使用显卡纹理保存和更新粒子，相机平移或缩放期间清空轨迹，操作结束后按新视野重新生成粒子。Leaflet 调用同名方法时会返回 `UNSUPPORTED_CAPABILITY`，不会抛异常。
+
+Cesium 由宿主通过 `window.Cesium` 提供。启用 `terrainEnabled` 后，图层会采样当前 `viewer.terrainProvider`，让轨迹高度随地形变化；如果当前使用椭球地形，采样高度为 0。
+
+### 基础用法
+
+```js
+const response = await fetch('/mock/uv.json')
+const windData = await response.json()
+
+const result = await mapCore.upsertGpuWindLayer({
+  layerId: 'surface-gpu-wind',
+  windData,
+  maxParticles: 10000,
+  particleHeight: 0,
+  terrainEnabled: false,
+  fadeOpacity: 0.901,
+  dropRate: 0.001,
+  dropRateBump: 0.002,
+  speedFactor: 0.15,
+  lineWidth: 4.23,
+  color: '#ffffff',
+  particleOpacity: 1,
+})
+
+if (!result.success) {
+  console.warn(result.code, result.message)
+}
+```
+
+创建和更新是异步方法，可能等待地形采样，建议始终使用 `await`。
+
+### 数据格式
+
+可直接使用 BaseGIS 现有 Canvas 风场的 `Bound / DataAry` 数据：
+
+```js
+const windData = {
+  // 经度最小值、纬度最小值、经向格点数、纬向格点数、
+  // 经度跨度、纬度跨度、数值缩放倍数。
+  Bound: [100, 10, 181, 91, 80, 40, 10],
+  // 每个格点按 U、V 交错；纬度行从南向北排列。
+  DataAry: [u0, v0, u1, v1],
+}
+```
+
+也可以传独立 U/V 分量：
+
+```js
+const windData = {
+  width: 181,
+  height: 91,
+  bounds: {
+    west: 100,
+    east: 180,
+    south: 10,
+    north: 50,
+  },
+  u: new Float32Array(181 * 91),
+  v: new Float32Array(181 * 91),
+  // index-gpu.vue 解码结果从北向南排列，因此使用 north-to-south。
+  rowOrder: 'north-to-south',
+}
+```
+
+也可以不改 `windData`，在 `upsertGpuWindLayer` 参数中传 `flipY: true`。这与 `rowOrder: 'north-to-south'` 等价。
+
+### 更新、显隐和移除
+
+```js
+await mapCore.updateGpuWindLayer({
+  layerId: 'surface-gpu-wind',
+  maxParticles: 40000,
+  speedFactor: 0.2,
+  lineWidth: 3,
+  terrainEnabled: true,
+  particleHeight: 20,
+})
+
+mapCore.hideGpuWindLayer({ layerId: 'surface-gpu-wind' })
+mapCore.showGpuWindLayer({ layerId: 'surface-gpu-wind' })
+mapCore.flyToGpuWindLayer({ layerId: 'surface-gpu-wind', duration: 0.8 })
+
+const stateResult = mapCore.getGpuWindLayerState({
+  layerId: 'surface-gpu-wind',
+})
+console.log(stateResult.data)
+
+mapCore.removeGpuWindLayer({ layerId: 'surface-gpu-wind' })
+```
+
+`updateGpuWindLayer` 只传参数时复用现有数据；传入新的 `windData` 或 `data` 时会重建 GPU 图层。
+
+### 方法总表
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `upsertGpuWindLayer(payload)` | 数据和完整配置 | 创建或替换同 `layerId` 的 GPU 风场 |
+| `updateGpuWindLayer(payload)` | `{ layerId, ...partialOptions }` | 更新参数；传新数据时重建 |
+| `showGpuWindLayer(payload)` | `{ layerId }` | 显示图层 |
+| `hideGpuWindLayer(payload)` | `{ layerId }` | 隐藏图层 |
+| `removeGpuWindLayer(payload)` | `{ layerId }` | 删除图层并释放 GPU 资源 |
+| `flyToGpuWindLayer(payload)` | `{ layerId, duration? }` | 飞到风场数据范围 |
+| `getGpuWindLayerState(payload)` | `{ layerId }` | 获取粒子、范围、地形采样和显隐状态 |
+
+### 参数总表
+
+| 参数 | 是否必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `layerId` / `gpuWindLayerId` / `id` | 建议必填 | `gpu-wind-default` | 图层 id |
+| `windData` / `data` | 创建时必填 | - | 上述任一种风场数据 |
+| `maxParticles` | 选填 | `10000` | 请求粒子数；实际值向上取整为整数平方 |
+| `particleHeight` | 选填 | `0` | 离地高度，单位米 |
+| `terrainEnabled` | 选填 | `false` | 是否贴合 Cesium 地形 |
+| `fadeOpacity` | 选填 | `0.901` | 拖尾保留系数，范围 0～1 |
+| `dropRate` | 选填 | `0.001` | 基础粒子丢弃率 |
+| `dropRateBump` | 选填 | `0.002` | 随风速增加的附加丢弃率 |
+| `speedFactor` | 选填 | `0.15` | 移动速度倍率 |
+| `lineWidth` | 选填 | `4.23` | 轨迹线宽 |
+| `color` | 选填 | `#ffffff` | 粒子轨迹颜色 |
+| `particleOpacity` | 选填 | `1` | 粒子轨迹透明度，范围 0～1 |
+| `visible` | 选填 | `true` | 初始是否显示 |
+| `terrainMaxSamples` | 选填 | `4096` | 单次地形采样点上限，允许 4～16384 |
+| `terrainSampleLevel` | 选填 | 自动计算 | 固定地形采样层级，允许 0～15 |
+| `flipY` | 选填 | `false` | 独立 U/V 数据为北到南行序时传 `true` |
+
+GPU 专用 API 不属于跨引擎自动恢复图层。切换 Cesium/Leaflet 后，业务应重新调用 `upsertGpuWindLayer`；需要自动恢复时改用 `upsertWindLayer`。核心渲染流程改编自 [RaymanNg/3D-Wind-Field](https://github.com/RaymanNg/3D-Wind-Field)，遵循源码目录内 `LICENSE-RaymanNg.txt` 的 MIT License。
+
+<a id="volume-rendering"></a>
+
 ## 三维体渲染
 
 三维体渲染是 Cesium 专有能力，直接通过 `BaseGIS` 调用。Leaflet 调用时会返回不支持结果，不会抛出破坏页面的异常。
@@ -1267,6 +1868,8 @@ console.log(stateResult.data)
 | `geometry` / `dim` | 选填 | 自定义体渲染几何或维度，普通业务通常不需要传。 |
 | `visible` | 选填 | 初始是否显示，默认显示。 |
 
+<a id="section-rendering"></a>
+
 ## 三维切片 / 剖面渲染
 
 三维切片/剖面渲染也是 Cesium 专有能力，直接通过 `BaseGIS` 调用。它把三维网格数据按 X、Y、Z 三个方向切出剖面，适合气象温度、湿度、风场标量、污染物浓度等三维格点数据查看。
@@ -1449,6 +2052,8 @@ if (result.success) {
 | `lon / lat / hpa` | hover 取值必填 | Cesium 拾取得到的经度、纬度、气压高度。 |
 | `showZLayer` | hover 取值选填 | Z 切片是否参与 hover 命中，默认参与。 |
 
+<a id="point-large-layer-controller"></a>
+
 ## PointLargeLayerController
 
 用于海量点位渲染。它会尽量把传入的有效点位全部渲染出来，适合站点、设备、告警、监测点等需要保留全部点位并支持点击、高亮、删除、显隐的场景。
@@ -1811,6 +2416,315 @@ console.log(state)
 ```
 
 
+<a id="point-cluster-controller"></a>
+
+## PointClusterController 点位聚合
+
+### 能力介绍
+
+用于点位聚合。地图移动、缩放或数据更新后，会把当前视野内落入同一屏幕网格的邻近点合成一个带数量的聚合圆；放大后，聚合圆会继续拆分为更小的聚合组或独立点。
+
+Cesium / Leaflet 使用相同的点位解析、屏幕网格和状态字段。页面只创建 `BaseGIS` 与 `PointClusterController`，不需要判断当前引擎。
+
+一次聚合过程会：
+
+1. 根据当前地图视野筛选可见点位。
+2. 把经纬度投影到屏幕坐标，并按 `pixelRange` 划分网格。
+3. 网格内点数达到 `minimumClusterSize` 时渲染聚合圆，否则渲染独立点。
+4. 在地图移动、缩放或数据更新后重新计算，并通过 `onStateChange` 返回最新统计。
+
+聚合只改变当前视野的渲染方式，不修改传入的原始点位数据。它适合站点、设备、告警等密集点位；如果需要显示全部点位或只保留代表点，应分别使用 `PointLargeLayerController` 或 `PointDensityController`。
+
+它和另外两种点位能力的区别：
+
+- `PointLargeLayerController`：尽量显示全部有效点位。
+- `PointClusterController`：邻近点合成一个带数量的聚合圆，可点击继续展开。
+- `PointDensityController`：邻近点只保留一个代表点，不显示合计数量。
+
+### Demo 位置
+
+- 路由：`/test-page-29`
+- 页面：`src/views/test-page-29/index.vue`
+- 数据量：默认生成 10,000 个点位。
+- 覆盖能力：Cesium / Leaflet 切换、聚合参数更新、数据更新、聚合点击放大、单点点击、显隐、清空、删除和状态读取。
+
+### Vue 页面完整用法
+
+```vue
+<template>
+  <div id="station-cluster-map" class="station-cluster-map"></div>
+</template>
+
+<script setup>
+import { onBeforeUnmount, onMounted } from 'vue'
+import { BaseGIS } from '@3clear/basegis'
+import { PointClusterController } from '@3clear/basegis/methods'
+import '@3clear/basegis/style.css'
+
+let mapCore = null
+let stationCluster = null
+
+const points = [
+  { id: 'A001', name: '站点 A', position: [121.4700, 31.2300] },
+  { id: 'A002', name: '站点 B', position: [121.4705, 31.2304] },
+  { id: 'A003', name: '站点 C', position: [121.4710, 31.2308] },
+]
+
+onMounted(async () => {
+  mapCore = new BaseGIS({
+    engineType: 'cesium',
+    containerId: 'station-cluster-map',
+    config: {
+      view: {
+        initialView: {
+          center: [121.4737, 31.2304],
+          height: 420000,
+          zoom: 8,
+          pitch: -90,
+        },
+      },
+    },
+  })
+
+  const initResult = mapCore.init()
+  if (!initResult.success) {
+    console.warn(initResult.message)
+    return
+  }
+
+  stationCluster = new PointClusterController({
+    mapCore,
+    layerId: 'station-cluster',
+
+    // 聚合网格大小，单位屏幕像素。值越大，点越容易聚在一起。
+    pixelRange: 72,
+
+    // 同一网格至少有 3 个点时才显示聚合圆。
+    minimumClusterSize: 3,
+
+    pointColor: '#36cfc9',
+    pointOutlineColor: '#e6fffb',
+    pointSize: 14,
+    clusterColor: '#1677ff',
+    clusterTextColor: '#ffffff',
+    clusterSize: 42,
+
+    // 默认 true。点击聚合圆后，当前引擎会自动向聚合中心放大。
+    zoomOnClusterClick: true,
+
+    onClick(point) {
+      console.log('点击单点：', point)
+    },
+
+    onClusterClick(cluster) {
+      console.log(`点击了包含 ${cluster.count} 个点的聚合圆`)
+      console.log(cluster.center, cluster.ids, cluster.points)
+    },
+
+    onStateChange(state) {
+      console.log('源点、聚合组、渲染对象：', {
+        sourceCount: state.sourceCount,
+        clusterCount: state.clusterCount,
+        renderedCount: state.renderedCount,
+      })
+    },
+  })
+
+  const loadResult = await stationCluster.load({
+    points,
+    visible: true,
+  })
+  if (!loadResult.success) {
+    console.warn(loadResult.message)
+  }
+})
+
+onBeforeUnmount(() => {
+  stationCluster?.destroy()
+  stationCluster = null
+  mapCore?.destroy()
+  mapCore = null
+})
+</script>
+
+<style scoped lang="scss">
+.station-cluster-map {
+  width: 100%;
+  height: 100%;
+}
+</style>
+```
+
+`load` 也支持直接传数组或 GeoJSON FeatureCollection：
+
+```js
+await stationCluster.load(points)
+await stationCluster.load(featureCollection)
+```
+
+点位既可以使用 `position: [经度, 纬度, 高度]`、`coordinates` 或直接坐标数组，也可以使用以下默认字段：
+
+- 经度：`longitude / lon / lng / x`
+- 纬度：`latitude / lat / y`
+- 高度：`height / altitude / z`
+- 唯一值：默认 `id`，可通过 `idKey` 指定
+
+### 更新聚合参数与数据
+
+```js
+// 让点位更容易形成聚合。
+await stationCluster.setConfig({
+  pixelRange: 96,
+  minimumClusterSize: 2,
+})
+
+// 替换数据，保留图层和其他配置。
+await stationCluster.update({
+  points: nextPoints,
+})
+```
+
+`clusterRadius` 是 `pixelRange` 的别名。两者同时传入时，以 `pixelRange` 为准。
+
+### 切换 Cesium / Leaflet
+
+聚合图层由 `BaseGIS` 托管。切换引擎时直接调用 `setEngine()`，无需在页面里重建 Cesium / Leaflet 分支；切换成功后，现有聚合数据和配置会通过托管快照自动恢复。
+
+```js
+const result = await mapCore.setEngine('leaflet')
+if (!result.success) {
+  console.warn(result.message)
+}
+```
+
+### 点击回调
+
+单点点击的第一个参数是原始点位数据：
+
+```js
+onClick(point, engineObject, event) {
+  console.log(point.id)
+}
+```
+
+聚合点击的第一个参数结构如下：
+
+```js
+{
+  layerId: 'station-cluster',
+  key: 'cluster:12:8',
+  count: 36,
+  center: [121.48, 31.23, 0],
+  ids: ['A001', 'A002'],
+  points: [/* 原始点位数据 */],
+}
+```
+
+`engineObject` 和 `event` 是当前引擎的拾取对象与事件，仅在确实需要底层信息时使用。通用业务逻辑应优先只读取第一个参数。
+
+### 显隐、清空和销毁
+
+```js
+stationCluster.hide()
+stationCluster.show()
+stationCluster.toggle()
+stationCluster.toggle(true)
+stationCluster.refreshState()
+
+// 清空数据但保留图层实例，后续仍可 update/load。
+stationCluster.clear()
+
+// 删除图层并释放监听与渲染资源。
+stationCluster.destroy()
+```
+
+| 方法 | 说明 |
+| --- | --- |
+| `mount(mapCore)` | 挂载 `BaseGIS`。构造时已传 `mapCore/baseGIS` 时无需重复调用。 |
+| `load(payload, options)` | 创建或覆盖聚合点数据，支持数组、FeatureCollection 或 `{ points }`。 |
+| `upsert(payload, options)` | `load` 的别名。 |
+| `update(payload)` | 合并现有配置，更新数据、样式或聚合参数。 |
+| `setConfig(payload)` | `update` 的别名，适合只表达参数更新。 |
+| `show()` / `hide()` / `toggle()` | 控制图层显隐。 |
+| `clear()` | 清空点位，保留图层实例。 |
+| `refreshState()` | 从当前引擎重新读取状态。 |
+| `destroy()` / `removeLayer()` | 删除图层并释放资源。 |
+| `getState()` | 获取控制器与引擎侧聚合状态。 |
+
+### 参数总表
+
+| 参数 | 是否必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `mapCore` / `baseGIS` | 构造时建议必填 | - | `BaseGIS` 实例。 |
+| `layerId` / `pointClusterLayerId` / `clusterLayerId` / `id` | 否 | `point-cluster-default` | 聚合图层 ID。 |
+| `points` / `data` / `items` | 首次加载必填其一 | - | 点位数组或 GeoJSON FeatureCollection。 |
+| `idKey` | 否 | `id` | 点位唯一值字段。 |
+| `longitudeKeys` / `latitudeKeys` / `heightKeys` | 否 | 内置常用字段 | 自定义坐标字段候选名。 |
+| `visible` | 否 | `true` | 初始是否显示。 |
+| `pixelRange` / `clusterRadius` | 否 | `64` | 屏幕聚合网格大小，单位像素。 |
+| `minimumClusterSize` | 否 | `2` | 形成聚合圆所需的最少点数，最小为 2。 |
+| `pointSize` | 否 | Cesium `16` / Leaflet `14` | 未传图片时的圆点尺寸。 |
+| `pointWidth` / `pointHeight` | 否 | `pointSize` | 单点图片显示尺寸。 |
+| `pointColor` | 否 | `#3aa7ff` | 默认单点填充色。 |
+| `pointOutlineColor` / `pointOutlineWidth` | 否 | 白色 / `2` | 默认单点描边。 |
+| `image` / `pointImage` / `icon` / `iconUrl` | 否 | - | 自定义单点图片。 |
+| `imageCallback` | 否 | - | 按点位返回图片地址或图标配置。 |
+| `clusterSize` | 否 | `42` | 聚合圆基础尺寸；数量增大时会轻微放大。 |
+| `clusterColor` | 否 | `#1677ff` | 聚合圆背景色。 |
+| `clusterTextColor` | 否 | `#ffffff` | 聚合数量文字颜色。 |
+| `clusterOutlineColor` / `clusterOutlineWidth` | 否 | 白色 / `3` | 聚合圆描边。 |
+| `clusterImageCallback` | 否 | - | 默认图标由双引擎共用 Canvas 生成；可返回自定义图片地址、Canvas 或图标配置。 |
+| `zoomOnClusterClick` | 否 | `true` | 点击聚合圆后是否自动放大。 |
+| `throttleTime` | 否 | `100` | 地图变化后重新聚合的节流时间，毫秒。 |
+| `onClick` | 否 | - | 单点点击回调。 |
+| `onClusterClick` | 否 | - | 聚合点击回调。 |
+| `onStateChange` | 否 | - | 聚合状态变化回调。 |
+| `viewportBuffer` | 否 | `80` | Cesium 专用：屏幕视野缓冲像素。 |
+| `cullByGlobe` | 否 | `true` | Cesium 专用：剔除地球背面点。 |
+| `clampToGround` | 否 | `false` | Cesium 专用：单点是否贴地。 |
+| `clusterZoomFactor` | 否 | `0.45` | Cesium 专用：每次点击后的目标高度比例。 |
+| `clusterZoomStep` | 否 | `2` | Leaflet 专用：每次点击增加的缩放级别。 |
+| `maxClusterZoom` | 否 | `Infinity` | Leaflet 专用：聚合点击最大缩放级别。 |
+| `zIndexOffset` | 否 | `0` | Leaflet 专用：Marker 层级偏移。 |
+
+### 状态返回
+
+```js
+const state = stationCluster.getState()
+
+console.log(state)
+// {
+//   engineType: 'leaflet',
+//   layerType: 'leaflet-point-cluster-layer',
+//   sourceCount: 10000,
+//   inViewCount: 9800,
+//   outOfViewCount: 200,
+//   clusterCount: 185,
+//   clusteredPointCount: 9600,
+//   visiblePointCount: 200,
+//   renderedCount: 385,
+//   pixelRange: 72,
+//   minimumClusterSize: 3,
+//   visible: true,
+//   destroyed: false,
+// }
+```
+
+其中 `renderedCount = clusterCount + visiblePointCount`；被聚合的原始点数量单独记录在 `clusteredPointCount`，不会和聚合圆数量混淆。
+
+底层统一方法也可直接通过 `BaseGIS` 调用：
+
+```js
+mapCore.upsertPointClusterLayer(payload)
+mapCore.showPointClusterLayer({ layerId: 'station-cluster' })
+mapCore.hidePointClusterLayer({ layerId: 'station-cluster' })
+mapCore.clearPointClusterLayer({ layerId: 'station-cluster' })
+mapCore.getPointClusterLayerState({ layerId: 'station-cluster' })
+mapCore.removePointClusterLayer({ layerId: 'station-cluster' })
+```
+
+<a id="point-density-controller"></a>
+
 ## PointDensityController
 
 用于点位密度抽稀。地图移动、缩放后会按当前视野和屏幕网格重新计算可见点，适合站点、设备、告警、空气质量监测点等高密度点位。
@@ -2170,9 +3084,35 @@ console.log(state)
 // }
 ```
 
-## ContourLayerController
+<a id="contour-guide"></a>
+
+## 等值线与中心标注能力选择
+
+对外只保留 2 个控制器：已有线坐标或中心坐标时用 `ContourLayerController`，手里是栅格时用 `RasterContourController`。线值标签与中心标注都属于通用 Contour 渲染配置，不再需要单独的气压组合层。
+
+| 手里的数据 / 目标 | 使用入口 | 负责内容 |
+| --- | --- | --- |
+| 已经计算好的等值线，可选已有中心点 | [`ContourLayerController`](#contour-layer-controller) | 渲染线、线值标签和传入的 `centers`，并管理统一生命周期。 |
+| GeoTIFF、灰度图或数值网格 | [`RasterContourController`](#raster-contour-controller) | 读取栅格、追踪等值线；显式开启后可从网格检测局部 H/L 中心。 |
+
+两条数据链路：
+
+```text
+已有 isolines + 可选 centers ──> ContourLayerController ──> 线 + 标签 + 中心
+GeoTIFF / 灰度图 / 数值网格 ──> RasterContourController ──> ContourLayerController ──> 地图
+```
+
+特别注意：
+
+- `ContourLayerController` 只渲染传入的 `centers`，不会从已有线坐标反推极值中心。
+- `RasterContourController.centerDetection` 默认关闭；只有气压等确实需要 H/L 语义的数值网格才应显式开启。
+- 两个控制器都不转换业务单位或 Windy 原始格式；传入值就是最终计算和展示值。
 
-用于等值线图层，支持加载、更新、显隐、清空和销毁。
+<a id="contour-layer-controller"></a>
+
+## ContourLayerController：渲染已有等值线与中心标注
+
+负责渲染已经计算好的线和业务传入的中心坐标，不读取栅格，也不执行插值或等值线追踪。Cesium / Leaflet 共用同一套数据、样式和生命周期 API。
 
 ```js
 import { ContourLayerController } from '@3clear/basegis/methods'
@@ -2181,6 +3121,10 @@ const contour = new ContourLayerController({
   mapCore,
   layerId: 'temperature-contour',
   visible: true,
+  color: '#ff4d4f',
+  width: 2,
+  showLabel: true,
+  labelFormatter: (item) => `${item.value}℃`,
 })
 
 await contour.load({
@@ -2188,6 +3132,7 @@ await contour.load({
     {
       value: 20,
       lines: [
+        // 默认坐标顺序是 [纬度, 经度]。
         [
           [30, 104],
           [31, 105],
@@ -2196,18 +3141,11 @@ await contour.load({
       ],
     },
   ],
-  style: {
-    color: '#ff4d4f',
-    width: 2,
-  },
-  showLabel: true,
-  labelFormatter: (item) => String(item.value),
 })
 
 await contour.update({
-  style: {
-    color: '#1677ff',
-  },
+  color: '#1677ff',
+  width: 1.5,
 })
 
 contour.hide()
@@ -2216,13 +3154,63 @@ contour.clear()
 contour.destroy()
 ```
 
-数据别名支持 `contours / isolines / isoline / lines / data / items`。开启 `showLabel` 后，Cesium 和 Leaflet 都会根据当前屏幕范围重新选择可见线段上的位置；地图平移、缩放、容器尺寸变化或切换引擎时只重排标签，不重新生成等值线。
+样式参数必须放在配置顶层，或通过 `styleCallback` 按线返回；`style: { color, width }` 不会生效。
+
+### 输入数据
+
+推荐使用 `{ value, lines }` 结构：
+
+```js
+const contours = [
+  {
+    value: 20,
+    label: '20℃',
+    lines: [
+      // 一条等值线；默认每个坐标是 [纬度, 经度]。
+      [[30, 104], [31, 105], [32, 106]],
+    ],
+  },
+]
+```
+
+还支持：
+
+- `{ value, coordinates: [[lat, lon], ...] }`
+- `{ value, points: [lat, lon, lat, lon, ...] }`
+- GeoJSON `LineString` / `MultiLineString` Feature；GeoJSON 坐标按标准 `[经度, 纬度]` 解析
+- 原始线数组，以及顶层字段别名 `contours / isolines / isoline / lines / data / items`
+
+传 GeoJSON FeatureCollection 时，请传 `featureCollection.features` 或 `{ contours: featureCollection.features }`。
+
+<a id="contour-layer-parameters"></a>
+
+### 核心参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `mapCore/baseGIS` | `BaseGIS` | - | 当前 `BaseGIS` 实例；构造时不传则后续调用 `mount(mapCore)`。 |
+| `layerId/contourLayerId` | `string` | `contour-default` | 图层唯一 ID。 |
+| `coordinateOrder` | `latlng/lnglat` | `latlng` | `lines/coordinates` 的嵌套坐标顺序。 |
+| `flatOrder` | `latlng/lnglat` | `latlng` | `points` 平铺数组的坐标顺序。 |
+| `color` | `string` | `rgba(255,255,255,0.82)` | 默认线色。 |
+| `width/weight` | `number` | `1.15` | 线宽；两种写法用于兼容双引擎。 |
+| `opacity` | `number` | `1` | 线透明度。 |
+| `styleCallback(rawItem, line, lineIndex, record)` | `Function` | - | 按原始记录和线段返回动态样式。 |
+| `splitWrappedLine` | `boolean` | `true` | 是否拆分跨日期变更线的异常跳线。 |
+| `worldCopyOffsets` | `number[]` | Cesium `[0]`；Leaflet `[-360,0,360]` | 世界副本经度偏移。 |
+| `visible` | `boolean` | `true` | 初始是否显示。 |
+
+Cesium 专用参数包括 `height / clampToGround / granularity / lineThinStep`；Leaflet 专用参数包括 `smoothFactor / lineCap / lineJoin / interactive / pane`。
+
+### 双引擎渲染说明
+
+开启 `showLabel` 后，Cesium 和 Leaflet 都会根据当前屏幕范围重新选择可见线段上的标签位置。Leaflet 传入经度跨度达到 360° 的 `worldCopyArea` 后，还会按当前视野动态更新等值线路径和标签的世界副本；这个过程只重建可见路径，不重新解析栅格或追踪等值线。`RasterContourController` 会自动把栅格范围作为 `worldCopyArea` 传入。
 
 Cesium 在默认椭球地表上使用 `PolylineCollection` 批量落图；真正启用 DEM 地形后才使用 `GroundPolylinePrimitive`。新批次就绪后再替换旧批次，不为每条线创建独立 Entity。标签定位可通过 `labelLineThinStep` 抽样投影点，不会改变实际绘制的等值线。
 
 Leaflet 默认复用高精度 SVG renderer，并使用 `smoothFactor: 0.5` 做屏幕空间简化：缩小时清理挤在同一像素内的折点，放大后自动保留曲线细节，避免全局 `preferCanvas` 放大细线锯齿。线位于 `dt-contour-pane`（层级 `450`），稳定显示在图片图层上方，并保持在 `markerPane` 数值标签下方；显式传入 `pane` 时仍以业务配置为准。
 
-屏幕标注参数：
+### 通用线值标签参数
 
 | 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
@@ -2244,11 +3232,28 @@ Leaflet 默认复用高精度 SVG renderer，并使用 `smoothFactor: 0.5` 做
 
 `getState()` 的 `labelCount` 是当前视野实际显示的标签数量。Cesium 状态额外包含 `lineRenderer/lineBuildElapsed/labelLayoutElapsed/primitiveReadyElapsed`，用于区分线构建、标签排版和异步就绪耗时。`onStateChange(state)` 会在视野重排后回传新状态。页面存在侧栏等遮挡时，可通过 `labelViewportPadding` 排除对应区域。
 
-## RasterContourController
+### 生命周期与状态
+
+| 方法 | 说明 |
+| --- | --- |
+| `mount(mapCore)` | 后挂载 `BaseGIS`；构造时已传入则无需调用。 |
+| `load(payload, options)` / `upsert(...)` | 首次创建或覆盖图层，必须包含等值线数据或 `centers`。 |
+| `update(payload)` / `setConfig(...)` | 合并数据或渲染参数并更新已经加载的图层。 |
+| `show()` / `hide()` / `toggle(visible)` | 控制图层显隐。 |
+| `clear()` | 清空线、线值标签和中心标注，但保留图层实例，可再次加载。 |
+| `refreshState()` | 从当前引擎重新读取状态。 |
+| `getState()` | 返回普通状态对象，包括 `levelCount / lineCount / centerCount / lineLabelCount / centerLabelCount / labelCount / visible`。 |
+| `destroy()` / `removeLayer()` | 删除图层、释放资源，并移除 `BaseGIS` 托管快照。 |
+
+推荐顺序：`BaseGIS.init()` 成功后创建控制器并 `load()`；页面卸载时先 `contour.destroy()`，再 `mapCore.destroy()`。
+
+<a id="raster-contour-controller"></a>
 
-用于从 GeoTIFF、灰度图或数值网格直接计算并绘制等值线。内部统一使用 `d3-contour` 追踪等值线，输出仍交给 `ContourLayerController`，所以页面不需要区分 Cesium 和 Leaflet；调用 `BaseGIS.setEngine()` 时，已经生成的等值线会随托管图层自动恢复。
+## RasterContourController：从栅格生成等值线
 
-### 1. GeoTIFF 生成等值线
+负责完整的“读取数据源 → 标准化数值网格 → 追踪等值线 → 双引擎渲染”链路。内部使用 `d3-contour` 生成线，再交给 `ContourLayerController` 渲染；页面不需要区分 Cesium 和 Leaflet。调用 `BaseGIS.setEngine()` 时，已经生成的线会随托管图层自动恢复。
+
+### GeoTIFF
 
 ```js
 import { RasterContourController } from '@3clear/basegis/methods'
@@ -2294,7 +3299,7 @@ await rasterContour.update({ interval: 2 })
 
 GeoTIFF 依赖宿主页面提供 `window.GeoTIFF`。控制器会读取波段、尺寸、坐标系和范围；当前原生支持 EPSG:4326、EPSG:3857。其他投影可先转换为 WGS84，或传入 WGS84 `area` 覆盖原始范围。
 
-### 2. 灰度图生成等值线
+### 灰度图
 
 ```js
 await rasterContour.loadGrayImage({
@@ -2318,7 +3323,9 @@ await rasterContour.loadGrayImage({
 
 灰度图片本身没有地理范围和业务值含义，因此 `area` 必填；要表达真实数据，还应传正确的灰度范围与业务值范围。已经着色的彩色 PNG 不能反推出原始业务值，应使用对应 TIF 或直接传数值网格。
 
-### 3. 数值网格生成等值线
+上例虽然使用了气压值域，但 `centerDetection` 默认关闭，因此只生成普通等压线和线值标签。需要 H/L 中心时，按下方“自动检测 H/L 中心”配置显式开启。
+
+### 数值网格
 
 ```js
 await rasterContour.loadGrid({
@@ -2340,13 +3347,13 @@ await rasterContour.loadGrid({
 })
 ```
 
-### 4. 参数
+### 参数
 
 数据源参数：
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 | --- | --- | --- | --- | --- |
-| `mapCore/baseGIS` | `BaseGIS` | 构造时必填 | `null` | 当前 BaseGIS 实例。 |
+| `mapCore/baseGIS` | `BaseGIS` | 否 | `null` | 当前 BaseGIS 实例；构造时不传则后续调用 `mount(mapCore)`。 |
 | `layerId/contourLayerId` | `string` | 否 | `raster-contour-default` | 等值线图层 id。 |
 | `sourceType` | `geotiff/grayscale/grid` | 否 | 自动判断 | `loadGeoTiff/loadGrayImage/loadGrid` 会自动补齐。 |
 | `tifUrl/tiffUrl` | `string` | GeoTIFF 必填 | `''` | GeoTIFF 地址。 |
@@ -2377,91 +3384,127 @@ await rasterContour.loadGrid({
 | `minimumLinePoints` | `number` | 否 | `3` | 最短线点数，用于过滤栅格四角的两点补边。 |
 | `coordinatePrecision` | `number` | 否 | `6` | 输出经纬度小数位数。 |
 | `visible` | `boolean` | 否 | `true` | 初始显隐。 |
-| 其他渲染参数 | - | 否 | - | 与 `ContourLayerController` 相同，如 `color/width/weight/styleCallback/showLabel/labelViewportPadding`。 |
+| 其他渲染参数 | - | 否 | - | 复用 [`ContourLayerController` 核心参数](#contour-layer-parameters)，如 `color/width/weight/styleCallback/showLabel/labelViewportPadding`。 |
+
+级别选择优先级为 `thresholds` → `interval` → `thresholdCount`。显式传入 `thresholds` 时，只保留实际值域内的级别。
+
+### 自动检测 H/L 中心
+
+该能力默认关闭。它使用标准化后的数值网格查找局部极大值（H）和局部极小值（L），而不是根据已经生成的线反推。因此只应用于确实存在 H/L 语义的栅格数据。
+
+```js
+await rasterContour.loadGrid({
+  values: pressureValues,
+  width,
+  height,
+  area: [70, 10, 140, 60],
+  interval: 4,
+  showLabel: true,
+  centerDetection: {
+    enabled: true,
+    radius: 6,
+    minProminence: 2,
+    minGridDistance: 20,
+    maxCount: 12,
+  },
+  centerAnnotation: {
+    visible: true,
+    collision: true,
+    color: '#e3f8ff',
+    valueColor: '#ffffff',
+  },
+})
+```
 
-### 5. 方法和状态
+| `centerDetection` 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `false` | 开启 H/L 自动检测。 |
+| `radius` | `6` | 计算局部显著度的网格半径。 |
+| `minProminence` | `2` | 中心值与邻域平均值的最小差异，单位与输入网格一致。 |
+| `minGridDistance` | `20` | 同类中心的最小网格距离，距离过近时合并。 |
+| `maxCount` | `12` | H/L 合计最大输出数。 |
+| `includeHigh/includeLow` | `true/true` | 是否输出 H 或 L。 |
+| `excludeBoundary` | `true` | 排除贴近边界或 NoData 空洞的候选。 |
+| `smoothingIterations` | `1` | 3×3 有效值平滑次数，范围 0~3。 |
+
+检测流程会先进行轻量平滑，再按显著度过滤、合并过近的同类中心并限制数量。超过 100 万格时只对候选搜索做块均值抽样，最终仍回到原网格取精确值和坐标。关闭检测后会清理上一次自动中心。
+
+`RasterContourController` 也可直接传顶层 `centers`。手工数组（包括 `[]`）优先于自动检测；传 `centers: null` 可恢复使用当前 `centerDetection` 的结果。检测只产生中心数据，仍需 `centerAnnotation.visible: true` 才会显示。
+
+### 方法和状态
 
 | 方法 | 说明 |
 | --- | --- |
+| `mount(mapCore)` | 后挂载 `BaseGIS`；构造时已传入则无需调用。 |
 | `load(payload, options)` | 自动判断数据源并生成等值线。 |
 | `loadGeoTiff(payload, options)` | 从 GeoTIFF 生成。 |
 | `loadGrayImage(payload, options)` | 从灰度图生成。 |
 | `loadGrid(payload, options)` | 从数值网格生成。 |
 | `update(payload)` | 合并配置后重新计算；仅修改等值线或渲染参数时复用已解析网格，修改数据源参数时自动重新加载。 |
-| `show/hide/toggle` | 控制等值线显隐。 |
+| `show/hide/toggle` | 统一控制等值线、线值标签和中心标注显隐。 |
 | `clear/destroy` | 清空或销毁控制器。 |
-| `getState()` | 返回尺寸、值域、级别、线数、当前标注数、投影、耗时和底层 contour 状态。 |
+| `getState()` | 返回尺寸、值域、级别、线数、`centerCount`、标注数、投影、耗时和底层 contour 状态。 |
 | `getRasterData()` | 返回当前标准栅格，包含 `values/width/height/area`。 |
 
-[//]: # ()
-[//]: # (## PressureContourLayer)
-
-[//]: # ()
-[//]: # (用于等压线和高低压中心标注。`buildPressureRenderData&#40;&#41;` 可把 Windy 风格的 `press.json` 数据整理成渲染结构，`createPressureDataResolver&#40;&#41;` 提供简单缓存。)
-
-[//]: # ()
-[//]: # (```js)
-
-[//]: # (import {)
-
-[//]: # (  PressureContourLayer,)
-
-[//]: # (  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,)
+```js
+// clear 只清空当前渲染结果，控制器仍可继续 update/load。
+rasterContour.clear()
 
-[//]: # (}&#41;)
+// 页面卸载时彻底释放栅格、图层和监听。
+rasterContour.destroy()
+```
+<a id="contour-center-annotation"></a>
 
-[//]: # ()
-[//]: # (pressureLayer.mount&#40;&#41;)
+## 中心标注配置（两个控制器通用）
 
-[//]: # (await pressureLayer.load&#40;resolvePressureData&#40;'default'&#41;&#41;)
+`ContourLayerController` 通过顶层 `centers` 接收已经计算好的中心点，通过 `centerAnnotation` 控制显示和样式。该能力是通用标注，不把数据限制为气压；H/L 只是气压业务中的一种标签。
 
-[//]: # (await pressureLayer.update&#40;resolvePressureData&#40;'next'&#41;&#41;)
+```js
+const pressureContour = new ContourLayerController({
+  mapCore,
+  layerId: 'pressure-contour',
+  showLabel: true,
+  labelFormatter: (item) => String(item.value),
+  centerAnnotation: {
+    visible: true,
+    collision: true,
+    color: '#e3f8ff',
+    fontSize: 20,
+    valueColor: '#ffffff',
+    valueFontSize: 12,
+  },
+})
 
-[//]: # (pressureLayer.hide&#40;&#41;)
+await pressureContour.load({
+  isolines: [
+    {
+      value: 1012,
+      lines: [[[31, 116.5], [31.4, 117.2], [31.7, 118]]],
+    },
+  ],
+  centers: [
+    { type: 'H', value: 1020, lat: 32.1, lon: 117.3 },
+    { type: 'L', value: 1004, lat: 30.5, lon: 116.8 },
+  ],
+})
+```
 
-[//]: # (pressureLayer.destroy&#40;&#41;)
+`centers[]` 支持 `{ label, type, value, lat, lon }`，也支持 `position`。对象坐标字段固定按语义读取；`position` 数组遵循 `coordinateOrder`。主标签优先读取 `label`，其次读取 `type`。
 
-[//]: # (```)
+| `centerAnnotation` 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `visible` | `false` | 是否显示中心标注。数据与显示配置分开，传入 centers 不会自动开启。 |
+| `collision` | `true` | 是否避让其他中心；中心先占位，线值标签随后避让。 |
+| `formatter(raw, center)` | - | 返回文本，或返回 `{ label, value }`。 |
+| `styleCallback(raw, index, center)` | - | 按中心覆盖颜色、字号、字重或返回 `visible:false`。 |
+| `color/fontSize` | `#34464f / 18` | 主标签颜色与字号。 |
+| `valueColor/valueFontSize` | 跟随 `color` / `12` | 数值颜色与字号；`color` 也未传时颜色为 `#34464f`。 |
+| `collisionPadding` | `8` | 碰撞间距，单位 px。 |
+| `viewportPadding` | `24` | 屏幕安全边距。 |
 
-说明：
+状态中的 `centerCount` 是成功解析的有效中心数，`lineLabelCount` 和 `centerLabelCount` 是当前视野实际显示数，`labelCount` 是两者合计。`show/hide/clear/destroy` 以及 `BaseGIS.setEngine()` 会和等值线一起管理这些中心标注。
 
-- 等压线数据会被整理为 `isolines` 和 `centers`。
-- Leaflet 使用 `divIcon` 绘制 H/L 中心和线值标签。
-- Cesium 使用独立标注集合，地图变化时会调度刷新。
+<a id="wind-field-methods"></a>
 
 ## WindFieldMethods
 
@@ -2689,7 +3732,7 @@ const result = await setEngine('leaflet')
 console.log(result.data?.restore)
 ```
 
-只有风场、剖面、一次性绘制对象或页面直接创建的底层引擎对象需要在切换成功后自行恢复。
+只有 GPU 专用风场、剖面、一次性绘制对象或页面直接创建的底层引擎对象需要在切换成功后自行恢复。
 
 ## 能力支持说明
 
@@ -2700,9 +3743,11 @@ console.log(result.data?.restore)
 | 放大、缩小、重置 | 支持 | 支持 |
 | 底图切换 | 支持 | 支持 |
 | 点线面文字 | 支持 | 支持 |
+| 独立线、虚线、渐变与沿线动画 | 支持 | 支持 |
 | 图片覆盖层 | 支持 | 支持 |
 | 网格 / TIF | 支持 | 支持 |
 | 海量点 | 支持 | 支持 |
+| 点位聚合 | 支持 | 支持 |
 | 点位密度抽稀 | 支持 | 支持 |
 | 等值线 | 支持 | 支持 |
 | 等压线标注 | 支持 | 支持 |
@@ -2711,6 +3756,34 @@ console.log(result.data?.restore)
 | 三维切片 / 剖面渲染 | 支持 | 不支持 |
 | DEM 地形 | 支持 | 不支持 |
 
+## 第三方许可
+
+GPU 粒子风场核心改编自 RaymanNg/3D-Wind-Field：
+
+```text
+MIT License
+
+Copyright (c) 2019 RaymanNg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## 本地开发与打包
 
 在仓库根目录执行：
@@ -2821,7 +3894,7 @@ mapCore.init()
 
 ### 切换引擎后图层没了
 
-直接使用 `setEngine()`。BaseGIS 会保留视野，并自动恢复图片、网格、海量点、点位抽稀、等值线和三维体等托管图层：
+直接使用 `setEngine()`。BaseGIS 会保留视野，并自动恢复图片、网格、海量点、点位聚合、点位抽稀、独立线、等值线、统一风场和三维体等托管图层：
 
 ```js
 const result = await mapCore.setEngine('leaflet')
@@ -2830,4 +3903,4 @@ console.log(result.data?.restore?.restored)
 console.log(result.data?.restore?.failed)
 ```
 
-如果丢失的是 `drawPoint/drawLine/drawPolygon/drawText/addMarker`、点击监听、风场、剖面图层或页面直接创建的 Cesium / Leaflet 对象，它们不属于托管图层，需要业务在切换成功后自行恢复。
+如果丢失的是 `drawPoint/drawLine/drawPolygon/drawText/addMarker`、点击监听、GPU 专用风场、剖面图层或页面直接创建的 Cesium / Leaflet 对象，它们不属于托管图层，需要业务在切换成功后自行恢复。