Updates

README.md

@@ -1,30 +1,74 @@
-Extended GNUPlot wrapper
-========================
+gnuplot C interface library
+===========================
 
-This is a modification of the gnuplot_i library by N.Devillard, which enables the following functionality:
+Overview
+--------
 
-*    3D plots, using gnuplot_splot(handle,x,y,z,n,"title");
-*    Setting z-axis labels with gnuplot_set_zlabel(handle,"z-axis label");
-*    Production of colour PostScript files with gnuplot_hardcopy_colour(handle,"graph.ps");
-*    Windows support - added in September 2005.
-*    Plotting of complex structures through the use of callbacks - see gnuplot_plot_obj_xy and gnuplot_splot_obj in gnuplot_i.c.
-*    Contour plotting, using gnuplot_setstyle(handle,"lines");gnuplot_contour_plot(handle,x,y,z,nx,ny,"title");
+The `gnuplot_i` interface library enables developers to create [gnuplots](http://www.gnuplot.info/) directly from their C programs.
 
-If you have any questions or comments, these can be sent to [email protected], or via my website (http://www.robert-bradley.co.uk).
+The program works by creating a UNIX pipe through which gnuplot commands are sent and then executed. 
 
-Changelog
----------
+The central data structure is the gnuplot control handle, which holds the gnuplot commands as well as technical internal information, such as terminal type, amount of open windows and such. 
+
+The plot can be displayed in its own window or otherwise saved as an image file to disk.
+
+Example of a minimal program structure:
+
+    #include "gnuplot_i.h"
+
+    gnuplot_ctrl *handle = gnuplot_init();
+    gnuplot_setterm (handle, "wxt", 600, 400);
+    gnuplot_plot_equation (handle, "sin(x)", "Sine wave");
+    gnuplot_close (handle);
+
+
+Provenance
+----------
+
+This program was originally developed by Nicolas Devillard (2000) who also placed it in the public domain. 
+Other authors have contributed to this library:
+* Peter Maresh (2010): compile and run on MS-Windows 7/64 using mingw64.
+* Robert Bradley (2004-2006): functional enhancements, see next section.
+* longradix (2023): refactoring, error handling, stylistic improvements, documentation updates.
+
+
+Enhancements
+------------
 
-2nd April 2006 - Added gnuplot_splot_grid for plotting 2D arrays of data, and restored the lost contour plotting code.
+This interface library features the following enhancements from the original program:
 
-13th March 2006 - Fixed "bus error" under OS X when not using X11 and USE_AQUA environment variable is not set.
+* 3D plots, using `gnuplot_splot (handle, x, y, z, n, "title")`.
+* Setting z-axis labels with `gnuplot_set_axislabel (handle, "z-axis label", "z")`.
+* Production of colour PostScript files with `gnuplot_hardcopy (handle, "graph.ps")`.
+* Windows support.
+* On OS X, if `DISPLAY` environment variable is not set or `USE_AQUA=1`, then aqua is used instead of x11.
+* Plotting of complex structures through the use of callbacks, see `gnuplot_plot_obj_xy` and `gnuplot_splot_obj`.
+* Contour plotting with `gnuplot_setstyle (handle, "lines")` and `gnuplot_contour_plot (handle, x, y, z, nx, ny, "title")`.
 
-23rd November 2005 - gnuplot_contour_plot added (plots contours, use gnuplot_setstyle to set the contour style)
+If you have any questions or comments, these can be sent to [email protected], or via the [website](http://www.robert-bradley.co.uk).
 
-15th September 2005 - Added possible OS X support, plus the gnuplot_plot_obj_xy and gnuplot_splot_obj functions.
 
-11th September 2005 - Windows support added
+Examples
+--------
 
-14th August 2005 - included fixes from the official version 2.10
+This library comes with the following examples:
+
+* **example.c**: a garden variety of `gnuplot_i` function calls to demonstrate general usage and capabilities.
+* **animation.c**: a brief animation of a run-time generated sine wave.
+* **sinepng.c**: a demonstration of how `gnuplot_i` can be used to store its output as a file.
+
+Compilation instructions are included in each of these examples.
+
+
+Documentation
+-------------
+
+A tutorial is available in `tutorial.md`.
+
+Documentation of macros, includes, functions and prototypes can be straightforwardly generated using [doxygen](https://www.doxygen.nl) and/or the [doxywizard](https://www.doxygen.nl/manual/doxywizard_usage.html). A Doxyfile is provided for this purpose.
+
+
+Licensing
+---------
 
-2nd November 2004 - initial version uploaded (based on gnuplot_i v2.6)
+This library has been licensed under the GPL, same as all other GNU software, and is therefore less strict than the [gnuplot license](https://spdx.org/licenses/gnuplot.html) itself. 

TODO

@@ -0,0 +1,11 @@
+* More unit tests as not all functions are being covered by tests, notably 3D plots, such as contourplots and heatmaps.
+* Improve print_gnuplot_handle().
+* Further refactoring.
+* wxt is the default terminal type, but need a test to check whether wxWidgets is actually installed: find / -name libwx* 2>/dev/null
+* Plotting styles have been added to gnuplot since this interface library was completed, hence further testing and documentation.
+* Do common pitfalls lead to a graceful exit?
+* More field testing is needed: 
+  - Does the current version still work on MS-Windows / OS-X / other operating systems? 
+  - How does it perform in high-volume or high-performance environments?
+  - Are there limitations which need to be looked at, for example the maximum amount of open gnuplot files (GP_MAX_TMP_FILES)?
+  - Does it still work if gnuplot is installed but qt or wxWidgets is not?

examples/animation.c

@@ -0,0 +1,35 @@
+/*
+ * Examples of gnuplot_i.c usage
+ * Compilation: gcc -Wall -g animation.c gnuplot_i.c -o animation
+ *
+ * This program produces an animated sine wave in a gnuplot window.
+ * It does so by reeatedly calling gnuplot_resetplot() and gnuplot_cmd()
+ * in a loop.
+ * The gnuplot window closes after all equation-plots have been generated.
+ *
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include "../gnuplot_i.h"
+
+int main(int argc, char *argv[]) {
+  gnuplot_ctrl *handle;
+  double phase;
+
+  printf("*** example of gnuplot control through C ***\n");
+  handle = gnuplot_init();
+
+  for (phase = 0.1; phase < 10; phase += 0.1) {
+    gnuplot_resetplot(handle);
+    gnuplot_cmd(handle, "plot sin(x+%g)", phase);
+  }
+
+  for (phase = 10; phase >= 0.1; phase -= 0.1) {
+    gnuplot_resetplot(handle);
+    gnuplot_cmd(handle, "plot sin(x+%g)", phase);
+  }
+
+  gnuplot_close(handle);
+  return 0;
+}

examples/bentcoolwarm.palette

@@ -0,0 +1,53 @@
+# Palette from Kenneth Moreland
+# http://www.kennethmoreland.com/color-advice/
+# https://raw.githubusercontent.com/bruceravel/Graphics-Gnuplot-Palettes/master/lib/Graphics/Gnuplot/Palettes/Moreland/BentCoolWarm.pm
+# 
+# to use this palette in gnuplot:
+# load "bentcoolwarm.palette"
+# set output "bentcoolwarm.png"
+# test palette
+
+# line styles
+set style line 1 lt 1 lc rgb '#5548c1' #
+set style line 2 lt 1 lc rgb '#7982d7' #
+set style line 3 lt 1 lc rgb '#abb8e7' #
+set style line 4 lt 1 lc rgb '#dde3ef' #
+set style line 5 lt 1 lc rgb '#ead3c6' #
+set style line 6 lt 1 lc rgb '#dba188' #
+set style line 7 lt 1 lc rgb '#ca6b55' #
+set style line 8 lt 1 lc rgb '#b10027' #
+
+# palette
+set palette defined (\
+0.000000  0.334791  0.283084  0.756495,\
+0.032258  0.358463  0.329961  0.777134,\
+0.064516  0.384197  0.375595  0.796252,\
+0.096774  0.412066  0.420411  0.813918,\
+0.129032  0.442119  0.464652  0.830208,\
+0.161290  0.474392  0.508463  0.845204,\
+0.193548  0.508911  0.551927  0.858994,\
+0.225806  0.545690  0.595092  0.871671,\
+0.258065  0.584740  0.637982  0.883336,\
+0.290323  0.626066  0.680601  0.894092,\
+0.322581  0.669670  0.722945  0.904050,\
+0.354839  0.715549  0.764998  0.913324,\
+0.387097  0.763702  0.806740  0.922035,\
+0.419355  0.814122  0.848146  0.930308,\
+0.451613  0.866801  0.889187  0.938272,\
+0.483871  0.921729  0.929831  0.946064,\
+0.516129  0.943107  0.925843  0.914369,\
+0.548387  0.929415  0.877320  0.844886,\
+0.580645  0.915786  0.828497  0.777697,\
+0.612903  0.902058  0.779359  0.712904,\
+0.645161  0.888093  0.729874  0.650600,\
+0.677419  0.873772  0.679993  0.590875,\
+0.709677  0.858993  0.629636  0.533813,\
+0.741935  0.843670  0.578682  0.479498,\
+0.774194  0.827730  0.526951  0.428010,\
+0.806452  0.811110  0.474162  0.379431,\
+0.838710  0.793759  0.419874  0.333847,\
+0.870968  0.775631  0.363343  0.291350,\
+0.903226  0.756686  0.303214  0.252045,\
+0.935484  0.736891  0.236622  0.216053,\
+0.967742  0.716213  0.155523  0.183513,\
+1.000000  0.694626  0.002965  0.154582)

examples/example.c

@@ -0,0 +1,194 @@
+/*
+ * Examples of gnuplot_i.c usage
+ * Compilation: gcc -Wall -g example.c gnuplot_i.c -o example -lm
+ *
+ * TODO
+ * - need an example for gnuplot_splot_grid(), gnuplot_splot_obj(), gnuplot_plot_obj_xy()
+ *
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <math.h>
+#include "../gnuplot_i.h"
+
+#define SECONDS 1
+#define NPOINTS 50
+
+int main(int argc, char *argv[]) {
+  gnuplot_ctrl *h1, *h2, *h3;
+  double x[NPOINTS], y[NPOINTS], z[NPOINTS];
+  int i;
+
+  /** Initialize the gnuplot handle */
+
+  printf("*** Examples of gnuplot control through C ***\n");
+  h1 = gnuplot_init();
+
+  /** Dumb terminal: ASCII-plot */
+  /** Simplest usage of gnuplot_cmd function with fewest dependencies */
+
+  printf("\n*** dumb terminal\n");
+  gnuplot_setterm(h1, "dumb", 150, 40);
+  gnuplot_cmd(h1, "plot sin(x) w lines, cos(x) w lines");
+  sleep(SECONDS);
+
+  /** Equations */
+
+  printf("\n*** various equations\n");
+  gnuplot_setterm(h1, "wxt", 900, 400);
+  gnuplot_resetplot(h1);
+  printf("y = sin(x)\n");
+  gnuplot_plot_equation(h1, "sin(x)", "sine points");  // points is the default linestyle
+  sleep(SECONDS);
+  printf("y = sin(x)*cos(2*x)\n");
+  gnuplot_setstyle(h1, "lines");
+  gnuplot_plot_equation(h1, "sin(x)*cos(2*x)", "sines lines");
+  sleep(SECONDS);
+  printf("y = 2*x-1\n");
+  gnuplot_setstyle(h1, "dots");
+  gnuplot_plot_equation(h1, "2*x-1", "slope dots");
+  sleep(SECONDS);
+
+  /** Styles */
+
+  printf("\n*** various styles\n");
+  gnuplot_resetplot(h1);
+  printf("sin(x) in linespoints\n");
+  gnuplot_setstyle(h1, "linespoints");
+  gnuplot_plot_equation(h1, "sin(x)", "sine linespoints");
+  sleep(SECONDS);
+  printf("cos(x/pi) in impulses\n");
+  gnuplot_setstyle(h1, "impulses");
+  // note that M_PI cannot be used in the denominator, since that is not known to gnuplot...
+  gnuplot_plot_equation(h1, "cos(x/(atan(1)*4))", "sine impulses");
+  sleep(SECONDS);
+  printf("atan(x/pi) in steps\n");
+  gnuplot_setstyle(h1, "steps");
+  // ...but it is possible to use gnuplot constants, such as "pi"
+  gnuplot_plot_equation(h1, "atan(x/pi)", "arctangens steps");
+  sleep(SECONDS);
+
+  /** User defined 1d and 2d point sets */
+
+  printf("\n*** user-defined list of points: 1d\n");
+  gnuplot_resetplot(h1);
+  printf("quadratic 1d array\n");
+  gnuplot_setstyle(h1, "points");
+  gnuplot_set_axislabel(h1, "x", "X");
+  for (i = 0; i < NPOINTS; i++) {
+    x[i] = (double)i * i;
+  }
+  gnuplot_plot_coordinates(h1, x, y, NPOINTS, "user-defined points: 1d");   // note: y is NULL
+  sleep(SECONDS);
+
+  printf("\n*** user-defined lists of points: 2d\n");
+  gnuplot_resetplot(h1);
+  printf("square root 2d array\n");
+  gnuplot_setstyle(h1, "points");
+  gnuplot_set_axislabel(h1, "y", "square root");
+  for (i = 0; i < NPOINTS; i++) {
+    x[i] = (double)i/2;  // change of axis scale
+    y[i] = sqrt(i);
+  }
+  gnuplot_plot_coordinates(h1, x, y, NPOINTS, "user-defined points: 2d");
+  sleep(SECONDS);
+
+  /** gnuplot_plot_once demo: User defined 1d and 2d point sets */
+
+  printf("\n*** gnuplot_plot_once: user-defined list of doubles\n");
+  gnuplot_plot_once ("lines", "X", "Y", x, y, NPOINTS, "list of doubles (plot once)");
+
+  /** Splot (surface plot) example */
+
+  printf("\n*** parametric 3D plot\n");
+  gnuplot_resetplot(h1);
+  printf("lissajous curve in 3d space\n");
+  gnuplot_setstyle(h1, "lines");
+  gnuplot_set_axislabel(h1, "x", "X");
+  gnuplot_set_axislabel(h1, "y", "Y");
+  gnuplot_set_axislabel(h1, "z", "Z-axis");
+  for (int i = 0; i < NPOINTS; i++) {
+    x[i] = 2*sin((double)i/3);
+    y[i] = 5*sin((double)i/2 + 1);
+    z[i] = x[i] + y[i];
+  }
+  printf("Internal debugging information:\n");
+  print_gnuplot_handle(h1);
+  gnuplot_splot(h1, x, y, z, NPOINTS, "Lissajous");
+  sleep(SECONDS);
+
+  /** Contour plot example */
+
+  printf("\n*** contour plot\n");
+  gnuplot_resetplot(h1);
+  printf("contour of multivariate bell curve\n");
+  double xx[NPOINTS*NPOINTS], yy[NPOINTS*NPOINTS], zz[NPOINTS*NPOINTS];
+  for (int i = 0; i < NPOINTS; i++) {
+    for (int j = 0; j < NPOINTS; j++) {
+      xx[NPOINTS*i+j] = i;
+      yy[NPOINTS*i+j] = j;
+      zz[NPOINTS*i+j] = 1000*sqrt(pow(i-NPOINTS/2, 2)+pow(j-NPOINTS/2, 2));
+    }
+  }
+  gnuplot_setstyle(h1, "lines");
+  gnuplot_contour_plot(h1, xx, yy, zz, NPOINTS, NPOINTS, "Contour");
+  sleep(SECONDS);
+
+  /** Scatter plot: gnuplot example with data file */
+  /** Note that the program exits gracefully if file is not present, not readable or mispelled **/
+
+  printf("\n*** scatter plot: data file\n");
+  gnuplot_resetplot(h1);
+  gnuplot_set_axislabel(h1, "x", "avg(mRS)");
+  gnuplot_set_axislabel(h1, "y", "alpha");
+  gnuplot_cmd(h1, "plot 'scatter.data' with points pointtype '•' linecolor 'blue'");
+  sleep(SECONDS);
+
+  /** Contour plot with color palette*/
+  /** if no color palette is found, then gnuplots standard color palette will be used: rgbformulae */
+  /** This does not work yet: no z-axis is shown */
+
+  printf("\n*** contour plot with palette\n");
+  gnuplot_resetplot(h1);
+  gnuplot_set_axislabel(h1, "x", "shape");
+  gnuplot_set_axislabel(h1, "y", "scale");
+  gnuplot_set_axislabel(h1, "z", "alpha");
+  gnuplot_cmd(h1, "set parametric");
+  gnuplot_cmd(h1, "set contour base");
+  gnuplot_cmd(h1, "set style data lines");
+  gnuplot_cmd(h1, "set dgrid3d 20, 20, 20");
+  gnuplot_cmd(h1, "set title 'Alpha-parameter by shape and scale'");
+  gnuplot_cmd(h1, "load 'bentcoolwarm.palette'");
+  gnuplot_cmd(h1, "set pm3d");
+  gnuplot_cmd(h1, "splot 'indicatorvalues.data'");
+  sleep(SECONDS);
+
+  /** Multiple output screens */
+
+  printf("\n*** multiple output windows\n");
+  gnuplot_resetplot(h1);
+  gnuplot_setstyle(h1, "lines");
+  h2 = gnuplot_init();
+  gnuplot_setstyle(h2, "lines");
+  h3 = gnuplot_init();
+  gnuplot_setstyle(h3, "filledcurves");
+  printf("window 1: x*sin(x)\n");
+  gnuplot_cmd(h1, "set linecolor rgb 'blue'");   // this does not work yet
+  gnuplot_plot_equation(h1, "x*sin(x)", "x*sin(x)");
+  sleep(SECONDS);
+  printf("window 2: log(x)/x\n");
+  gnuplot_plot_equation(h2, "log(x)/x", "log(x)/x");
+  sleep(SECONDS);
+  printf("window 3: sin(x)/x\n");
+  gnuplot_plot_equation(h3, "sin(x)/x", "sin(x)/x");
+  sleep(SECONDS);
+
+  /** Close gnuplot handles */
+
+  printf("\n*** closing all gnuplot windows\n");
+  gnuplot_close(h1);
+  gnuplot_close(h2);
+  gnuplot_close(h3);
+  return 0;
+}