The Rectangle Series Type

The Rectangle Series Type in SciChart.js provides a highly configurable and performant way to visualize rectangular data, supporting a variety of charting scenarios where rectangles, bars, or ranges are required. Its flexible data and rendering options make it suitable for both simple and advanced data visualization needs.

Rectangle Series can be created using the FastRectangleRenderableSeries📘 type.

Here is a simple Rectangle Series made using XyxyDataSeries📘:

const xValues = [0, 6, 10, 17];
const yValues = [0, 6, 2, 5];
const x1Values = [5, 9, 15, 25];
const y1Values = [5, 9, 8, 10];

const rectangleSeries = new FastRectangleRenderableSeries(wasmContext, {
    dataSeries: new XyxyDataSeries(wasmContext, {
        xValues,
        yValues,
        x1Values,
        y1Values
    }),
    columnXMode: EColumnMode.StartEnd, // x, x1
    columnYMode: EColumnYMode.TopBottom, // y, y1
    fill: "cornflowerblue",
    stroke: "black",
    strokeThickness: 1,
    opacity: 0.5
});

Rectangle Series could be used for displaying:

• Gannt chart
• Histogram
• Range bars
• Waterfall chart
• Treemap
• Linear gauges
• Bar chart race

info

Resampling is OFF by default for Rectangle Series. If you are using it with XyDataSeries, with non-overlapping data that is sorted in X, and you have enough data to potentially benefit from resampling, you can turn it on by passing resamplingMode: EResamplingMode.Auto

Properties

• columnXMode (EColumnMode📘) - This determines how the x values and optional x1 values are interpreted.

  • EColumnMode.Mid - each column is centered on its X-value. This means the center of the column aligns directly with the X data point, rather than the left or right edge. This is typically the default and most intuitive way to display columns, as it visually associates each bar with its data value on the axis
  • EColumnMode.Start - each column is drawn so that its left edge aligns exactly with the X data value
  • EColumnMode.MidWidth - each column is centered on its X data value, but the centering takes into account the full width of the column
  • EColumnMode.StartWidth - each column (bar) should be positioned so its left edge aligns with the X data value, and the column's width extends to the right from that point. This means the X value marks the start (left boundary) of the column, and the entire width of the column is drawn to the right of this value
  • EColumnMode.StartEnd - each column’s left and right X positions are explicitly defined by two separate values "start" and "end" of the column. Instead of specifying a single X value and a width, you provide both the starting and ending X coordinates for each bar

• columnYMode (EColumnYMode📘) - This determines how the y values and optional y1 values are interpreted.

  • EColumnYMode.TopBottom - is a mode used to define the vertical positioning of columns (bars) by specifying both the top and bottom Y-values for each column. Instead of providing just a single Y-value (for example, the height or value of the bar), you provide two Y-values: one for the top edge and one for the bottom edge of the column
  • EColumnYMode.TopHeight - is a mode for defining the vertical positioning of columns (bars) where you specify the top Y-value and the height of each column, rather than the top and bottom Y-values
  • EColumnYMode.CenterHeight - is a mode that defines the vertical positioning of columns (bars) by specifying a center Y-value and a height for each column

• dataPointWidth - Sets a value used to calculate the width of rectangles in the X direction. By default, the value is treated as data range since rectangle series do not tend to be evenly spaced. To specify if the value should be treated as relative, absolute, or based on range use dataPointWidthMode Note that Absolute mode does not work well with autoRange due to circularity between the range calculation and the axis layout.

• dataPointWidthMode - Sets the mode which determines how dataPointWidth in X direction is interpreted. Available values are EDataPointWidthMode. Default Relative.

  • EDataPointWidthMode.Range - Interprets Data Point Width as the x data range per column. This is useful if you are plotting sparse columns on a NumericAxis
  • EDataPointWidthMode.Absolute - Interprets Data Point Width as an absolute pixel value
  • EDataPointWidthMode.Relative - Interprets Data Point Width as a relative to the full width which is the axis length/number of columns. This assumes that there are no gaps in the data. If you are plotting sparse columns on a NumericAxis, consider Range mode

• stroke - A Stroke for lines, outlines and edges of this RenderableSeries. Acceptable values include RGB format e.g. #FF0000, RGBA format e.g. #FF000077`` and RGBA format e.g. rgba(255,0,0,0.5)

• strokeThickness - The Stroke Thickness for lines, outlines and edges of this RenderableSeries

• fill - The column fill as an HTML color code

• opacity - An Opacity factor of the Series that controls its semi-transparency level, where value 1 means the Series is opaque; 0 - transparent.

• defaultY1 - Sets a common y1 value for all rectangles if y1Values are not provided. Default 0

• customTextureOptions - Options that create a custom texture brush

• dataLabels - Options to pass to the DataLabelProvider. Set a style with font and size to enable per-point text for this series. By default, y value is displayed here

   dataLabels: {
       style: {
           fontSize: 16
       },
       color: "black"
   }

• topCornerRadius - Corner radius for the top left and top right corners
• bottomCornerRadius - Corner radius for the bottom left and bottom right corners

Examples

Rectangle Series Basic Example

In this example we have created the rectangle series using columnXMode: EColumnMode.StartEnd, which allows you to specify both the start and end X positions for each rectangle and columnYMode: EColumnYMode.TopBottom, which allows you to specify both the start and end Y positions for each rectangle.

const xValues = [0, 6, 10, 17];
const yValues = [0, 6, 2, 5];
const x1Values = [5, 9, 15, 25];
const y1Values = [5, 9, 8, 10];

const rectangleSeries = new FastRectangleRenderableSeries(wasmContext, {
    dataSeries: new XyxyDataSeries(wasmContext, {
        xValues,
        yValues,
        x1Values,
        y1Values
    }),
    columnXMode: EColumnMode.StartEnd, // x, x1
    columnYMode: EColumnYMode.TopBottom, // y, y1
    fill: "cornflowerblue",
    stroke: "black",
    strokeThickness: 1,
    opacity: 0.5
});

Rectangle Series Custom Texture Example

In this example we have added a custom texture to the rectangle series using the customTextureOptions property. This allows you to fill each rectangle with a pattern or image instead of a solid color.

const xValues = [0, 6, 10, 17];
const yValues = [0, 6, 2, 5];
const x1Values = [5, 9, 15, 25];
const y1Values = [5, 9, 8, 10];

const rectangleSeries = new FastRectangleRenderableSeries(wasmContext, {
    dataSeries: new XyxyDataSeries(wasmContext, {
        xValues,
        yValues,
        x1Values,
        y1Values
    }),
    columnXMode: EColumnMode.StartEnd, // x, x1
    columnYMode: EColumnYMode.TopBottom, // y, y1
    customTextureOptions: new StickFigureTextureOptions({ stroke: "white" }),
    fill: "cornflowerblue",
    stroke: "black",
    strokeThickness: 1,
    opacity: 0.5
});

Rectangle Series Custom Label Example

This example shows how to add a custom label to each rectangle in the series using the dataLabelProvider property. By providing a custom dataLabelProvider, you can display any text or value for each rectangle, such as category names or formatted values.

class MyRectangleSeriesDataLabelProvider extends RectangleSeriesDataLabelProvider {
    getText(state) {
        const usefinal = !this.updateTextInAnimation && state.parentSeries.isRunningAnimation;
        const yval = usefinal ? state.yValAfterAnimation() : state.yVal();
        if (isNaN(yval)) {
            return undefined;
        } else {
            const diff = Math.abs(state.x1Val() - state.xVal());
            if (this.engineeringPrefix) {
                return formatNumber(diff, this.numericFormat, this.precision, this.engineeringPrefixProperty);
            } else {
                return formatNumber(diff, this.numericFormat ?? ENumericFormat.Decimal, this.precision);
            }
        }
    }
}

const xValues = [0, 6, 10, 17];
const yValues = [0, 6, 2, 5];
const x1Values = [5, 9, 15, 25];
const y1Values = [5, 9, 8, 10];

const rectangleSeries = new FastRectangleRenderableSeries(wasmContext, {
    dataSeries: new XyxyDataSeries(wasmContext, {
        xValues,
        yValues,
        x1Values,
        y1Values
    }),
    columnXMode: EColumnMode.StartEnd,
    columnYMode: EColumnYMode.TopBottom,
    fill: "white",
    stroke: "steelblue",
    strokeThickness: 4,
    opacity: 0.5,
    topCornerRadius: 10,
    bottomCornerRadius: 10,
    dataLabelProvider: new MyRectangleSeriesDataLabelProvider({
        style: {
            fontSize: 16
        },
        color: "black"
    })
});

Rectangle Series Animated Example

This example demonstrates how to animate the rectangle series using the GenericAnimation📘.

const initialData = {
    xValues: [0, 6, 10, 17],
    yValues: [0, 6, 2, 5],
    x1Values: [5, 9, 15, 25],
    y1Values: [5, 9, 8, 10]
};
const dataSeries = new XyxyDataSeries(wasmContext, initialData);

const rectangleSeries = new FastRectangleRenderableSeries(wasmContext, {
    dataSeries,
    columnXMode: EColumnMode.StartEnd,
    columnYMode: EColumnYMode.TopBottom,
    fill: "white",
    stroke: "steelblue",
    strokeThickness: 1,
    opacity: 0.5
});
sciChartSurface.renderableSeries.add(rectangleSeries);

const getData = () => {
    const xValues = [];
    const yValues = [];
    const x1Values = [];
    const y1Values = [];
    initialData.xValues.forEach((d, i) => {
        xValues.push(Math.random() * 3 + 8 * i);
        yValues.push(Math.random() * 3 * i);
        x1Values.push((Math.random() + 2) * 5);
        y1Values.push((Math.random() + 2) * 3);
    });
    return {
        xValues,
        yValues,
        x1Values,
        y1Values
    };
};

const interpolateNumber = (from, to, progress) => {
    if (progress < 0) return from;
    if (progress > 1) return to;
    return from + (to - from) * progress;
};

const dataAnimation = new GenericAnimation({
    from: initialData,
    to: getData(),
    duration: 2000,
    ease: easing.inOutSine,
    onAnimate: (from, to, progress) => {
        const newXValues = [];
        const newYValues = [];
        const newX1Values = [];
        const newY1Values = [];
        from.xValues.forEach((value, index) => {
            newXValues.push(interpolateNumber(from.xValues[index], to.xValues[index], progress));
            newYValues.push(interpolateNumber(from.yValues[index], to.yValues[index], progress));
            newX1Values.push(interpolateNumber(from.x1Values[index], to.x1Values[index], progress));
            newY1Values.push(interpolateNumber(from.y1Values[index], to.y1Values[index], progress));
        });
        dataSeries.clear();
        dataSeries.appendRange(newXValues, newYValues, newX1Values, newY1Values);
    },
    onCompleted: () => {
        dataAnimation.from = dataAnimation.to;
        dataAnimation.to = getData();
        dataAnimation.reset();
    }
});