.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Graphics::GnuplotIF 3pm" .TH Graphics::GnuplotIF 3pm 2024-03-06 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Graphics::GnuplotIF \- A dynamic Perl interface to gnuplot .SH VERSION .IX Header "VERSION" This documentation refers to Graphics::GnuplotIF version 1.6 .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& 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( \e@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( \e@x, \e@y1, \e@y2 ); # plot 1: y1, y2 over x \& $plot1\->gnuplot_plot_many( \e@x, \e@y1, \e@x, \e@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( \e@xyz ); # start 3\-D\-plot \& $plot3\->gnuplot_pause( ); # hit RETURN to continue .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Graphics::GnuplotIF is a simple and easy to use dynamic Perl interface to \&\fBgnuplot\fR. \fBgnuplot\fR 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 \f(CW\*(C`gnuplot.exe\*(C'\fR. .PP This module enables sending display requests asynchronously to \fBgnuplot\fR through simple Perl subroutine calls. .PP A gnuplot session is an instance of class Graphics::GnuplotIF. The constructor starts \fBgnuplot\fR as a separate process for each session. The plot commands are send through a \fIpipe\fR. The graphical output from \fBgnuplot\fR will be displayed immediately. .PP 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 \fBgnuplot\fR processes terminate when the corresponding pipes are closed. Their graphical output will now disappear (but see parameter persist). .PP Graphics::GnuplotIF is similar to \f(CW\*(C` gnuplot_i \*(C'\fR, a C interface to \fBgnuplot\fR ( http://ndevilla.free.fr/gnuplot/ ), and to \f(CW\*(C` gnuplot_i++ \*(C'\fR, a C++ interface to \fBgnuplot\fR ( http://jijo.cjb.net/code/cc++ ). .SH SUBROUTINES/METHODS .IX Header "SUBROUTINES/METHODS" An object of this class represents an interface to a running \fBgnuplot\fR 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. .PP Most methods return a reference to the Graphics::GnuplotIF object, allowing method calls to be chained like so: .PP .Vb 2 \& $plot1 \-> gnuplot_plot_xy(\e@x, \e@y) \& \-> gnuplot_reset; .Ve .PP The exception to this are "gnuplot_get_plotnumber" and "gnuplot_get_object_id", which are used to obtain specific scalar values. .SS new .IX Subsection "new" The constructor creates a new \fBgnuplot\fR session object, referenced by a handle: .PP .Vb 1 \& $plot1 = Graphics::GnuplotIF\->new( ); .Ve .PP A few named arguments can be passed as key \- value pairs (here shown with their default values): .PP .Vb 10 \& program => \*(Aqgnuplot\*(Aq # fully qualified name of the Gnuplot executable \& style => \*(Aqlines\*(Aq, # one of the gnuplot line styles (see below) \& title => \*(Aq\*(Aq, # string \& xlabel => \*(Aqx\*(Aq, # string \& ylabel => \*(Aqy\*(Aq, # string \& xrange => [], # array reference; autoscaling, if empty \& xrange => [], # array reference; autoscaling, if empty \& plot_titles => [], # array of strings; titles used in the legend \& scriptfile => \*(Aq\*(Aq, # 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 => \*(Aq\*(Aq, # 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 .Ve .PP These attributes are stored in each object. .PP Allowed line styles are .PP .Vb 2 \& boxes dots filledcurves fsteps histeps \& impulses lines linespoints points steps .Ve .PP The generated \fBgnuplot\fR commands can be stored to a file instead of being executed immediately. This file can be used as input to \fBgnuplot\fR, e.g. .PP .Vb 1 \& gnuplot < function_set_1.gnuplot .Ve .PP A script file can also be used for checking the commands send to \fBgnuplot\fR. .PP The objects are automatically deleted by a destructor. The destructor closes the pipe to the \fBgnuplot\fR process belonging to that object. The \fBgnuplot\fR process will also terminate and remove the graphic output. The termination can be controlled by the method \f(CW\*(C`gnuplot_pause\*(C'\fR . .PP The program argument is provided to allow Graphics::GnuplotIF to be used with Gnuplot on Windows using \f(CW\*(C`gnuplot.exe\*(C'\fR, a compilation which includes code that emulates a unix pipe. .SS GnuplotIF .IX Subsection "GnuplotIF" The short form of the constructor above (\f(CW\*(C`new\*(C'\fR): .PP .Vb 1 \& use Graphics::GnuplotIF qw(GnuplotIF); \& \& $plot1 = GnuplotIF; .Ve .PP This subroutine is exported only on request. .SS gnuplot_plot_y .IX Subsection "gnuplot_plot_y" .Vb 1 \& $plot1\->gnuplot_plot_y( \e@y1, \e@y2 ); .Ve .PP \&\f(CW\*(C`gnuplot_plot_y\*(C'\fR takes one or more array references and plots the values over the x\-values 0, 1, 2, 3, ... .SS gnuplot_plot_xy .IX Subsection "gnuplot_plot_xy" .Vb 1 \& $plot1\->gnuplot_plot_xy( \e@x, \e@y1, \e@y2 ); .Ve .PP \&\f(CW\*(C`gnuplot_plot_xy\*(C'\fR takes two or more array references. The first array is assumed to contain the x\-values for the following function values. .SS gnuplot_plot_xy_style .IX Subsection "gnuplot_plot_xy_style" .Vb 3 \& %y1 = ( \*(Aqy_values\*(Aq => \e@y1, \*(Aqstyle_spec\*(Aq => "lines lw 3" ); \& %y2 = ( \*(Aqy_values\*(Aq => \e@y2, \& \*(Aqstyle_spec\*(Aq => "points pointtype 4 pointsize 5" ); \& \& $plot1\->gnuplot_plot_xy_style( \e@x, \e%y1, \e%y2 ); .Ve .PP \&\f(CW\*(C`gnuplot_plot_xy_style\*(C'\fR 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 \f(CW\*(C`with\*(C'\fR and \f(CW\*(C`title\*(C'\fR of \fBgnuplot\fR's \&\f(CW\*(C`plot\*(C'\fR command. .SS gnuplot_plot_many .IX Subsection "gnuplot_plot_many" .Vb 1 \& $plot1\->gnuplot_plot_xy( \e@x1, \e@y1, \e@x2, \e@y2 ); .Ve .PP \&\f(CW\*(C`gnuplot_plot_many\*(C'\fR 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. .SS gnuplot_plot_many_style .IX Subsection "gnuplot_plot_many_style" .Vb 4 \& %f1 = ( \*(Aqx_values\*(Aq => \e@x1, \*(Aqy_values\*(Aq => \e@y1, \& \*(Aqstyle_spec\*(Aq => "lines lw 3" ); \& %f2 = ( \*(Aqx_values\*(Aq => \e@x2, \*(Aqy_values\*(Aq => \e@y2, \& \*(Aqstyle_spec\*(Aq => "points pointtype 4 pointsize 5" ); \& \& $plot1\->gnuplot_plot_many_style( \e%f1, \e%f2 ); .Ve .PP \&\f(CW\*(C`gnuplot_plot_many_style\*(C'\fR 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 \f(CW\*(C`with\*(C'\fR and \f(CW\*(C`title\*(C'\fR of \fBgnuplot\fR's \f(CW\*(C`plot\*(C'\fR command. .SS gnuplot_plot_equation .IX Subsection "gnuplot_plot_equation" .Vb 4 \& $plot2\->gnuplot_plot_equation( # 3 equations in one plot \& "y1(x) = sin(x)", \& "y2(x) = cos(x)", \& "y3(x) = sin(x)/x" ); .Ve .PP \&\f(CW\*(C`gnuplot_plot_equation\*(C'\fR takes one or more \fBgnuplot\fR function descriptions as strings. The plot ranges can be controlled by \&\f(CW\*(C`gnuplot_set_xrange\*(C'\fR and \&\f(CW\*(C`gnuplot_set_yrange\*(C'\fR . .SS gnuplot_plot_3d .IX Subsection "gnuplot_plot_3d" .Vb 1 \& $plot2\->gnuplot_plot_3d( \e@array ); # 3\-D\-plot .Ve .PP \&\f(CW\*(C`gnuplot_plot_3d\*(C'\fR takes one reference to an 2\-D\-array of z\-values. .SS gnuplot_pause .IX Subsection "gnuplot_pause" .Vb 1 \& $plot1\->gnuplot_pause( [time] [,text] ); .Ve .PP This is an emulation of the \fBgnuplot\fR \f(CW\*(C`pause\*(C'\fR 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 .PP .Vb 1 \& silent_pause => 0 .Ve .PP given to the constructor (see new ). .PP \&\f(CW\*(C`time\*(C'\fR 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. .PP The time value and the text are stored in the object and reused. A sequence like .PP .Vb 2 \& $plot1\->gnuplot_plot_y( \e@y1 ); \& $plot1\->gnuplot_pause( 5.5 ); # delay is 5.5 seconds \& \& $plot1\->gnuplot_plot_y( \e@y2 ); \& $plot1\->gnuplot_pause( ); \& \& $plot1\->gnuplot_plot_y( \e@y3 ); \& $plot1\->gnuplot_pause( ); .Ve .PP will display 3 plots with 5.5 seconds delay. .SS gnuplot_cmd .IX Subsection "gnuplot_cmd" .Vb 3 \& $plot2\->gnuplot_cmd( \*(Aqset grid\*(Aq, \& \*(Aqset timestamp "%d/%m/%y %H:%M" 0,0 "Helvetica"\*(Aq \& ); .Ve .PP \&\f(CW\*(C`gnuplot_cmd\*(C'\fR can be used to send one or more \fBgnuplot\fR commands, especially those not wrapped by a Graphics::GnuplotIF method. .SS gnuplot_reset .IX Subsection "gnuplot_reset" .Vb 1 \& $plot1\->gnuplot_reset(); .Ve .PP Set all options set with the \f(CW\*(C`set\*(C'\fR command to their \fBgnuplot\fR default values. .SS gnuplot_set_style .IX Subsection "gnuplot_set_style" .Vb 1 \& $plot1\->gnuplot_set_style( "steps" ); # new line style .Ve .PP Sets one of the allowed line styles (see new ) in a plot command. .SS gnuplot_set_title .IX Subsection "gnuplot_set_title" .Vb 1 \& $plot1\->gnuplot_set_title("parabola"); # new title .Ve .PP Sets the plot title. Equivalent to the \fBgnuplot\fR command \f(CW\*(C`set title "parabola"\*(C'\fR. .SS gnuplot_set_xlabel .IX Subsection "gnuplot_set_xlabel" .Vb 1 \& $plot1\->gnuplot_set_xlabel("time (days)"); .Ve .PP Sets the x axis label. Equivalent to the \fBgnuplot\fR command \f(CW\*(C`set xlabel "time (days)"\*(C'\fR. .SS gnuplot_set_ylabel .IX Subsection "gnuplot_set_ylabel" .Vb 1 \& $plot1\->gnuplot_set_ylabel("bugs fixed"); .Ve .PP Sets the y axis label. Equivalent to the \fBgnuplot\fR command \f(CW\*(C`set ylabel "bugs fixed"\*(C'\fR. .SS gnuplot_set_xrange .IX Subsection "gnuplot_set_xrange" .Vb 1 \& $plot1\->gnuplot_set_xrange( left, right ); .Ve .PP Sets the horizontal range that will be displayed. Equivalent to the \fBgnuplot\fR command \f(CW\*(C`set xrange [left:right]\*(C'\fR. .SS gnuplot_set_yrange .IX Subsection "gnuplot_set_yrange" .Vb 1 \& $plot1\->gnuplot_set_yrange( low, high ); .Ve .PP Sets the vertical range that will be displayed. Equivalent to the \fBgnuplot\fR command \f(CW\*(C`set yrange [low:high]\*(C'\fR. .SS gnuplot_set_plot_titles .IX Subsection "gnuplot_set_plot_titles" .Vb 1 \& $plot1\->gnuplot_set_plot_titles( @ytitles ); .Ve .PP 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 \fBgnuplot\fR command; rather it adds a \&\f(CW\*(C`title\*(C'\fR clause to each data set specified in a \fBgnuplot\fR \f(CW\*(C`plot\*(C'\fR command. .SS gnuplot_hardcopy .IX Subsection "gnuplot_hardcopy" \&\f(CW\*(C`gnuplot_cmd\*(C'\fR can be used to write a plot into a file or make a printable file by setting/resetting the terminal and the output file: .PP .Vb 3 \& $plot1\->gnuplot_hardcopy( \*(Aqfunction1.gnuplot.ps\*(Aq, \& \*(Aqpostscript\*(Aq, \& \*(Aqcolor lw 3\*(Aq ); \& \& $plot1\->gnuplot_plot_xy( \e@x, \e@y1, \e@y2 ); \& \& $plot1\->gnuplot_restore_terminal(); .Ve .PP The 1. parameter is a file name, the 2. parameter is a \fBgnuplot\fR terminal type, the 3. parameter is a string with additional terminal parameters (optional). The current terminal settings will be saved. .SS gnuplot_restore_terminal .IX Subsection "gnuplot_restore_terminal" Restores the saved terminal settings after a call to \f(CWgnuplot_hardcopy()\fR. Output will go to \f(CW\*(C`STDOUT\*(C'\fR again. .PP \fIPrint a plot directly\fR .IX Subsection "Print a plot directly" .PP A hardcopy can be made with an appropriate output format and a pipe to a printer: .PP .Vb 2 \& $plot1\->gnuplot_cmd( \*(Aqset terminal postscript\*(Aq, \& \*(Aqset output " | lpr " \*(Aq ); \& \& $plot1\->gnuplot_plot_xy( \e@x, \e@y1, \e@y2 ); \& \& $plot1\->gnuplot_cmd( \*(Aqset output\*(Aq, \& \*(Aqset terminal x11\*(Aq ); .Ve .SS gnuplot_get_object_id .IX Subsection "gnuplot_get_object_id" Get the (internal) object number (and the object name): .PP .Vb 2 \& $obj_number = $plot1\->gnuplot_get_object_id(); \& ($obj_number, $obj_name) = $plot1\->gnuplot_get_object_id(); .Ve .PP The object number is set automatically by the constructor. The object name can be set by the constructor (objectname => 'MyName'). .SS gnuplot_get_plotnumber .IX Subsection "gnuplot_get_plotnumber" Get the (internal) plot number of the \fBnext\fR plot: .PP .Vb 1 \& $plot_number = $plot1\->gnuplot_get_plotnumber() .Ve .PP The plot number is set automatically by the constructor starting with 1. Each call to .PP .Vb 7 \& gnuplot_plot_y \& gnuplot_plot_xy \& gnuplot_plot_xy_style \& gnuplot_plot_many \& gnuplot_plot_many_style \& gnuplot_plot_equation \& gnuplot_plot_3d .Ve .PP increments this number by 1. This can be used to identify single plots, e.g. with .PP .Vb 1 \& $plot\->gnuplot_cmd( "set timestamp \e"plot number ${plot_number} / %c\e"" ); .Ve .SH EXPORTS .IX Header "EXPORTS" \&\fBGnuplotIF\fR constructor, short form (see \f(CW\*(C`GnuplotIF\*(C'\fR ). .SH DIAGNOSTICS .IX Header "DIAGNOSTICS" Dialog messages and diagnostic messages start with \&\f(CW\*(C` Graphics::GnuplotIF (object NR): ... \*(C'\fR . .PP \&\f(CW\*(C`NR\*(C'\fR is the number of the corresponding Graphics::GnuplotIF object and output stream. NR counts the objects in the order of their generation. .PP The gnuplot messages going to STDERR will be redirected to the file \&\f(CW\*(C`.gnuplot.PPP.OOO.stderr.log\*(C'\fR. PPP is the process number, OOO is the number of the plot object (see \f(CW\*(C`gnuplot_get_object_id\*(C'\fR). .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" The environment variable DISPLAY is checked for the display. .SH DEPENDENCIES .IX Header "DEPENDENCIES" .IP \(bu 2 \&\f(CW\*(C`gnuplot\*(C'\fR ( http://sourceforge.net/projects/gnuplot ) must be installed. .Sp Using Graphics::GnuplotIF on Windows requires having the \&\f(CW\*(C`gnuplot.exe\*(C'\fR version installed. This is the version that emulates a pipe. The Graphics::GnuplotIF object must then be instantiated with the \f(CW\*(C`program\*(C'\fR argument, like so: .Sp .Vb 1 \& my $plot = Graphics::GnuplotIF \-> new(program => \*(AqC:\egnuplot\ebinaries\egnuplot.exe\*(Aq); .Ve .Sp A recent compilation of Gnuplot for Windows can be found at SourceForge: . .IP \(bu 2 The module \f(CW\*(C`Carp\*(C'\fR is used for error handling. .IP \(bu 2 The module \f(CW\*(C`IO::Handle\*(C'\fR is used to handle output pipes. Your operating system must support pipes, of course. .SH INCOMPATIBILITIES .IX Header "INCOMPATIBILITIES" There are no known incompatibilities. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" .Vb 1 \& $plot1\->gnuplot_cmd("pause \-1"); # send the gnuplot pause command .Ve .PP does not work. Use .PP .Vb 1 \& $plot1\->gnuplot_pause( ); .Ve .PP There are no known bugs in this module. Please report problems to author. Patches are welcome. .SH AUTHOR .IX Header "AUTHOR" Dr.\-Ing. Fritz Mehner (mehner.fritz@web.de) .SH CREDITS .IX Header "CREDITS" Stephen Marshall (smarshall at wsi dot com) contributed \f(CW\*(C`gnuplot_set_plot_titles\*(C'\fR. .PP Georg Bauhaus (bauhaus at futureapps dot de) contributed \f(CW\*(C`gnuplot_plot_xy_style\*(C'\fR. .PP Bruce Ravel (bravel at bnl dot gov) contributed \f(CW\*(C`gnuplot_plot_many\*(C'\fR and \f(CW\*(C`gnuplot_plot_many_style\*(C'\fR, made method calls chainable, and added Windows support. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (C) 2005\-2011 by Fritz Mehner .PP 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. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\f(CWgnuplot(1)\fR.