obsvis

ObsVis is a tool written in Tcl/Tk to aid in observation planning, 
allowing the inspection of sky images with overlaid instrument
fields-of-view (FoV). The tool allows for the manipulation of the FoVs
in a variety of ways: adjusting the spacecraft roll angle, adjusting
the target X, Y and detector SIM-Z offsets, configuring instruments
(ACIS,HRC), configuring gratings, selecting ACIS chips, ACIS
subarrays, exposure modes and CCD node boundaries, and HRC-S timing
mode.  ObsVis allows for grouping of FoVs together using three
different grouping modes: Grids, Compound and Synchronized. FoV
information can be saved and loaded to/from a file as well as printed
to a printer. ObsVis relies on SAOImage ds9, an astronomical imaging
and data visualization application, to display and manipulate FoVs.
ObsVis does not restrict any of ds9's functionality but extends it to
allow for versatile and consistent manipulation of FoVs.

When ObsVis starts up, it brings up a main window to display
information about different possible configurations of the FoVs, as
well as a ds9 window for displaying sky images. As the user creates
a new FoV in the main window, the  specified FoV configuration is
overlaid on the sky image in ds9. The FoV can then be manipulated 
either from the ObsVis display window or by interacting with ds9
directly. 

The ObsVis manual is available at

   https://cxc.harvard.edu/soft/obsvis/OBSVISReference.html

Additional information about ObsVis is available at 

   https://cxc.harvard.edu/obsvis


Additional information about ds9 is available at

   http://hea-www.harvard.edu/RD/ds9

  File
  ----

   Open 
	displays dialog box to open saved FoVs from an ASCII file.
	User can select which FoV in a file to load.
	Selected FoVs from a file are loaded to current frame in ds9 if one
	exists, otherwise a new one is created  and image is loaded 
	using target coordinates of the first loaded FoV.
	     	 

   Save 
	displays dialog box to save FoVs into an ASCII file.  User can 
	select which FoVs to save.  All image information is lost
	when saving FoVs.

   Print 
	 prints all FoVs to default printer

   Exit
	exits application, closing both the ObsVis and ds9 windows.

  Edit
  ----

   Copy

	Depending on current focus, either copies FoV data, copies
	ACIS window data, or cuts text.


   Cut
	Depending on current focus, either deletes FoV, deletes ACIS
	window or cuts text and puts the deleted data into clipboard.
	

   Paste

	If the content of the clipboard is FoV and FoV table is currently in
	focus, it attempts to add a new FoV.
	If the content of the clipboard is ACIS window and window table is
	currently in focus, it attempts to add a new ACIS window.
	If the content of the clipboard is text and text field is in focus
	it pastes the text into the field.  Otherwise nothing happens.

   Preferences
      
	Opens a dialog box with all the preferences that a user can set
	for the ObsVis application.  See the Section 'Preferences' for a
	more detailed description.
	


  Adjust-FoV
  ----------

   Move

	Selects and brings to front the current ds9 FoV target
	marker.  User can then drag that marker with mouse to move FoV or a
	group. 

   Roll

	Selects and brings to front the current ds9 FoV target
	marker. User can then rotate that marker using Shift Key with
	mouse button to rotate FoV. 

   OffsetYZ

	Brings to front and selects optical axis marker in ds9 for
	current FoV. User can then drag that marker to modify FoV's Y
	and Z offsets. 

   OffsetSimZ

	Selects and brings to front the current ds9 FoV nominal
	aimpoint marker.  User can then drag that marker with the mouse to
	modify FoV's SimZ offset. 


   Rotate Group
   
	Brings to front and selects group center marker for current
	FoV in ds9. By pressing the Shift Key, the user can then drag
	or rotate that marker with the mouse. For Compound groups,
	dragging the group center only changes the group center position,
	while for Grids the whole group is translated.  Rotation of
	the marker rotates all the members of the group around the group
	center.

   Calibrate

	Retrieves copy of calibration file from Smithsonian archive
	and automatically updates user's local copy if necessary.


   Image Auto Reload

	Sets user preference for auto reloading of images.  Auto image
	reloading would occur when the user presses 'Apply Changes' button
	and :
		there is one FoV in the current frame and the FoV's
		target point is positioned farther away from the image
		center than specified in Preferences,
		       
		        or 

		there is one grid group in the current frame and the
		grid's center is positioned farther from the image
		center than specified in Preferences.
		  
	Image Auto Reload must be toggled off if you wish to use 
	a custom image of your own, or an image from anything other
	than the Image Display/Survey option selected in Preferences.

	
  Layout 
  ------

   


Show Fov Id 
    Controls whether the ObsVis GUI should display the frame that allows
        the user to input a custom id for the FoV. 

Show Instrument Detail
    Controls whether the ObsVis GUI displays the frame containing the
        instrument details area which allows the user to view/modify 
        settings specific to the selected instrument.


Show Fov Table
    Controls whether the ObsVis GUI displays the FoV table which provides
        a summary of all generated FoVs.

  Help
  ----

   


Reference Manual
    Invokes a window to display the ObsVis reference manual.


About
    Invokes a window to display version information for ObsVis.

Acknowledgements
   Invokes a window to display acknowledgement information.

POSITION PARAMETERS
-------------------

FoVId 
   Allows assigning an ID to a generated FoV.  If left empty, ObsVis
   automatically generates the ID.  FoV ID is used to access any
   information about an FoV so it must be unique.


Target Name

   FoV can have a target name assigned. Inputting a Target Name will
   erase any previous Target Coordinate input.  When a new FoV is generated,
   ObsVis contacts SIMBAD to obtain sky coordinates for the named object.
   If the user wishes to then modify Target Coordinates and generate a
   new FoV, the Target Name field should be erased.

Target Coordinates

   Target coordinates (equatorial J2000) of FoV. The coordinates can
   be specified in a number of formats.  Target coordinates should be
   specified as right ascension and declination. Both RA and Dec can
   be specified in sexagesimal format (hours/minutes/seconds for RA,
   degrees/arcminutes/arcseconds for Dec) using either spaces or
   colons (:) as separators, or in decimal degrees.  In addition, RA
   can be specified in decimal hours by appending either "H" or "h"
   (do not type the double quotes) to the decimal value. If the RA is
   specified in sexagesimal format then the Dec value must be
   separated from the RA value by a comma or a plus or minus sign, or
   the degree (or decimal degree) part of the Dec must have a "D" or
   "d" appended to it, or all three hours/minutes/seconds values must
   be included. In all other cases, trailing zero values for
   minutes/seconds (RA) or arcminutes/ arcseconds (Dec) may be
   dropped. Extra whitespace is always ignored.

   Examples:
   String entered 	Translation
   -------------- 	-----------
   23 59 59.9999 -89 59 59.999 	23 59 59.9999 -89 59 59.999
   23:59:59.9999 -89:59:59.999 	23 59 59.9999 -89 59 59.999
   23.7654, +0.6857 	01 35 03.6960 +00 41 08.520
   09h 16m 54.28s 32d 15' 6.1" 	09 16 54.2800 +32 15 06.100
   10.9876h, +14 	10 59 15.3600 +14 00 00.000
   0, 0 	00 00 00.0000 +00 00 00.000
   14 12, 16 10 	14 12 00.0000 +16 10 00.000
   14 12 +16 10 	14 12 00.0000 +16 10 00.000
   14 12 16d 10 	14 12 00.0000 +16 10 00.000
   14 12 16 10 --- AMBIGUOUS will be treated as 14 12 16.0000 +10 00 00.000 

Roll
   
   Roll of FoV in degrees.  Roll is measured positive, West of North. 

Offset-Y

   Offset Y in arcmin of target position on the detector.

Offset-Z

   Offset Z in arcmin of target position on the detector.

Offset-SimZ(arcmin)

   Offset SimZ in arcmin, obtained by movement of the Science
   Instrument Module (SIM).  If this field is modified with a value
   then Offset-SimZ(mm) will display that value converted to mm.

Offset-SimZ(mm)

   Offset SimZ in mm, obtained by movement of the Science 
   Instrument Module (SIM).  If this field is modified with a value then
   Offset-SimZ(arcmin) will display that value converted to arcmin.



INSTRUMENT
----------

Currently the following instrument selections are available:
     - ACIS-I
     - ACIS-S
     - HRC-I
     - HRC-S

DISPLAY PARAMETERS
------------------

The toggle options in the Display Parameters frame allow the user to
show or hide the target, nominal aimpoint, and optical axis markers on
the FOV in the DS9 display. The initial settings of the markers upon
start-up of the GUI can be specified in the Edit->Preferences->Display
Parameters menu item. 

GRATING SPECTRA
---------------

Supported grating selections are NONE, HETG and LETG.


FOV GROUPING
------------

Grouping allows creation and editing of groups of FoVs that are
bound using predefined constraints.  Currently ObsVis supports
the following choices for grouping: None, Grid, Compound,
Synchronized.  Details are listed below.
   

NONE
----

FoV is not in any group.  Any modifications to this FoV will
not affect any other FoV.

Grid
----

Desired FoV is a regular grid.  Changes to Grouping to Grid and its
moving a member affect the whole grid. 

The following parameters can be entered for grids:

    Group ID 
     
        Used to specify ID of group. ObsVis fills in group attributes if
	a group with specified ID already exits.

    Grid Center 

	J2000 sky coordinates of grid center. Grid center coordinates
	will be defined as the middle of outer grid boundaries for
	any (horizontal or vertical) dimension with an even number
	of pointings, or as the aimpoint of the central FoV for an
	odd number of pointings.

    Grid Angle

	 Angle of entire grid in degrees, measured positive East
	 of North (opposite to spacecraft roll).

    Num Horiz Pointings 

	Horizontal size of grid, expressed as the number of FoVs.

    Num Vert Pointings 

	Vertical size of grid, expressed as the number of FoVs.

    Horiz Spacing 

	Horizontal spacing of grid in arcmin between adjacent FoV aimpoints.
	  
    Vert Spacing

        Vertical spacing of grid in arcmin between adjacent FoV aimpoints.

    FOV X Index 

	X position of FoV in grid.  FoVs index from zero.

    FOV Y Index 

        Y position of FoV in grid.  FoVs index from zero.

    FOV Angle in Grid 

 	Angle of individual selected FoV relative to grid's axis in
	degrees, measured  positive East of North (opposite to
	spacecraft roll). 

    Synchronize params of group members

	Option to force mirroring of FoV's attributes in all group
	members.

    Show detail 

	 Option to show details of which FoV parameters are synchronized.



Compound
--------

FoV is in an irregular group.  Changes to group and group members
might affect the whole grid depending on operation and options selected.


The following parameters can be entered for compound groups:

    Group ID 
     
        Used to specify the ID of a group. ObsVis fills in group attributes if
	a group with specified ID already exits.

    Group Center 

	 J2000 sky coordinates of grid center. Grid center coordinates
	 will be defined as the middle of outer grid boundaries for
	 any (horizontal or vertical) dimension with an even number
	 of pointings, or as the aimpoint of the central FoV for an
	 odd number of pointings.

    Group Angle

	 Angle of entire grid in degrees, measured positive East
	 of North (opposite to spacecraft roll).


    Synchronize params of group members

	Option to force mirroring of FoV's attributes in all group members.

    Show detail 

	 Option to show details of which FoV parameters are
	 synchronized.


Synchronized
------------

Members of one synchronized group must be located in separate
frames in ds9.  Changes to one member are mirrored in all other
members based on options selected.
   


The following parameters can be entered for grids:

    Group id 
     
     Is used to specify the ID of a group. ObsVis fills in group
	attributes if a group with specified ID already exits.

    Synchronize params of group members

	Option to force mirroring of FoV's attributes in all group members.

    Show detail 

	 Option to show details of which FoV parameters are synchronized.


Synchronization Details
-----------------------


The following parameters can be selected for synchronization in groups:
    - Roll
    - Offset-Y
    - Offset-Z
    - Offset-SimZ
    - Grating
    - Instrument
    - Unselected Chips
    - Chips
    - Subarrays
    - Exposure Mode
    - Node Boundaries
    - Windows
    - Chip Boundary
    - Timing Mode

 ACIS INSTRUMENT DETAILS
 -----------------------

  ACIS Chips
  -----------

  Individual Chips (CCDs) can be selected to be displayed in the
 FoV. Calibration data specifies the maximum number of chips that may be
 used, in terms of chips which are on/selected and chips which are
 optional. The calibration 'maxselectchips' value specifies the
 maximum number of chips which may be turned on for a given FoV.
 In addition, the user may specify optional chips, up to a total of 
 'maxenabledchips' selected and optional chips. If any optional chips 
 are specified they are displayed in a different color. Unlike unselected
 chips, optional chips can not be hidden when specified.

 By default, on/selected chips display in green in the FoV in the ds9
 window; optional chips display in yellow in a dotted line style; and
 unselected chips display in blue if the user selects the 'Unselected'
 chips option. These selected/optional/unselected chip colors may be 
 adjusted using the Edit->Preferences->Region Colors menu item, In 
 addition, the appearance of the dotted and dash lines may be adjusted
 using the Edit->Preferences->Line Types option.
 
 The default ACIS chip selections are instrument and gratings dependent. 
 Whenever changes are made to either the 'Instrument' field or the 
 'Gratings Spectra' field (both on which are located on the left side
 of the GUI), the default ACIS chip selections are updated to match the
 values specified in the user's preferences (or $HOME/.obsvisrc file if
 it exists). 

  SUBARRAYS
  ---------

      Supported subarrays settings :

         None 

            No subarrays selected

         1/2 
                          ACIS-I   ACIS-S
            Start row      513       257
            Number of rows 512       512

         1/4

                          ACIS-I   ACIS-S
            Start row      769       385
            Number of rows 256       256


         1/8
		          ACIS-I   ACIS-S
            Start row      897       449
            Number of rows 128       128

         Custom

	     Start row - set by user	     
             Number of Rows - set by user 



  EXPOSURE MODE
  -------------

  Depending on exposure mode and FoV instrument configuration these
  options modify default offsets for FoV.


   TE 
      Generate FoV in TE exposure mode

   CC
      Generate FoV In CC exposure mode



  NODE BOUNDARIES
  ---------------

  This selection generates node boundaries on selected chips in FoV layout.



  UNSELECTED CHIPS
  ----------------

  This selection generates unselected chip FoVs in layout using dashed
  lines, in addition to selected chips in layout of FoV.


  WINDOWS
  -------

  Users can add up to 6 windows per ACIS chip and 36 windows in total per 
  pointing. The table displays details on created windows.  Appearance of
  the table is configurable via Preferences.  Clicking on the heading of
  a column sorts the table using that column's values as keys. The order
  of sorting alternates between ascending and descending with each
  click. 


  HRC-I INSTRUMENT DETAIL
  -----------------------

  CHIP BOUNDARY
  -------------

  Generate HRC-I layout with chip boundaries



  HRC-S INSTRUMENT DETAIL
  -----------------------

  CHIP BOUNDARY
  -------------

  Generate HRC-S layout with chip boundaries


  TIMING MODE
  -----------

  Generate HRC-S layout in timing mode 

  Apply Changes

      Applies changes from input fields into current FoV and/or group.
      This button is highlighted in yellow when an FoV is selected in the
      FoV table and (1) any entry in the ObsVis window is modified or 
      (2) 'Image Auto-Reload' is set and image in ds9 needs to be
      reloaded. 
                
  Clear Input

      Clears all input fields and resets selections to default
      preferences as set in Preferences.

  New FoV 

      Attempts to generate a new FoV using data from input fields in
      the ObsVis window.    

  New FoV Grid

      If 'FoV Grouping' is set to grid in the input area, new FoV Grid
      attempts to generate a grid of pointings with specified parameters.  
      Otherwise a dialog box is displayed so that the user can specify
      grid parameters.

  Delete FoV
       
       Deletes currently selected FoV.

  Delete Group

       Deletes all FoVs from a group that contains the currently
       selected FoV. 

  Delete All

       Deletes all FoVs

FoV layout consists of the following elements :

    - instrument outline (default blue)
    - grating (default red)
    - target point (default red)
    - optical axis point (default blue)
    - nominal aimpoint (default green)

Colors for any of these elements can be customized via Preferences.
Instrument layout is determined by user input in the ObsVis window.
Target point size is adjusted to match the default dither pattern
sized for the selected instrument.

   - drag target point (red) or any other part of the FoV
      moves the whole instrument modifying target coordinates

   - drag optical axis point (blue) modifies offsetY and offsetZ

   - drag nominal axis point (green) modifies offsetSimZ

   - drag group center point (yellow) valid for Grids and Compound
      groups.  It modifies location of Grid/Group center.  For Grids
      the whole grid is moved and angle of FoV in grid is maintained
      which might result in changes to rolls of FoVs.  For Compound 
      groups only group center  coordinates are modified

   - rotate the roll angle of the FoV by holding the mouse over one of
     the corners of the target point, FoV or grating and dragging
     while holding down the shift key 

   - rotate the grid/group members around a point by holding the mouse
     over one of the corners of the grid/group center point, and
     dragging while holding down the shift key.  For Grids, each FoV's
     angle within in the grid is maintained, which might result in
     changes to rolls of FoVs.  For Compound groups, no parameter is
     modified during group rotation.

   (Dragging is accomplished by holding down the left mouse button 
    over the desired point of interest and moving the mouse).

Groups are moved as a single unit. Dragging one FoV in ds9 will 
move the entire group. Rotating groups can be accomplished the same
way as rotating single FoV's; however, instead of selecting the FoV
target point, the group center point (yellow) should be selected. 

Groups are created implicitly by selecting grouping type and assigning
ID in the "Group ID" entry field.  Group members' attributes can be
independently manipulated within the constraints of group.  Group
members can be added and removed from a group and moved between
groups.   


Three types of grouping are supported: 'Grid', 'Compound' and 'Synchronized'.

Grid

   Members can occupy specified spots in the rectangular grid and have
   a specified angle relative to the grid axis, which determines their
   target coordinates and roll angles.  Moving one group member or
   grid center moves the whole grid.  Rotating the group center
   rotates all members while maintaining each FoV position and angle
   relative to grid axis constant.  This results in modification to
   each FoV's target coordinates and roll angle.  If 'Members
   Synchronization' parameters are selected, changes to one group
   member are mirrored by all other group members.  If "Image Auto
   Reload" preference is set, the grid center coordinates are used to
   determine if an new image must be retrieved and loaded.  Grids can
   be sparse, i.e., not all the spots have to be filled.  That also
   allows for moving of members within the group by changing X,Y
   parameters of FoV.  Only single FoV can occupy a given X,Y spot in
   grid.  Grids can be reconfigured and resized.  When resizing a grid
   to be smaller, extra members are deleted, and larger empty slots
   are created.  When resizing grid to be smaller the modification has
   to be performed through a member that is not going to be deleted
   when the grid is reduced, so the user must select an FoV with X,Y
   grid indexes that are within legal limits for new resized grid.

   Note that for grids with a large number of pointings, an image
   larger than the default image server maximum of 1 degree may be
   required.  As one option, in ds9, you can select
   Analysis/Archives/SkyView, specify the image size in both degrees
   and pixels.  Retrieve/save a FITS image in your desired bandpass,
   then deselect Image-Auto-Reload in the Adjust-FoV pulldown, and
   load the wider image into ds9.  


Compound

   Members of Compound group are bound in an irregular fashion.
   Locations within the group are remembered when each FoV is first
   added into a group.  Relative positions of all members are
   maintained in Compound groups.  Any change to the position of a
   group member is mirrored by the same delta changes (in image
   coordinates) to all other members and the group center.  Moving the
   group center affects only the point of group rotation, not individual
   FoVs in the group.  When a compound group s created, the center of
   the group is calculated. When rotating groups, the rotation is
   about this point.  The point is displayed in ds9 and can be moved
   by simply selecting it (clicking the left button on the mouse while
   over the marker) and dragging the mouse while button is still
   pressed.


Synchronized

   Synchronized grouping is intended for grouping FoVs in different
   frames. It allows synchronization of position and other
   synchronization parameters (selectable) to be mirrored in all group
   members across different ds9 frames.  Each member of this group must
   occupy a different FoV frame.

Preferences can be modified through the Preferences sub-menu under the
Edit menu entry.  The following groups of preferences are supported:

Calibration

	options for retrieval of calibration data

ACIS Labels

        options for ACIS windows labels

FoV Defaults

	default values for FoV input fields in the ObsVis window

ACIS-I Details

        defaults for ACIS-I instrument settings

ACIS-S Details

        defaults for ACIS-S instrument settings

HRC Details

	defaults for HRC instrument settings

GUI Params

	defaults for ObsVis window appearance

Grid Params

	defaults for grid parameters

Region Colors

       defaults for colors of FoV components in ds9

Image Display

       defaults for auto loading of images

Line Types

       defaults for line types in ds9

Display Parameters
        
       default settings for displaying/hiding target, nominal aimpoint, and 
       optical axis markers on the FoV 


ObsVis stores user preferences in user's home directory ($HOME/.obsvisrc).
 

When ObsVis searches for ds9, it first tries to find it using the PATH
variable. If this fails, it attempts to find ds9 in the ObsVis package
installation. This version of ObsVis requires ds9 v7.0 or newer.
ObsVis performs ds9 version check whenever it is started. 

ObsVis accepts the following command line options:

 any ds9 command line option 
	 such options are passed to ds9 when ds9 is initiated

 --help 
	prints the help info on standard output

 -v    
       prints the version of ObsVis

 -imager imager_path

       uses imager_path as imager, this option allows
	    overriding of environment settings for ds9 location
	    and name.

 

   1. Leading zeros should not be used when entering parameter values
      (other than target coordinates) since they will be interpreted
      as octal values by the parser. Thus "09" for example will result
      in an error.

   2. Loading FoV groups from a saved FoV file does not center them on
      the image.

   3. Saving FoVs that are displayed in different frames does not keep
      frame information. Therefore, FoVs reloaded from a single saved
      FoV file are always put into the current ds9 frame.

   4. If ds9 is minimized, then creating a new FoV causes the "Apply
      Changes" button to light up. If the "Apply Changes" button is
      pressed, then redisplaying ds9 causes a segmentation violation.

   5. There are problems with retrieving of images from some default
      archives that ObsVis supports.  It looks like certain
      combinations of target coordinates fail to retrieve images. A
      workaround is to reduce number of decimal digits to no more than
      three in RA and/or Dec. 

   6. Due to some asynchronous and event-driven nature of the
      ObsVis/ds9 interaction, there might be situations when FoV are
      not updated properly in ds9 (especially when FoVs are either moved
      or rotated faster than ds9 can update them).

   7. Please note that the nominal roll/visibility/pitch plots for a
      given target position that were once packaged as part of ObsVis are
      now found only at http://obsvis.harvard.edu