NChart3D UWP Tutorial

Overview

This documentation provides a short tutorial that will explain the main concepts of the NChart3D framework as well as show you how to draw charts using NChart3D.
NChart3D is a versatile charting engine for Universal Windows Platform that lets you draw 2D and 3D interactive charts of different types according to your data.
The usage of NChart3D is very simple and requires only a few lines of code to visualize your data in a convenient and beautiful form.

Introduction

This tutorial will show you how to install NChart3D framework and build a simple project using C# that displays some random data, how to customize the appearance of charts and how to manage the selection of data. This tutorial is partially based on the samples provided in the NChart3D SDK that can be downloaded here.
At the end of this tutorial you will be able to create a simple application that looks like this:
Screen 1

Installation

First, download the NChart3D framework. It is recommended to install the framework that will allow you to add it from the "Extensions" section in Visual Studio. To do so, run "NChart3DSDK.vsix". Alternatively you can just copy the .dll to your disk and then link it through the "Browse" option. The framework is located in the "Framework" directory, the documentation is located in the "Documentation" directory and the set of samples is located in the "NChart3D/UWP-Samples" directory.
For each sample the Visual Studio projects are already created, so you can check them out to see whether everything works properly.
This tutorial will show you how to create a project from scratch. Let’s begin!
Create a new project of the "Blank App (Universal Windows)" type.
If you installed the framework properly, you should be able to link it to your application in the usual way. Right click the References in your project’s tree, select "Add References", then select the tab "Universal Windows", then "Extensions", scroll down and click the check box near "NChart3D SDK". Then hit "OK" button.
Screen 2
Make a test-run to check whether the project is able to build and run.
Now your project is set up and you can start using the NChart3D framework!

Anatomy of Charts

Before we start, let’s explain a little bit of terminology.
Screen 3

Background — the color or gradient that fills the background.
Caption — the text label (that can have background and border) that is displayed on top of the chart.
Legend — the scrollable widget that contains the names and marker images of all the series on the chart.
Plot area — the area where the series are drawn.
Axes — axes that surrounds the plot area.
Axes ticks — ticks that divide axes into pieces. There are major and minor ticks.
Axes grid lines — lines on the plot area that are parallel to the axes and start in the major ticks.
Axes labels — labels of the axes ticks.
Axes captions — captions of the axes.
Series — data visualizers.
Series’ points — individual values in the series.
Tooltip — a label on the chart displaying information about the chart point.

Drawing a Simple Chart

Let’s draw a simple chart. First, open MainPage.xaml and add NChartView to the main page:

<chart:NChartView x:Name="ChartView"/>

Do not forget to add link to NChart3D namespace as xmlns attribute to the Page tag:

xmlns:chart="using:NChart3D_UWP"

Result page looks like follows:

<Page
    x:Class="Tutorial.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:Tutorial"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:chart="using:NChart3D_UWP"
    mc:Ignorable="d">

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <chart:NChartView x:Name="ChartView"/>
    </Grid>
</Page>

The main class of NChart3D framework is called NChart and its instance is accessible from the NChartView. NChartView is the subclass of Grid that represents everything needed to display the chart in your views hierarchy. You can create an NChartView instance, place it anywhere you want and then communicate with the chart through the corresponding property of that instance. Add the

using NChart3D_UWP;

to your MainPage.xaml.cs file. This will include everything that is needed to operate with NChart3D framework.
You can access all chart function through internal field called Chart of the NChartView instance.
Now you can customize the chart through the ChartView.Chart property.
Add internal property r as

Random r = new Random();

to access random generator.
Now we'll add some setup code to the contructor of the Page. You can place this new code right after this.InitializeComponent(); that should already be generated by Visual Studio.
If you have a license key, set it to the chart like this:

ChartView.Chart.LicenseKey = "Your license key";

You may want to add some margin to the chart to get a spacing from the screen borders:

ChartView.Chart.CartesianSystem.Margin = NChartMarginHelper.MarginMake(10, 10, 10, 20);

Now you may switch on anti-aliasing (that is off by default). It will not hurt performance, because the anti-aliasing algorithm is adaptive, so it is recommended to switch it on to get better visual quality of the image. Add the following line of code:

ChartView.Chart.ShouldAntialias = true;

Now you should create a series that will be displayed. First, create only one column series and assign some brush that will fill this series with color. For example, let this series be green:

NChartColumnSeries series = new NChartColumnSeries();
series.Brush = new NChartSolidColorBrush(Windows.UI.ColorHelper.FromArgb(255, 0, 178, 102));

Now you should assign a data source to that series.
There is an interface called INChartSeriesDataSource that you should implement to build a data source. For example, you can make a data source from MainPage simply by implementing the interface in the MainPage.xaml.cs file as follows:

public sealed partial class MainPage : Page, INChartSeriesDataSource

And then add 4 methods that will supply data and names for the series:

IReadOnlyList<NChartPoint> INChartSeriesDataSource.Points(INChartSeries series)
{
    // Create points with some data for the series.
    List<NChartPoint> points = new List<NChartPoint>();
    for (int i = 0; i <= 10; ++i)
    {
        points.Add(new NChartPoint(NChartPointState.PointStateAlignedToXWithXY(i, r.Next(30) + 1), series));
    }
    return points;
}

string INChartSeriesDataSource.Name(INChartSeries series)
{
    // Get name of the series.
    return "My series";
}

IReadOnlyList<NChartPoint> INChartSeriesDataSource.ExtraPoints(INChartSeries series)
{
    // If you don't want to implement method, return null.
    return null;
}

NChartRawBitmap INChartSeriesDataSource.Image(INChartSeries series)
{
    // If you don't want to implement method, return null.
    return null;
}

As you can see, the first method generates an array of points with some random data. Each point can contain an array of states representing the changes of data in time. However in this tutorial we will create only one state for each point, which will be automatically the current one. Each state holds the actual data. For 2D columns the data are represented by X and Y values. We want the columns to be aligned to the X axis to make them look like "paling", so we use integer X values. The height of columns is "free", so normally double values are used, but in our case also integers are used because of the r.Next() function. Feel free to experiment with different values and see what happens.
The second method generates names for series to allow NChart3D to build the legend.
Other methods are empty.
Now, when the data source is ready, assign it to the series you have created and finally add series to the chart:

series.DataSource = this;
ChartView.Chart.AddSeries(series);

That’s almost all we need to visualize the data. The only thing we’ve missed is to update data in the chart:

ChartView.Chart.UpdateData();

This will force the NChart3D framework to process the data and build the visual appearance of the series. You should call this method any time the data was changed. Now you can build and run your application and see what happens. You should get the following result:
Screen 4

Customizing Appearance

As you can see, the values on the axes are calculated automatically. Let’s customize them and display some labels on the X axis! The axes as well as the series can have their own data sources. These data sources can supply custom minimums / maximums or custom strings for labels of the ticks. Implement the interface INChartValueAxisDataSource to the MainPage:

public sealed partial class MainPage : Page, INChartSeriesDataSource, INChartValueAxisDataSource

Next implement a single method that will supply the strings used for ticks' labels:

IReadOnlyList<string> INChartValueAxisDataSource.Ticks(NChartValueAxis axis)
{
    switch (axis.Kind)
    {
        case NChartValueAxisKind.X:
            return new List<string>() { @"one", @"two", @"three", @"four", @"five", @"six", @"seven", @"eight", @"nine", @"ten", @"eleven" };

        default:
            return null;
    }
}

We have 11 points in the series, so we should supply 11 strings.
Let's also add captions to the axes. Implement the following method:

string INChartValueAxisDataSource.Name(NChartValueAxis axis)
{
    switch (axis.Kind)
    {
        case NChartValueAxisKind.X:
            return "X Axis";

        case NChartValueAxisKind.Y:
            return "Y Axis";

        default:
            return String.Empty;
    }
}

This will supply names for the X and Y axes.
Of course, you should set the data source to the axes you want to customize. You can do this by adding the following line before your UpdateData call:

ChartView.Chart.CartesianSystem.XAxis.DataSource = this;
ChartView.Chart.CartesianSystem.YAxis.DataSource = this;

Don't forget to implement the other methods of INChartValueAxisDataSource as follows:

TimeSpan? INChartValueAxisDataSource.DateStep(NChartValueAxis axis)
{
    // If you don't want to implement method, return null.
    return null;
}

string INChartValueAxisDataSource.DateToString(DateTimeOffset date, TimeSpan tickInterval, NChartValueAxis axis)
{
    // If you don't want to implement method, return empty string.
    return String.Empty;
}

string INChartValueAxisDataSource.DoubleToString(double value, NChartValueAxis axis)
{
    // If you don't want to implement method, return empty string.
    return String.Empty;
}

IReadOnlyList<string> INChartValueAxisDataSource.ExtraTicks(NChartValueAxis axis)
{
    // If you don't want to implement method, return null.
    return null;
}

double? INChartValueAxisDataSource.Length(NChartValueAxis axis)
{
    // If you don't want to implement method, return null.
    return null;
}

double? INChartValueAxisDataSource.Max(NChartValueAxis axis)
{
    // If you don't want to implement method, return null.
    return null;
}

DateTimeOffset? INChartValueAxisDataSource.MaxDate(NChartValueAxis axis)
{
    // If you don't want to implement method, return null.
    return null;
}

double? INChartValueAxisDataSource.Min(NChartValueAxis axis)
{
    // If you don't want to implement method, return null.
    return null;
}

DateTimeOffset? INChartValueAxisDataSource.MinDate(NChartValueAxis axis)
{
    // If you don't want to implement method, return null.
    return null;
}

double? INChartValueAxisDataSource.Step(NChartValueAxis axis)
{
    // If you don't want to implement method, return null.
    return null;
}

You can also play with the colors of chart. For example, let’s change the background to the gray-to-white gradient. For this, you can create a gradient brush and assign it to the chart’s Background property:

ChartView.Chart.Background = new NChartLinearGradientBrush(Windows.UI.ColorHelper.FromArgb(255, 178, 178, 178), Windows.UI.Colors.White);

You may use the multicolor gradients as well. See the documentation for NChartLinearGradientBrush for details.
You can also add a border for your series, like this:

series.BorderThickness = 2.0f;
series.BorderBrush = new NChartSolidColorBrush(Windows.UI.Colors.Black);

Now add the caption to the chart by adding another lines:

ChartView.Chart.Caption.Margin = NChartMarginHelper.MarginMake(0, 0, 0, 20);
ChartView.Chart.Caption.Text = "NChart3D";

You will get the following result:
Screen 5

Adding More Charts

Now let’s add more series to the chart.
Just create another series of different types, for example one area and one line. To do this, add the following code after the creation of the first series:

NChartAreaSeries series2 = new NChartAreaSeries();
series2.DataSource = this;
series2.Brush = new NChartSolidColorBrush(Windows.UI.Colors.Orange);
series2.Brush.Opacity = 0.7f;
ChartView.Chart.AddSeries(series2);

NChartLineSeries series3 = new NChartLineSeries();
series3.DataSource = this;
series3.Brush = new NChartSolidColorBrush(Windows.UI.Colors.Red);
series3.LineThickness = 3.0f;
ChartView.Chart.AddSeries(series3);

You should get the following result:
Screen 6

As you can see, three series of different types appear on the chart. Wait, what? The names in the legend are all the same! Let’s fix it. First, add the tag for each series like this:

series.Tag = 1;
series2.Tag = 2;
series3.Tag = 3;

And then change the INChartSeriesDataSource.Name method to the following:

string INChartSeriesDataSource.Name(INChartSeries series)
{
    return string.Format("My series {0}", series.Tag);
}

This will add the numbers to the series’ names that appear in the legend.

Adding Tooltips

It’s time to add tooltips that will appear and disappear by tapping chart points and display some information, for example, the name of a series and the current Y value. To handle which chart points are selected when tapped, INChartDelegate is used. Add the reference to this interface to MainPage:

public sealed partial class MainPage : Page, INChartSeriesDataSource, INChartValueAxisDataSource, INChartDelegate

Then implement three required methods of this interface (but we will use only one of them):

void INChartDelegate.PointSelected(NChart chart, NChartPoint point)
{
    // Disable old highlight.
    if (prevSelectedPoint != null)
        prevSelectedPoint.Tooltip.SetVisibleAnimated(false, 0.25f);

    if (point != null)
    {
        if (point == prevSelectedPoint)
        {
            prevSelectedPoint = null;
        }
        else
        {
            prevSelectedPoint = point;

            if (point.Tooltip == null)
            {
                point.Tooltip = CreateTooltip();
            }
            UpdateTooltip(point);
            point.Tooltip.SetVisibleAnimated(true, 0.25f);
        }
    }
    else
    {
        prevSelectedPoint = null;
    }
}

void INChartDelegate.TimeIndexChanged(NChart chart, double timeIndex)
{
}

void INChartDelegate.DidEndAnimating(NChart chart, object obj, NChartAnimationType animation)
{
}

void INChartDelegate.DidChangeZoomPhase(NChart chart, NChartEventPhase phase)
{
}

The logic here is pretty straightforward. We hide old tooltip (if any) with animation and then show the new one or do nothing if the selected point is the one we selected before (so second tap to the same point hides the tooltip).
To make this work, we should store the previously selected point somewhere. Let’s use internal variable called prevSelectedPoint of type NChartPoint for that.
Also we will need two additional methods to create and update a tooltip.
You may use some initial settings for the tooltip like this:

NChartTooltip CreateTooltip()
{
    NChartTooltip result = new NChartTooltip();

    result.Background = new NChartSolidColorBrush(Windows.UI.Colors.White);
    result.Background.Opacity = 0.9f;
    result.Padding = NChartMarginHelper.MarginMake(10.0f, 10.0f, 10.0f, 10.0f);
    result.BorderColor = Windows.UI.Colors.Gray;
    result.BorderThickness = 1.0f;
    result.Font = NChartFont.SystemFontWithSize(16.0f);
    result.Visible = false;

    return result;
}

And then you should update the text in the tooltip:

void UpdateTooltip(NChartPoint point)
{
    point.Tooltip.Text = string.Format("{0}: {1:#.##}", point.Series.Name, point.CurrentState.DoubleY);
}

As you can see, you can display any information in the tooltip you want.
Finally set the delegate for chart by adding the following line to the Page's constructor:

ChartView.Chart.Delegate = this;

And that’s it! You should get something like this:
Screen 1

What's next?

You can find more information about using the NChart3D framework in samples in the SDK. If you have any questions, feel free to contact us.