Zoom Band Chart

The Zoom band chart is generally a complementary chart type used in conjunction with 1 or more XY charts. Usually, it is used to display the full range of data at a completely zoomed out level, while allowing the user to inspect the data closer up in the ChartXY.

The Zoom band chart makes it convenient for users to interact with the displayed data range. For example, you can drag on the zoom band to move the view around, or click on a position that you want to see.

// Creation of a Zoom band chart
const lc = lightningChart()
const zoomBandChart = lc.ZoomBandChart()

Access to LightningChart resources

The Zoom band chart feature utilizes static file assets distributed along side LightningChart library. These are used by the built-in themes to display the "Knobs" that users can interact with. In order to display these picture assets, setting up local hosting of LC resources is needed.

This is optional, and only side effects are 1) Knobs don't show up 2) File not found error in console

For instructions of setting up LightningChart resources, please see LightningChart resources

Adding series to Zoom band chart

The idea of Zoom band chart is that it displays copies of series that belong to some other ChartXY. Series are attached to zoom band chart with add method:

const lc = lightningChart()
const chartXY = lc.ChartXY()
const lineSeries = chartXY.addLineSeries()
    .appendSamples({ yValues: [10, 12, 15, 8, 5] })
const zoomBandChart = lc.ZoomBandChart()
// (!)
zoomBandChart.add(lineSeries)

The zoom band chart automatically matches and displays any data changes to the original series.

Styling series in Zoom band chart

By default, copied series in Zoom band chart use exactly same style as the original series. Alternatively, you can apply a different style to the series in Zoom band chart:

const zbcSeries = zoomBandChart.add(lineSeries)
    .setStrokeStyle((stroke) => stroke.setThickness(1))

For more details about style API, please see Styles, colors and fonts.

Removing series

Series can be removed from Zoom band chart using disposeSeries method:

// Example, remove series from being displayed in zoom band chart
// NOTE: parameter should be the "original series"
zoomBandChart.disposeSeries(lineSeries)

This needs to be done only when you want to remove a series from zoom band chart. If you are removing the original series, then it is enough to dispose() that series to destroy it, which will automatically be reflected in Zoom band chart also.

Axis

Zoom band chart automatically mimics the axis of its attached series. For example, if you add a series to the Zoom band chart which is attached to a Date-Time axis, the Zoom band chart will also use a Date-Time axis. Otherwise, Zoom band chart axes work the same as ChartXY axes.

When using Date-Time axis with small time ranges (few days or smaller), you need to enable "high precision axis":

const zoomBandChart = lc.ZoomBandChart({
    defaultAxis: {
        type: 'linear-highPrecision'
    }
})

For more information, APIs and guides about Axis, please refer to common Axis section.

Vertical orientation

By default, Zoom band chart works on a "horizontal" manner, taking the X Axis of series as the "shared" axis (usually Date-Time). This can be also changed to "vertical":

const zoomBandChart = lc.ZoomBandChart({ orientation: 'y' })

Shared value axis

Zoom band chart can display several series at once. These series can also be attached to different Y axis, and might represent different units (Voltage, Temperature, etc.). However, in Zoom band chart all the series are displayed in the same series area, without separating the different Y axes.

By default, every unique value axis in Zoom band chart will have its own scale. For example, if you attach 2 series with different value axes, those series values will not be comparable to each other in the Zoom band chart:

On the other hand, if the 2 series belong to the same value axis (Y in this case), then they will share the same scale in Zoom band chart and be comparable:

There is also an option to force every series in Zoom band chart to use the same value Axis, even if the series belong to different value axes. This also shows the value axis ticks, as there is only 1 value axis in Zoom band chart to display in contrast to having several different axes.

const zoomBandChart = lc.ZoomBandChart({ useSharedValueAxis: true })

Axis layout

When the main chart has multiple Y axes with stacking (iStack) or parallel positioning (iParallel), you can configure the Zoom band chart to mirror this layout.

By default, all series in the Zoom band chart overlap in the same area regardless of their axis positioning in the main chart. With useAxisLayouts: true, the Zoom band chart will display each series according to its axis position, matching the main chart's layout:

const chart = lc.ChartXY()
chart.getDefaultAxisY().dispose()

// Create stacked axes in main chart
const axisY1 = chart.addAxisY({ iStack: 0 }).setTitle('Temperature')
const axisY2 = chart.addAxisY({ iStack: 1 }).setTitle('Pressure')
const axisY3 = chart.addAxisY({ iStack: 2 }).setTitle('Humidity')

const series1 = chart.addLineSeries({ axisY: axisY1 })
const series2 = chart.addLineSeries({ axisY: axisY2 })
const series3 = chart.addLineSeries({ axisY: axisY3 })

// Create Zoom band chart that mirrors the stacked layout
const zoomBandChart = lc.ZoomBandChart({ useAxisLayouts: true })
zoomBandChart.add(series1)
zoomBandChart.add(series2)
zoomBandChart.add(series3)

note

useAxisLayouts and useSharedValueAxis are mutually exclusive. If both are set, useSharedValueAxis takes precedence.

You can optionally override the axis position for each series when adding to the Zoom band chart:

zoomBandChart.add(series1, { iStack: 2 })
zoomBandChart.add(series2, { iStack: 1 })
zoomBandChart.add(series3, { iStack: 0 })

If not specified, the Zoom band chart mirrors the source axis positions automatically.

Configuring view

The position of the band is not configured via Zoom band chart, but rather the attached axis itself.

chartXY.axisX.setInterval({ start: 0, end: 100 })

For more details, refer to Axis.

Monitoring view change

Zoom band chart doesn't expose a function for tracking changes to displayed view. However, the attached axes have interval change event which is triggered when Zoom band chart is interacted with:

chartXY.axisX.addEventListener('intervalchange', (event) => {
    console.log(event)
})

Automatic alignment between Zoom band chart and attached charts

By default, Zoom band chart aligns itself against attached charts. This is done by assuming that the charts are laid on top of each other, or next to each other.

However, it is also a valid use case to not align ZBC and the other charts. In this case, you probably want to remove the automatic alignment of ZBC:

// By explicitly configuring ZBC padding, automatic alignment to other charts is disabled
zoomBandChart.setPadding({ left: 10, right: 10, top: 0 })

Zoom band chart style

The Zoom band charts splitters and defocus overlay can be styled individually:

zoomBandChart
    .setSplitterStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(255, 255, 255) }) }))
    .setDefocusOverlayFillStyle(new SolidFill({ color: ColorRGBA(0, 0, 0, 150) }))

For more details about style API, please see Styles, colors and fonts.

Chart title

zoomBandChart
    .setTitle('Voltage')
    .setTitleFont(font => font.setSize(10).setFamily('Segoe UI'))
    .setTitleFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))

For more details about style API, please see Styles, colors and fonts.

Background style

ZoomBandChart has 3 different levels of backgrounds:

• Series background (area enclosed by axes)
• Chart background (entire chart area)
• Engine background (additional background shared by entire engine)
  • Understanding difference between chart/engine background is mainly useful if you are using the legacy Dashboard feature - in this case, engine background is shared across the whole dashboard.

zoomBandChart
    .setBackgroundFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    .setSeriesBackgroundFillStyle(new SolidFill({ color: ColorRGBA(0, 255, 0) }))
    .setSeriesBackgroundStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 0, 255) }) }))
zoomBandChart.engine.setBackgroundFillStyle(new SolidFill({ color: ColorRGBA(0, 0, 255) }))

For more details about style API, please see Styles, colors and fonts.

Space around chart

zoomBandChart.setPadding({ left: 10, right: 10, top: 10, bottom: 10 })

Disable animations

const zoomBandChart = lc.ZoomBandChart({ animationsEnabled: false })

Positioning charts

Please see common Positioning charts section.

Color themes

Please see common Color themes section.