高斯核2D热力图heatmap-gauss
heatmap-gauss
一个无渲染逻辑、跨环境兼容的高斯核2D热力图计算库，基于TypeScript开发，专注于热力图核心数据的生成与处理，支持浏览器和Node.js双环境，将渲染控制权完全交给使用者，灵活适配各类可视化场景。
🌟 核心特性
- 无渲染依赖：仅提供热力图数据计算能力，不绑定任何渲染引擎（如Canvas、SVG），用户可自定义渲染逻辑。
- 双环境兼容：纯TypeScript实现，不依赖浏览器或Node.js特定API，无缝运行于浏览器和Node.js环境。
- 高斯核精确计算：基于标准高斯函数（G(d)=e−d22σ2G(d) = e^{-\frac{d^2}{2\sigma^2}}G(d)=e−2σ2d2）计算点的影响范围，热力过渡平滑自然。
- 高效性能优化：采用「3σ原则」限制计算范围（覆盖高斯分布99.7%的能量），平衡计算精度与性能。
- 灵活数据输出：支持两种核心数据格式（网格数据/归一化点数据），适配不同渲染需求。
- 完整类型支持：内置TypeScript类型定义，提供清晰的类型提示，提升开发体验。
📦 安装
通过npm或yarn安装：
# npm
npm install heatmap-gauss --save# yarn
yarn add heatmap-gauss
🚀 快速开始
以下示例分别展示在浏览器和Node.js环境中的基础用法。
1. 浏览器环境示例
import { GaussianHeatmap } from 'heatmap-gauss';// 1. 创建热力图计算实例
const heatmap = new GaussianHeatmap({width: 800, // 热力图宽度（单位：像素）height: 600, // 热力图高度（单位：像素）cellSize: 5, // 网格单元格大小（单位：像素，越小精度越高）sigma: 25, // 高斯核标准差（控制扩散范围，越大扩散越广）maxValue: 10 // 可选，强度最大值（用于归一化，不指定则自动计算）
});// 2. 添加数据点（x/y为坐标，value为强度值）
heatmap.addPoints([{ x: 150, y: 200, value: 6 },{ x: 300, y: 400, value: 9 },{ x: 600, y: 300, value: 7 },{ x: 450, y: 500, value: 5 }
]);// 3. 获取计算结果（二选一，根据渲染需求）
// 方式1：获取网格数据（适合批量渲染，如Canvas像素填充）
const gridData = heatmap.getGridData();
console.log('网格数据:', gridData);// 方式2：获取归一化点数据（适合逐个点渲染，如SVG圆）
const normalizedPoints = heatmap.getNormalizedDataPoints();
console.log('归一化点数据:', normalizedPoints);// 4. 自定义渲染（示例：浏览器中用Canvas渲染网格数据）
const canvas = document.getElementById('heatmap-canvas');
const ctx = canvas.getContext('2d');
if (ctx) {canvas.width = gridData.width;canvas.height = gridData.height;// 遍历网格，根据强度值填充颜色（自定义颜色映射）for (let row = 0; row < gridData.data.length; row++) {for (let col = 0; col < gridData.data[row].length; col++) {const intensity = gridData.data[row][col] / gridData.maxValue; // 归一化到0-1const color = `rgba(255, ${Math.floor(255 * (1 - intensity))}, 0, ${intensity * 0.8})`;ctx.fillStyle = color;ctx.fillRect(col * gridData.cellSize,row * gridData.cellSize,gridData.cellSize,gridData.cellSize);}}
}
2. Node.js环境示例
const { GaussianHeatmap } = require('heatmap-gauss');
const fs = require('fs').promises;
const path = require('path');// 1. 创建热力图计算实例
const heatmap = new GaussianHeatmap({width: 800,height: 600,cellSize: 5,sigma: 25
});// 2. 生成并添加随机数据点
function generateRandomPoints(count = 100) {const points = [];for (let i = 0; i < count; i++) {points.push({x: Math.random() * 800, // 随机x坐标（0-800）y: Math.random() * 600, // 随机y坐标（0-600）value: 1 + Math.random() * 9 // 随机强度（1-10）});}return points;
}
heatmap.addPoints(generateRandomPoints());// 3. 获取网格数据并保存到文件
async function saveHeatmapData() {const gridData = heatmap.getGridData();await fs.writeFile(path.join(__dirname, 'heatmap-data.json'),JSON.stringify(gridData, null, 2),'utf8');console.log('热力图数据已保存到 heatmap-data.json');
}// 执行保存
saveHeatmapData().catch(console.error);// 后续可将数据传递给 node-canvas 等库进行渲染
📚 API 文档
1. 构造函数 GaussianHeatmap(options)
创建热力图计算实例，options 参数如下：
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
width | number | 必传 | 热力图整体宽度（单位：像素） |
height | number | 必传 | 热力图整体高度（单位：像素） |
cellSize | number | 5 | 网格单元格大小（单位：像素），越小精度越高，计算量越大 |
sigma | number | 20 | 高斯核标准差，控制数据点的扩散范围，越大扩散越广，热力越平滑 |
maxValue | number | undefined | 强度最大值（用于归一化），不指定则自动计算所有点的最大强度值 |
2. 实例方法
addPoint(point: HeatPoint): void
添加单个数据点。
HeatPoint类型：{ x: number; y: number; value: number }x/y：点的坐标（需在[0, width]/[0, height]范围内）value：点的强度值（正数，值越大热力越显著）
示例：
heatmap.addPoint({ x: 200, y: 300, value: 7 });
addPoints(points: HeatPoint[]): void
批量添加多个数据点。
示例：
heatmap.addPoints([{ x: 100, y: 200, value: 5 },{ x: 300, y: 400, value: 9 }
]);
clear(): void
清空所有数据点和计算结果，重置实例状态。
示例：
heatmap.clear();
getGridData(): GridData
获取网格格式的热力图数据（适合批量渲染）。
GridData类型：interface GridData {width: number; // 热力图宽度（同构造函数参数）height: number; // 热力图高度（同构造函数参数）cellSize: number; // 单元格大小（同构造函数参数）sigma: number; // 高斯核标准差（同构造函数参数）minValue: number; // 所有单元格的最小强度值maxValue: number; // 所有单元格的最大强度值data: number[][]; // 二维数组，[row][col] 对应单元格的强度值 }
getNormalizedDataPoints(): NormalizedPoint[]
获取归一化后的点数据（适合逐个点渲染，如粒子效果）。
NormalizedPoint类型：interface NormalizedPoint {x: number; // 点的原始x坐标y: number; // 点的原始y坐标value: number; // 点的原始强度值normalizedValue: number;// 归一化后的强度值（0-1，基于 maxValue）radius: number; // 点的影响半径（基于 sigma，即 3*sigma） }
setSigma(sigma: number): void
动态修改高斯核标准差（sigma），修改后需重新添加数据点生效。
示例：
heatmap.setSigma(30); // 扩大扩散范围
heatmap.clear();
heatmap.addPoints(/* 重新添加数据 */);
getSigma(): number
获取当前高斯核标准差（sigma）。
📊 数据格式说明
1. 网格数据（GridData）
- 核心是
data二维数组，每个元素代表对应单元格的强度值。 - 适合批量渲染场景（如Canvas像素填充、SVG矩形网格）。
- 渲染时可根据
minValue/maxValue将强度值归一化到 0-1，再映射到自定义颜色梯度。
2. 归一化点数据（NormalizedPoint）
- 每个数据点包含归一化后的强度和影响半径，适合逐个渲染（如Canvas圆、SVG圆）。
radius为3*sigma（基于3σ原则），确保覆盖点的主要影响范围。
🎯 适用场景
- 自定义渲染需求：需要使用Canvas、SVG、WebGL等不同渲染引擎的场景。
- 跨环境计算：在浏览器中预处理数据，或在Node.js中批量生成热力图数据。
- 数据可视化预处理：为ECharts、D3.js等可视化库提供高斯核热力图数据。
- 高精度热力计算：对热力过渡平滑度要求高的场景（如用户行为分析、物理场模拟）。