mirror of
https://github.com/dkogan/feedgnuplot.git
synced 2025-05-05 22:11:12 +08:00
365 lines
15 KiB
Plaintext
365 lines
15 KiB
Plaintext
=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<awk> command generates some data to
|
|
plot and the C<feedgnuplot> reads it in from STDIN and generates the plot. The
|
|
C<awk> 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<all> the curves, 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<X>-value for the rest of the data on that line. Without
|
|
C<--domain> the I<X>-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<X>-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<X>-values. As many points as
|
|
desired can appear on a single line, but all points on a line are associated
|
|
with the I<X>-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<awk>, 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<and> 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<Z> as a function of I<X> and I<Y>
|
|
instead of I<Y> as a function of I<X>). 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<replot> and C<clear>. If a line of data begins with
|
|
C<replot> and we're plotting in realtime with C<--stream>, the plot will be
|
|
refreshed immediately. If a line of data begins with C<clear>, the plot is
|
|
cleared, to be re-filled with any data following the C<clear>.
|
|
|
|
=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<refreshperiod> 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<only> 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<all> the data), C<--xlen
|
|
windowsize> can be given. This will create an constantly-updating, scrolling
|
|
view of the recent past. C<windowsize> 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 is inferred from the filename with B<.ps>, B<.eps>, B<.pdf> and
|
|
B<.png> currently supported.
|
|
|
|
=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<data> 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( <DATA> )
|
|
{
|
|
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.
|
|
|
|
--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
|
|
|
|
--curvestyleall xxx Additional styles for ALL curves.
|
|
|
|
--extracmds xxx Additional commands. These could contain extra global styles
|
|
for instance
|
|
|
|
--size xxx Gnuplot size option
|
|
|
|
--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
|
|
|
|
--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.
|
|
|
|
=head1 ACKNOWLEDGEMENT
|
|
|
|
This program is originally based on the driveGnuPlots.pl script from
|
|
Thanassis Tsiodras. It is available from his site at
|
|
L<http://users.softlab.ece.ntua.gr/~ttsiod/gnuplotStreaming.html>
|
|
|
|
=head1 REPOSITORY
|
|
|
|
L<https://github.com/dkogan/feedgnuplot>
|
|
|
|
=head1 AUTHOR
|
|
|
|
Dima Kogan, C<< <dima@secretsauce.net> >>
|
|
|
|
=head1 LICENSE AND COPYRIGHT
|
|
|
|
Copyright 2011 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
|