首页 / deck.gl / API 文档

HeatmapLayer

先看结论

在 GPU 上把点核密度化，得到连续的密度场。

最后验证 2026-11-03 · deck.gl 9.0 · 更新 2026-10-27 · 引用本文

new deck.HeatmapLayer(props)

核心参数

参数	默认	说明
`data`	`[]`	点数据数组
`getPosition`	—	返回 `[经度, 纬度]`
`getWeight`	`1`	每个点对密度的贡献，可表达流量、人口
`radiusPixels`	`20`	核半径，屏幕像素，不随缩放变化
`intensity`	`1`	整体亮度倍率，调高会更早饱和
`threshold`	`0.05`	低于该值的密度不绘制，去掉稀疏噪点
`colorRange`	内置蓝紫渐变	`[[r, g, b], …]`，至少两档
`colorDomain`	`[0, 1]`	把密度值映射到色带的值域
`aggregation`	`'SUM'`	`'SUM'` 或 `'MEAN'`
`weightsTextureSize`	`2048`	权重纹理边长，越大越精细也越占显存

色带怎么写

色带是按密度线性插值的离散色标，通常给 5–7 档。第一档往往用全透明，让密度场边缘自然淡出。

var colorRange = [
  [0, 20, 60, 0],
  [18, 70, 130, 120],
  [30, 130, 190, 190],
  [250, 200, 70, 220],
  [245, 110, 45, 235],
  [210, 30, 40, 255]
];

var layer = new deck.HeatmapLayer({
  id: 'heat',
  data: points,
  getPosition: function (d) { return [d.lng, d.lat]; },
  getWeight: function (d) { return d.weight; },
  radiusPixels: 42,
  intensity: 1.1,
  threshold: 0.04,
  colorRange: colorRange,
  pickable: false
});

半径与缩放的关系

radiusPixels 以屏幕像素计，所以放大时密度场不会跟着地形放大，而是保持同样的视觉尺度。这会让同一个点在不同层级下覆盖的地理范围不同：缩得越近，一个核对应的实际面积越小。

需要「固定地理半径」的效果，就不要用 HeatmapLayer，改用 HexagonLayer 或 GridLayer，这两者的 radius / cellSize 以米为单位。

阈值与强度

密度值归一化在 0–1 之间。threshold 决定画不画， intensity 在归一化之前放大权重之和。稀疏数据看不清时，先加大 intensity；大片底色发灰时，抬高 threshold。

现象	调整
整屏都有淡色，看不到热点	提高 `threshold` 到 0.1–0.2
热点只有一小块纯色	降低 `intensity`，加长 `colorRange`
边缘生硬	色带首档设 alpha 为 0
密度差异被压平	用 `getWeight` 拉开数值差距，而不是调亮度

HeatmapLayer 不参与拾取。它输出的是连续密度场，没有单条数据可供命中。需要点击查询时，另加一个透明的 ScatterplotLayer 承担拾取，或在聚合图层上做。

引用本文

经纬志（2026）。《HeatmapLayer》。https://www.jingweizhi.com/deckgl/api/heatmap-layer.html（访问日期 2026-11-03）。