Cartesian Chart

The CartesianChart control allows you to create diagrams using the Cartesian coordinate system.

cartesian-chart

The control's main features include:

An unlimited number of data series
Supported diagram types (views): Line, Scatter Line, Point (with SVG marker support), Area, Step Line, Step Area, Range Area, Bar, Range Bar.
Multiple axes support
Multiple axis types: Numeric, Date-Time, Time Span, Qualitative, and Logarithmic
Scrolling and zooming all axes at the same time
Scrolling and zooming individual axes
High-performance when displaying large data
Real-time data visualization
Strips and constant lines
Using the MVVM design pattern to provide data and customize chart options
Displaying rapidly changing real-time data. Use a special data adapter to implement a moving viewport

Get Started

Chart Control's Elements

The main elements of the chart control are series and axes.

Series — Provides data and specifies how to visualize this data. You can plot as many series as you need within the same chart control. See Series for more information.

Axes — A typical cartesian chart displays two axes: the X-axis and Y-axis. You can also add additional axes to the chart when it plots two or more series. Each series can be associated with its own axes. See Axes.

Series

A series provides data to plot by the chart control, and specifies the series view (visual presentation of this data).

The CartesianSeries class encapsulates a series for the CartesianChart control. To add series to the chart, use the CartesianChart.Series collection. You can also populate the chart with series using the MVVM design pattern. Use the CartesianChart.SeriesSource and CartesianChart.SeriesTemplate properties for this purpose. See the following link for more information: Get Started with Charts - MVVM Pattern.

The following code defines one series in the CartesianChart.Series collection.

<mxc:CartesianChart>
    <mxc:CartesianChart.Series>
        <mxc:CartesianSeries DataAdapter="{Binding Series.DataAdapter}">
            <mxc:CartesianLineSeriesView Color="{Binding Series.Color}" Thickness="2" />
        </mxc:CartesianSeries>
    </mxc:CartesianChart.Series>
    <!-- ... -->
</mxc:CartesianChart>

chart-cartesian-sample

Series Data

You can supply data for a chart control's series using Data Adapters.

<mxc:CartesianSeries DataAdapter="{Binding Series.DataAdapter}">
    <!-- ... -->
</mxc:CartesianSeries>

A Data Adapter is an object that implements the ISeriesDataAdapter interface. Typically you do not need to implement this interface manually. Eremex Charts ship with multiple Data Adapters for various data types (numeric, date-time, and qualitative). Choose a Data Adapter based on your requirements.

Below you'll find Data Adapters grouped by the type of the X values:

Numeric X Values:

SortedNumericDataAdapter
FormulaDataAdapter
ScatterDataAdapter
NumericRangeDataAdapter

Date and Time X Values:

SortedDateTimeDataAdapter
DateTimeRangeDataAdapter
SortedTimeSpanDataAdapter
TimeSpanRangeDataAdapter

Qualitative X Values:

QualitativeDataAdapter
QualitativeRangeDataAdapter

Series Views

CartesianChart supports multiple series views (diagram types):


Line Series View (`CartesianLineSeriesView` object) Points connected with lines.	Scatter Line Series View (`CartesianScatterLineSeriesView` object) Connects points in the order in which they appear in the data series.
Point Series View (`CartesianPointSeriesView` object) Plots individual points.	Area Series View (`CartesianAreaSeriesView` object) Connects points with lines and paints filled areas.
Step Line Series View (`CartesianStepLineSeriesView` object) Connects points with horizontal and vertical line segments.	Step Area Series View (`CartesianStepAreaSeriesView` object) Connects points with horizontal and vertical line segments, and paints filled areas.
Range Area Series View (`CartesianRangeAreaSeriesView` object) Fills the area between the two Y-values of a data series.	Bar Series View (`CartesianSideBySideBarSeriesView` object) Visualizes data as a set of rectangular bars.
Range Bar Series View (`CartesianSideBySideRangeBarSeriesView` object) Draws rectangular bars between the two Y-values of a data series.

To specify a view for series, define a corresponding ...SeriesView object as the content of the CartesianSeries object. In code behind, use the CartesianSeries.View property to specify a series view.

The following sample assigns the 'Line Series View' to a series.

<mxc:CartesianSeries DataAdapter="{Binding Series.DataAdapter}">
    <mxc:CartesianLineSeriesView Color="{Binding Series.Color}" Thickness="2" />
</mxc:CartesianSeries>

Axes

The CartesianChart control automatically creates cartesian axes (the X-axis and Y-axis) if you do not define them manually. If you need to customize axes in XAML, define AxisX and/or AxisY objects in the CartesianChart.AxesX/CartesianChart.AxesY collections, and then modify settings of these axes.

<mxc:CartesianChart>
    <!-- ... -->

    <mxc:CartesianChart.AxesX>
        <mxc:AxisX ShowTitle="False">
        </mxc:AxisX>
    </mxc:CartesianChart.AxesX>

    <mxc:CartesianChart.AxesY>
        <mxc:AxisY Title="t(°C)" TitlePosition="WithLabels">
            <mxc:AxisYRange AlwaysShowZeroLevel="False" />
        </mxc:AxisY>
    </mxc:CartesianChart.AxesY>
</mxc:CartesianChart>

Axis Value Range

Place AxisXRange/AxisYRange objects as the content of the AxisX/AxisY objects to specify range settings of the axes. The AxisXRange/AxisYRange objects allow you to customize the minimum and maximum range values, visibility of the zero level, etc.

<mxc:CartesianChart.AxesY>
    <mxc:AxisY Title="Amplitude (dB SPL)">
        <mxc:AxisYRange AlwaysShowZeroLevel="False" />
    </mxc:AxisY>
</mxc:CartesianChart.AxesY>

Axis Scale

An axis scale defines the type of scale units and various axis display options. The image below demonstrates a few scale types:

chart-scales

To specify the scale settings for axes, use the AxisX.ScaleOptions and AxisY.ScaleOptions properties.

Customize Scale Settings for an X Axis

Use the AxisX.ScaleOptions property to change the scale settings for an X axis. This property is of the base ScaleOptions type.

To modify the scale settings, set the AxisX.ScaleOptions property to one of the following objects based on the type of the X values of the series:

NumericScaleOptions — Numeric data scale. Use this scale type if the X values provided by the series are numeric values.

<mxc:AxisX Title="Frequency">
    <mxc:AxisX.ScaleOptions>
        <mxc:NumericScaleOptions 
            LogarithmicBase="{Binding AxisX.LogarithmicBase}"
            LabelFormatter="{Binding FrequencyFormatter}" />
    </mxc:AxisX.ScaleOptions>
</mxc:AxisX>

DateTimeScaleOptions — DateTime data scale. Use this scale type if the X values provided by the series are DateTime values. The DateTimeScaleOptions.MeasureUnit property allows you to specify the time unit for the axis scale: Millisecond, Second, Minute, Hour, Day, Week, Month, Quarter, or Year
```
<mxc:AxisX ShowTitle="False">
    <mxc:AxisX.ScaleOptions>
        <mxc:DateTimeScaleOptions MeasureUnit="Day" />
    </mxc:AxisX.ScaleOptions>
</mxc:AxisX>
```
TimeSpanScaleOptions— TimeSpan data scale. Use this scale type if the X values provided by the series are TimeSpan values. The TimeSpanScaleOptions.MeasureUnit property allows you to specify the time unit for the axis scale: Millisecond, Second, Minute, Hour, or Day.
```
<mxc:AxisX>
    <mxc:AxisX.ScaleOptions>
        <mxc:TimeSpanScaleOptions MeasureUnit="Minute" />
    </mxc:AxisX.ScaleOptions>
</mxc:AxisX>
```
QualitativeScaleOptions — Qualitative data scale. Use this scale type if the X values provided by the series are qualitative values (text strings).
```
<mxc:AxisX >
    <mxc:AxisX.ScaleOptions>
        <mxc:QualitativeScaleOptions GridSpacing="1" />
    </mxc:AxisX.ScaleOptions>
</mxc:AxisX>
```

Customize Scale Settings for an Y Axis

Use the AxisY.ScaleOptions property to modify the scale settings of the Y axis. This property is of the NumericScaleOptions type.

<mxc:AxisY Title="Amplitude (dB SPL)">
    <mxc:AxisY.ScaleOptions>
        <mxc:NumericScaleOptions LabelFormatter="{Binding MyCustomLabelFormatter}"/>
    </mxc:AxisY.ScaleOptions>
</mxc:AxisY>

Format Axis Labels

The ScaleOptions.LabelFormatter property allows you to specify an object that formats axis display values in a custom manner. You can implement a custom label formatter based on a function/expression using the Eremex.AvaloniaUI.Charts.FuncLabelFormatter object.

The following example implements a custom label formatter for DateTime values.

charts-custom-label-formatter

<mxc:AxisX Name="salesAxis" Title="Sales">
    <mxc:AxisX.ScaleOptions>
        <mxc:DateTimeScaleOptions MeasureUnit="Month" LabelFormatter="{Binding MonthFormatter}" />
    </mxc:AxisX.ScaleOptions>
</mxc:AxisX>

public partial class MainWindowViewModel : ViewModelBase
{
    // ...
    [ObservableProperty] FuncLabelFormatter monthFormatter = new(o => String.Format("{0:MMM} {0:yy}", o));
}

Multiple Axes

A typical cartesian chart has one X and one Y axis. You can add any number of additional X and Y axes when required. This is helpful when you display multiple series, and want to show its own X and/or Y axis for each series.

cartesian-chart-multiple-axes

Do the following to link a series with an axis:

Set the Key property of the axis to a unique ID (string).
Set the series's AxisXKey and/or AxisYKey property to the value of the Key property of the axis.

The following example adds an X axis and binds it to the lineSeries series.

<mxc:CartesianSeries Name="lineSeries" DataAdapter="{Binding LineSeries.DataAdapter}"  
  AxisXKey="lineSeriesAxis">
    <mxc:CartesianLineSeriesView Color="{Binding LineSeries.Color}" />
</mxc:CartesianSeries>

<mxc:CartesianChart.AxesX>
    <!-- ... -->
    <mxc:AxisX Position="Far" Title="Expenses"
       Key="lineSeriesAxis">
        <mxc:AxisX.ScaleOptions>
            <mxc:NumericScaleOptions />
        </mxc:AxisX.ScaleOptions>
    </mxc:AxisX>
</mxc:CartesianChart.AxesX>

A user can zoom and scroll the entire view and individual axes with the mouse.

To scroll all series simultaneously, drag the diagram area with the mouse. Use the mouse wheel over the diagram area to zoom all series at the same time.

To scroll an individual series, a user should drag with the mouse within the corresponding axis area. To zoom a series, scroll the mouse wheel within the axis area.

The following options allow you to disable zoom and scroll operations for individual axes:

Axis.EnableZooming
Axis.EnableScrolling

<mxc:CartesianChart.AxesX>
    <mxc:AxisX ShowTitle="False" EnableScrolling="False" EnableZooming="False" />
</mxc:CartesianChart.AxesX>

chartControl1.AxesX[0].EnableZooming = false;

Axis Settings

The following list summarizes display and behavior settings of cartesian axes:

ConstantLines and ConstantLinesSource — Allows you to paint constant lines for specific values. See also Strips and StripsSource.
EnableScrolling — Allows a user to scroll an axis with a mouse drag operation.
EnableZooming — Allows a user to zoom an axis.
InterlacingColor - The color used to paint interlaced strip lines (when the ShowInterlacing option is enabled).
MinorCount — Specifies the number of minor tickmarks and grid lines.
Position — Specifies the position of the axis. Available options include: Near (the X-axis is displayed at the bottom, and the Y-axis is displayed at the chart's left edge), and Far (the X-axis is displayed at the top, and the Y-axis is displayed at the chart's right edge).
ShowAxisLine — Specifies the visibility of the axis line.
ShowInterlacing — Specifies whether to paint interlaced strip lines between major gridlines.
ShowLabels — Specifies the visibility of the labels corresponding to major tickmarks.
ShowMajorGridlines — Specifies the visibility of the grid lines corresponding to major tickmarks.
ShowMajorTickmarks — Specifies the visibility of the major tickmarks.
ShowMinorGridlines — Specifies the visibility of the grid lines corresponding to minor tickmarks.
ShowMinorTickmarks — Specifies the visibility of the minor tickmarks.
ShowTitle — Specifies the visibility of the axis title (the Title property).
Strips and StripsSource — Allows you to fill ranges between specific values. See also ConstantLines and ConstantLinesSource.
Thickness — The thickness of the axis line.
Title — Gets or sets the title for the axis.
TitlePosition — Specifies the position of the axis title.

Crosshair

A crosshair is a pair of thin vertical and horizontal lines (argument and value lines) that allow a user to see exact values on axes and charts at the current cursor position. The crosshair appears when hovering over the chart, and it follows the mouse pointer.

chart-crosshair-one-series

Use the CartesianChart.CrosshairOptions property to customize display settings of the crosshair, or disable this feature.

Disable the Crosshair

The CrosshairOptions.ShowCrosshair property allows you to disable the crosshair.

<mxc:CartesianChart x:Name="chartControl1" >
    <mxc:CartesianChart.CrosshairOptions>
        <mxc:CrosshairOptions ShowCrosshair="False"/>
    </mxc:CartesianChart.CrosshairOptions>
    <!-- ... -->
</mxc:CartesianChart>

Disable Individual Lines and Axis Labels of the Crosshair

The CrosshairOptions.ShowArgumentLine and CrosshairOptions.ShowValueLine properties can be used to hide the vertical and horizontal line of the crosshair, respectively. To prevent crosshair labels from being displayed for the X and Y axes, use the CrosshairOptions.ShowArgumentLabel and CrosshairOptions.ShowValueLabel properties.

The following example hides the crosshair's vertical line and label for the X axis:

chart-crosshair-vertical-line-hidden

<mxc:CartesianChart x:Name="chartControl1" >
    <mxc:CartesianChart.CrosshairOptions>
        <mxc:CrosshairOptions ShowArgumentLabel="False" ShowValueLabel="False"/>
    </mxc:CartesianChart.CrosshairOptions>
    <!-- ... -->
</mxc:CartesianChart>

Customize Chart Labels of the Crosshair

A series view's CrosshairSeriesViewBase.ShowInCrosshair property specifies the visibility of the crosshair chart label for this series.

The following code hides the crosshair's chart label:

<mxc:CartesianChart.Series>
    <mxc:CartesianSeries DataAdapter="{Binding Series.DataAdapter}">
        <mxc:CartesianLineSeriesView Color="{Binding Series.Color}" Thickness="2" ShowInCrosshair="false"/>
    </mxc:CartesianSeries>
</mxc:CartesianChart.Series>

chart-crosshair-showincrosshair-disabled

Show an Exact or Interpolated Value in Crosshair Chart Labels

Cartesian Chart supports series that consist of sorted discrete data points. For these series, the crosshair lines do not always intersect data points, but are most often displayed between them. You can use the CartesianSortedLineSeriesView.CrosshairMode property to specify whether the crosshair's chart label snaps to the nearest data point, or displays an interpolated value. The following options are available:

CrosshairSeriesMode.Point — The crosshair chart label snaps to the nearest data point and displays its value.
CrosshairSeriesMode.Interpolate — The crosshair chart label displays an interpolated value of the point at the intersection of the vertical crosshair line with the chart.

The following code shows how to customize the CrosshairMode option:

<mxc:CartesianChart.Series>
    <mxc:CartesianSeries DataAdapter="{Binding Series.DataAdapter}">
        <mxc:CartesianLineSeriesView Color="{Binding Series.Color}" Thickness="2" CrosshairMode="Interpolate"/>
    </mxc:CartesianSeries>
</mxc:CartesianChart.Series>

Customize Crosshair Chart Labels for Multiple Series

When the Cartesian Chart contains multiple series, the crosshair displays a chart label for each series:

chart-crosshair-two-series

Use the CrosshairOptions.SeriesLabelMode property to specify display mode of chart labels for multiple series. The following options are available:

CrosshairSeriesLabelMode.ForEachSeries — A crosshair chart label is displayed for each series.
CrosshairSeriesLabelMode.ForNearestSeries — A crosshair chart label is displayed for the nearest series.
CrosshairSeriesLabelMode.OneForAllSeries — The crosshair displays one chart label that combines information on values of all series.

Below is an example that enables one crosshair chart label in the case of multiple series.

<mxc:CartesianChart.CrosshairOptions>
    <mxc:CrosshairOptions SeriesLabelMode="OneForAllSeries"/>
</mxc:CartesianChart.CrosshairOptions>

Table of Contents