                              RtPlot (version 0.47) 
                         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 #
version 0.46 (08-28-2002) - Added support for saving plots as BMP (bitmap) files.
version 0.47 (09-07-2002) - (1) Fixed bugs.
                            (2) Added support for saving plots in in PNG (Portable Network Graphic) format.
                                The PNG support uses the publicly available libraries zlib, libpng, and
                                pngdib (by Jason Summers).

Copyright
---------

 RtPlot version 0.47, 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. Plots may be saved
in BMP/PNG  formats and plot configurations may be saved/read in XML configuration 
files.


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

 The package includes the following files: 
   (1)  rtplot.exe - RtPlot executable
   (2)  readme.txt - this file    
  The following files are included for demonstration purposes (see below):
   (3)  plottest.exe - for demonstration purposes (see below).
   (4)  testplot1.txt, testplot2.txt - sample files produced by plottest.exe
  The following file is Simtel xml file. It is not required for using RtPlot.
   (5)  rtplt047.xml

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 possibly with 
default file name. You may edit the values in this dialog. "x-col" is the column in 
the data file used as 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 prevously 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.

BMP/PNG files
------------------
RtPlot is able to save the contents of any plot window in 4-bit (16 colors) bitmap 
(BMP) or PNG (Portable Network Graphics) formats. The choice of 4-bits is to save disk 
space, but this may be configurable in future versions. From the file menu select 
"Save as.." to open the Windows Save dialog box and select BMP or PNG formats. 

 If you need your plot in GIF format, you may use other tools such as the free command- 
line utility bmp2gif (downloadable from Simtel) to generate a GIF file from BMP.


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

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

  To load a plot using an existing 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 if it exists. 

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. Loading files to RtPlot
create "moving" sin & cosine plots. If the plots are not moving, it is probably because
you did not execute correctly the plottest.exe executable. 

Author
------

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

Dov Bai
e-mail: dbai@juno.com