MapLibre GL JS 用 maplibre-gl-wind 做风场可视化

编程与开发
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

用 maplibre-gl-wind 可在 MapLibre GL JS 中叠加高性能 GPU 粒子风场动画:通过 WindParticleLayer(基于 deck.gl 9.x 与 transform feedback)按风速着色并流动显示,风格接近 Windy.com。安装 maplibre-gl-wind 与配套 deck.gl 包后,准备 RG 通道风纹理(或点数据经 IDW 插值生成纹理),再用 MapboxOverlay 挂到地图即可。截至 2026 年 11 月,稳定版本为 0.2.3(2026-10-28 发布),要求 Node.js ≥24、deck.gl ≥9.0.0,不支持 Globe 投影。

maplibre-gl-wind 粒子风场可视化效果示意

如何安装并接入 MapLibre GL JS

目标是把 WindParticleLayer 作为 deck.gl 图层,通过 MapboxOverlay 叠到已有 MapLibre 地图上。先确认运行环境满足 Node.js ≥24.0.0,并安装 peer 依赖。

  1. 安装核心包:执行 npm install maplibre-gl-wind @deck.gl/core @deck.gl/layers(或 pnpm/bun 等价命令)。MapLibre 集成还需 @deck.gl/mapbox,以便使用 MapboxOverlay。
  2. 也可从 JSR 引入:pnpm i jsr:@geoql/maplibre-gl-wind。包导出主类 WindParticleLayer,以及 generateWindTexture、rasterizeWindField、createWindDataFromOpenWeatherMap 等辅助函数。
  3. 创建 MapLibre 地图(可用 OpenFreeMap liberty 等公开样式),在 map.on(‘load’) 回调里实例化 Overlay:new MapboxOverlay({ interleaved: true, layers: [new WindParticleLayer({ id: ‘wind’, … })] }),再 map.addControl(overlay)。
  4. 验收:地图加载后应看到粒子沿风向运动,颜色随速度变化;控制台无 shader 编译错误。若重复打包 deck.gl,会出现 “Vertex shader is not compiled” 或缺少 DECKGL_FILTER_* hook,需保证单一版本捆绑。

完整仓库与示例说明见 maplibre-gl-wind GitHub 仓库;版本变更可核对 GitHub Releases 列表。0.2.0 起为破坏性重写(用 deck.gl 粒子层替代旧 wind-gl-core),升级时注意 API 差异。

风场数据如何转成可用纹理

图层需要一张风纹理图:R 通道存 U(东西分量)、G 通道存 V(南北分量),数值按 imageUnscale 线性缩放到 0–255;A=255 表示有效像元,A=0 表示无数据。bounds 为 [west, south, east, north]。

  • 已有 PNG/纹理 URL:直接传给图层的 image,并设置对应 bounds 与 imageUnscale(风速最小/最大值)。
  • 离散风点数据:调用 generateWindTexture(windData, { width, height, bounds, power? }),在浏览器 canvas 上做 IDW 插值,返回 { canvas, imageUnscale },再把 canvas 转成 data URL 或纹理传给图层。rasterizeWindField 是纯函数版本,可放 Worker 或服务端。
  • OpenWeatherMap 等来向数据:天气 API 常报“风从哪来”,图层需要“吹向”角度(顺时针从北)。转换时给方向加 180°,再用 createWindDataFromOpenWeatherMap 辅助整理。
  • 局部非全球数据:务必正确设置 bounds,避免粒子跑出有效范围;无效区域用 A=0 标记。

演示站点使用 Open-Meteo 全球风数据,所有图层属性可实时调节,便于对照自己的数据格式。

maplibre-gl-wind 官方 GitHub 仓库页面,含 README 与演示链接
maplibre-gl-wind 官方 GitHub 仓库页面,含 README 与演示链接(截图来源:github.com)

WindParticleLayer 主要参数怎么选

创建图层时传入以下选项(括号内为默认值)。先固定 image、bounds、imageUnscale,再调粒子数量与速度观感;调完后观察帧率与视觉密度,作为验收标准。

参数 类型/默认 说明与选用建议
image string(必需) 风纹理 URL 或 data URL。必须先准备好 RG 编码图。
bounds number[] / [-180,-90,180,90] [west, south, east, north]。局部数据改成实际范围,否则粒子错位。
imageUnscale number[] / [0,0] 风速 [min, max],用于把 0–255 还原成真实 U/V。
numParticles number / 8192 粒子总数。移动端可降到 2048–4096,减轻 GPU 压力。
maxAge number / 50 粒子寿命(帧)。越大轨迹越长,视觉更连贯但更耗资源。
speedFactor number / 50 整体速度倍率。数据风速偏小时可适当加大。
colorRamp ColorStop[](蓝→红) [position, [r,g,b,a]] 数组,按速度着色。可改成业务配色。
speedRange number[] / [0,30] 着色用的风速区间(单位与数据一致)。
width number / 1.5 轨迹线宽。过粗易糊,过细在高 DPI 上难辨。
animate boolean / true 是否开启动画。调试静态时可临时关掉。

颜色按实际速度变化;本库不提供粒子尾巴效果,也不直接读 GeoTIFF,需事先转成单张 PNG/纹理。移动端依赖 deck.gl/luma.gl,WebGL 上下文丢失时粒子会停,需监听上下文恢复后重建 Overlay。

使用中要注意哪些限制

  • 不支持 MapLibre Globe 投影:deck.gl MapboxOverlay 与 Globe 存在深度/交错问题,平面 Mercator 或常规投影下正常。
  • Overlay 移除后重加:先 setProps({ layers: [] }) 清空,再重新 setProps 填入新图层,否则可能不显示。
  • 与旧库区分:@sakitam-gis/maplibre-wind 等基于旧 wind-layer,对 MapLibre v5/v6 支持较差;本库是独立 deck.gl 实现,兼容性更好,但仍受 WebGL 与打包影响。
  • 性能验收:桌面端 8192 粒子通常流畅;若掉帧,优先降 numParticles 或 maxAge,并检查是否重复引入了多份 @deck.gl/*。
  • 数据方向与无效值:来向转吹向、A 通道标记 NA,是最常见的“粒子方向反了/空白一片”原因。

常见问题

粒子不出现或完全静止怎么办?

先确认 image 能加载、bounds 与 imageUnscale 正确,且 animate 为 true。检查控制台是否有 shader 错误(多为 deck.gl 重复打包)。Overlay 若曾移除,务必先清空 layers 再重新添加。局部数据还要核对 CRS 与地图当前视图是否重叠。

风向看起来反了如何修正?

多数天气 API 报“来向”,而图层按“吹向”推进粒子。把方向角加 180° 后再生成纹理或点数据即可。U/V 分量符号也要与约定一致(东正、北正)。

可以在 Globe 模式或移动端稳定使用吗?

Globe 明确不支持。移动端可用,但受 WebGL 上下文与设备 GPU 限制,建议降低 numParticles,并在页面可见性变化或上下文丢失后重建图层。旧 webgl-wind 的 float 精度伪影在本库(transform feedback)上相对少见。

如何确认版本与已知问题?

以 package 中 0.2.3 及 CHANGELOG 为准;仓库 Issues 目前很少,开放需求多为“可运行示例”。遇到异常可先对照官方 README 的 peer 依赖版本,再排查打包与 Overlay 生命周期。

总结:先装好 maplibre-gl-wind 与 deck.gl 9.x,用正确 RG 纹理 + bounds/imageUnscale 驱动 WindParticleLayer,再经 MapboxOverlay 挂到 MapLibre;验收标准是粒子按真实风速着色并沿吹向流动、无 shader 报错。建议从官方演示参数起步微调 numParticles/speedFactor,并始终用平面投影;数据侧务必处理好来向转吹向与 A 通道无效值,这样一次就能稳定出图。