Class PointLineAreaSeries

Deprecated

Use appendJSON instead

Deprecated

Use appendSamples instead

Add callback function to be triggered when specified event is fired.

 // Example syntax
 object.addEventListener('click', (event) => {
     console.log(event)
 })

Some classes also report extra information about the interacted object with the second parameter:

 // Most series share information about interacted data point
 series.addEventListener('click', (event, info) => {
     console.log(info)
 })

Optional third parameter allows registering event handlers that will automatically remove themselves after first trigger:

 // Example this listener will only fire once
 object.addEventListener('click', (event) => {})

Each class has its own list of supported events. Some events are from HTML standard (click, pointerdown, etc.), while others are own events from LightningChart JS (dispose, resize, etc.)

To find what events are available, you can try following:

• If your development environment has TypeScript enabled, just write addEventListener and see what possible event types the IDE suggests. These APIs are strongly typed, and even the callback event will be correctly typed.
• Otherwise, open the class section in API documentation and check out which interface K type parameter extends.

Alter existing samples in the data set. This method also supports automatically appending samples when attempting to alter samples that don't exist in data set.

This method alters existing samples by referencing sample indexes. This simply refers to a incrementing counter of when each sample was first introduced. For example, 0 refers to first sample that was added to data set. When data cleaning is enabled, sample indexes do NOT shift. They always point to unique samples, even if old samples are removed.

 // Example, basic usage - set first sample to { x: 0, y: 0 }
 DataSetXY.alterSamples(0, {
     xValues: [0],
     yValues: [1]
 })

 // Example, alter several samples at once - set first sample to { x: 0, y: 10 }, second sample to { x: 1, y: 11 } and so on.
 DataSetXY.alterSamples(0, {
     xValues: [0, 1, 2],
     yValues: [10, 11, 12]
 })

 // Example, alter last sample to have Y = 0.
 DataSetXY.alterSamples(DataSetXY.getNextSampleIndex() - 1, {
     yValues: [0]
 })

See also alterSamplesByID.

Returns

Object itself.

Alter existing samples in the data set.

This method alters existing samples by referencing their ID properties. The ID property is an optional sample number property, which CAN be specified by the user. They have to be enabled using ids and afterwards can be added alongside other data properties, like x, y, etc.

 // Example, basic usage
 const dataSet = new DataSetXY({ ids: true })
 dataSet.appendSamples({
     ids: [0, 1, 2],
     yValues: [10, 12, 7],
 })
 dataSet.alterSamplesByID([1], {
     yValues: [20]
 })
 // result yValues = [10, 20, 7]

 // Example, apply same value to all altered samples
 dataSet.alterSamplesByID([0, 1, 2], { size: 5 })

See also alterSamples.

Returns

Object itself.

Add several samples from JSON by reading values from instructed property names.

 // Example, read x + y
 const arr = [{ x: 0, y: 0 }]
 DataSetXY.appendJSON(arr, { x: 'x', y: 'y' })

 // Example, read custom property names
 const arr = [{ timestamp: 0, voltage: 0 }]
 DataSetXY.appendJSON(arr, { x: 'timestamp', y: 'voltage' })

 // Example, only Y values
 const arr = [{ price: 0 }]
 DataSetXY.appendJSON(arr, { y: 'price' })

 // Example, color values
 const arr = [{ x: 0, y: 0, color: 0xff0000ff }]
 DataSetXY.appendJSON(arr, { x: 'x', y: 'y', color: 'color' })

Please note that before adding optional values (lookup values, ids or colors), they need to be enabled using colors or equivalent!

Supported sample property types:

• x: number, Date object or Date time string
• y: number, Date object or Date time string
• lookupValue: number
• id: number
• color: either Color object or number which represents a Uint32 RGBA color with Red channel being least significant byte. Note that using Color objects in large quantities should be avoided for performance reasons.
  • See uint32ColorFromRGBA

Returns

Object itself.

Add 1 sample to data set.

 // Example, basic usage
 DataSetXY.appendSample({ x: 0, y: 0 })

 // Example, only Y value with automatic X step
 DataSetXY.appendSample({ y: 0, step: 1 })

 // Example, extra properties (color)
 DataSetXY.appendSample({ x: 0, y: 0, color: 0xff0000ff })

Please note that before adding optional values (lookup values, ids or colors), they need to be enabled using colors or equivalent!

Supported sample property types:

• x: number, Date object or Date time string
• y: number, Date object or Date time string
• lookupValue: number
• id: number
• size: number
• rotation: number
• color: either Color object or number which represents a Uint32 RGBA color with Red channel being least significant byte. Note that using Color objects in large quantities should be avoided for performance reasons.
  • See uint32ColorFromRGBA

Returns

Object itself.

Add a list of samples to data set.

 // Example, basic usage.
 DataSetXY.appendSamples({
     xValues: [0, 1, 2],
     yValues: [100, 101, 102],
 })

 // Example, only Y values with automatic X step
 DataSetXY.appendSamples({
     yValues: [100, 101, 102],
     start: 0,
     step: 1,
 })

 // Example, typed array input.
 DataSetXY.appendSamples({
     yValues: new Float32Array([100, 101, 102]),
 })

 // Example, extra properties (color)
 DataSetXY.appendSamples({
     xValues: [0, 1, 2],
     yValues: [100, 101, 102],
     colors: [0xff0000ff, 0xff00ff00, 0xffff0000]
 })

Please note that before adding optional values (lookup values, ids or colors), they need to be enabled using colors or equivalent!

Supported sample property types:

• x: number, Date object or Date time string
• y: number, Date object or Date time string
• lookupValue: number
• id: number
• size: number
• rotation: number
• color: either Color object or number which represents a Uint32 RGBA color with Red channel being least significant byte. Note that using Color objects in large quantities should be avoided for performance reasons.
  • See uint32ColorFromRGBA

offset properties can optionally be used to start reading values from middle of input array. Can be situationally useful.

Returns

Object itself.

Clear all samples in the data set.

Returns

Object itself.

Load same value or many values to all samples that currently exist in the data set.

 // Example, set point size of all samples to 5 pixels
 DataSetXY.fill({ size: 5 })

Returns

Object itself.

Get current area fill style.

Returns

FillStyle object.

Get active curve preprocessing mode.

Returns

CurvePreprocessing interface

Get active data set of the series.

Get current configured maximum sample count. See setMaxSampleCount for more information.

Returns

Number of undefined.

Get next new sample index. This also counts old samples that have been dropped out by data cleaning logic.

Returns

Number.

Get alignment of points. Defaults to center { x: 0, y: 0 }.

Can be used to offset points relative to their size.

Released as beta feature in v5.2.0 feature may still change according to user feedback and experiences.

Get current markers fill style.

Returns

FillStyle object.

Get the current rotation of points as degrees.

Get current shape of displayed points.

Returns

PointShape.

Get current size of points in pixels.

Returns

Size of point in pixels.

Get number of samples currently existing in the data set. This does NOT count any samples that have been dropped out by data cleaning logic.

Returns

Number.

Get stroke style of Series.

Returns

LineStyle object

Read back the current contents of the data set.

 // Read back data
 const data = DataSetXY.readBack()
 console.log(data)

If data cleaning (max sample count) is enabled, this can result in allocating new memory (and thus be expensive). Otherwise, a very efficient operation.

The returned values should NOT be modified.

Optionally, you can include the flag onlyInRange to find return only samples that are in specified range. This is only supported if the data set has a "data pattern" (e.g. { dataPattern: 'ProgressiveX' }). The range is always considered to be in the same dimension as this data pattern (e.g. X Axis).

 // Example, read back data that is visible
 ChartXY.getDefaultAxisX().onIntervalChange((axis, start, end) => {
     const data = DataSetXY.readBack({ onlyInRange: { start, end } })
     console.log(data)
 })

This operation is not "pixel perfect", meaning it can often return 1 extra sample that is not visible (the next and/or previous ones).

Returns

Object with lists of separate data channels, like x coordinates, y coordinates, look up values, colors, etc.

Remove event listener added using addEventListener. The expected argument should be the exact same callback function that was supplied using addEventListener:

 // Basic example syntax
 const listener = () => {}
 obj.addEventListener('click', listener)
 obj.removeEventListener('click', listener)

 // Basic boilerplate of custom interaction when user drags on an object
 obj.addEventListener('pointerdown', (eventDown) => {
     let prevCoord = eventDown
     const handlePointerMove: LCJSInteractionEventListener<'pointermove'> = (eventMove) => {
         const delta = { x: eventMove.clientX - prevCoord.clientX, y: eventMove.clientY - prevCoord.clientY }
         prevCoord = eventMove
         console.log(delta, eventMove.clientX, eventMove.clientY)
     }
     const handlePointerUp: LCJSInteractionEventListener<'pointerup'> = (eventUp) => {
         window.removeEventListener('pointermove', handlePointerMove)
         window.removeEventListener('pointerup', handlePointerUp)
     }
     window.addEventListener('pointermove', handlePointerMove)
     window.addEventListener('pointerup', handlePointerUp)
 })

Set fill style of area under the series trend.

Supported fill styles:

SolidFill:

Solid color for entire area fill.

 // Example, solid colored area fill.
 PointLineAreaSeries.setAreaFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))

To learn more about available Color factories, see ColorRGBA

PalettedFill:

Supports following look-up modes: x, y and value.

lookUpProperty: 'x' | 'y':

Color dynamically based on x or y coordinate.

 // Example, dynamic color by Y coordinates
 PointLineAreaSeries.setAreaFillStyle(new PalettedFill({
     lookUpProperty: 'y',
     lut: new LUT({
         interpolate: true,
         steps: [
             { value: 0, color: ColorRGBA(255, 0, 0) },
             { value: 100, color: ColorRGBA(0, 255, 0) },
         ]
     })
 }))

To learn more about Color lookup tables, see LUT.

lookUpProperty: 'value':

Color dynamically based on separately supplied value data set. values are specified when adding data points.

 // Example, dynamic color by Value data set
 const series = ChartXY.addPointLineAreaSeries({ lookupValues: true })
     .setAreaFillStyle(new PalettedFill({
         lookUpProperty: 'value',
         lut: new LUT({
             interpolate: true,
             steps: [
                 { value: 0, color: ColorRGBA(255, 0, 0) },
                 { value: 100, color: ColorRGBA(0, 255, 0) },
             ]
         })
     }))
     .appendSamples({
         yValues: [0, 1],
         lookupValues: [0, 100]
     })

Data point lookup value properties have to be explicitly enabled before they can be used, see lookupValues for more details.

To learn more about Color lookup tables, see LUT.

IndividualPointFill:

Color area fill with individually picked sample colors. Colors are interpolated between data points.

 // Example, individual colors
 const series = ChartXY.addPointLineAreaSeries({ colors: true })
     .setAreaFillStyle(new IndividualPointFill())
     .appendSamples({
         yValues: [0, 1],
         colors: [0xff0000ff, 0xff00ff00]
     })

Data point color properties have to be explicitly enabled before they can be used, see colors for more details.

LinearGradientFill:

Color area fill with a linear gradient.

 // Example, linear gradient area fill
 PointLineAreaSeries.setAreaFillStyle(new LinearGradientFill())

To learn more about linear gradient configurations, see LinearGradientFill.

RadialGradientFill:

Color area fill with a radial gradient.

 // Example, radial gradient line color
 PointLineAreaSeries.setAreaFillStyle(new RadialGradientFill())

To learn more about radial gradient configurations, see RadialGradientFill.

Returns

Object itself for fluent interface.

Set curve preprocessing mode. See CurvePreprocessing for more information.

 // Example, enable step preprocessing
 PointLineAreaSeries.setCurvePreprocessing({ type: 'step', step: 'middle' })

Returns

Object itself.

Set data set which the series visualizes. This can be changed at any point.

If data set is not set using this method, then the series creates it automatically as soon as data is pushed in.

 // Example
 const dataSet = new DataSetXY()
 PointLineAreaSeries.setDataSet(dataSet)

All real-time use cases (where data points are pushed in periodically) must define a "max sample count".

 // Example, keep maximum 1 million samples
 PointLineAreaSeries.setMaxSampleCount(1_000_000)

This allocates the required amount of memory beforehand, which is crucial to get the best performance. After 1 million samples are reached, the oldest samples will start dropping out.

Alternatively, if you are uncertain what value to use and don't want to allocate too much memory up-front, you can start small and automatically increase the buffer size as samples flow in:

 PointLineAreaSeries.setMaxSampleCount({ mode: 'auto', max: 10_000_000 })

This would first allocate only small amount of memory, progressively increase memory allocation as samples come in until eventually limiting sample count to 10 million.

Returns

Object itself.

All real-time use cases (where data points are pushed in periodically) must define a "max sample count".

 // Example, keep maximum 1 million samples
 PointLineAreaSeries.setMaxSampleCount(1_000_000)

This allocates the required amount of memory beforehand, which is crucial to get the best performance. After 1 million samples are reached, the oldest samples will start dropping out.

Alternatively, if you are uncertain what value to use and don't want to allocate too much memory up-front, you can start small and automatically increase the buffer size as samples flow in:

 PointLineAreaSeries.setMaxSampleCount({ mode: 'auto', max: 10_000_000 })

This would first allocate only small amount of memory, progressively increase memory allocation as samples come in until eventually limiting sample count to 10 million.

Returns

Object itself.

Set alignment of points. Defaults to center { x: 0, y: 0 }.

Can be used to offset points relative to their size.

 // Example, position point by bottom
 PointLineAreaSeries.setPointAlignment({ x: 0, y: -1 })

 // Example, position point by bottom with extra gap
 PointLineAreaSeries.setPointAlignment({ x: 0, y: -1.5 })

Returns

Object itself.

Released as beta feature in v5.2.0 feature may still change according to user feedback and experiences.

Set fill style of markers displayed at sample locations.

Supported fill styles:

SolidFill:

Solid color.

 // Example, solid colored markers
 PointLineAreaSeries.setPointFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))

To learn more about available Color factories, see ColorRGBA

PalettedFill:

Supports following look-up modes: x, y and value.

lookUpProperty: 'x' | 'y':

Color dynamically based on x or y coordinate.

 // Example, dynamic color by Y coordinates
 PointLineAreaSeries.setPointFillStyle(new PalettedFill({
     lookUpProperty: 'y',
     lut: new LUT({
         interpolate: true,
         steps: [
             { value: 0, color: ColorRGBA(255, 0, 0) },
             { value: 100, color: ColorRGBA(0, 255, 0) },
         ]
     })
 }))

To learn more about Color lookup tables, see LUT.

lookUpProperty: 'value':

Color dynamically based on separately supplied value data set. values are specified when adding data points.

 // Example, dynamic color by Value data set
 const series = ChartXY.addPointLineAreaSeries({ lookupValues: true })
     .setPointFillStyle(new PalettedFill({
         lookUpProperty: 'value',
         lut: new LUT({
             interpolate: true,
             steps: [
                 { value: 0, color: ColorRGBA(255, 0, 0) },
                 { value: 100, color: ColorRGBA(0, 255, 0) },
             ]
         })
     }))
     .appendSamples({
         yValues: [0, 1],
         lookupValues: [0, 100]
     })

Data point lookup value properties have to be explicitly enabled before they can be used, see lookupValues for more details.

To learn more about Color lookup tables, see LUT.

IndividualPointFill:

Color by individually picked sample colors. Colors are interpolated between data points.

 // Example, individual colors
 const series = ChartXY.addPointLineAreaSeries({ colors: true })
     .setPointFillStyle(new IndividualPointFill())
     .appendSamples({
         yValues: [0, 1],
         colors: [0xff0000ff, 0xff00ff00]
     })

Data point color properties have to be explicitly enabled before they can be used, see colors for more details.

ImageFill (beta feature, introduced in v5.2.0):

Display custom images.

 // Example syntax
 const image = new Image()
 image.src = 'my-asset.png'

 const pointSeries = chart.addPointLineAreaSeries({ dataPattern: null })
     .setAreaFillStyle(emptyFill)
     .setStrokeStyle(emptyLine)
     .setPointFillStyle(new ImageFill({ source: image }))
     .appendSample({ x: 0, y: 0 })

Please note that when ImageFill is used, Point line area series behaves a little bit differently:

1. Different point shapes are not available. Point shape should always be PointShape.Square
2. Point size is interpreted as multiplier of source Image size. Defaults to 1.

LinearGradientFill:

Color with a linear gradient.

 // Example, linear gradient area fill
 PointLineAreaSeries.setPointFillStyle(new LinearGradientFill())

To learn more about linear gradient configurations, see LinearGradientFill.

RadialGradientFill:

Color with a radial gradient.

 // Example, radial gradient line color
 PointLineAreaSeries.setPointFillStyle(new RadialGradientFill())

To learn more about radial gradient configurations, see RadialGradientFill.

Returns

Object itself for fluent interface.

Set the rotation of points in degrees.

 // Example syntax, rotate 45 degrees
 PointLineAreaSeries.setPointRotation(45)

Point rotations can also be configured individually, see DataSetXY.rotations for more information.

Set shape of displayed points, markers.

 // Example syntax
 PointLineAreaSeries.setPointShape(PointShape.Square)

All valid options are listed under PointShape

Returns