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.addPointLineAreaSeries({ dataPattern: 'ProgressiveX' })
    .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 })

Monitoring view change

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

chartXY.getDefaultAxisX().onIntervalChange((axis, start, end) => {
    console.log('x view', start, end)
})

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.