HVI2 users guide


Date: 3-22-95
updated:
	4-24-95
	5-16-95
	5-25-95
	6-01-95
	6-26-95
	7-18-95
	10-20-95
By: MFC
An image of the HVI2 gui interface (version 2.5) is here

An image of the current image display widget is here

Contents:

  1. Setup
  2. Starting the HRI screening Widget
  3. Display of Detections on Images
  4. Setting Flags
  5. Useful Tips
  6. Status of Known Bugs
  7. Enhancements
  8. Running prehrra2 automatically

Setting Up the Workspace

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.

Placement of Widgets on the workstation screen

Versions hvi2.5 and later automatically place 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 $IDL_STARTUP as 
% setenv IDL_STARTUP $IDL_VI/hvi2.5.4/startup/startup

Starting the HRI Screening Widget

Preparing HRI data for screening

The hvi2 routine operates on the following files: These files 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. To run prehrra2 for a given sequence, type 
	prehrra2,'<seqid>/<seqid>'
at the IDL> prompt. For example, to run prehrra2 on the dataset $RRA/rh123456n00, type 
IDL> prehrra2,'rh123456n00/rh123456n00'
(assuming you are currently in the $RRA directory). Before starting the HRI checking gui, users should cd to $RRA and then start idl: 
% cd $RRA
% idl
(this assumes that all the necessary software paths are set). 1) Once in idl, start the gui by typing hvi2 at the idl prompt: IDL> hvi2,checker=checker, cksite=cksite the main gui widget should pop up within a few seconds. Note: 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=cksitecolor=0 ; will load the B-W LINEAR color table
or 
IDL> hvi2, checker=checker, cksite=cksitecolor=16, rev_ct = 1 ; loads the reverse Haze color table.
In Version hvi2.4 and later parameters were added to HVI2 to allow input of the checker id and checksite at hvi2 startup. For example 
IDL> hvi2,checker='MFC', cksite='GSFC' ; starts with checker = MFC and site=GSFC
IDL> hvi2,checker='DEH', cksite='CFA', color=0, rev_ct=1
checkers should be consistent in use of ID and site name. These keywords are REQUIRED (version 2.4.1 and subsequent versions). That is, the routine WILL NOT run if one or both are missing.

Loading a New Sequence for Screening

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

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 (if not entered on the command line at hvi2 startup). 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.

Display of Detections on the Images

Unique sources with S/N above 4 are overplotted on the image displays. The current source is labelled with its SDS_NUM in each window. The RRA checker should scan each image for sources which have not been flagged and for other problem sources. Sources are colored according to the following scheme: Checkers can change the selection of sources to be plotted on the images by clicking on the Plot Src button and choosing one of the following selections: Note: Certain actions (like changing the cutoff or smoothing of an image) may cause the displayed sources to DISAPPEAR. Users can re-display the sources by choosing one of the selections under the PLOT SRC menu.

In rare instances, one may see a larger (cyan) box which includes a smaller (cyan or green) box. This can occur when there are more than one detection (for the same size, small box) inside the large detection and one of these has a s/n < 4. Since large detection cells occasionally are matched with more than one smaller cell detection, the larger box becomes 'significant' for the algorithm that selects colors for display by virtue of the smaller detection with the low s/n. Since the 'u' flag will be set, there is no problem insofar as the flags are concerned, it is only a small 'imperfection' in the display for the VI operator.

Setting Flags

Flagging Detections

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.

RESETting: 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. This can be done for the Current Source or for all the sources.

Field Flagging

Field flagging can be done at any time during the screening process by clicking on the Field Flag buttons and/or typing a T or F in the editable flag fields.

Comments

Source comments (12 characters max) can be stored in the "Src Comment" field.

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.

Remember to press <CR> after completion of the comment to record the comment!

Missed Sources

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: MISSED SOURCE SELECTION WORKS IN EITHER THE 5"/PIXEL IMAGE DISPLAY OR THE 2"/PIXEL IMAGE DISPLAY

Finishing Up

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 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.

USEFUL TIPS:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. with hvi2.4 and later versions 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.

  6. 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.

  7. A note about the MULTIPLE_DETECT (m) source flag: sources which receive an "m" flag automatically receive the "f" flag as well. If you want to remove the "m" flag from a source, you should "RESET CURRENT" then re-do flagging for this source.

  8. A note about the ASP_SUSP (A) and DEFERRED (D) field flags. Choosing the "A" flag means that all sources for that sequence have the "i", "p" and "v" source flags set to TRUE. Similarly, choosing the "D" flag means that all sources have the "n" flag set to "TRUE". To undo the "D" or "A" flag, turn the appropriate field flag button OFF, then "RESET ALL"

Status of KNOWN BUGS

  1. 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

  2. The color table cannot be adjusted in the ZOOMED window. You should adjust the color table before ZOOMing.
  3. hvi2 (actually pickseq.pro) will fall over if your rra working directory only contains 1 data sequence directory.

    BUG EXTERMINATED: in hvi2.4

  4. pos_susp button can't be turned on manually.

    BUG EXTERMINATED: in hvi2.3

  5. (a) flag can't be changed manually

    BUG EXTERMINATED: in hvi2.3

  6. cannot check sequences with no sources found

    BUG EXTERMINATED: in hvi2.4

  7. display of smooth=0 image doesn't work if smooth initially set to non-zero value

    BUG EXTERMINATED: hvi2.4.1

  8. display of image with cut<5 doesn't work

    BUG EXTERMINATED: hvi2.4.1

ENHANCEMENTS

  1. reserve colors for plotting symbols

    DONE: HVI2.3

  2. separate zoom window widget

    DONE: NEW ZOOM HANDLER IN HVI2.3 makes this unnecessary

  3. plot all sources for missed source event, or perhaps have a PLOT SOURCE (ALL) (DEFAULT) or (NONE) menu.

    DONE: hvi2.3

  4. allow display of NOT_CHECKED = True sources

    Done: hvi2.4.1

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.