diff --git a/Changes b/Changes index 93dc7ea..eba3ab1 100644 --- a/Changes +++ b/Changes @@ -1,3 +1,12 @@ +feedgnuplot (1.24) unstable; urgency=low + + * Fixed regression in --monotonic. This works again now + * moved POD back into the main source file. This fixes the broken usage + messages + * added --version + + -- Dima Kogan Fri, 08 Feb 2013 01:53:47 -0800 + feedgnuplot (1.23) * --extracmds no longer accepts comma-separated lists diff --git a/INSTALL b/INSTALL index c86f4f5..10f8a92 100644 --- a/INSTALL +++ b/INSTALL @@ -1,5 +1,10 @@ If running on a Debian-based OS (this includes Ubuntu), it is highly recommended -to install this program as a package by doing +to install this program as a package. In debian/unstable feedgnuplot is in the +official repos, so all you need to do is + + sudo apt-get install feedgnuplot + +Otherwise a package can be built with ln -fs package_definitions/debian debian dpkg-buildpackage -us -uc -b diff --git a/MANIFEST b/MANIFEST index 8ed0a3e..7a47fbf 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1,7 +1,6 @@ Makefile.PL MANIFEST bin/feedgnuplot -bin/feedgnuplot.pod t/00-load.t t/manifest.t Changes diff --git a/Makefile.PL b/Makefile.PL index 04ffa4b..3b28356 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -9,12 +9,28 @@ sub parseversion # libpackage-perl (0.02) # # I parse out the 0.02 part - open DCH, 'Changes' or die "Couldn't open 'Changes'"; + open DCH, '<', 'Changes' or die "Couldn't open 'Changes'"; my ($version) = =~ /^\S+ \s* \( ([0-9\.]+) \)/x or die "Couldn't parse version from 'Changes'"; close DCH; - return $version; + # The version is also stored in the script itself. Here I extract that version + # number and make sure the two match + open PL, '<', 'bin/feedgnuplot' or die "Couldn't open 'bin/feedgnuplot'"; + + while() + { + if( /VERSION = ([0-9\.]+)/ ) + { + if ( $1 != $version ) + { + die "Version mismatch. Changes says version is '$version', but 'bin/feedgnuplot' says it is '$1'"; + } + + return $version; + } + } + die "Couldn't parse version from 'bin/feedgnuplot'"; } sub MY::libscan @@ -42,13 +58,11 @@ WriteMakefile NAME => 'feedgnuplot', AUTHOR => q{Dima Kogan }, VERSION => parseversion(), - ABSTRACT_FROM => 'bin/feedgnuplot.pod', ($ExtUtils::MakeMaker::VERSION >= 6.3002 ? ('LICENSE' => 'perl') : ()), PL_FILES => {}, EXE_FILES => [ 'bin/feedgnuplot' ], - MAN1PODS => { 'bin/feedgnuplot.pod' => 'blib/man1/feedgnuplot.1' }, PREREQ_PM => { 'Test::Script::Run' => 0}, dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', }, clean => { FILES => 'feedgnuplot-*' }, diff --git a/README.pod b/README.pod index cc120d0..abe0c14 120000 --- a/README.pod +++ b/README.pod @@ -1 +1 @@ -bin/feedgnuplot.pod \ No newline at end of file +bin/feedgnuplot \ No newline at end of file diff --git a/bin/feedgnuplot b/bin/feedgnuplot index 4ddf1c7..7c0c4e0 100755 --- a/bin/feedgnuplot +++ b/bin/feedgnuplot @@ -12,6 +12,8 @@ use threads::shared; use Thread::Queue; use Pod::Usage; +my $VERSION = 1.24; + my %options; interpretCommandline(\%options); @@ -108,12 +110,25 @@ sub interpretCommandline 'square!', 'square_xy!', 'hardcopy=s', 'maxcurves=i', 'monotonic!', 'histogram=s@', 'binwidth=f', 'histstyle=s', 'terminal=s', - 'extraValuesPerPoint=i', 'help', 'dump', - 'geometry=s') or pod2usage(1); + 'extraValuesPerPoint=i', 'help', 'dump', 'version', + 'geometry=s') or pod2usage( -exitval => 1, + -verbose => 1, # synopsis and args + -output => \*STDERR ); + # handle various cmdline-option errors if ( $options->{help} ) - { pod2usage(0); } + { + pod2usage( -exitval => 0, + -verbose => 1, # synopsis and args + -output => \*STDOUT ); + } + + if( $options->{version} ) + { + print "feedgnuplot version $VERSION\n"; + exit 0; + } # no global style if one isn't given $options->{curvestyleall} = '' unless defined $options->{curvestyleall}; @@ -488,9 +503,10 @@ sub mainThread { if( defined $latestX && $domain[0] < $latestX ) { - # the x-coordinate of the new point is in the past, so I wipe out all the data for this curve - # and start anew + # the x-coordinate of the new point is in the past, so I wipe out + # all the data and start anew clearCurves(); + $latestX = undef; } else { $latestX = $domain[0]; } @@ -695,3 +711,404 @@ sub pushPoint my ($curve, $xy) = @_; push @$curve, $xy; } + + +=head1 NAME + +feedgnuplot - Pipe-oriented frontend to Gnuplot + +=head1 SYNOPSIS + +Simple plotting of stored data: + + $ seq 5 | awk '{print 2*$1, $1*$1}' + 2 1 + 4 4 + 6 9 + 8 16 + 10 25 + + $ seq 5 | awk '{print 2*$1, $1*$1}' | + feedgnuplot --lines --points --legend 0 "data 0" --title "Test plot" --y2 1 + +Simple real-time plotting example: plot how much data is received on the wlan0 +network interface in bytes/second (uses bash, awk and Linux): + + $ while true; do sleep 1; cat /proc/net/dev; done | + gawk '/wlan0/ {if(b) {print $2-b; fflush()} b=$2}' | + feedgnuplot --lines --stream --xlen 10 --ylabel 'Bytes/sec' --xlabel seconds + +=head1 DESCRIPTION + +This is a flexible, command-line-oriented frontend to Gnuplot. It creates +plots from data coming in on STDIN or given in a filename passed on the +commandline. Various data representations are supported, as is hardcopy +output and streaming display of live data. A simple example: + + $ seq 5 | awk '{print 2*$1, $1*$1}' | feedgnuplot + +You should see a plot with two curves. The C command generates some data to +plot and the C reads it in from STDIN and generates the plot. The +C invocation is just an example; more interesting things would be plotted +in normal usage. No commandline-options are required for the most basic +plotting. Input parsing is flexible; every line need not have the same number of +points. New curves will be created as needed. + +The most commonly used functionality of gnuplot is supported directly by the +script. Anything not directly supported can still be done with the +C<--extracmds> and C<--curvestyle> options. Arbitrary gnuplot commands can be +passed in with C<--extracmds>. For example, to turn off the grid, pass in +C<--extracmds 'unset grid'>. As many of these options as needed can be passed +in. To add arbitrary curve styles, use C<--curvestyle curveID extrastyle>. Pass +these more than once to affect more than one curve. To apply an extra style to +I the curves that lack an explicit C<--curvestyle>, pass in +C<--curvestyleall extrastyle>. + +=head2 Data formats + +By default, each value present in the incoming data represents a distinct data +point, as demonstrated in the original example above (we had 10 numbers in the +input and 10 points in the plot). If requested, the script supports more +sophisticated interpretation of input data + +=head3 Domain selection + +If C<--domain> is passed in, the first value on each line of input is +interpreted as the I-value for the rest of the data on that line. Without +C<--domain> the I-value is the line number, and the first value on a line is +a plain data point like the others. Default is C<--nodomain>. Thus the original +example above produces 2 curves, with B<1,2,3,4,5> as the I-values. If we run +the same command with --domain: + + $ seq 5 | awk '{print 2*$1, $1*$1}' | feedgnuplot --domain + +we get only 1 curve, with B<2,4,6,8,10> as the I-values. As many points as +desired can appear on a single line, but all points on a line are associated +with the I-value at the start of that line. + +=head3 Curve indexing + +By default, each column represents a separate curve. This is fine unless sparse +data is to be plotted. With the C<--dataid> option, each point is represented by +2 values: a string identifying the curve, and the value itself. If we add +C<--dataid> to the original example: + + $ seq 5 | awk '{print 2*$1, $1*$1}' | feedgnuplot --dataid --autolegend + +we get 5 different curves with one point in each. The first column, as produced +by C, is B<2,4,6,8,10>. These are interpreted as the IDs of the curves to +be plotted. The C<--autolegend> option adds a legend using the given IDs to +label the curves. The IDs need not be numbers; generic strings are accepted. As +many points as desired can appear on a single line. C<--domain> can be used in +conjunction with C<--dataid>. + +=head3 Multi-value style support + +Depending on how gnuplot is plotting the data, more than one value may be needed +to represent a single point. For example, the script has support to plot all the +data with C<--circles>. This requires a radius to be specified for each point in +addition to the position of the point. Thus, when plotting with C<--circles>, 2 +numbers are read for each data point instead of 1. A similar situation exists +with C<--colormap> where each point contains the position I the +color. There are other gnuplot styles that require more data (such as error +bars), but none of these are directly supported by the script. They can still be +used, though, by specifying the specific style with C<--curvestyle>, and +specifying how many extra values are needed for each point with +C<--extraValuesPerPoint extra>. C<--extraValuesPerPoint> is ONLY needed for the +styles not explicitly supported; supported styles set that variable +automatically. + +=head3 3D data + +To plot 3D data, pass in C<--3d>. C<--domain> MUST be given when plotting 3D +data to avoid domain ambiguity. If 3D data is being plotted, there are by +definition 2 domain values instead of one (I as a function of I and I +instead of I as a function of I). Thus the first 2 values on each line are +interpreted as the domain instead of just 1. The rest of the processing happens +the same way as before. + +=head3 Special data commands + +Other than the raw data, 2 special commands are interpreted if they appear in +the input. These are C and C. If a line of data begins with +C and we're plotting in realtime with C<--stream>, the plot will be +refreshed immediately. If a line of data begins with C, the plot is +cleared, to be re-filled with any data following the C. + +=head2 Real-time streaming data + +To plot real-time data, pass in the C<--stream [refreshperiod]> option. Data +will then be plotted as it is received. The plot will be updated every +C seconds. If the period isn't specified, a 1Hz refresh rate is +used. To refresh at specific intervals indicated by the data, set the +refreshperiod to 0 or to 'trigger'. The plot will then I be refreshed when +a data line 'replot' is received. This 'replot' command works in both triggered +and timed modes, but in triggered mode, it's the only way to replot. + +To plot only the most recent data (instead of I the data), C<--xlen +windowsize> can be given. This will create an constantly-updating, scrolling +view of the recent past. C should be replaced by the desired length +of the domain window to plot, in domain units (passed-in values if C<--domain> +or line numbers otherwise). + +=head2 Hardcopy output + +The script is able to produce hardcopy output with C<--hardcopy outputfile>. The +output type can be inferred from the filename, if B<.ps>, B<.eps>, B<.pdf>, +B<.svg> or B<.png> is requested. If any other file type is requested, +C<--terminal> I be passed in to tell gnuplot how to make the plot. + +=head2 Self-plotting data files + +This script can be used to enable self-plotting data files. There are 2 ways of +doing this: with a shebang (#!) or with inline perl data. + +=head3 Self-plotting data with a #! + +A self-plotting, executable data file C is formatted as + + $ cat data + #!/usr/bin/feedgnuplot --lines --points + 2 1 + 4 4 + 6 9 + 8 16 + 10 25 + 12 36 + 14 49 + 16 64 + 18 81 + 20 100 + 22 121 + 24 144 + 26 169 + 28 196 + 30 225 + +This is the shebang (#!) line followed by the data, formatted as before. The +data file can be plotted simply with + + $ ./data + +The caveats here are that on Linux the whole #! line is limited to 127 charaters +and that the full path to feedgnuplot must be given. The 127 character limit is +a serious limitation, but this can likely be resolved with a kernel patch. I +have only tried on Linux 2.6. + +=head3 Self-plotting data with perl inline data + +Perl supports storing data and code in the same file. This can also be used to +create self-plotting files: + + $ cat plotdata.pl + #!/usr/bin/perl + use strict; + use warnings; + + open PLOT, "| feedgnuplot --lines --points" or die "Couldn't open plotting pipe"; + while( ) + { + my @xy = split; + print PLOT "@xy\n"; + } + __DATA__ + 2 1 + 4 4 + 6 9 + 8 16 + 10 25 + 12 36 + 14 49 + 16 64 + 18 81 + 20 100 + 22 121 + 24 144 + 26 169 + 28 196 + 30 225 + +This is especially useful if the logged data is not in a format directly +supported by feedgnuplot. Raw data can be stored after the __DATA__ directive, +with a small perl script to manipulate the data into a useable format and send +it to the plotter. + +=head1 ARGUMENTS + + --[no]domain If enabled, the first element of each line is the + domain variable. If not, the point index is used + + --[no]dataid If enabled, each data point is preceded by the ID + of the data set that point corresponds to. This ID is + interpreted as a string, NOT as just a number. If not + enabled, the order of the point is used. + +As an example, if line 3 of the input is "0 9 1 20" + '--nodomain --nodataid' would parse the 4 numbers as points in 4 + different curves at x=3 + + '--domain --nodataid' would parse the 4 numbers as points in 3 different + curves at x=0. Here, 0 is the x-variable and 9,1,20 are the data values + + '--nodomain --dataid' would parse the 4 numbers as points in 2 different + curves at x=3. Here 0 and 1 are the data IDs and 9 and 20 are the + data values + + '--domain --dataid' would parse the 4 numbers as a single point at + x=0. Here 9 is the data ID and 1 is the data value. 20 is an extra + value, so it is ignored. If another value followed 20, we'd get another + point in curve ID 20 + + --[no]3d Do [not] plot in 3D. This only makes sense with --domain. + Each domain here is an (x,y) tuple + + --colormap Show a colormapped xy plot. Requires extra data for the color. + zmin/zmax can be used to set the extents of the colors. + Automatically increments extraValuesPerPoint + + --stream [period] Plot the data as it comes in, in realtime. If period is given, + replot every period seconds. If no period is given, replot at + 1Hz. If the period is given as 0 or 'trigger', replot ONLY when + the incoming data dictates this . See the "Real-time streaming + data" section of the man page. + + --[no]lines Do [not] draw lines to connect consecutive points + --[no]points Do [not] draw points + --circles Plot with circles. This requires a radius be specified for + each point. Automatically increments extraValuesPerPoint + + --xlabel xxx Set x-axis label + --ylabel xxx Set y-axis label + --y2label xxx Set y2-axis label. Does not apply to 3d plots + --zlabel xxx Set y-axis label. Only applies to 3d plots + + --title xxx Set the title of the plot + + --legend curveID legend + Set the label for a curve plot. Use this option multiple times + for multiple curves. With --dataid, curveID is the ID. Otherwise, + it's the index of the curve, starting at 0 + + --autolegend Use the curve IDs for the legend. Titles given with --legend + override these + + --xlen xxx When using --stream, sets the size of the x-window to plot. + Omit this or set it to 0 to plot ALL the data. Does not + make sense with 3d plots. Implies --monotonic + + --xmin xxx Set the range for the x axis. These are ignored in a + streaming plot + --xmax xxx Set the range for the x axis. These are ignored in a + streaming plot + --ymin xxx Set the range for the y axis. + --ymax xxx Set the range for the y axis. + --y2min xxx Set the range for the y2 axis. Does not apply to 3d plots. + --y2max xxx Set the range for the y2 axis. Does not apply to 3d plots. + --zmin xxx Set the range for the z axis. Only applies to 3d plots or colormaps. + --zmax xxx Set the range for the z axis. Only applies to 3d plots or colormaps. + + --y2 xxx Plot the data specified by this curve ID on the y2 axis. + Without --dataid, the ID is just an ordered 0-based index. + Does not apply to 3d plots. Can be passed multiple times, or passed a + comma-separated list + + --histogram curveID + Set up a this specific curve to plot a histogram. The bin + width is given with the --binwidth option (assumed 1.0 if + omitted). --histogram does NOT touch the drawing style. + It is often desired to plot these with boxes, and this + MUST be explicitly requested with --curvestyleall 'with + boxes'. This works with --domain and/or --stream, but in + those cases the x-value is used ONLY to cull old data + because of --xlen or --monotonic. I.e. the x-values are + NOT drawn in any way. Can be passed multiple times, or passed a comma- + separated list + --binwidth width The width of bins when making histograms. This setting applies to ALL + histograms in the plot. Defaults to 1.0 if not given. + --histstyle style Normally, histograms are generated with the 'smooth freq' + gnuplot style. --histstyle can be used to select + different 'smooth' settings. Allowed are 'unique', + 'cumulative' and 'cnormal'. 'unique' indicates whether a + bin has at least one item in it: instead of counting the + items, it'll always report 0 or 1. 'cumulative' is the + integral of the "normal" histogram. 'cnormal' is like + 'cumulative', but rescaled to end up at 1.0. + + --curvestyle curveID style + Additional styles per curve. With --dataid, curveID is + the ID. Otherwise, it's the index of the curve, starting + at 0. Use this option multiple times for multiple curves. + --curvestylall does NOT apply to curves that have a + --curvestyle + + --curvestyleall xxx Additional styles for all curves that have no --curvestyle + + --extracmds xxx Additional commands. These could contain extra global styles + for instance. Can be passed multiple times. + + --square Plot data with aspect ratio 1. For 3D plots, this controls the + aspect ratio for all 3 axes + + --square_xy For 3D plots, set square aspect ratio for ONLY the x,y axes + + --hardcopy xxx If not streaming, output to a file specified here. Format + inferred from filename, unless specified by --terminal + --terminal xxx String passed to 'set terminal'. No attempts are made to + validate this. --hardcopy sets this to some sensible + defaults if --hardcopy is given .png, .pdf, .ps, .eps or + .svg. If any other file type is desired, use both + --hardcopy and --terminal + + --maxcurves xxx The maximum allowed number of curves. This is 100 by default, + but can be reset with this option. This exists purely to + prevent perl from allocating all of the system's memory when + reading bogus data + + --monotonic If --domain is given, checks to make sure that the x- + coordinate in the input data is monotonically increasing. + If a given x-variable is in the past, all data currently + cached for this curve is purged. Without --monotonic, all + data is kept. Does not make sense with 3d plots. + No --monotonic by default. + + --extraValuesPerPoint xxx + How many extra values are given for each data point. Normally this + is 0, and does not need to be specified, but sometimes we want + extra data, like for colors or point sizes or error bars, etc. + feedgnuplot options that require this (colormap, circles) + automatically set it. This option is ONLY needed if unknown styles are + used, with --curvestyleall for instance + + --dump Instead of printing to gnuplot, print to STDOUT. Very useful for + debugging. It is possible to send the output produced this way to + gnuplot directly. + + --geometry If using X11, specifies the size, position of the plot window + + --version Print the version and exit + +=head1 ACKNOWLEDGEMENT + +This program is originally based on the driveGnuPlots.pl script from +Thanassis Tsiodras. It is available from his site at +L + +=head1 REPOSITORY + +L + +=head1 AUTHOR + +Dima Kogan, C<< >> + +=head1 LICENSE AND COPYRIGHT + +Copyright 2011-2012 Dima Kogan. + +This program is free software; you can redistribute it and/or modify it +under the terms of either: the GNU General Public License as published +by the Free Software Foundation; or the Artistic License. + +See http://dev.perl.org/licenses/ for more information. + +=cut diff --git a/bin/feedgnuplot.pod b/bin/feedgnuplot.pod deleted file mode 100644 index 1db9962..0000000 --- a/bin/feedgnuplot.pod +++ /dev/null @@ -1,396 +0,0 @@ -=head1 NAME - -feedgnuplot - Pipe-oriented frontend to Gnuplot - -=head1 SYNOPSIS - -Simple plotting of stored data: - - $ seq 5 | awk '{print 2*$1, $1*$1}' - 2 1 - 4 4 - 6 9 - 8 16 - 10 25 - - $ seq 5 | awk '{print 2*$1, $1*$1}' | - feedgnuplot --lines --points --legend 0 "data 0" --title "Test plot" --y2 1 - -Simple real-time plotting example: plot how much data is received on the wlan0 -network interface in bytes/second (uses bash, awk and Linux): - - $ while true; do sleep 1; cat /proc/net/dev; done | - gawk '/wlan0/ {if(b) {print $2-b; fflush()} b=$2}' | - feedgnuplot --lines --stream --xlen 10 --ylabel 'Bytes/sec' --xlabel seconds - -=head1 DESCRIPTION - -This is a flexible, command-line-oriented frontend to Gnuplot. It creates -plots from data coming in on STDIN or given in a filename passed on the -commandline. Various data representations are supported, as is hardcopy -output and streaming display of live data. A simple example: - - $ seq 5 | awk '{print 2*$1, $1*$1}' | feedgnuplot - -You should see a plot with two curves. The C command generates some data to -plot and the C reads it in from STDIN and generates the plot. The -C invocation is just an example; more interesting things would be plotted -in normal usage. No commandline-options are required for the most basic -plotting. Input parsing is flexible; every line need not have the same number of -points. New curves will be created as needed. - -The most commonly used functionality of gnuplot is supported directly by the -script. Anything not directly supported can still be done with the -C<--extracmds> and C<--curvestyle> options. Arbitrary gnuplot commands can be -passed in with C<--extracmds>. For example, to turn off the grid, pass in -C<--extracmds 'unset grid'>. As many of these options as needed can be passed -in. To add arbitrary curve styles, use C<--curvestyle curveID extrastyle>. Pass -these more than once to affect more than one curve. To apply an extra style to -I the curves that lack an explicit C<--curvestyle>, pass in -C<--curvestyleall extrastyle>. - -=head2 Data formats - -By default, each value present in the incoming data represents a distinct data -point, as demonstrated in the original example above (we had 10 numbers in the -input and 10 points in the plot). If requested, the script supports more -sophisticated interpretation of input data - -=head3 Domain selection - -If C<--domain> is passed in, the first value on each line of input is -interpreted as the I-value for the rest of the data on that line. Without -C<--domain> the I-value is the line number, and the first value on a line is -a plain data point like the others. Default is C<--nodomain>. Thus the original -example above produces 2 curves, with B<1,2,3,4,5> as the I-values. If we run -the same command with --domain: - - $ seq 5 | awk '{print 2*$1, $1*$1}' | feedgnuplot --domain - -we get only 1 curve, with B<2,4,6,8,10> as the I-values. As many points as -desired can appear on a single line, but all points on a line are associated -with the I-value at the start of that line. - -=head3 Curve indexing - -By default, each column represents a separate curve. This is fine unless sparse -data is to be plotted. With the C<--dataid> option, each point is represented by -2 values: a string identifying the curve, and the value itself. If we add -C<--dataid> to the original example: - - $ seq 5 | awk '{print 2*$1, $1*$1}' | feedgnuplot --dataid --autolegend - -we get 5 different curves with one point in each. The first column, as produced -by C, is B<2,4,6,8,10>. These are interpreted as the IDs of the curves to -be plotted. The C<--autolegend> option adds a legend using the given IDs to -label the curves. The IDs need not be numbers; generic strings are accepted. As -many points as desired can appear on a single line. C<--domain> can be used in -conjunction with C<--dataid>. - -=head3 Multi-value style support - -Depending on how gnuplot is plotting the data, more than one value may be needed -to represent a single point. For example, the script has support to plot all the -data with C<--circles>. This requires a radius to be specified for each point in -addition to the position of the point. Thus, when plotting with C<--circles>, 2 -numbers are read for each data point instead of 1. A similar situation exists -with C<--colormap> where each point contains the position I the -color. There are other gnuplot styles that require more data (such as error -bars), but none of these are directly supported by the script. They can still be -used, though, by specifying the specific style with C<--curvestyle>, and -specifying how many extra values are needed for each point with -C<--extraValuesPerPoint extra>. C<--extraValuesPerPoint> is ONLY needed for the -styles not explicitly supported; supported styles set that variable -automatically. - -=head3 3D data - -To plot 3D data, pass in C<--3d>. C<--domain> MUST be given when plotting 3D -data to avoid domain ambiguity. If 3D data is being plotted, there are by -definition 2 domain values instead of one (I as a function of I and I -instead of I as a function of I). Thus the first 2 values on each line are -interpreted as the domain instead of just 1. The rest of the processing happens -the same way as before. - -=head3 Special data commands - -Other than the raw data, 2 special commands are interpreted if they appear in -the input. These are C and C. If a line of data begins with -C and we're plotting in realtime with C<--stream>, the plot will be -refreshed immediately. If a line of data begins with C, the plot is -cleared, to be re-filled with any data following the C. - -=head2 Real-time streaming data - -To plot real-time data, pass in the C<--stream [refreshperiod]> option. Data -will then be plotted as it is received. The plot will be updated every -C seconds. If the period isn't specified, a 1Hz refresh rate is -used. To refresh at specific intervals indicated by the data, set the -refreshperiod to 0 or to 'trigger'. The plot will then I be refreshed when -a data line 'replot' is received. This 'replot' command works in both triggered -and timed modes, but in triggered mode, it's the only way to replot. - -To plot only the most recent data (instead of I the data), C<--xlen -windowsize> can be given. This will create an constantly-updating, scrolling -view of the recent past. C should be replaced by the desired length -of the domain window to plot, in domain units (passed-in values if C<--domain> -or line numbers otherwise). - -=head2 Hardcopy output - -The script is able to produce hardcopy output with C<--hardcopy outputfile>. The -output type can be inferred from the filename, if B<.ps>, B<.eps>, B<.pdf>, -B<.svg> or B<.png> is requested. If any other file type is requested, -C<--terminal> I be passed in to tell gnuplot how to make the plot. - -=head2 Self-plotting data files - -This script can be used to enable self-plotting data files. There are 2 ways of -doing this: with a shebang (#!) or with inline perl data. - -=head3 Self-plotting data with a #! - -A self-plotting, executable data file C is formatted as - - $ cat data - #!/usr/bin/feedgnuplot --lines --points - 2 1 - 4 4 - 6 9 - 8 16 - 10 25 - 12 36 - 14 49 - 16 64 - 18 81 - 20 100 - 22 121 - 24 144 - 26 169 - 28 196 - 30 225 - -This is the shebang (#!) line followed by the data, formatted as before. The -data file can be plotted simply with - - $ ./data - -The caveats here are that on Linux the whole #! line is limited to 127 charaters -and that the full path to feedgnuplot must be given. The 127 character limit is -a serious limitation, but this can likely be resolved with a kernel patch. I -have only tried on Linux 2.6. - -=head3 Self-plotting data with perl inline data - -Perl supports storing data and code in the same file. This can also be used to -create self-plotting files: - - $ cat plotdata.pl - #!/usr/bin/perl - use strict; - use warnings; - - open PLOT, "| feedgnuplot --lines --points" or die "Couldn't open plotting pipe"; - while( ) - { - my @xy = split; - print PLOT "@xy\n"; - } - __DATA__ - 2 1 - 4 4 - 6 9 - 8 16 - 10 25 - 12 36 - 14 49 - 16 64 - 18 81 - 20 100 - 22 121 - 24 144 - 26 169 - 28 196 - 30 225 - -This is especially useful if the logged data is not in a format directly -supported by feedgnuplot. Raw data can be stored after the __DATA__ directive, -with a small perl script to manipulate the data into a useable format and send -it to the plotter. - -=head1 ARGUMENTS - - --[no]domain If enabled, the first element of each line is the - domain variable. If not, the point index is used - - --[no]dataid If enabled, each data point is preceded by the ID - of the data set that point corresponds to. This ID is - interpreted as a string, NOT as just a number. If not - enabled, the order of the point is used. - -As an example, if line 3 of the input is "0 9 1 20" - '--nodomain --nodataid' would parse the 4 numbers as points in 4 - different curves at x=3 - - '--domain --nodataid' would parse the 4 numbers as points in 3 different - curves at x=0. Here, 0 is the x-variable and 9,1,20 are the data values - - '--nodomain --dataid' would parse the 4 numbers as points in 2 different - curves at x=3. Here 0 and 1 are the data IDs and 9 and 20 are the - data values - - '--domain --dataid' would parse the 4 numbers as a single point at - x=0. Here 9 is the data ID and 1 is the data value. 20 is an extra - value, so it is ignored. If another value followed 20, we'd get another - point in curve ID 20 - - --[no]3d Do [not] plot in 3D. This only makes sense with --domain. - Each domain here is an (x,y) tuple - - --colormap Show a colormapped xy plot. Requires extra data for the color. - zmin/zmax can be used to set the extents of the colors. - Automatically increments extraValuesPerPoint - - --stream [period] Plot the data as it comes in, in realtime. If period is given, - replot every period seconds. If no period is given, replot at - 1Hz. If the period is given as 0 or 'trigger', replot ONLY when - the incoming data dictates this . See the "Real-time streaming - data" section of the man page. - - --[no]lines Do [not] draw lines to connect consecutive points - --[no]points Do [not] draw points - --circles Plot with circles. This requires a radius be specified for - each point. Automatically increments extraValuesPerPoint - - --xlabel xxx Set x-axis label - --ylabel xxx Set y-axis label - --y2label xxx Set y2-axis label. Does not apply to 3d plots - --zlabel xxx Set y-axis label. Only applies to 3d plots - - --title xxx Set the title of the plot - - --legend curveID legend - Set the label for a curve plot. Use this option multiple times - for multiple curves. With --dataid, curveID is the ID. Otherwise, - it's the index of the curve, starting at 0 - - --autolegend Use the curve IDs for the legend. Titles given with --legend - override these - - --xlen xxx When using --stream, sets the size of the x-window to plot. - Omit this or set it to 0 to plot ALL the data. Does not - make sense with 3d plots. Implies --monotonic - - --xmin xxx Set the range for the x axis. These are ignored in a - streaming plot - --xmax xxx Set the range for the x axis. These are ignored in a - streaming plot - --ymin xxx Set the range for the y axis. - --ymax xxx Set the range for the y axis. - --y2min xxx Set the range for the y2 axis. Does not apply to 3d plots. - --y2max xxx Set the range for the y2 axis. Does not apply to 3d plots. - --zmin xxx Set the range for the z axis. Only applies to 3d plots or colormaps. - --zmax xxx Set the range for the z axis. Only applies to 3d plots or colormaps. - - --y2 xxx Plot the data specified by this curve ID on the y2 axis. - Without --dataid, the ID is just an ordered 0-based index. - Does not apply to 3d plots. Can be passed multiple times, or passed a - comma-separated list - - --histogram curveID - Set up a this specific curve to plot a histogram. The bin - width is given with the --binwidth option (assumed 1.0 if - omitted). --histogram does NOT touch the drawing style. - It is often desired to plot these with boxes, and this - MUST be explicitly requested with --curvestyleall 'with - boxes'. This works with --domain and/or --stream, but in - those cases the x-value is used ONLY to cull old data - because of --xlen or --monotonic. I.e. the x-values are - NOT drawn in any way. Can be passed multiple times, or passed a comma- - separated list - --binwidth width The width of bins when making histograms. This setting applies to ALL - histograms in the plot. Defaults to 1.0 if not given. - --histstyle style Normally, histograms are generated with the 'smooth freq' - gnuplot style. --histstyle can be used to select - different 'smooth' settings. Allowed are 'unique', - 'cumulative' and 'cnormal'. 'unique' indicates whether a - bin has at least one item in it: instead of counting the - items, it'll always report 0 or 1. 'cumulative' is the - integral of the "normal" histogram. 'cnormal' is like - 'cumulative', but rescaled to end up at 1.0. - - --curvestyle curveID style - Additional styles per curve. With --dataid, curveID is - the ID. Otherwise, it's the index of the curve, starting - at 0. Use this option multiple times for multiple curves. - --curvestylall does NOT apply to curves that have a - --curvestyle - - --curvestyleall xxx Additional styles for all curves that have no --curvestyle - - --extracmds xxx Additional commands. These could contain extra global styles - for instance. Can be passed multiple times. - - --square Plot data with aspect ratio 1. For 3D plots, this controls the - aspect ratio for all 3 axes - - --square_xy For 3D plots, set square aspect ratio for ONLY the x,y axes - - --hardcopy xxx If not streaming, output to a file specified here. Format - inferred from filename, unless specified by --terminal - --terminal xxx String passed to 'set terminal'. No attempts are made to - validate this. --hardcopy sets this to some sensible - defaults if --hardcopy is given .png, .pdf, .ps, .eps or - .svg. If any other file type is desired, use both - --hardcopy and --terminal - - --maxcurves xxx The maximum allowed number of curves. This is 100 by default, - but can be reset with this option. This exists purely to - prevent perl from allocating all of the system's memory when - reading bogus data - - --monotonic If --domain is given, checks to make sure that the x- - coordinate in the input data is monotonically increasing. - If a given x-variable is in the past, all data currently - cached for this curve is purged. Without --monotonic, all - data is kept. Does not make sense with 3d plots. - No --monotonic by default. - - --extraValuesPerPoint xxx - How many extra values are given for each data point. Normally this - is 0, and does not need to be specified, but sometimes we want - extra data, like for colors or point sizes or error bars, etc. - feedgnuplot options that require this (colormap, circles) - automatically set it. This option is ONLY needed if unknown styles are - used, with --curvestyleall for instance - - --dump Instead of printing to gnuplot, print to STDOUT. For - debugging. - - --geometry If using X11, specifies the size, position of the plot window - -=head1 ACKNOWLEDGEMENT - -This program is originally based on the driveGnuPlots.pl script from -Thanassis Tsiodras. It is available from his site at -L - -=head1 REPOSITORY - -L - -=head1 AUTHOR - -Dima Kogan, C<< >> - -=head1 LICENSE AND COPYRIGHT - -Copyright 2011-2012 Dima Kogan. - -This program is free software; you can redistribute it and/or modify it -under the terms of either: the GNU General Public License as published -by the Free Software Foundation; or the Artistic License. - -See http://dev.perl.org/licenses/ for more information. - -=cut