PLOVE ~~~~~ OVERVIEW -------- Plove is a handy tool for plotting OMNeT++ output vectors. It uses gnuplot to do the actual work. You can specify the drawing style (lines, dots etc) for each vector as well as set the most frequent drawing options like axis bounds, scaling, titles and labels etc. You can save the gnuplot graphs to files (postscript, latex, pbm etc) with a click. Plove can also generate standalone shell scripts that plot output vectors in much the same way Plove does itself. These scripts can be used for batch processing or to debug filters (see later). Plove does not take away any of gnuplot's flexibility -- you can embed your own gnuplot commands to customize the output. Filtering the results before plotting (averaging, truncation, smoothing, etc) is possible. Some filters are built in, and you can easily create new filters or modify the existing ones. Filters can be incorporated in one of three ways: as awk expressions, as awk programs and as external filter programs. Filters can be parameterized. Multiple filters for the same vector is not currently supported; also, you cannot currently feed several vectors into a single filter. Plove does not create temporary files, so you don't need to worry about disk space: if the output vector is there, Plove can plot it for you. Moreover, it can also work with gzipped vector files without extracting them -- just make sure you have zcat. Plove never modifies the output vector files themselves. On startup, Plove automatically reads the .ploverc file in your home directory. The file contains general gnuplot settings, the filter configuration etc (that is, the stuff from the Options menu). REQUIRED PROGRAMS ----------------- grep, gnuplot -- absolutely needed awk (gawk) -- if you want to use the built-in filters zcat -- if you want to process gzipped output vector files (without decomp- ressing them) WINDOWS ------- Windows users should create a plove.bat file which starts plove using wish, e.g: @c:\tcl82\bin\wish82.exe -f c:\omnetpp\src\plove\plove or rename the plove file to plove.tcl and associate the .tcl extension with the wish application. Be sure to fill in the Options|External programs dialog. If still you cannot load an output vector file properly (you see garbage in the left listbox), your grep program is probably broken (it has difficulties with Unix-style, LF-terminated lines). Especially, the Borland grep is not good. You should get a decent one, for example from the Cygwin package. USAGE ----- First, you load an output vector file (.vec) into the left pane. You can also load gzipped vector files (.vec.gz) without having to decompress them. You can copy vectors from the left pane to the right pane by clicking the right arrow icon in the middle. The large PLOT button will plot the _selected_ vectors in the right pane. Selection works as in Windows: dragging and shift+left click selects a range, and ctrl+left click selects/deselects individual items. To adjust drawing style, change vector title or add filter, push the Options... button. This works for several selected vectors too. Plove accepts nc/mc-like keystrokes: F3, F4, F5, F6, F8, grey'+' and grey '*'. The left pane works as a general storage for vectors you're working with. You can load several vector files, delete unnecessary vectors, rename them etc. All this will not affect the vector files on disk. In the right pane, you can duplicate vectors if you want to filter the vector and also keep the original. If you set the right options for a vector but temporarily do not want it to hang around in the right pane, you can put it back into the left pane for storage. WRITING FILTERS --------------- As you might have guessed already, filters get an output vector on their standard input (as plain text, with the timestamp being the second and the value being the third field on each line), do some processing to it and write the result to the standard output. Filters can be incorporated in one of three ways: as awk expressions, as awk programs and as external programs. The 'awk expression' filters mean assembling and launching commands like this: ... | awk '{$3 = ; print}' | ... An awk program filter means running the following command: ... | awk '' | ... The third type of filters will be used like this: ... | | ... Before the filter pipeline is launched, the following substitutions are performed on the awk scripts: t --> $2 x --> $3 The parameters of the form $(paramname) are also replaced with their actual value. Thus, if you want to add 1 to all value, you can use the awk expression filter x+1 (this will turn into: awk '{$3 = $3+1}; print'). When you want to shift the vector by a used-defined DT time, you can create the following awk program filter: {t += $(DT); print}. Do not forget the print statement, or your filter will not output anything and the gnuplot graph will be empty. If you push the PLOT button and nothing shows up, probably there's something wrong with the filter expression. If you're writing a new filter and it doesn't seem to work, choose File|Save script and do your debugging on the resulting script. For example, it is a common mistake to leave out 'print' from the script. PORTABILITY ----------- Plove works fine on Unix and (with some limitations) on Win95/NT. (The limitations come from the facts that Win95/NT doesn't have named pipes in the way Unix does, the length of the command line is limited, the shell is crippled etc... I had to use a dozen temporary files. And expect the Win95/NT version to be slower than Unix version.) Known bug: If you plot too many vectors at the same time, some of them may not appear in the plot because the length of the 'plot' command exceeds the limit hardwired in gnuplot. Enjoy! --Andras