gplot++

A header-only C++ interface to Gnuplot. See this video for a demo (running Visual Studio under Windows 10).

This repository contains the file gplot++.h, which provides a way for C++ programs to connect to a Gnuplot instance to produce plots. To use this library, you must first install Gnuplot on your system!

A few features of this library are the following:

• Header-only library: very easy to install
• Plot std::vector variables
• Multiple series in the same plot
• Multiple plots (via Gnuplot::multiplot)
• Logarithmic axes (via Gnuplot::set_logscale)
• Histograms (via Gnuplot::histogram)
• Custom ranges (via Gnuplot::set_xrange and Gnuplot::set_yrange)
• Possibility to save the plots in PNG and PDF files
• 3D plots (new in 0.2.0)

Table of Contents

• gplot++
• Table of Contents
  • Installing Gnuplot and gplot++.h
    • Windows
    • Linux
    • Mac OS X
    • Installing gplot++.h
  • Examples
  • Documentation
    • Initializing a connection to Gnuplot
    • Plot commands
    • Histograms
    • Line styles
    • Styling the plot axes
    • Logarithmic scale
    • Multiple plots
    • Error bars
    • 3D plots
    • Vector fields
    • Saving plots to a file
    • Animations
    • Low-level interface
  • Similar libraries
  • Changelog
  • Changelog
    • HEAD
    • v0.10.0
    • v0.9.1
    • v0.9.0
    • v0.8.0
    • v0.7.0
    • v0.5.1 (a.k.a. 0.6.0)
    • v0.5.0
    • v0.4.0
    • v0.3.1
    • v0.3.0
    • v0.2.1
    • v0.2.0
    • v0.1.0

<!-- Created by https://github.com/ekalinin/github-markdown-toc -->

Installing Gnuplot and gplot++.h

Of course, before using gplot++.h you must have Gnuplot installed and available in the PATH! We provide here instructions about how to install Gnuplot under Windows, Mac OS X, and Linux.

Windows users, beware that the standard installation won't work with gplot++.h because you need to activate a flag during the installation!

Windows

Download the Gnuplot installer from the SourceForge website. Be sure not to download the .tar.gz file; instead, you should download the file ending with .exe, e.g., gp542-win64-mingw.exe.

When you run the installer, pay attention to the option Add application directory to your PATH environment variable while installing Gnuplot, otherwise gplot++.h will fail to generate the plots! See this video for help.

Linux

Linux users should use their package manager to install Gnuplot:

# Debian, Ubuntu, Linux Mint
sudo apt-get install gnuplot

# Arch, Manjaro
sudo pacman -Syu gnuplot

# Fedora
sudo dns install gnuplot

Mac OS X

The preferred way to install Gnuplot is using Homebrew from the terminal:

brew install gnuplot

Installing gplot++.h

Once you have Gnuplot installed, download the file gplot++.h and save it in the same folder as your program. That's all.

This video shows how to include gplot++.h in a C++ project created using Visual Studio 2019 (Windows).

Examples

Here is the output of one of the examples:

The source code of the example is in file example-complex.cpp:

#include "gplot++.h"

int main(void) {
  Gnuplot plt{};
  std::vector<double> x{1, 2, 3, 4, 5}, y{5, 2, 4, 1, 3};

  // Save the plot into a PNG file with the desired size (in pixels)
  plt.redirect_to_png("complex.png", "800,600");

  /* Create two plots with the following layout (2 rows, 1 column):
   *
   * +------------------------+
   * |                        |
   * |        Plot #1         |
   * |                        |
   * +------------------------+
   * |                        |
   * |        Plot #2         |
   * |                        |
   * +------------------------+
   */
  plt.multiplot(2, 1, "Title");

  // Plot #1
  plt.set_title("Plot #1");
  plt.set_xlabel("X axis");
  plt.set_ylabel("Y axis");
  plt.plot(x, y, "x-y plot");
  plt.plot(y, x, "y-x plot", Gnuplot::LineStyle::LINESPOINTS);
  plt.show(); // Always call "show"!

  // Plot #2
  plt.set_title("Plot #2");
  plt.set_xlabel("Value");
  plt.set_ylabel("Number of counts");
  plt.histogram(y, 2, "Histogram");
  plt.set_xrange(-1, 7);
  plt.set_yrange(0, 5);
  plt.show(); // Always call "show"!
}

Documentation

Initializing a connection to Gnuplot

The only symbol exported by file gplot++.h is the Gnuplot class. When you instance an object of this class, it will silently start gnuplot in the background and open a pipe through it:

#include "gplot++.h"

int main() {
    Gnuplot plt{};
    
    // ...
}

If Gnuplot is not available in your PATH (probably this is most common on Windows system), you can specify the full path to the executable:

#include "gplot++.h"

int main() {
    Gnuplot plt{R"(C:\Program Files\Gnuplot\gnuplot.exe)"};
    
    // ...
}

The connection will be automatically closed once the variable plt goes out of scope; by default, the Gnuplot window will be left open. In this way, you can navigate through the Gnuplot window even after your C++ has completed its execution.

Plot commands

There are two ways to produce a plot; both require you to call the Gnuplot::plot method:

1. Pass one std::vector variable, which will be used to set the y coordinates of the points;
2. Pass two std::vector variables; these will be used to set the (x, y) coordinates of the points.

You can call plot multiple times, and each time your call will be recorded in a list. When you are ready to produce a plot, call Gnuplot::show, like in the following example:

several ways to produce a plot. Each of them requires you to pass the data to plot through one or more std::vector variables:

std::vector<int> x{1, 2, 4};  // No problem to use a vector of ints
std::vector<double> y1{3.1, -4.6, 5.1};
std::vector<double> y2{1.3, 1.6, 4.1};

Gnuplot plt{};
// Just pass the set of y values
plt.plot(y1);

// You can provide a label and a linestyle
plt.plot(x, y2, "Dataset #1", Gnuplot::LineStyle::LINESPOINTS);

// Now produce the plot
plt.show();

New in version 0.7.0: Instead of providing the two vectors, you can call Gnuplot::add_point() repeatedly and then call Gnuplot::plot() without specifying vectors. See the example program example-addpoint.cpp.

Histograms

Gplot++ implements the method Gnuplot::histogram, which computes the histogram of a series and plot it using Gnuplot. Here is an example (example-histogram.cpp):

#include "gplot++.h"

int main(void) {
  Gnuplot gnuplot{};
  std::vector<double> y{5, 2, 4, 1, 3};

  gnuplot.histogram(y, 2, "Histogram");

  gnuplot.set_xlabel("Value");
  gnuplot.set_ylabel("Number of counts");
  gnuplot.set_xrange(1, 5);
  gnuplot.set_yrange(0, 5);

  gnuplot.show();
}

The parameters to Gnuplot::histogram are the following:

• A vector containing the values to use in the plot;

• The number of bins to plot (two bins in the example above);

• A label for the plot (optional, default is empty)

• The line style (optional, default is Gnuplot::LineStyle::BOXES)

Line styles

There are several line styles:

• Gnuplot::LineStyle::DOTS (only use this when you have many points);

• Gnuplot::LineStyle::LINES (the default);

• Gnuplot::LineStyle::POINTS;

• Gnuplot::LineStyle::LINESPOINTS;

• Gnuplot::LineStyle::STEPS;

• Gnuplot::LineStyle::BOXES (only used for histograms).

• Gnuplot::LineStyle::VECTORS (only used for 2D and 3D vector fields).

Styling the plot axes

You can manually assign a range to the X and Y axes using the methods Gnuplot::set_xlabel and Gnuplot::set_ylabel:

Gnuplot plt{};

plt.set_xrange(1.5, 3.5);
plt.set_yrange(); // No parameters means automatic axes

If you are creating multiple plots (see below), you should probably reset the x and y ranges after each call to Gnuplot::show.

You can also provide a label for both axes:

plt.set_xlabel("Time [s]");
plt.set_ylabel("Speed [cm/s]");

Logarithmic scale

To set a logarithmic scale, use Gnuplot::set_logscale:

Gnuplot plt{};

plt.set_logscale(Gnuplot::AxisScale::LOGXY);

Possible parameters are:

• Gnuplot::AxisScale::LINEAR (the default);
• Gnuplot::AxisScale::LOGX;
• Gnuplot::AxisScale::LOGY;
• Gnuplot::AxisScale::LOGXY.

Multiple plots

You can make several plots within th