NAME
Graphics::GnuplotIF - A dynamic Perl interface to gnuplot
VERSION
This documentation refers to Graphics::GnuplotIF version 1.3
SYNOPSIS
use Graphics::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 ); # rewrite plot1 : y1 and y2 over x
my $plot2 = Graphics::GnuplotIF->new;
$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
DESCRIPTION
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.
Graphics::GnuplotIF starts gnuplot as a separate process. 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 when the script terminates. The gnuplot processes terminate when the corresponding pipes are closed. Their graphical output will now disappear.
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++ ).
SUBROUTINES/METHODS
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.
new
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
These attributes are stored in each object. Allowed line styles are
boxes dots filledcurves fsteps histeps
impulses lines linespoints points steps
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
.
gnuplot_plot_y
$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, ...
gnuplot_plot_xy
$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.
gnuplot_plot_xy_style
%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.
gnuplot_plot_equation
$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
.
gnuplot_pause
$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.
time
may be any constant or expression. Choosing -1 (default) will wait until a carriage return is hit, zero (0) 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_pause( 5 ); # delay is 5 seconds
$plot1->gnuplot_plot_y( \@y1 );
$plot1->gnuplot_pause( );
$plot1->gnuplot_plot_y( \@y2 );
$plot1->gnuplot_pause( );
$plot1->gnuplot_plot_y( \@y3 );
$plot1->gnuplot_pause( -1 );
will display 3 plots with 5 seconds delay and wait for a final carriage return.
gnuplot_cmd
$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.
Write a plot into a file
gnuplot_cmd
can be used to write a plot into a file or make a hardcopy by setting/resetting the terminal and the output file:
$plot1->gnuplot_cmd( 'set terminal png',
'set output "test-plot-1.png" ' );
$plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 );
$plot1->gnuplot_cmd( 'set output',
'set terminal x11' );
Make a hardcopy
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' );
gnuplot_reset
$plot1->gnuplot_reset();
Set all options set with the set
command to their gnuplot default values.
gnuplot_set_style
$plot1->gnuplot_set_style( "steps" ); # new line style
Sets one of the allowed line styles (see new ) in a plot command.
gnuplot_set_title
$plot1->gnuplot_set_title("parabola"); # new title
Sets the plot title. Equivalent to the gnuplot command set title "parabola"
.
gnuplot_set_xlabel
$plot1->gnuplot_set_xlabel("time (days)");
Sets the x axis label. Equivalent to the gnuplot command set xlabel "time (days)"
.
gnuplot_set_ylabel
$plot1->gnuplot_set_ylabel("bugs fixed");
Sets the y axis label. Equivalent to the gnuplot command set ylabel "bugs fixed"
.
gnuplot_set_xrange
$plot1->gnuplot_set_xrange( left, right );
Sets the horizontal range that will be displayed. Equivalent to the gnuplot command set xrange [left:right]
.
gnuplot_set_yrange
$plot1->gnuplot_set_yrange( low, high );
Sets the vertical range that will be displayed. Equivalent to the gnuplot command set yrange [low:high]
.
gnuplot_set_plot_titles
$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.
DIAGNOSTICS
Dialog messages and diagnostic messages start with Graphics::GnuplotIF (NR): ...
.
NR
is the number of the corresponding Graphics::GnuplotIF object and output stream. NR counts the objects in the order of their generation.
CONFIGURATION AND ENVIRONMENT
The environment variable DISPLAY is checked for the display.
DEPENDENCIES
gnuplot ( http://sourceforge.net/projects/gnuplot ) must be installed.
The module IO::Handle is used to handle output pipes. Your operating system must support pipes, of course.
INCOMPATIBILITIES
There are no known incompatibilities.
BUGS AND LIMITATIONS
$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.
AUTHOR
Dr.-Ing. Fritz Mehner (mehner@fh-swf.de)
CREDITS
Stephen Marshall (smarshall@wsi.com) contributed gnuplot_set_plot_titles
.
Georg Bauhaus (bauhaus@futureapps.de) contributed gnuplot_plot_xy_style
.
LICENSE AND COPYRIGHT
Copyright (C) 2005-2007 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.
SEE ALSO
gnuplot(1)
.