gl-heatmap

高性能通用热力三维网格计算库，无外部依赖，支持 ESM、CJS、IIFE 多种模块格式，可无缝集成到各类前端项目与可视化场景。

特性

• 多模块支持：同时提供 ESM（ES 模块）、CJS（CommonJS）、IIFE（立即执行函数）格式，适配不同开发环境
• 轻量高效：无任何第三方依赖（如 Three.js），通过高斯表缓存、范围裁剪等优化实现高性能计算
• 类型安全：基于 TypeScript 开发，提供完整类型定义，支持 IDE 智能提示与类型校验
• 灵活配置：支持自定义热力点半径、模糊系数、坐标字段映射等核心参数
• 动态数据：提供 addData（追加）和 setData（替换）两种数据更新方式，满足实时渲染需求

模块格式与安装

支持的格式

• ESM：dist/esm/index.js（适用于现代浏览器、Vite、Webpack 等支持 ES 模块的环境）
• CJS：dist/cjs/index.js（适用于 Node.js 环境或 Webpack 等支持 CommonJS 的构建工具）
• IIFE：dist/iife/gl-heatmap.js（适用于直接通过 <script> 标签引入，暴露全局变量 GlHeatmap）

安装方式

1. 包管理器安装（推荐）

# npm
npm install gl-heatmap --save

# yarn
yarn add gl-heatmap

# pnpm
pnpm add gl-heatmap

2. 直接引入 IIFE 格式

<!-- 使用 CDN（需替换为实际 CDN 地址） -->
<script src="https://unpkg.com/gl-heatmap@latest/dist/index.global.js"></script>

快速开始

1. ESM 环境（如 Vite、现代浏览器）

import { Heatmap } from 'gl-heatmap';

// 创建热力图实例
const heatmap = Heatmap.create({
  width: 800,
  height: 600,
  defaultRadius: 25,
  defaultBlur: 0.6
});

// 添加数据
heatmap.addData([
  { x: 150, y: 200, value: 8 },
  { x: 400, y: 300, value: 12, radius: 35 }
]);

// 生成强度网格
const intensityGrid = heatmap.generate();

// 获取颜色
const color = Heatmap.getColor(0.7);

2. CJS 环境（如 Node.js、Webpack 旧版本）

const { Heatmap } = require('gl-heatmap');

// 用法与 ESM 一致
const heatmap = Heatmap.create({ width: 500, height: 500 });
heatmap.setData({ x: 250, y: 250, value: 10 });
const grid = heatmap.generate();

3. IIFE 环境（直接通过 <script> 引入）

<script src="https://unpkg.com/gl-heatmap@latest/dist/index.global.js"></script>
<script>
  // 通过全局变量 GlHeatmap 访问
  const heatmap = GlHeatmap.create({ width: 600, height: 400 });
  heatmap.addData([
    { x: 300, y: 200, value: 5 },
    { x: 400, y: 300, value: 8 }
  ]);
  const intensityGrid = heatmap.generate();
  console.log(intensityGrid); // Float32Array(600*400)
</script>

核心概念

• 热力点（HeatPoint）：包含坐标（x,y）、强度值（value）和影响半径（radius）的基础数据单元，决定热力图的原始数据分布。
• 强度网格：通过高斯分布算法计算的二维网格数据，每个单元格值为 0~1 的归一化强度，反映该位置的热力聚集程度。
• 颜色映射：将强度值（0~1）映射为 RGB 颜色的过程，默认从蓝色（低强度）到红色（高强度）渐变，用于最终可视化渲染。

API 文档

类型定义

HeatmapConfig（配置项）

| 属性 | 类型 | 默认值 | 说明 | |----------------|--------|----------|--------------------------| | defaultRadius | number | 20 | 热力点默认影响半径 | | defaultBlur | number | 0.7 | 模糊系数（0~1，值越大边缘越模糊） | | xField | string | 'x' | 数据中 x 坐标的字段名 | | yField | string | 'y' | 数据中 y 坐标的字段名 | | valueField | string | 'value' | 数据中强度值的字段名 | | width | number | 200 | 网格宽度（列数） | | height | number | 200 | 网格高度（行数） |

HeatPoint（热力点数据）

| 属性 | 类型 | 可选 | 说明 | |--------|--------|------|---------------------------------------| | x | number | 必选 | x 坐标（需在 0~width 范围内） | | y | number | 必选 | y 坐标（需在 0~height 范围内） | | value | number | 可选 | 强度值（默认 1，需 >0） | | radius | number | 可选 | 影响半径（默认使用 defaultRadius，需 >0） |

RGBColor（颜色类型）

| 属性 | 类型 | 说明 | |------|--------|---------------------| | r | number | 红色通道（0~1 范围） | | g | number | 绿色通道（0~1 范围） | | b | number | 蓝色通道（0~1 范围） |

Heatmap 静态工具

Heatmap.create(config?: Partial<HeatmapConfig>): HeatStore

创建热力数据存储实例，支持部分配置覆盖默认值。

// 示例：自定义坐标字段和网格大小
const heatmap = Heatmap.create({
  width: 1000,
  height: 800,
  xField: 'longitude', // 映射经度字段
  yField: 'latitude'   // 映射纬度字段
});

Heatmap.getColor(intensity: number): RGBColor

根据强度值（0~1）计算对应的 RGB 颜色，默认渐变规则：

• 0 → 蓝色（0,0,1）
• 0.2 → 青色（0,1,1）
• 0.4 → 绿色（0,1,0）
• 0.6 → 黄色（1,1,0）
• 0.8 → 橙色（1,0.5,0）
• 1 → 红色（1,0,0）

Heatmap.gaussianRandom(): number

生成符合正态分布的随机数，可用于模拟热力点数据。

HeatStore 实例方法

addData(data: HeatPoint | HeatPoint[]): void

追加热力点数据（保留现有数据，新数据与原有数据叠加计算）。

setData(data: HeatPoint | HeatPoint[]): void

替换所有热力点数据（先清空现有数据，再添加新数据）。

generate(): Float32Array

计算并返回归一化的热力强度网格，数组长度为 width * height，每个元素值为 0~1。

高级用法

结合 WebGL 渲染

生成的 intensityGrid 可作为纹理数据传入 WebGL 进行渲染，核心步骤：

function renderHeatmap(gl, intensityGrid, width, height) {
  // 创建纹理并绑定
  const texture = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, texture);
  
  // 写入强度网格数据
  gl.texImage2D(
    gl.TEXTURE_2D,
    0,
    gl.LUMINANCE,
    width,
    height,
    0,
    gl.LUMINANCE,
    gl.FLOAT,
    intensityGrid
  );
  
  // 配置纹理参数
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
  
  // 在片段着色器中通过强度值采样颜色
  //（需结合 Heatmap.getColor 的逻辑实现着色器代码）
}

构建说明

库的构建输出位于 dist 目录：

• dist/esm：ES 模块格式，支持 import 导入
• dist/cjs：CommonJS 格式，支持 require 导入
• dist/iife：立即执行函数，可通过 <script> 直接引入，暴露全局变量 GlHeatmap

许可证

MIT License