Plotting data on the NCCS
=========================

MG 2001/10/11

Data received by observing programs should be displayed for visual verification
of data quality.  

If on-screen plotting is done using a subroutine that is part of the
observing program, the plot will disappear as soon as the observing program
terminates.

A better way of handling plotting is to use an independent plot server
program, whereby the plot of the last data obtained will remain on screen
until the next data set comes in.

This has been done for the NCCS with the program "plotserver",
which is to be found in directory:
/usr/local/src/nccs/plotting/plotserver.

It is based on code found in the Australian correlator software.

It uses sockets to communicate, and sets up a socket server to which
observing programs can connect.  

In order that the programs know what socket number to use, the following
line setting an environment variable has been added to .bash_profile on
pc NCCS1, so it is set for each xterm that is opened:
	export PlotDataSocket="localhost::5018"
The socket number is one greater than than largest used in the correlator
software.

Graphics are done using PGPLOT.  The options for plotting have been kept
simple and are outlined below.

To illustrate how to set up data for plotting, a program "testsendplot" has
been written as a dummy observing program.  It shows the code and
subroutines that need to be incorporated into an observing program.  It is
found in directory:
/usr/local/src/nccs/plotting/testsendplot.

You can run "plotserver" and "testsendplot" to see how they operate.

The subroutines called by "testsendplot" will likely end up in the system
library: 
"makebuf" constructs the data buffer for transmission to "plotserver".
"sendplot" transmits the buffer via the socket.

The following comments are extracted from "testsendplot.c" and show what to
do in the observing program:


/* x, y data array lengths
 * based on maximum spectrum length, 
 * can be made longer but then must also be changed in "plotserver" */
#define DATA_LEN 4096
/* corresponding buffer size needed for sending data + housekeeping */
#define BUF_LEN  ( ( DATA_LEN * 8 ) + 190 )
 
/* housekeeping and data for the plot */
	
	int num_panels;	/* number of panels on page 
			 * used when num_graph = 1
			 * 1 = 1 plot per page; 
			 * 2 = one plot above the other;
			 * 3 or 4 = 2 by 2 plots on page;
			 * 5 or more = 3 x 3 plots on page */

	int num_graph;	/* 0 = draw data on previous axes, 
	                 *      put title on second line
	                 * 1 = draw graph on new page, div as per num_panels
	                 * 2 = draw graph on new axes on this page */

	int num_points;	/* number of data point in xx, yy */

	/* plot title: 
	 * for num_panels = 1 or 2, use up to 80 chars;
	 *		    3 or 4, use up to 50 chars;
	 *		    5+,     use up to 40 chars
         * relevant information about the data should be written in 'title'
         * eg object name, frequency, polarization, time
	 */
	char title[80];

	/* plot x-axis label:
	 * for all num_panels, use up to 40 chars 
	 */
	char xlabel[40];

	/* plot y-axis label:
	 * for num_panels = 1 to 4, use up to 40 chars;
	 * 		    5+,     use up to 30 chars
	 */	
	char ylabel[40];

	/* test data - PGPLOT requires data as floats, not doubles */
	float xx[DATA_LEN];
	float yy[DATA_LEN];

	/* buffer for storing data for transmission */
	char buf[BUF_LEN];

As we will generally be getting two signals at a time, from each
polarization, the program is designed to show the first signal on the plot
with the first line of the title and the first data set in one colour, and a
repeat plot on the same axes for the second signal has the second title and
data set in a different colour.

Only two data sets should be plotted on the same axes,
as the second title will be overwritten on any subsequent attempt to plot on
the same axes.  The data will however plot correctly if this is done.


Making it work
--------------

To make this all work, "plotserver" must be run in its own xterm before
running the observing.  It will open another xterm for the PGPLOT graphics
when the first data set is received for plotting.

At present "plotserver" writes diagnostic message to the xterm from which it
is run.  In the fullness of time this would be replaced by the logging of
errors to the observing log file.

Also in the fullness of time this implementation should be replaced by a
device server by JQ.