                              RtPlot (version 0.45) 
                            Copyright (c) Dov Bai (1999-2002)


Version history:
----------------
Version 0.4  (12-1-2001) - Initial release.
Version 0.41 (12-8-2001) - Added "ticks" with numbers on x,y axes.
Version 0.45 (03-2-2002)   - Added (1) Ability to configure with XML configuration files.
                           (2) Data points in addition to the lines. 
                           (3) Different line styles. 
                           (4) Comments are allowed at lines beginning with #

Copyright
---------

 RtPlot version 0.45, Copyright(c) 1999-2002 Dov Bai

 Permission to use, copy, and distribute this software and its
 documentation for any purpose (except as detailed hereunder) is granted
 without fee, provided that the above copyright notice and this permission
 notice appear in all copies of the software and related documentation. You
 may not disassemble, decompose, reverse engineer, or alter any of the files
 in the package.

 This software cannot be sold or bundled with any commercial package without
 express written permission from Dov Bai, its author.

 THIS IS FREEWARE. THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF 
 ANY KIND. THERE IS NO LIABILITY FOR ANY DAMAGES OF ANY KIND ARISING OUT OF 
 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 

RtPlot-Real time plotting - Summary
--------------------------------------

RtPlot is a small and little resource consuming  program for displaying real time 
2D plots of data generated by other programs. It was written because of a need 
to monitor the progress of long-running scientific programs occasionally producing 
output suitable for plotting. The user can open as many plotting windows as needed. 
Each plotting window monitors a single data file and plots its contents. When the 
data file is updated by another concurrently running program the 2D display is 
updated in the plotting window. The plot may be dragged with the mouse in the plot- 
window. The user can configure the frequency in which RtPlot checks for file updates, 
force freezing or an update of the plot, range of x, range of y, number of ticks 
along x,y axes and other parameters with a couple of mouse clicks. The plot 
configuration may be saved or read from XML configuration files.


Package contents
----------------

 The package includes 3 files: 
   (1)  rtplot.exe - RtPlot executable
   (2)  readme.txt - this file    
   (3)  plottest.exe - for demonstration purposes (see below).
   (4)  testplot1.txt, testplot2.txt - sample files produced by plottest.exe
   (4)  testplot1.xml, testplot2.xml - Sample XML configuration 
                     files for the files testplot1.txt & testplot2.txt
                     generated by plottest.exe
   (5)  rtplot.xml - sample default configuration file

Usage
-----

 To open a new plot window click File->New Plot in the initial menu. A dialog box opens 
with default values of ranges of x & y ([x-min,x-max], [y-min, y-max]), and file name. 
You may change the values in this dialog. "x-col" is the column in the data file used 
for the x-axis, "y-col" is the y-axis. If there are only two data columns in the file, 
normally "x-col" is the first (0) column and "y-col" is the second (1). With more than 
two columns, it is possible to change to different columns.

 Alternatively, you may load a saved configuration from XML file by checking the
"Use XML configuration file" box. The defaults are loaded from the file "rtplot.xml"
if it exists.  See Section "XML configuration". 

 Once the all parameters are set in the initial dialog, click "OK" and a plot window 
opens with the data plotted. By default the program checks for data file updates about 
every 1 second. This can be changed by clicking Timer->Set and typing a different 
number of seconds in the dialog box. Setting the update interval to 0 stops checking 
for file updates. It is also possible to stop checking for updates by right-clicking 
anywhere on the plot window area and choosing "Freeze" from the floating pop-up menu. 
Selecting "Unfreeze" in the pop-up menu will re-enable data updates. Selecting 
"Update" forces an immediate data update no matter what the value of timer interval is.

 The x, y ranges can be adjusted either by clicking Plot->Range->x-range (or y-range) 
in the main menu or "Modify" in the floating pop-up menu. Adjusting the number of 
x & y "ticks" is similar. Selecting "Line" in the pop-up menu opens sub menu from 
which it is possible to change color (default black), width (default 1) and style 
(default solid) of the line. The color is expressed in R-G-B (Re, Green, Blue) units. 
Each of R, G, B can  be any number between 0,255. RGB=(0,0,0) is a black line, 
RGB=(255,0,0) is a red line, RGB = (0,255,0) is a green line and RGB=(0,0,255) is 
a blue line.

 Small data points are added by default to the plotted line. It is possible to change 
their size by selecting in the floating pop-up menu line->points and choosing the point 
size. Selecting 0 will eliminate the data points.

 Another useful feature is the ability to plot up to 3 most recent data updates in the 
same plot window. The number of updates can be set by clicking Plot->History in the main 
menu and then checking any of the numbers in the menu. By default the history number 
is 0 (no previous data is displayed).
   
 Listed in the title bar of the plot window are (1) The data file name, (2) Plotted 
columns and (3) time of most recent data update. The time of starting RtPlot appears 
in the application title bar.

 It is possible to open any number of plot windows by clicking File->New Plot in the 
main menu.

 DRAGGING: A useful feature is the ability to drag the plotted data in the plot window 
and to examine various portions of the plot. This is done by clicking the left mouse 
button and dragging the mouse while the button is pressed.

XML configuration
-----------------

  The configuration of a plot may be saved in a XML file. To save configuration, click 
File->Save Configuration. A file dialog will open.

  To load a plot using a configuration file click File and in the "New Plot Information"
dialog check the "use XML configuration file" box. A file dialog will open.

  By default, RtPlot loads its configuration from a file "rtplot.xml" in the current
directory.

Data Format
-----------

 RtPlot assumes the data in the file is ordered in two (or more) columns.  E.g.

0.0   1.0
1.0   2.0
2.0   3.0

describes three points of a straight line. Lines beginning with # are considered
comments.


Demonstration
--------------

The package contains a small executable, plottest.exe. Running the executable will 
produce two data files: testplot1.txt & testplot2.txt. Initially, the two files include
data for sin & cosine functions with zero phase. As time progresses the phase is 
changing and the data in the files is updated every 1 second. The package includes XML 
configuration files for the two data files. If you load the files into RtPlot, you may 
view the "moving" sin & cosine.  


Author
------

Please direct questions, suggestions or bug reports to the author:

Dov Bai
e-mail: dbai@juno.com