@3clear/basegis 0.1.4 → 0.1.6

package/README.md

@@ -1,195 +1,394 @@
 # @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 示例资源。
-- `style.css`：Leaflet、GIS 图层和标注相关基础样式。
+- `assets`：站点、工厂、信息标记和台风中心 SVG 资源。
+- `style.css`：BaseGIS 自有图层、标注和截图框选样式，不内嵌 Leaflet 官方 CSS。
 
 ## 能力总览
 
 以下按类型展示 `@3clear/basegis` 的主要业务能力；工具型辅助函数不单独作为能力卡展示。点击名称可跳转到下方详细说明，完整导入方式见[出口](#出口)。
 
-### Core 核心（1）
+### 快速开始
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#base-gis-lifecycle"><strong>初始化与生命周期</strong></a></small></td>
       <td>
-        <a href="#base-gis"><strong>BaseGIS</strong></a><br>
-        <small>Cesium / Leaflet 统一 GIS 主入口 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+        <small>创建并初始化 BaseGIS 实例，管理实例状态、尺寸刷新和资源销毁。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#map-init-config"><strong>地图初始化配置</strong></a></small></td>
+      <td>
+        <small>说明构造参数、init() 参数优先级、完整配置分组，以及 setConfig() 的用法与生效规则。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#engine-switch"><strong>切换引擎</strong></a></small></td>
+      <td>
+        <small>支持 Cesium / Leaflet 运行时切换，并保留当前视野、恢复托管图层。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#view-control-scene"><strong>视角控制与场景模式</strong></a></small></td>
+      <td>
+        <small>支持视角缩放、重置、范围适配，以及 2D、2.5D、3D 场景模式切换。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#map-view-listener"><strong>地图视角监听</strong></a></small></td>
+      <td>
+        <small>监听地图移动、缩放和视角变化的开始、过程与结束状态。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-36" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#map-click-events"><strong>点击事件</strong></a></small></td>
+      <td>
+        <small>统一监听 Cesium / Leaflet 地图点击，返回坐标及命中目标信息。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Graphics 图形与点位（4）
+### 地图工具（2）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
-      <td width="50%">
-        <a href="#graphic-group-controller"><strong>GraphicGroupController</strong></a><br>
-        <small>点、线、面、文字与 Marker 图形组 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
-      </td>
-      <td width="50%">
-        <a href="#point-large-layer-controller"><strong>PointLargeLayerController</strong></a><br>
-        <small>海量点 · <a href="http://61.50.111.214:31166/lgmap/test-page-5" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#map-screenshot"><strong>地图截图导出</strong></a></small></td>
+      <td>
+        <small>支持当前视口、框选区域及指定范围截图，并导出 PNG 图片。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-40" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
     <tr>
-      <td width="50%">
-        <a href="#point-cluster-controller"><strong>PointClusterController</strong></a><br>
-        <small>点位聚合 · <a href="http://61.50.111.214:31166/lgmap/test-page-29" target="_blank" rel="noopener noreferrer">查看示例</a></small>
-      </td>
-      <td width="50%">
-        <a href="#point-density-controller"><strong>PointDensityController</strong></a><br>
-        <small>点位视野裁剪抽稀 · <a href="http://61.50.111.214:31166/lgmap/test-page-8" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#map-view-link-controller"><strong>多地图联动</strong></a></small></td>
+      <td>
+        <small>支持多地图实例注册，以及移动、缩放和视角实时联动。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-36" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Line 线图层（1）
+### 通用点位图层（5）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#basic-graphics"><strong>基础图形与点位</strong></a></small></td>
       <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>绘制点、线、面、文字和 Marker，支持 Cesium / Leaflet。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#point-large-layer-controller"><strong>海量点</strong></a></small></td>
+      <td>
+        <small>使用批量渲染展示大规模点位数据。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-5" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#point-cluster-controller"><strong>点位聚合</strong></a></small></td>
+      <td>
+        <small>根据地图视图和缩放层级对邻近点位进行聚合展示。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-29" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#point-density-controller"><strong>点位抽稀</strong></a></small></td>
+      <td>
+        <small>根据当前视野裁剪点位，并按屏幕密度进行抽稀展示。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-8" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#marker-icons"><strong>图标</strong></a></small></td>
+      <td>
+        <small>提供项目常用图标及告警扩散效果图标。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-41" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Image 图片图层（1）
+### 行政区划边界图层（1）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#geojson-layer"><strong>GeoJSON 图层</strong></a></small></td>
       <td>
-        <a href="#image-layer-controller"><strong>ImageLayerController</strong></a><br>
-        <small>图片覆盖层与时次切换 · <a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>支持：PNG / JPG / WebP 等浏览器图片、灰度图；可配套 GeoTIFF 取值</small>
+        <small>支持 GeoJSON 点、线、面、行政区划边界，以及数据驱动的边线、填充和点样式。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-23" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Grid 数值网格（1）
+### 轨迹路径图层（2）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#line-layer-controller"><strong>走航路径</strong></a></small></td>
+      <td>
+        <small>轨迹折线、逐顶点浓度着色、时间裁剪与沿线动画；底层支持实线/虚线、固定/流动渐变和图标引领的逐步出线。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-43" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#typhoon-path-controller"><strong>台风路径</strong></a></small></td>
       <td>
-        <a href="#grid-layer-controller"><strong>GridLayerController</strong></a><br>
-        <small>栅格数值注记与鼠标探针 · <a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>支持：GeoTIFF、灰度图、直接数值网格</small>
+        <small>实况路径、强度节点、当前中心、四象限风圈、多机构预报与路径播放；支持 Cesium / Leaflet 同一份规范化台风数据与引擎切换恢复。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-10" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Contour 通用等值线与中心标注（2）
+### 格点填色图层（2）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
-      <td width="50%">
-        <a href="#contour-layer-controller"><strong>ContourLayerController</strong></a><br>
-        <small>已有等值线、线值标签与中心标注 · <a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#image-layer-controller"><strong>图片填色图层</strong></a></small></td>
+      <td>
+        <small>支持 PNG / JPG / WebP 等图片覆盖、灰度图及时次切换，可配套 GeoTIFF 取值。</small>
       </td>
-      <td width="50%">
-        <a href="#raster-contour-controller"><strong>RasterContourController</strong></a><br>
-        <small>从栅格追线，可选自动检测 H/L 中心 · <a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#grid-layer-controller"><strong>网格数值图层</strong></a></small></td>
+      <td>
+        <small>支持 GeoTIFF、灰度图和直接数值网格的数值注记与鼠标探针。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Volume 三维体渲染（1）
+### 等值线图层（2）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#contour-layer-controller"><strong>通用等值线</strong></a></small></td>
       <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>已有等值线数据，支持线平滑、线值标签、中心标注与标注避让。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-19" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#raster-contour-controller"><strong>栅格等值线</strong></a></small></td>
+      <td>
+        <small>没有等值线数据，需要前端通过格点数据自动生成等值线，支持线平滑、标注避让，可选自动检测 H/L 中心。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Section 三维切片 / 剖面（1）
+### 三维渲染（不支持2维）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#dem-terrain"><strong>DEM 地形</strong></a></small></td>
+      <td>
+        <small>Cesium 专用，支持椭球地形、World Terrain 与地形夸张。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#source-transport"><strong>源解析传输</strong></a></small></td>
+      <td>
+        <small>展示贡献弧线、灰色烟羽点云、移动烟团与目标汇聚体，体云复用现有体渲染。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-42" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#volume-rendering"><strong>盒子体渲染</strong></a></small></td>
       <td>
-        <a href="#section-rendering"><strong>BaseGIS.upsertSectionLayer</strong></a><br>
-        <small>Cesium 专有；按经度、纬度、高度/气压层切片 · <a href="http://61.50.111.214:31166/lgmap/test-page-15" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>支持：{ Bound, DataAry } 三维格点数据</small>
+        <small>对三维标量场进行体积采样与裁切，支持原位更新体数据及按屏幕位置取值。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-14" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#section-rendering"><strong>切片/剖面渲染</strong></a></small></td>
+      <td>
+        <small>基于三维格点数据，按经度、纬度或气压层渲染切片与剖面。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-15" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Wind 风场（1）
+### 风场图层（2）
 
-<table>
+<p><small>推荐使用 <a href="#unified-wind-layer"><code>BaseGIS.upsertWindLayer</code></a> 统一入口：Cesium 自动使用 GPU，Leaflet 自动使用 Canvas，切换引擎时自动恢复风场。</small></p>
+
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#gpu-wind-layer"><strong>GPU 风场</strong></a></small></td>
+      <td>
+        <small>Cesium 专用，使用 GPU 绘制风场粒子，支持地形采样。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-21" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#wind-field-methods"><strong>Canvas 风场</strong></a></small></td>
       <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>
+        <small>通过 Canvas 在 Cesium / Leaflet 上绘制风场粒子，支持风速底图。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Layers 图层构造器（4）
+### 影像瓦片图层（4）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
-      <td width="50%">
-        <a href="#layer-config-builders"><strong>createTiandituLayer</strong></a><br>
-        <small>天地图图层配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#layer-config-builders"><strong>天地图图层</strong></a></small></td>
+      <td>
+        <small>生成天地图矢量、影像、地形及注记图层配置。</small>
       </td>
-      <td width="50%">
-        <a href="#layer-config-builders"><strong>createGeoserverPyramidLayer</strong></a><br>
-        <small>GeoServer 金字塔瓦片配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#layer-config-builders"><strong>GeoServer 金字塔瓦片</strong></a></small></td>
+      <td>
+        <small>生成 GeoServer 金字塔瓦片图层配置，支持标准瓦片地址模板。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
     <tr>
-      <td width="50%">
-        <a href="#layer-config-builders"><strong>createWmsLayer</strong></a><br>
-        <small>WMS 图层配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#layer-config-builders"><strong>WMS 图层</strong></a></small></td>
+      <td>
+        <small>生成 WMS 服务图层配置，支持图层名称及附加请求参数。</small>
       </td>
-      <td width="50%">
-        <a href="#layer-config-builders"><strong>createWmtsLayer</strong></a><br>
-        <small>WMTS 图层配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#layer-config-builders"><strong>WMTS 图层</strong></a></small></td>
+      <td>
+        <small>生成 WMTS 标准瓦片图层配置，可指定 Cesium / Leaflet 引擎支持范围。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Assets 示例资源（1）
+### 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,16 +399,43 @@
 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 截图时按需加载。
+
+在应用入口引入 BaseGIS 与自有样式：
+
+```js
+import { BaseGIS } from '@3clear/basegis'
+import '@3clear/basegis/style.css'
+```
+
+外部依赖版本以 `package.json` 为准：当前为 `leaflet ^1.9.4`、`axios ^1.15.1`。
+
+当前限制：完整 BaseGIS 入口中的剖面工具仍在模块加载时访问 `Cesium.Cartesian3`，因此即使只创建 Leaflet 地图，也需在导入 BaseGIS 前加载下文的 Cesium 脚本，否则会报 `Cesium is not defined`。这是既有的引擎依赖问题，与本次 Leaflet CSS 共用处理无关；纯原生 Leaflet 不受此限制。
 
-使用样式：
+Leaflet JS 和 `leaflet/dist/leaflet.css` 都由宿主依赖提供。BaseGIS 保留对官方 CSS 的导入，因此上面的原有用法仍然有效；官方规则不再另行内嵌到包的 `style.css` 中。
+
+如果项目同时使用原生 Leaflet，可以在应用入口统一引入：
 
 ```js
+import L from 'leaflet'
+import 'leaflet/dist/leaflet.css'
+import { BaseGIS } from '@3clear/basegis'
 import '@3clear/basegis/style.css'
 ```
 
-Cesium 当前不随 npm 包发布，项目需要按原项目方式把 Cesium 静态资源放到 `public/lib/Cesium`，并保证初始化前能访问 `window.Cesium`。
-如果需要加载 GeoTIFF 网格，需要项目提前提供 `window.GeoTIFF`。
+确保 BaseGIS 与业务代码解析到同一份安装的 Leaflet，宿主构建器即可复用同路径的 JS / CSS。不同地图使用各自容器；不需要挂载 `window.L` 或注册 Vue 插件，其他模块需要使用 `L` / `BaseGIS` 时仍按需 import。纯原生页面若不导入 BaseGIS JS，必须自行引入 `leaflet/dist/leaflet.css`，仅引入包的 `style.css` 不包含官方规则。
+
+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 +445,9 @@ import { BaseGIS } from '@3clear/basegis'
 
 // 高级能力控制器
 import {
-  GraphicGroupController,
   LineLayerController,
+  MapViewLinkController,
+  TyphoonPathController,
   ImageLayerController,
   toImageLayerArea,
   GridLayerController,
@@ -235,13 +462,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'
 ```
 
 ## 快速开始
@@ -280,8 +513,6 @@ onMounted(() => {
       basemap: {
         // 默认内置值：tianditu-imagery。
         defaultVisibleId: 'tianditu-imagery',
-        // 默认内置值：tianditu-vector-label。
-        defaultAnnotationId: 'tianditu-vector-label',
       },
     },
   })
@@ -297,17 +528,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,16 +558,326 @@ onBeforeUnmount(() => {
   message: 'error message',
   code: 'NOT_INITIALIZED'
 }
+```
+
+`getEngineType()`、`getConfig()`、`getMapInstance()` 等读取方法直接返回值；`createMarkerIcon()` 直接返回图标参数或 `null`。控制器的 `getState()` 也返回状态对象，不能一律按 `result.data` 读取。
+
+<a id="map-init-config"></a>
+
+## 地图初始化与运行时配置
+
+`BaseGIS` 的初始化参数分为两类：需要长期保留的默认配置放在构造函数的 `config` 中；只想覆盖本次初始化时，传给 `init(options)`。地图已经创建后，`setConfig()` 只更新实例保存的配置，不会直接改变当前画面；初始化默认值通常需要重新 `init()` 才会生效。
+
+| 配置入口 | 适用场景 | 是否写入运行时配置 | 是否立即重建地图 |
+| --- | --- | --- | --- |
+| `new BaseGIS({ ... })` | 创建实例并设置默认引擎、容器和整套配置。 | 是 | 否，仍需调用 `init()`。 |
+| `init(options)` | 创建或重新创建地图，并单次覆盖容器、引擎、场景模式或初始视角。 | `engineType` 会写入；`sceneMode / initialView` 不写入。 | 是 |
+| `setConfig(config)` | 修改实例保存的配置，供后续初始化或配置查询使用。 | 是 | 否 |
+
+### 构造参数
+
+```js
+const mapCore = new BaseGIS({
+  engineType: 'cesium',
+  containerId: 'map',
+  config: {
+    view: {
+      defaultSceneMode: '3d',
+      initialView: {
+        center: [104, 35],
+        height: 5000000,
+        zoom: 5,
+        heading: 0,
+        pitch: -90,
+        roll: 0,
+      },
+    },
+  },
+})
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `engineType` | `'cesium' \| 'leaflet'` | `config.engine.active`，内置为 `cesium` | 默认引擎。该参数最终覆盖 `config.engine.active`。 |
+| `container` | `HTMLElement \| string` | - | 地图容器 DOM，也兼容传容器 id 字符串。 |
+| `containerId` | `string` | - | 地图容器 id。与 `container` 二选一即可。 |
+| `config` | `Object` | 内置配置 | 推荐的配置入口，与内置配置做深合并。 |
+| `engine / view / basemap / dem / sourceTransport` | `Object` | - | 兼容直接写在构造参数顶层；推荐统一放入 `config`，避免与控制参数混淆。同名配置同时出现时，`config` 中的值优先。 |
+
+### `init(options)` 参数与优先级
+
+```js
+const result = mapCore.init({
+  // 都是选填；构造时已经设置过的内容不需要重复传。
+  containerId: 'map',
+  engineType: 'cesium',
+  sceneMode: '3d',
+  initialView: {
+    center: [104, 35],
+    height: 5000000,
+    zoom: 5,
+    pitch: -90,
+  },
+})
+
+if (!result.success) {
+  console.warn(result.message)
+}
+```
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `container` | `HTMLElement \| string` | 本次使用的容器 DOM 或容器 id，优先级最高。 |
+| `containerId` | `string` | 本次使用的容器 id。 |
+| `engineType` | `'cesium' \| 'leaflet'` | 本次使用的引擎，同时更新实例保存的 `engine.active`。 |
+| `sceneMode` | `'2d' \| '2.5d' \| '3d'` | 本次初始化的场景模式；Leaflet 只支持 `2d`。不会写回 `config.view.defaultSceneMode`。 |
+| `initialView` | `Object` | 本次初始化的视角。不会写回 `config.view.initialView`。 |
+
+`init({ config: ... })` 不是有效写法；`init()` 不会合并 `config`。持久配置必须在构造函数中传入，或先调用 `setConfig()`。
+
+各参数的实际取值顺序如下，左侧优先级更高：
 
+| 项目 | 取值优先级 |
+| --- | --- |
+| 容器 | `init.container` → `init.containerId` → 构造函数 `container` → 构造函数 `containerId` |
+| 引擎 | `init.engineType` → 实例当前引擎（由构造函数 `engineType` 或 `config.engine.active` 得到）→ `cesium` |
+| 场景模式 | Cesium：`init.sceneMode` → `config.view.defaultSceneMode` → `3d`；Leaflet 始终为 `2d` |
+| 初始视角 | `init.initialView` → `config.view.initialView` → 引擎内置安全视角 |
+
+重复调用 `init()` 时会先销毁旧 adapter，再创建新地图；BaseGIS 托管图层会异步恢复。`init()` 本身同步返回初始化结果，后续逻辑依赖图层恢复时还需等待：
+
+```js
+const result = mapCore.init()
+if (result.success) {
+  const restore = await mapCore.whenReady()
+  console.log(restore.restored, restore.failed)
+}
 ```
 
-说明：
+### 完整配置分组
+
+`config` 当前只有以下五个顶层分组。页面不要直接依赖包内部的 `src/gis/config` 文件；需要查看当前实例最终合并后的配置时，使用 `mapCore.getConfig()`。
+
+| 配置组 | 用途 | 主要生效时机 |
+| --- | --- | --- |
+| `engine` | 默认引擎、引擎接入元数据及 Cesium 渲染质量。 | `init()` / 重新 `init()` |
+| `view` | 默认场景模式和初始视角。 | `init()` / 重新 `init()` |
+| `basemap` | 初始底图、可切换底图列表及内置服务元数据。 | `init()`；列表也供 `setBasemapById()` 查询 |
+| `dem` | Cesium 默认地形及可切换地形列表。 | Cesium `init()`；列表也供 `loadDEMById()` 查询 |
+| `sourceTransport` | 源解析传输图层的实例级默认视觉参数。 | 创建 adapter 时锁定；`setConfig()` 后需重新 `init()`，新 adapter 创建图层时才会读取 |
+
+#### `engine` 引擎配置
+
+| 配置项 | 内置默认值 | 说明 |
+| --- | --- | --- |
+| `engine.active` | `'cesium'` | 默认引擎；构造参数 `engineType` 或 `init({ engineType })` 的优先级更高。 |
+| `engine.cesium.sourceType` | `'local-script'` | Cesium 接入方式说明字段。 |
+| `engine.cesium.scriptUrl` | `'/lib/Cesium/Cesium.js'` | Cesium 脚本地址说明字段；BaseGIS 不会自动加载该脚本。 |
+| `engine.cesium.cssUrl` | `'/lib/Cesium/Widgets/widgets.css'` | Cesium 样式地址说明字段；BaseGIS 不会自动加载该样式。 |
+| `engine.cesium.renderQuality.maximumDevicePixelRatio` | `2` | Cesium 最大设备像素比，实际值限制在 `1～3`；越高越清晰，也越耗 GPU。 |
+| `engine.cesium.renderQuality.fxaa` | `true` | 是否启用 Cesium FXAA。 |
+| `engine.cesium.renderQuality.msaaSamples` | `4` | Cesium MSAA 采样数，取整并限制在 `1～8`。 |
+| `engine.leaflet.sourceType` | `'npm'` | Leaflet 接入方式说明字段。 |
+| `engine.leaflet.packageName` | `'leaflet'` | Leaflet 依赖包名说明字段。 |
+
+`scriptUrl / cssUrl` 只是接入元数据。Cesium 资源的实际加载方法见[安装](#安装)。渲染质量在创建 Cesium Viewer 时读取，修改后需要重新 `init()`。
+
+#### `view` 视角配置
+
+| 配置项 | 内置默认值 | Cesium | Leaflet | 说明 |
+| --- | --- | --- | --- | --- |
+| `view.defaultSceneMode` | `'3d'` | 使用 | 只接受 `2d` | 默认场景，可选 `2d / 2.5d / 3d`。 |
+| `view.initialView.center` | `[121.4737, 31.2304]` | 使用 | 使用 | `[经度, 纬度]`。 |
+| `view.initialView.height` | `1800000` | 使用 | 忽略 | Cesium 相机高度，单位米。 |
+| `view.initialView.zoom` | `7` | 忽略 | 使用 | Leaflet 缩放级别。 |
+| `view.initialView.heading` | `0` | 使用 | 忽略 | Cesium 航向角，单位度。 |
+| `view.initialView.pitch` | `-90` | 使用 | 忽略 | Cesium 俯仰角，单位度；`-90` 表示垂直俯视。 |
+| `view.initialView.roll` | `0` | 使用 | 忽略 | Cesium 翻滚角，单位度。 |
+
+#### `basemap` 底图配置
+
+| 配置项 | 内置默认值 | 说明 |
+| --- | --- | --- |
+| `basemap.defaultVisibleId` | `'tianditu-imagery'` | 初始化时从 `basemap.list` 选择的底图 id。 |
+| `basemap.defaultAnnotationId` | `'tianditu-vector-label'` | 当前为保留字段，初始化流程尚未读取；注记应通过所选底图项的 `annotationResourceKey` 配置，天地图也会按底图资源自动推断注记。 |
+| `basemap.list` | 内置天地图、WMS、WMTS 示例列表 | 底图资源数组；完整默认项和字段见下方[默认底图配置](#default-basemap-config)。外部传入数组会整体替换内置数组。 |
+| `basemap.providers` | 内置天地图 provider | 内置服务的地址、子域名、token 池及资源映射。当前适配器读取包内 provider，构造参数或 `setConfig()` 中的覆盖值尚不会生效；自定义服务请在 `basemap.list` 中配置 URL。 |
+
+#### `dem` 地形配置
+
+| 配置项 | 内置默认值 | 说明 |
+| --- | --- | --- |
+| `dem.defaultEnabled` | `true` | Cesium 初始化时是否加载默认 DEM；`false` 时跳过。 |
+| `dem.defaultVisibleId` | `'ellipsoid-flat'` | 默认 DEM id，必须能在 `dem.list` 中找到、`visible !== false` 且支持 Cesium，否则初始化失败。 |
+| `dem.list` | 平面地形、Cesium World Terrain、天地图 DEM 占位项 | DEM 资源数组；外部传入时整体替换。列表项常用字段为 `id / name / sourceType / factory / url / visible / engineSupport / options`，详细用法见[DEM 地形](#dem-terrain)。 |
+
+Leaflet 不加载 DEM。`cesium-world-terrain` 需要 Cesium Ion 能力；`tianditu-dem` 是待补真实服务地址的占位项。
+
+#### 常用地图初始化配置示例
+
+下面示例把真正参与地图创建的常用配置集中写在一起。未传的字段继续使用上表中的内置默认值：
+
+```js
+const mapCore = new BaseGIS({
+  containerId: 'map',
+  config: {
+    engine: {
+      active: 'cesium',
+      cesium: {
+        renderQuality: {
+          maximumDevicePixelRatio: 2,
+          fxaa: true,
+          msaaSamples: 4,
+        },
+      },
+    },
+    view: {
+      defaultSceneMode: '3d',
+      initialView: {
+        center: [104, 35],
+        height: 5000000,
+        zoom: 5,
+        heading: 0,
+        pitch: -90,
+        roll: 0,
+      },
+    },
+    basemap: {
+      defaultVisibleId: 'tianditu-imagery',
+    },
+    dem: {
+      defaultEnabled: true,
+      defaultVisibleId: 'ellipsoid-flat',
+    },
+  },
+})
+
+const result = mapCore.init()
+if (!result.success) {
+  console.warn(result.message)
+}
+```
+
+#### `sourceTransport` 源解析传输默认配置
 
-- `containerId` 和 `container` 二选一即可；`init()` 时也可以再次传入。
-- 页面传入的 `config` 会覆盖内置默认配置。
-- `basemap.list` 和 `dem.list` 是数组，外部传入时会整体覆盖内置列表；如果要使用内置默认底图，不要传空数组覆盖。
-- Cesium 默认视角 `pitch: -90`，表示垂直俯视。
-- `BaseGIS` 只保存运行时配置，调用 `setConfig()` 不会自动重建地图，需要重新 `init()` 才会创建新地图实例。
+这一组不是地图容器或相机初始化参数，而是 Cesium [源解析传输](#source-transport)图层的实例级默认值。
+
+| 配置项 | 内置默认值 | 说明 |
+| --- | --- | --- |
+| `sourceTransport.visible` | `true` | 新建图层默认是否显示。 |
+| `sourceTransport.running` | `true` | 新建图层默认是否播放烟羽动画。 |
+| `sourceTransport.colors` | 内置 7 色数组 | 多来源默认色板。 |
+| `sourceTransport.path` | 内置对象 | 弧线路径分段、高度与弯曲参数。 |
+| `sourceTransport.line` | 内置对象 | 线宽、透明度、辉光、收尖和命中宽度。 |
+| `sourceTransport.smoke` | 内置对象 | 烟羽数量、大小、透明度、扩散和速度。 |
+| `sourceTransport.sourceNode` | 内置对象 | 来源节点大小与标签数量。 |
+| `sourceTransport.targetNode` | 内置对象 | 目标节点颜色与环半径。 |
+| `sourceTransport.volume` | 内置对象 | 目标体云开关、网格尺寸、渲染参数及色带。 |
+| `sourceTransport.interaction` | 内置对象 | 交互开关、命中容差和鼠标样式。 |
+| `sourceTransport.fog` | 内置对象 | 雾效开关与密度。 |
+| `sourceTransport.camera` | 内置对象 | 定位图层时的俯仰角、高度和动画时长。 |
+
+单个图层传入的同名参数优先于这里的实例默认值。
+
+### 配置合并规则
+
+构造函数和 `setConfig()` 使用同一套合并规则：
+
+| 数据类型 | 合并方式 |
+| --- | --- |
+| 普通对象 | 按层级递归合并，只传一个叶子字段不会删除同组其他字段。 |
+| 数组 | 整体替换，不会追加；`basemap.list`、`dem.list`、`sourceTransport.colors` 都遵循此规则。 |
+| 基本类型、函数及其他值 | 使用新值替换旧值。 |
+| 未传字段 | 保留当前配置中的值。 |
+
+配置会被克隆后保存，不会直接修改包内默认配置。`getConfig()` 返回当前实例持有的配置对象引用，建议只读；修改配置统一调用 `setConfig()`。
+
+例如，只覆盖 Cesium 像素比不会丢失 `fxaa` 和 `msaaSamples`：
+
+```js
+mapCore.setConfig({
+  engine: {
+    cesium: {
+      renderQuality: {
+        maximumDevicePixelRatio: 1.5,
+      },
+    },
+  },
+})
+```
+
+如果要在现有底图列表后追加一项，必须自行保留原数组：
+
+```js
+const currentConfig = mapCore.getConfig()
+
+mapCore.setConfig({
+  basemap: {
+    list: [
+      ...currentConfig.basemap.list,
+      {
+        id: 'custom-xyz',
+        name: '自定义 XYZ',
+        category: 'basemap',
+        type: 'xyz',
+        provider: 'custom',
+        url: 'https://example.com/tiles/{z}/{x}/{y}.png',
+        engineSupport: ['cesium', 'leaflet'],
+      },
+    ],
+  },
+})
+```
+
+### `setConfig()` 怎么用
+
+`setConfig(overrideConfig)` 是同步方法，不校验配置，也没有统一结果对象或其他返回值。它只更新 `BaseGIS` 实例保存的配置，不会把新配置推送给已经创建的 adapter，也不会自动改变当前场景、视角、底图、DEM 或渲染质量。`engine.active` 是一个需要特别注意的例外：它会同步实例记录的引擎类型，但不会真正替换当前底层地图。
+
+需要让整套初始化配置生效时，直接再次 `init()`，不要先调用 `destroy()`；否则托管图层快照会被清空：
+
+```js
+mapCore.setConfig({
+  engine: {
+    cesium: {
+      renderQuality: {
+        maximumDevicePixelRatio: 1.5,
+        fxaa: true,
+        msaaSamples: 4,
+      },
+    },
+  },
+  view: {
+    defaultSceneMode: '2d',
+    initialView: {
+      center: [116.4, 39.9],
+      height: 1800000,
+      zoom: 7,
+      pitch: -90,
+    },
+  },
+})
+
+const result = mapCore.init()
+if (result.success) {
+  await mapCore.whenReady()
+}
+```
+
+如果目标只是立即操作当前地图，不要用 `setConfig() + init()` 代替已有的实时 API：
+
+| 目标 | 推荐 API | 是否重建地图 |
+| --- | --- | --- |
+| 切换 Cesium / Leaflet | `await mapCore.setEngine(engineType)` | 是，并自动恢复托管图层 |
+| 切换当前场景模式 | `mapCore.setSceneMode({ mode })` | 否 |
+| 移动当前视角 | `mapCore.setInitialView(view)` | 否 |
+| 切换当前底图 | `mapCore.setBasemapById(id)` 或 `mapCore.setBasemap(payload)` | 否 |
+| 切换当前 DEM | `mapCore.loadDEMById(id)`、`mapCore.loadDefaultDEM()` 或 `mapCore.loadDEM(payload)` | 否 |
+| 修改当前或新建源解析传输层 | `mapCore.updateSourceTransportLayer(payload)` 或 `mapCore.upsertSourceTransportLayer(payload)` | 否 |
+| 修改 Cesium 渲染质量或整套初始化默认值 | `setConfig()` 后重新 `init()` | 是 |
+
+特别注意：不要用 `setConfig({ engine: { active: 'leaflet' } })` 切换已经显示的地图；应直接调用 `setEngine('leaflet')`。前者会让 `getEngineType()` 变成 `leaflet`，但底层仍可能是 Cesium，随后调用相同目标的 `setEngine('leaflet')` 还会被当作“已经是当前引擎”而跳过。若已经这样修改，应调用 `init()` 重建并校正地图实例。
+
+<a id="default-basemap-config"></a>
 
 ### 默认底图配置
 
@@ -343,6 +886,7 @@ onBeforeUnmount(() => {
 ```js
 basemap: {
   defaultVisibleId: 'tianditu-imagery',
+  // 当前为保留字段，初始化时不会读取。
   defaultAnnotationId: 'tianditu-vector-label',
 }
 ```
@@ -354,29 +898,19 @@ basemap: {
 | `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`
+| `tianditu-vector-label` | 天地图矢量注记 | `annotation` | `true` | `wmts` | `tianditu` | `vectorLabel` | 可作为底图的 `annotationResourceKey` | Cesium / Leaflet |
+| `tianditu-terrain-label` | 天地图地形注记 | `annotation` | `true` | `wmts` | `tianditu` | `terrainLabel` | 可作为底图的 `annotationResourceKey` | Cesium / Leaflet |
 
 说明：
 
 - `defaultVisibleId` 应指向 `category: 'basemap'` 的底图。
-- `defaultAnnotationId` 应指向 `category: 'annotation'` 的注记层。
+- `defaultVisibleId` 找不到可用项时，会回退到 `basemap.list` 中第一个 `enabled !== false`、分类和引擎均匹配的底图；仍找不到时使用内置天地图矢量兜底配置。
+- `defaultAnnotationId` 当前只是保留字段，不参与初始化。要指定注记，给底图项设置 `annotationResourceKey`；天地图矢量、影像和地形底图未显式设置时，也会分别推断对应注记资源。
 - `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`，也可以直接传配置对象。当前适配层支持：
 
@@ -494,9 +1028,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,15 +1049,23 @@ 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 基础能力
 
 这一节列的是 `BaseGIS` 主入口直接提供的基础能力。业务页面优先调用这些方法；图片图层、网格图层、海量点、点位聚合、点位抽稀、等值线、风场等更复杂能力，建议使用后文 `methods` 中对应的 Controller。
 
-### 1. 生命周期、实例与引擎切换
+<a id="base-gis-lifecycle"></a>
+
+### 1. 生命周期与实例
 
-`BaseGIS` 支持 `cesium` 和 `leaflet` 两种引擎。引擎可以在构造时指定，也可以在 `init()` 时指定。
+`BaseGIS` 负责地图实例的初始化、状态读取、尺寸刷新和销毁。构造参数、完整配置项、参数优先级及 `setConfig()` 的生效规则见[地图初始化与运行时配置](#map-init-config)。
 
 ```js
 const mapCore = new BaseGIS({
@@ -529,58 +1073,49 @@ const mapCore = new BaseGIS({
   containerId: 'map',
 })
 
-// 创建地图实例。
-mapCore.init()
-
-// 只传目标引擎即可完成切换、视野保留和托管图层恢复。
-await mapCore.setEngine('leaflet')
+const initResult = mapCore.init()
+if (!initResult.success) {
+  console.warn(initResult.message)
+}
 
-// 覆盖运行时配置，不会自动重建地图。
-mapCore.setConfig({ view: { defaultSceneMode: '2d' } })
+const engineType = mapCore.getEngineType()
+const config = mapCore.getConfig() // 只读使用，不要直接修改。
+const mapInstance = mapCore.getMapInstance()
 
-// 读取当前地图引擎
-mapCore.getEngineType()
-//获取当前地图配置
-mapCore.getConfig()
-//获取地图实例
-mapCore.getMapInstance()
-// 销毁当前地图实例。
+mapCore.resize()
 mapCore.destroy()
 ```
 
-Cesium 默认使用最高 2 倍设备像素比、FXAA 和 4 倍 MSAA，避免高分屏上的细线出现明显像素阶梯。可按设备性能覆盖：
-
-```js
-const mapCore = new BaseGIS({
-  config: {
-    engine: {
-      cesium: {
-        renderQuality: {
-          maximumDevicePixelRatio: 1.5,
-          fxaa: true,
-          msaaSamples: 4,
-        },
-      },
-    },
-  },
-})
-```
-
 方法说明：
 
 | 方法 | 参数 | 说明 |
 | --- | --- | --- |
-| `init(options)` | `{ container, containerId, engineType }` | 初始化地图。重复调用时会自动恢复 BaseGIS 托管图层。 |
-| `setEngine(engineType, options)` | 引擎类型、初始化参数 | 未初始化时记录默认引擎；已初始化时自动切换、保留视野并恢复托管图层。 |
-| `switchEngine(engineType, options)` | 引擎类型、初始化参数 | `setEngine()` 的兼容别名。 |
+| `init(options)` | `{ container, containerId, engineType, sceneMode, initialView }` | 初始化地图。重复调用会重建地图并异步恢复 BaseGIS 托管图层。 |
 | `whenReady()` | 无 | 等待最近一次 `init()` 触发的托管图层恢复完成。 |
 | `destroy()` | 无 | 销毁当前地图实例和 adapter，并清空托管图层快照。 |
-| `setConfig(config)` | `Object` | 合并运行时配置；不自动重建地图。 |
+| `setConfig(config)` | `Object` | 合并实例配置，无返回值且不自动重建地图；[查看完整规则](#map-init-config)。 |
 | `getEngineType()` | 无 | 返回当前引擎类型。 |
-| `getConfig()` | 无 | 返回当前运行时配置。 |
+| `getConfig()` | 无 | 返回当前配置对象引用，建议只读。 |
 | `getMapInstance()` | 无 | 返回底层地图实例：Cesium `viewer` 或 Leaflet `map`。 |
+| `getMapContainer()` | 无 | 返回统一结果，`data.container` 为地图容器 DOM。 |
+| `resize()` | 无 | 在容器尺寸改变、隐藏面板重新显示后刷新地图尺寸。 |
+
+<a id="engine-switch"></a>
+
+### 2. 切换引擎
+
+`BaseGIS` 支持 `cesium` 和 `leaflet` 两种引擎。调用 `setEngine()` 可以在运行时切换引擎、保留当前视野，并恢复 BaseGIS 托管图层。
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `setEngine(engineType, options)` | 引擎类型、初始化参数 | 未初始化时记录默认引擎；已初始化时自动切换、保留视野并恢复托管图层。 |
+| `switchEngine(engineType, options)` | 引擎类型、初始化参数 | `setEngine()` 的兼容别名。 |
+
+目标引擎与当前引擎相同时，`setEngine()` 会直接返回，不会应用 `options.sceneMode / initialView / container`。同一引擎下调整场景或视角应调用 `setSceneMode()`、`setInitialView()`；需要重建地图时直接调用 `init()`。
 
-#### 推荐的引擎切换写法
+发生实际切换时，`setEngine()` 会把目标场景模式，以及显式传入或从当前地图保留的视角写回 `config.view`，供之后再次初始化使用。
+
+#### 推荐写法
 
 页面上做 Cesium / Leaflet 切换时，直接调用 `setEngine()`。它会保留当前视野、重建目标引擎，并等待托管图层自动恢复。
 
@@ -614,27 +1149,32 @@ 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. 视角控制与场景模式
+<a id="view-control-scene"></a>
+
+### 3. 视角控制与场景模式
 
 视角控制分为缩放、重置视角、设置初始视角、场景模式切换、视图状态读取和视图变化监听。
 
@@ -688,6 +1228,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,
@@ -697,6 +1244,8 @@ const pointResult = mapCore.projectToContainerPoint({
 // pointResult.data: { x, y }
 ```
 
+<a id="map-view-listener"></a>
+
 视图变化监听：
 
 ```js
@@ -708,6 +1257,10 @@ const viewListener = mapCore.onViewChange({
   // 缩放过程中要实时刷新点位样式时，优先用 onChange。
   onChange() {},
 
+  // Cesium 交互期间逐渲染帧检测相机变化；适合多地图实时联动。
+  // 默认 false，普通业务监听无需开启。
+  continuous: true,
+
   // Cesium: camera.moveEnd / morphComplete；Leaflet: moveend / zoomend / resize。
   onEnd() {},
 
@@ -730,13 +1283,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 }` | 经纬度投影到地图容器像素坐标。 |
 
-### 4. 绘制点、线、面、文字和 Marker
+<a id="map-screenshot"></a>
+
+### 4. 地图截图与导出
+
+`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` 仅表示已触发下载，不代表浏览器已确认文件保存到磁盘。导出范围始终限制在当前视口内，不是整页长截图，也不支持自动加载并拼接屏幕外瓦片。
 
-这些方法用于轻量绘制和样例验证。大量点位或复杂业务图层请优先使用后文的 `PointLargeLayerController`、`PointClusterController`、`PointDensityController`、`GraphicGroupController` 等控制器。
+<a id="basic-graphics"></a>
+
+### 5. 绘制点、线、面、文字和 Marker
+
+这些方法用于轻量绘制和样例验证。大量点位请优先使用后文的 `PointLargeLayerController`、`PointClusterController`、`PointDensityController` 等控制器。
 
 点：
 
@@ -827,11 +1465,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 +1677,115 @@ 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>
+
+### 6. GeoJSON 图层
+
+`upsertGeoJsonLayer()` 用同一个 `layerId` 创建或替换 GeoJSON 点、线、面图层，两个引擎共用数据与样式参数。图层基础样式使用 `style`，按要素覆盖的完整样式由 `styleCallback(feature, index)` 返回。坐标按 GeoJSON 顺序传入 `[经度, 纬度, 可选高度]`。
+
+```js
+const result = await mapCore.upsertGeoJsonLayer({
+  layerId: 'region-boundaries',
+  data: {
+    type: 'FeatureCollection',
+    features: [{
+      type: 'Feature',
+      id: 'region-1',
+      properties: {
+        name: '示例区域',
+      },
+      geometry: {
+        type: 'Polygon',
+        coordinates: [[[103, 34], [105, 34], [105, 36], [103, 36], [103, 34]]],
+      },
+    }],
+  },
+  styleCallback(feature) {
+    return {
+      color: '#36d3ff',
+      weight: 3,
+      opacity: 1,
+      dashArray: '8 4',
+      fillColor: '#1677ff',
+      fillOpacity: 0.4,
+    }
+  },
+  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 / dashArray / fillColor / fillOpacity / stroke / fill`；Leaflet 圆点大小用 `radius`，Cesium 标记大小用 `markerSize`。 |
+| `styleCallback(feature, index)` | 按数据返回样式覆盖；线、面支持全部 `style` 字段，点还支持 `radius / markerSize`；异常时使用基础样式。 |
+| `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' }) // 删除图层。
+```
+
+`styleCallback` 可直接返回完整样式；需要按要素变化时，在回调中读取 `feature.properties` 后决定返回值即可。`opacity: 0`、`fillOpacity: 0`、`stroke: false`、`fill: false` 都会按原值保留。两个引擎都会渲染虚线，但 `dashArray` 的具体节奏是近似效果。
+
+上述管理方法也可直接传 id 字符串；方法名兼容大写 `GeoJSON`，例如 `upsertGeoJSONLayer()`。更新时需重新提供完整数据和样式。GeoJSON 当前不在自动恢复清单中，切换引擎后需重新调用 `upsertGeoJsonLayer()`。
+
+<a id="dem-terrain"></a>
+
+### 7. 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`，不要直接假定结果包含地形状态。
+
+<a id="map-click-events"></a>
+
+### 8. 点击事件
 
 `onClick` 注册地图点击事件；`offClick` 移除当前点击监听。当前每个 adapter 只保留一个基础点击监听，重复调用 `onClick` 会先移除旧监听。
 
@@ -935,50 +1852,149 @@ Leaflet 当前返回坐标点击：
 - 海量点、点位聚合、点位抽稀等图层自己的点击事件，应使用对应 Controller 的点击回调参数。
 
 
-<a id="graphic-group-controller"></a>
+<a id="map-view-link-controller"></a>
 
-## GraphicGroupController
+## 多地图联动（双屏联动）
 
-用于一次性加载一组点、线、面、文字、marker。它只调用 `BaseGIS.drawPoint / drawLine / drawPolygon / drawText / addMarker`。
+`MapViewLinkController` 注册多个已经初始化的 BaseGIS，并实时同步拖动、缩放和视角。每个地图仍可独立加载不同模式、时次和图层；控制器只负责视角，不创建地图，也不会在 `unregisterMap()`、`clear()` 或 `destroy()` 时销毁 BaseGIS。
+
+在线示例：[查看分屏布局中的页面地图联动](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' })
 
-graphics.clear()
-graphics.getState()
+// 获取 BaseGIS、底层地图实例和全部 id -> BaseGIS 映射。
+const registeredMapA = viewLinks.getMap('map-a')
+const leafletMapA = viewLinks.getNativeMap('map-a')
+const allMaps = viewLinks.getMaps()
+
+// 以 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`。
 
 ### 实线、虚线与纯色
 
@@ -1089,6 +2105,10 @@ flightLine.restartAnimation()
 | 参数 | 默认值 | 说明 |
 | --- | --- | --- |
 | `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` | 线宽和透明度。 |
@@ -1104,17 +2124,166 @@ flightLine.restartAnimation()
 
 | 方法 | 说明 |
 | --- | --- |
-| `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)` | 加载或更新线、样式和动画。 |
+| `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` | 否 | 点击回调透传的业务数据。 |
+
+### 样式与播放配置
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `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()` | 控制专题显隐；隐藏时暂停，重新显示后恢复原播放意图。 |
+| `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 +2637,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 +2647,7 @@ imageLayer.destroy({ layerId: 'radar-image' })
 | `colorize.noDataValue` | 选填 | 无效值。 |
 | `colorize.colors` | 灰度图必填 | 色带颜色数组。 |
 | `opacity` | 选填 | 透明度，通常 0 - 1。 |
+| `zIndex` | 选填 | Leaflet 图片叠放层级，默认 `650`。 |
 | `visible` | 选填 | 是否显示图层。 |
 | `showProbe` | 选填 | 是否开启鼠标探针，需要 `tifUrl` 或灰度图数值。 |
 | `showLabel` | 选填 | 是否显示网格注记，需要 `tifUrl` 或灰度图数值。 |
@@ -1483,11 +2656,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 +2724,7 @@ await gridLayer.loadData({
   },
 })
 
-gridLayer.update({ decimalPlaces: 2 })
+await gridLayer.update({ decimalPlaces: 2 })
 gridLayer.hide()
 gridLayer.show()
 gridLayer.destroy()
@@ -1570,9 +2739,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>
+
+## 风场统一入口（推荐）
+
+风场有 GPU 和 Canvas 两种渲染方式，三个调用入口的区别如下：
+
+| 调用入口 | Cesium | Leaflet | 切换引擎后自动恢复 |
+| --- | --- | --- | --- |
+| `BaseGIS.upsertWindLayer()`（推荐） | GPU | Canvas | 支持 |
+| [`BaseGIS.upsertGpuWindLayer()`](#gpu-wind-layer) | GPU | 不支持 | 不支持 |
+| [`WindFieldMethods`](#wind-field-methods) | Canvas | Canvas | 不支持 |
 
-同一组 API 会根据当前引擎自动选择渲染器：Cesium 使用 GPU 粒子风场，Leaflet 使用迁自 one-map 的 Canvas 粒子风场。
+一般使用 `upsertWindLayer()` 即可，它会根据当前引擎自动选择渲染器。需要在 Cesium 上使用 Canvas，或需要叠加风速底图时，使用 `WindFieldMethods`。
 
 ```js
 const windData = await fetch('/mock/uv.json').then((response) => response.json())
@@ -1610,9 +2801,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 +2847,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 +2867,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 +2935,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 +3016,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 +3037,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 +3059,8 @@ const result = mapCore.upsertVolumeLayer({
     zCut: -0.5,
   },
 
+  colorRamp: ['#2f80ed', '#22c55e', '#facc15', '#ef4444'],
+
   // 选填：初始是否显示。
   visible: true,
 })
@@ -1798,13 +3072,13 @@ if (!result.success) {
 
 ### 更新参数
 
-更新透明阈值、步进数、裁切面时，不需要重新加载体数据，直接更新参数即可。
+更新透明度、密度、步进数或裁切面时，不需要重新加载体数据，直接更新参数即可。
 
 ```js
 mapCore.updateVolumeLayerParameters({
   layerId: 'volume-demo',
   parameters: {
-    threshold: 0.5,
+    opacity: 0.5,
     steps: 180,
     zCut: 0.1,
   },
@@ -1813,27 +3087,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 +3134,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 +3174,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 +3214,8 @@ const optionData = {
 }
 ```
 
+`Bound[11]` 可传 `null` 表示等间距气压层；传列表时长度必须等于 `LayerNums`，首项必须等于 `Bound[0]`。`Stride > 1` 时当前实现计算各分量的模长。
+
 ### 加载或更新数据
 
 同一个 `layerId` 重复调用 `upsertSectionLayer` 就是更新数据。适配层会清理旧切片，再加载新数据。
@@ -1936,15 +3239,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 +3268,7 @@ mapCore.renderSectionLayer({
   value: 39.9,
 })
 
-// Z 高度/气压方向切片。
+// Z 气压方向切片，单位 hPa。
 mapCore.renderSectionLayer({
   layerId: 'section-demo',
   sectionType: 2,
@@ -1978,7 +3282,7 @@ mapCore.renderSectionLayer({
 | --- | --- | --- |
 | `0` | 经度方向剖面 | 经度值。 |
 | `1` | 纬度方向剖面 | 纬度值。 |
-| `2` | 高度/气压方向剖面 | 气压层或高度层值。 |
+| `2` | 气压方向剖面 | 气压值，单位 hPa。 |
 | `3` | 全量剖面 | 可不传 `value`。 |
 
 ### 显隐、移除和定位
@@ -1994,16 +3298,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 +3351,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 +3367,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 +3749,7 @@ onBeforeUnmount(() => {
 <style scoped lang="scss">
 .station-cluster-map {
   width: 100%;
-  height: 100%;
+  height: 100vh;
 }
 </style>
 ```
@@ -2602,9 +3801,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 +3936,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 +3964,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 +4003,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 +4155,7 @@ density.destroy()
 | `priorityKey` | 否 | - | 同一网格内点位优先级字段，值越大越优先显示。 |
 | `priorityCallback` | 否 | - | 自定义优先级函数，返回值越大越优先显示。 |
 | `image` / `icon` / `iconUrl` | 否 | - | 默认图标地址。 |
-| `imageCallback` | 否 | - | 图标生成函数，适合每个点图标不同的场景。 |
+| `imageCallback` | 否 | - | 图标生成函数；配置对象可附带 `pulse` 告警扩散参数。 |
 | `width` | 否 | `32` | 图标宽度，单位像素。 |
 | `height` | 否 | `32` | 图标高度，单位像素。 |
 | `throttleTime` | 否 | `120` | 地图移动、缩放后刷新抽稀的节流时间，单位毫秒。 |
@@ -3088,7 +4199,7 @@ console.log(state)
 
 ## 等值线与中心标注能力选择
 
-对外只保留 2 个控制器：已有线坐标或中心坐标时用 `ContourLayerController`，手里是栅格时用 `RasterContourController`。线值标签与中心标注都属于通用 Contour 渲染配置，不再需要单独的气压组合层。
+已有线坐标或中心坐标时用 `ContourLayerController`，输入栅格时用 `RasterContourController`。线值标签与中心标注均使用通用 Contour 渲染配置。
 
 | 手里的数据 / 目标 | 使用入口 | 负责内容 |
 | --- | --- | --- |
@@ -3384,7 +4495,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 +4617,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 +4634,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 +4676,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 +4719,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 +4783,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 +4790,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 +4844,15 @@ SOFTWARE.
 
 ## 本地开发与打包
 
-在仓库根目录执行：
+包源码来自仓库 `src/gis`；`packages/basegis` 负责构建与发布配置。安装仓库依赖后，在仓库根目录执行：
 
 ```bash
 npm run build:basegis
+npm run test:basegis
 npm run pack:basegis
 ```
 
-`build:basegis` 会生成：
+`build:basegis` 生成以下入口，以及它们依赖的共享、异步代码块：
 
 ```text
 packages/basegis/dist/basegis.js
@@ -3803,23 +4862,27 @@ packages/basegis/dist/assets.js
 packages/basegis/dist/style.css
 ```
 
-`pack:basegis` 会在仓库根目录生成类似文件：
+分发时必须保留完整 `packages/basegis/dist`，不能只复制上述入口文件。`pack:basegis` 不会自动构建，修改源码后应先执行 `build:basegis`。
+
+`test:basegis` 会先构建包，再检查 Leaflet JS / CSS 外部依赖及样式产物边界，防止包重新内嵌一份官方 CSS。
+
+当前包版本为 `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,47 +4894,39 @@ 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 样式异常
 
-确认已引入：
+BaseGIS JS 会导入宿主的 Leaflet 官方 CSS；使用 npm 包时还需引入自有样式。也可以在应用入口显式统一加载两者：
 
 ```js
+import 'leaflet/dist/leaflet.css'
 import '@3clear/basegis/style.css'
 ```
 
+### 全局同时引入 BaseGIS 和原生 Leaflet 会覆盖吗
+
+按[安装](#安装)中的共同使用示例引入，并确保解析到同一份 Leaflet。包不再把官方 CSS 复制进 `style.css`，宿主可复用对 `leaflet/dist/leaflet.css` 的引用；不要再叠加 CDN 或其他版本的 Leaflet。
+
+这解决的是重复打包，不会隔离 CSS 的全局作用域。业务直接修改 `.leaflet-*` 仍会影响所有匹配的地图；页面定制应限定在自己的容器内，例如：
+
+```vue
+<style scoped lang="scss">
+.native-map-page {
+  :deep(.leaflet-popup-content) {
+    color: #333;
+  }
+}
+</style>
+```
+
 ### 调用方法返回 NOT_INITIALIZED
 
 说明地图还没有初始化成功。先执行：
@@ -3883,18 +4938,21 @@ console.log(result.success, result.message)
 
 ### 切换配置后地图没有变化
 
-`setConfig()` 只更新 `BaseGIS` 内部配置，不会自动重建地图。需要销毁后重新初始化：
+`setConfig()` 不会更新当前 adapter；需要再次 `init()` 才会按新配置重建地图。不要先手动 `destroy()`，以免清空托管图层快照：
 
 ```js
 mapCore.setConfig(nextConfig)
-mapCore.init()
+const result = mapCore.init()
+if (result.success) await mapCore.whenReady()
 ```
 
 `init()` 内部会先销毁旧适配器，再创建新实例。
 
+完整的配置项、生效时机和实时操作 API 对照见[地图初始化与运行时配置](#map-init-config)。
+
 ### 切换引擎后图层没了
 
-直接使用 `setEngine()`。BaseGIS 会保留视野，并自动恢复图片、网格、海量点、点位聚合、点位抽稀、独立线、等值线、统一风场和三维体等托管图层：
+先确认通过 `setEngine()` 切换且没有提前 `destroy()`，再查看恢复结果：
 
 ```js
 const result = await mapCore.setEngine('leaflet')
@@ -3903,4 +4961,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)`。