C interface to gnuplot. More...

#include "gnuplot_i.h"

Macros
#define	_GNUPLOT_PIPES_C_
#define	GP_CMD_SIZE 2048
#define	GP_TITLE_SIZE 80
#define	GP_EQ_SIZE 512
#define	PATH_MAXNAMESZ 4096
#define	P_tmpdir "."
#define	GNUPLOT_TEMPFILE "%s/gnuplot-i-XXXXXX"
#define	GNUPLOT_EXEC "gnuplot"

Functions
char *	gnuplot_get_program_path (char *pname)
	Find out where a command lives in your PATH.
gnuplot_ctrl *	gnuplot_init (void)
	Opens up a gnuplot session, ready to receive commands.
void	gnuplot_close (gnuplot_ctrl *handle)
	Closes a gnuplot session previously opened by gnuplot_init()
void	gnuplot_cmd (gnuplot_ctrl handle, char cmd,...)
	Sends a command to an active gnuplot session.
void	gnuplot_prompt (gnuplot_ctrl *handle)
	Read commands from standard in and send them to gnuplot handle.
void	gnuplot_setstyle (gnuplot_ctrl h, char plot_style)
	Change the plotting style of a gnuplot session.
void	gnuplot_setaxes (gnuplot_ctrl h, char plot_axes)
	Change the plotting axes of a gnuplot session (2d only).
void	gnuplot_setterm (gnuplot_ctrl h, char terminal)
	Change the terminal of a gnuplot session.
void	gnuplot_set_xlabel (gnuplot_ctrl h, char label)
	Sets the x label of a gnuplot session.
void	gnuplot_set_ylabel (gnuplot_ctrl h, char label)
	Sets the y label of a gnuplot session.
void	gnuplot_set_zlabel (gnuplot_ctrl h, char label)
	Sets the z label of a gnuplot session.
void	gnuplot_resetplot (gnuplot_ctrl *h)
	Resets a gnuplot session (next plot will erase previous ones).
void	gnuplot_plot_x (gnuplot_ctrl handle, double d, int n, char *title)
	Plots a 2d graph from a list of doubles.
void	gnuplot_plot_xy (gnuplot_ctrl handle, double x, double y, int n, char title)
	Plot a 2d graph from a list of points.
int	gnuplot_splot (gnuplot_ctrl handle, double x, double y, double z, int n, char *title)
	Plot a 3d graph from a list of points.
int	gnuplot_splot_grid (gnuplot_ctrl handle, double points, int rows, int cols, char *title)
	Plot a 3d graph from a grid of points.
int	gnuplot_contour_plot (gnuplot_ctrl handle, double x, double y, double z, int nx, int ny, char *title)
	Plot contours from a list of points.
int	gnuplot_splot_obj (gnuplot_ctrl handle, void obj, void(getPoint)(void , gnuplot_point , int, int), int n, char title)
	Plot a 3d graph using callback functions to return the points.
int	gnuplot_plot_obj_xy (gnuplot_ctrl handle, void obj, void(getPoint)(void , gnuplot_point , int, int), int n, char title)
void	gnuplot_plot_once (char title, char style, char label_x, char label_y, double x, double y, int n)
	Open a new session, plot a signal, close the session.
void	gnuplot_plot_slope (gnuplot_ctrl handle, double a, double b, char title)
	Plot a slope on a gnuplot session.
void	gnuplot_plot_equation (gnuplot_ctrl h, char equation, char *title)
	Plot a curve of given equation y=f(x).
void	gnuplot_hardcopy (gnuplot_ctrl h, char filename)
	Save a graph as a postscript file on the hard disk.
void	gnuplot_hardcopy_colour (gnuplot_ctrl h, char filename)
	Save a graph in colour as a postscript file on the hard disk.

Detailed Description

C interface to gnuplot.

Author: N. Devillard (parts R. Bradley, R.Higgins)

Date: Sep 1998, Oct 2004, Sept 2005, Nov 2005, Apr 2006, Dec 2009

Version

Revision:: 2.10.4

gnuplot is a freely available, command-driven graphical display tool for Unix. It compiles and works quite well on a number of Unix flavours as well as other operating systems. The following module enables sending display requests to gnuplot through simple C calls.

3D and colour printing extensions added October 2004 by Robert Bradley (rober.nosp@m.t.br.nosp@m.adley.nosp@m.@mer.nosp@m.ton.o.nosp@m.x.ac.nosp@m..uk), based on existing code:

gnuplot_splot (plot 3D graph), gnuplot_set_zlabel (set the z axis label for 3D plots), gnuplot_hardcopy_colour (for printing in colour)

OS X and limited Windows support added 11-13th September 2005:

On Windows, pgnuplot and wgnuplot.exe must be in the current directory. On OS X, if DISPLAY environment variable is not set, or USE_AQUA=1, aqua is used instead of x11. gnuplot_setterm also added to allow the terminal type to be set.

gnuplot_plot_obj_xy added 15th September 2005 - plotting data from arbitrary structures using callback functions gnuplot_contour_plot added 23rd November 2005 (plots contours, use gnuplot_setstyle to set the contour style)

gnuplot_splot_grid added 2nd April 2006 - plots 2D grids of data [x,y]

gnuplot_setaxes added December 2009 (R. Higgins)

Definition in file gnuplot_i.c.

Macro Definition Documentation

#define _GNUPLOT_PIPES_C_

Definition at line 2 of file gnuplot_i.c.

#define GNUPLOT_EXEC "gnuplot"

Definition at line 76 of file gnuplot_i.c.

#define GNUPLOT_TEMPFILE "%s/gnuplot-i-XXXXXX"

Definition at line 74 of file gnuplot_i.c.

#define GP_CMD_SIZE 2048

Maximal size of a gnuplot command

Definition at line 58 of file gnuplot_i.c.

#define GP_EQ_SIZE 512

Maximal size for an equation

Definition at line 62 of file gnuplot_i.c.

#define GP_TITLE_SIZE 80

Maximal size of a plot title

Definition at line 60 of file gnuplot_i.c.

#define P_tmpdir "."

Define P_tmpdir if not defined (this is normally a POSIX symbol)

Definition at line 71 of file gnuplot_i.c.

#define PATH_MAXNAMESZ 4096

Maximal size of a name in the PATH

Definition at line 64 of file gnuplot_i.c.

Function Documentation

void gnuplot_close ( gnuplot_ctrl * handle )

Closes a gnuplot session previously opened by gnuplot_init()

Parameters

handle Gnuplot session control handle.

Returns: void

Kills the child PID and deletes all opened temporary files. It is mandatory to call this function to close the handle, otherwise temporary files are not cleaned and child process might survive.

Definition at line 261 of file gnuplot_i.c.

void gnuplot_cmd	(	gnuplot_ctrl *	handle,
		char *	cmd,
			...
	)

Sends a command to an active gnuplot session.

Parameters

handle	Gnuplot session control handle
cmd	Command to send, same as a printf statement.

This sends a string to an active gnuplot session, to be executed. There is strictly no way to know if the command has been successfully executed or not. The command syntax is the same as printf.

Examples:

gnuplot_cmd(g, "plot %d*x", 23.0);

gnuplot_cmd(g, "plot %g * cos(%g * x)", 32.0, -3.0);

Since the communication to the gnuplot process is run through a standard Unix pipe, it is only unidirectional. This means that it is not possible for this interface to query an error status back from gnuplot.

Definition at line 313 of file gnuplot_i.c.

int gnuplot_contour_plot	(	gnuplot_ctrl *	handle,
		double *	x,
		double *	y,
		double *	z,
		int	nx,
		int	ny,
		char *	title
	)

Plot contours from a list of points.

Parameters

handle	Gnuplot session control handle.
x	Pointer to a list of x coordinates. (length=nx*ny)
y	Pointer to a list of y coordinates. (length=nx*ny)
z	Pointer to a list of z coordinates. (length=nx*ny)
nx	Number of doubles in x-direction
ny	Number of doubles in y-direction
title	Title of the plot.

Returns: void

gnuplot_contour_plot(handle,x,y,z,n,title); Based on gnuplot_splot, modifications by Robert Bradley 23/11/2005

Plots a contour plot from a list of points, passed in the form of three arrays x, y and z.

gnuplot_ctrl    *h ;
double x[50] ; y[50] ; z[50];
int i ;
h = gnuplot_init() ;
int count=100;
double x[count*count],y[count*count],z[count*count];
int i,j;
for (i=0;i<count;i++) {
    for (j=0;j<count;j++) {
        x[count*i+j]=i;
        y[count*i+j]=j;
        z[count*i+j]=1000*sqrt(square(i-count/2)+square(j-count/2));
    }
}
gnuplot_setstyle(h,"lines");
gnuplot_contour_plot(h,x,y,z,count,count,"Points");
sleep(2) ;
gnuplot_close(h) ;

Definition at line 989 of file gnuplot_i.c.

char* gnuplot_get_program_path ( char * pname )

Find out where a command lives in your PATH.

Parameters

pname Name of the program to look for.

Returns: pointer to statically allocated character string.

This is the C equivalent to the 'which' command in Unix. It parses out your PATH environment variable to find out where a command lives. The returned character string is statically allocated within this function, i.e. there is no need to free it. Beware that the contents of this string will change from one call to the next, though (as all static variables in a function).

The input character string must be the name of a command without prefixing path of any kind, i.e. only the command name. The returned string is the path in which a command matching the same name was found.

Examples (assuming there is a prog named 'hello' in the cwd):

gnuplot_get_program_path("hello") returns "."
gnuplot_get_program_path("ls") returns "/bin"
gnuplot_get_program_path("csh") returns "/usr/bin"
gnuplot_get_program_path("/bin/ls") returns NULL

Definition at line 137 of file gnuplot_i.c.

void gnuplot_hardcopy	(	gnuplot_ctrl *	h,
		char *	filename
	)

Save a graph as a postscript file on the hard disk.

Parameters

h	Gnuplot session control handle.
filename	Filename to save as

Returns: void

A wrapper for the gnuplot_cmd function that sets the terminal the terminal to postscript, replots the graph and then resets the terminal to x11.

Example:

gnuplot_ctrl    *h ;
char            eq[80] ;
h = gnuplot_init() ;
strcpy(eq, "sin(x) * cos(2*x)") ;
gnuplot_plot_equation(h, eq, "sine wave", normal) ;
gnuplot_hardcopy(h, "sinewave.ps");
gnuplot_close(h) ;

Definition at line 1475 of file gnuplot_i.c.

void gnuplot_hardcopy_colour	(	gnuplot_ctrl *	h,
		char *	filename
	)

Save a graph in colour as a postscript file on the hard disk.

Parameters

h	Gnuplot session control handle.
filename	Filename to save as

Returns: void

Added by Robert Bradley on 12th october 2004

This function is identical in syntax (and implementation) to gnuplot_hardcopy, but the resulting PostScript file retains colour information.

Definition at line 1503 of file gnuplot_i.c.

gnuplot_ctrl* gnuplot_init ( void )

Opens up a gnuplot session, ready to receive commands.

Returns: Newly allocated gnuplot control structure.

This opens up a new gnuplot session, ready for input. The struct controlling a gnuplot session should remain opaque and only be accessed through the provided functions.

The session must be closed using gnuplot_close().

Definition at line 196 of file gnuplot_i.c.

void gnuplot_plot_equation	(	gnuplot_ctrl *	h,
		char *	equation,
		char *	title
	)

Plot a curve of given equation y=f(x).

Parameters

h	Gnuplot session control handle.
equation	Equation to plot.
title	Title of the plot.

Returns: void

Plots out a curve of given equation. The general form of the equation is y=f(x), you only provide the f(x) side of the equation.

Example:

gnuplot_ctrl    *h ;
char            eq[80] ;
h = gnuplot_init() ;
strcpy(eq, "sin(x) * cos(2*x)") ;
gnuplot_plot_equation(h, eq, "sine wave", normal) ;
gnuplot_close(h) ;

Definition at line 1422 of file gnuplot_i.c.

int gnuplot_plot_obj_xy	(	gnuplot_ctrl *	handle,
		void *	obj,
		void()(void , gnuplot_point *, int, int)	getPoint,
		int	n,
		char *	title
	)

Definition at line 1201 of file gnuplot_i.c.

void gnuplot_plot_once	(	char *	title,
		char *	style,
		char *	label_x,
		char *	label_y,
		double *	x,
		double *	y,
		int	n
	)

Open a new session, plot a signal, close the session.

Parameters

title	Plot title
style	Plot style
label_x	Label for X
label_y	Label for Y
x	Array of X coordinates
y	Array of Y coordinates (can be NULL)
n	Number of values in x and y.

Returns

This function opens a new gnuplot session, plots the provided signal as an X or XY signal depending on a provided y, waits for a carriage return on stdin and closes the session.

It is Ok to provide an empty title, empty style, or empty labels for X and Y. Defaults are provided in this case.

Definition at line 1297 of file gnuplot_i.c.

void gnuplot_plot_slope	(	gnuplot_ctrl *	handle,
		double	a,
		double	b,
		char *	title
	)

Plot a slope on a gnuplot session.

Parameters

handle	Gnuplot session control handle.
a	Slope.
b	Intercept.
title	Title of the plot.

Returns: void

Plot a slope on a gnuplot session. The provided slope has an equation of the form y=ax+b

Example:

gnuplot_ctrl    *   h ;
double              a, b ;
h = gnuplot_init() ;
gnuplot_plot_slope(h, 1.0, 0.0, "unity slope") ;
sleep(2) ;
gnuplot_close(h) ;

Definition at line 1368 of file gnuplot_i.c.

void gnuplot_plot_x	(	gnuplot_ctrl *	handle,
		double *	d,
		int	n,
		char *	title
	)

Plots a 2d graph from a list of doubles.

Parameters

handle	Gnuplot session control handle.
d	Array of doubles.
n	Number of values in the passed array.
title	Title of the plot.

Returns: void

Plots out a 2d graph from a list of doubles. The x-coordinate is the index of the double in the list, the y coordinate is the double in the list.

Example:

gnuplot_ctrl    *h ;
double          d[50] ;
int             i ;
h = gnuplot_init() ;
for (i=0 ; i<50 ; i++) {
    d[i] = (double)(i*i) ;
}
gnuplot_plot_x(h, d, 50, "parabola") ;
sleep(2) ;
gnuplot_close(h) ;

Definition at line 577 of file gnuplot_i.c.

void gnuplot_plot_xy	(	gnuplot_ctrl *	handle,
		double *	x,
		double *	y,
		int	n,
		char *	title
	)

Plot a 2d graph from a list of points.

Parameters

handle	Gnuplot session control handle.
x	Pointer to a list of x coordinates.
y	Pointer to a list of y coordinates.
n	Number of doubles in x (assumed the same as in y).
title	Title of the plot.

Returns: void

Plots out a 2d graph from a list of points. Provide points through a list of x and a list of y coordinates. Both provided arrays are assumed to contain the same number of values.

gnuplot_ctrl    *h ;
double          x[50] ;
double          y[50] ;
int             i ;
h = gnuplot_init() ;
for (i=0 ; i<50 ; i++) {
    x[i] = (double)(i)/10.0 ;
    y[i] = x[i] * x[i] ;
}
gnuplot_plot_xy(h, x, y, 50, "parabola") ;
sleep(2) ;
gnuplot_close(h) ;

Definition at line 684 of file gnuplot_i.c.

void gnuplot_prompt ( gnuplot_ctrl * handle )

Read commands from standard in and send them to gnuplot handle.

Parameters

handle Gnuplot session control handle

This reads commands from a simple interactive prompt and sends them to be executed via the gnuplot handle. There is no indicatio nof whether a command is executed successfully or not and no checking of input command syntax.

Ctrl+D ends the interactive session.

Definition at line 342 of file gnuplot_i.c.

void gnuplot_resetplot ( gnuplot_ctrl * h )

Resets a gnuplot session (next plot will erase previous ones).

Parameters

h	Gnuplot session control handle.

Returns: void

Resets a gnuplot session, i.e. the next plot will erase all previous ones.

Definition at line 531 of file gnuplot_i.c.

void gnuplot_set_xlabel	(	gnuplot_ctrl *	h,
		char *	label
	)

Sets the x label of a gnuplot session.

Parameters

h	Gnuplot session control handle.
label	Character string to use for X label.

Returns: void

Sets the x label for a gnuplot session.

Definition at line 470 of file gnuplot_i.c.

void gnuplot_set_ylabel	(	gnuplot_ctrl *	h,
		char *	label
	)

Sets the y label of a gnuplot session.

Parameters

h	Gnuplot session control handle.
label	Character string to use for Y label.

Returns: void

Sets the y label for a gnuplot session.

Definition at line 491 of file gnuplot_i.c.

void gnuplot_set_zlabel	(	gnuplot_ctrl *	h,
		char *	label
	)

Sets the z label of a gnuplot session.

Parameters

h	Gnuplot session control handle.
label	Character string to use for Z label.

Returns: void

Sets the z label for a gnuplot session. (Added by Robert Bradley 12 October 2004)

Definition at line 511 of file gnuplot_i.c.

void gnuplot_setaxes	(	gnuplot_ctrl *	h,
		char *	plot_axes
	)

Change the plotting axes of a gnuplot session (2d only).

Change the plotting axes of a gnuplot session.

Parameters

h	Gnuplot session control handle
plot_axes	Plotting-axes to use (character string)

Returns: void

The provided plotting axes is a character string. It must be one of the following:

x1y1
x1y2
x2y1
x2y2

Definition at line 422 of file gnuplot_i.c.

void gnuplot_setstyle	(	gnuplot_ctrl *	h,
		char *	plot_style
	)

Change the plotting style of a gnuplot session.

Parameters

h	Gnuplot session control handle
plot_style	Plotting-style to use (character string)

Returns: void

The provided plotting style is a character string. It must be one of the following:

lines
points
linespoints
impulses
dots
steps
errorbars
boxes
boxeserrorbars

Definition at line 385 of file gnuplot_i.c.

void gnuplot_setterm	(	gnuplot_ctrl *	h,
		char *	terminal
	)

Change the terminal of a gnuplot session.

Parameters

h	Gnuplot session control handle
terminal	Terminal name (character string)

Returns: void

No attempt is made to check the validity of the terminal name. This function simply makes a note of it and calls gnuplot_cmd to change the name

Definition at line 449 of file gnuplot_i.c.

int gnuplot_splot	(	gnuplot_ctrl *	handle,
		double *	x,
		double *	y,
		double *	z,
		int	n,
		char *	title
	)

Plot a 3d graph from a list of points.

Parameters

handle	Gnuplot session control handle.
x	Pointer to a list of x coordinates.
y	Pointer to a list of y coordinates.
z	Pointer to a list of z coordinates.
n	Number of doubles in x (y and z must be the the same).
title	Title of the plot.

Returns: void

gnuplot_splot(handle,x,y,z,n,title); Based on gnuplot_plot_xy, modifications by Robert Bradley 12/10/2004

Plots a 3d graph from a list of points, passed in the form of three arrays x, y and z. All arrays are assumed to contain the same number of values.

gnuplot_ctrl    *h ;
double x[50] ; y[50] ; z[50];
int i ;
h = gnuplot_init() ;
for (i=0 ; i<50 ; i++) {
    x[i] = (double)(i)/10.0 ;
    y[i] = x[i] * x[i] ;
    z[i] = x[i] * x[i]/2.0;
}
gnuplot_splot(h, x, y, z, 50, "parabola") ;
sleep(2) ;
gnuplot_close(h) ;

Definition at line 792 of file gnuplot_i.c.

int gnuplot_splot_grid	(	gnuplot_ctrl *	handle,
		double *	points,
		int	rows,
		int	cols,
		char *	title
	)

Plot a 3d graph from a grid of points.

Parameters

handle	Gnuplot session control handle.
points	Pointer to a grid of points (rows,cols).
rows	Number of rows (y points).
cols	Number of columns (x points).
title	Title of the plot.

Returns: void

gnuplot_splot_grid(handle,(double*) points,rows,cols,title); Based on gnuplot_splot, modifications by Robert Bradley 2/4/2006

Plots a 3d graph from a grid of points, passed in the form of a 2D array [x,y].

Definition at line 871 of file gnuplot_i.c.

int gnuplot_splot_obj	(	gnuplot_ctrl *	handle,
		void *	obj,
		void()(void , gnuplot_point *, int, int)	getPoint,
		int	n,
		char *	title
	)

Plot a 3d graph using callback functions to return the points.

Parameters

handle	Gnuplot session control handle.
obj	Pointer to an arbitrary object.
getPoint	Pointer to a callback function.
n	Number of doubles in x (y and z must be the the same).
title	Title of the plot.

Returns: void

Calback:

void getPoint(void *object,gnuplot_point *point,int index,int pointCount);

Parameters

obj	Pointer to an arbitrary object
point	Pointer to the returned point struct (double x,y,z)
i	Index of the current point (0 to n-1)
n	Number of points

Returns: void

Definition at line 1091 of file gnuplot_i.c.

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation