03 气象图层效果绘制

0. 效果预设

风场：随风向流动的彩色流线（非粒子雨），颜色按风速由蓝→白→黄→橙→红渐变，叠加稀疏风羽箭头；台风环流呈逆时针涡旋、近中心红色大风区；

海浪：平滑紫色渐变大浪区（深紫红核心 → 淡紫 → 浅灰，非等值色带/等高线），叠浪高数值标注；

台风：橙色实线+圆点历史路径 → 黄色虚线+圆点预报路径 → 红色虚线 48 小时警戒线；右侧台风列表（蓝色标题栏 + 年份下拉 + 复选框）；当前台风位带时间提示（showTimeTipMinZoom:6 生效）；

底图：船讯网当前海图样式（瓦片源 gdtc.shipxy.com/tile.g，私有化镜像后本地 XYZ 同样式）；

天气功能按钮条：32px 图标，hover #ff8573、active #48505c；单点气象面板深色 #1d374c。

目标：基于离线气象数据，在私有化海图上复现在线平台气象服务（ShipxyAPI.WeatherService → map.weatherService）的核心图层效果：风场粒子（showWindFiel）、海浪等值面（showSeaWaves）、台风路径与风圈（showTyphoonInfoList），以及单点气象查询（对应 GetWeatherByPoint）。数据字段结构与船讯网官方气象接口（6.1 实时/预报气象、6.2 台风）保持一致，离线数据包可直接灌入。

效果图：

风场粒子动画（第 2 节效果）：
03-风场流线.png

海浪等值面（第 3 节效果）：
03-海浪渐变.png

台风路径与风圈（第 4 节效果）：

注：台风的动态图标请自行准备资源

1. 离线气象数据形态与预处理

1.1 与官方接口对齐的数据结构

单点实时气象（对应官方 GET /apicall/v3/CurrentWeather?key&lng&lat，官方 6.1.1）返回结构（离线数据包按此组织）：

{
  "status": 0, "msg": "",
  "data": {
    "observation_time": "2026-01-01T10:00:00Z",
    "atmospheric_data": {
      "temperature": 12.314,          "wind_speed_100m": 8.994,
      "wind_direction_100m": 37.562,  "wind_speed": 13.067,
      "wind_direction": 38.758,       "atmospheric_pressure": 102.206,
      "weather": "阴",               "precipitation": 0,
      "visibility": 13.032
    },
    "ocean_data": {
      "wave_direction": 44.949,   "wave_height": 0.77,    "wave_period": 4.75,
      "swell_direction": 67.553, "swell_height": 0.377,  "swell_period": 7.647,
      "wind_wave_direction": 38.313, "wind_wave_height": 0.66, "wind_wave_period": 2.867,
      "ocean_current_direction": 203.454, "ocean_current_speed": 0.402,
      "sea_water_height": 9.659, "sea_water_temp": 14.905, "sea_level_pressure": 102.275
    }
  }
}

官方口径：数据精度 0.08°×0.08° 每网格，每小时一包（6.1.1 服务介绍）。单点接口只取网格内插值；私有化做整层动画时，用"区域网格数据包"（一个网格点一个 atmospheric_data.ocean_data 子集）效率更高。

台风数据（对应官方 GET /apicall/v3/GetAllTyphoon 列表 + GET /apicall/v3/GetSingleTyphoon 详情，官方 6.2.1/6.2.2）：

{
  "status": 0, "msg": "", "total": 15,
  "data": [
    {
      "typhoon_id": "3063123",
      "typhoon_time": "202507231400",       // yyyyMMddHHmm，UTC+0（国内使用 +8）
      "forecast": "BABJ",                  // 非空=预报机构预测点；空=实测点
      "fhour": "24",                       // 未来小时；实测点为空
      "lat": 16.8667, "lng": 119.9667,     // WGS84
      "grade": 10,                         // 风级（5-18）
      "mspeed": 28,                        // 风速 m/s
      "pressure": 985,                     // 中心气压 hPa
      "kspeed": 13, "direction": "S",      // 移速 km/h，移向
      "radius7": 180,  "radius10": 0,      // 7/10 级风圈平均半径 km
      "radius7_s": "180,120,150,200",      // 四象限 7 级风圈：东北,东南,西南,西北
      "radius10_s": "0", "radius12_s": "0"
    }
  ]
}

1.2 区域网格包（绘制图层用）

把格点数据预转成紧凑 JSON（weather-grid.json），一次加载、前端自绘：

{
  "time": "2026-09-17 08:00:00",
  "lon0": 118.0, "lat0": 26.0,          // 网格原点（西南角）
  "dlon": 0.08, "dlat": 0.08,           // 官方网格精度 0.08°
  "nx": 120, "ny": 90,
  "wind_u": [ ... ],                     // 10m 风东向分量 m/s（长度 nx*ny）
  "wind_v": [ ... ],                     // 北向分量
  "wave_height": [ ... ]                // 有效波高 m
}

GRIB 源（如客户自购的 ECMWF/GFS 离线包）预转脚本（服务端 Python，定时生成后放到内网静态目录）：

时间格式沿用平台习惯 yyyy-MM-dd HH:mm:ss（官方 WeatherService 的时间参数即此格式）。

2. 风场粒子图层（复刻 showWindFiel）

在线平台 map.weatherService.showWindFiel() 是风场粒子动画：粒子随风速流向移动、颜色表达风速量级。私有化实现（Canvas 全屏层 + 网格插值 + 粒子生命周期）：

2.1 完整实现 `WindParticleLayer.js`

2.2 使用示例 + 图例

建议在图层打开时同步渲染一个图例（风速→颜色分级），与官方图层面板一致：

3. 海浪等值面图层（复刻 showSeaWaves）

在线平台 showSeaWaves() 渲染的是有效波高色斑图（波高越大颜色越深/越暖）。私有化实现：网格 → marching squares 等值线 → 分级填色多边形。

3.1 等值面提取 `WaveIsolineLayer.js`

marchingSquares 完整实现（网格二值化 → 轮廓提取，纯前端无依赖）：

上面为可运行的简化版（格边描边成等值线观感）。要精确的"闭合填色多边形"，可引入 d3-contour（内网部署 d3-contour.js，d3.contours().size([nx,ny]).thresholds(bands) 一步生成多边形坐标，再从行列号反算经纬度）。两种都给客户提供时，小网格（≤500×500）建议 d3 方案：

3.2 单点波高/气象查询（对应 GetWeatherByPoint）

在地图点击处查询网格插值（代替在线平台的单点接口），返回卡片与官方 GetWeatherByPoint 字段对齐（气压、风向、风速、浪高、水温等；无效值统一 -32767，与官方约定一致）：

4. 台风图层（复刻 showTyphoonInfoList）

在线平台 showTyphoonInfoList() 展示：台风实况路径点（按强度分级着色）、预报机构路径、7/10/12 级四象限风圈、当前台风中心符号与信息卡。私有化实现要点：

data 数组里 forecast 为空的是实测点，非空是预报点（按机构分组，BABJ=北京、RJTD=东京等）；

grade（5–18）映射颜色：≥11 强台风/超强台风深红、8–10 台风橙、6–7 热带风暴黄、5 热带低压蓝绿；

radius7_s 四象限（东北、东南、西南、西北）风圈画成四段不同半径的圆弧拼合。

4.1 完整实现 `TyphoonLayer.js`

4.2 使用示例（含台风列表）

台风数据定时更新：typhoon_time 为 UTC+0，国内展示 +8（官方同款提示）；radius7/radius10 为平均半径（画整圆用），四象限精细风圈用 radius*_s。

5. 其他气象图层的复刻思路（对照速查）

在线 API	数据源	私有化绘制方式
`showTempTile` / `showPressureTile` 气温/气压瓦片	网格数据	服务端预渲染色斑瓦片（Python + Pillow 按网格画 PNG 瓦片，存入文档 01 的瓦片服务），前端 `L.tileLayer` 叠加
`showSeaBreezes` 海风符号	风向/风速格点	网格抽稀后画风羽符号（barb）marker
`showOceanCurrentFiel` 海流粒子	海流 u/v 格点	复用第 2 节粒子引擎，换数据通道
`showRainFall` 降雨	降水格点	复用第 3 节等值面（换 bands 配色）
`weatherChoroplethServer` 气压等值线	气压格点	d3-contour 生成标量等值线（不填充），线上标气压值
`showTides` 潮汐	港口潮汐表（6.3 口径）	港口 marker + 潮高曲线弹框（参考文档 02 的 showTrackAnalysis 曲线画法）
气象图标 `icon_base_url`	自托管图标目录	天气状况（weather 字段）→ 本地图标映射，`ShipxyOptions.weather.icon_base_url` 在线版同思路，私有化直接用本地目录

6. 本章效果自查

风场粒子随流场连续漂移、按风速分色，关闭后 hideWindFiel 等效清屏；

海浪等值面按波高分档填色、图例正确、透明度不遮挡船舶层；

台风路径按强度着色、点悬浮显示时间/风速/气压/移速、7/10/12 级风圈四象限半径正确（东北象限 ≠ 西南象限时可看出差异）、预报路径虚线区分机构；

单点查询卡片字段与官方 GetWeatherByPoint 对齐，无效值显示 -32767。

至此，私有化底图 + 船舶/轨迹 + 气象三层能力全部就绪。

03 气象图层效果绘制

0. 效果预设#

1. 离线气象数据形态与预处理#

1.1 与官方接口对齐的数据结构#

1.2 区域网格包（绘制图层用）#

2. 风场粒子图层（复刻 showWindFiel）#

2.1 完整实现 WindParticleLayer.js#

2.2 使用示例 + 图例#

3. 海浪等值面图层（复刻 showSeaWaves）#

3.1 等值面提取 WaveIsolineLayer.js#

3.2 单点波高/气象查询（对应 GetWeatherByPoint）#

4. 台风图层（复刻 showTyphoonInfoList）#

4.1 完整实现 TyphoonLayer.js#

4.2 使用示例（含台风列表）#

5. 其他气象图层的复刻思路（对照速查）#

6. 本章效果自查#