@gridmap/renderer

一个强大的 OpenLayers 格点数据渲染库，支持 WebGL、等值线、风羽、风向箭头等多种可视化方式

✨ 特性

• 🚀 高性能 WebGL 渲染 - 支持大规模格点数据的实时渲染
• 📊 多种可视化方式 - 等值线、数值标注、风羽、风向箭头
• 🎨 灵活的样式配置 - 支持自定义颜色映射、透明度等
• 🗺️ 多投影支持 - 支持 EPSG:3857、EPSG:4326 等多种投影坐标系
• 🔄 坐标系切换 - 支持动态切换投影坐标系并自动重建图层
• 📱 自适应显示 - 根据缩放级别自动调整显示密度
• 💪 TypeScript 支持 - 完整的类型定义

📦 安装

npm install @gridmap/renderer

或

yarn add @gridmap/renderer

🔧 依赖

本库需要 OpenLayers 7.0+ 作为 peer dependency：

npm install ol

🚀 快速开始

1. WebGL 格点图层

import GridRenderer from '@gridmap/renderer';

// 准备格点数据
const gridData = {
    beginLon: 100,
    endLon: 120,
    beginLat: 20,
    endLat: 40,
    lonCount: 100,
    latCount: 100,
    lonStep: 0.2,
    latStep: 0.2,
    data: [/* 格点数据数组 */]
};

// 定义颜色映射
const colorMapper = [
    { min: 0, max: 10, color: [0, 0, 255, 200] },     // 蓝色
    { min: 10, max: 20, color: [0, 255, 0, 200] },    // 绿色
    { min: 20, max: 30, color: [255, 255, 0, 200] },  // 黄色
    { min: 30, max: 40, color: [255, 0, 0, 200] }     // 红色
];

// 添加图层
const layer = GridRenderer.addWebGLGridLayer(
    map,              // OpenLayers 地图实例
    gridData,         // 格点数据
    colorMapper,      // 颜色映射
    0.8,              // 透明度
    10,               // 图层层级
    {
        layerId: 'temp-layer',
        layerName: '温度分布'
    }
);

2. 数值标注图层

const labelLayer = GridRenderer.addOptimizedValueLabels(
    map,
    gridData,
    {
        layerId: 'temp-labels',
        layerName: '温度标注',
        baseZoom: 7,
        baseFontSize: 14,
        fontColor: '#000',
        fontOutlineColor: '#fff',
        fontOutlineWidth: 2,
        valueFormatter: (value) => value.toFixed(1) + '°C',
        minZoom: 6,
        maxZoom: 18
    }
);

3. 等值线图层

const contourLayer = GridRenderer.addContourLines(
    map,
    gridData,
    {
        layerId: 'temp-contour',
        layerName: '温度等值线',
        contourLevels: [0, 5, 10, 15, 20, 25, 30],  // 等值线级别
        lineColor: '#ff0000',
        lineWidth: 1.5,
        showLabels: true,
        smoothFactor: 0.3
    }
);

4. 风向箭头图层

// 风数据需要包含 data（风速）和 data2（风向）
const windData = {
    beginLon: 100,
    endLon: 120,
    beginLat: 20,
    endLat: 40,
    lonCount: 50,
    latCount: 50,
    lonStep: 0.4,
    latStep: 0.4,
    gridBaseInformation: { /* ... */ },
    data: [/* 风速数据 */],
    data2: [/* 风向数据（度） */]
};

const arrowLayer = GridRenderer.addWindArrows(
    map,
    windData,
    {
        layerId: 'wind-arrows',
        layerName: '风向箭头',
        density: 8,
        arrowScale: 1.2,
        arrowColor: [0, 0, 0, 1],
        adaptiveDisplay: true
    }
);

5. 风羽图层

const barbLayer = GridRenderer.addWindBarbs(
    map,
    windData,
    {
        layerId: 'wind-barbs',
        layerName: '风羽',
        density: 4,
        barbColor: [0, 0, 255, 1],
        barbScale: 1.0,
        adaptiveDisplay: true,
        // 自定义风羽图标路径（可选）
        iconPath: '/assets/custom-wind-icons',  // SVG 文件所在目录
        iconFormat: 'svg'  // 文件格式
    }
);

// 也可以手动预加载图标（使用自定义路径）
await GridRenderer.preloadWindBarbIcons('/assets/custom-wind-icons', 'svg', 13);

📖 API 文档

GridRenderer.addWebGLGridLayer(map, gridData, colorMapper, opacity, zIndex, options)

添加 WebGL 格点图层

参数：

• map (Map) - OpenLayers 地图实例
• gridData (Object) - 格点数据对象
• colorMapper (Array) - 颜色映射数组
• opacity (Number) - 透明度，默认 0.8
• zIndex (Number) - 图层层级，默认 10
• options (Object) - 可选配置
  • layerId (String) - 图层 ID
  • layerName (String) - 图层名称

返回： TileLayer - WebGL 瓦片图层实例

GridRenderer.addOptimizedValueLabels(map, gridData, options)

添加优化的数值标注图层

参数：

• map (Map) - OpenLayers 地图实例
• gridData (Object) - 格点数据对象
• options (Object) - 配置选项
  • layerId (String) - 图层 ID
  • layerName (String) - 图层名称
  • baseZoom (Number) - 基准缩放级别，默认 7
  • baseDensity (Number) - 基准密度，默认 8
  • baseFontSize (Number) - 基准字体大小，默认 14
  • fontColor (String) - 字体颜色，默认 '#000'
  • fontOutlineColor (String) - 字体轮廓颜色，默认 '#fff'
  • fontOutlineWidth (Number) - 字体轮廓宽度，默认 2
  • valueFormatter (Function) - 数值格式化函数
  • minZoom (Number) - 最小缩放级别，默认 1
  • maxZoom (Number) - 最大缩放级别，默认 19

返回： VectorLayer - 矢量图层实例

GridRenderer.addContourLines(map, gridData, options)

添加等值线图层

参数：

• map (Map) - OpenLayers 地图实例
• gridData (Object) - 格点数据对象
• options (Object) - 配置选项
  • layerId (String) - 图层 ID
  • layerName (String) - 图层名称
  • contourLevels (Array) - 等值线级别数组，默认 [0, 5, 10, 15, 20, 25, 30]
  • lineColor (String) - 线颜色，默认 '#ff0000'
  • lineWidth (Number) - 线宽度，默认 1.5
  • showLabels (Boolean) - 是否显示标签，默认 true
  • smoothFactor (Number) - 平滑因子，默认 0.3
  • zIndex (Number) - 图层层级，默认 1000

返回： VectorLayer | null - 矢量图层实例

GridRenderer.addWindArrows(map, gridData, options)

添加风向箭头图层

参数：

• map (Map) - OpenLayers 地图实例
• gridData (Object) - 格点数据对象（需包含 data 和 data2）
• options (Object) - 配置选项
  • layerId (String) - 图层 ID
  • layerName (String) - 图层名称
  • density (Number) - 箭头密度，默认 8
  • arrowScale (Number) - 箭头长度比例，默认 1.2
  • minArrowLength (Number) - 最小箭头长度，默认 5
  • maxArrowLength (Number) - 最大箭头长度，默认 20
  • arrowWidth (Number) - 箭头线宽，默认 1.5
  • arrowColor (Array) - 箭头颜色 [R, G, B, A]，默认 [0, 0, 0, 1]
  • adaptiveDisplay (Boolean) - 是否自适应显示，默认 true

返回： VectorLayer | null - 矢量图层实例

GridRenderer.addWindBarbs(map, gridData, options)

添加风羽图层

参数：

• map (Map) - OpenLayers 地图实例
• gridData (Object) - 格点数据对象（需包含 data 和 data2）
• options (Object) - 配置选项
  • layerId (String) - 图层 ID
  • layerName (String) - 图层名称
  • density (Number) - 风羽密度，默认 4
  • barbScale (Number) - 风羽缩放比例，默认 1.0
  • barbLength (Number) - 风羽长度，默认 40
  • barbColor (Array) - 风羽颜色 [R, G, B, A]，默认 [0, 0, 255, 1]
  • adaptiveDisplay (Boolean) - 是否自适应显示，默认 true
  • iconPath (String) - 风羽图标路径（不含文件名），默认 '/src/assets/wind_icons' ⭐
  • iconFormat (String) - 图标文件格式，默认 'svg' ⭐

返回： VectorLayer | null - 矢量图层实例

图标文件要求：

• 文件命名：0.svg, 1.svg, 2.svg, ..., 13.svg（对应风级 0-13）
• 文件格式：SVG 矢量图
• 文件位置：放在 iconPath 指定的目录下

GridRenderer.rebuildLayer(map, layer)

重建图层（坐标系切换后使用）

参数：

• map (Map) - OpenLayers 地图实例
• layer (Layer) - 原图层对象

返回： Layer | null - 新图层对象

GridRenderer.rebuildAllLayers(map)

重建所有自定义图层（坐标系切换时调用）

参数：

• map (Map) - OpenLayers 地图实例

GridRenderer.removeLayer(map, layer)

移除图层

参数：

• map (Map) - OpenLayers 地图实例
• layer (Layer) - 图层实例

工具方法

GridRenderer.transformFromLonLat(lonLat, targetProjection)

将经纬度坐标转换为地图投影坐标

参数：

• lonLat (Array) - 经纬度数组 [lon, lat]
• targetProjection (String) - 目标投影坐标系，默认 'EPSG:3857'

返回： Array - 投影坐标 [x, y]

GridRenderer.getWindLevel(speed)

根据风速(m/s)转换为风级

参数：

• speed (Number) - 风速 (m/s)

返回： Number - 风级 (0-13)

📊 数据格式

格点数据结构

const gridData = {
    beginLon: 100,        // 起始经度
    endLon: 120,          // 结束经度
    beginLat: 20,         // 起始纬度
    endLat: 40,           // 结束纬度
    lonCount: 100,        // 经度方向格点数
    latCount: 100,        // 纬度方向格点数
    lonStep: 0.2,         // 经度步长
    latStep: 0.2,         // 纬度步长
    data: [],             // 数据数组（一维数组）
    data2: []             // 可选的第二数据数组（如风向）
};

颜色映射格式

const colorMapper = [
    {
        min: 0,                           // 最小值
        max: 10,                          // 最大值
        color: [0, 0, 255, 200]          // 颜色 [R, G, B, A]
    },
    // ... 更多映射
];

🎨 样式自定义

自定义数值格式化

GridRenderer.addOptimizedValueLabels(map, gridData, {
    valueFormatter: (value) => {
        return value.toFixed(2) + ' mm';  // 自定义格式
    }
});

自定义等值线颜色

GridRenderer.addContourLines(map, gridData, {
    contourLevels: [100, 200, 300, 400, 500],
    lineColor: '#0066cc',
    lineWidth: 2,
    showLabels: true
});

🔄 坐标系切换

当地图投影坐标系发生变化时，可以使用重建功能：

// 切换投影后重建所有图层
map.getView().setProjection('EPSG:4326');
GridRenderer.rebuildAllLayers(map);

// 或单独重建某个图层
const newLayer = GridRenderer.rebuildLayer(map, oldLayer);
if (newLayer) {
    map.removeLayer(oldLayer);
}

🧹 资源清理

// 方法 1: 使用通用方法移除图层
GridRenderer.removeLayer(map, layer);

// 方法 2: 使用专门的方法移除特定类型的图层
GridRenderer.removeWebGLLayer(map, webglLayer);
GridRenderer.removeValueLabelsLayer(map, labelLayer);
GridRenderer.removeContourLayer(map, contourLayer);
GridRenderer.removeWindArrowLayer(map, arrowLayer);
GridRenderer.removeWindBarbLayer(map, barbLayer);

// 方法 3: 根据图层 ID 移除
GridRenderer.removeLayerById(map, 'temp-layer');

// 方法 4: 移除所有格点图层
GridRenderer.removeAllGridLayers(map);

// 清理风羽图标缓存（如果使用了风羽图层）
GridRenderer.clearWindBarbIconCache();

图层查询

// 根据 ID 获取图层
const layer = GridRenderer.getLayerById(map, 'temp-layer');
if (layer) {
    layer.setVisible(false);
}

⚠️ 注意事项

1. 数据格式：确保格点数据按照指定格式组织
2. 性能优化：大规模数据建议使用 WebGL 渲染
3. 风羽图标：风羽图层需要 SVG 图标文件支持，请确保图标路径正确
4. 坐标系：支持 EPSG:3857 和 EPSG:4326，切换时需要重建图层
5. 内存管理：不使用的图层应及时移除以释放内存

📝 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📮 联系方式

如有问题或建议，请通过以下方式联系：

• Issue: GitHub Issues
• Email: [email protected]