HVI2 User's Guide

Michael F. Corcoran

Code 660.2
GSFC
Greenbelt MD 20771

Date: 3-22-95
updated:
	4-24-95
	5-16-95
	5-25-95
	6-01-95
	6-26-95
	7-18-95
	2-20-98
By: MFC

Last modified February 20, 1998

An image of the HVI2 gui interface (version 2.5.7) is here

An image of the current image display widget is here

New in HVI2.5.7

Drag on/Drag off buttons - These allow the user to flag sources within an entire region of the field by clicking and dragging. This is useful to set all the source flags for all sources within a large region of the field to the same value (for example if you want to set the "multiple detect" flag to True for all the sources in an SNR field).
To use the drag on/drag off buttons:
1. click on the DRAG ON button;
2. in the full field of view image, click the left mouse button and drag; a white rectangle is drawn
3. while holding the left mouse button, move the mouse until all the sources you wish to flag are within the white rectangle, then release the mouse button;
4. set the source flags you wish to apply to all the sources within the rectangle (for example, set m='T')
5. click the DRAG OFF button; the rectangle disappears, and the source flags for all the sources get set to the specified flags.
You no longer have to start screening in the $RRA directory, since the directory path to the HRI data is now specified by an IDL system variable, !RRADIR. You can set !RRADIR at the IDL> command line. You can also change the definition of !RRADIR in the $IDL_VI/startup/startup.pro file. For example if you always keep the HRI data for screening in /rra/hri/data, then edit the defsysv,"!rradir" line in the startup.pro file:
```
defsysv,'!rradir','/rra/hri/data/' ; rra working directory
```
Macintosh users (for eg, any dedicated screener who wants to screen data on a powerbook during an international flight) should note the following:
1. since there is no $PATH environment, work-arounds to specify the appropriate $IDL_PATH are placed in the startup.pro file.
2. the file in hvi2.5.7/utilities/wmenu.pro.mac should be renamed hvi2.5.7/utilities/wmenu.pro

Use of the hvi2 GUI for RRA source checking:

RDF fits files for HRI sources should be contained in subdirectories which have the seqid as the directory name. For a given dataset, the seqid is defined as
```
	rhXXXXXXYYY
	
	where XXXXXX = 6 digit ror number
		 YYY = 3 character suffix (eg. n00, a01, etc.)
```
Users should copy all the test sequence subdirectories to a test directory. In the following we assume that all the sequence subdirectories exist under the directory $RRA. Before starting the HRI checking gui, users should
```
		% cd $RRA 
```
and then start idl
```
% idl
```
(this assumes that all the necessary software paths are set). The hvi2 routine operates on the following files:
1. the qsrc.init file
2. a 512 x 512 gaussian smoothed image with 2" pixels
3. the 512 x 512 image with 5" pixels
Items (a), (b) and (c) must be created by running the idl routine "prehrra2". This routine can be run as a standalone, or can be automatically run by the hvi2 software if necessary. Since prehrra2 often takes a few minutes to run, it's generally better to run it standalone.
Workspace setup: Version of HVI2 after HVI2.5 automatically places the main gui at the bottom of the workstation screen and the image displays side-by-side at the top of the screen. It does this by reading 2 IDL system variables, !hvi2yoff (which controls the y offset of the main gui) and !idlimfxoff (which controls the x offset of the 5 arcsec/pixel window). To change the offset locations you should edit the following lines in the file $IDL_VI/hvi2.5/startup/startup.pro:
```
defsysv,'!hvi2yoff',520
defsysv,'!idlimfxoff',580
```
You should also have defined the environment variable $HVIVER as the name of the current version, for eg
```
% setenv HVIVER hvi2.5.7
```
and define the $IDL_STARTUP environment variable as
```
% setenv IDL_STARTUP $IDL_VI/$HVIVER/startup/startup
```
Preparation of a Sequence for screening: To prepare a sequence for screening run prehrra2 at the IDL> prompt. For example, to run prehrra2 on the dataset $RRA/rh123456n00 do the following
```
% cd $RRA
% idl
IDL> prehrra2,'rh123456n00/rh123456n00'
```
Note that if you try to screen a sequence for which prehrra2 has not been run, hvi2 will automatically run prehrra2 for you.
Once in idl, start the gui by typing hvi2 at the idl prompt:
```
IDL> checker='JDS'
IDL> cksite='SAO'
IDL> hvi2,checker=checker, cksite=cksite
```
or
```
IDL> hvi2,checker='MFC', cksite='GSFC' ; starts with checker = MFC and site=GSFC
```
IMPORTANT: Checkers should be consistent in use of ID and site name. These keywords are now REQUIRED (version 2.4.1 and subsequent versions). That is, the routine WILL NOT run if one or both are missing.
After starting hvi2 the main gui widget should pop up within a few seconds.

Color Table Specification: in hvi2.3, parameters were added to allow the user to select the default color table (and to allow the user to reverse the default color table). HVI2 can now be called with the keywords COLOR (which loads a pre-defined color table) and REV_CT (which allows the user the option of reversing the color table loaded).

COLOR is an integer which has the following values:

0-        B-W LINEAR   14-             STEPS   28-         Hardcandy
 1-        BLUE/WHITE   15-     STERN SPECIAL   29-            Nature
 2-   GRN-RED-BLU-WHT   16-              Haze   30-             Ocean
 3-   RED TEMPERATURE   17- Blue - Pastel - R   31-        Peppermint
 4- BLUE/GREEN/RED/YE   18-           Pastels   32-            Plasma
 5-      STD GAMMA-II   19- Hue Sat Lightness   33-          Blue-Red
 6-             PRISM   20- Hue Sat Lightness   34-           Rainbow
 7-        RED-PURPLE   21-   Hue Sat Value 1   35-        Blue Waves
 8- GREEN/WHITE LINEA   22-   Hue Sat Value 2   36-           Volcano
 9- GRN/WHT EXPONENTI   23- Purple-Red + Stri   37-             Waves
10-        GREEN-PINK   24-             Beach   38-         Rainbow18
11-          BLUE-RED   25-         Mac Style   39-   Rainbow + white
12-          16 LEVEL   26-             Eos A   40-   Rainbow + black
13-           RAINBOW   27-             Eos B   40-   Rainbow + black

REV_CT is a keyword which, if set (i.e. given a NON-ZERO value) will reverse the color table. For example

IDL> hvi2, checker=checker, cksite=cksite, color=0 ; will load the B-W LINEAR color table

IDL> hvi2, checker=checker, cksite=cksite, color=16, rev_ct = 1 ; loads the reverse Haze color table.

IDL> hvi2,checker='DEH', cksite='SAO', color=0, rev_ct=1

Press the "New Seq" button to read in a new sequence for RRA checking. Pressing "New Seq" will cause a small screen to appear which contains a list of all the available sequence subdirectories in the $RRA directory. Move the cursor to one sequence and click any mouse button.
HVI2 reads the log file (if any) and the source and field flag information from the *qsrc.fits file (or, if it doesn't exist, the *qsrc.init file). If neither the *qsrc.fits file nor the *qsrc.init file exists, HVI2 will spawn the routine "prehrra2" to create the qsrc.init file as well as the 2 arcsec/pixel image of the center of the field of view (and the gaussian smoothed version of this image). If no log file exists, hvi2 will create one (the log file is a simple ascii file which contains a list of commands, etc. given during source checking).
HVI2 will display the source and field flags in the appropriate button or text fields in the main gui, and will spawn an image display showing the full field of view (with 5"/pixel) and one showing the inner part of the field of view (at 2"/pixel, smoothed by a gaussian).
Using the controls on the bottom of the image displays, users can
```
load a color table - press XLOADCT
zoom on the image - press ZOOM
change the image cutoff pixel value - type an integer value 
			in the CUT field
change the boxcar smoothing employed - type an integer value > 2 
			in the smo field
or kill the image display - press QUIT (not useful 
			during RRA checking however)
```
The name of the checker and the site at which the checking is being conducted should be put in the appropriate boxes on the main GUI. IMPORTANT: THAT YOU NEED TO ENTER A CARRIAGE RETURN (< CR >) in the EDITABLE FIELDS IN ORDER FOR THE VALUE TO BE READ BY THE GUI.
Unique sources with S/N above 4 are overplotted on the image displays. The current source is marked by a double box in the 5"/pixel window and labelled with it's SDS_NUM in each window. The RRA checker should scan each image for sources which have not been flagged and for other problem sources. Users can set the color of the source plotting symbol by pressing the "SRC colors" button and adjusting the sliders. The current color table used. To load a new color table press the XLOADCT button on one of the image displays. (IDL only accesses one color table at a time, by the way). After the colors have been set to the user's liking press the "DONE" button at the bottom of the slider widget, then press the "Plot Src" button on the main GUI to replot the sources using the new symbol colors.
Source and field flag buttons can be set by pressing, and they spawn the appropriate subordinate flags. If necessary, subordinate source and field flags can be set by typing a "T "or "F" in the appropriate flag field. Again, NOTE THAT YOU NEED TO ENTER A CARRIAGE RETURN (< CR >) in the EDITABLE FIELDS IN ORDER FOR THE VALUE TO BE READ BY THE GUI.
the checker can switch sources by moving the mouse into one of the image display windows and clicking the LEFT button. The source nearest the cursor is selected and its flag settings displayed in the main gui.
The checker can flag missed sources by pressing the "Missed SRC" button on the main gui. Missed sources can be flagged by moving the cursor to the location of the missed source in the 5"/pixel or the 2"/pixel image window and clicking a button. The buttons have the following actions:
```
left:	add a missed source
middle:	remove missed source from the missed source list
right:	end missed source selection.
```
NOTE THAT MISSED SOURCE SELECTION WORKS IN EITHER THE 5"/PIXEL IMAGE DISPLAY OR THE 2"/PIXEL IMAGE DISPLAY
After the checker is satisfied, the results can be saved by pressing the "SAVE" button on the gui.
At any time the checker can quit by presing the "QUIT" button. Before quitting the user is asked if the current results should be saved.
The RESET button on the main GUI re-sets the source flag values to the values they had at the start of the sequence checking.
the checker can press the "New Seq" button to load a new sequence. Before the new sequence is loaded the checker is asked if the current results should be saved.
Source comments (12 characters max) can be stored in the "Src Comment" field. Remember to press < CR > after completion of the comment to record the comment!
One field comment can be added to the "Field Comment" field. When a sequence is saved a single comment is saved in the header of the 1st extension of the qsrc file. Note that new comments get prepended ahead of old comments. Also, old field comments are not displayed when a new sequence is selected for checking.

Useful Tips:

Keep the window you started idl in open. IDL will display diagnostic messages to this window. If you see an error message, you can try the following steps to recover:
```
% ERROR - (bad thing happened)
```
you type
```
IDL> retall
IDL> xmanager
```
Generally at this point, if xmanager starts successfully and you're back in the GUI, you should press the "QUIT" button and notify Mike.
if you think something's hung, control-C (^C) usually works to halt the current routine. If you halt the current routine and want to restart it, type
```
IDL> .con
```
at the IDL prompt.
It seems to be a good idea to load a color table via XLOADCT immediately after the sequence is loaded. Lowering the "Gamma" in xloadct is useful to bring up the background.
usually the cursor takes an hourglass shape when over a widget if its processing an event and not expecting user input. There are times when an event is being processed but the cursor does not have the hourglass shape, however, so beware.
with hvi2.4 you should be able to fit the main gui (with flag buttons) and the 2 image displays on the monitor so important parts of each can be seen simultaneously. Put the main gui at the bottom of your screen and place the image displays above it. This works with the screens at GSFC.
If at any time a checker wishes to make a gif image of an image display, the user should press the "Make Gif" button under the "Tools" menu on the image display widgets. The gif image idlim.gif will be written to the sequence directory.

Known Bugs

After you quit ZOOMing an image, the sources are replotted, and they are replotted a number of times equal to the number of times the LEFT mouse was clicked in the image window during the ZOOM. This is because the event manager doesn't know how to handle the events generated when you click in the image display when zooming. This has the result that if you click the LEFT mouse button in the image display while zooming (as you might to zoom on another source for example), after you quit ZOOM the event handler will replot the sources to the image displays, and the number of times it replots is equal to the number of clicks of the LEFT mouse button in the image display.
BUG EXTERMINATED: in hvi2.3
The color table cannot be adjusted in the ZOOMED window. You should adjust the color table before ZOOMing.
hvi2 (actually pickseq.pro) will fall over if your rra working directory only contains 1 data sequence directory. BUG EXTERMINATED: in hvi2.4
pos_susp button can't be turned on manually. BUG EXTERMINATED: in hvi2.3
(a) flag can't be changed manually BUG EXTERMINATED: in hvi2.3
cannot check sequences with no sources found BUG EXTERMINATED: in hvi2.4
display of smooth=0 image doesn't work if smooth initially set to non-zero value. BUG EXTERMINATED: hvi2.4.1
display of image with cut<5 doesn't work BUG EXTERMINATED: hvi2.4.1

Enhancements

reserve colors for plotting symbols DONE: HVI2.3
separate zoom window widget DONE: NEW ZOOM HANDLER IN HVI2.3 makes this unnecessary
plot all sources for missed source event, or perhaps have a PLOT SOURCE (ALL) (DEFAULT) or (NONE) menu. DONE: hvi2.3
allow display of NOT_CHECKED = True sources Done: hvi2.4.1
Allow flagging of entire region in field. Done hvi2.5.7

RUNNING PREHRRA2 AUTOMATICALLY

From rsdc_rra_relay@head-cfa.harvard.edu Wed May  3 11:30:11 1995
Date: Wed, 3 May 1995 11:29:51 -0400
From: Mike Corcoran 
To: rsdc_rra@head-cfa.harvard.edu
Subject: scripts for running prehrra2 automatically
Cc: corcoran@barnegat.gsfc.nasa.gov
Content-Length: 1796

Hi RRAders,

I've written scripts which will, given a list of sequence id's for HRI
data to be visually inspected,  allow you to automatically generate the
files you need for HRI rra visual inspection.  The scripts are in

	rosat/data/qsrc/software/scripts

on legacy.  There are presently 2 files, auto_prep.pro (an IDL script)
and prephri.csh (a c-shell script).  You should download these files to
the directory $IDL_VI/scripts. Make sure that before running them
$IDL_VI appears as the first entry in your $IDL_PATH.

These scripts assume that you've copied HRI data for RRA checking to a
directory $RRA_DIR.  $RRA_DIR is defined in the first line of
prephri.csh - currently it's set correctly for the test data directory
at GSFC, so you should modify it for your individual site.

The HRI data for checking should be contained in subdirectories which
are named with the sequence id.  For example for GSFC currently we have
the following definition for $RRA_DIR

rosserv[corcoran]-82: printenv RRA_DIR
/scratch/corcoran/rra

with 2 test datasets available:

rosserv[corcoran]-84: ls -d1 $RRA_DIR/rh*
/scratch/corcoran/rra/rh150020n00
/scratch/corcoran/rra/rh150024n00

The scripts require that the new data directories are written to the
file $RRA_DIR/NEWDATA.LIST.  For example

rosserv[corcoran]-85: cd $RRA_DIR
rosserv[corcoran]-88: ls -d rh* > NEWDATA.LIST
rosserv[corcoran]-89: more NEWDATA.LIST
rh150020n00
rh150024n00

(The entries in NEWDATA.LIST should ONLY contain the sequence id's of
the data which needs to be converted.)

Then to begin the automatic HRI RRA product generation, 

% cd $IDL_VI/scripts
% source prephri.csh

and that should do it.