@3clear/basegis 0.1.1 → 0.1.3

package/README.md

@@ -4,26 +4,47 @@
 把leaflet cesium 常用方法做了二次封装统一了api 使同一套代码可以适配2套地图引擎
 当前包包含：
 
-- `BaseGIS`：地图初始化、引擎切换、视角控制、底图切换、绘制、图层显隐、DEM、点击事件、三维体渲染、三维切片/剖面渲染等基础能力。
+- `BaseGIS`：地图初始化、引擎切换、视角控制、底图切换、绘制、图层显隐、DEM、点击事件、Cesium / Leaflet 统一粒子风场、GPU 粒子风场、三维体渲染、三维切片/剖面渲染等基础能力。
 - `methods`：图片图层、网格图层、海量点、点位抽稀、等值线、等压线、风场、图形组等高级控制器。
 - `layers`：天地图、GeoServer 金字塔瓦片、WMS、WMTS 图层配置快捷构造器。
 - `assets`：GIS 示例资源。
 - `style.css`：Leaflet、GIS 图层和标注相关基础样式。
 
+## 能力总览
+
+下表以当前 npm 包的真实出口和本项目源码为准。使用位置列展示原测试路由，点击后会在新标签页打开代码演练场，并通过 `path` 参数自动选中对应路由；没有独立页面的辅助函数与其所属控制器合并展示。
+
+| <small>导出 / 能力</small> | <small>功能</small> | <small>在本项目中的使用位置或路由</small> |
+| --- | --- | --- |
+| <small>[`BaseGIS`](#base-gis)</small> | <small>Cesium / Leaflet 统一入口，负责地图初始化、引擎切换、视角控制、场景模式、底图、DEM、绘制、点击事件，以及 GeoJSON、风场、三维体渲染和剖面渲染等能力。</small> | <small>基础能力：<a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a><br>专项能力：<a href="http://61.50.111.214:31166/lgmap/test-page-14" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-15" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-20" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-21" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-23" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`GraphicGroupController`](#graphic-group-controller)</small> | <small>统一装载和清理一组点、线、面、文字及 Marker 图形。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`ImageLayerController` / `toImageLayerArea`](#image-layer-controller)</small> | <small>加载普通图片、GeoTIFF、灰度图着色和多时次栅格，并提供范围参数转换。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`GridLayerController`](#grid-layer-controller)</small> | <small>加载灰度图或 GeoTIFF 数值网格，支持着色、探针、网格注记和生命周期控制。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`PointLargeLayerController`](#point-large-layer-controller)</small> | <small>面向海量点位的异步构建、样式规则、点击、高亮、删除和显隐控制。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-5" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`PointDensityController`](#point-density-controller)</small> | <small>点位视野裁剪和屏幕网格抽稀，支持动态图标、点击回调、配置更新和状态统计。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-8" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-9" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-13" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`PressureContourLayer` / `createPressureDataResolver` / `buildPressureRenderData`](#pressure-contour-layer)</small> | <small>解析气压数据并生成等值线、数值标签及高低压中心标注。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-7" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`ContourLayerController`](#contour-layer-controller)</small> | <small>统一管理等值线图层的加载、更新、显隐、引擎切换和销毁。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`RasterContourController`](#raster-contour-controller)</small> | <small>从 GeoTIFF、灰度图或数值网格提取并渲染等值线。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`WindFieldMethods`](#wind-field-methods)</small> | <small>提供 Cesium / Leaflet 风场数据加载、粒子动画、速度底图、交互和生命周期控制。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`createTiandituLayer` / `createGeoserverPyramidLayer` / `createWmsLayer` / `createWmtsLayer`](#layer-config-builders)</small> | <small>构造天地图、GeoServer 金字塔瓦片、WMS 和 WMTS 图层配置。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+| <small>[`gisMarkerSample`](#gis-marker-sample)</small> | <small>可直接导入的 GIS Marker 示例资源。</small> | <small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a>、<a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small> |
+
 ## 安装
 
 ```bash
-npm install @3clear/basegis leaflet axios pixi.js leaflet-pixi-overlay
+npm install @3clear/basegis leaflet axios
 ```
 
+`d3-contour`、`pixi.js` 和 `leaflet-pixi-overlay` 已随 BaseGIS 构建产物发布，业务项目不需要单独安装。其中 Pixi 相关代码只在首次使用 Leaflet 海量点能力时按需加载。
+
 使用样式：
 
 ```js
 import '@3clear/basegis/style.css'
 ```
 
-Cesium 当前不随 npm 包发布，宿主项目需要按原项目方式把 Cesium 静态资源放到 `public/lib/Cesium`，并保证初始化前能访问 `window.Cesium`。
-如果需要加载 GeoTIFF 网格，需要宿主项目提前提供 `window.GeoTIFF`。
+Cesium 当前不随 npm 包发布，项目需要按原项目方式把 Cesium 静态资源放到 `public/lib/Cesium`，并保证初始化前能访问 `window.Cesium`。
+如果需要加载 GeoTIFF 网格，需要项目提前提供 `window.GeoTIFF`。
 
 ## 出口
 
@@ -39,6 +60,7 @@ import {
   PointLargeLayerController,
   PointDensityController,
   ContourLayerController,
+  RasterContourController,
   PressureContourLayer,
   createPressureDataResolver,
   buildPressureRenderData,
@@ -263,6 +285,70 @@ mapCore.setBasemap({
 | `parameters` | 选填 | WMS 附加参数。 |
 | `engineSupport` | 选填 | 支持的引擎列表，如 `['cesium', 'leaflet']`。 |
 
+<a id="layer-config-builders"></a>
+
+## 图层配置构造器
+
+`layers` 出口提供四个快捷构造器，只负责生成标准图层配置，不会直接操作地图。构造结果可以放入 `config.basemap.list`，也可以传给 `setBasemap()`。
+
+```js
+import { BaseGIS } from '@3clear/basegis'
+import {
+  createGeoserverPyramidLayer,
+  createTiandituLayer,
+  createWmsLayer,
+  createWmtsLayer,
+} from '@3clear/basegis/layers'
+
+const basemapList = [
+  createTiandituLayer({
+    id: 'tianditu-imagery',
+    name: '天地图影像',
+    category: 'basemap',
+    resourceKey: 'imagery',
+    annotationResourceKey: 'imageryLabel',
+  }),
+  createGeoserverPyramidLayer({
+    id: 'geoserver-pyramid',
+    name: 'GeoServer 金字塔瓦片',
+    category: 'basemap',
+    url: 'https://example.com/tiles/{z}/{x}/{y}.png',
+  }),
+  createWmsLayer({
+    id: 'weather-wms',
+    name: '气象 WMS',
+    category: 'basemap',
+    serviceUrl: 'https://example.com/geoserver/wms',
+    layers: 'workspace:weather',
+    parameters: {
+      transparent: true,
+      format: 'image/png',
+    },
+  }),
+  createWmtsLayer({
+    id: 'weather-wmts',
+    name: '气象 WMTS',
+    category: 'basemap',
+    url: 'https://example.com/wmts',
+    layer: 'weather',
+    tileMatrixSet: 'EPSG:3857',
+  }),
+]
+
+const mapCore = new BaseGIS({
+  containerId: 'map',
+  config: {
+    basemap: {
+      list: basemapList,
+      defaultVisibleId: 'tianditu-imagery',
+    },
+  },
+})
+```
+
+四个构造器都会保留额外传入字段，便于继续配置 `engineSupport`、缩放级别、注记资源或服务参数。
+
+<a id="base-gis"></a>
 
 ## BaseGIS 基础能力
 
@@ -281,15 +367,8 @@ const mapCore = new BaseGIS({
 // 创建地图实例。
 mapCore.init()
 
-// 只修改当前运行时引擎配置，不会自动重建地图实例。
-mapCore.setEngine('leaflet')
-
-// 真正切换地图引擎，需要再次 init。
-// init 内部会先销毁旧 adapter，再按新 engineType 创建新地图实例。
-mapCore.init({
-  engineType: 'leaflet',
-  containerId: 'map',
-})
+// 只传目标引擎即可完成切换、视野保留和托管图层恢复。
+await mapCore.setEngine('leaflet')
 
 // 覆盖运行时配置，不会自动重建地图。
 mapCore.setConfig({ view: { defaultSceneMode: '2d' } })
@@ -304,13 +383,33 @@ mapCore.getMapInstance()
 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 }` | 初始化地图。`container` 可传 DOM，`containerId` 可传 DOM id。 |
-| `destroy()` | 无 | 销毁当前地图实例和 adapter。 |
-| `setEngine(engineType)` | `'cesium'/'leaflet'` | 修改当前引擎类型；不自动重建地图。 |
+| `init(options)` | `{ container, containerId, engineType }` | 初始化地图。重复调用时会自动恢复 BaseGIS 托管图层。 |
+| `setEngine(engineType, options)` | 引擎类型、初始化参数 | 未初始化时记录默认引擎；已初始化时自动切换、保留视野并恢复托管图层。 |
+| `switchEngine(engineType, options)` | 引擎类型、初始化参数 | `setEngine()` 的兼容别名。 |
+| `whenReady()` | 无 | 等待最近一次 `init()` 触发的托管图层恢复完成。 |
+| `destroy()` | 无 | 销毁当前地图实例和 adapter，并清空托管图层快照。 |
 | `setConfig(config)` | `Object` | 合并运行时配置；不自动重建地图。 |
 | `getEngineType()` | 无 | 返回当前引擎类型。 |
 | `getConfig()` | 无 | 返回当前运行时配置。 |
@@ -318,62 +417,55 @@ mapCore.destroy()
 
 #### 推荐的引擎切换写法
 
-页面上做 Cesium / Leaflet 切换时，建议把切换动作收敛成一个函数。`setEngine()` 用来更新 `BaseGIS` 内部引擎类型，`init()` 才是真正重建地图。
+页面上做 Cesium / Leaflet 切换时，直接调用 `setEngine()`。它会保留当前视野、重建目标引擎，并等待托管图层自动恢复。
 
 ```js
-async function switchEngine(engineType) {
+async function changeEngine(engineType) {
   if (!mapCore || mapCore.getEngineType() === engineType) {
     return
   }
 
-  const result = mapCore.init({
-    engineType,
-    containerId: 'map',
-  })
+  const result = await mapCore.setEngine(engineType)
 
   if (!result.success) {
     console.warn(result.message)
     return
   }
-
-  // 地图实例已经重建，业务图层需要用自己的数据源重新加载。
-  await reloadBusinessLayers()
 }
 ```
 
-也可以显式先调用 `setEngine()`：
+直接重复调用 `init({ engineType })` 也会自动开始恢复；如果后续逻辑依赖恢复完成，需要再等待 `whenReady()`：
 
 ```js
-mapCore.setEngine('leaflet')
 const result = mapCore.init({
+  engineType: 'leaflet',
   containerId: 'map',
 })
+
+if (result.success) {
+  await mapCore.whenReady()
+}
 ```
 
-两种写法效果一致；如果 `init({ engineType })` 已经传了目标引擎，可以不单独调用 `setEngine()`。
+`switchEngine()` 作为兼容别名保留，行为与 `setEngine()` 一致。
 
 #### 切换后的图层处理
 
-引擎切换不是把 Cesium 图层“搬到” Leaflet，也不是把 Leaflet 图层“搬到” Cesium。`init()` 重建地图时会销毁旧引擎实例，因此：
+引擎切换不是把 Cesium 图层对象“搬到” Leaflet，也不是把 Leaflet 图层对象“搬到” Cesium。BaseGIS 会保存托管图层的业务参数，并在新 adapter 中重新创建图层。
 
-- `BaseGIS` 的配置会保留，例如 `config / initialView / basemap`。
-- 业务数据应由页面或 store 保存，例如站点数组、图片地址、等值线数据、风场数据。
-- 切换成功后，用这些业务数据重新调用对应 Controller 的 `load/update`，或重新调用 `BaseGIS` 图层方法。
+- 自动恢复范围包括图片、网格、海量点、点位抽稀、等值线和三维体图层，对应 `upsert*Layer` 方法及 Controller。
+- 图层最新的数据参数、显隐、清空、删除、海量点删除和高亮状态会同步到 BaseGIS 快照。
+- 快照只保存业务参数引用，不复制大数组，不保存任何底层引擎对象。
+- 三维体图层切到 Leaflet 时会返回不支持结果，但快照仍保留，切回 Cesium 后会继续恢复。
 - Cesium 专有能力在 Leaflet 下不可用，例如 DEM、三维体渲染、三维切片/剖面渲染。
-- 页面层不应直接依赖 Cesium / Leaflet 分支；如果确实要访问底层实例，只在边界很清楚的地方使用 `getMapInstance()`。
+- 一次性绘制对象、点击监听、风场、剖面图层和页面直接操作底层引擎创建的对象不在托管范围内，需要业务自行恢复。
 
-常见重载示例：
+切换结果中可以查看恢复明细：
 
 ```js
-async function reloadBusinessLayers() {
-  await imageLayer.update(currentImagePayload)
-  await pointLayer.load({ points: currentPoints })
-  await contour.load(currentContourPayload)
-
-  if (mapCore.getEngineType() === 'cesium') {
-    mapCore.upsertVolumeLayer(currentVolumePayload)
-  }
-}
+const result = await mapCore.setEngine('leaflet')
+console.log(result.data.restore.restored)
+console.log(result.data.restore.failed)
 ```
 
 
@@ -570,6 +662,25 @@ mapCore.addMarker({
 })
 ```
 
+<a id="gis-marker-sample"></a>
+
+#### 使用 gisMarkerSample 示例资源
+
+`gisMarkerSample` 是可直接导入的 Marker 图片资源，适合快速验证 `addMarker()` 或控制器图标配置。
+
+```js
+import { gisMarkerSample } from '@3clear/basegis/assets'
+
+mapCore.addMarker({
+  id: 'marker-sample',
+  name: '示例站点',
+  position: [104, 35],
+  iconUrl: gisMarkerSample,
+  iconSize: [42, 50],
+  iconAnchor: [21, 50],
+})
+```
+
 清理图形：
 
 ```js
@@ -659,6 +770,8 @@ Leaflet 当前返回坐标点击：
 - 海量点、点位抽稀等图层自己的点击事件，应使用对应 Controller 的 `onClick` 参数。
 
 
+<a id="graphic-group-controller"></a>
+
 ## GraphicGroupController
 
 用于一次性加载一组点、线、面、文字、marker。它只调用 `BaseGIS.drawPoint / drawLine / drawPolygon / drawText / addMarker`。
@@ -696,10 +809,28 @@ graphics.clear()
 graphics.getState()
 ```
 
+<a id="image-layer-controller"></a>
+
 ## ImageLayerController
 
 用于管理一个图片覆盖层。所有更新都走 `update(payload)`；页面有很多时次数据时，自己维护数据列表，然后把当前时次的数据传给 `update`。
 
+`toImageLayerArea()` 可以把经纬度数组、Leaflet Bounds 或常见范围对象统一转换成 `{ startLon, startLat, endLon, endLat }`：
+
+```js
+import {
+  ImageLayerController,
+  toImageLayerArea,
+} from '@3clear/basegis/methods'
+
+const area = toImageLayerArea({
+  west: 73,
+  south: 18,
+  east: 135,
+  north: 54,
+})
+```
+
 先创建控制器。这里是控制器级默认参数，后续每次 `update(payload)` 都可以覆盖这些默认值：
 
 ```js
@@ -863,6 +994,8 @@ await imageLayer.update({
 })
 ```
 
+Leaflet 会对经度跨度达到 360° 的全球图片按当前视野自动补充相邻世界副本，全球 TIF / 灰度格点的注记和鼠标探针也会使用同一套经度循环，因此业务页面不需要手动创建 `±360°` 图片层。原始图片按 `0° ~ 360°` 排列时传 `isSplit: true`，适配层会在交换左右半幅的同时把显示范围统一为 `-180° ~ 180°`，确保图片与格点值落在同一经度位置。
+
 `loadGrayImage` 的灰度值换算规则：
 
 ```js
@@ -1070,6 +1203,8 @@ imageLayer.destroy({ layerId: 'radar-image' })
 - `switchTo(idOrIndex)`：在已加载的 `items` 内切换到某一项。
 - `next() / prev()`：只适合本地小数组演示，不推荐作为业务时次更新主路径。
 
+<a id="grid-layer-controller"></a>
+
 ## GridLayerController
 
 用于 TIF 网格、灰度图网格、外部数值网格。
@@ -1132,6 +1267,176 @@ gridLayer.show()
 gridLayer.destroy()
 ```
 
+## 统一粒子风场
+
+同一组 API 会根据当前引擎自动选择渲染器：Cesium 使用 GPU 粒子风场，Leaflet 使用迁自 one-map 的 Canvas 粒子风场。
+
+```js
+const windData = await fetch('/mock/uv.json').then((response) => response.json())
+
+await mapCore.upsertWindLayer({
+  layerId: 'surface-wind',
+  windData,
+  maxParticles: 6400,
+  speedFactor: 0.15,
+  lineWidth: 2,
+  fadeOpacity: 0.92,
+  color: '#b7d9ff',
+  particleOpacity: 0.72,
+})
+
+await mapCore.updateWindLayer({
+  layerId: 'surface-wind',
+  speedFactor: 0.2,
+})
+mapCore.hideWindLayer({ layerId: 'surface-wind' })
+mapCore.showWindLayer({ layerId: 'surface-wind' })
+mapCore.flyToWindLayer({ layerId: 'surface-wind', duration: 0.8 })
+const stateResult = mapCore.getWindLayerState({ layerId: 'surface-wind' })
+mapCore.removeWindLayer({ layerId: 'surface-wind' })
+```
+
+| 方法 | 说明 |
+| --- | --- |
+| `upsertWindLayer(payload)` | 创建或更新当前引擎的风场 |
+| `updateWindLayer(payload)` | 更新数据或部分参数 |
+| `showWindLayer(payload)` / `hideWindLayer(payload)` | 显隐风场 |
+| `flyToWindLayer(payload)` | 定位到风场数据范围 |
+| `getWindLayerState(payload)` | 获取渲染器、粒子数量、范围和显隐状态 |
+| `removeWindLayer(payload)` | 删除风场并释放资源 |
+
+跨引擎统一使用 `Bound / DataAry` 数据格式。公共参数包括 `maxParticles`、`speedFactor`、`lineWidth`、`fadeOpacity`、`particleOpacity`、`color` 和 `visible`；适配层会统一速度、帧率拖尾、屏幕线宽、设备像素比和粒子视觉密度。`maxParticles` 表示跨引擎视觉预算：Cesium 的实际粒子数会按 GPU 纹理向上取整为整数平方，Leaflet 会按 Canvas 拖尾覆盖率换算实际粒子数，均可通过图层状态查看；算法和投影不同，因此不保证逐像素完全一致。Leaflet 还支持 `particleGap`、`maxAge`、`frameRate`、`minSpeed`。统一风场属于 BaseGIS 托管图层，`setEngine()` 切换引擎时会自动使用原数据和最新参数恢复。
+
+## GPU 粒子风场
+
+GPU 粒子风场是 Cesium 专有能力，直接通过 `BaseGIS` 调用。它使用显卡纹理保存和更新粒子，相机平移或缩放期间清空轨迹，操作结束后按新视野重新生成粒子。Leaflet 调用同名方法时会返回 `UNSUPPORTED_CAPABILITY`，不会抛异常。
+
+Cesium 由宿主通过 `window.Cesium` 提供。启用 `terrainEnabled` 后，图层会采样当前 `viewer.terrainProvider`，让轨迹高度随地形变化；如果当前使用椭球地形，采样高度为 0。
+
+### 基础用法
+
+```js
+const response = await fetch('/mock/uv.json')
+const windData = await response.json()
+
+const result = await mapCore.upsertGpuWindLayer({
+  layerId: 'surface-gpu-wind',
+  windData,
+  maxParticles: 10000,
+  particleHeight: 0,
+  terrainEnabled: false,
+  fadeOpacity: 0.901,
+  dropRate: 0.001,
+  dropRateBump: 0.002,
+  speedFactor: 0.15,
+  lineWidth: 4.23,
+  color: '#ffffff',
+  particleOpacity: 1,
+})
+
+if (!result.success) {
+  console.warn(result.code, result.message)
+}
+```
+
+创建和更新是异步方法，可能等待地形采样，建议始终使用 `await`。
+
+### 数据格式
+
+可直接使用 BaseGIS 现有 Canvas 风场的 `Bound / DataAry` 数据：
+
+```js
+const windData = {
+  // 经度最小值、纬度最小值、经向格点数、纬向格点数、
+  // 经度跨度、纬度跨度、数值缩放倍数。
+  Bound: [100, 10, 181, 91, 80, 40, 10],
+  // 每个格点按 U、V 交错；纬度行从南向北排列。
+  DataAry: [u0, v0, u1, v1],
+}
+```
+
+也可以传独立 U/V 分量：
+
+```js
+const windData = {
+  width: 181,
+  height: 91,
+  bounds: {
+    west: 100,
+    east: 180,
+    south: 10,
+    north: 50,
+  },
+  u: new Float32Array(181 * 91),
+  v: new Float32Array(181 * 91),
+  // index-gpu.vue 解码结果从北向南排列，因此使用 north-to-south。
+  rowOrder: 'north-to-south',
+}
+```
+
+也可以不改 `windData`，在 `upsertGpuWindLayer` 参数中传 `flipY: true`。这与 `rowOrder: 'north-to-south'` 等价。
+
+### 更新、显隐和移除
+
+```js
+await mapCore.updateGpuWindLayer({
+  layerId: 'surface-gpu-wind',
+  maxParticles: 40000,
+  speedFactor: 0.2,
+  lineWidth: 3,
+  terrainEnabled: true,
+  particleHeight: 20,
+})
+
+mapCore.hideGpuWindLayer({ layerId: 'surface-gpu-wind' })
+mapCore.showGpuWindLayer({ layerId: 'surface-gpu-wind' })
+mapCore.flyToGpuWindLayer({ layerId: 'surface-gpu-wind', duration: 0.8 })
+
+const stateResult = mapCore.getGpuWindLayerState({
+  layerId: 'surface-gpu-wind',
+})
+console.log(stateResult.data)
+
+mapCore.removeGpuWindLayer({ layerId: 'surface-gpu-wind' })
+```
+
+`updateGpuWindLayer` 只传参数时复用现有数据；传入新的 `windData` 或 `data` 时会重建 GPU 图层。
+
+### 方法总表
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `upsertGpuWindLayer(payload)` | 数据和完整配置 | 创建或替换同 `layerId` 的 GPU 风场 |
+| `updateGpuWindLayer(payload)` | `{ layerId, ...partialOptions }` | 更新参数；传新数据时重建 |
+| `showGpuWindLayer(payload)` | `{ layerId }` | 显示图层 |
+| `hideGpuWindLayer(payload)` | `{ layerId }` | 隐藏图层 |
+| `removeGpuWindLayer(payload)` | `{ layerId }` | 删除图层并释放 GPU 资源 |
+| `flyToGpuWindLayer(payload)` | `{ layerId, duration? }` | 飞到风场数据范围 |
+| `getGpuWindLayerState(payload)` | `{ layerId }` | 获取粒子、范围、地形采样和显隐状态 |
+
+### 参数总表
+
+| 参数 | 是否必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `layerId` / `gpuWindLayerId` / `id` | 建议必填 | `gpu-wind-default` | 图层 id |
+| `windData` / `data` | 创建时必填 | - | 上述任一种风场数据 |
+| `maxParticles` | 选填 | `10000` | 请求粒子数；实际值向上取整为整数平方 |
+| `particleHeight` | 选填 | `0` | 离地高度，单位米 |
+| `terrainEnabled` | 选填 | `false` | 是否贴合 Cesium 地形 |
+| `fadeOpacity` | 选填 | `0.901` | 拖尾保留系数，范围 0～1 |
+| `dropRate` | 选填 | `0.001` | 基础粒子丢弃率 |
+| `dropRateBump` | 选填 | `0.002` | 随风速增加的附加丢弃率 |
+| `speedFactor` | 选填 | `0.15` | 移动速度倍率 |
+| `lineWidth` | 选填 | `4.23` | 轨迹线宽 |
+| `color` | 选填 | `#ffffff` | 粒子轨迹颜色 |
+| `particleOpacity` | 选填 | `1` | 粒子轨迹透明度，范围 0～1 |
+| `visible` | 选填 | `true` | 初始是否显示 |
+| `terrainMaxSamples` | 选填 | `4096` | 单次地形采样点上限，允许 4～16384 |
+| `terrainSampleLevel` | 选填 | 自动计算 | 固定地形采样层级，允许 0～15 |
+| `flipY` | 选填 | `false` | 独立 U/V 数据为北到南行序时传 `true` |
+
+GPU 专用 API 不属于跨引擎自动恢复图层。切换 Cesium/Leaflet 后，业务应重新调用 `upsertGpuWindLayer`；需要自动恢复时改用 `upsertWindLayer`。核心渲染流程改编自 [RaymanNg/3D-Wind-Field](https://github.com/RaymanNg/3D-Wind-Field)，遵循源码目录内 `LICENSE-RaymanNg.txt` 的 MIT License。
+
 ## 三维体渲染
 
 三维体渲染是 Cesium 专有能力，直接通过 `BaseGIS` 调用。Leaflet 调用时会返回不支持结果，不会抛出破坏页面的异常。
@@ -1440,10 +1745,14 @@ if (result.success) {
 | `lon / lat / hpa` | hover 取值必填 | Cesium 拾取得到的经度、纬度、气压高度。 |
 | `showZLayer` | hover 取值选填 | Z 切片是否参与 hover 命中，默认参与。 |
 
+<a id="point-large-layer-controller"></a>
+
 ## PointLargeLayerController
 
 用于海量点位渲染。它会尽量把传入的有效点位全部渲染出来，适合站点、设备、告警、监测点等需要保留全部点位并支持点击、高亮、删除、显隐的场景。
 
+Leaflet 模式使用 BaseGIS 内置的 `pixi.js` 和 `leaflet-pixi-overlay` 异步渲染，业务项目无需安装这两个依赖；Cesium 模式不加载 Pixi 相关代码。
+
 如果业务目标是“地图缩小时按屏幕网格抽稀，只显示代表点”，应使用后文的 `PointDensityController`。
 
 ### Demo 位置
@@ -1800,6 +2109,8 @@ console.log(state)
 ```
 
 
+<a id="point-density-controller"></a>
+
 ## PointDensityController
 
 用于点位密度抽稀。地图移动、缩放后会按当前视野和屏幕网格重新计算可见点，适合站点、设备、告警、空气质量监测点等高密度点位。
@@ -2159,6 +2470,8 @@ console.log(state)
 // }
 ```
 
+<a id="contour-layer-controller"></a>
+
 ## ContourLayerController
 
 用于等值线图层，支持加载、更新、显隐、清空和销毁。
@@ -2189,6 +2502,8 @@ await contour.load({
     color: '#ff4d4f',
     width: 2,
   },
+  showLabel: true,
+  labelFormatter: (item) => String(item.value),
 })
 
 await contour.update({
@@ -2203,71 +2518,224 @@ contour.clear()
 contour.destroy()
 ```
 
-数据别名支持 `contours / isolines / isoline / lines / data / items`。
+数据别名支持 `contours / isolines / isoline / lines / data / items`。开启 `showLabel` 后，Cesium 和 Leaflet 都会根据当前屏幕范围重新选择可见线段上的位置。Leaflet 传入经度跨度达到 360° 的 `worldCopyArea` 后，还会按当前视野动态更新等值线路径和标签的世界副本；这个过程只重建可见路径，不重新解析栅格或追踪等值线。`RasterContourController` 会自动把栅格范围作为 `worldCopyArea` 传入。
 
-[//]: # ()
-[//]: # (## PressureContourLayer)
+Cesium 在默认椭球地表上使用 `PolylineCollection` 批量落图；真正启用 DEM 地形后才使用 `GroundPolylinePrimitive`。新批次就绪后再替换旧批次，不为每条线创建独立 Entity。标签定位可通过 `labelLineThinStep` 抽样投影点，不会改变实际绘制的等值线。
 
-[//]: # ()
-[//]: # (用于等压线和高低压中心标注。`buildPressureRenderData&#40;&#41;` 可把 Windy 风格的 `press.json` 数据整理成渲染结构，`createPressureDataResolver&#40;&#41;` 提供简单缓存。)
+Leaflet 默认复用高精度 SVG renderer，并使用 `smoothFactor: 0.5` 做屏幕空间简化：缩小时清理挤在同一像素内的折点，放大后自动保留曲线细节，避免全局 `preferCanvas` 放大细线锯齿。线位于 `dt-contour-pane`（层级 `450`），稳定显示在图片图层上方，并保持在 `markerPane` 数值标签下方；显式传入 `pane` 时仍以业务配置为准。
 
-[//]: # ()
-[//]: # (```js)
+屏幕标注参数：
 
-[//]: # (import {)
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `showLabel/showLabels` | `boolean` | `false` | 是否显示等值线数值。 |
+| `labelFormatter(item, record)` | `Function` | 等值级别 | 格式化标签文本。 |
+| `labelColor` | `string` | `#34464f` | 文字颜色。 |
+| `labelBackgroundColor` | `string` | `rgba(255,255,255,0.78)` | 背景色。 |
+| `labelBorderColor/labelBorderWidth` | `string/number` | `rgba(93,112,116,0.35)` / `0.5` | 边框颜色和宽度。 |
+| `labelBorderRadius` | `number` | `8` | 圆角，单位 px。 |
+| `labelFontSize/labelFontWeight` | `number/string` | `10/600` | 字号和字重。 |
+| `labelPaddingX/labelPaddingY` | `number` | `4/0` | 标签内部留白。 |
+| `labelMinWidth` | `number` | `32` | 标签最小宽度，短数值保持横向胶囊形状。 |
+| `labelViewportPadding` | `number/object/Function` | `24` | 屏幕安全边距；对象为 `top/right/bottom/left`，函数接收 `{width,height}`。 |
+| `labelMinScreenLength` | `number` | `72` | 可见线段达到该像素长度后才允许放标签。 |
+| `labelLineThinStep` | `number` | Cesium `3`，Leaflet `1` | 标签定位时的投影抽样步长，不影响实际线几何。 |
+| `labelCollisionPadding` | `number` | `7` | 标签碰撞间距。 |
+| `labelMaxPerLevel` | `number` | `Infinity` | 每个等值级别在当前视野中的标签上限；默认按可见线数量自动决定。 |
+| `labelDisableDepthTestDistance` | `number` | `Infinity` | Cesium 标签关闭深度检测的距离。 |
 
-[//]: # (  PressureContourLayer,)
+`getState()` 的 `labelCount` 是当前视野实际显示的标签数量。Cesium 状态额外包含 `lineRenderer/lineBuildElapsed/labelLayoutElapsed/primitiveReadyElapsed`，用于区分线构建、标签排版和异步就绪耗时。`onStateChange(state)` 会在视野重排后回传新状态。页面存在侧栏等遮挡时，可通过 `labelViewportPadding` 排除对应区域。
 
-[//]: # (  createPressureDataResolver,)
+<a id="raster-contour-controller"></a>
 
-[//]: # (} from '@3clear/basegis/methods')
+## RasterContourController
 
-[//]: # ()
-[//]: # (const resolvePressureData = createPressureDataResolver&#40;{)
+用于从 GeoTIFF、灰度图或数值网格直接计算并绘制等值线。内部统一使用 `d3-contour` 追踪等值线，输出仍交给 `ContourLayerController`，所以页面不需要区分 Cesium 和 Leaflet；调用 `BaseGIS.setEngine()` 时，已经生成的等值线会随托管图层自动恢复。
 
-[//]: # (  default: pressJson,)
+### 1. GeoTIFF 生成等值线
 
-[//]: # (  next: pressJson2,)
+```js
+import { RasterContourController } from '@3clear/basegis/methods'
 
-[//]: # (}&#41;)
+const rasterContour = new RasterContourController({
+  mapCore,
+  layerId: 'temperature-raster-contour',
+  // thresholds / interval / thresholdCount 三选一。
+  interval: 5,
+  smooth: true,
+  visible: true,
+})
 
-[//]: # ()
-[//]: # (const pressureLayer = new PressureContourLayer&#40;{)
+const result = await rasterContour.loadGeoTiff({
+  tifUrl: '/data/temperature.tif',
+  // TIF 范围不准确时可用 WGS84 四至覆盖文件元数据。
+  area: {
+    startLon: -180,
+    startLat: -90,
+    endLon: 180,
+    endLat: 90,
+  },
+  band: 0,
+  interval: 5,
+  clampToGround: true,
+  showLabel: true,
+  labelFormatter: (item) => String(Math.round(item.value)),
+  labelViewportPadding: { top: 32, right: 32, bottom: 32, left: 360 },
+  styleCallback: (item) => ({
+    color: item.value >= 30 ? '#ff6b6b' : '#d5f4ff',
+    width: item.value % 10 === 0 ? 2 : 1,
+    weight: item.value % 10 === 0 ? 2 : 1,
+  }),
+})
 
-[//]: # (  mapCore,)
+if (!result.success) {
+  console.warn(result.message)
+}
 
-[//]: # (  layerId: 'pressure',)
+// 仅调整等值距时复用已解析网格，不再请求和解码 TIF。
+await rasterContour.update({ interval: 2 })
+```
 
-[//]: # (  color: 'rgba&#40;255,255,255,0.82&#41;',)
+GeoTIFF 依赖宿主页面提供 `window.GeoTIFF`。控制器会读取波段、尺寸、坐标系和范围；当前原生支持 EPSG:4326、EPSG:3857。其他投影可先转换为 WGS84，或传入 WGS84 `area` 覆盖原始范围。
+
+### 2. 灰度图生成等值线
+
+```js
+await rasterContour.loadGrayImage({
+  grayImageUrl: '/data/pressure-gray.png',
+  area: [-180, -90, 180, 90],
+  grayMinValue: 0,
+  grayMaxValue: 255,
+  minValue: 960,
+  maxValue: 1040,
+  noDataValue: 255,
+  interval: 4,
+})
+```
+
+灰度换算规则：
+
+```text
+业务值 = (灰度值 - grayMinValue) / (grayMaxValue - grayMinValue)
+       * (maxValue - minValue) + minValue
+```
 
-[//]: # (  width: 1.15,)
+灰度图片本身没有地理范围和业务值含义，因此 `area` 必填；要表达真实数据，还应传正确的灰度范围与业务值范围。已经着色的彩色 PNG 不能反推出原始业务值，应使用对应 TIF 或直接传数值网格。
 
-[//]: # (  smoothFactor: 0.2,)
+### 3. 数值网格生成等值线
 
-[//]: # (  // Cesium 场景下用于定位容器尺寸，Leaflet 场景也可以传同一个地图容器 id。)
+```js
+await rasterContour.loadGrid({
+  values: [12, 14, 16, 18, 20, 22],
+  width: 3,
+  height: 2,
+  area: [100, 20, 103, 22],
+  thresholds: [15, 20],
+})
 
-[//]: # (  mapContainerId: 'map',)
+// values 也可以直接传二维数组，此时不需要 width / height。
+await rasterContour.loadGrid({
+  values: [
+    [12, 14, 16],
+    [18, 20, 22],
+  ],
+  area: [100, 20, 103, 22],
+  thresholdCount: 6,
+})
+```
 
-[//]: # (  // 标注层通过该函数读取当前数据，便于地图缩放后重建标签。)
+### 4. 参数
+
+数据源参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `mapCore/baseGIS` | `BaseGIS` | 构造时必填 | `null` | 当前 BaseGIS 实例。 |
+| `layerId/contourLayerId` | `string` | 否 | `raster-contour-default` | 等值线图层 id。 |
+| `sourceType` | `geotiff/grayscale/grid` | 否 | 自动判断 | `loadGeoTiff/loadGrayImage/loadGrid` 会自动补齐。 |
+| `tifUrl/tiffUrl` | `string` | GeoTIFF 必填 | `''` | GeoTIFF 地址。 |
+| `arrayBuffer` | `ArrayBuffer` | 否 | `null` | 可代替 `tifUrl` 直接传 TIF 内容。 |
+| `band` | `number` | 否 | `0` | GeoTIFF 波段下标，从 0 开始。 |
+| `imageIndex` | `number` | 否 | `0` | 多图像 GeoTIFF 的图像下标。 |
+| `grayImageUrl/imageUrl` | `string` | 灰度图必填 | `''` | 灰度图地址，服务端必须允许 Canvas 跨域读取。 |
+| `values/data/grid` | `Array/TypedArray` | 数值网格必填 | - | 一维或二维数值。 |
+| `width/height` | `number` | 一维网格必填 | `0` | 一维数组的网格尺寸。 |
+| `area` | `object/number[]` | 图片和普通网格必填 | `null` | WGS84 范围；数组顺序为 `[west,south,east,north]`。 |
+| `sourceProjection` | `string` | 否 | 自动读取 | 支持 `EPSG:4326`、`EPSG:3857`。 |
+| `noDataValue` | `number` | 否 | TIF 自动读取 | 指定无效值；灰度图不传时仅透明像素无效。 |
+| `validMin/validMax` | `number` | 否 | - | 过滤值域外数据。 |
+| `scale/offset` | `number` | 否 | `1/0` | 数值换算为 `value * scale + offset`。 |
+| `isSplit` | `boolean` | 否 | `false` | 把左右半幅交换，处理以 0° 经线为边界的全球数据。 |
+
+等值线参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `thresholds/levels` | `number[]` | 三选一 | - | 显式等值线级别，仅保留实际值域内的值。 |
+| `interval/contourInterval` | `number` | 三选一 | - | 固定等值距。 |
+| `thresholdCount/levelCount` | `number` | 三选一 | `12` | 自动均分级别数量，范围 1~100。 |
+| `smooth` | `boolean` | 否 | `true` | 是否平滑等值线。 |
+| `smoothingIterations` | `number` | 否 | `0` | Chaikin 补点平滑次数，范围 0~3；气象格点通常取 1~2，次数越高，点数越多。 |
+| `excludeBoundary` | `boolean` | 否 | `true` | 去掉 d3 面边界中贴着栅格四边的伪矩形线。 |
+| `maxCells` | `number` | 否 | `1000000` | 超过该像元数时先等比例抽样，避免大图阻塞页面。 |
+| `minimumLinePoints` | `number` | 否 | `3` | 最短线点数，用于过滤栅格四角的两点补边。 |
+| `coordinatePrecision` | `number` | 否 | `6` | 输出经纬度小数位数。 |
+| `visible` | `boolean` | 否 | `true` | 初始显隐。 |
+| 其他渲染参数 | - | 否 | - | 与 `ContourLayerController` 相同，如 `color/width/weight/styleCallback/showLabel/labelViewportPadding`。 |
+
+### 5. 方法和状态
 
-[//]: # (  getData: &#40;&#41; => resolvePressureData&#40;'default'&#41;,)
+| 方法 | 说明 |
+| --- | --- |
+| `load(payload, options)` | 自动判断数据源并生成等值线。 |
+| `loadGeoTiff(payload, options)` | 从 GeoTIFF 生成。 |
+| `loadGrayImage(payload, options)` | 从灰度图生成。 |
+| `loadGrid(payload, options)` | 从数值网格生成。 |
+| `update(payload)` | 合并配置后重新计算；仅修改等值线或渲染参数时复用已解析网格，修改数据源参数时自动重新加载。 |
+| `show/hide/toggle` | 控制等值线显隐。 |
+| `clear/destroy` | 清空或销毁控制器。 |
+| `getState()` | 返回尺寸、值域、级别、线数、当前标注数、投影、耗时和底层 contour 状态。 |
+| `getRasterData()` | 返回当前标准栅格，包含 `values/width/height/area`。 |
 
-[//]: # (  isAnnotationVisible: &#40;&#41; => true,)
+<a id="pressure-contour-layer"></a>
 
-[//]: # (}&#41;)
+## PressureContourLayer
 
-[//]: # ()
-[//]: # (pressureLayer.mount&#40;&#41;)
+用于等压线、线值标签和高低压中心标注。`buildPressureRenderData()` 可把 Windy 风格的气压数据整理成 `{ isolines, centers }`，`createPressureDataResolver()` 在此基础上提供按数据版本缓存的解析函数。
 
-[//]: # (await pressureLayer.load&#40;resolvePressureData&#40;'default'&#41;&#41;)
+```js
+import {
+  PressureContourLayer,
+  buildPressureRenderData,
+  createPressureDataResolver,
+} from '@3clear/basegis/methods'
 
-[//]: # (await pressureLayer.update&#40;resolvePressureData&#40;'next'&#41;&#41;)
+// 单份原始数据可以直接转换。
+const renderData = buildPressureRenderData(pressJson)
 
-[//]: # (pressureLayer.hide&#40;&#41;)
+// 多个时次或版本可用解析器按 key 缓存转换结果。
+const resolvePressureData = createPressureDataResolver({
+  default: pressJson,
+  next: pressJson2,
+})
 
-[//]: # (pressureLayer.destroy&#40;&#41;)
+const pressureLayer = new PressureContourLayer({
+  mapCore,
+  layerId: 'pressure',
+  color: 'rgba(255,255,255,0.82)',
+  width: 1.15,
+  smoothFactor: 0.2,
+  // Cesium 用它判断标签碰撞和屏幕范围，Leaflet 可复用同一容器 id。
+  mapContainerId: 'map',
+  isAnnotationVisible: () => true,
+})
 
-[//]: # (```)
+pressureLayer.mount()
+await pressureLayer.load(renderData)
+await pressureLayer.update(resolvePressureData('next'))
+pressureLayer.hide()
+pressureLayer.destroy()
+```
 
 说明：
 
@@ -2275,6 +2743,8 @@ contour.destroy()
 - Leaflet 使用 `divIcon` 绘制 H/L 中心和线值标签。
 - Cesium 使用独立标注集合，地图变化时会调度刷新。
 
+<a id="wind-field-methods"></a>
+
 ## WindFieldMethods
 
 用于叠加 Canvas 风场粒子动画。它通过 `BaseGIS` 获取容器、投影、视野范围和视图变化事件，不直接依赖某个引擎。
@@ -2460,20 +2930,19 @@ export function useBaseGIS(options = {}) {
     mapCore.value = null
   })
 
-  function switchEngine(engineType) {
+  async function setEngine(engineType) {
     if (!mapCore.value || mapCore.value.getEngineType() === engineType) {
       return { success: true }
     }
 
-    return mapCore.value.init({
+    return mapCore.value.setEngine(engineType, {
       ...options,
-      engineType,
     })
   }
 
   return {
     mapCore,
-    switchEngine,
+    setEngine,
   }
 }
 ```
@@ -2488,22 +2957,22 @@ export function useBaseGIS(options = {}) {
 <script setup>
 import { useBaseGIS } from './useBaseGIS'
 
-const { mapCore, switchEngine } = useBaseGIS({
+const { mapCore, setEngine } = useBaseGIS({
   engineType: 'cesium',
   containerId: 'map',
 })
 </script>
 ```
 
-如果页面有业务图层，`switchEngine()` 成功后要重新加载图层数据：
+BaseGIS 托管图层会自动恢复，页面不需要重新请求数据：
 
 ```js
-const result = switchEngine('leaflet')
-if (result.success) {
-  await reloadBusinessLayers()
-}
+const result = await setEngine('leaflet')
+console.log(result.data?.restore)
 ```
 
+只有风场、剖面、一次性绘制对象或页面直接创建的底层引擎对象需要在切换成功后自行恢复。
+
 ## 能力支持说明
 
 | 能力 | Cesium | Leaflet |
@@ -2524,6 +2993,34 @@ if (result.success) {
 | 三维切片 / 剖面渲染 | 支持 | 不支持 |
 | DEM 地形 | 支持 | 不支持 |
 
+## 第三方许可
+
+GPU 粒子风场核心改编自 RaymanNg/3D-Wind-Field：
+
+```text
+MIT License
+
+Copyright (c) 2019 RaymanNg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## 本地开发与打包
 
 在仓库根目录执行：
@@ -2634,18 +3131,13 @@ mapCore.init()
 
 ### 切换引擎后图层没了
 
-这是预期行为。Cesium 和 Leaflet 的图层对象不能互相复用，`init({ engineType })` 会销毁旧地图实例并创建新地图实例。
-
-处理方式是：页面或 store 保存业务数据，切换成功后重新调用对应的加载方法。
+直接使用 `setEngine()`。BaseGIS 会保留视野，并自动恢复图片、网格、海量点、点位抽稀、等值线和三维体等托管图层：
 
 ```js
-const result = mapCore.init({
-  engineType: 'leaflet',
-  containerId: 'map',
-})
+const result = await mapCore.setEngine('leaflet')
 
-if (result.success) {
-  await imageLayer.update(currentImagePayload)
-  await pointLayer.load({ points: currentPoints })
-}
+console.log(result.data?.restore?.restored)
+console.log(result.data?.restore?.failed)
 ```
+
+如果丢失的是 `drawPoint/drawLine/drawPolygon/drawText/addMarker`、点击监听、风场、剖面图层或页面直接创建的 Cesium / Leaflet 对象，它们不属于托管图层，需要业务在切换成功后自行恢复。