@3clear/basegis 0.1.4 → 0.1.5

package/README.md

@@ -1,13 +1,13 @@
 # @3clear/basegis
 
-`@3clear/basegis` 是 3clear 一张图项目抽出的 GIS 能力包。它提供一个统一入口 `BaseGIS`，把 Cesium / Leaflet 的差异收敛到适配层里；业务页面优先只操作 `BaseGIS`，复杂图层能力通过 `methods` 控制器组合 `BaseGIS` 公共方法完成。
-把leaflet cesium 常用方法做了二次封装统一了api 使同一套代码可以适配2套地图引擎
+`@3clear/basegis` 是 3clear 一张图项目抽出的 GIS 能力包，通过统一入口 `BaseGIS` 封装 Cesium / Leaflet 常用 API。业务页面可复用同一套地图逻辑，复杂图层通过 `methods` 控制器组合公共方法；三维专有能力的支持范围见[能力支持说明](#能力支持说明)。
+
 当前包包含：
 
-- `BaseGIS`：地图初始化、引擎切换、视角控制、底图切换、绘制、图层显隐、DEM、点击事件、Cesium / Leaflet 统一粒子风场、GPU 粒子风场、三维体渲染、三维切片/剖面渲染等基础能力。
-- `methods`：独立线图层、图片图层、网格图层、海量点、点位聚合、点位抽稀、等值线、风场、图形组等高级控制器。
+- `BaseGIS`：初始化、引擎切换、视角与底图、[地图截图导出](#map-screenshot)、基础图形、Canvas 图标与扩散 Marker、GeoJSON、DEM、点击事件，以及统一风场、源解析传输、GPU 风场、三维体与剖面。
+- `methods`：多地图实时视角联动、独立线图层、台风路径、图片图层、网格图层、海量点、点位聚合、点位抽稀、等值线、风场等高级控制器。
 - `layers`：天地图、GeoServer 金字塔瓦片、WMS、WMTS 图层配置快捷构造器。
-- `assets`：GIS 示例资源。
+- `assets`：站点、工厂、信息标记和台风中心 SVG 资源。
 - `style.css`：Leaflet、GIS 图层和标注相关基础样式。
 
 ## 能力总览
@@ -27,14 +27,53 @@
   </tbody>
 </table>
 
+### DEM 地形
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#dem-terrain"><strong>DEM 地形</strong></a><br>
+        <small>Cesium 椭球地形、World Terrain 与地形夸张</small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### 地图截图导出
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#map-screenshot"><strong>BaseGIS.screenshot</strong></a><br>
+        <small>当前视口、框选及指定范围截图 · <a href="http://61.50.111.214:31166/lgmap/test-page-40" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### 多地图联动（双屏联动）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#map-view-link-controller"><strong>MapViewLinkController</strong></a><br>
+        <small>多地图实例注册与移动、缩放、视角实时联动 · <a href="http://61.50.111.214:31166/lgmap/test-page-36" 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>
+        <a href="#basic-graphics"><strong>绘制点、线、面、文字和 Marker</strong></a><br>
+        <small>BaseGIS 基础绘图与清理，支持 Cesium / Leaflet · <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>
@@ -54,6 +93,32 @@
   </tbody>
 </table>
 
+### geojson
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#geojson-layer"><strong>BaseGIS.upsertGeoJsonLayer</strong></a><br>
+        <small>GeoJSON 点、线、面与按要素设置样式 · <a href="http://61.50.111.214:31166/lgmap/test-page-23" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### 图标
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#marker-icons"><strong>图标</strong></a><br>
+        <small>提供了一些项目中常用的图标及告警扩散效果图标 · <a href="http://61.50.111.214:31166/lgmap/test-page-41" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
 ### Line 线图层（1）
 
 <table>
@@ -62,7 +127,21 @@
       <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>
+        <small>支持：逐顶点色、时间裁剪和图标引领的逐步出线；走航轨迹见 <a href="http://61.50.111.214:31166/lgmap/test-page-43" target="_blank" rel="noopener noreferrer">走航示例</a></small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Typhoon 台风路径（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#typhoon-path-controller"><strong>TyphoonPathController</strong></a><br>
+        <small>实况路径、强度节点、当前中心、四象限风圈、多机构预报与路径播放 · <a href="http://61.50.111.214:31166/lgmap/test-page-10" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
+        <small>支持：Cesium / Leaflet 同一份规范化台风数据与引擎切换恢复</small>
       </td>
     </tr>
   </tbody>
@@ -103,7 +182,7 @@
     <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>
+        <small>已有等值线、线值标签与中心标注 · <a href="http://61.50.111.214:31166/lgmap/test-page-19" target="_blank" rel="noopener noreferrer">查看示例</a></small>
       </td>
       <td width="50%">
         <a href="#raster-contour-controller"><strong>RasterContourController</strong></a><br>
@@ -113,6 +192,20 @@
   </tbody>
 </table>
 
+### Source 源解析传输（1）
+
+<table>
+  <tbody>
+    <tr>
+      <td>
+        <a href="#source-transport"><strong>BaseGIS.upsertSourceTransportLayer</strong></a><br>
+        <small>Cesium 专有；贡献弧线、灰色烟羽点云、移动烟团与目标汇聚体 · <a href="http://61.50.111.214:31166/lgmap/test-page-42" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
+        <small>页面最少只传 target + flows，体云复用 BaseGIS 现有体渲染</small>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
 ### Volume 三维体渲染（1）
 
 <table>
@@ -121,7 +214,7 @@
       <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>
+        <small>支持：一维体数据 + rows / cols / heights 网格维度、原位更新体数据与屏幕位置取值</small>
       </td>
     </tr>
   </tbody>
@@ -134,21 +227,29 @@
     <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>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）
+### Wind 风场（2）
+
+风场分为 GPU 和 Canvas 两种渲染方式。推荐使用 [BaseGIS.upsertWindLayer](#unified-wind-layer) 统一入口：Cesium 自动使用 GPU，Leaflet 自动使用 Canvas，切换引擎时自动恢复风场。
 
 <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>
+        <a href="#gpu-wind-layer"><strong>GPU 风场</strong></a><br>
+        <small>Cesium 专用，使用 GPU 绘制风场粒子，支持地形采样 · <a href="http://61.50.111.214:31166/lgmap/test-page-21" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <a href="#wind-field-methods"><strong>Canvas 风场</strong></a><br>
+        <small>通过 WindFieldMethods 在 Cesium / Leaflet 上绘制风场粒子，支持风速底图 · <a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small>
       </td>
     </tr>
   </tbody>
@@ -181,15 +282,29 @@
   </tbody>
 </table>
 
-### Assets 示例资源（1）
+### Assets 示例资源（4）
 
 <table>
   <tbody>
     <tr>
-      <td>
+      <td width="50%">
         <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>
+      <td width="50%">
+        <a href="#typhoon-path-controller"><strong>typhoonPathIcon</strong></a><br>
+        <small>台风路径默认中心 SVG · <a href="http://61.50.111.214:31166/lgmap/test-page-10" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      </td>
+    </tr>
+    <tr>
+      <td width="50%">
+        <a href="#gis-marker-sample"><strong>gisFactoryMarker</strong></a><br>
+        <small>工厂标记 SVG，可配合图片与数值图标使用</small>
+      </td>
+      <td width="50%">
+        <a href="#gis-marker-sample"><strong>gisInfoMarker</strong></a><br>
+        <small>信息标记 SVG，可配合图片与名称图标使用</small>
+      </td>
     </tr>
   </tbody>
 </table>
@@ -200,7 +315,7 @@
 npm install @3clear/basegis leaflet axios
 ```
 
-`d3-contour`、`pixi.js` 和 `leaflet-pixi-overlay` 已随 BaseGIS 构建产物发布，业务项目不需要单独安装。其中 Pixi 相关代码只在首次使用 Leaflet 海量点能力时按需加载。
+`d3-contour`、`pixi.js`、`leaflet-pixi-overlay` 和 `html2canvas` 已随 BaseGIS 构建产物发布，业务项目不需要单独安装。其中 Pixi 相关代码只在首次使用 Leaflet 海量点能力时按需加载，`html2canvas` 只在首次调用 Leaflet 截图时按需加载。
 
 使用样式：
 
@@ -208,8 +323,19 @@ npm install @3clear/basegis leaflet axios
 import '@3clear/basegis/style.css'
 ```
 
-Cesium 当前不随 npm 包发布，项目需要按原项目方式把 Cesium 静态资源放到 `public/lib/Cesium`，并保证初始化前能访问 `window.Cesium`。
-如果需要加载 GeoTIFF 网格，需要项目提前提供 `window.GeoTIFF`。
+外部依赖版本以 `package.json` 为准：当前为 `leaflet ^1.9.4`、`axios ^1.15.1`。仅使用 Leaflet 时，不需要加载 Cesium。
+
+Cesium 不随 npm 包发布。使用 Cesium 时，宿主项目需自行加载 `Cesium.js` 和 `Widgets/widgets.css`，并保留 `Workers`、`Assets` 等完整静态目录；初始化前必须能访问 `window.Cesium`。`config.engine.cesium.scriptUrl/cssUrl` 不会自动注入脚本和样式。
+
+例如，将完整 Cesium 资源放入 `public/lib/Cesium` 后，在 Vite 的 `index.html` 中、应用入口脚本之前添加：
+
+```html
+<script>window.CESIUM_BASE_URL = '%BASE_URL%lib/Cesium/'</script>
+<link rel="stylesheet" href="%BASE_URL%lib/Cesium/Widgets/widgets.css">
+<script src="%BASE_URL%lib/Cesium/Cesium.js"></script>
+```
+
+使用 GeoTIFF 数据时，宿主还需提前提供 `window.GeoTIFF`。本文 `/data/...`、`/mock/...` 均为示例数据地址，不包含在 npm 包中，请替换为项目真实地址；部署在子路径时，应结合宿主的 `import.meta.env.BASE_URL` 生成静态资源 URL。
 
 ## 出口
 
@@ -219,8 +345,9 @@ import { BaseGIS } from '@3clear/basegis'
 
 // 高级能力控制器
 import {
-  GraphicGroupController,
   LineLayerController,
+  MapViewLinkController,
+  TyphoonPathController,
   ImageLayerController,
   toImageLayerArea,
   GridLayerController,
@@ -235,13 +362,19 @@ import {
 // 图层配置构造器
 import {
   createTiandituLayer,
+  createTiandituTileSource,
   createGeoserverPyramidLayer,
   createWmsLayer,
   createWmtsLayer,
 } from '@3clear/basegis/layers'
 
 // 示例资源
-import { gisMarkerSample } from '@3clear/basegis/assets'
+import {
+  gisMarkerSample,
+  gisFactoryMarker,
+  gisInfoMarker,
+  typhoonPathIcon,
+} from '@3clear/basegis/assets'
 ```
 
 ## 快速开始
@@ -297,17 +430,19 @@ onBeforeUnmount(() => {
 })
 </script>
 
-<style scoped>
+<style scoped lang="scss">
 .map {
   width: 100%;
-  height: 100%;
+  height: 100vh;
 }
 </style>
 ```
 
+以下 API 示例默认 `mapCore` 已初始化成功；示例中的业务数据、图片和服务地址需由页面准备。组件卸载时先销毁控制器、移除页面监听，再调用 `mapCore.destroy()`。
+
 ## 返回值约定
 
-多数方法返回统一结果对象：
+操作方法通常返回统一结果对象；图片、GeoJSON、风场等异步加载方法应使用 `await`：
 
 ```js
 {
@@ -325,9 +460,12 @@ onBeforeUnmount(() => {
   message: 'error message',
   code: 'NOT_INITIALIZED'
 }
-
 ```
 
+`getEngineType()`、`getConfig()`、`getMapInstance()` 等读取方法直接返回值；`createMarkerIcon()` 直接返回图标参数或 `null`。控制器的 `getState()` 也返回状态对象，不能一律按 `result.data` 读取。
+
+## 配置与底图
+
 说明：
 
 - `containerId` 和 `container` 二选一即可；`init()` 时也可以再次传入。
@@ -357,17 +495,6 @@ basemap: {
 | `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'` 的底图。
@@ -376,7 +503,7 @@ basemap: {
 - `geoserver-wmts-sample` 和 `geoserver-wms-sample` 默认 `enabled: false`，只是配置格式示例；如果要作为默认底图，需要替换真实服务地址并改为 `enabled: true`。
 - 天地图 provider 内置资源还包括 `imageryLabel`；默认 `basemap.list` 没有单独注册影像注记 id，但 `resourceKey: 'imagery'` 会自动推断使用 `imageryLabel` 注记。
 
-###  底图切换
+### 底图切换
 
 底图可以来自 `config.basemap.list`，也可以直接传配置对象。当前适配层支持：
 
@@ -494,9 +621,11 @@ const basemapList = [
     id: 'weather-wmts',
     name: '气象 WMTS',
     category: 'basemap',
-    url: 'https://example.com/wmts',
-    layer: 'weather',
-    tileMatrixSet: 'EPSG:3857',
+    engineSupport: ['cesium'],
+    url: 'https://example.com/geoserver/gwc/service/wmts?' +
+      'SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=workspace:weather&' +
+      'STYLE=default&TILEMATRIXSET=EPSG:3857&FORMAT=image/png&' +
+      'TILEMATRIX=EPSG:3857:{z}&TILEROW={y}&TILECOL={x}',
   }),
 ]
 
@@ -513,6 +642,12 @@ const mapCore = new BaseGIS({
 
 四个构造器都会保留额外传入字段，便于继续配置 `engineSupport`、缩放级别、注记资源或服务参数。
 
+`createWmtsLayer()` 只生成配置，不会根据 `layer / tileMatrixSet` 自动拼接请求。自定义 WMTS 需要完整的 GetTile URL 模板，矩阵标识应按服务实际配置填写；XYZ 瓦片同样使用包含 `{z}/{x}/{y}` 的 URL。
+
+模板瓦片不会自动重投影。上面的 `EPSG:3857` WMTS 示例限定用于 Cesium；当前 Leaflet 使用 `EPSG:4326`，自定义瓦片需匹配地图的坐标系和瓦片矩阵。
+
+`layers` 还导出辅助函数 `createTiandituTileSource(resourceKey = 'imagery')`，返回 `{ url, subdomains }`，资源不可用时返回 `null`。它供需要直接操作引擎的特殊页面使用，普通页面仍优先调用 `createTiandituLayer()` 和 `BaseGIS`。
+
 <a id="base-gis"></a>
 
 ## BaseGIS 基础能力
@@ -579,6 +714,8 @@ const mapCore = new BaseGIS({
 | `getEngineType()` | 无 | 返回当前引擎类型。 |
 | `getConfig()` | 无 | 返回当前运行时配置。 |
 | `getMapInstance()` | 无 | 返回底层地图实例：Cesium `viewer` 或 Leaflet `map`。 |
+| `getMapContainer()` | 无 | 返回统一结果，`data.container` 为地图容器 DOM。 |
+| `resize()` | 无 | 在容器尺寸改变、隐藏面板重新显示后刷新地图尺寸。 |
 
 #### 推荐的引擎切换写法
 
@@ -614,25 +751,28 @@ if (result.success) {
 
 `switchEngine()` 作为兼容别名保留，行为与 `setEngine()` 一致。
 
+<a id="managed-layer-restore"></a>
+
 #### 切换后的图层处理
 
 引擎切换不是把 Cesium 图层对象“搬到” Leaflet，也不是把 Leaflet 图层对象“搬到” Cesium。BaseGIS 会保存托管图层的业务参数，并在新 adapter 中重新创建图层。
 
-- 自动恢复范围包括图片、网格、海量点、点位聚合、点位抽稀、独立线、等值线、统一风场和三维体图层，对应 `upsert*Layer` 方法及 Controller。
+- 自动恢复范围包括图片、网格、海量点、点位聚合、点位抽稀、独立线、源解析传输、台风路径、等值线、统一风场和三维体图层。
 - 图层最新的数据参数、显隐、清空、删除、海量点删除和高亮状态会同步到 BaseGIS 快照。
 - 快照只保存业务参数引用，不复制大数组，不保存任何底层引擎对象。
-- 三维体图层切到 Leaflet 时会返回不支持结果，但快照仍保留，切回 Cesium 后会继续恢复。
+- 三维体、源解析传输切到 Leaflet 时会返回不支持结果，但快照仍保留，切回 Cesium 后会继续恢复。
 - Cesium 专有能力在 Leaflet 下不可用，例如 DEM、三维体渲染、三维切片/剖面渲染。
-- 一次性绘制对象、点击监听、风场、剖面图层和页面直接操作底层引擎创建的对象不在托管范围内，需要业务自行恢复。
+- 基础绘制对象、GeoJSON、点击/视图监听、GPU 专用风场、独立 `WindFieldMethods`、剖面图层和页面直接创建的底层引擎对象不在托管范围内，需要业务重新加载或绑定。
 
 切换结果中可以查看恢复明细：
 
 ```js
 const result = await mapCore.setEngine('leaflet')
-console.log(result.data.restore.restored)
-console.log(result.data.restore.failed)
+console.log(result.data?.restore?.restored)
+console.log(result.data?.restore?.failed)
 ```
 
+`result.success` 表示引擎初始化/切换是否成功，不保证每个图层都恢复成功；应同时检查 `data.restore.failed`。不要在切换前先调用 `destroy()`，它会清空托管快照。
 
 ### 2. 视角控制与场景模式
 
@@ -688,6 +828,13 @@ const viewStateResult = mapCore.getViewState()
 // Cesium 通常包含 center / bounds / height / heading / pitch / roll / engineType。
 // Leaflet 通常包含 center / bounds / zoom / engineType。
 
+// 让地图适配指定经纬度范围，可用于多地图首次统一范围。
+mapCore.fitViewBounds({
+  bounds: { west: 73, south: 18, east: 135, north: 54 },
+  animate: false,
+  padding: 0,
+})
+
 // 经纬度转地图容器像素坐标，常用于自定义 HTML 浮层定位。
 const pointResult = mapCore.projectToContainerPoint({
   longitude: 104,
@@ -708,6 +855,10 @@ const viewListener = mapCore.onViewChange({
   // 缩放过程中要实时刷新点位样式时，优先用 onChange。
   onChange() {},
 
+  // Cesium 交互期间逐渲染帧检测相机变化；适合多地图实时联动。
+  // 默认 false，普通业务监听无需开启。
+  continuous: true,
+
   // Cesium: camera.moveEnd / morphComplete；Leaflet: moveend / zoomend / resize。
   onEnd() {},
 
@@ -730,13 +881,98 @@ viewListener.data?.off?.()
 | `setSceneMode(payload)` | `'2d'/'2.5d'/'3d'` 或 `{ mode, duration, preserveView }` | 切换场景模式。 |
 | `getSceneMode()` | 无 | 获取当前场景模式。 |
 | `getViewBounds()` | 无 | 获取当前视图经纬度边界。 |
-| `getViewState()` | 无 | 获取当前视图状态。 |
-| `onViewChange(payload)` | `{ onStart, onChange, onEnd, endDelay }` | 监听视图变化，返回 `{ off }`。 |
+| `getViewState(payload)` | 可选 `{includeBounds:false}` | 获取当前视图状态；实时同引擎联动可关闭较重的范围采样。 |
+| `fitViewBounds(payload)` | `{bounds:{west,south,east,north},animate?,padding?,duration?}` | 适配指定经纬度范围；`duration` 仅用于 Cesium 动画。 |
+| `onViewChange(payload)` | `{ onStart, onChange, onEnd, endDelay, continuous? }` | 监听视图变化，返回 `{ off }`；Cesium 开启 `continuous` 后交互期间逐帧检测。 |
 | `projectToContainerPoint(payload)` | `{ longitude, latitude, height }` | 经纬度投影到地图容器像素坐标。 |
 
+<a id="map-screenshot"></a>
+
+### 3. 地图截图与导出
+
+`screenshot()` 用于导出当前 Cesium 或 Leaflet 地图，两个引擎使用完全相同的调用方式、参数和结果对象。默认截取当前可视范围（地图视口）并下载 PNG，不会自动拼接视口外尚未渲染的地图内容；只截取地图内容，不包含页面工具栏、弹窗等地图容器外的 DOM 浮层。
+
+框选遮罩样式包含在 `@3clear/basegis/style.css` 中，使用 npm 包时应按安装章节导入该样式文件。
+
+在线示例：[地图截图与 PNG 导出](http://61.50.111.214:31166/lgmap/test-page-40)。
+
+#### 直接下载 PNG
+
+默认 `download: true`，页面不需要自己创建下载链接或处理 Blob。`fileName` 可指定文件名；不传时使用前缀和时间戳自动命名。
+
+```js
+// 截取当前可视范围并直接下载。
+const result = await mapCore.screenshot({ fileName: 'weather-map.png' })
+if (!result.success) {
+  console.warn('截图导出失败', result.code, result.message)
+}
+
+// 左键拖拽框选区域，松开后下载；右键或 Esc 取消。
+const selectResult = await mapCore.screenshot({
+  mode: 'select',
+  namePrefix: 'map-select',
+})
+if (!selectResult.success && selectResult.code !== 'CANCELLED') {
+  console.warn('框选导出失败', selectResult.message)
+}
+```
+
+#### 按范围裁剪导出
+
+```js
+// 按当前视野中的经纬度范围裁剪。
+await mapCore.screenshot({
+  namePrefix: 'east-china',
+  bounds: { west: 115, south: 25, east: 123, north: 36 },
+})
+
+// 按相对当前地图视口左上角的 CSS 像素区域裁剪。
+await mapCore.screenshot({
+  rect: { left: 120, top: 80, width: 640, height: 360 },
+})
+```
+
+#### 获取 Blob，不自动下载
+
+```js
+const captureResult = await mapCore.screenshot({
+  download: false,
+  fileName: 'weather-map.png',
+})
+if (captureResult.success) {
+  const { blob, fileName, width, height } = captureResult.data
+  // 页面可将 blob 交给自己的预览或上传逻辑，BaseGIS 不会自动上传。
+  console.log(blob, fileName, width, height)
+}
+```
+
+#### 方法与参数
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `screenshot(payload)` | `{ mode?, download?, fileName?, namePrefix?, bounds?, area?, rect?, screenRect? }` | 截取 Cesium / Leaflet 地图；`mode: 'select'` 进入交互框选，`download` 默认为 `true`。 |
+| `cancelScreenshotSelection(reason?)` | 可选取消原因字符串 | 主动取消正在进行的框选；返回布尔值，表示是否取消了现有框选。 |
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `mode` | 省略 | 默认直接截图；`'select'` 进入鼠标框选，也可简写为 `screenshot('select')`。 |
+| `download` | `true` | 自动触发浏览器下载；传 `false` 只生成截图结果。 |
+| `fileName` | 自动生成 | 优先于 `namePrefix`；未以 `.png` 结尾时自动追加扩展名。当前仅导出 PNG。 |
+| `namePrefix` | `map-screenshot` | 自动文件名前缀；未指定名称的框选截图默认使用 `map-select`。 |
+| `bounds` / `area` | 当前视口 | 经纬度范围别名，支持 `{ west, south, east, north }` 或 `{ startLon, startLat, endLon, endLat }`。 |
+| `rect` / `screenRect` | 当前视口 | 屏幕区域别名，支持 `{ left, top, width, height }`，也可用 `x / y` 代替 `left / top`；单位为相对地图视口左上角的 CSS 像素。 |
+
+取消框选时，原 `screenshot()` Promise 返回 `success: false`、`code: 'CANCELLED'` 和 `data.cancelled: true`；页面通常无需按错误弹窗处理。
+
+成功结果的 `data` 包含 `blob`、`width`、`height`、`mimeType`、`fileName`、`downloaded`、`screenRect` 和 `pixelRect`。Cesium 读取 WebGL 场景画布；Leaflet 在首次调用时按需加载 DOM 渲染器，合成瓦片、SVG、Canvas 和 DOM Marker，并排除 Leaflet 自带控件。跨域地图资源需要服务端允许 CORS，否则对应资源可能缺失或截图返回 `FAILED`。为保证 WebGL 截图可靠，Cesium 初始化时会保留 drawing buffer；在超高分辨率大屏上会增加一定显存占用。
+
+`width / height / pixelRect` 使用导出图片的实际像素，可能与 CSS 像素不同；`downloaded: true` 仅表示已触发下载，不代表浏览器已确认文件保存到磁盘。导出范围始终限制在当前视口内，不是整页长截图，也不支持自动加载并拼接屏幕外瓦片。
+
+<a id="basic-graphics"></a>
+
 ### 4. 绘制点、线、面、文字和 Marker
 
-这些方法用于轻量绘制和样例验证。大量点位或复杂业务图层请优先使用后文的 `PointLargeLayerController`、`PointClusterController`、`PointDensityController`、`GraphicGroupController` 等控制器。
+这些方法用于轻量绘制和样例验证。大量点位请优先使用后文的 `PointLargeLayerController`、`PointClusterController`、`PointDensityController` 等控制器。
 
 点：
 
@@ -827,11 +1063,188 @@ mapCore.addMarker({
 })
 ```
 
+<a id="marker-icons"></a>
+
+#### Canvas 数据图标与扩散效果
+
+`mapCore.createMarkerIcon(options, data)` 支持圆点、“数值 + 名称”、气象风向、“图片 + 名称”和“图片 + 数值 + 名称”五种 Canvas 样式。圆点用法：
+
+```js
+const station = {
+  id: 'station-1',
+  name: '示例站点',
+  position: [104, 35],
+  value: 28.6,
+  status: 'normal',
+  windDirection: 90,
+  windSpeed: 6,
+}
+
+const markerIcon = mapCore.createMarkerIcon({
+  type: 'dot',
+  size: 18,
+  color: '#64748b',
+  getColor(data) {
+    if (data.status === 'normal') return '#00e600'
+    if (data.status === 'warning') return '#a67824'
+    return '#6b7280'
+  },
+}, station)
+
+mapCore.addMarker({
+  id: station.id,
+  name: station.name,
+  position: station.position,
+  data: station,
+  ...markerIcon,
+})
+```
+
+“数值 + 名称”用法：
+
+```js
+const markerIcon = mapCore.createMarkerIcon({
+  type: 'value-label',
+  value: station.value,
+  label: station.name,
+  showLabel: station.showName !== false,
+  color: '#64748b',
+  getColor(data) {
+    if (data.status === 'normal') return '#00e600'
+    if (data.status === 'warning') return '#a67824'
+    return '#6b7280'
+  },
+}, station)
+
+mapCore.addMarker({
+  id: station.id,
+  name: station.name,
+  position: station.position,
+  data: station,
+  ...markerIcon,
+})
+```
+
+气象风向用法：
+
+```js
+const markerIcon = mapCore.createMarkerIcon({
+  type: 'wind',
+  direction: station.windDirection,
+  label: station.name,
+  showLabel: station.showName !== false,
+  color: '#64748b',
+  getColor(data) {
+    if (data.windSpeed >= 17.2) return '#e5484d'
+    if (data.windSpeed >= 10.8) return '#f59e0b'
+    if (data.windSpeed >= 5.5) return '#2f80ed'
+    return '#00e600'
+  },
+}, station)
+
+mapCore.addMarker({
+  id: station.id,
+  position: station.position,
+  data: station,
+  ...markerIcon,
+})
+```
+
+“图片 + 名称”用法：
+
+```js
+import { gisInfoMarker } from '@3clear/basegis/assets'
+
+const stationImage = new Image()
+// 跨域图片需由服务端允许 CORS，并在设置 src 前配置 crossOrigin。
+stationImage.src = gisInfoMarker
+await stationImage.decode()
+
+const markerIcon = mapCore.createMarkerIcon({
+  type: 'image-label',
+  image: stationImage,
+  imageSize: [20, 20],
+  label: station.name,
+  showLabel: station.showName !== false,
+}, station)
+
+mapCore.addMarker({
+  id: station.id,
+  position: station.position,
+  data: station,
+  ...markerIcon,
+})
+```
+
+“图片 + 数值 + 名称”用法：
+
+```js
+import { gisFactoryMarker } from '@3clear/basegis/assets'
+
+const company = { id: 'factory-1', name: '示例企业', emissionValue: 12.5 }
+const factoryImage = new Image()
+factoryImage.src = gisFactoryMarker
+await factoryImage.decode()
+
+const markerIcon = mapCore.createMarkerIcon({
+  type: 'image-value-label',
+  image: factoryImage,
+  imageSize: [14, 14],
+  value: company.emissionValue,
+  label: company.name,
+  showValue: company.showValue !== false,
+  showLabel: company.showName !== false,
+}, company)
+
+mapCore.addMarker({
+  id: company.id,
+  position: [104.2, 35.1],
+  data: company,
+  ...markerIcon,
+})
+```
+
+`getColor(data)` 同步接收 `createMarkerIcon` 第二个参数传入的原始数据并返回 CSS 颜色。回调异常、返回非法颜色或空值时使用 `options.color`，再无有效静态颜色时使用默认灰色。圆点 `size` 默认 18px，允许 4～96px，并使用中心锚点。`value-label` 的 `value` 位于上方彩色色块，`label` 位于下方白色名称块；`showLabel: false` 时只显示数值块，图标宽高和锚点会自动更新。`wind` 的 `direction` 使用角度，`0` 指向正上方（北）、`90` 指向右侧（东），按顺时针方向增加；`label` 位于下方白色名称块，`showLabel: false` 时可隐藏，风速颜色分级完全由业务回调决定。`image-label` 的 `image` 接收已加载的 CanvasImageSource，`imageSize` 控制图片尺寸；URL 图片应先加载一次再传入，以保持抽稀回调同步。`image-value-label` 在同一规则上增加右侧 `value` 和蓝色圆角色块；`showValue: false` 时不绘制数值底板，只保留图片本身，`showLabel: false` 可独立隐藏名称。两者都隐藏时得到纯图片图标，画布尺寸和锚点会按照 `imageSize` 自动收缩。该类型使用整数锚点减少低 DPR 下的文字模糊。返回的 `iconUrl/iconSize/iconAnchor` 可用于普通 Marker、点位抽稀及其他图片点位能力。
+
+Cesium / Leaflet 双引擎扩散 Marker：
+
+```js
+mapCore.addMarker({
+  id: 'alarm-station',
+  name: '告警站点',
+  position: [121.48, 31.23],
+  data: station,
+  iconUrl: '/marker.png',
+  iconSize: [34, 40],
+  pulse: {
+    color: '#22d3ee',
+    size: 88,
+    duration: 2,
+    ringCount: 2,
+    ringWidth: 2,
+    ringOpacity: 0.72,
+  },
+  clampToGround: true,
+  onClick({ data }) {
+    console.log(data)
+  },
+})
+```
+
+`pulse` 只是图标下方的效果层，不会生成中心点。`pulse.size` 是最大扩散直径（像素），`ringWidth` 是独立的屏幕像素线宽，`ringOpacity` 是圆环不透明度；`duration` 是单个圆环的周期（秒），`ringCount` 支持 1～3。页面不需要判断当前引擎；Leaflet 使用 SVG 动画，Cesium 使用 Billboard 缩放动画，两端保持相同的半径、线宽、透明度和相位变化曲线。只传 `pulse` 时仅显示扩散环；与 `iconUrl` 同时传入时，图标显示在扩散环上层。
+
 <a id="gis-marker-sample"></a>
 
-#### 使用 gisMarkerSample 示例资源
+#### 使用 SVG 资源
 
-`gisMarkerSample` 是可直接导入的 Marker 图片资源，适合快速验证 `addMarker()` 或控制器图标配置。
+`assets` 导出的资源均为可直接用于 `iconUrl` 的 SVG URL；传给 Canvas 图标的 `image` 时则需要先加载为图片对象。
+
+| 导出 | 用途 |
+| --- | --- |
+| `gisMarkerSample` | 基础 Marker 示例。 |
+| `gisFactoryMarker` | 工厂标记，适合企业排放数据。 |
+| `gisInfoMarker` | 信息标记，适合站点名称与数值。 |
+| `typhoonPathIcon` | 台风路径默认中心图标。 |
 
 ```js
 import { gisMarkerSample } from '@3clear/basegis/assets'
@@ -862,13 +1275,105 @@ mapCore.clearGraphics()
 | `drawLine(payload)` | 线配置 | 绘制线。 |
 | `drawPolygon(payload)` | 面配置 | 绘制面。 |
 | `drawText(payload)` | 文字配置 | 绘制文字。 |
-| `addMarker(payload)` | Marker 配置 | 绘制图片 Marker；未传 `iconUrl` 时降级为点。 |
+| `createMarkerIcon(options, data)` | 图标配置、原始数据 | 直接返回 `iconUrl/iconSize/iconAnchor`；未知 `type` 返回 `null`。 |
+| `addMarker(payload)` | Marker 配置 | 绘制图片或 `pulse` 扩散 Marker；未传图片或扩散参数时，Cesium 使用点、Leaflet 使用默认 Marker。 |
 | `removeGraphic(payload)` | 图形 id 或 `{ id }` | 删除指定图形。 |
 | `clearGraphics()` | 无 | 清空通过基础绘制方法创建的图形。 |
 
 
 
-### 6. 点击事件
+<a id="geojson-layer"></a>
+
+### 5. GeoJSON 图层
+
+`upsertGeoJsonLayer()` 用同一个 `layerId` 创建或替换 GeoJSON 点、线、面图层，两个引擎共用数据与样式参数。坐标按 GeoJSON 顺序传入 `[经度, 纬度, 可选高度]`。
+
+```js
+const result = await mapCore.upsertGeoJsonLayer({
+  layerId: 'region-boundaries',
+  data: {
+    type: 'FeatureCollection',
+    features: [{
+      type: 'Feature',
+      id: 'region-1',
+      properties: { name: '示例区域', level: 'warning' },
+      geometry: {
+        type: 'Polygon',
+        coordinates: [[[103, 34], [105, 34], [105, 36], [103, 36], [103, 34]]],
+      },
+    }],
+  },
+  style: { color: '#2f80ff', weight: 2, fillOpacity: 0.2 },
+  styleCallback(feature) {
+    return feature?.properties?.level === 'warning'
+      ? { color: '#ff4d4f', fillColor: '#ff4d4f' }
+      : {}
+  },
+  onClick({ feature, properties }) {
+    console.log(properties.name, feature)
+  },
+})
+
+if (result.success && result.data.bounds) {
+  mapCore.fitViewBounds({ bounds: result.data.bounds, animate: false })
+}
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| `layerId` | 必填，图层唯一 id。 |
+| `data` | 必填；支持 FeatureCollection、Feature、Geometry、Feature 数组、JSON 字符串或 URL。也兼容 `geojson / geoJson / source / url`。 |
+| `fetchOptions` | 使用 URL 时传给 Fetch 的请求参数。业务接口通常由宿主 `api/modules` 获取后再传入 `data`。 |
+| `style` | 统一样式：`color / weight / opacity / fillColor / fillOpacity / stroke / fill`；Leaflet 圆点大小用 `radius`，Cesium 标记大小用 `markerSize`。 |
+| `styleCallback(feature, index)` | 按要素返回样式覆盖；异常时使用基础样式。 |
+| `onClick(event)` | 返回 `layerId / feature / properties / data / event / target / engineType`；`data` 为原始 Feature。 |
+| `visible` | 默认 `true`。 |
+| `clampToGround` | Cesium 是否贴地，默认 `true`。 |
+
+```js
+mapCore.hideGeoJsonLayer({ layerId: 'region-boundaries' })
+mapCore.showGeoJsonLayer({ layerId: 'region-boundaries' })
+const stateResult = mapCore.getGeoJsonLayerState({ layerId: 'region-boundaries' })
+console.log(stateResult.data) // layerId / layerType / visible / featureCount / bounds
+
+mapCore.clearGeoJsonLayer({ layerId: 'region-boundaries' }) // 清空要素，保留图层。
+mapCore.removeGeoJsonLayer({ layerId: 'region-boundaries' }) // 删除图层。
+```
+
+上述管理方法也可直接传 id 字符串；方法名兼容大写 `GeoJSON`，例如 `upsertGeoJSONLayer()`。更新时需重新提供完整数据和样式。GeoJSON 当前不在自动恢复清单中，切换引擎后需重新调用 `upsertGeoJsonLayer()`。
+
+<a id="dem-terrain"></a>
+
+### 6. DEM 地形
+
+仅 Cesium 支持。默认使用 `ellipsoid-flat` 椭球地形；`tianditu-terrain` 是底图瓦片，不会提供高程。当前 DEM 接口支持椭球和 Cesium World Terrain，配置中的 `tianditu-dem` 仍是占位项，不能作为已实现地形源使用。
+
+```js
+// 使用 World Terrain 前，宿主需准备 Cesium Ion 等所需凭据与网络访问。
+const result = mapCore.loadDEMById('cesium-world-terrain')
+if (!result.success) {
+  console.warn(result.message)
+} else if (result.data.loading) {
+  // 某些 Cesium 版本异步加载地形；调用返回成功不等于地形已经就绪。
+  const provider = await result.data.readyPromise
+  if (!provider) console.warn('World Terrain 加载失败')
+}
+
+mapCore.setTerrainExaggeration({ factor: 2 })
+console.log(mapCore.getDEMState().data)
+```
+
+| 方法 | 说明 |
+| --- | --- |
+| `loadDEMById(id)` | 从 `config.dem.list` 查找地形配置，常用 `ellipsoid-flat / cesium-world-terrain`。 |
+| `loadDEM(payload)` | 直接传配置；支持 `{ id, sourceType: 'ellipsoid-flat' }` 或 `{ id, sourceType: 'cesium-official', factory: 'worldTerrain' }`。 |
+| `loadDefaultDEM()` | 按当前 `config.dem` 加载默认地形。 |
+| `getDEMState()` | `data` 返回 `{ id, enabled, exaggeration }`；`enabled` 按 `id !== 'ellipsoid-flat'` 判断，不代表异步地形已就绪。 |
+| `setTerrainExaggeration(payload)` | 传数字或 `{ factor }`，范围 `1～10`。 |
+
+恢复平面地形可调用 `mapCore.loadDEMById('ellipsoid-flat')`。Leaflet 不提供 DEM；调用失败时应检查 `success / code / message`，不要直接假定结果包含地形状态。
+
+### 7. 点击事件
 
 `onClick` 注册地图点击事件；`offClick` 移除当前点击监听。当前每个 adapter 只保留一个基础点击监听，重复调用 `onClick` 会先移除旧监听。
 
@@ -935,50 +1440,149 @@ Leaflet 当前返回坐标点击：
 - 海量点、点位聚合、点位抽稀等图层自己的点击事件，应使用对应 Controller 的点击回调参数。
 
 
-<a id="graphic-group-controller"></a>
+<a id="map-view-link-controller"></a>
+
+## 多地图联动（双屏联动）
 
-## GraphicGroupController
+`MapViewLinkController` 注册多个已经初始化的 BaseGIS，并实时同步拖动、缩放和视角。每个地图仍可独立加载不同模式、时次和图层；控制器只负责视角，不创建地图，也不会在 `unregisterMap()`、`clear()` 或 `destroy()` 时销毁 BaseGIS。
 
-用于一次性加载一组点、线、面、文字、marker。它只调用 `BaseGIS.drawPoint / drawLine / drawPolygon / drawText / addMarker`。
+在线示例：[查看分屏布局中的页面地图联动](http://61.50.111.214:31166/lgmap/test-page-36)。布局可混合地图、图表和表格，地图实例与联动由页面管理。
 
 ```js
-import { GraphicGroupController } from '@3clear/basegis/methods'
+import { BaseGIS } from '@3clear/basegis'
+import { MapViewLinkController } from '@3clear/basegis/methods'
 
-const graphics = new GraphicGroupController({ mapCore })
+const mapA = new BaseGIS({
+  engineType: 'leaflet',
+  containerId: 'map-a',
+})
+const mapB = new BaseGIS({
+  engineType: 'leaflet',
+  containerId: 'map-b',
+})
+mapA.init()
+mapB.init()
+
+const viewLinks = new MapViewLinkController({
+  enabled: true,
+  realtime: true,
+  mode: 'all',       // all | leader | group
+  strategy: 'auto',  // auto | view | bounds
+  leaderId: 'map-a',
+  syncInterval: 32, // 实时同步间隔，约 30fps
+})
 
-graphics.load([
-  {
-    type: 'point',
-    id: 'p1',
-    longitude: 104,
-    latitude: 35,
-  },
-  {
-    type: 'line',
-    id: 'l1',
-    positions: [
-      [103, 34],
-      [105, 36],
-    ],
-  },
-  {
-    type: 'text',
-    id: 't1',
-    longitude: 104,
-    latitude: 35,
-    text: '站点',
-  },
-])
+viewLinks.registerMap('map-a', mapA, { group: 'forecast' })
+viewLinks.registerMap('map-b', mapB, { group: 'forecast' })
+
+// 获取 BaseGIS、底层地图实例和全部 id -> BaseGIS 映射。
+const registeredMapA = viewLinks.getMap('map-a')
+const leafletMapA = viewLinks.getNativeMap('map-a')
+const allMaps = viewLinks.getMaps()
 
-graphics.clear()
-graphics.getState()
+// 以 map-a 为操作源放大，并实时同步其他地图。
+viewLinks.zoomIn({ mapId: 'map-a', step: 1 })
+
+// 程序化控制全部注册地图。
+viewLinks.setView({ center: [104, 34], zoom: 5, height: 5000000 })
+viewLinks.fitBounds({ bounds: { west: 73, south: 18, east: 135, north: 54 } })
+
+// 页面卸载：控制器先解绑，地图仍由页面自己销毁。
+viewLinks.destroy()
+mapA.destroy()
+mapB.destroy()
 ```
 
+构造参数：
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `enabled` | `Boolean` | `true` | 是否开启联动。 |
+| `realtime` | `Boolean` | `true` | `true` 按动画帧同步移动/缩放；`false` 只在操作结束时同步。 |
+| `mode` | `String` | `'all'` | `all` 任意图控制；`leader` 仅主图；`group` 仅同组地图。 |
+| `strategy` | `String` | `'auto'` | `auto` 自动选择；`view` 优先中心和层级/高度；`bounds` 使用视图范围。 |
+| `leaderId` | `String` | `''` | 主图 id；空值会使用首个注册地图。 |
+| `syncInterval` | `Number` | `32` | 实时同步的最小间隔，单位 ms；默认约 30fps，降低多 Cesium 实例同时渲染的压力。 |
+| `suppressionMs` | `Number` | `220` | 被同步地图的事件抑制时长，避免反向循环。 |
+| `endDelay` | `Number` | `80` | Cesium 操作结束事件延迟，单位 ms。 |
+| `onStateChange` | `Function` | `null` | 注册、模式、主图和操作结束后的回调，参数为 `{ reason, state }`。 |
+
+联动与实例方法：
+
+| 方法 | 参数 | 返回 / 说明 |
+| --- | --- | --- |
+| `registerMap(id,mapCore,options)` | `options:{group?,enabled?,replace?}` | 注册已初始化的 BaseGIS 并绑定实时视图监听。 |
+| `unregisterMap(id)` | 地图 id | 解除监听和注册，不销毁 BaseGIS。 |
+| `refreshMap(id)` | 地图 id | `BaseGIS.setEngine()` 后重新绑定新 adapter 的监听。 |
+| `getMap(id)` | 地图 id | 返回 BaseGIS 或 `null`。 |
+| `getNativeMap(id)` | 地图 id | 返回 Cesium Viewer / Leaflet Map 或 `null`。 |
+| `getMaps()` | 无 | 返回新的 `Map<id, BaseGIS>`，修改它不会改变控制器注册表。 |
+| `getMapIds()` / `hasMap(id)` | 可选 id | 查询注册状态。 |
+| `forEachMap(callback)` | `(mapCore,id,entry)` | 遍历已注册 BaseGIS。 |
+| `getLeaderMap()` / `getActiveMap()` | 无 | 获取主图或最近操作地图。 |
+| `setLeader(id)` | 地图 id | 设置主图。 |
+| `setMode(mode)` | `all/leader/group` | 更新联动模式。 |
+| `setStrategy(strategy)` | `auto/view/bounds` | 更新视角映射策略。 |
+| `setMapGroup(id,group)` | 地图 id、组名 | 更新地图所在联动组。 |
+| `setMapEnabled(id,enabled)` | 地图 id、布尔值 | 单独启停某张地图的联动。 |
+| `setEnabled(enabled)` / `pause()` / `resume()` | 可选布尔值 | 整体启停联动。 |
+| `setRealtime(realtime)` | 布尔值 | 切换实时或操作结束后同步。 |
+| `syncFrom(id,options)` | 地图 id、`force/strategy` 等 | 立即把指定地图视角同步给目标地图。 |
+
+统一视角操作：
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `zoomIn(payload)` | `{mapId?,step?,distance?}` | 按显式 `mapId`、最近活动地图、主图的顺序选取操作源，再按联动规则同步。 |
+| `zoomOut(payload)` | 同上 | 缩小并同步。 |
+| `setView(payload)` | `center,zoom,height,heading,pitch,roll` | 设置全部注册地图视角。 |
+| `fitBounds(payload)` | `{bounds,animate?,padding?,duration?}` | 让全部地图适配相同范围。 |
+| `resetView(payload)` | 可选视角 | 重置全部地图。 |
+| `resizeAll(payload)` | 可选参数 | 刷新全部地图容器尺寸。 |
+| `getState()` | 无 | 返回模式、主图、注册地图、最近同步来源等状态。 |
+| `clear()` / `destroy()` | 无 | 解绑全部监听并释放引用，不销毁 BaseGIS。 |
+
+`setView / fitBounds / resetView / resizeAll` 始终作用于所有注册地图，不受联动分组或暂停状态限制。
+
+同为 Leaflet 时会同步 `center + zoom`；同为 Cesium 时会直接同步相机经纬度、`height + heading/pitch/roll`；两种视图模型无法直接对应时，`auto` 才会计算并使用 `bounds`。Cesium 交互期间会逐帧检测相机变化，再按 `syncInterval` 合并为最新状态写入目标地图，避免目标地图追赶稀疏跳点，也避免四五个 Cesium 实例每帧重复计算完整视域。一次拖动期间会锁定唯一交互源，目标地图的程序化相机事件不会反向接管并形成反馈循环。
+
+> BaseGIS 切换引擎会重建 adapter，原视图监听随旧 adapter 销毁。切换完成后调用 `viewLinks.refreshMap(id)`；控制器不会劫持或改写 `BaseGIS.setEngine()`。
+
+
 <a id="line-layer-controller"></a>
 
 ## LineLayerController
 
-独立管理一组折线，支持整体更新、显隐、清空、销毁和引擎切换恢复。每条线必须提供唯一 `id` 和至少两个 `[longitude, latitude, height?]` 坐标点。第一版可以加载多条线，但同一控制器只播放一条线的动画。
+独立管理一组折线，支持整体更新、显隐、清空、销毁和引擎切换恢复。每条线必须提供唯一 `id` 和至少两个 `[longitude, latitude, height?]` 坐标点；同一控制器同一时刻只播放一条线的逐步出线动画。
+
+### 逐顶点色专题线与时间裁剪
+
+`lines[].colors` 是六位 HEX 数组，长度必须与 `positions` 完全一致，颜色沿每两个相邻顶点连续插值，优先于 `style.color`：
+
+```js
+import { LineLayerController } from '@3clear/basegis/methods'
+
+const lineLayer = new LineLayerController({ mapCore, layerId: 'sampling-tracks' })
+const startTime = Date.parse('2026-08-28T08:00:00+08:00')
+await lineLayer.load({
+  lines: [{
+    id: 'sampling-track',
+    positions: [[113.30, 22.60], [113.31, 22.61]],
+    colors: ['#00FF00', '#FF3B30'],
+    times: [startTime, startTime + 60000],
+  }],
+  style: { width: 5, opacity: 1, clampToGround: false },
+  animation: { enabled: false },
+  currentTime: startTime,
+})
+
+lineLayer.setTime(startTime + 30000) // 显示前 30 秒已走过的路线。
+lineLayer.setTime(null) // 恢复完整路线。
+```
+
+需要行驶回放时，为各条线附加 `times: [起点毫秒时间戳, 终点毫秒时间戳, ...]`，长度与坐标相同且严格递增。`load` 可设置 `currentTime`，加载后调用 `lineLayer.setTime(time)` 裁掉未来部分；`setTime(null)` 恢复完整路线。不带 `times` 的线不参与裁剪。成功返回 `{ success: true, data: { layerId, currentTime } }`，非法时间返回友好失败结果。
+
+Cesium 使用一个批量 Primitive 做顶点色插值，时间用相对秒数存入顶点，回放每帧仅改材质参数。Leaflet 使用共享 Canvas 重绘已走过的线段，不重新投影或创建图层。这是实线专题叠加，不能与虚线、流动、单线 reveal 或贴地混用；Cesium 关闭深度测试，带时间的采样按直线连接，不用于地形遮挡/贴合，位置必须不同。数据/配色更新仍为全量替换，显隐和引擎切换保留时间。浓度映射、分车/断线、时钟和小车属于业务层；参考项目 `/test-page-43`。
 
 ### 实线、虚线与纯色
 
@@ -1082,39 +1686,192 @@ flightLine.playAnimation()
 flightLine.restartAnimation()
 ```
 
-动画按照各段实际地理距离插值。`hide()` 暂停帧更新并记录播放状态，`show()` 恢复隐藏前正在运行的动画；`clear()` 和 `destroy()` 会取消动画。切换引擎会恢复播放/暂停意图，但不会保存逐帧进度，动画从起点重新计算。
+动画按照各段实际地理距离插值。`hide()` 暂停帧更新并记录播放状态，`show()` 恢复隐藏前正在运行的动画；`clear()` 和 `destroy()` 会取消动画。切换引擎会恢复播放/暂停意图，但不会保存逐帧进度，动画从起点重新计算。
+
+### 参数
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `layerId` | `line-default` | 独立线图层 id。 |
+| `lines` | `[]` | 折线数组，每项包含唯一 `id` 和至少两个 `positions` 坐标。 |
+| `lines[].colors` | - | 与坐标等长的六位 HEX 数组，优先于 `style.color`；用于实线专题叠加。 |
+| `lines[].times` | - | 与坐标等长、严格递增的有限毫秒时间戳；必须与 `colors` 配合。 |
+| `currentTime` | `null` | 路线时间裁剪位置；`null` 显示全部。 |
+| `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)` | 加载或更新线、样式和动画。 |
+| `setTime(currentTime)` | 更新路线时间裁剪；传 `null` 恢复完整路线，不重建全部线数据。 |
+| `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="typhoon-path-controller"></a>
+
+## TyphoonPathController
+
+把已经整理好的台风实况和预报数据渲染为独立专题图层，统一支持 Cesium / Leaflet。控制器负责实况路径、强度着色节点、生命周期标签、移动中心、当前点 7/10/12 级四象限风圈、多机构预报、不确定性圆和播放定位。
+
+BaseGIS 不请求台风接口，也不推算强度、风圈、预报或预警等级。分页筛选、接口字段转换、ECharts 和业务面板仍由应用层负责。24/48 小时警戒线属于普通业务折线，推荐与 `LineLayerController` 组合使用。
+
+### 最小用法
+
+```js
+import { TyphoonPathController } from '@3clear/basegis/methods'
+
+const typhoonLayer = new TyphoonPathController({
+  mapCore,
+  layerId: 'typhoon-senlac',
+})
+
+await typhoonLayer.load({
+  typhoon: { id: '2604', code: '2604', name: '森拉克' },
+  tracks: [
+    {
+      id: 'track-1',
+      time: '2026-04-10T18:00:00Z',
+      position: [136.2, 10.5],
+      level: 'TD',
+      stage: '热带低压',
+      windSpeed: 16,
+      pressure: 1002,
+      windCircles: {
+        r7: { ne: 120, se: 140, sw: 90, nw: 110 },
+      },
+      label: '生成 4/10 18时',
+    },
+    {
+      id: 'track-2',
+      time: '2026-04-11T12:00:00Z',
+      position: [133.2, 12],
+      level: 'TY',
+      stage: '台风',
+      windSpeed: 35,
+      pressure: 970,
+      windCircles: {
+        r7: { ne: 300, se: 320, sw: 200, nw: 220 },
+        r10: { ne: 120, se: 140, sw: 80, nw: 100 },
+      },
+      label: '加强 4/11 12时',
+    },
+  ],
+  playback: {
+    enabled: true,
+    durationMs: 12000,
+    autoplay: false,
+    loop: true,
+  },
+  onCurrentChange({ index, point, progress }) {
+    console.log(index, point, progress)
+  },
+})
+
+typhoonLayer.play()
+```
+
+坐标固定为 `[longitude, latitude, height?]`。风圈半径单位是公里，`ne / se / sw / nw` 分别表示东北、东南、西南、西北四个象限；没有某一级风圈时直接省略对应的 `r7 / r10 / r12`。
+
+### 已准备好的预报路径
+
+`forecastPaths` 支持同时传入多个机构结果。BaseGIS 只渲染传入结果，不在前端生成预报。
+
+```js
+await typhoonLayer.update({
+  forecastPaths: [{
+    id: 'cma',
+    name: '中央气象台',
+    style: {
+      color: '#ffdf4d',
+      width: 2.5,
+      opacity: 0.96,
+      dashLength: 12,
+      gapLength: 8,
+    },
+    points: [
+      { id: 'f1', time: '2026-04-13T12:00:00Z', position: [127.4, 19.2], level: 'STY' },
+      {
+        id: 'f2',
+        time: '2026-04-14T00:00:00Z',
+        position: [122.8, 20.5],
+        level: 'TY',
+        uncertaintyRadiusKm: 90,
+      },
+    ],
+  }],
+})
+```
+
+### 路径点格式
 
-### 参数
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `id` | 否 | 点 id；未传时使用时次或数组索引生成内部 id。 |
+| `time` | 建议 | ISO 字符串或浏览器可解析时间；播放优先按真实时距插值。 |
+| `position` | 是 | `[longitude, latitude, height?]`。 |
+| `level` | 否 | 强度代码，默认 `TD`；内置 `TD / TS / STS / TY / STY / SuperTY` 颜色。 |
+| `stage` / `label` | 否 | 中心状态文字和静态生命周期标签。 |
+| `windSpeed` / `pressure` | 否 | 中心标签可展示的风速和气压业务值。 |
+| `windCircles` | 否 | `r7 / r10 / r12` 四象限半径对象，单位 km。 |
+| `data` | 否 | 点击回调透传的业务数据。 |
+
+### 样式与播放配置
 
 | 参数 | 默认值 | 说明 |
 | --- | --- | --- |
-| `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` | - | 可选的飞机、车辆或船舶图标配置。 |
+| `visible` | `true` | 图层初始显隐。 |
+| `style.trackLine` | 白色、`width: 3` | 实况路径颜色、宽度、透明度及描边。 |
+| `style.forecastLine` | 白色虚线、`width: 2` | 未给单条预报路径样式时的默认值。 |
+| `style.point.radius` | `5` | 实况和预报节点半径。 |
+| `style.label.visible` | `true` | 是否显示传入的生命周期标签。 |
+| `style.center.iconUrl` | 包内台风 SVG | 可覆盖为业务 GIF、PNG 或 SVG。 |
+| `style.center.iconSize` | `[36, 36]` | 当前中心图标尺寸。 |
+| `style.center.rotate` | `true` | 是否旋转中心图标。 |
+| `style.center.showLabel` | `true` | 是否显示台风编号、名称、强度和风速。 |
+| `style.windCircle.visible` | `true` | 是否显示当前点的 7/10/12 级风圈。 |
+| `style.intensityColors` | 内置强度色 | 按 `level` 覆盖节点颜色。 |
+| `playback.enabled` | `true` | 是否允许路径播放。 |
+| `playback.durationMs` | `15000` | 从首点到末点的总时长。 |
+| `playback.autoplay` / `loop` | `false` / `false` | 自动播放与循环。 |
+| `playback.currentIndex` | `0` | 初始活动路径点。 |
+
+`onCurrentChange` 只在活动点索引变化或显式定位时触发，不会在每一帧刷业务状态。`onPointClick` 在点击实况点、预报点或当前中心时返回 `{ targetType, point, pointIndex, forecastPathId, coordinate, containerPoint, engineType }`，弹窗由业务页面实现。
 
 ### 方法
 
 | 方法 | 说明 |
 | --- | --- |
-| `mount(mapCore)` | 后挂载 BaseGIS。 |
-| `load(payload, options?)` / `update(payload)` | 加载或更新线、样式和动画。 |
-| `show()` / `hide()` / `toggle()` | 控制显隐。 |
-| `playAnimation()` / `pauseAnimation()` / `restartAnimation()` | 控制沿线动画。 |
-| `clear()` | 清空线和动画，保留控制器。 |
-| `refreshState()` / `getState()` | 获取线数量、点数和动画状态。 |
-| `destroy()` | 删除图层、动画和引擎恢复快照。 |
+| `mount(mapCore)` | 后挂载已经初始化的 BaseGIS。 |
+| `load(payload, options?)` / `update(payload)` | 加载或局部更新路径、预报、样式和播放配置。 |
+| `show()` / `hide()` / `toggle()` | 控制专题显隐；隐藏时暂停，重新显示后恢复原播放意图。 |
+| `play()` / `pause()` / `restart({ autoplay })` | 控制台风中心播放。 |
+| `seek(index)` / `seek({ time })` | 按点索引或时次定位。 |
+| `flyTo(options?)` | 定位到实况和预报路径范围。 |
+| `clear()` | 清空实况和预报数据，保留空图层及控制器。 |
+| `refreshState()` / `getState()` | 获取点数、预报数、当前索引、进度和播放状态。 |
+| `destroy()` | 删除图层、动画、点击监听和引擎恢复快照。 |
 
-页面卸载时先执行 `lineLayer.destroy()`，再执行 `mapCore.destroy()`。
+切换引擎会恢复数据、样式、显隐、播放/暂停意图和最后一次显式 `seek` 的位置；不会保存正在播放的逐帧进度。页面卸载时先执行 `typhoonLayer.destroy()`，再执行 `mapCore.destroy()`。
 
-在线示例：[查看 LineLayerController 双引擎应用 Demo](http://61.50.111.214:31166/lgmap/test-page-34)。
+在线示例：[查看 TyphoonPathController 双引擎应用 Demo](http://61.50.111.214:31166/lgmap/test-page-10)。
 
 <a id="image-layer-controller"></a>
 
@@ -1468,6 +2225,9 @@ imageLayer.destroy({ layerId: 'radar-image' })
 | `imageUrl` | 普通图片、灰度图、图片+TIF 必填 | 图片地址。仅 TIF 模式建议传空字符串清掉旧图片。 |
 | `tifUrl` | 仅 TIF、图片+TIF 必填 | GeoTIFF 数值地址，用于鼠标探针或网格注记，不会单独生成彩色图片底图。 |
 | `area` | 传 `imageUrl` 时必填 | 图片范围：`startLon / startLat / endLon / endLat`。 |
+| `sourceProjection` | 选填 | 源图投影；当前支持将 `EPSG:3857` 图片重采样为经纬度图片，不是任意投影转换器。 |
+| `sourceArea` | 选填 | 源图片范围，默认使用 `area`；支持墨卡托米坐标范围或经纬度范围。 |
+| `targetProjection` | 选填 | 默认从地图 CRS 推断；源投影与目标相同则不重采样。 |
 | `imageSourceType` | 灰度图必填，其他选填 | `color` 表示已填色图片；`grayscale` 表示灰度图。 |
 | `colorize` | 灰度图必填 | 灰度图业务值和色带配置。 |
 | `colorize.minValue` | 灰度图必填 | 色带映射最小值。 |
@@ -1475,6 +2235,7 @@ imageLayer.destroy({ layerId: 'radar-image' })
 | `colorize.noDataValue` | 选填 | 无效值。 |
 | `colorize.colors` | 灰度图必填 | 色带颜色数组。 |
 | `opacity` | 选填 | 透明度，通常 0 - 1。 |
+| `zIndex` | 选填 | Leaflet 图片叠放层级，默认 `650`。 |
 | `visible` | 选填 | 是否显示图层。 |
 | `showProbe` | 选填 | 是否开启鼠标探针，需要 `tifUrl` 或灰度图数值。 |
 | `showLabel` | 选填 | 是否显示网格注记，需要 `tifUrl` 或灰度图数值。 |
@@ -1483,11 +2244,7 @@ imageLayer.destroy({ layerId: 'radar-image' })
 | `gridTotal` | 选填 | 切片网格数量。 |
 | `tileSize` | 选填 | 切片尺寸。 |
 
-兼容方法：
-
-- `load(items, { index, visible })`：兼容旧的图片集合加载方式，会把 `items[index]` 写入当前图层。
-- `switchTo(idOrIndex)`：在已加载的 `items` 内切换到某一项。
-- `next() / prev()`：只适合本地小数组演示，不推荐作为业务时次更新主路径。
+图片重采样依赖 Canvas 读取像素，跨域图片需要服务端允许 CORS。
 
 <a id="grid-layer-controller"></a>
 
@@ -1555,7 +2312,7 @@ await gridLayer.loadData({
   },
 })
 
-gridLayer.update({ decimalPlaces: 2 })
+await gridLayer.update({ decimalPlaces: 2 })
 gridLayer.hide()
 gridLayer.show()
 gridLayer.destroy()
@@ -1570,9 +2327,31 @@ gridLayer.destroy()
 
 灰度图要表达真实业务值时，应显式传入 `minValue / maxValue`。数值图层不使用色带绘制背景；如果需要同时显示彩色图片，请使用 `ImageLayerController`。
 
-## 统一粒子风场
+### 方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `mount(mapCore)` | 后挂载 BaseGIS。 |
+| `load(payload)` | 加载 `tifUrl / imageUrl / grayImageUrl / imageGridData` 数据源。 |
+| `loadTif(payload)` / `loadGrayImage(payload)` / `loadData(payload)` | 对应三种数据源的快捷加载方法。 |
+| `update(payload)` | 合并更新已加载数据和参数；首次尚未加载时返回 `NOT_LOADED`。 |
+| `show()` / `hide()` | 控制显隐。 |
+| `getState()` | 返回挂载状态、引擎、图层 id、显隐及当前 payload。 |
+| `destroy()` | 移除网格图层并清理控制器数据。 |
+
+<a id="unified-wind-layer"></a>
+
+## 风场统一入口（推荐）
 
-同一组 API 会根据当前引擎自动选择渲染器：Cesium 使用 GPU 粒子风场，Leaflet 使用迁自 one-map 的 Canvas 粒子风场。
+风场有 GPU 和 Canvas 两种渲染方式，三个调用入口的区别如下：
+
+| 调用入口 | Cesium | Leaflet | 切换引擎后自动恢复 |
+| --- | --- | --- | --- |
+| `BaseGIS.upsertWindLayer()`（推荐） | GPU | Canvas | 支持 |
+| [`BaseGIS.upsertGpuWindLayer()`](#gpu-wind-layer) | GPU | 不支持 | 不支持 |
+| [`WindFieldMethods`](#wind-field-methods) | Canvas | Canvas | 不支持 |
+
+一般使用 `upsertWindLayer()` 即可，它会根据当前引擎自动选择渲染器。需要在 Cesium 上使用 Canvas，或需要叠加风速底图时，使用 `WindFieldMethods`。
 
 ```js
 const windData = await fetch('/mock/uv.json').then((response) => response.json())
@@ -1610,9 +2389,13 @@ mapCore.removeWindLayer({ layerId: 'surface-wind' })
 
 跨引擎统一使用 `Bound / DataAry` 数据格式。公共参数包括 `maxParticles`、`speedFactor`、`lineWidth`、`fadeOpacity`、`particleOpacity`、`color` 和 `visible`；适配层会统一速度、帧率拖尾、屏幕线宽、设备像素比和粒子视觉密度。`maxParticles` 表示跨引擎视觉预算：Cesium 的实际粒子数会按 GPU 纹理向上取整为整数平方，Leaflet 会按 Canvas 拖尾覆盖率换算实际粒子数，均可通过图层状态查看；算法和投影不同，因此不保证逐像素完全一致。Leaflet 还支持 `particleGap`、`maxAge`、`frameRate`、`minSpeed`。统一风场属于 BaseGIS 托管图层，`setEngine()` 切换引擎时会自动使用原数据和最新参数恢复。
 
-## GPU 粒子风场
+<a id="gpu-wind-layer"></a>
+
+## GPU 风场
 
-GPU 粒子风场是 Cesium 专有能力，直接通过 `BaseGIS` 调用。它使用显卡纹理保存和更新粒子，相机平移或缩放期间清空轨迹，操作结束后按新视野重新生成粒子。Leaflet 调用同名方法时会返回 `UNSUPPORTED_CAPABILITY`，不会抛异常。
+`upsertGpuWindLayer()` 与统一入口在 Cesium 下使用同一套 GPU 实现。本节接口直接使用 GPU 参数，不参与 BaseGIS 的引擎切换恢复；统一入口还会换算线宽等参数，因此两组接口的参数值不宜直接照搬。
+
+GPU 风场仅支持 Cesium。它使用显卡纹理保存和更新粒子，相机平移或缩放期间清空轨迹，操作结束后按新视野重新生成粒子。Leaflet 调用本节接口时会返回 `UNSUPPORTED_CAPABILITY`，不会抛异常。
 
 Cesium 由宿主通过 `window.Cesium` 提供。启用 `terrainEnabled` 后，图层会采样当前 `viewer.terrainProvider`，让轨迹高度随地形变化；如果当前使用椭球地形，采样高度为 0。
 
@@ -1652,9 +2435,9 @@ if (!result.success) {
 const windData = {
   // 经度最小值、纬度最小值、经向格点数、纬向格点数、
   // 经度跨度、纬度跨度、数值缩放倍数。
-  Bound: [100, 10, 181, 91, 80, 40, 10],
+  Bound: [100, 10, 2, 2, 10, 10, 10],
   // 每个格点按 U、V 交错；纬度行从南向北排列。
-  DataAry: [u0, v0, u1, v1],
+  DataAry: [30, 10, 40, 15, 20, 10, 35, 5],
 }
 ```
 
@@ -1672,7 +2455,7 @@ const windData = {
   },
   u: new Float32Array(181 * 91),
   v: new Float32Array(181 * 91),
-  // index-gpu.vue 解码结果从北向南排列，因此使用 north-to-south。
+  // 仅当数据行从北向南排列时设置；默认按南到北排列。
   rowOrder: 'north-to-south',
 }
 ```
@@ -1740,6 +2523,76 @@ 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="source-transport"></a>
+
+## 源解析传输
+
+源解析传输是 Cesium 专有复合层，包含彩色贡献弧线、灰色烟羽 Billboard、移动烟团、来源/目标节点、路径选择和目标汇聚体。业务接口、城市聚合、污染物字段与时间轴由页面处理，整理好 `target + flows` 后一次调用即可：
+
+```js
+const sources = [
+  { code: 'source-1', name: '来源一', position: [118.1, 24.5], value: 12, percent: 37.5 },
+  { code: 'source-2', name: '来源二', position: [120.6, 27.9], value: 20, percent: 62.5 },
+]
+
+const result = mapCore.upsertSourceTransportLayer({
+  layerId: 'source-analysis',
+  target: {
+    name: '福州市',
+    position: [119.331, 26.0639],
+    label: '福州市  汇聚中心\n累积浓度 32.00 μg/m³',
+  },
+  flows: sources.map(source => ({
+    id: source.code,
+    name: source.name,
+    start: source.position,
+    value: source.value,
+    percent: source.percent,
+    label: source.label,
+    data: source,
+  })),
+  onSelect(flow) {
+    console.log('选中来源', flow)
+  },
+  onHover(flow, screenPosition) {
+    console.log('悬停来源', flow, screenPosition)
+  },
+})
+
+if (result.success) {
+  mapCore.flyToSourceTransportLayer({ layerId: 'source-analysis' })
+}
+```
+
+| 参数 | 是否必填 | 说明 |
+| --- | --- | --- |
+| `layerId` | 否 | 默认 `source-transport-default`。 |
+| `target.position` | 创建时必填 | 目标 `[longitude, latitude]`；可附带 `name/label/data`。 |
+| `flows` | 创建时必填 | 每项至少传 `start`（兼容 `position`）；`end` 默认目标位置。 |
+| `flow.id/code` | 建议 | 稳定且不重复的来源标识。 |
+| `flow.value/intensity` | 否 | `intensity` 范围 `0～1`；不传时按本批有效 `value` 做最小最大归一化，同值时为 `0.5`。 |
+| `flow.percent` | 否 | 百分数值，例如 `37.5` 表示 `37.5%`，参与弧高与烟羽速度计算。 |
+| `flow.bend/arcHeight/color/lineWidth/label/smoke/data` | 否 | 单来源覆盖。 |
+| `colors` | 否 | 来源颜色调色板，可由每条 flow 的 `color` 覆盖。 |
+| `visible/running` | 否 | 初始显隐与动画状态，默认均为 `true`。 |
+| `path/line/smoke/sourceNode/targetNode/volume/interaction/fog/camera` | 否 | 单层视觉配置，可覆盖 BaseGIS 实例级默认值。 |
+| `onSelect/onHover` | 否 | 分别接收 `flow/null` 和 `flow/null, screenPosition/null`。 |
+
+`target.volume: false` 或 `volume: { enabled: false }` 可关闭目标汇聚体；也可通过 `target.volume.data/option/parameters/colorRamp` 传真实体数据。未传数据时会生成示意汇聚云，底层复用 `upsertVolumeLayer`，该云形不代表业务浓度的真实三维分布。
+
+`updateSourceTransportLayer()` 支持部分更新：`target` 对象会合并，`flows` 数组整体替换。只更新 `target.volume` 时，不会重建来源弧线：
+
+```js
+mapCore.updateSourceTransportLayer({
+  layerId: 'source-analysis',
+  target: { volume: { parameters: { opacity: 0.5, brightness: 1.1 } } },
+})
+```
+
+目标体云创建失败时，其余部分仍可能加载成功。除 `success` 外，还应检查 `result.data.degraded`（可能包含 `'targetVolume'`）和 `result.data.state.volumeError`。
+
+生命周期方法：`updateSourceTransportLayer`、`showSourceTransportLayer`、`hideSourceTransportLayer`、`playSourceTransportLayer`、`pauseSourceTransportLayer`、`flyToSourceTransportLayer`、`clearSourceTransportLayer`、`getSourceTransportLayerState`、`removeSourceTransportLayer`。`clear` 会一起清掉来源、目标和内部体云；Leaflet 返回 `UNSUPPORTED_CAPABILITY` 且不抛异常，切回 Cesium 后自动恢复托管快照。
+
 <a id="volume-rendering"></a>
 
 ## 三维体渲染
@@ -1751,11 +2604,17 @@ GPU 专用 API 不属于跨引擎自动恢复图层。切换 Cesium/Leaflet 后
 ### 基础用法
 
 ```js
+// 3 个经度 × 2 个纬度 × 2 个高度层，X 最快变化，随后是 Y、Z。
+const volumeValues = new Uint8Array([
+  20, 80, 120, 60, 160, 220,
+  40, 100, 160, 80, 180, 240,
+])
+
 const result = mapCore.upsertVolumeLayer({
   // 建议必填：图层唯一 id。再次使用同一个 layerId 调用会覆盖旧体渲染层。
   layerId: 'volume-demo',
 
-  // 必填：体数据一维数组，长度通常为 rows * cols * heights。
+  // 必填：0～255 编码的一维数组，长度必须等于 rows * cols * heights。
   data: volumeValues,
 
   // 必填：体数据范围和网格尺寸。
@@ -1766,19 +2625,20 @@ const result = mapCore.upsertVolumeLayer({
     // 纬度范围。
     ymin: 30,
     ymax: 40,
-    // 高度范围，单位按业务数据约定。
+    // 高度范围，单位米。
     zmin: 0,
     zmax: 10000,
-    // 纬向、经向、高度向网格数量。
-    rows: 100,
-    cols: 100,
-    heights: 30,
+    // 经度 X、纬度 Y、高度 Z 的网格数量，均为不小于 2 的整数。
+    rows: 3,
+    cols: 2,
+    heights: 2,
   },
 
   // 选填：体渲染 shader 参数，可后续单独更新。
   parameters: {
-    // 采样阈值。值越小，通常显示范围越少；具体效果和数据归一化有关。
-    threshold: 0.3,
+    // 使用 0～255 编码直接定位色带，不再采用旧的 0～15 映射。
+    normalizedColorRamp: 1,
+    opacity: 0.72,
     // 光线步进采样次数。越大越细腻，也越耗性能。
     steps: 100,
     // x/y/z 三个方向裁切位置，默认 -0.5 表示不裁切。
@@ -1787,6 +2647,8 @@ const result = mapCore.upsertVolumeLayer({
     zCut: -0.5,
   },
 
+  colorRamp: ['#2f80ed', '#22c55e', '#facc15', '#ef4444'],
+
   // 选填：初始是否显示。
   visible: true,
 })
@@ -1798,13 +2660,13 @@ if (!result.success) {
 
 ### 更新参数
 
-更新透明阈值、步进数、裁切面时，不需要重新加载体数据，直接更新参数即可。
+更新透明度、密度、步进数或裁切面时，不需要重新加载体数据，直接更新参数即可。
 
 ```js
 mapCore.updateVolumeLayerParameters({
   layerId: 'volume-demo',
   parameters: {
-    threshold: 0.5,
+    opacity: 0.5,
     steps: 180,
     zCut: 0.1,
   },
@@ -1813,27 +2675,46 @@ mapCore.updateVolumeLayerParameters({
 
 ### 更新数据
 
-更新数据或空间范围时，继续使用同一个 `layerId` 调用 `upsertVolumeLayer`。适配层会先移除旧 Primitive，再创建新的体渲染层。
+空间范围和网格尺寸不变时，使用 `updateVolumeLayerData()` 更新同一 Primitive 的体纹理：
+
+```js
+mapCore.updateVolumeLayerData({
+  layerId: 'volume-demo',
+  data: Uint8Array.from(volumeValues, (value) => Math.min(255, value + 10)),
+})
+```
+
+新数据长度必须与原网格一致。此方法会恢复显示；如果需要保持隐藏，更新后再调用 `hideVolumeLayer()`。空间范围或网格尺寸改变时，使用同一 `layerId` 重新调用 `upsertVolumeLayer({ data, option, ... })`。新 Primitive 创建并加入场景后才释放旧图层，创建失败时保留旧图层。
+
+### 按屏幕位置取值
+
+`sampleVolumeLayerValue()` 沿屏幕位置的相机射线采样，选取对可见体云贡献最大的点，并对数据做三线性插值。`position` 为相对地图画布左上角的 CSS 像素坐标，不是经纬度：
 
 ```js
-mapCore.upsertVolumeLayer({
+const sampleResult = mapCore.sampleVolumeLayerValue({
   layerId: 'volume-demo',
-  data: nextVolumeValues,
-  option: nextVolumeOption,
-  parameters: currentParameters,
+  position: { x: 320, y: 180 },
+  steps: 120,
+  // 可选 data：与纹理同长度、同顺序的原始业务值数组。
+  // 不传则返回渲染数据值；命中位置始终由可见体云决定。
 })
+if (sampleResult.success) {
+  console.log(sampleResult.data) // { value, lon, lat, height }，height 单位米。
+}
 ```
 
+图层隐藏、未命中或被地表遮挡时返回失败结果。取值采样步数限制为 `32～400`，与渲染步数上限不同。
+
 ### 显隐、定位和移除
 
 ```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)
+mapCore.removeVolumeLayer({ layerId: 'volume-demo' })
 ```
 
 ### 方法总表
@@ -1841,30 +2722,37 @@ console.log(stateResult.data)
 | 方法 | 参数 | 说明 |
 | --- | --- | --- |
 | `upsertVolumeLayer(payload)` | 体渲染配置 | 创建或更新体渲染层。同 `layerId` 会覆盖旧图层。 |
+| `updateVolumeLayerData(payload)` | `{ layerId, data }` | 同范围、同网格尺寸时更新体纹理，不重建 Primitive。 |
 | `updateVolumeLayerParameters(payload)` | `{ layerId, parameters }` | 更新体渲染 shader 参数，不重新加载体数据。 |
 | `showVolumeLayer(payload)` | `{ layerId }` | 显示体渲染层。 |
 | `hideVolumeLayer(payload)` | `{ layerId }` | 隐藏体渲染层。 |
 | `removeVolumeLayer(payload)` | `{ layerId }` | 移除体渲染层并释放 Primitive。 |
 | `flyToVolumeLayer(payload)` | `{ layerId, duration }` | 飞到体渲染层经纬度范围。 |
 | `getVolumeLayerState(payload)` | `{ layerId }` | 获取图层状态。 |
+| `sampleVolumeLayerValue(payload)` | `{ layerId, position, data?, steps? }` | 按屏幕位置取值；可用 `windowPosition`、`values` 作为别名。 |
 
 ### 参数总表
 
 | 参数 | 是否必填 | 说明 |
 | --- | --- | --- |
 | `layerId` / `volumeLayerId` / `id` | 建议必填 | 体渲染图层 id，不传默认 `volume-default`。 |
-| `data` / `value` / `values` | 必填 | 体数据一维数组，通常按层、行、列展开。 |
+| `data` / `value` / `values` | 必填 | `0～255` 字节编码，长度为 `rows * cols * heights`；索引为 `z * rows * cols + y * rows + x`。业务浮点值需先编码，不会自动归一化。 |
 | `option` | 必填 | 体数据空间范围和网格尺寸。 |
 | `option.xmin / xmax` | 必填 | 经度最小值和最大值。 |
 | `option.ymin / ymax` | 必填 | 纬度最小值和最大值。 |
-| `option.zmin / zmax` | 必填 | 高度最小值和最大值。 |
-| `option.rows` | 必填 | 纬向网格数量。 |
-| `option.cols` | 必填 | 经向网格数量。 |
-| `option.heights` | 必填 | 高度层数量。 |
-| `parameters.threshold` | 选填 | 采样阈值。 |
-| `parameters.steps` | 选填 | 光线步进采样次数。 |
+| `option.zmin / zmax` | 必填 | 高度最小值和最大值，单位米。 |
+| `option.rows` | 必填 | X / 经度方向数量，不小于 `2` 的整数。 |
+| `option.cols` | 必填 | Y / 纬度方向数量，不小于 `2` 的整数。 |
+| `option.heights` | 必填 | Z / 高度层数量，不小于 `2` 的整数。 |
+| `parameters.threshold` | 选填 | 默认 `1.2`；仅累积归一化纹理值小于该阈值的样本，不是整体透明度。 |
+| `parameters.steps` | 选填 | 默认 `1200`；渲染步进数限制在 `1～4000`。 |
+| `parameters.densityThreshold` | 选填 | 默认 `0.08`，按色带位置过滤低密度样本的起点。 |
+| `parameters.densitySoftness` | 选填 | 默认 `0.47`，低密度过滤的过渡宽度。 |
+| `parameters.densityScale` | 选填 | 默认 `0.34`，每步透明度累积强度。 |
+| `parameters.opacity / brightness` | 选填 | 默认 `0.72 / 1`，整体透明度和颜色亮度倍率。 |
+| `parameters.normalizedColorRamp` | 选填 | 默认 `0`；设为 `1` 时用 `data / 255` 定位色带。 |
 | `parameters.xCut / yCut / zCut` | 选填 | 三个方向的裁切位置，默认 `-0.5`。 |
-| `colorRamp` / `colors` / `colorKeys` | 选填 | 自定义色带配置。 |
+| `colorRamp` | 选填 | CSS 颜色数组、RGBA 数组列表或展平的 RGBA 字节数组。 |
 | `geometry` / `dim` | 选填 | 自定义体渲染几何或维度，普通业务通常不需要传。 |
 | `visible` | 选填 | 初始是否显示，默认显示。 |
 
@@ -1874,27 +2762,28 @@ console.log(stateResult.data)
 
 三维切片/剖面渲染也是 Cesium 专有能力，直接通过 `BaseGIS` 调用。它把三维网格数据按 X、Y、Z 三个方向切出剖面，适合气象温度、湿度、风场标量、污染物浓度等三维格点数据查看。
 
-这里的“切片”指三维数据剖面，不是 `ImageLayerController` 里的大图切片。
+这里的“切片”指三维数据剖面，不是 `ImageLayerController` 里的大图切片。当前 Z 轴按 hPa 气压处理，内部将气压换算为高度后放大 10 倍显示，不接受任意米制高度层。
 
 ### 数据格式
 
 ```js
 const sectionData = {
   Bound: [
-    1000,      // 0: LayerMax，最高气压层或起始层值。
+    1000,      // 0: LayerMax，起始气压值（hPa），较大气压在下方。
     108.68,    // 1: LonMin，经度最小值。
     28.59,     // 2: LatMin，纬度最小值。
     10,        // 3: LayerNums，层数。
     147,       // 4: LonNums，经向格点数。
     198,       // 5: LatNums，纬向格点数。
-    900,       // 6: DLayer 或 LayerMin 相关值，按数据生成规则提供。
+    900,       // 6: DLayer，气压跨度；LayerMin = LayerMax - DLayer。
     16.74,     // 7: DLon，经度跨度。
     16.71,     // 8: DLat，纬度跨度。
-    1,         // 9: ValueScale，数值缩放。
-    1,         // 10: 预留/数据标记。
+    1,         // 9: ValueScale，业务值 = 原始值 / ValueScale。
+    1,         // 10: Stride，每个格点的分量数；标量为 1。
     [1000, 925, 850, 700, 600, 500, 400, 300, 200, 100], // 11: LayerList，气压层列表。
   ],
-  // 必填：三维格点值一维数组，长度通常为 LayerNums * LatNums * LonNums。
+  // 长度必须等于 LayerNums * LatNums * LonNums * Stride。
+  // 每层从西南角开始，经度最快变化，再纬度，最后气压层。
   DataAry: valueList,
 }
 
@@ -1913,6 +2802,8 @@ const optionData = {
 }
 ```
 
+`Bound[11]` 可传 `null` 表示等间距气压层；传列表时长度必须等于 `LayerNums`，首项必须等于 `Bound[0]`。`Stride > 1` 时当前实现计算各分量的模长。
+
 ### 加载或更新数据
 
 同一个 `layerId` 重复调用 `upsertSectionLayer` 就是更新数据。适配层会清理旧切片，再加载新数据。
@@ -1936,15 +2827,16 @@ const result = mapCore.upsertSectionLayer({
 
   // 选填：是否显示坐标轴和刻度。
   showAxis: false,
+  // 选填：有 DEM 时避免近地切片被地形裁断，默认 false。
+  ignoreTerrainDepth: true,
 })
 
-if (!result.success) {
+if (result.success) {
+  const state = result.data.state
+  console.log(state.XRange, state.YRange, state.ZRange)
+} else {
   console.warn(result.message)
-  return
 }
-
-const state = result.data.state
-console.log(state.XRange, state.YRange, state.ZRange)
 ```
 
 ### 渲染 X / Y / Z 切片
@@ -1964,7 +2856,7 @@ mapCore.renderSectionLayer({
   value: 39.9,
 })
 
-// Z 高度/气压方向切片。
+// Z 气压方向切片，单位 hPa。
 mapCore.renderSectionLayer({
   layerId: 'section-demo',
   sectionType: 2,
@@ -1978,7 +2870,7 @@ mapCore.renderSectionLayer({
 | --- | --- | --- |
 | `0` | 经度方向剖面 | 经度值。 |
 | `1` | 纬度方向剖面 | 纬度值。 |
-| `2` | 高度/气压方向剖面 | 气压层或高度层值。 |
+| `2` | 气压方向剖面 | 气压值，单位 hPa。 |
 | `3` | 全量剖面 | 可不传 `value`。 |
 
 ### 显隐、移除和定位
@@ -1994,16 +2886,16 @@ mapCore.removeSectionLayer({
   sectionType: 2,
 })
 
-// 移除整个切片图层。
-mapCore.removeSectionLayer({ layerId: 'section-demo' })
-
 // 飞到切片数据范围。
 mapCore.flyToSectionLayer({ layerId: 'section-demo', duration: 0.8 })
+
+// 移除整个切片图层。
+mapCore.removeSectionLayer({ layerId: 'section-demo' })
 ```
 
 ### hover 取值
 
-页面先用 Cesium 拾取得到鼠标所在三维点，再交给 `sampleSectionLayerValue` 计算当前切片上的数值。
+页面先用 Cesium 拾取得到鼠标所在三维点，再将经纬度与对应气压交给 `sampleSectionLayerValue`。`hpa` 不是 Cesium 的 `cartographic.height`；应先还原 10 倍高度显示比例，再按剖面使用的气压高度关系换算。
 
 ```js
 const result = mapCore.sampleSectionLayerValue({
@@ -2047,9 +2939,10 @@ if (result.success) {
 | `colorInfo.rgbAry` | 建议必填 | 色标 RGB 数组。 |
 | `boxInfo` | 选填 | 自定义剖面盒子范围。不传时根据 `dataInfo` 自动生成。 |
 | `showAxis` | 选填 | 是否显示坐标轴和刻度。 |
-| `sectionType` | 渲染、显隐、移除单个切片时必填 | `0` 经度，`1` 纬度，`2` 高度/气压，`3` 全量。 |
+| `ignoreTerrainDepth` | 选填 | 默认 `false`；设为 `true` 时，可见剖面暂时关闭 globe 地形深度检测，不改变切片自身深度写入。 |
+| `sectionType` | 渲染、显隐、移除单个切片时必填 | `0` 经度，`1` 纬度，`2` 气压，`3` 全量。 |
 | `value` / `param` | `sectionType` 为 `0/1/2` 时必填 | 切片位置值。 |
-| `lon / lat / hpa` | hover 取值必填 | Cesium 拾取得到的经度、纬度、气压高度。 |
+| `lon / lat / hpa` | hover 取值必填 | 经度、纬度及换算后的气压（hPa），不是米制高度。 |
 | `showZLayer` | hover 取值选填 | Z 切片是否参与 hover 命中，默认参与。 |
 
 <a id="point-large-layer-controller"></a>
@@ -2062,160 +2955,54 @@ Leaflet 模式使用 BaseGIS 内置的 `pixi.js` 和 `leaflet-pixi-overlay` 异
 
 如果业务目标是“地图缩小时按屏幕网格抽稀，只显示代表点”，应使用后文的 `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 包外部项目使用：
+地图初始化成功后创建控制器，再调用 `load()` 加载点位。以下使用内置圆点，无需先准备图片资源；实际项目可通过 `icon / highlightIcon` 替换普通与高亮图标。
 
 ```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}。`},
-    
+  mapCore,
+  layerId: 'station-large',
+  idKey: 'stationCode',
+  width: 18,
+  height: 18,
+  color: '#ffffff', // 白色基础纹理，供分级规则着色。
+  styleField: 'value',
+  // 从上到下匹配，首个命中的规则生效。
+  styleRules: [
+    { gte: 150, style: { color: '#ff4d4f' } },
+    { gte: 75, style: { color: '#faad14' } },
+    { default: true, style: { color: '#19d3a2' } },
+  ],
+  onClick({ id, data }) {
+    console.log('点击点位', id, data)
+  },
 })
 
 await pointLayer.load({
   points: [
-    {
-      stationCode: 'A001',
-      name: '站点 A001',
-      longitude: 104,
-      latitude: 35,
-      value: 86,
-    },
+    { stationCode: 'A001', name: '站点 A001', longitude: 104, latitude: 35, value: 86 },
+    { stationCode: 'A002', name: '站点 A002', longitude: 105, latitude: 35, value: 42 },
+    { stationCode: 'A003', name: '站点 A003', longitude: 106, latitude: 35, value: 168 },
   ],
 })
 ```
 
 `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 }`                               | 兜底规则。 |
-
-
-
+| 写法 | 说明 |
+| --- | --- |
+| `{ field: 'aqi', min: 51, max: 100 }` | 指定字段并按区间匹配。 |
+| `{ gt: 150 }` | 使用 `styleField` 指定的字段做大于判断。 |
+| `{ gte: 51, lt: 101 }` | 使用 `styleField` 指定的字段做区间判断。 |
+| `{ values: ['优', '良'] }` | 命中指定值集合。 |
+| `{ operator: '>', value: 100 }` | 支持 `> / >= / < / <= / == / === / != / !== / in`。 |
+| `{ when: (point, index, record) => point.value > 100 }` | 自定义匹配函数。 |
+| `{ default: true }` | 兜底规则。 |
 
-### 使用方式：更新数据或样式
+### 更新数据或样式
 
 时间轴、实时刷新等场景中，建议复用同一个控制器实例，不要每次刷新都重新 `new PointLargeLayerController()`。
 
@@ -2550,7 +3337,7 @@ onBeforeUnmount(() => {
 <style scoped lang="scss">
 .station-cluster-map {
   width: 100%;
-  height: 100%;
+  height: 100vh;
 }
 </style>
 ```
@@ -2602,9 +3389,11 @@ if (!result.success) {
 单点点击的第一个参数是原始点位数据：
 
 ```js
-onClick(point, engineObject, event) {
-  console.log(point.id)
-}
+await stationCluster.setConfig({
+  onClick(point, engineObject, event) {
+    console.log(point.id)
+  },
+})
 ```
 
 聚合点击的第一个参数结构如下：
@@ -2735,9 +3524,9 @@ mapCore.removePointClusterLayer({ layerId: 'station-cluster' })
 
 仓库内已有多个点位抽稀 demo：
 
-- `/test-page-6`：站点 ICON 抽稀，使用 `imageCallback` 按数据绘制站点图标。
 - `/test-page-8`：空气质量站点抽稀，使用固定 `image` 图标。
 - `/test-page-13`：空气质量业务页里的城市点位抽稀。
+- `/test-page-41`：`imageCallback` 同步返回 Canvas 图标和 `pulse` 告警扩散参数。
 
 ### 基础用法
 
@@ -2763,12 +3552,31 @@ const density = new PointDensityController({
   // 同一网格内保留哪个点。字段值越大越优先显示。
   priorityKey: 'level',
 
-  // 默认图标。
-  image: '/icons/station.png',
-
-  // 图标尺寸。
-  width: 28,
-  height: 28,
+  // 直接复用 BaseGIS 内置 Canvas 图标。
+  imageCallback(point) {
+    const icon = mapCore.createMarkerIcon({
+      type: 'image-value-label',
+      image: factoryImage,
+      imageSize: [24, 24],
+      showValue: false,
+      showLabel: false,
+    }, point)
+
+    return {
+      ...icon,
+      iconAnchor: 'center',
+      pulse: point.status === 'alarm'
+        ? {
+            color: '#ef4444',
+            size: 72,
+            duration: 1.6,
+            ringCount: 2,
+            ringWidth: 2,
+            ringOpacity: 0.75,
+          }
+        : false,
+    }
+  },
 
   // 点击点位回调。第一个参数是原始点位数据。
   onClick(point) {
@@ -2783,122 +3591,13 @@ const density = new PointDensityController({
 
 await density.load({
   points: [
-    { staNum: 'A001', longitude: 104, latitude: 35, level: 5 },
-    { staNum: 'A002', longitude: 104.01, latitude: 35.01, level: 3 },
+    { staNum: 'A001', name: '站点一', longitude: 104, latitude: 35, level: 5, value: 22, status: 'normal' },
+    { staNum: 'A002', name: '站点二', longitude: 104.01, latitude: 35.01, level: 3, value: 68, status: 'alarm' },
   ],
 })
 ```
 
-### 完整配置模板
-
-下面的配置接近 `test-page-6` 的写法，字段已加注释。业务中按需保留即可。
-
-```js
-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)
-  },
-})
-```
+上例中的 `factoryImage` 是创建抽稀层前已加载完成的 `Image`。`pulse` 使用与普通 Marker 相同的参数，只为抽稀后实际保留的点创建；点被替换、移出视野、隐藏、清空或删除时，扩散圈会随图标一起回收。
 
 ### 点位数据格式
 
@@ -3044,7 +3743,7 @@ density.destroy()
 | `priorityKey` | 否 | - | 同一网格内点位优先级字段，值越大越优先显示。 |
 | `priorityCallback` | 否 | - | 自定义优先级函数，返回值越大越优先显示。 |
 | `image` / `icon` / `iconUrl` | 否 | - | 默认图标地址。 |
-| `imageCallback` | 否 | - | 图标生成函数，适合每个点图标不同的场景。 |
+| `imageCallback` | 否 | - | 图标生成函数；配置对象可附带 `pulse` 告警扩散参数。 |
 | `width` | 否 | `32` | 图标宽度，单位像素。 |
 | `height` | 否 | `32` | 图标高度，单位像素。 |
 | `throttleTime` | 否 | `120` | 地图移动、缩放后刷新抽稀的节流时间，单位毫秒。 |
@@ -3088,7 +3787,7 @@ console.log(state)
 
 ## 等值线与中心标注能力选择
 
-对外只保留 2 个控制器：已有线坐标或中心坐标时用 `ContourLayerController`，手里是栅格时用 `RasterContourController`。线值标签与中心标注都属于通用 Contour 渲染配置，不再需要单独的气压组合层。
+已有线坐标或中心坐标时用 `ContourLayerController`，输入栅格时用 `RasterContourController`。线值标签与中心标注均使用通用 Contour 渲染配置。
 
 | 手里的数据 / 目标 | 使用入口 | 负责内容 |
 | --- | --- | --- |
@@ -3384,7 +4083,7 @@ await rasterContour.loadGrid({
 | `minimumLinePoints` | `number` | 否 | `3` | 最短线点数，用于过滤栅格四角的两点补边。 |
 | `coordinatePrecision` | `number` | 否 | `6` | 输出经纬度小数位数。 |
 | `visible` | `boolean` | 否 | `true` | 初始显隐。 |
-| 其他渲染参数 | - | 否 | - | 复用 [`ContourLayerController` 核心参数](#contour-layer-parameters)，如 `color/width/weight/styleCallback/showLabel/labelViewportPadding`。 |
+| 其他渲染参数 | - | 否 | - | 复用 [`ContourLayerController` 核心参数](#contour-layer-parameters)，如 `color/weight/styleCallback/showLabel/labelViewportPadding`；顶层 `width/height` 为栅格尺寸，线宽请用 `weight` 或 `styleCallback` 返回的 `width/weight`。 |
 
 级别选择优先级为 `thresholds` → `interval` → `thresholdCount`。显式传入 `thresholds` 时，只保留实际值域内的级别。
 
@@ -3506,10 +4205,14 @@ await pressureContour.load({
 
 <a id="wind-field-methods"></a>
 
-## WindFieldMethods
+## Canvas 风场（WindFieldMethods）
 
 用于叠加 Canvas 风场粒子动画。它通过 `BaseGIS` 获取容器、投影、视野范围和视图变化事件，不直接依赖某个引擎。
 
+与 `upsertWindLayer()` 不同，该控制器在两个引擎中都使用 Canvas，可叠加风速底图，但不参与 BaseGIS 托管恢复。切换引擎时先清理旧控制器，再在新地图初始化后重新挂载并加载数据。
+
+Leaflet 的统一风场入口使用的是另一套 Canvas 渲染器。本节控制器使用 `particleCount / velocityScale` 等参数，不能直接套用统一入口的 `maxParticles / speedFactor`。
+
 ```js
 import { WindFieldMethods } from '@3clear/basegis/methods'
 
@@ -3519,9 +4222,9 @@ wind.addWindField({
   id: 'wind-main',
   data: windData,
   particleCount: 3000,
-  velocityScale: 0.01,
   lineWidth: 1,
-  color: 'rgba(80, 180, 255, 0.8)',
+  // 单色粒子用一档色标；不传则使用内置风速分级色标。
+  particleColorScale: [{ value: 0, color: '#50b4ff' }],
 })
 
 wind.updateWindField({
@@ -3561,11 +4264,9 @@ const wind = new WindFieldMethods({ mapCore })
 ```js
 const windData = {
   // [经度最小值, 纬度最小值, 经向网格数, 纬向网格数, 经度跨度, 纬度跨度, 数值缩放]
-  Bound: [70, 15, 121, 81, 60, 40, 10],
+  Bound: [100, 10, 2, 2, 10, 10, 10],
   // 从左下角开始，按行平铺；每个格点两个值：[u, v]
-  DataAry: [
-    // u0, v0, u1, v1, ...
-  ],
+  DataAry: [30, 10, 40, 15, 20, 10, 35, 5],
 }
 ```
 
@@ -3606,12 +4307,12 @@ const windData = {
 | `particleCount` | `number` | `1400` | 粒子总数。数值越大越密，渲染开销越高。 |
 | `maxFrameParticles` | `number` | `1200` | 单帧最多推进和绘制的粒子数。 |
 | `frameParticleLimit` | `number` | `1200` | `maxFrameParticles` 的别名。 |
-| `sceneModeMaxFrameParticles` | `number` | `0` | 场景模式相关帧粒子上限预留参数。当前未作为主路径使用。 |
+| `sceneModeMaxFrameParticles` | `number` | `0` | 大于 `0` 时进一步限制 2D / 2.5D 场景每帧推进的粒子数，且不超过 `maxFrameParticles`。 |
 | `maxAge` | `number` | `58` | 粒子最大生命周期，超过后重新随机出生。 |
 | `frameRate` | `number` | `30` | 粒子动画目标帧率，内部限制在 `1 ~ 60`。 |
 | `velocityScale` | `number` | `900` | 风速到粒子位移的缩放系数。数值越大粒子移动越快。 |
 | `lineWidth` | `number` | `0.85` | 粒子轨迹基础线宽。 |
-| `color` | `string` | `rgba(230, 248, 255, 0.52)` | 粒子单色兜底颜色。传了 `particleColorScale` 时优先按风速分级着色。 |
+| `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`。 |
@@ -3670,70 +4371,6 @@ const windData = {
 | `bounds` | 风场数据范围 `{ west, south, east, north }`。 |
 | `center` | 风场中心 `{ lon, lat }`。 |
 
-## 在 Vue 中封装 Hook
-
-推荐页面用 hook 管理生命周期，组件只处理 UI。
-
-```js
-import { onBeforeUnmount, onMounted, shallowRef } from 'vue'
-import { BaseGIS } from '@3clear/basegis'
-
-export function useBaseGIS(options = {}) {
-  const mapCore = shallowRef(null)
-
-  onMounted(() => {
-    mapCore.value = new BaseGIS(options)
-    mapCore.value.init()
-  })
-
-  onBeforeUnmount(() => {
-    mapCore.value?.destroy()
-    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,
-  }
-}
-```
-
-使用：
-
-```vue
-<template>
-  <div id="map" class="map"></div>
-</template>
-
-<script setup>
-import { useBaseGIS } from './useBaseGIS'
-
-const { mapCore, setEngine } = useBaseGIS({
-  engineType: 'cesium',
-  containerId: 'map',
-})
-</script>
-```
-
-BaseGIS 托管图层会自动恢复，页面不需要重新请求数据：
-
-```js
-const result = await setEngine('leaflet')
-console.log(result.data?.restore)
-```
-
-只有 GPU 专用风场、剖面、一次性绘制对象或页面直接创建的底层引擎对象需要在切换成功后自行恢复。
-
 ## 能力支持说明
 
 | 能力 | Cesium | Leaflet |
@@ -3741,20 +4378,29 @@ console.log(result.data?.restore)
 | 2D 地图 | 支持 | 支持 |
 | 2.5D / 3D 场景 | 支持 | 不支持 |
 | 放大、缩小、重置 | 支持 | 支持 |
+| 多地图视角联动 | 支持 | 支持 |
+| 地图截图与 PNG 导出 | 支持 | 支持 |
 | 底图切换 | 支持 | 支持 |
 | 点线面文字 | 支持 | 支持 |
+| Canvas 数据图标与扩散 Marker | 支持 | 支持 |
+| GeoJSON 图层 | 支持 | 支持 |
 | 独立线、虚线、渐变与沿线动画 | 支持 | 支持 |
+| 逐顶点色与路线时间裁剪 | 支持 | 支持 |
+| 台风路径与播放 | 支持 | 支持 |
 | 图片覆盖层 | 支持 | 支持 |
 | 网格 / TIF | 支持 | 支持 |
 | 海量点 | 支持 | 支持 |
 | 点位聚合 | 支持 | 支持 |
 | 点位密度抽稀 | 支持 | 支持 |
 | 等值线 | 支持 | 支持 |
-| 等压线标注 | 支持 | 支持 |
-| 风场 Canvas 动画 | 支持 | 支持 |
-| 三维体渲染 | 支持 | 不支持 |
+| 等值线标签与 H/L 中心标注 | 支持 | 支持 |
+| 统一风场 `upsertWindLayer` | GPU | Canvas |
+| 独立 Canvas 风场 `WindFieldMethods` | 支持 | 支持 |
+| GPU 专用风场 `upsertGpuWindLayer` | 支持 | 不支持 |
+| 源解析弧线、灰色烟羽点云与目标汇聚体 | 支持 | 不支持 |
+| 三维体渲染、更新与取值 | 支持 | 不支持 |
 | 三维切片 / 剖面渲染 | 支持 | 不支持 |
-| DEM 地形 | 支持 | 不支持 |
+| DEM 地形与夸张 | 支持 | 不支持 |
 
 ## 第三方许可
 
@@ -3786,14 +4432,14 @@ SOFTWARE.
 
 ## 本地开发与打包
 
-在仓库根目录执行：
+包源码来自仓库 `src/gis`；`packages/basegis` 负责构建与发布配置。安装仓库依赖后，在仓库根目录执行：
 
 ```bash
 npm run build:basegis
 npm run pack:basegis
 ```
 
-`build:basegis` 会生成：
+`build:basegis` 生成以下入口，以及它们依赖的共享、异步代码块：
 
 ```text
 packages/basegis/dist/basegis.js
@@ -3803,23 +4449,25 @@ packages/basegis/dist/assets.js
 packages/basegis/dist/style.css
 ```
 
-`pack:basegis` 会在仓库根目录生成类似文件：
+分发时必须保留完整 `packages/basegis/dist`，不能只复制上述入口文件。`pack:basegis` 不会自动构建，修改源码后应先执行 `build:basegis`。
+
+当前包版本为 `0.1.4`，`pack:basegis` 会在仓库根目录生成以下文件；后续以 `packages/basegis/package.json` 中的版本及实际输出为准：
 
 ```text
-3clear-basegis-0.1.0.tgz
+3clear-basegis-0.1.4.tgz
 ```
 
 其他项目本地安装：
 
 ```bash
-npm install ./3clear-basegis-0.1.0.tgz
+npm install ./3clear-basegis-0.1.4.tgz
 ```
 
 ## 发布到 npm
 
 只发布 `packages/basegis`，不要在项目根目录执行 `npm publish`，否则会把整个业务项目上传到 npm。
 
-发布前检查包内容：
+更新包版本并重新构建后，先检查包内容：
 
 ```bash
 npm pack --dry-run ./packages/basegis
@@ -3831,38 +4479,13 @@ npm pack --dry-run ./packages/basegis
 npm publish ./packages/basegis --access public
 ```
 
-如果只希望私有发布，保留 `packages/basegis/package.json` 中的：
-
-```json
-{
-  "publishConfig": {
-    "access": "restricted"
-  }
-}
-```
-
-如果希望公开发布，需要改为：
-
-```json
-{
-  "publishConfig": {
-    "access": "public"
-  }
-}
-```
+包已配置 `publishConfig.access: 'public'`，发布内容为完整 `dist`、README 和 npm 自动附带的包元信息，不包含测试页面、mock 数据和 Cesium 静态资源。
 
 ## 常见问题
 
 ### Cesium 地图不显示
 
-检查宿主项目是否存在：
-
-```text
-public/lib/Cesium/Cesium.js
-public/lib/Cesium/Widgets/widgets.css
-```
-
-并确认页面初始化前能访问 `window.Cesium`。
+按[安装](#安装)章节加载 Cesium 脚本、样式及完整静态资源，确认初始化前存在 `window.Cesium`，并确保地图容器有实际宽高。部署在子路径时还要检查 `CESIUM_BASE_URL`。
 
 ### Leaflet 样式异常
 
@@ -3883,18 +4506,19 @@ console.log(result.success, result.message)
 
 ### 切换配置后地图没有变化
 
-`setConfig()` 只更新 `BaseGIS` 内部配置，不会自动重建地图。需要销毁后重新初始化：
+`setConfig()` 只更新内部配置，需要再次 `init()` 才会重建地图。不要先手动 `destroy()`，以免清空托管图层快照：
 
 ```js
 mapCore.setConfig(nextConfig)
-mapCore.init()
+const result = mapCore.init()
+if (result.success) await mapCore.whenReady()
 ```
 
 `init()` 内部会先销毁旧适配器，再创建新实例。
 
 ### 切换引擎后图层没了
 
-直接使用 `setEngine()`。BaseGIS 会保留视野，并自动恢复图片、网格、海量点、点位聚合、点位抽稀、独立线、等值线、统一风场和三维体等托管图层：
+先确认通过 `setEngine()` 切换且没有提前 `destroy()`，再查看恢复结果：
 
 ```js
 const result = await mapCore.setEngine('leaflet')
@@ -3903,4 +4527,4 @@ console.log(result.data?.restore?.restored)
 console.log(result.data?.restore?.failed)
 ```
 
-如果丢失的是 `drawPoint/drawLine/drawPolygon/drawText/addMarker`、点击监听、GPU 专用风场、剖面图层或页面直接创建的 Cesium / Leaflet 对象，它们不属于托管图层，需要业务在切换成功后自行恢复。
+自动恢复与手动恢复范围见[切换后的图层处理](#managed-layer-restore)。GeoJSON、基础绘制、独立 Canvas/GPU 风场、剖面和页面监听需重新加载或绑定；使用多地图联动时还需调用 `viewLinks.refreshMap(id)`。