Table of contents

• Overview
• License
• How to include the library in your package
• How to include the library in your Jupyter Notebook
• How to setup Docker instance for SwiftPlot
• Examples
  • Simple Line Graph
  • Line Graph with multiple series of data
  • Line Graph with Sub Plots stacked horizontally
  • Plot functions using LineGraph
  • Using a secondary axis in LineGraph
  • Displaying plots in Jupyter Notebook
• How does this work ?
• Documentation
• Limitations
• Guidelines for Contributors
• Credits

Overview

The SwiftPlot framework is a cross-platform library that lets you plot graphs natively in Swift. The existing Swift plotting frameworks (such as CorePlot) run only on iOS or Mac. The idea behind SwiftPlot is to create a cross-platform library that runs on iOS, Mac, Linux and Windows.

SwiftPlot currently uses three rendering backends to generate plots:

• Anti-Grain Geometry(AGG) C++ rendering library
• A simple SVG Renderer
• A Core Graphics renderer with support for macOS, iOS, watchOS and tvOS

To encode the plots as PNG images it uses the lodepng library.
SwiftPlot can also be used in Jupyter Notebooks, with Python interop support for Google Colab.

Examples, demonstrating all the features, have been included with the repository under the Tests/SwiftPlotTests directory. To run the examples, clone the repository, and run the swift test command from the package directory.

Jupyter Notebook examples are under the Notebooks directory.

The resultant images are stored in a directory named output. The Tests folder includes a collection of reference images in the Reference directory.

License

SwiftPlot is licensed under Apache 2.0. View license

How to include the library in your package

Add the library to your projects dependencies in the Package.swift file as shown below.

dependencies: [
        .package(url: "https://github.com/KarthikRIyer/swiftplot.git", from: "2.0.0")),
    ],

In case you get an error saying that a file ft2build.h is not found, you need to install the freetype development package.

Linux

sudo apt-get install libfreetype6-dev

macOS

brew install freetype

If the above method doesn't work you can also build and install freetype on your own. You can find the source code and build instructions here.

How to include the library in your Jupyter Notebook

Add these lines to the first cell:

%install-swiftpm-flags -Xcc -isystem/usr/include/freetype2 -Xswiftc -lfreetype
%install '.package(url: "https://github.com/IBM-Swift/BlueCryptor.git", from: "1.0.28")' Cryptor
%install '.package(url: "https://github.com/KarthikRIyer/swiftplot", from: "2.0.0")' SwiftPlot AGGRenderer

In order to display the generated plot in the notebook, add this line to a new cell:

%include "EnableJupyterDisplay.swift"

If you wish to display the generated plot in a Google Colab environment, add these lines to a new cell instead:

import Python
%include "EnableIPythonDisplay.swift"
func display(base64EncodedPNG: String) {
  let displayImage = Python.import("IPython.display")
  let codecs = Python.import("codecs")
  let imageData = codecs.decode(Python.bytes(base64EncodedPNG, encoding: "utf8"), encoding: "base64")
  displayImage.Image(data: imageData, format: "png").display()
}

Note that because Google Colab doesn't natively support Swift libraries that produce rich output, we use Swift's Python interop as a workaround.

How to setup Docker instance for SwiftPlot

For computers running MacOS or Windows, Docker instance is to easy to setup and use swift-jupyter. Please refer SwiftPlot_Docker_setup.md for setup instructions.

Examples

Here are some examples to provide you with a headstart to using this library. Here we will be looking at plots using only the AGGRenderer, but the procedure will remain the same for SVGRenderer. To use the library in your package, include it as a dependency to your target, in the Package.swift file.

More tests can be found in the SwiftPlotTests folder.

Simple Line Graph

import SwiftPlot
import AGGRenderer

let x:[Float] = [10,100,263,489]
let y:[Float] = [10,120,500,800]

var agg_renderer: AGGRenderer = AGGRenderer()
var lineGraph = LineGraph<Float,Float>(enablePrimaryAxisGrid: true)
lineGraph.addSeries(x, y, label: "Plot 1", color: .lightBlue)
lineGraph.plotTitle.title = "SINGLE SERIES"
lineGraph.plotLabel.xLabel = "X-AXIS"
lineGraph.plotLabel.yLabel = "Y-AXIS"
lineGraph.plotLineThickness = 3.0
lineGraph.drawGraphAndOutput(fileName: filePath+"agg/"+fileName, renderer: agg_renderer)

Line Graph with multiple series of data

import SwiftPlot
import AGGRenderer
import SVGRenderer

let x1:[Float] = [0,100,263,489]
let y1:[Float] = [0,320,310,170]
let x2:[Float] = [0,50,113,250]
let y2:[Float] = [0,20,100,170]

var agg_renderer: AGGRenderer = AGGRenderer()
var lineGraph = LineGraph<Float,Float>(enablePrimaryAxisGrid: true)
lineGraph.addSeries(x1, y1, label: "Plot 1", color: .lightBlue)
lineGraph.addSeries(x2, y2, label: "Plot 2", color: .orange)
lineGraph.plotTitle.title = "MULTIPLE SERIES"
lineGraph.plotLabel.xLabel = "X-AXIS"
lineGraph.plotlabel.yLabel = "Y-AXIS"
lineGraph.plotLineThickness = 3.0
lineGraph.drawGraphAndOutput(fileName: filePath+"agg/"+fileName, renderer: agg_renderer)

Line Graph with Sub Plots stacked horizontally

import SwiftPlot
import AGGRenderer

let x:[Float] = [10,100,263,489]
let y:[Float] = [10,120,500,800]

var agg_renderer: AGGRenderer = AGGRenderer()
var subplot = SubPlot(layout: .horizontal)

var lineGraph1 = LineGraph<Float,Float>(enablePrimaryAxisGrid: true)
lineGraph1.addSeries(x, y, label: "Plot 1", color: .lightBlue)
lineGraph1.plotTitle.title = "PLOT 1"
lineGraph1.plotLabel.xLabel = "X-AXIS"
lineGraph1.plotLabel.yLabel = "Y-AXIS"
lineGraph1.plotLineThickness = 3.0

var lineGraph2 = LineGraph<Float,Float>(enablePrimaryAxisGrid: true)
lineGraph2.addSeries(x, y, label: "Plot 2", color: .orange)
lineGraph2.plotTitle.title = "PLOT 2"
lineGraph2.plotLabel.xLabel = "X-AXIS"
lineGraph2.plotLabel.yLabel = "Y-AXIS"
lineGraph2.plotLineThickness = 3.0

subplot.plots = [lineGraph1, lineGraph2]
subPlot.drawGraphAndOutput(fileName: "subPlotsHorizontallyStacked", renderer: agg_renderer)

Plot functions using LineGraph

import Foundation
import SwiftPlot
import AGGRenderer

func function(_ x: Float)->Float {
    return 1.0/x
}

var agg_renderer: AGGRenderer = AGGRenderer()
var lineGraph = LineGraph<Float,Float>(enablePrimaryAxisGrid: true)
lineGraph.addFunction(function, minX: -5.0, maxX: 5.0, numberOfSamples: 400, clampY: -50...50, label: "Function", color: .orange)
lineGraph.plotTitle.title = "FUNCTION"
lineGraph.plotLabel.xLabel = "X-AXIS"
lineGraph.plotLabel.yLabel = "Y-AXIS"
lineGraph.drawGraphAndOutput(fileName: "functionPlotLineGraph", renderer: agg_renderer)

Using a secondary axis in LineGraph

import SwiftPlot
import AGGRenderer

let x:[Float] = [10,100,263,489]
let y:[Float] = [10,120,500,800]
let x1:[Float] = [100,200,361,672]
let y1:[Float] = [150,250,628,800]

var agg_renderer: AGGRenderer = AGGRenderer() 
var lineGraph = LineGraph<Float,Float>()
lineGraph.addSeries(x1, y1, label: "Plot 1", color: .lightBlue, axisType: .primaryAxis)
lineGraph.addSeries(x, y, label: "Plot 2", color: .orange, axisType: .secondaryAxis)
lineGraph.plotTitle.title = "SECONDARY AXIS"
lineGraph.plotLabel.xLabel = "X-AXIS"
lineGraph.plotLabel.yLabel = "Y-AXIS"
lineGraph.plotLineThickness = 3.0
lineGraph.drawGraphAndOutput(fileName: filePath+"agg/"+fileName, renderer: agg_renderer)

The series plotted on the secondary axis are drawn dashed.

Displaying plots in Jupyter Notebook

You can display plots in Jupyter Notebook using only the AGGRenderer. To do so, create the plots as shown in the above examples and instead of using the drawGraphAndOutput function from LineGraph, use the drawGraph function, then get a base64 encoded image from the AGGRenderer and pass it to the display function as showm below:

lineGraph.drawGraph(renderer: agg_renderer)
display(base64EncodedPNG: agg_renderer.base64Png())

How does this work

All the plotting code, utility functions, and necessary types are included in the SwiftPlot module. Each Renderer is implemented as a separate module. Each Renderer must have SwiftPlot as its dependency and must conform to the Renderer protocol defined in Renderer.swift in the SwiftPlot module. Each plot type is a generic that accepts data conforming to a protocol, FloatConvertible. At the moment FloatConvertible supports both Float and Double. The Renderer protocol defines all the necessary functions that a Renderer needs to implement. Each Plot must conform to the Plot protocol. At the moment this protocol defines the necessary variablse and functions that each Plot must implement in order to support SubPlots.

You can add series to the plots using their respective functions(addSeries for LineGraph). This is stored in as an array of Series objects. You can set other properties such as plotTitle, plotLabel, plotDimensions, etc. To actually generate the plot you need to call either the drawGraph or drawGraphAndOutput function. This calculates all the parameters necessary to generate the plots such as the coordinates of the border, scaled points to plot, etc. Then it sends over this information to the renderer which has functions to draw primitives like lines, rectangles and text.

In case the Renderer is in C++(here in the case of AGG), a C wrapper is written which is in turn wrapped in Swift.

In order to display the plots in Jupyter notebook, we encode the image(which is in the form of an RGB buffer) to a PNG image in memory and return the encoded image to the Swift code where it is stored as NSData. Then it is encoded to base64 and passed to the display function in swift-jupyter which finally displays the image.

Documentation

LineGraph<T: FloatConvertible, U: FloatConvertible>

BarChart<T: LosslessStringConvertible, U: FloatConvertible>

Histogram

ScatterPlot<T:FloatConvertible, U:FloatConvertible>

SubPlot

PlotDimensions

Pair<T,U>

PlotLabel

PlotTitle

Color

Built-in Colors can be found here.

PlotLabel

Axis<T,U>

ScatterPlotSeriesOptions

HistogramSeriesOptions

BarGraphSeriesOptions

Base64Encoder

Limitations

• FloatConvertible supports only Float and Double. We plan to extend this to Int in the future.

Guidelines for Contributors

If you want to contribute to improve this library, please read our guidelines. Feel free to open an issue.

Credits

1. Maxim Shemanarev : The AGG library is directly used to render plots.
2. Lode Vandevenne : The lodepng library is directly used to encode PNG images.
3. The FreeType Project : AGG uses FreeType to draw text.
4. Brad Larson and Marc Rasi for their invaluable guidance.