Graphics::GnuplotIF - A dynamic Perl interface to gnuplot

       Dr.-Ing. Fritz Mehner (mehner.fritz@web.de)

         $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.

       The environment variable DISPLAY is checked for the display.

       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", made
       method calls chainable, and added Windows support.

       • "gnuplot" ( http://sourceforge.net/projects/gnuplot ) must be installed.

         Using  Graphics::GnuplotIF on Windows requires having the "gnuplot.exe" version installed.  This is the
         version that emulates a pipe.  The Graphics::GnuplotIF  object  must  then  be  instantiated  with  the
         "program" argument, like so:

           my $plot = Graphics::GnuplotIF -> new(program => 'C:\gnuplot\binaries\gnuplot.exe');

         A    recent    compilation    of    Gnuplot    for    Windows    can    be    found   at   SourceForge:
         <http://sourceforge.net/projects/gnuplot/files/gnuplot/>.

       • 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.

       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, including Windows with "gnuplot.exe".

       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++ ).

       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").

GnuplotIF     constructor, short form (see "GnuplotIF" ).

       There are no known incompatibilities.

       Copyright (C) 2005-2011 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.

       Graphics::GnuplotIF - A dynamic Perl interface to gnuplot

gnuplot(1).

perl v5.38.2                                       2024-03-06                           Graphics::GnuplotIF(3pm)

       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.

   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):

         program      => 'gnuplot' # fully qualified name of the Gnuplot executable
         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()
         no_error_log => 0,        # suppress ".gnuplot.${$}.${object_number}.stderr.log" file

       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 being 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 program argument is provided to allow Graphics::GnuplotIF to be used with Gnuplot on Windows using
       "gnuplot.exe", a compilation which includes code that emulates a unix pipe.

   GnuplotIF
       The short form of the constructor above ("new"):

         use Graphics::GnuplotIF qw(GnuplotIF);

         $plot1  = GnuplotIF;

       This subroutine is exported only on request.

   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_many
         $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.

   gnuplot_plot_many_style
         %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.

   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_plot_3d
         $plot2->gnuplot_plot_3d( \@array );    # 3-D-plot

       "gnuplot_plot_3d" takes one reference to an 2-D-array of z-values.

   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. 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.

   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.

   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.

   gnuplot_hardcopy
       "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.

   gnuplot_restore_terminal
       Restores the saved terminal settings after a call to gnuplot_hardcopy().  Output will go to "STDOUT"
       again.

       Printaplotdirectly

       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_get_object_id
       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').

   gnuplot_get_plotnumber
       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\"" );

         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

       This documentation refers to Graphics::GnuplotIF version 1.6