view release on metacpan or  search on metacpan

lib/Graphics/GnuplotIF.pm  view on Meta::CPAN

#__END__
#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
#  Module Documentation
#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

=head1 NAME

Graphics::GnuplotIF - A dynamic Perl interface to gnuplot

=head1 VERSION

This documentation refers to Graphics::GnuplotIF version 1.6

=head1 SYNOPSIS

  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

=head1 DESCRIPTION

Graphics::GnuplotIF is a simple and easy to use dynamic Perl interface to
B<gnuplot>.  B<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 C<gnuplot.exe>.

This module enables sending display requests asynchronously to B<gnuplot>
through simple Perl subroutine calls.

A gnuplot session is an instance of class Graphics::GnuplotIF.  The constructor
starts B<gnuplot> as a separate process for each session. The plot commands are
send through a I<pipe>. The graphical output from B<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 B<gnuplot> processes terminate when the corresponding
pipes are closed.  Their graphical output will now disappear (but see parameter
L<persist|new>).

Graphics::GnuplotIF is similar to C< gnuplot_i >, a C interface to B<gnuplot>
( http://ndevilla.free.fr/gnuplot/ ), and to  C< gnuplot_i++ >, a C++ interface
to B<gnuplot> ( http://jijo.cjb.net/code/cc++ ).

=head1 SUBROUTINES/METHODS

An object of this class represents an interface to a running B<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 L</gnuplot_get_plotnumber> and
L</gnuplot_get_object_id>, which are used to obtain specific scalar
values.

=head2 new

The constructor creates a new B<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 B<gnuplot> commands can be stored to a file instead of beeing
executed immediately.  This file can be used as input to B<gnuplot>, e.g.

  gnuplot < function_set_1.gnuplot

A script file can also be used for checking the commands send to B<gnuplot>.

The objects are automatically deleted by a destructor.  The destructor closes
the pipe to the B<gnuplot> process belonging to that object.  The B<gnuplot>
process will also terminate and remove the graphic output.  The termination can
be controlled by the method L<C<gnuplot_pause> | gnuplot_pause> .

The program argument is provided to allow Graphics::GnuplotIF to be
used with Gnuplot on Windows using C<gnuplot.exe>, a compilation
which includes code that emulates a unix pipe.

=head2 GnuplotIF

The short form of the constructor above (L<C<new>|new>):

  use Graphics::GnuplotIF qw(GnuplotIF);

  $plot1  = GnuplotIF;

This subroutine is exported only on request.

=head2  gnuplot_plot_y

  $plot1->gnuplot_plot_y( \@y1, \@y2 );

C<gnuplot_plot_y> takes one or more array references and plots the values over
the x-values 0, 1, 2, 3, ...

=head2 gnuplot_plot_xy

  $plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 );

C<gnuplot_plot_xy> takes two or more array references.  The first array is
assumed to contain the x-values for the following function values.

=head2 gnuplot_plot_xy_style

  %y1 = ( 'y_values' => \@y1, 'style_spec' => "lines lw 3" );
  %y2 = ( 'y_values' => \@y2,