ContextQMD
Back to Devexpress

Provide Series Data

wpf-117340-controls-and-libraries-charts-suite-chart3d-control-series-provide-series-data.md

latest13.0 KB
Original Source

Provide Series Data

  • Oct 12, 2020
  • 6 minutes to read

The Chart3DControl can display multiple series against three-dimensional data. At least three values are required to create a point in the 3D Chart. To visualize data, the chart uses three axes: x-axis, y-axis, and z-axis.

This help topic contains the following sections:

Supported Data Types

You can use the following data types for X and Y arguments:

The Chart3DControl determines the type of arguments based on underlying data. You can explicitly specify the Series3DBase.XArgumentScaleType and Series3DBase.YArgumentScaleType properties to prevent the chart from automatic type detection.

The 3D Chart only supports numeric values that are plotted on the value axis (z-axis).

Create Series Automatically from a Template

Use the following XAML to create several series from a data source:

xaml
<dxc:Chart3DControl>
    <dxc:Series3DDataSourceAdapter DataSource="{Binding Irises}"
                                   SeriesDataMember="Species"
                                   XArgumentDataMember="SepalLength"
                                   YArgumentDataMember="PetalLength"
                                   ValueDataMember="SepalWidth">
        <dxc:Series3DDataSourceAdapter.SeriesTemplate>
            <dxc:Series3DTemplate>
                <dxc:Series3DTemplate.View>
                    <dxc:Point3DSeriesView/>
                </dxc:Series3DTemplate.View>
            </dxc:Series3DTemplate>
        </dxc:Series3DDataSourceAdapter.SeriesTemplate>
    </dxc:Series3DDataSourceAdapter>
</dxc:Chart3DControl>

Related API members:

MemberDescription
Chart3DControl.SeriesSourceThe Chart3D control’s series source. (Content property)
Series3DDataSourceAdapterGenerates series from a data source based on a SeriesDataMember‘s values.
Series3DDataSourceAdapter.SeriesTemplateThe series template.

To fine-tune specific generated series, use the Series3DDataSourceAdapter.CustomizeSeries event.

Create Series Manually

Use the following XAML to create series and add them to a series storage:

xaml
<dxc:Chart3DControl>
    <dxc:Series3DStorage>
        <dxc:Series3D/>
        <dxc:Series3D/>
        <!--...-->
    </dxc:Series3DStorage>
</dxc:Chart3DControl>

Related API members:

MemberDescription
Chart3DControl.SeriesSourceThe Chart3D control’s series source. (Content property)
Series3DStorageThe storage of manually created series.
Series3DAn individual series.

Create a Series Manually with Unbound Point Data

The series storage allows you to create and configure series points manually if you do not have a data source of arguments and values. The following XAML demonstrates this approach:

xaml
<dxc:Series3D DisplayName="GDP by Year">
    <dxc:SeriesPoint3DStorage>
        <dxc:SeriesPoint3D XArgument="USA" YArgument="1/1/2014" Value="17348"/>
        <!--Other points.-->
    </dxc:SeriesPoint3DStorage >
</dxc:Series3D >

Related API members:

MemberDescription
Series3D.PointSourceThe source of series’ points. (Content property)
SeriesPoint3DStorageThe storage of manually created points.
SeriesPoint3DStorage.PointsThe collection of manually created points. (Content property)
SeriesPoint3DAn individual series point.
SeriesPoint3D.XArgumentSpecifies the series point’s x-argument.
SeriesPoint3D.YArgumentSpecifies the series point’s y-argument.
SeriesPoint3D.ValueSpecifies the series point’s value.

Create Series Manually and Generate Points from a Data Source

Use the following XAML to populate a series with points generated from an external source:

xaml
<dxc:Series3D DisplayName="Population Statistics">
    <dxc:SeriesPoint3DDataSourceAdapter DataSource="{Binding Countries}"
                                        XArgumentDataMember="Name"
                                        YArgumentDataMember="Year"
                                        ValueDataMember="Population"/>
</dxc:Series3D >

Related API members:

MemberDescription
Series3D.PointSourceThe source of series’ points. (Content property)
SeriesPoint3DDataSourceAdapterGenerates series points based on the specified data source’s values.
SeriesPoint3DDataSourceAdapter.DataSourceThe source whose values are used to generate series points.
SeriesPoint3DDataSourceAdapter.XArgumentDataMemberThe name of the data member whose values are used as point x-arguments.
SeriesPoint3DDataSourceAdapter.YArgumentDataMemberThe name of the data member whose values are used as point y-arguments.
SeriesPoint3DDataSourceAdapter.ValueDataMemberThe name of the data member whose values are used as point values.

Create Series Manually with Points from Argument and Value Arrays

You can use separate data arrays or collections as a source of arguments and values:

xaml
<dxc:Series3D DisplayName="Population Statistics">
    <dxc:SeriesPoint3DMatrixAdapter XArguments="{Binding CountryNames}"
                                    YArguments="{Binding Years}"
                                    Values="{Binding Populations}"/>
</dxc:Series3D >

Related API members:

MemberDescription
Series3D.PointSourceThe source of series’ points. (Content property)
SeriesPoint3DMatrixAdapterCreates series points by the specified arguments and values.
SeriesPoint3DMatrixAdapter.XArgumentsSpecifies a source of x-arguments.
SeriesPoint3DMatrixAdapter.YArgumentsSpecifies a source of y-arguments.
SeriesPoint3DMatrixAdapter.ValuesSpecifies a source of values.

Create Series Programmatically

The following example creates a series in code-behind:

csharp
private void Window_Loaded(object sender, RoutedEventArgs e) {
    Chart3DControl chart = new Chart3DControl();
    this.Content = chart;
    Series3DStorage storage = new Series3DStorage();
    chart.SeriesSource = storage;
    Series3D series = new Series3D() { DisplayName = "Series 1" };
    storage.Series.Add(series);
    series.View = new Bubble3DSeriesView() { MarkerModel = new Marker3DSpherePointModel() };
    SeriesPoint3DStorage pointstorage = new SeriesPoint3DStorage();
    series.PointSource = pointstorage;
    List<DataPoint> BubblePoints = new List<DataPoint>();
    BubblePoints.Add(new DataPoint() { XArgument = "2", YArgument = "USA", Value = 10, Weight = 10 });
    BubblePoints.Add(new DataPoint() { XArgument = "8", YArgument = "Canada", Value = 12, Weight = 15 });
    BubblePoints.Add(new DataPoint() { XArgument = "6", YArgument = "France", Value = 15, Weight = 25 });
    BubblePoints.Add(new DataPoint() { XArgument = "10", YArgument = "Italy", Value = 5, Weight = 5 });
    BubblePoints.Add(new DataPoint() { XArgument = "7", YArgument = "Greece", Value = 13, Weight = 17 });
    foreach (DataPoint dataPoint in BubblePoints) {
        SeriesPoint3D seriesPoint = new SeriesPoint3D(dataPoint.XArgument, dataPoint.YArgument, dataPoint.Value);
        Bubble3DSeriesView.SetWeight(seriesPoint, dataPoint.Weight);
        pointstorage.Points.Add(seriesPoint);
    }
}

public class DataPoint {
    public string XArgument { get; set; }
    public string YArgument { get; set; }
    public double Value { get; set; }

    public double Weight { get; set; }
}
vb
Private Sub Window_Loaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
    Dim chart As Chart3DControl = New Chart3DControl()
    Me.Content = chart
    Dim storage As Series3DStorage = New Series3DStorage()
    chart.SeriesSource = storage
    Dim series As Series3D = New Series3D() With {
        .DisplayName = "Series 1"
    }
    storage.Series.Add(series)
    series.View = New Bubble3DSeriesView() With {
        .MarkerModel = New Marker3DSpherePointModel()
    }
    Dim pointstorage As SeriesPoint3DStorage = New SeriesPoint3DStorage()
    series.PointSource = pointstorage
    Dim BubblePoints As List(Of DataPoint) = New List(Of DataPoint)()
    BubblePoints.Add(New DataPoint() With {
        .XArgument = "2",
        .YArgument = "USA",
        .Value = 10,
        .Weight = 10
    })
    BubblePoints.Add(New DataPoint() With {
        .XArgument = "8",
        .YArgument = "Canada",
        .Value = 12,
        .Weight = 15
    })
    BubblePoints.Add(New DataPoint() With {
        .XArgument = "6",
        .YArgument = "France",
        .Value = 15,
        .Weight = 25
    })
    BubblePoints.Add(New DataPoint() With {
        .XArgument = "10",
        .YArgument = "Italy",
        .Value = 5,
        .Weight = 5
    })
    BubblePoints.Add(New DataPoint() With {
        .XArgument = "7",
        .YArgument = "Greece",
        .Value = 13,
        .Weight = 17
    })

    For Each dataPoint As DataPoint In BubblePoints
        Dim seriesPoint As SeriesPoint3D = New SeriesPoint3D(dataPoint.XArgument, dataPoint.YArgument, dataPoint.Value)
        Bubble3DSeriesView.SetWeight(seriesPoint, dataPoint.Weight)
        pointstorage.Points.Add(seriesPoint)
    Next
End Sub

Public Class DataPoint
    Public Property XArgument As String
    Public Property YArgument As String
    Public Property Value As Double
    Public Property Weight As Double
End Class

Related API members:

MemberDescription
Series3DStorageThe storage of manually created series.
Chart3DControl.SeriesSourceThe Chart3D control’s series source.
SeriesPoint3DStorageThe storage of manually created points.
Series3D.PointSourceThe source of series points.

The Chart3DControl uses the following principle to create points: for each x-argument, all y-arguments and values (the number of required values is equal to the number of y-arguments) are fetched from collections. Use the SeriesPoint3DMatrixAdapter.IsCorrectDimension property to check whether the value collection contains the required number of values to plot the chart.