The SubCharts API allows to place a separate child chart within a parent chart (Charts within charts). It is possible to have multiple sub-charts within the main SciChartSurface.

The purpose of the SubCharts API is to allow:

• Very large grids of charts, e.g. 10 charts x 10 charts (100 total) and maintain very high performance drawing by sharing a single WebGL Context.
• Charts within charts, e.g. a 2-dimensional overview
• Charts placed within axis or other advanced scenarios

A sub-chart is represented by the SciChartSubSurface class, and similarly to SciChartSurface it has its own Axes, Modifiers, Renderable Series and Annotations.

SubCharts API could be applied to display separate charts simultaneously on a single root element. The API allows to set a position, size , and styling of a sub-chart. Additionally it is possible to add custom HTML elements to the chart, which would be positioned accordingly to the chart layout flow.

Discovering the API

A sub-chart is represented by an instance of SciChartSubSurface class, which extends SciChartSurface. To create a sub-chart on an existing surface we can use SciChartSurface.addSubChart method.

The method accepts I2DSubSurfaceOptions as parameters and returns the created SciChartSubSurface object. (See the following sections for the usage example of the options argument).  It will also add a new sub-surface to the SciChartSurface.subCharts collection of the main surface object. Then you should be able to access it directly or from the collection and configure similarly as you would do with a regular surface.

Basic Subchart (Charts within Charts)

Let's demonstrate a simple setup, where we define a sub-chart on a surface. For this we will start from defining a surface with some axes on it. On the surface we will create a sub-chart on a specified area.

import { NumericAxis } from 'scichart/Charting/Visuals/Axis/NumericAxis';
import { SciChartSurface } from 'scichart/Charting/Visuals/SciChartSurface';
import { Rect } from 'scichart/Core/Rect';
// ...
// create a main (regular) surface which will contain a sub-chart
const { sciChartSurface, wasmContext } = await SciChartSurface.create(divElementId);
// axes here are optional, but may be required
// e.g. when using ECoordinateMode.DataValue or drawing renderable series
sciChartSurface.xAxes.add(new NumericAxis(wasmContext));
sciChartSurface.yAxes.add(new NumericAxis(wasmContext));
// Add a sub-chart to the main surface
const subChartSurface = sciChartSurface.addSubChart({ position: new Rect(0, 0, 0.5, 0.5) });
// Add axes to the sub-surface as well to make sure it will be drawn
subChartSurface.xAxes.add(new NumericAxis(wasmContext));
subChartSurface.yAxes.add(new NumericAxis(wasmContext));

In the example above we passed an object as argument of SciChartSurface.addSubChart method, which contains a position property. The property defines a structure for specifying coordinates and sizes of a sub-chart. By default, the coordinates and size are treated as ratio values in range from 0 to 1, with a canvas viewport used as a base.

SubCharts with the Builder API

It is also possible to create a sub-chart via Builder API. For this pass an array of ISubChartDefinition via ISciChart2DDefinition.subCharts property.

For example, the following snippet will give us the same result as Basic Example setup:

import { chartBuilder } from "scichart/Builder/chartBuilder";
import { Rect } from 'scichart/Core/Rect';
import { EAxisType } from 'scichart/types/AxisType';
// ...
const { wasmContext, sciChartSurface } = await chartBuilder.build2DChart(divElementId, {
    // axes here are optional, but may be required
    // e.g. when using ECoordinateMode.DataValue or drawing renderable series
    xAxes: { type: EAxisType.NumericAxis },
    yAxes: { type: EAxisType.NumericAxis },
    subCharts: [
        {
            surface: { position: new Rect(0, 0, 0.5, 0.5) },
        },
    ],
});