@3clear/basegis 0.1.0 → 0.1.2

package/README.md

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