@3clear/basegis 0.1.3 → 0.1.4

package/README.md

@@ -5,29 +5,194 @@
 当前包包含：
 
 - `BaseGIS`：地图初始化、引擎切换、视角控制、底图切换、绘制、图层显隐、DEM、点击事件、Cesium / Leaflet 统一粒子风场、GPU 粒子风场、三维体渲染、三维切片/剖面渲染等基础能力。
-- `methods`：图片图层、网格图层、海量点、点位抽稀、等值线、等压线、风场、图形组等高级控制器。
+- `methods`：独立线图层、图片图层、网格图层、海量点、点位聚合、点位抽稀、等值线、风场、图形组等高级控制器。
 - `layers`：天地图、GeoServer 金字塔瓦片、WMS、WMTS 图层配置快捷构造器。
 - `assets`：GIS 示例资源。
 - `style.css`：Leaflet、GIS 图层和标注相关基础样式。
 
 ## 能力总览
 
-下表以当前 npm 包的真实出口和本项目源码为准。使用位置列展示原测试路由，点击后会在新标签页打开代码演练场，并通过 `path` 参数自动选中对应路由；没有独立页面的辅助函数与其所属控制器合并展示。
-
-| <small>导出 / 能力</small> | <small>功能</small> | <small>在本项目中的使用位置或路由</small> |
-| --- | --- | --- |
-| <small>[`BaseGIS`](#base-gis)</small> | <small>Cesium / Leaflet 统一入口，负责地图初始化、引擎切换、视角控制、场景模式、底图、DEM、绘制、点击事件，以及 GeoJSON、风场、三维体渲染和剖面渲染等能力。</small> | <small>基础能力：<a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a><br>专项能力：<a href="http://61.50.111.214:31166/lgmap/test-page-14" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-15" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-20" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-21" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-23" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`GraphicGroupController`](#graphic-group-controller)</small> | <small>统一装载和清理一组点、线、面、文字及 Marker 图形。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`ImageLayerController` / `toImageLayerArea`](#image-layer-controller)</small> | <small>加载普通图片、GeoTIFF、灰度图着色和多时次栅格，并提供范围参数转换。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`GridLayerController`](#grid-layer-controller)</small> | <small>加载灰度图或 GeoTIFF 数值网格，支持着色、探针、网格注记和生命周期控制。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`PointLargeLayerController`](#point-large-layer-controller)</small> | <small>面向海量点位的异步构建、样式规则、点击、高亮、删除和显隐控制。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-5" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`PointDensityController`](#point-density-controller)</small> | <small>点位视野裁剪和屏幕网格抽稀，支持动态图标、点击回调、配置更新和状态统计。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-8" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-9" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-13" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`PressureContourLayer` / `createPressureDataResolver` / `buildPressureRenderData`](#pressure-contour-layer)</small> | <small>解析气压数据并生成等值线、数值标签及高低压中心标注。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-7" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`ContourLayerController`](#contour-layer-controller)</small> | <small>统一管理等值线图层的加载、更新、显隐、引擎切换和销毁。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`RasterContourController`](#raster-contour-controller)</small> | <small>从 GeoTIFF、灰度图或数值网格提取并渲染等值线。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`WindFieldMethods`](#wind-field-methods)</small> | <small>提供 Cesium / Leaflet 风场数据加载、粒子动画、速度底图、交互和生命周期控制。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`createTiandituLayer` / `createGeoserverPyramidLayer` / `createWmsLayer` / `createWmtsLayer`](#layer-config-builders)</small> | <small>构造天地图、GeoServer 金字塔瓦片、WMS 和 WMTS 图层配置。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
-| <small>[`gisMarkerSample`](#gis-marker-sample)</small> | <small>可直接导入的 GIS Marker 示例资源。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+以下按类型展示 `@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>
 
 ## 安装
 
@@ -55,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'
 
@@ -352,7 +517,7 @@ const mapCore = new BaseGIS({
 
 ## BaseGIS 基础能力
 
-这一节列的是 `BaseGIS` 主入口直接提供的基础能力。业务页面优先调用这些方法；图片图层、网格图层、海量点、点位抽稀、等值线、风场等更复杂能力，建议使用后文 `methods` 中对应的 Controller。
+这一节列的是 `BaseGIS` 主入口直接提供的基础能力。业务页面优先调用这些方法；图片图层、网格图层、海量点、点位聚合、点位抽稀、等值线、风场等更复杂能力，建议使用后文 `methods` 中对应的 Controller。
 
 ### 1. 生命周期、实例与引擎切换
 
@@ -453,7 +618,7 @@ if (result.success) {
 
 引擎切换不是把 Cesium 图层对象“搬到” Leaflet，也不是把 Leaflet 图层对象“搬到” Cesium。BaseGIS 会保存托管图层的业务参数，并在新 adapter 中重新创建图层。
 
-- 自动恢复范围包括图片、网格、海量点、点位抽稀、等值线和三维体图层，对应 `upsert*Layer` 方法及 Controller。
+- 自动恢复范围包括图片、网格、海量点、点位聚合、点位抽稀、独立线、等值线、统一风场和三维体图层，对应 `upsert*Layer` 方法及 Controller。
 - 图层最新的数据参数、显隐、清空、删除、海量点删除和高亮状态会同步到 BaseGIS 快照。
 - 快照只保存业务参数引用，不复制大数组，不保存任何底层引擎对象。
 - 三维体图层切到 Leaflet 时会返回不支持结果，但快照仍保留，切回 Cesium 后会继续恢复。
@@ -571,7 +736,7 @@ viewListener.data?.off?.()
 
 ### 4. 绘制点、线、面、文字和 Marker
 
-这些方法用于轻量绘制和样例验证。大量点位或复杂业务图层请优先使用后文的 `PointLargeLayerController`、`PointDensityController`、`GraphicGroupController` 等控制器。
+这些方法用于轻量绘制和样例验证。大量点位或复杂业务图层请优先使用后文的 `PointLargeLayerController`、`PointClusterController`、`PointDensityController`、`GraphicGroupController` 等控制器。
 
 点：
 
@@ -767,7 +932,7 @@ Leaflet 当前返回坐标点击：
 说明：
 
 - 基础 `onClick` 适合地图空白点击、简单 Entity 点击。
-- 海量点、点位抽稀等图层自己的点击事件，应使用对应 Controller 的 `onClick` 参数。
+- 海量点、点位聚合、点位抽稀等图层自己的点击事件，应使用对应 Controller 的点击回调参数。
 
 
 <a id="graphic-group-controller"></a>
@@ -809,12 +974,164 @@ 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
@@ -996,57 +1313,26 @@ await imageLayer.update({
 
 Leaflet 会对经度跨度达到 360° 的全球图片按当前视野自动补充相邻世界副本，全球 TIF / 灰度格点的注记和鼠标探针也会使用同一套经度循环，因此业务页面不需要手动创建 `±360°` 图片层。原始图片按 `0° ~ 360°` 排列时传 `isSplit: true`，适配层会在交换左右半幅的同时把显示范围统一为 `-180° ~ 180°`，确保图片与格点值落在同一经度位置。
 
-`loadGrayImage` 的灰度值换算规则：
+### 4. 仅 TIF 数值层
 
-```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 渲染的场景。
+只传 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,
 })
 ```
 
@@ -1138,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`。如果地图已销毁，只清本地状态。 |
@@ -1179,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` | 选填 | 切片网格数量。 |
@@ -1207,7 +1493,15 @@ imageLayer.destroy({ layerId: 'radar-image' })
 
 ## 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'
@@ -1222,7 +1516,6 @@ const gridLayer = new GridLayerController({
 
 await gridLayer.loadTif({
   tifUrl: '/data/grid/temp.tif',
-  colorize: true,
 })
 
 await gridLayer.loadGrayImage({
@@ -1233,7 +1526,7 @@ await gridLayer.loadGrayImage({
     endLon: 135,
     endLat: 54,
   },
-  // 灰度图需要把灰度值映射成业务值，再按业务值找色带。
+  // 灰度图需要把灰度值映射成业务值。
   colorize: {
     // 必填建议：业务值最小值。
     minValue: -20,
@@ -1249,24 +1542,34 @@ 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 粒子风场。
@@ -1437,6 +1740,8 @@ mapCore.removeGpuWindLayer({ layerId: 'surface-gpu-wind' })
 
 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 调用时会返回不支持结果，不会抛出破坏页面的异常。
@@ -1563,6 +1868,8 @@ console.log(stateResult.data)
 | `geometry` / `dim` | 选填 | 自定义体渲染几何或维度，普通业务通常不需要传。 |
 | `visible` | 选填 | 初始是否显示，默认显示。 |
 
+<a id="section-rendering"></a>
+
 ## 三维切片 / 剖面渲染
 
 三维切片/剖面渲染也是 Cesium 专有能力，直接通过 `BaseGIS` 调用。它把三维网格数据按 X、Y、Z 三个方向切出剖面，适合气象温度、湿度、风场标量、污染物浓度等三维格点数据查看。
@@ -2109,6 +2416,313 @@ 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
@@ -2470,11 +3084,35 @@ console.log(state)
 // }
 ```
 
+<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
+## ContourLayerController：渲染已有等值线与中心标注
 
-用于等值线图层，支持加载、更新、显隐、清空和销毁。
+负责渲染已经计算好的线和业务传入的中心坐标，不读取栅格，也不执行插值或等值线追踪。Cesium / Leaflet 共用同一套数据、样式和生命周期 API。
 
 ```js
 import { ContourLayerController } from '@3clear/basegis/methods'
@@ -2483,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({
@@ -2490,6 +3132,7 @@ await contour.load({
     {
       value: 20,
       lines: [
+        // 默认坐标顺序是 [纬度, 经度]。
         [
           [30, 104],
           [31, 105],
@@ -2498,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()
@@ -2518,13 +3154,63 @@ contour.clear()
 contour.destroy()
 ```
 
-数据别名支持 `contours / isolines / isoline / lines / data / items`。开启 `showLabel` 后，Cesium 和 Leaflet 都会根据当前屏幕范围重新选择可见线段上的位置。Leaflet 传入经度跨度达到 360° 的 `worldCopyArea` 后，还会按当前视野动态更新等值线路径和标签的世界副本；这个过程只重建可见路径，不重新解析栅格或追踪等值线。`RasterContourController` 会自动把栅格范围作为 `worldCopyArea` 传入。
+样式参数必须放在配置顶层，或通过 `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` 时仍以业务配置为准。
 
-屏幕标注参数：
+### 通用线值标签参数
 
 | 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
@@ -2546,13 +3232,28 @@ Leaflet 默认复用高精度 SVG renderer，并使用 `smoothFactor: 0.5` 做
 
 `getState()` 的 `labelCount` 是当前视野实际显示的标签数量。Cesium 状态额外包含 `lineRenderer/lineBuildElapsed/labelLayoutElapsed/primitiveReadyElapsed`，用于区分线构建、标签排版和异步就绪耗时。`onStateChange(state)` 会在视野重排后回传新状态。页面存在侧栏等遮挡时，可通过 `labelViewportPadding` 排除对应区域。
 
+### 生命周期与状态
+
+| 方法 | 说明 |
+| --- | --- |
+| `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>
 
-## RasterContourController
+## RasterContourController：从栅格生成等值线
 
-用于从 GeoTIFF、灰度图或数值网格直接计算并绘制等值线。内部统一使用 `d3-contour` 追踪等值线，输出仍交给 `ContourLayerController`，所以页面不需要区分 Cesium 和 Leaflet；调用 `BaseGIS.setEngine()` 时，已经生成的等值线会随托管图层自动恢复。
+负责完整的“读取数据源 → 标准化数值网格 → 追踪等值线 → 双引擎渲染”链路。内部使用 `d3-contour` 生成线，再交给 `ContourLayerController` 渲染；页面不需要区分 Cesium 和 Leaflet。调用 `BaseGIS.setEngine()` 时，已经生成的线会随托管图层自动恢复。
 
-### 1. GeoTIFF 生成等值线
+### GeoTIFF
 
 ```js
 import { RasterContourController } from '@3clear/basegis/methods'
@@ -2598,7 +3299,7 @@ await rasterContour.update({ interval: 2 })
 
 GeoTIFF 依赖宿主页面提供 `window.GeoTIFF`。控制器会读取波段、尺寸、坐标系和范围；当前原生支持 EPSG:4326、EPSG:3857。其他投影可先转换为 WGS84，或传入 WGS84 `area` 覆盖原始范围。
 
-### 2. 灰度图生成等值线
+### 灰度图
 
 ```js
 await rasterContour.loadGrayImage({
@@ -2622,7 +3323,9 @@ await rasterContour.loadGrayImage({
 
 灰度图片本身没有地理范围和业务值含义，因此 `area` 必填；要表达真实数据，还应传正确的灰度范围与业务值范围。已经着色的彩色 PNG 不能反推出原始业务值，应使用对应 TIF 或直接传数值网格。
 
-### 3. 数值网格生成等值线
+上例虽然使用了气压值域，但 `centerDetection` 默认关闭，因此只生成普通等压线和线值标签。需要 H/L 中心时，按下方“自动检测 H/L 中心”配置显式开启。
+
+### 数值网格
 
 ```js
 await rasterContour.loadGrid({
@@ -2644,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 地址。 |
@@ -2681,67 +3384,125 @@ 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`。 |
 
-### 5. 方法和状态
+级别选择优先级为 `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',
+  },
+})
+```
+
+| `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`。 |
 
-<a id="pressure-contour-layer"></a>
-
-## PressureContourLayer
-
-用于等压线、线值标签和高低压中心标注。`buildPressureRenderData()` 可把 Windy 风格的气压数据整理成 `{ isolines, centers }`，`createPressureDataResolver()` 在此基础上提供按数据版本缓存的解析函数。
-
 ```js
-import {
-  PressureContourLayer,
-  buildPressureRenderData,
-  createPressureDataResolver,
-} from '@3clear/basegis/methods'
+// clear 只清空当前渲染结果，控制器仍可继续 update/load。
+rasterContour.clear()
+
+// 页面卸载时彻底释放栅格、图层和监听。
+rasterContour.destroy()
+```
+<a id="contour-center-annotation"></a>
 
-// 单份原始数据可以直接转换。
-const renderData = buildPressureRenderData(pressJson)
+## 中心标注配置（两个控制器通用）
 
-// 多个时次或版本可用解析器按 key 缓存转换结果。
-const resolvePressureData = createPressureDataResolver({
-  default: pressJson,
-  next: pressJson2,
-})
+`ContourLayerController` 通过顶层 `centers` 接收已经计算好的中心点，通过 `centerAnnotation` 控制显示和样式。该能力是通用标注，不把数据限制为气压；H/L 只是气压业务中的一种标签。
 
-const pressureLayer = new PressureContourLayer({
+```js
+const pressureContour = new ContourLayerController({
   mapCore,
-  layerId: 'pressure',
-  color: 'rgba(255,255,255,0.82)',
-  width: 1.15,
-  smoothFactor: 0.2,
-  // Cesium 用它判断标签碰撞和屏幕范围，Leaflet 可复用同一容器 id。
-  mapContainerId: 'map',
-  isAnnotationVisible: () => true,
+  layerId: 'pressure-contour',
+  showLabel: true,
+  labelFormatter: (item) => String(item.value),
+  centerAnnotation: {
+    visible: true,
+    collision: true,
+    color: '#e3f8ff',
+    fontSize: 20,
+    valueColor: '#ffffff',
+    valueFontSize: 12,
+  },
 })
 
-pressureLayer.mount()
-await pressureLayer.load(renderData)
-await pressureLayer.update(resolvePressureData('next'))
-pressureLayer.hide()
-pressureLayer.destroy()
+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 },
+  ],
+})
 ```
 
-说明：
+`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` | 屏幕安全边距。 |
 
-- 等压线数据会被整理为 `isolines` 和 `centers`。
-- Leaflet 使用 `divIcon` 绘制 H/L 中心和线值标签。
-- Cesium 使用独立标注集合，地图变化时会调度刷新。
+状态中的 `centerCount` 是成功解析的有效中心数，`lineLabelCount` 和 `centerLabelCount` 是当前视野实际显示数，`labelCount` 是两者合计。`show/hide/clear/destroy` 以及 `BaseGIS.setEngine()` 会和等值线一起管理这些中心标注。
 
 <a id="wind-field-methods"></a>
 
@@ -2971,7 +3732,7 @@ const result = await setEngine('leaflet')
 console.log(result.data?.restore)
 ```
 
-只有风场、剖面、一次性绘制对象或页面直接创建的底层引擎对象需要在切换成功后自行恢复。
+只有 GPU 专用风场、剖面、一次性绘制对象或页面直接创建的底层引擎对象需要在切换成功后自行恢复。
 
 ## 能力支持说明
 
@@ -2982,9 +3743,11 @@ console.log(result.data?.restore)
 | 放大、缩小、重置 | 支持 | 支持 |
 | 底图切换 | 支持 | 支持 |
 | 点线面文字 | 支持 | 支持 |
+| 独立线、虚线、渐变与沿线动画 | 支持 | 支持 |
 | 图片覆盖层 | 支持 | 支持 |
 | 网格 / TIF | 支持 | 支持 |
 | 海量点 | 支持 | 支持 |
+| 点位聚合 | 支持 | 支持 |
 | 点位密度抽稀 | 支持 | 支持 |
 | 等值线 | 支持 | 支持 |
 | 等压线标注 | 支持 | 支持 |
@@ -3131,7 +3894,7 @@ mapCore.init()
 
 ### 切换引擎后图层没了
 
-直接使用 `setEngine()`。BaseGIS 会保留视野，并自动恢复图片、网格、海量点、点位抽稀、等值线和三维体等托管图层：
+直接使用 `setEngine()`。BaseGIS 会保留视野，并自动恢复图片、网格、海量点、点位聚合、点位抽稀、独立线、等值线、统一风场和三维体等托管图层：
 
 ```js
 const result = await mapCore.setEngine('leaflet')
@@ -3140,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 对象，它们不属于托管图层，需要业务在切换成功后自行恢复。