iOS & macOS Charting Documentation - SciChart iOS & macOS Charts SDK v4.x

The Surface Mesh 3D Chart Type

The surface mesh renders a two-dimensional array as a heightmap. In SciChart it’s defined by the SCISurfaceMeshRenderableSeries3D class and provides a number of configurable chart types in SciChart 3D, including:

dynamic real-time Surfaces (terrains or height maps).
texturing of surfaces or terrains or height maps.
Non-uniform or uniform grid spacing.
Contour mapping or wireframe on terrain or height maps.

Surface Mesh 3D Series Type

NOTE: Examples of the Surface Mesh 3D Series can be found in the SciChart iOS Examples Suite as well as on GitHub:

Obj-C/Swift Example

Xamarin Example

In the Surface Mesh 3D Series, the data is stored in the SCIUniformGridDataSeries3D. This represents a 2-dimensional grid, typically of type double.

Some important points which is mandatory to understand while configuring the Surface Meshes:

The double values which are stored in the SCIUniformGridDataSeries3D correspond to the heights on the chart (the Y-Axis). They are transformed into chart World Coordinates via the ISCIChartSurface3D.yAxis.
The Z and X Data-Value are defined by the StartX, StepX, StartZ and StepZ properties on SCIUniformGridDataSeries3D. These are transformed into World Coordinates via the ISCIChartSurface3D.xAxis and ISCIChartSurface3D.zAxis respectively.
The Colours on the SurfaceMesh are defined by the SCIMeshColorPalette. More on this in the following sections.

The SCISurfaceMeshRenderableSeries3D is highly configurable, so please read on the Configuring Surface Mesh 3D Series section.

Create a Surface Mesh Series 3D

In order to create Uniform Surface Mesh 3D - you will need to provide the SCIUniformGridDataSeries3D with N x M array of points.

The above graph is rendered with the following code:

    SCINumericAxis3D *xAxis = [SCINumericAxis3D new];
    xAxis.growBy = [[SCIDoubleRange alloc] initWithMin:0.1 max:0.1];

    SCINumericAxis3D *yAxis = [SCINumericAxis3D new];
    yAxis.growBy = [[SCIDoubleRange alloc] initWithMin:0.1 max:0.1];
    yAxis.visibleRange = [[SCIDoubleRange alloc] initWithMin:0.0 max:0.3];
    
    SCINumericAxis3D *zAxis = [SCINumericAxis3D new];
    zAxis.growBy = [[SCIDoubleRange alloc] initWithMin:0.1 max:0.1];
    
    SCIUniformGridDataSeries3D *ds = [[SCIUniformGridDataSeries3D alloc] initWithXType:SCIDataType_Double yType:SCIDataType_Double zType:SCIDataType_Double xSize:25 zSize:25];
    
    for (int x = 0; x < 25; ++x) {
        for (int z = 0; z < 25; ++z) {
            double xVal = 25 * x / 25;
            double zVal = 25 * z / 25;
            double yVal = sin(xVal * 0.2) / ((zVal + 1.0) * 2);
            [ds updateYValue:@(yVal) atXIndex:x zIndex:z];
        }
    }
    
    unsigned int colors[7] = { 0xFF1D2C6B, 0xFF0000FF, 0xFF00FFFF, 0xFFADFF2F, 0xFFFFFF00, 0xFFFF0000, 0xFF8B0000 };
    float stops[7] = { 0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0};
    SCIGradientColorPalette *palette = [[SCIGradientColorPalette alloc] initWithColors:colors stops:stops count:7];
    
    SCISurfaceMeshRenderableSeries3D *rs0 = [SCISurfaceMeshRenderableSeries3D new];
    rs0.dataSeries = ds;
    rs0.drawMeshAs = SCIDrawMeshAs_SolidWireframe;
    rs0.stroke = 0x77228B22;
    rs0.strokeThickness = 2.0;
    rs0.drawSkirt = NO;
    rs0.meshColorPalette = palette;
    
    [SCIUpdateSuspender usingWithSuspendable:self.surface withBlock:^{
        self.surface.xAxis = xAxis;
        self.surface.yAxis = yAxis;
        self.surface.zAxis = zAxis;
        [self.surface.renderableSeries add:rs0];
        [self.surface.chartModifiers add:ExampleViewBase.createDefault3DModifiers];
    }];

    let Size: Int = 25

    let xAxis = SCINumericAxis3D()
    xAxis.growBy = SCIDoubleRange(min: 0.1, max: 0.1)
    
    let yAxis = SCINumericAxis3D()
    yAxis.growBy = SCIDoubleRange(min: 0.1, max: 0.1)
    yAxis.visibleRange = SCIDoubleRange(min: 0, max: 0.3)
    
    let zAxis = SCINumericAxis3D()
    zAxis.growBy = SCIDoubleRange(min: 0.1, max: 0.1)
    
    let ds = SCIUniformGridDataSeries3D(xType: .double, yType: .double, zType: .double, xSize: Size, zSize: Size)
    
    for x in 0 ..< Size {
        for z in 0 ..< Size {
            let xVal = Double(25 * x / Size)
            let zVal = Double(25 * z / Size)
            let y = sin(xVal * 0.2) / ((zVal + 1.0) * 2.0)
            ds.update(y: y, atX: x, z: z)
        }
    }
    
    let colors: [UInt32] = [0xFF1D2C6B, 0xFF0000FF, 0xFF00FFFF, 0xFFADFF2F, 0xFFFFFF00, 0xFFFF0000, 0xFF8B0000]
    let stops: [Float] = [0, 0.1, 0.3, 0.5, 0.7, 0.9, 1]
    let palette = SCIGradientColorPalette(colors: colors, stops: stops, count: 7)
    
    let rs = SCISurfaceMeshRenderableSeries3D()
    rs.dataSeries = ds
    rs.drawMeshAs = .solidWireframe
    rs.stroke = 0x77228B22
    rs.contourStroke = 0x77228B22
    rs.strokeThickness = 2.0
    rs.drawSkirt = false
    rs.meshColorPalette = palette
    
    SCIUpdateSuspender.usingWith(surface) {
        self.surface.xAxis = xAxis
        self.surface.yAxis = yAxis
        self.surface.zAxis = zAxis
        self.surface.renderableSeries.add(rs)
        self.surface.chartModifiers.add(ExampleViewBase.createDefault3DModifiers())
    }

    const int xSize = 25;
    const int zSize = 25;

    var dataSeries3D = new UniformGridDataSeries3D(xSize, zSize);

    for (int x = 0; x < xSize; x++)
    {
        for (int z = 0; z < zSize; z++)
        {
            var xVal = 25.0 * x / xSize;
            var zVal = 25.0 * z / zSize;

            var y = Math.Sin(xVal * .2) / ((zVal + 1) * 2);
            dataSeries3D.UpdateYAt(x, z, y);
        }
    }

    var rSeries3D = new SCISurfaceMeshRenderableSeries3D
    {
        DataSeries = dataSeries3D,
        DrawMeshAs = SCIDrawMeshAs.SolidWireframe,
        Stroke = 0x77228B22,
        ContourStroke = 0x77228B22,
        StrokeThickness = 2f,
        DrawSkirt = false,
        MeshColorPalette = new SCIGradientColorPalette(
            new[] { ColorUtil.Sapphire, ColorUtil.Blue, ColorUtil.Cyan, ColorUtil.GreenYellow, ColorUtil.Yellow, ColorUtil.Red, ColorUtil.DarkRed },
            new[] { 0, .1f, .3f, .5f, .7f, .9f, 1 })
    };

    using (Surface.SuspendUpdates())
    {
        Surface.XAxis = new SCINumericAxis3D { GrowBy = new SCIDoubleRange(0.1, 0.1) };
        Surface.YAxis = new SCINumericAxis3D { VisibleRange = new SCIDoubleRange(0, .3) };
        Surface.ZAxis = new SCINumericAxis3D { GrowBy = new SCIDoubleRange(0.1, 0.1) };
        Surface.RenderableSeries.Add(rSeries3D);
        Surface.ChartModifiers.Add(CreateDefault3DModifiers());

        Surface.Camera = new SCICamera3D();
    }

Configuring Surface Mesh 3D Series

There are several properties which affect rendering of the SCISurfaceMeshRenderableSeries3D and those are listed below:

Property	Description
`SCIContourMeshRenderableSeries3DBase.highlight`	Changes the lighting algorithm to make cells appear *lighter*.
`SCIContourMeshRenderableSeries3DBase.meshColorPalette`	defines the `SCIMeshColorPalette` which is used to calculate color from data value. See the Applying Palettes to the 3D Surface Meshes section for more information.
`SCIContourMeshRenderableSeries3DBase.meshPaletteMode`	Changes how the *heightmap* is applied. See the Applying Palettes to the 3D Surface Meshes section for more information.
`SCISurfaceMeshRenderableSeries3D.heightScaleFactor`	Applies a constant *scaling factor* to the heights, e.g. setting to 0 will make the surface mesh flat.
`SCISurfaceMeshRenderableSeries3D.yOffset`	Applies a constant *offset heights*, e.g. setting to 1 will move the SurfaceMesh `1-Data-Value` in the `Y-direction`.

The effect of these properties are demonstrated in the images below.

Highlight = 0	Highlight = 1

HeightScaleFactor = 0	meshPaletteMode = HeightMapSolidCells

Applying Palettes to the 3D Surface Meshes

The SCISurfaceMeshRenderableSeries3D accepts color palettes via the SCIContourMeshRenderableSeries3DBase.meshColorPalette property. There are several palettes available out of the box, including the following:

SCISolidColorBrushPalette - applies a solid color to all cells in the mesh
SCIGradientColorPalette - maps a linear gradient to the mesh.
SCIBrushColorPalette - maps a SCIBrushStyle to the mesh. For example, this can be used to map an image via the SCITextureBrushStyle type.
Custom Palette - maps a custom Texture to the mesh.

Read on to learn more about each of these options.

In addition, rendering all of the above palettes can be affected by the SCIMeshPaletteMode. See the Mesh Palette Modes section below for more information.

Mesh Palette Modes

The SCIContourMeshRenderableSeries3DBase.meshPaletteMode property changes how the palette is applied to the Mesh. Possible SCIMeshPaletteMode are listed in the table below:

Mode	Description
`heightMapInterpolated`	the palette is applied in the `Y-direction` (vertically).
`heightMapSolidCells`	same as `heightMapInterpolated` but no *interpolation*. Use this if you want each cell have a separate colour.
`textured`	palette is applied to the mesh in the XZ plane. Imagine the palette is stretched over the mesh itself.
`texturedSolidCells`	same as `textured` but no *interpolation*. Use this if you want each cell have a separate colour.

Solid Color Palette

The Solid palette if provided by the SCISolidColorBrushPalette class. It’s quite simple, let’s dig into declaration:

    SCISurfaceMeshRenderableSeries3D *rSeries = [SCISurfaceMeshRenderableSeries3D new];
    rSeries.meshColorPalette = [[SCISolidColorBrushPalette alloc] initWithColor:0xFF006400];

    let rSeries = SCISurfaceMeshRenderableSeries3D()
    rSeries.meshColorPalette = SCISolidColorBrushPalette(color: 0xFF006400)

    var rSeries = new SCISurfaceMeshRenderableSeries3D();
    rSeries.MeshColorPalette = new SCISolidColorBrushPalette(0xFF006400);

Surface Mesh Solid Palette

Gradient Color Palette

The SCIGradientColorPalette can be used to map a Gradient Brush set of colors to heights in the Surface Mesh. The mapping is similar to that performed by the Heatmap Series in 2D Charts.

Given the following code:

    unsigned int colors[7] = { 0xFF1D2C6B, 0xFF0000FF, 0xFF00FFFF, 0xFFADFF2F, 0xFFFFFF00, 0xFFFF0000, 0xFF8B0000 };
    float stops[7] = { 0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0};

    SCIGradientColorPalette *palette = [[SCIGradientColorPalette alloc] initWithColors:colors stops:stops count:7];

    let colors: [UInt32] = [0xFF1D2C6B, 0xFF0000FF, 0xFF00FFFF, 0xFFADFF2F, 0xFFFFFF00, 0xFFFF0000, 0xFF8B0000]
    let stops: [Float] = [0, 0.1, 0.3, 0.5, 0.7, 0.9, 1]

    let palette = SCIGradientColorPalette(colors: colors, stops: stops, count: 7)

    var colors = new[] { ColorUtil.Sapphire, ColorUtil.Blue, ColorUtil.Cyan, ColorUtil.GreenYellow, ColorUtil.Yellow, ColorUtil.Red, ColorUtil.DarkRed };
    var stops = new[] { 0, .1f, .3f, .5f, .7f, .9f, 1 };

    var palette = new SCIGradientColorPalette(colors, stops);

Colors are mapped onto Y-values as follows:

SCISurfaceMeshRenderableSeries3D.minimum are drawn with the gradient stop color at offset 0.
SCISurfaceMeshRenderableSeries3D.maximum are drawn with the gradient stop color at offset 1.
All other values are linearly interpolated (including Y-Values outside of minimum and maximum values).

It’s also possible to specify whether gradient is stepped or not. See code which creates stepped palette below:

    SCIGradientColorPalette *palette = [[SCIGradientColorPalette alloc] initWithColors:colors stops:stops count:7 isStepped:YES];

    let palette = SCIGradientColorPalette(colors: colors, stops: stops, count: 7, isStepped: true)

var palette = new SCIGradientColorPalette(colors, stops, true);

And the difference is showed below:

Linear Gradient	Stepped Gradient (isStepped = YES)

Brush Color Palette

A texture can be applied to the SurfaceMesh and mapped over it in the XZ plane plane by using a combination of the following:

See the code below:

    SCIBitmap *bitmap = [UIImage imageNamed:@“image.weather.storm”].sciBitmap;
    SCITextureBrushStyle *brushStyle = [[SCITextureBrushStyle alloc] initWithTexture:bitmap];
    SCIBrushColorPalette *palette = [[SCIBrushColorPalette alloc] initWithBrushStyle:brushStyle];

    rSeries.meshColorPalette = palette;
    rSeries.meshPaletteMode = SCIMeshPaletteMode_Textured;
    rSeries.meshColorPaletteSize = CGSizeMake(bitmap.width, bitmap.height);

    let bitmap = #imageLiteral(resourceName: “image.weather.storm”).sciBitmap()
    let brushStyle = SCITextureBrushStyle(texture: bitmap)
    let palette = SCIBrushColorPalette(brushStyle: brushStyle)
    
    rSeries.meshColorPalette = palette
    rSeries.meshPaletteMode = .textured
    rSeries.meshColorPaletteSize = CGSize(width: CGFloat(bitmap.width), height: CGFloat(bitmap.height))

    var bitmap = new UIImage(“image.weather.storm”).SciBitmap();
    var brushStyle = new SCITextureBrushStyle(bitmap);
    var palette = new SCIBrushColorPalette(brushStyle);

    rSeries.MeshColorPalette = palette;
    rSeries.MeshPaletteMode = SCIMeshPaletteMode.Textured;
    rSeries.MeshColorPaletteSize = new CGSize(bitmap.Width, bitmap.Height);

Surface Mesh Textured Palette

Create a Custom Palette

In addition to all of the above, you can create your own custom Color Palette by inheriting SCIMeshColorPalette and overriding the -[SCIMeshColorPalette getTextureWithWidth:height:] method.

For example, see the following code snippet:

    @interface CustomPalette : SCIMeshColorPalette
    @end

    @implementation CustomPalette

    - (id<ISCITexture2D>)getTextureWithWidth:(int)width height:(int)height {
        SCIBitmap *bitmap = [[SCIBitmap alloc] initWithSize:CGSizeMake(width, height)];
        
        // TODO: Fill Bitmap
        return [bitmap createTexture];
    }

    @end

    class CustomPalette: SCIMeshColorPalette {
        override func getTextureWithWidth(_ width: Int32, height: Int32) -> ISCITexture2D! {
            let bitmap = SCIBitmap(size: CGSize(width: CGFloat(width), height: CGFloat(height)))
            
            // TODO: FIll bitmap
            return bitmap.createTexture()
        }
    }

    class CustomPalette : SCIMeshColorPalette
    {
        public override IISCITexture2D GetTexture(int width, int height)
        {
            var bitmap = new SCIBitmap(new CGSize(width, height));

            // TODO: FIll bitmap
            return bitmap.CreateTexture();
        }
    }

The palette is applied to a SCISurfaceMeshRenderableSeries3D as in the above examples.

NOTE: You might noticed helped extension, which allows to create ISCITexture2D directly from your SCIBitmap - -[SCIBitmap createTexture]

Surface Mesh 3D Wireframe and Contours

In SciChart, the 3D Surface Mesh can be configured to draw with Contours and/or Wireframe. That is added optionally ans configured via the SCIContourMeshRenderableSeries3DBase.drawMeshAs property. See the possible options in the table below:

Option	Surface	Wireframe	Contours
`SolidMesh`	+
`Wireframe`		+
`Contours`			+
`SolidWireframe`	+	+
`SolidWithContours`	+		+
`SolidWireframeWithContours`	+	+	+

Wireframe and Contours can be configured via the following properties:

SCIContourMeshRenderableSeries3DBase.contourStrokeThickness - defines the thickness of the contour line.
SCIContourMeshRenderableSeries3DBase.contourStroke - defines the stroke color of the contours, which may optionally include opacity.
SCIContourMeshRenderableSeries3DBase.contourOffset - defines the offset of contours from Y-values, defaults to 0.
SCIContourMeshRenderableSeries3DBase.contourInterval - defines the Y-value intervals between contours.
SCIContourMeshRenderableSeries3DBase.strokeThickness - defines the thickness of the wireframe line.
SCIContourMeshRenderableSeries3DBase.stroke - defines the stroke color of the wireframe, which may optionally include opacity.

Some examples are shown below:

Bare Wireframe	Solid Surface With Contours

Overriding Surface Mesh 3D Specific Cell Colors

In addition to the custom palettes, heightmaps, textures - you can override a specific cell or cells in the SCISurfaceMeshRenderableSeries3D by using the MetadataProvider API.

For example it can be used for one of the following:

remove specific cells or mark them as NULL by overriding the cell color to be Transparent.
mark regions of interest, say certain cells in a value range, or with index must be colored differently.
with higher resolution meshes, you can change the shape of the mesh to circular (approx) by removing cells outside of a region.

It is showcased in our Surface mesh 3D with Metadata provider example. Let’s see a code snippet from it, which shows how to implement the custom MetadataProvider:

    @interface SurfaceMeshMetaDataProvider3D : SCIMetadataProvider3DBase<SCISurfaceMeshRenderableSeries3D *><ISCISurfaceMeshMetadataProvider3D>
    @end

    @implementation SurfaceMeshMetaDataProvider3D

    - (instancetype)init {
        return [super initWithSeriesType:SCISurfaceMeshRenderableSeries3D.class];
    }

    - (void)updateMeshColors:(SCIUnsignedIntegerValues *)cellColors {
        SCISurfaceMeshRenderPassData3D *currentRenderPassData = (SCISurfaceMeshRenderPassData3D *)self.renderableSeries.currentRenderPassData;
        
        NSInteger countX = currentRenderPassData.countX - 1;
        NSInteger countZ = currentRenderPassData.countZ - 1;
        
        cellColors.count = currentRenderPassData.pointsCount;
        
        unsigned int *items = cellColors.itemsArray;
        for (int x = 0; x < countX; ++x) {
            for (int z = 0; z < countZ; ++z) {
                NSInteger index = x * countZ + z;
                unsigned int color;
                if  ((x >= 20 && x <= 26 && z > 0 && z < 47) || (z >= 20 && z <= 26 && x > 0 && x < 47)) {
                    color = 0x00FFFFFF;
                } else {
                    color = SCDDataManager.randomColor;
                }
                items[index] = color;
            }
        }
    }

    @end

    private class SurfaceMeshMetaDataProvider3D: SCIMetadataProvider3DBase, ISCISurfaceMeshMetadataProvider3D {
        
        init() {
            super.init(seriesType: SCISurfaceMeshRenderableSeries3D.self)
        }
        
        override init(seriesType: AnyClass) {
            super.init(seriesType: seriesType)
        }
        
        func updateMeshColors(_ cellColors: SCIUnsignedIntegerValues!) {
            guard let currentRenderPassData = self.renderableSeries.currentRenderPassData as? SCISurfaceMeshRenderPassData3D else {
                return
            }
            
            let countX = currentRenderPassData.countX - 1
            let countZ = currentRenderPassData.countZ - 1
            
            cellColors.count = currentRenderPassData.pointsCount
            for x in 0 ..< countX {
                for z in 0 ..< countX {
                    let index = x * countZ + z;
                    var color: UInt32 = 0;
                    if  ((x >= 20 && x <= 26 && z > 0 && z < 47) || (z >= 20 && z <= 26 && x > 0 && x < 47)) {
                        color = 0x00FFFFFF;
                    } else {
                        color = SCDDataManager.randomColor()
                    }
                    
                    cellColors.set(color, at: index)
                }
            }
        }
    }

    class SurfaceMeshMetadataProvider3D : SCIMetadataProvider3DBase<SCISurfaceMeshRenderableSeries3D>, IISCISurfaceMeshMetadataProvider3D
    {
        public void UpdateMeshColors(SCIUnsignedIntegerValues cellColors)
        {
            var currentRenderPassData = Runtime.GetNSObject<SCISurfaceMeshRenderPassData3D>(RenderableSeries.CurrentRenderPassData.Handle);
            var dataManager = DataManager.Instance;

            var countX = currentRenderPassData.CountX - 1;
            var countZ = currentRenderPassData.CountZ - 1;
            cellColors.Count = currentRenderPassData.PointsCount;

            for (int x = 0; x < countX; x++)
            {
                for (int z = 0; z < countX; z++)
                {
                    int index = x * countZ + z;

                    uint color = ((x >= 20 && x <= 26 && z > 0 && z < 47) || (z >= 20 && z <= 26 && x > 0 && x < 47))
                        ? ColorUtil.Red
                        : (uint)dataManager.GetRandomColor().ToArgb();
                    
                    cellColors.Set(color, index);
                }
            }
        }
    }

NOTE: For more information about custom MetadataProviders - please refer to the MetadataProvider API article.

MetadataProvider API

NOTE: Examples of using MetadataProvider API can be found in the SciChart iOS Examples Suite as well as on GitHub:

Obj-C/Swift Example

Xamarin Example