Scrolling heatmap

A variant of Heatmap, this feature is suitable for streaming applications where data is measured and visualized in real-time.

Scrolling heatmaps work same as Static heatmaps for the most part. The main differences are creation syntax and data input.

// Creation of scrolling heatmap series
const heatmapSeries = chart.addHeatmapScrollingGridSeries({
    // Scroll along X axis
    scrollDimension: 'columns',
    // Each sample has 5 values
    resolution: 5,
})
    .setStart({ x: 0, y: 0 })
    .setStep({ x: 1, y: 1 })

Data input

A sample is added to a scrolling heatmap with addIntensityValues method:

heatmapSeries.addIntensityValues([
    [0, 1, 2, 3, 4]
])

Alternatively, invalidateIntensityValues can also be used. This lets you control which sample index you are defining.

Using timestamps

Most use cases of scrolling heatmaps use timestamped data. In these cases, samples realistically don't always arrive with the same time step. Generally this is worked around by configuring a "minimum perceived time step" for the heatmap:

// Minimum time step that can be displayed by the heatmap
// Smaller value means more precision but more RAM and GPU memory usage.
const heatmapMinTimeStepMs = 1 // 1 millisecond
heatmapSeries.setStep({ x: heatmapMinTimeStepMs, y: 1 })

Then, input data is mapped from timestamps to "heatmap sample index", and inserted to heatmap using invalidateIntensityValues method. This also works even if data doesn't come in correct time order.

let tFirstSample: number | undefined
const handleIncomingData = (timestamp, sample) => {
    if (!tFirstSample) {
        tFirstSample = timestamp
        heatmapSeries.setStart({ x: timestamp, y: 0 })
    }
    // Calculate sample index from timestamp to place sample in correct location in heatmap.
    const iSample = Math.round((timestamp - tFirstSample) / heatmapMinTimeStepMs)
    heatmapSeries.invalidateIntensityValues({
        iSample,
        values: [sample],
    })
}

The heatmap automatically fills any gaps between samples by repeating the previous sample value. So, actually 1 sample can occupy several data slots in the heatmap.

info

If the axis doesn't let you zoom in far enough, consider enabling "high precision" axis

Data cleaning

// Enable automatic cleaning of data that is not visible
heatmapSeries.setDataCleaning({ minDataPointCount: 1 })

Scrolling heatmap doesn't currently have a method to control maximum memory usage precisely. setDataCleaning effectively enables "lazy" data cleaning, which will prevent applications from running out of memory, but when this data cleaning exactly happens is not guaranteed.