Graphics::GnuplotIF - A dynamic Perl interface to gnuplot
This documentation refers to Graphics::GnuplotIF version 1.6
use Graphics::GnuplotIF qw(GnuplotIF);
my @x = ( -2, -1.50, -1, -0.50, 0, 0.50, 1, 1.50, 2 ); # x values my @y1 = ( 4, 2.25, 1, 0.25, 0, 0.25, 1, 2.25, 4 ); # function 1 my @y2 = ( 2, 0.25, -1, -1.75, -2, -1.75, -1, 0.25, 2 ); # function 2
my $plot1 = Graphics::GnuplotIF->new(title => "line", style => "points");
$plot1->gnuplot_plot_y( \@x ); # plot 9 points over 0..8
$plot1->gnuplot_pause( ); # hit RETURN to continue
$plot1->gnuplot_set_title( "parabola" ); # new title $plot1->gnuplot_set_style( "lines" ); # new line style
$plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 ); # plot 1: y1, y2 over x $plot1->gnuplot_plot_many( \@x, \@y1, \@x, \@y2 ); # plot 1: y1 - x, y2 - x
my $plot2 = Graphics::GnuplotIF->new; # new plot object
$plot2->gnuplot_set_xrange( 0, 4 ); # set x range
$plot2->gnuplot_set_yrange( -2, 2 ); # set y range
$plot2->gnuplot_cmd( "set grid" ); # send a gnuplot command
$plot2->gnuplot_plot_equation( # 3 equations in one plot
"y1(x) = sin(x)",
"y2(x) = cos(x)",
"y3(x) = sin(x)/x" );
$plot2->gnuplot_pause( ); # hit RETURN to continue
$plot2->gnuplot_plot_equation( # rewrite plot 2
"y4(x) = 2*exp(-x)*sin(4*x)" );
$plot2->gnuplot_pause( ); # hit RETURN to continue
my $plot3 = GnuplotIF; # new plot object
my @xyz = ( # 2-D-matrix, z-values
[0, 1, 4, 9],
[1, 2, 6, 15],
[4, 6, 12, 27],
[9, 15, 27, 54],
);
$plot3->gnuplot_cmd( "set grid" ); # send a gnuplot command
$plot3->gnuplot_set_plot_titles("surface"); # set legend
$plot3->gnuplot_plot_3d( \@xyz ); # start 3-D-plot
$plot3->gnuplot_pause( ); # hit RETURN to continue
Graphics::GnuplotIF is a simple and easy to use dynamic Perl interface to gnuplot. 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.
This module enables sending display requests asynchronously to gnuplot through simple Perl subroutine calls.
A gnuplot session is an instance of class Graphics::GnuplotIF. The constructor starts gnuplot as a separate process for each session. The plot commands are send through a pipe. The graphical output from gnuplot will be displayed immediately.
Several independent plots can be started from one script. Each plot has its own pipe. All pipes will be closed automatically by the destructor when the script terminates. The gnuplot processes terminate when the corresponding pipes are closed. Their graphical output will now disappear (but see parameter persist).
Graphics::GnuplotIF is similar to gnuplot_i , a C interface to gnuplot
( http://ndevilla.free.fr/gnuplot/ ), and to gnuplot_i++ , a C++ interface
to gnuplot ( http://jijo.cjb.net/code/cc++ ).
An object of this class represents an interface to a running gnuplot process. During the creation of an object such an process will be started for each such object. Communication is done through an unidirectional pipe; the resulting stream is write-only.
Most methods return a reference to the Graphics::GnuplotIF object, allowing method calls to be chained like so:
$plot1 -> gnuplot_plot_xy(\@x, \@y)
-> gnuplot_reset;
The exception to this are gnuplot_get_plotnumber and gnuplot_get_object_id, which are used to obtain specific scalar values.
The constructor creates a new gnuplot session object, referenced by a handle:
$plot1 = Graphics::GnuplotIF->new( );
A few named arguments can be passed as key - value pairs (here shown with their default values):
style => 'lines', # one of the gnuplot line styles (see below)
title => '', # string
xlabel => 'x', # string
ylabel => 'y', # string
xrange => [], # array reference; autoscaling, if empty
xrange => [], # array reference; autoscaling, if empty
plot_titles => [], # array of strings; titles used in the legend
scriptfile => '', # write all plot commands to the specified file
plot_also => 0, # write all plot commands to the specified file,
# in addition show the plots
persist => 0, # let plot windows survive after gnuplot exits
# 0 : close / 1 : survive
objectname => '', # an optional name for the object
silent_pause => 1, # 0 suppress message from gnuplot_pause()
These attributes are stored in each object.
Allowed line styles are
boxes dots filledcurves fsteps histeps impulses lines linespoints points steps
The generated gnuplot commands can be stored to a file instead of beeing executed immediately. This file can be used as input to gnuplot, e.g.
gnuplot < function_set_1.gnuplot
A script file can also be used for checking the commands send to gnuplot.
The objects are automatically deleted by a destructor. The destructor closes
the pipe to the gnuplot process belonging to that object. The gnuplot
process will also terminate and remove the graphic output. The termination can
be controlled by the method gnuplot_pause .
The short form of the constructor above (new):
use Graphics::GnuplotIF qw(GnuplotIF);
$plot1 = GnuplotIF;
This subroutine is exported only on request.
$plot1->gnuplot_plot_y( \@y1, \@y2 );
gnuplot_plot_y takes one or more array references and plots the values over
the x-values 0, 1, 2, 3, ...
$plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 );
gnuplot_plot_xy takes two or more array references. The first array is
assumed to contain the x-values for the following function values.
%y1 = ( 'y_values' => \@y1, 'style_spec' => "lines lw 3" );
%y2 = ( 'y_values' => \@y2,
'style_spec' => "points pointtype 4 pointsize 5" );
$plot1->gnuplot_plot_xy_style( \@x, \%y1, \%y2 );
gnuplot_plot_xy_style takes one array reference and one or more hash
references. The first array is assumed to contain the x-values for the
following function values. The following hashes are assumed to contain pairs of
y-values and individual style specifications for use in the plot command. The
'style_spec' settings are placed between with and title of gnuplot's
plot command.
$plot1->gnuplot_plot_xy( \@x1, \@y1, \@x2, \@y2 );
gnuplot_plot_many takes pairs of array references. Each pair represents a
function and is a reference to the arrays of x- and y-values for that function.
%f1 = ( 'x_values' => \@x1, 'y_values' => \@y1,
'style_spec' => "lines lw 3" );
%f2 = ( 'x_values' => \@x2, 'y_values' => \@y2,
'style_spec' => "points pointtype 4 pointsize 5" );
$plot1->gnuplot_plot_many_style( \%f1, \%f2 );
gnuplot_plot_many_style takes one or more hash references. The hashes are
assumed to contain array referenses to x-values and y-values and individual
style specifications for use in the plot command. The 'style_spec' settings are
placed between with and title of gnuplot's plot command.
$plot2->gnuplot_plot_equation( # 3 equations in one plot
"y1(x) = sin(x)",
"y2(x) = cos(x)",
"y3(x) = sin(x)/x" );
gnuplot_plot_equation takes one or more gnuplot function descriptions as
strings. The plot ranges can be controlled by
gnuplot_set_xrange and
gnuplot_set_yrange .
$plot2->gnuplot_plot_3d( \@array ); # 3-D-plot
gnuplot_plot_3d takes one reference to an 2-D-array of z-values.
$plot1->gnuplot_pause( [time] [,text] );
This is an emulation of the gnuplot pause command. It displays any text
associated with the command and waits a specified amount of time or until the
carriage return is pressed. The message can be suppressed by
silent_pause => 0
given to the constructor (see new ).
time may be any constant or expression. Choosing 0 (default) will
wait until a carriage return is hit, a negative value won't pause at
all, and a positive number will wait the specified number of seconds.
The time value and the text are stored in the object and reused. A sequence like
$plot1->gnuplot_plot_y( \@y1 ); $plot1->gnuplot_pause( 5.5 ); # delay is 5.5 seconds
$plot1->gnuplot_plot_y( \@y2 ); $plot1->gnuplot_pause( );
$plot1->gnuplot_plot_y( \@y3 ); $plot1->gnuplot_pause( );
will display 3 plots with 5.5 seconds delay.
$plot2->gnuplot_cmd( 'set grid',
'set timestamp "%d/%m/%y %H:%M" 0,0 "Helvetica"'
);
gnuplot_cmd can be used to send one or more gnuplot commands, especially
those not wrapped by a Graphics::GnuplotIF method.
$plot1->gnuplot_reset();
Set all options set with the set command to their gnuplot default values.
$plot1->gnuplot_set_style( "steps" ); # new line style
Sets one of the allowed line styles (see new ) in a plot command.
$plot1->gnuplot_set_title("parabola"); # new title
Sets the plot title.
Equivalent to the gnuplot command set title "parabola".
$plot1->gnuplot_set_xlabel("time (days)");
Sets the x axis label.
Equivalent to the gnuplot command set xlabel "time (days)".
$plot1->gnuplot_set_ylabel("bugs fixed");
Sets the y axis label.
Equivalent to the gnuplot command set ylabel "bugs fixed".
$plot1->gnuplot_set_xrange( left, right );
Sets the horizontal range that will be displayed.
Equivalent to the gnuplot command set xrange [left:right].
$plot1->gnuplot_set_yrange( low, high );
Sets the vertical range that will be displayed.
Equivalent to the gnuplot command set yrange [low:high].
$plot1->gnuplot_set_plot_titles( @ytitles );
Sets the list of titles used in the key for each of the y-coordinate data sets
specified in subsequent calls to gnuplot_plot_xy or gnuplot_plot_y commands.
This is not equivalent to a complete gnuplot command; rather it adds a
title clause to each data set specified in a gnuplot plot command.
gnuplot_cmd can be used to write a plot into a file or make a printable file
by setting/resetting the terminal and the output file:
$plot1->gnuplot_hardcopy( 'function1.gnuplot.ps',
'postscript',
'color lw 3' );
$plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 );
$plot1->gnuplot_restore_terminal();
The 1. parameter is a file name, the 2. parameter is a gnuplot terminal type, the 3. parameter is a string with additional terminal parameters (optional). The current terminal settings will be saved.
Restores the saved terminal settings after a call to gnuplot_hardcopy().
Output will go to STDOUT again.
A hardcopy can be made with an appropriate output format and a pipe to a printer:
$plot1->gnuplot_cmd( 'set terminal postscript',
'set output " | lpr " ' );
$plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 );
$plot1->gnuplot_cmd( 'set output',
'set terminal x11' );
Get the (internal) object number (and the object name):
$obj_number = $plot1->gnuplot_get_object_id(); ($obj_number, $obj_name) = $plot1->gnuplot_get_object_id();
The object number is set automatically by the constructor. The object name can be set by the constructor (objectname => 'MyName').
Get the (internal) plot number of the next plot:
$plot_number = $plot1->gnuplot_get_plotnumber()
The plot number is set automatically by the constructor starting with 1. Each call to
gnuplot_plot_y gnuplot_plot_xy gnuplot_plot_xy_style gnuplot_plot_many gnuplot_plot_many_style gnuplot_plot_equation gnuplot_plot_3d
increments this number by 1. This can be used to identify single plots, e.g. with
$plot->gnuplot_cmd( "set timestamp \"plot number ${plot_number} / %c\"" );
GnuplotIF constructor, short form (see GnuplotIF ).
Dialog messages and diagnostic messages start with
Graphics::GnuplotIF (object NR): ... .
NR is the number of the corresponding Graphics::GnuplotIF object and output
stream. NR counts the objects in the order of their generation.
The gnuplot messages going to STDERR will be redirected to the file
.gnuplot.PPP.OOO.stderr.log. PPP is the process number, OOO is the number of
the plot object (see gnuplot_get_object_id).
The environment variable DISPLAY is checked for the display.
gnuplot ( http://sourceforge.net/projects/gnuplot ) must be installed.
The module Carp is used for error handling.
The module IO::Handle is used to handle output pipes. Your operating system
must support pipes, of course.
There are no known incompatibilities.
$plot1->gnuplot_cmd("pause -1"); # send the gnuplot pause command
does not work. Use
$plot1->gnuplot_pause( );
There are no known bugs in this module. Please report problems to author. Patches are welcome.
Dr.-Ing. Fritz Mehner (mehner.fritz@web.de)
Stephen Marshall (smarshall at wsi dot com) contributed gnuplot_set_plot_titles.
Georg Bauhaus (bauhaus at futureapps dot de) contributed gnuplot_plot_xy_style.
Bruce Ravel (bravel at bnl dot gov) contributed gnuplot_plot_many and
gnuplot_plot_many_style and made method calls chainable.
Copyright (C) 2005-2008 by Fritz Mehner
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perldoc perlartistic. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
gnuplot(1).