|
Документ взят из кэша поисковой машины. Адрес
оригинального документа
: http://www.naic.edu/~astro/aovlbi/fsdoc/manuals/pdplt.html
Дата изменения: Sat Mar 30 19:09:47 2002 Дата индексирования: Sun Dec 23 01:44:40 2007 Кодировка: Поисковые слова: п п п п п |
VLBI Software Documentation
Field System
pdplt: Plot Pointing Data
Fredrik Lindenau
NVI, Inc./GSFC
Program Reference Manual
NASA/Goddard Space Flight Center Version 9.3
Space Geodesy Program September 1, 1997
1.1 Purpose
pdplt is a graphical tool for examining, viewing and editing of pointing data. pdplt reads the
log file produced when pointing data was taken and generates a number of graphs which are
designed to help the user to examine and edit the data. The data can then be saved as an output
file in xtrac format, or printed to a postscript printer. Please refer to the xtrac manual for
information on that file format.
1.2 Definitions
Log file Field System log file containing pointing data.
Log directory directory in which Field System log files are stored, usually /usr2/log
Antenna type XYNS (X/Y, North/South); XYEW (X/Y, East/West); HADC (Hour
Angle/Declination) or AZEL (Azimuth/Elevation).
1st axis X, Hour Angle or Azimuth axis, depending on the current antenna type.
2nd axis Y, Declination or Elevation axis, depending on the current antenna type.
2.1 Getting started: the File-New menu item
This section describes how to start pdplt, and the New menu item in the File menu.
To start the program, just type pdplt at the command prompt. A window will open on your
screen, from which you can run the program interactively with your pointing device. If no
window opens, please go to the section 5.0 Installation in this manual for further reference.
To open a new log file for input, select the New menu item in the File menu. A window
will open, labeled Open new FS log file, in which you should enter the filename of the
log file you want to examine. If you do not enter a directory path, pdplt defaults to the log
directory. In order to open a file in the current directory (from which pdplt was started), you
must enter ./filename, to specify that the file is in the current directory.
After you hit return in the Open new FS log file window, pdplt tells you if the
filename was valid or not. If the filename was a valid log file, the day number of the initial entry
is displayed. Hit return again, or press OK, to accept this log file. (NB! When running pdplt
under Tk 4.0 and higher, pdplt may open the log file without first displaying the day number
for confirmation). pdplt will now run the xtrac and error programs to extract data from the
log file. This might take some time on older computers. If your system is correctly set up (i.e. the
Tcl/Tk interpreter was found, and the xtrac and error programs were installed) the screen
will eventually show a plot of the pointing data, 1st axis vs. 2nd axis. If an error occurred, see
Troubleshooting in section 5.2 for further information.
Two error messages are possible in the Open new FS log file window. The first, The
file specified could not be opened , is displayed if the open system call
generated an error. The most probable reason for this is that the file did not exist. Please note that
pdplt defaults to the log directory, not the current directory, unless otherwise specified. The
second error message, The file specified did not start with a valid day
no., is displayed if the file did exist, but did not start with five numeric (range 0-9) characters.
All FS log files should start with a day number of five numeric characters. If it does not, the file
may be corrupt and must be repaired before it can be opened by the pdplt program.
When you open a new log file, you may notice that the labels on the upper-right part of the screen
change to fit your antenna type. The current antenna type is set by pdplt as specified in the
xtrac control file, when reading the xtrac output file. Now, try selecting the graph menu, and
switch between the different plots available.
2.2 Examining pointing data: the Graph menu
You can examine the pointing data using the different types of plots available in the Graph
menu. These are:
1st axis vs. 2nd axis
1st axis vs. 1st and 2nd axis offsets
2nd axis vs. 1st and 2nd axis offsets
To change plot type, click on the Graph menu, and then on the plot desired. You may also use
the n key on the keyboard, which switches to the next plot in the menu, and the p key, which
switches to the previous plot. Changing plots may take some time on older computers.
2.2.1 Rescaling: the input fields in the main window
To rescale any plot, enter the new minimum and maximum values for the plot in the entry fields
on the right part of the screen. The plot is updated when you hit return in any of those fields.
Also, autoscaling is available by clicking on the appropriate autoscale button on the screen's
lower-right.
NB! If a data point is out of range, i.e. the value is not within the minimum and maximum values
of the current plot, it does not turn invisible, but is displayed on the border. That is, all points, or
error bars, that are on the border of the plot may have any value that is out of range. A way to be
certain of the accuracy of all points or error bars plotted is to use the autoscale buttons on the
main screen. When a plot is first selected in the graph menu, the vertical axis is always
autoscaled. The horizontal axis is set to certain default values, for example -90 to 90 degrees if
you have an XYNS, XYEW or HADC type antenna.
2.2.2 Viewing data affiliated with data points: data points in the main window
To view data affiliated with a certain data point, simply move the pointer over the data point. The
data fields on the screen's upper-right will tell you the following for the data point:
the 1st axis coordinate
the 2nd axis coordinate
the 1st axis offset
the 2nd axis offset
the 1st axis offset sigma (current selected sigma, see section 2.2.3)
the 2nd axis offset sigma (current selected sigma, see section 2.2.3)
the source for the data point
the elevation of the antenna when the data point was taken
For example, on an XYNS antenna, when moving the pointer over a data point, the data point
fields might read:
X: -71.8
Y: -44.4
X-offset: -0.002
Y-offset: -0.00606
X-sigma: 0.00131
Y-sigma: 0.00472
Source: orion-a
2.2.3 Changing the current sigma type: the Sigma menu
When plotting the offsets, you will notice that error bars will be shown for the data points. If you
have the latest version of the error program, there are different types of sigma values available.
These are:
Input sigma values. These are the input sigma values to the error program.
A-priori sigma values.
A-posteriori sigma values.
You can change the current sigma type by clicking on the Sigma menu and choosing a new
sigma type. The selected sigma value affects the error bars plotted, as well as the sigma value
shown in the screen's upper-right part when the cursor is over a data point. Note that older
versions of the error program only support Input sigma values.
2.2.4 Viewing statistics: the Statistics menu
Statistics, such as mean and rms values, can be viewed by clicking on the Statistics menu.
The statistics are shown on the pull-down menu. Note that the statistics originate from the last
time the error program was run. If you are editing data points out, the statistics will not be up
to date until you have reprocessed your editing. See section 2.3.4 for instructions on how to do
this.
2.3 Editing pointing data: manual editing in the main window
You may edit a data point out manually by moving the pointer over the data point and clicking
the left mouse button once. The data point will turn white, which means that it is inactive. If you
make a mistake, and want to re-add the point, just click on it a second time, and it will again turn
black, which means that it is active. Manual editing can be done in any of the plots available in
the Graph menu.
Note that the right part of the status bar on the bottom of the screen always tells you the number
of good data points, and the total number of data points. When you click on a black point, turning
it inactive, the number of good data points will be decreased by one.
Inactive data points are still plotted, but the autoscale procedure bypasses them. Hence, if the
extreme value of any plot was edited out, that data point will be displayed on the border when the
plot is autoscaled.
2.3.1 x-sigma editing: the Edit - x-sigma menu item
If you click on the Edit menu, and select the x-sigma menu item, a dialog box will open.
In the dialog box you may enter a factor for x-sigma removal of data points. The default value is
3. This means that all data points which are more than three sigma away from the zero line, in
any of the plots, will be automatically edited out. The value entered for x-sigma removal must be
greater then zero.
2.3.2 Re-adding all points: the Edit - Add all points menu item
To turn all data points active, thus discarding any manual or x-sigma editing made, select the
Add all points menu item in the Edit menu. All points will turn active, and they will
all be plotted in black on screen. This is useful, for example, when an x-sigma process did not
render the expected result.
2.3.3 Highlighting sources: the Sources menu
When editing data, it can be useful to highlight all data points originating from the same source.
This may by done by using the Sources menu. When a file is opened, the input is scanned for
all sources in the file. The sources found are put in the Sources menu. When selecting a
certain source in the menu, all points (at least one) originating from that source are highlighted.
Note that you can also see what source a data point originated from by moving the mouse pointer
over it. The source name will be displayed among the data fields on the upper-right part of the
screen.
To turn source highlighting off, select the No source menu item in the Sources menu.
2.3.4 Reprocessing your data: the Edit - Reprocess menu item
After you have edited data points out, you might want to re-run the error program to update
your data. This can be done by selecting the Reprocess menu item in the Edit menu. When
Reprocess is selected, a new input file for the error program will be created, based upon your
current editing. The error program is then executed, and the result again read into the pdplt
program. For example, you will notice that the mean and rms values in the statistics menu will
have changed.
2.4 Saving your work: the File - Save menu item
You can save your current editing by selecting the Save menu item in the File menu.
When selecting Save the current editing will immediately be saved in the file names specified
in I/O Setup . The setting of file names is discussed in section 2.4.2.
Two files are saved. The first is an output file of xtrac format. Please refer to the xtrac manual
for information on this file format. Inactive data points are marked with a 0 in the first column
of the file and active data points are marked with a 1 .
The second file is the output file from the error program. This is the file that was created when
you last reprocessed your data. If you never reprocessed the data, it is the file generated by the
error program when you started the pdplt program.
2.4.1 Opening a previously saved editing: the File - Open menu item
To open a previously saved editing, select the Open menu item in the File menu. In the
entry field, give the file name to the file in xtrac format. Only files in xtrac format can be
opened by selecting this menu item. When opening a new file, be sure that you have saved your
current editing, or it will be discarded as the new input file is read.
2.4.2 File name conventions: the File - I/O setup menu item
File names are usually automatically set according to the FS naming conventions when you open
a new log file. However, when you open a file of xtrac format, which is not named according
to the FS naming conventions, pdplt cannot determine the proper file names. In that case, you
must specify the output file names yourself. You may change the output file names by selecting
the I/O setup menu item in the File menu. According to the FS naming conventions, the
files should be named as follows:
Files in xtrac format: /usr2/log/xtrYYDDD
Files in error format: /usr2/log/errYYDDD
where YYDDD is the year and day number when the pointing data was taken. However, you may
specify any valid output file name in I/O setup .
Other things that can be changed in I/O setup are the default directory for FS log files
(which is usually /usr2/log), and the control files for the xtrac and error programs. Also,
the file names of the temporary files pdplt uses can be changed, but these may only be changed
before any log file has been opened. When the temporary files have been created, their file names
cannot be changed.
Please note that all changes in I/O setup are temporary, and will not stay in effect the next
time you run pdplt. To make permanent changes, you must change the parameters in the
initialization section of the source code. These have comments to help you, but be sure that you
know what you are doing.
2.5 Printing: the File - Print menu item
You can print any plot by selecting the Print menu item in the File menu. Plots are
printed in encapsulated postscript (eps) format. If you select destination Printer , the lpr
command will be used to print the plot. If you select destination File , the postscript output
will be saved in the file specified in the Filename entry field. If you do not specify a
directory, the current directory is used as default.
3.0 Implementation
pdplt is an event-driven program. After an initialization procedure, it sleeps and waits for user
input. The user input calls a procedure, and when that procedure is finished executing, the
program returns to sleep and waits for more user input.
The main task of pdplt is just to provide graphical user interface for the xtrac and error
programs. Both of them are called when necessary, by giving execution commands to the
operating system. The output from these programs is redirected to temporary files, which are read
(and deleted at exit) by pdplt. The file names of the temporary files can be changed, see section
2.4.2 for information on how to do that.
4.0 Hints for Maintenance and Further Development
4.1 On Tcl/Tk
pdplt was developed using Tcl 7.3 and Tk 3.6. Tcl stands for "Tool Command Language", and
Tk for "Toolkit", which is an extension to Tcl for writing graphical user interfaces. The language
is normally interpreted, although compilers are now available. To start the interpreter, type
wish -f sourcefile at the UNIX command prompt, where sourcefile is the Tcl/Tk script
you want to execute. To be able to run the script without first starting the interpreter, the first line
of the script should give the path to the interpreter, which is the case for pdplt, where it reads:
#!/usr/local/bin/wish
since this is the location of the interpreter on the GSFC workstations.
Since the language is interpreted it is fairly easy to port it to another platform, e.g., Windows
3.1/95/NT. Theoretically, all you would have to do is to install the Windows version of the
interpreter, and start the same script as you did in the UNIX environment. However, some things
must be changed, i.e. file names and operating system calls. Please refer to the Tcl/Tk for
Windows manual pages for further information on porting Tcl/Tk scripts to this platform.
One of the main features of the Tk extension to Tcl is the ability to bind commands to X (or
Windows) events. An X event is i.e. when the user moves the mouse, clicks the mouse buttons,
or presses a key on the keyboard. This makes it very convenient to write interactive programs
like pdplt. However, in pdplt, very few application-specific X event bindings are used. Most
Tk widgets created keep their default bindings as specified in the Tcl/Tk manual pages. The
application-specific bindings made can be found be searching for bind commands in the
source code.
4.2 On the source code of pdplt
The source code is divided into sections, each of them containing related Tcl/Tk procedures. This
is a short description of them.
4.2.1 The initialization section
This section is executed only once, at startup. Some of the Tk widgets section is also executed at
startup.
Since there is no #DEFINE statement in Tcl, pdplt starts with setting a number of global
variables. These are later made accessible in sub-procedures by use of the global command.
Those variables that are not trivial have comments in the source code, like Default
directory for log files etc.
4.2.2 The disk I/O section
This section contains procedures whose main task is to perform disk I/O, for example to:
Read the output of the error and xtrac programs.
Scan the input data for sources and build the Sources menu.
Create a new input file for the error program and execute error when necessary.
Save the current editing.
However, some procedures in the newfile and openfile sections also performs disk I/O. Those
sections are directly related to dialog boxes.
4.2.3 The plot section
This is the core part of the program. All mathematics required for calculating screen coordinates
for the plots is implemented in this section. Also, the procedures for toggling points
active/inactive are here. The parent plot procedure is named Replot, which calls a child
procedure, called pdplt, to do the actual work.
4.2.4 The newfile and openfile sections
These sections are directly related to the dialog boxes they are controlling. They are very similar.
The first procedure is the procedure called when the corresponding menu item is selected. It
creates the dialog box by calling a procedure in the Tk widgets section and does some
initializing. The second procedure is called when the user has clicked the OK button. It takes
care of opening the file selected, and running the xtrac and error external programs. There is
also a procedure for checking if the file name entered is valid, and finally, there is a procedure for
clearing the entry fields in the dialog box.
4.2.5 The print, preferences and sigma sections
These sections also control dialog boxes. They also contain the code that is executed when the
OK button of the corresponding dialog box is pressed.
4.2.6 The Tk widgets section
This section contains everything that has to do with creating the graphical user interface. Creating
the interface is a two-step procedure. First, the widgets (entry fields, labels, menus etc.) are
created and given a unique name. Then they are displayed on the screen, using the Tk pack
geometry manager.
Some of the code in the Tk widgets section is executed at startup. That is the code for creating
the main window, and completing the File and Edit pull-down menus. The widgets used
for dialog boxes are created when their menu item is selected, and destroyed when the OK or
Cancel button is pressed. Other menus are completed when a log file is opened, for example
the Sources menu.
Creating the menu widgets also includes specifying which commands that should be executed
when the menu items are selected. For example, the line:
.mbar.edit.menu add command -label "Reprocess" -command runError
tells the interpreter to run the procedure named runError when the user selects the
Reprocess menu item. To understand in which order the source code is executed, it is often a
good start to search for the add command statement and following the procedures called.
This can be a useful method for maintenance.
5.0 Installation
In order to work, pdplt requires the following installation procedure:
The Tcl/Tk interpreter wish must be installed. For information on how to do this, please read
the Tcl/Tk information available on the Wold Wide Web. For example, Yahoo has a page on
Tcl/Tk, from where software as well as documentation may be downloaded. Please note that
pdplt was developed using Tcl version 7.2 and Tk version 3.6. If you are installing the latest
version of Tcl/Tk (as of July 24, 1997, Tcl 7.6 and Tk 4.2), pdplt may require some conversion
to work. As long as the major version number (Tcl 7.x and Tk 3.x) is the same, the version is
backwards compatible. However, the upgrade to Tk version 4.x is not completely backwards
compatible.
The first line of pdplt must be changed to give the path to the interpreter. For example, on the
GSFC workstations, it reads #!/usr/local/bin/wish .
The error and xtrac programs of the Field System must be installed and in the search
path.
The UNIX grep and tail commands must be available and in the search path.
5.1 Licensing
This is the license statement for the Tcl/Tk interpreter:
"This software is copyrighted by the Regents of the University of California, Sun Microsystems,
Inc., and other parties. The following terms apply to all files associated with the software unless
explicitly disclaimed in individual files.
"The authors hereby grant permission to use, copy, modify, distribute, and license this software
and its documentation for any purpose, provided that existing copyright notices are retained in all
copies and that this notice is included verbatim in any distributions. No written agreement,
license, or royalty fee is required for any of the authorized uses. Modifications to this software
may be copyrighted by their authors and need not follow the licensing terms described here,
provided that the new terms are clearly indicated on the first page of each file where they apply.
"In no event shall the authors or distributors be liable to any party for direct, indirect, special
incidental, or consequential damages arising out of the use of this software, its documentation, or
any derivatives thereof, even if the authors have been advised of the possibility of such damage.
"The authors and distributors specifically disclaim any warranties, including, but not limited to,
the implied warranties of merchantability, fitness for a particular purpose, and non-infringement.
This software is provided on an "as is" basis, and the authors and distributors have no obligation
to provide maintenance, support, updates, enhancements, or modifications.
"Government use: If you are acquiring this software on behalf of the U.S. government, the
Government shall have only "Restricted Rights" in the software and related documentation as
defined in the Federal Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are
acquiring the software on behalf of the Department of Defense, the software shall be classified as
"Commercial Computer Software" and the Government shall have only "Restricted Rights" as
defined in the Clause 252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the
authors grant the U.S. Government and others acting in its behalf permission to use and distribute
the software in accordance with the terms specified in this license."
5.2 Troubleshooting
Problem: The log file cannot be opened. A Tcl error message shows up, ending with child
killed: segmentation violation .
Solution: You are trying to run xtrac with a control file that specifies a different antenna type
than the antenna type of the log file you are trying to open. You must change the antenna type in
the xtrac control file to agree with that of the log file. Please see the xtrac manual for
information on how to do this. You may temporarily change the path for the xtrac control file
by selecting the I/O setup menu item in the File menu, see section 2.4.2.
Problem: When starting pdplt, the interpreter bails out at the focus default .
command. The error message ends with should be: -displayof, -force or
-lastfor
Solution: You are trying to run pdplt on a later version of Tk than it was developed for. The
best solution is to install Tk 3.6. However, the focus default . command is not very
important and can be removed from the source code, by typing a # in front of it. The #
character is the Tcl/Tk remark character. However, if you continue to have problems with
pdplt, you should install Tk version 3.6 or contact tech support.
Problem: When reprocessing data, or at startup, the Tcl/Tk interpreter bailed out with a very
strange error message.
Solution: The xtrac or error program may have bailed out due to the nature of the data. In
that case, an error message would have been written to your standard output device. You should
save your editing, quit pdplt and read the error message generated by the external program.
Problem: The status bar reads WARNING: Check output file names in 'I/O
setup' after trying to open a file in xtrac format.
Solution: pdplt was unable to determine the proper file names for your data according to the FS naming conventions. You must set the file names manually in order to be able to save your editing. See section 2.4.2 for details.