Graphi...uplotIF(3pm)

🌸 Graphi...uplotIF(3pm) 🌸

User Contributed Perl Documentation, bestie. This is the manual for Graphics::GnuplotIF, and it’s giving dynamic Perl interface to gnuplot energy. Let’s go. 💖

💖 NAME 💖

Graphics::GnuplotIF — A dynamic Perl interface to gnuplot

✨ VERSION ✨

This documentation refers to Graphics::GnuplotIF version 1.6. No cap. 🎀

🦋 SYNOPSIS 🦋

okay so here’s the whole Pearl-core setup, exactly as the universe intended:

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

👑 DESCRIPTION 👑

Graphics::GnuplotIF is a simple and easy to use dynamic Perl interface to gnuplot. And gnuplot? It’s a freely available, command-driven graphical display tool for Unix, bestie. It compiles and works quite well on a number of Unix flavours, plus other operating systems too, including Windows with gnuplot.exe. 💅

This module lets you send display requests asynchronously to gnuplot through simple Perl subroutine calls. It’s giving “write Perl, get plot,” fr fr. ✨

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 if you need that. 😭💀

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++ ). So yeah, it’s lowkey iconic in the gnuplot-interface friend group. 👑

💅 SUBROUTINES/METHODS 💅

Okay bestie, so a Graphics::GnuplotIF object? It literally is a little live interface to a running gnuplot process. Like, the moment you make one, a gnuplot process gets spawned for it, one per object, no sharing. 💖

And the communication? It's a unidirectional pipe, which means the stream you get is write-only. You talk, gnuplot listens, that's the whole dynamic. 💅

Now here's the cute part: most methods return a reference to the Graphics::GnuplotIF object itself, so you can chain calls like this:

$plot1 -> gnuplot_plot_xy(\@x, \@y)
   -> gnuplot_reset;

Obsessed. But the two exceptions — the ones that give you actual scalar values back — are gnuplot_get_plotnumber and gnuplot_get_object_id. Those two are the ones that break the chain, periodt. ✨

new

The constructor spins up a brand new gnuplot session object and hands it back to you as a handle:

$plot1  = Graphics::GnuplotIF->new( );

You can also pass a few named arguments as key-value pairs. Here they all are, 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

All of those get stashed inside each object. 🎀

The line styles you're allowed to use are:

boxes     dots   filledcurves  fsteps  histeps
impulses  lines  linespoints   points  steps

And here's a fun one: instead of running the generated gnuplot commands right away, you can write them to a file. That file can then be fed straight into gnuplot, like:

gnuplot < function_set_1.gnuplot

A script file is also lowkey perfect for checking exactly what commands got sent to gnuplot. 🔍

The objects get cleaned up automatically by a destructor. What that destructor does is close the pipe to the gnuplot process that belongs to that object. Once that happens, the gnuplot process will also terminate and remove the graphic output — and you can control that termination with the gnuplot_pause method. 🦋

Oh and the program argument exists specifically so Graphics::GnuplotIF can play nice with Gnuplot on Windows using gnuplot.exe, which is a compilation that includes code emulating a unix pipe. iykyk. 💻

GnuplotIF

The short form of the constructor from above (new), for when you're feeling lazy in the best way:

use Graphics::GnuplotIF qw(GnuplotIF);

$plot1  = GnuplotIF;

Heads up though: this subroutine is exported only on request. Ask and you shall receive, don't ask and it stays out of your namespace. 🙈

gnuplot_plot_y

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

gnuplot_plot_y takes one or more array references and plots those values over the x-values 0, 1, 2, 3, ... — like, it just assumes the x's for you. So convenient. ✨

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 hold the x-values for all the function values that follow it. 🎀

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 plus one or more hash references. The first array holds the x-values for the function values that follow. Each following hash holds a pair of y-values and an individual style specification for the plot command. And the 'style_spec' settings get placed right between with and title in gnuplot's plot command. Slay. 💅

gnuplot_plot_many

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

gnuplot_plot_many takes pairs of array references. Each pair is one function — a reference to the x-values array and the y-values array 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. Each hash holds array references to the x-values and y-values, plus its own individual style specification for the plot command. Just like its xy cousin, the 'style_spec' settings land between with and title in 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. And if you want to control the plot ranges? That's gnuplot_set_xrange and gnuplot_set_yrange's whole job. 🧚

gnuplot_plot_3d

$plot2->gnuplot_plot_3d( \@array );    # 3-D-plot

gnuplot_plot_3d takes one reference to a 2-D-array of z-values. Boom, 3-D. 🔥

gnuplot_pause

$plot1->gnuplot_pause( [time] [,text] );

This one is an emulation of gnuplot's pause command. It shows whatever text is associated with the command and then waits either a set amount of time or until you hit carriage return. And the message can be suppressed with

silent_pause => 0

given to the constructor (peep new for that). 🎀

Now, time can be any constant or expression. The deets:

• Choosing 0 (the default) waits until a carriage return is hit.
• A negative value won't pause at all.
• A positive number waits that many seconds.

The time value and the text both get stored in the object and reused. So a sequence like this:

$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 show you 3 plots with a 5.5 second delay. Iconic behaviour honestly. 💜

gnuplot_cmd

$plot2->gnuplot_cmd( 'set grid',
                     'set timestamp "%d/%m/%y %H:%M" 0,0 "Helvetica"'
                     );

gnuplot_cmd is your little wildcard — use it to send one or more gnuplot commands, especially the ones that no Graphics::GnuplotIF method wraps up for you. Go off. 🌈

gnuplot_reset

$plot1->gnuplot_reset();

Sets every option that was set with the set command back to its gnuplot default value. Clean slate energy. 🫧

gnuplot_set_style

$plot1->gnuplot_set_style( "steps" );   # new line style

Sets one of the allowed line styles (go look at new for the full list) 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 you specify in later calls to gnuplot_plot_xy or gnuplot_plot_y commands. Important: this is not equivalent to a complete gnuplot command — instead it adds a title clause to every data set in a gnuplot plot command. Subtle difference, big deal. ⭐

gnuplot_hardcopy

gnuplot_cmd can be used to write a plot into a file, or to 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();

Here's the parameter breakdown, bestie:

• Parameter 1: a file name.
• Parameter 2: a gnuplot terminal type.
• Parameter 3: a string with additional terminal parameters (optional).

And the current terminal settings? Those get saved. 💾

gnuplot_restore_terminal

Restores the terminal settings that got saved after a call to gnuplot_hardcopy(). Output goes back to STDOUT again. Phew. 🫶

Print a plot directly

You can make a hardcopy with an appropriate output format and a pipe to a printer, like so:

$plot1->gnuplot_cmd( 'set terminal postscript',
                     'set output   " | lpr " ' );

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

$plot1->gnuplot_cmd( 'set output',
                     'set terminal x11' );

Printing from inside gnuplot, we love to see it. 🖨️💖

gnuplot_get_object_id

Get the (internal) object number — and the object name too, if you want:

 $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 too, via 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 at 1. And every single 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

bumps that number up by 1. Which is genuinely so useful for identifying single plots, e.g. with

$plot->gnuplot_cmd( "set timestamp \"plot number ${plot_number} / %c\"" );

Numbered plots, main character energy. 👑

---

🌈 EXPORTS 🌈

• GnuplotIF — the constructor, short form (go see "GnuplotIF" above). ✨

💀 DIAGNOSTICS 💀

Dialog messages and diagnostic messages both start with this lil prefix, quote style:

" Graphics::GnuplotIF (object NR): ... "

Here NR is the number of the corresponding Graphics::GnuplotIF object and output stream. And how does NR get counted? By the order the objects were generated. First born gets 1, etc. 🍼

Also, the gnuplot messages headed to STDERR get redirected to the file .gnuplot.PPP.OOO.stderr.log. Where PPP is the process number, and OOO is the number of the plot object (see "gnuplot_get_object_id"). So if you're wondering where your stderr went — it's in there, bestie. 🔍

🌸 CONFIGURATION AND ENVIRONMENT 🌸

The environment variable DISPLAY is checked for the display. 🖥️✨

💖 DEPENDENCIES 💖

Okay bestie, before you can even think about plotting, you gotta have your ducks in a row. Here's the vibe check:

• gnuplot (<http://sourceforge.net/projects/gnuplot>) — yeah it literally must be installed, no cap. The module is just the cute messenger; gnuplot does the actual drawing. 👑
• Using Graphics::GnuplotIF on Windows means you need the gnuplot.exe version installed. That's the one that emulates a pipe, okay? Not the other one. So your object has to be instantiated with the program argument, like this, exactly:

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

And if you need a recent compilation of Gnuplot for Windows, it's hanging out at SourceForge: <http://sourceforge.net/projects/gnuplot/files/gnuplot/>. Go get her. 🦋

• The module Carp is what handles the error handling. It's giving responsible adult energy so you don't have to be.
• The module IO::Handle is what deals with the output pipes. And obviously, your operating system has to support pipes — which, like, basically all of them do, but we said it so here it is. 🌸

---

🌈 INCOMPATIBILITIES 🌈

There are literally no known incompatibilities. She plays nice with everyone. Slay. ✨

---

😭 BUGS AND LIMITATIONS 😭

Okay so bestie, here's the one thing that will NOT work:

$plot1->gnuplot_cmd("pause -1");     # send the gnuplot pause command

Nope. Not it. Instead use:

$plot1->gnuplot_pause( );

That's the move. Periodt. 💅

There are no known bugs in this module. Please report problems to the author (yes, the actual author, not me). And patches are welcome — come through, contribute, be the main character. 🫶

---

👑 AUTHOR 👑

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

---

🎀 CREDITS 🎀

Look at all these legends who helped build the thing:

• Stephen Marshall (smarshall at wsi dot com) contributed gnuplot_set_plot_titles. Iconic.
• Georg Bauhaus (bauhaus at futureapps dot de) contributed gnuplot_plot_xy_style. Chef's kiss.
• Bruce Ravel (bravel at bnl dot gov) contributed gnuplot_plot_many and gnuplot_plot_many_style, made method calls chainable (!!), and added Windows support. Absolutely ate. 🔥

---

💜 LICENSE AND COPYRIGHT 💜

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. So like, it's free, but it's not promising you anything, bestie. 🙈

---

🌟 SEE ALSO 🌟

gnuplot(1).

---

And that's a wrap on the whole page, babe! 💖 This was Graphi...uplotIF(3pm), from perl v5.38.2, dated 2024-03-06. Now go plot something gorgeous. 🦋✨