Scalar GL

高性能标量场可视化库，基于 WebGL 实现的气象/海洋数据渲染引擎

✨ 特性

• 🚀 高性能渲染：基于 WebGL 的 GPU 加速渲染
• 🎨 灵活样式：支持多种插值算法和颜色渐变
• 🧩 平台适配：支持 Maptalks，易于扩展到其他地图库
• 📦 开箱即用：提供完整的图层组件
• 🔧 TypeScript：完整的类型定义
• 🌐 多格式支持：ESM、CJS、UMD、IIFE

📦 安装

# npm
npm install scalar-gl

# pnpm
pnpm add scalar-gl

# yarn
yarn add scalar-gl

如果使用 Maptalks 平台：

npm install maptalks scalar-gl

🚀 快速开始

基础使用（Maptalks）

import { Map } from 'maptalks';
import { MaptalksScalarFillLayer } from 'scalar-gl';

// 创建地图
const map = new Map('map', {
  center: [120, 30],
  zoom: 5
});

// 准备数据
const gridData = {
  lonMin: 110,
  lonMax: 130,
  latMin: 20,
  latMax: 40,
  value: [
    [15.2, 16.5, 17.8, ...],
    [14.8, 15.9, 17.1, ...],
    // ...
  ]
};

// 创建标量填充图层
const scalarLayer = new MaptalksScalarFillLayer('scalar', gridData, {
  opacity: 0.8,
  styleSpec: {
    'fill-color': [
      'interpolate',
      ['linear', 1],
      ['get', 'value'],
      0, '#3288bd',
      10, '#66c2a5',
      20, '#abdda4',
      30, '#fee08b',
      40, '#f46d43',
      50, '#d53e4f'
    ],
    opacity: 1
  }
});

// 添加到地图
scalarLayer.addTo(map);

使用图例配置

const scalarLayer = new MaptalksScalarFillLayer('scalar', gridData, {
  legend: {
    details: [
      { startValue: 0, endValue: 10, color: '#3288bd' },
      { startValue: 10, endValue: 20, color: '#66c2a5' },
      { startValue: 20, endValue: 30, color: '#abdda4' },
      { startValue: 30, endValue: 40, color: '#fee08b' },
      { startValue: 40, endValue: 50, color: '#f46d43' }
    ]
  },
  opacity: 0.8
});

动态更新数据

// 更新数据
scalarLayer.setData(newGridData);

// 更新透明度
scalarLayer.setOpacity(0.5);

// 更新配置
scalarLayer.setOptions({
  opacity: 0.6,
  wireframe: false
});

📖 API 文档

MaptalksScalarFillLayer

Maptalks 平台的标量填充图层。

构造函数

new MaptalksScalarFillLayer(id: string, data?: GridData, options?: MaptalksScalarFillLayerOptions)

参数：

• id - 图层唯一标识
• data - 网格数据（可选）
• options - 图层配置（可选）

配置项（MaptalksScalarFillLayerOptions）

interface MaptalksScalarFillLayerOptions {
  // 渲染配置
  opacity?: number;              // 透明度 (0-1)
  renderForm?: 'r';              // 渲染形式
  wireframe?: boolean;           // 是否显示线框
  
  // 样式配置（二选一）
  styleSpec?: StyleSpec;         // 使用样式表达式
  legend?: LegendOptions;        // 使用图例配置
  
  // 数据范围
  labelRange?: [number, number]; // 标签范围
  mappingRange?: [number, number]; // 映射范围
  
  // 网格配置
  widthSegments?: number;        // 宽度分段数
  heightSegments?: number;       // 高度分段数
  
  // WebGL 配置
  glOptions?: WebGLContextAttributes;
}

方法

setData(data: GridData | null): void

更新图层数据。

scalarLayer.setData({
  lonMin: 110, lonMax: 130,
  latMin: 20, latMax: 40,
  value: [[...], [...]]
});

setOpacity(opacity: number): this

设置图层透明度。

scalarLayer.setOpacity(0.5);

setOptions(options: MaptalksScalarFillLayerOptions): this

更新图层配置。

scalarLayer.setOptions({
  opacity: 0.7,
  wireframe: true
});

getData(): GridData | null

获取当前数据。

const data = scalarLayer.getData();

数据格式

GridData

interface GridData {
  lonMin: number;    // 最小经度
  lonMax: number;    // 最大经度
  latMin: number;    // 最小纬度
  latMax: number;    // 最大纬度
  value: Array<Array<number | 'NaN'>>;  // 二维网格数据
}

示例：

const gridData: GridData = {
  lonMin: 110,
  lonMax: 130,
  latMin: 20,
  latMax: 40,
  value: [
    [15.2, 16.5, 17.8, 'NaN', 19.1],  // 第一行
    [14.8, 15.9, 17.1, 18.4, 19.2],   // 第二行
    // ... 更多行
  ]
};

样式配置

StyleSpec（表达式样式）

interface StyleSpec {
  'fill-color': StyleAttrField;  // 颜色渐变配置
  opacity?: number;              // 透明度
  offset?: number;               // 偏移量
}

type StyleAttrField = [
  'interpolate',                          // 插值函数
  [InterpolationName, number],            // [插值类型, 基数]
  ['get', 'value'],                       // 取值字段
  ...Array<number | string>               // [值1, 颜色1, 值2, 颜色2, ...]
];

支持的插值类型：

• linear - 线性插值
• exponential - 指数插值
• cubic-bezier - 贝塞尔插值

示例：

const styleSpec: StyleSpec = {
  'fill-color': [
    'interpolate',
    ['linear', 1],
    ['get', 'value'],
    0, '#3288bd',      // 0°C -> 蓝色
    15, '#66c2a5',     // 15°C -> 青色
    25, '#fee08b',     // 25°C -> 黄色
    35, '#f46d43',     // 35°C -> 橙色
    45, '#d53e4f'      // 45°C -> 红色
  ],
  opacity: 1,
  offset: 0
};

LegendOptions（图例样式）

interface LegendOptions {
  details: LegendDetail[];
}

interface LegendDetail {
  startValue: number;  // 起始值
  endValue: number;    // 结束值
  color: string;       // 颜色（支持 hex、rgb、rgba）
}

示例：

const legend: LegendOptions = {
  details: [
    { startValue: -10, endValue: 0, color: '#3288bd' },
    { startValue: 0, endValue: 10, color: '#66c2a5' },
    { startValue: 10, endValue: 20, color: '#abdda4' },
    { startValue: 20, endValue: 30, color: '#fee08b' },
    { startValue: 30, endValue: 40, color: '#f46d43' }
  ]
};

🎨 示例

查看 examples/ 目录获取更多完整示例：

• 基础示例 - 最简单的使用方式
• 样式配置 - 各种样式配置示例
• 动态更新 - 数据动态更新
• 多图层 - 多个标量场图层

🏗️ 架构设计

src/
├── core/              # 核心渲染逻辑（平台无关）
│   ├── DataProcessor.ts       # 数据处理器
│   └── ScalarFillRenderer.ts  # 标量填充渲染器
├── platforms/         # 平台适配层
│   └── maptalks/              # Maptalks 适配
│       ├── MaptalksAdapter.ts
│       └── MaptalksScalarFillLayer.ts
├── webgl/            # WebGL 底层封装
│   ├── Base.ts       # 基础 WebGL 类
│   └── Fill.ts       # 填充渲染
├── utils/            # 工具函数
│   ├── gl-utils.ts   # WebGL 工具
│   ├── math.ts       # 数学工具
│   └── style-parser.ts # 样式解析
└── types/            # TypeScript 类型定义

设计原则：

• 核心渲染逻辑与平台无关
• 适配器模式支持多地图库
• WebGL 底层封装可复用

🔧 开发

# 安装依赖
pnpm install

# 开发模式（监听文件变化）
pnpm dev

# 构建
pnpm build

# 生产构建
pnpm build:prod

📦 构建产物

dist/
├── index.esm.js       # ES Module（推荐）
├── index.cjs.js       # CommonJS
├── index.js           # IIFE（浏览器直接引入）
├── index.umd.js       # UMD
└── index.d.ts         # TypeScript 类型声明

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🔗 相关链接

• Maptalks 官网
• WebGL 规范

⚠️ 浏览器兼容性

• Chrome >= 56
• Firefox >= 51
• Safari >= 11
• Edge >= 79

需要浏览器支持 WebGL 1.0。