@3clear/basegis 0.1.2 → 0.1.3

package/README.md

@@ -4,12 +4,31 @@
 把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
@@ -266,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 基础能力
 
@@ -579,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
@@ -668,6 +770,8 @@ Leaflet 当前返回坐标点击：
 - 海量点、点位抽稀等图层自己的点击事件，应使用对应 Controller 的 `onClick` 参数。
 
 
+<a id="graphic-group-controller"></a>
+
 ## GraphicGroupController
 
 用于一次性加载一组点、线、面、文字、marker。它只调用 `BaseGIS.drawPoint / drawLine / drawPolygon / drawText / addMarker`。
@@ -705,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
@@ -872,6 +994,8 @@ await imageLayer.update({
 })
 ```
 
+Leaflet 会对经度跨度达到 360° 的全球图片按当前视野自动补充相邻世界副本，全球 TIF / 灰度格点的注记和鼠标探针也会使用同一套经度循环，因此业务页面不需要手动创建 `±360°` 图片层。原始图片按 `0° ~ 360°` 排列时传 `isSplit: true`，适配层会在交换左右半幅的同时把显示范围统一为 `-180° ~ 180°`，确保图片与格点值落在同一经度位置。
+
 `loadGrayImage` 的灰度值换算规则：
 
 ```js
@@ -1079,6 +1203,8 @@ imageLayer.destroy({ layerId: 'radar-image' })
 - `switchTo(idOrIndex)`：在已加载的 `items` 内切换到某一项。
 - `next() / prev()`：只适合本地小数组演示，不推荐作为业务时次更新主路径。
 
+<a id="grid-layer-controller"></a>
+
 ## GridLayerController
 
 用于 TIF 网格、灰度图网格、外部数值网格。
@@ -1141,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 调用时会返回不支持结果，不会抛出破坏页面的异常。
@@ -1449,6 +1745,8 @@ if (result.success) {
 | `lon / lat / hpa` | hover 取值必填 | Cesium 拾取得到的经度、纬度、气压高度。 |
 | `showZLayer` | hover 取值选填 | Z 切片是否参与 hover 命中，默认参与。 |
 
+<a id="point-large-layer-controller"></a>
+
 ## PointLargeLayerController
 
 用于海量点位渲染。它会尽量把传入的有效点位全部渲染出来，适合站点、设备、告警、监测点等需要保留全部点位并支持点击、高亮、删除、显隐的场景。
@@ -1811,6 +2109,8 @@ console.log(state)
 ```
 
 
+<a id="point-density-controller"></a>
+
 ## PointDensityController
 
 用于点位密度抽稀。地图移动、缩放后会按当前视野和屏幕网格重新计算可见点，适合站点、设备、告警、空气质量监测点等高密度点位。
@@ -2170,6 +2470,8 @@ console.log(state)
 // }
 ```
 
+<a id="contour-layer-controller"></a>
+
 ## ContourLayerController
 
 用于等值线图层，支持加载、更新、显隐、清空和销毁。
@@ -2216,7 +2518,7 @@ contour.clear()
 contour.destroy()
 ```
 
-数据别名支持 `contours / isolines / isoline / lines / data / items`。开启 `showLabel` 后，Cesium 和 Leaflet 都会根据当前屏幕范围重新选择可见线段上的位置；地图平移、缩放、容器尺寸变化或切换引擎时只重排标签，不重新生成等值线。
+数据别名支持 `contours / isolines / isoline / lines / data / items`。开启 `showLabel` 后，Cesium 和 Leaflet 都会根据当前屏幕范围重新选择可见线段上的位置。Leaflet 传入经度跨度达到 360° 的 `worldCopyArea` 后，还会按当前视野动态更新等值线路径和标签的世界副本；这个过程只重建可见路径，不重新解析栅格或追踪等值线。`RasterContourController` 会自动把栅格范围作为 `worldCopyArea` 传入。
 
 Cesium 在默认椭球地表上使用 `PolylineCollection` 批量落图；真正启用 DEM 地形后才使用 `GroundPolylinePrimitive`。新批次就绪后再替换旧批次，不为每条线创建独立 Entity。标签定位可通过 `labelLineThinStep` 抽样投影点，不会改变实际绘制的等值线。
 
@@ -2244,6 +2546,8 @@ Leaflet 默认复用高精度 SVG renderer，并使用 `smoothFactor: 0.5` 做
 
 `getState()` 的 `labelCount` 是当前视野实际显示的标签数量。Cesium 状态额外包含 `lineRenderer/lineBuildElapsed/labelLayoutElapsed/primitiveReadyElapsed`，用于区分线构建、标签排版和异步就绪耗时。`onStateChange(state)` 会在视野重排后回传新状态。页面存在侧栏等遮挡时，可通过 `labelViewportPadding` 排除对应区域。
 
+<a id="raster-contour-controller"></a>
+
 ## RasterContourController
 
 用于从 GeoTIFF、灰度图或数值网格直接计算并绘制等值线。内部统一使用 `d3-contour` 追踪等值线，输出仍交给 `ContourLayerController`，所以页面不需要区分 Cesium 和 Leaflet；调用 `BaseGIS.setEngine()` 时，已经生成的等值线会随托管图层自动恢复。
@@ -2393,69 +2697,45 @@ await rasterContour.loadGrid({
 | `getState()` | 返回尺寸、值域、级别、线数、当前标注数、投影、耗时和底层 contour 状态。 |
 | `getRasterData()` | 返回当前标准栅格，包含 `values/width/height/area`。 |
 
-[//]: # ()
-[//]: # (## PressureContourLayer)
+<a id="pressure-contour-layer"></a>
 
-[//]: # ()
-[//]: # (用于等压线和高低压中心标注。`buildPressureRenderData&#40;&#41;` 可把 Windy 风格的 `press.json` 数据整理成渲染结构，`createPressureDataResolver&#40;&#41;` 提供简单缓存。)
+## PressureContourLayer
 
-[//]: # ()
-[//]: # (```js)
+用于等压线、线值标签和高低压中心标注。`buildPressureRenderData()` 可把 Windy 风格的气压数据整理成 `{ isolines, centers }`，`createPressureDataResolver()` 在此基础上提供按数据版本缓存的解析函数。
 
-[//]: # (import {)
-
-[//]: # (  PressureContourLayer,)
-
-[//]: # (  createPressureDataResolver,)
-
-[//]: # (} from '@3clear/basegis/methods')
-
-[//]: # ()
-[//]: # (const resolvePressureData = createPressureDataResolver&#40;{)
-
-[//]: # (  default: pressJson,)
-
-[//]: # (  next: pressJson2,)
-
-[//]: # (}&#41;)
-
-[//]: # ()
-[//]: # (const pressureLayer = new PressureContourLayer&#40;{)
-
-[//]: # (  mapCore,)
-
-[//]: # (  layerId: 'pressure',)
-
-[//]: # (  color: 'rgba&#40;255,255,255,0.82&#41;',)
-
-[//]: # (  width: 1.15,)
-
-[//]: # (  smoothFactor: 0.2,)
-
-[//]: # (  // Cesium 场景下用于定位容器尺寸，Leaflet 场景也可以传同一个地图容器 id。)
-
-[//]: # (  mapContainerId: 'map',)
-
-[//]: # (  // 标注层通过该函数读取当前数据，便于地图缩放后重建标签。)
-
-[//]: # (  getData: &#40;&#41; => resolvePressureData&#40;'default'&#41;,)
-
-[//]: # (  isAnnotationVisible: &#40;&#41; => true,)
-
-[//]: # (}&#41;)
-
-[//]: # ()
-[//]: # (pressureLayer.mount&#40;&#41;)
-
-[//]: # (await pressureLayer.load&#40;resolvePressureData&#40;'default'&#41;&#41;)
+```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()
+```
 
 说明：
 
@@ -2463,6 +2743,8 @@ await rasterContour.loadGrid({
 - Leaflet 使用 `divIcon` 绘制 H/L 中心和线值标签。
 - Cesium 使用独立标注集合，地图变化时会调度刷新。
 
+<a id="wind-field-methods"></a>
+
 ## WindFieldMethods
 
 用于叠加 Canvas 风场粒子动画。它通过 `BaseGIS` 获取容器、投影、视野范围和视图变化事件，不直接依赖某个引擎。
@@ -2711,6 +2993,34 @@ console.log(result.data?.restore)
 | 三维切片 / 剖面渲染 | 支持 | 不支持 |
 | 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.
+```
+
 ## 本地开发与打包
 
 在仓库根目录执行：

package/dist/WindDataGrid-AGJaASUG.js

@@ -0,0 +1,96 @@
+const u = {
+  OK: "OK",
+  FAILED: "FAILED",
+  NOT_INITIALIZED: "NOT_INITIALIZED",
+  INVALID_CONTAINER: "INVALID_CONTAINER",
+  ENGINE_NOT_REGISTERED: "ENGINE_NOT_REGISTERED",
+  ENGINE_RESOURCE_MISSING: "ENGINE_RESOURCE_MISSING",
+  METHOD_NOT_FOUND: "METHOD_NOT_FOUND",
+  UNSUPPORTED_CAPABILITY: "UNSUPPORTED_CAPABILITY",
+  INVALID_DEM: "INVALID_DEM"
+};
+function _({
+  success: i = !0,
+  message: t = "",
+  data: s = null,
+  code: n = u.OK
+} = {}) {
+  return { success: i, message: t, data: s, code: n };
+}
+function C(i = null, t = "OK", s = u.OK) {
+  return _({ success: !0, message: t, data: i, code: s });
+}
+function g(i = "Operation failed.", t = u.FAILED, s = null) {
+  return _({ success: !1, message: i, data: s, code: t });
+}
+function T(i, t, s = "") {
+  const n = `${t} adapter does not support "${i}". ${s}`.trim();
+  return console.warn(`[3clear-dt-base] ${n}`), g(n, u.UNSUPPORTED_CAPABILITY, {
+    methodName: i,
+    engineType: t,
+    detail: s
+  });
+}
+class x {
+  constructor(t = {}) {
+    this.rawData = t, this.bound = Array.isArray(t.Bound) ? t.Bound : [], this.data = Array.isArray(t.DataAry) ? t.DataAry : [], this.valid = !1, this.errorMessage = "", this.lonMin = 0, this.latMin = 0, this.lonMax = 0, this.latMax = 0, this.lonCount = 0, this.latCount = 0, this.lonSpan = 0, this.latSpan = 0, this.lonStep = 0, this.latStep = 0, this.valueScale = 1, this.parse();
+  }
+  parse() {
+    if (this.bound.length < 6) {
+      this.errorMessage = "Wind field Bound must contain at least 6 values.";
+      return;
+    }
+    const [t, s, n, o, e, a, l = 1] = this.bound, r = Number(n) * Number(o) * 2;
+    if (!Number.isFinite(Number(t)) || !Number.isFinite(Number(s)) || Number(n) < 2 || Number(o) < 2 || Number(e) <= 0 || Number(a) <= 0 || this.data.length !== r) {
+      this.errorMessage = `Invalid wind field data. Expected DataAry length ${r}, got ${this.data.length}.`;
+      return;
+    }
+    this.lonMin = Number(t), this.latMin = Number(s), this.lonCount = Number(n), this.latCount = Number(o), this.lonSpan = Number(e), this.latSpan = Number(a), this.valueScale = Number(l) || 1, this.lonMax = this.lonMin + this.lonSpan, this.latMax = this.latMin + this.latSpan, this.lonStep = this.lonSpan / (this.lonCount - 1), this.latStep = this.latSpan / (this.latCount - 1), this.valid = !0;
+  }
+  contains(t, s) {
+    return Number.isFinite(t) && Number.isFinite(s) && t >= this.lonMin && t <= this.lonMax && s >= this.latMin && s <= this.latMax;
+  }
+  getBounds() {
+    return {
+      west: this.lonMin,
+      south: this.latMin,
+      east: this.lonMax,
+      north: this.latMax
+    };
+  }
+  getCenter() {
+    return {
+      lon: this.lonMin + this.lonSpan / 2,
+      lat: this.latMin + this.latSpan / 2
+    };
+  }
+  getVector(t, s) {
+    const n = (t * this.lonCount + s) * 2;
+    return {
+      u: Number(this.data[n]) / this.valueScale,
+      v: Number(this.data[n + 1]) / this.valueScale
+    };
+  }
+  /**
+   * 双线性插值。
+   *
+   * 数据约定为从左下角开始平铺，因此 row 直接对应从南到北的纬度索引。
+   */
+  sample(t, s) {
+    if (!this.valid || !this.contains(t, s))
+      return null;
+    const n = (t - this.lonMin) / this.lonStep, o = (s - this.latMin) / this.latStep, e = Math.max(0, Math.min(Math.floor(n), this.lonCount - 2)), a = Math.max(0, Math.min(Math.floor(o), this.latCount - 2)), l = e + 1, r = a + 1, h = Math.max(0, Math.min(n - e, 1)), c = Math.max(0, Math.min(o - a, 1)), I = this.getVector(a, e), S = this.getVector(a, l), E = this.getVector(r, e), m = this.getVector(r, l), d = 1 - h, p = 1 - c, b = d * p, A = h * p, O = d * c, D = h * c, N = I.u * b + S.u * A + E.u * O + m.u * D, M = I.v * b + S.v * A + E.v * O + m.v * D;
+    return !Number.isFinite(N) || !Number.isFinite(M) ? null : {
+      u: N,
+      v: M,
+      speed: Math.hypot(N, M)
+    };
+  }
+}
+export {
+  u as R,
+  x as W,
+  g as f,
+  C as s,
+  T as u
+};