ObsVis is the Observation Visualizer created at the Chandra Science Center in Cambridge Massachusetts, USA.
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 http://cxc.harvard.edu/soft/obsvis/OBSVISReference.html Additional information about ObsVis is available at http://cxc.harvard.edu/obsvis Additional information about ds9 is available at http://hea-www.harvard.edu/RD/ds9
The ObsVis GUI consists of a ds9 window and ObsVis FoV window. the ds9 window can be used to either interactively manipulate FoVs or do some other activity that ds9 supports. The ObsVis window contains 5 major components:
- main menu
- FoV parameters input area (allows for the input of parameters like coordinates, offsets, roll, instrument, grating, etc.)
- instrument details area (allows for the viewing and modification of instrument specific data)
- field of view table (contains a listing of all generated FoV's)
- action buttons (initiate specific actions)
OBSVIS Main Menu
The menu items are enabled according to current selections of FoVs in the FoV table.
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.
FOV Parameters Input Area
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
Instrument Details Area
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
The table displays a list of all generated FoVs with details. The appearance of the FoV table is configurable via the Preferences. Clicking on the heading of a column sorts the table using that column's values as keys. The sorting order alternates between ascending and descending with each click. If an empty row is selected in the table, ObsVis displays the coordinates of the center of the current image in the 'Target Coordinates' input field. If no image is present, defaults from Preferences are displayed. Currently at most one FoV can be selected at any given time.
The buttons are enabled according to current selections of FoVs in the FoV table.
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.
Generating an FOV
FoVs can be generated by filling in the fields in the input areas and pressing the "New FoV" button. This will retrieve and load an image (using Preferences settings for image archive and size) into ds9, if one is not already loaded, and generate the instrument layout. If the FoV ID is left blank, it will be generated automatically.
When an FoV is generated, its group attributes are also considered. Any changes to group attributes take precedence before FoV is generated. For Grids, the Target Coordinates of a new FoV are disregarded and group center coordinates and X,Y position in the grid are used to calculate the FoV's s actual sky coordinates before it is generated in ds9.
An FoV can be generated by cloning an existing FoV. Simply select the desired FoV in the FoV table and click on "New FoV" button. Note that all the parameters but FoV ID are thereby duplicated in new FoV which might result in FoVs not being distinguishable in ds9 or might cause an error if they are both members of the same Grid and try to occupy the same spot in the Grid, or if they are members of the same Synchronized group and are being overlaid in a single ds9 frame.
Editing an FOV
Editing an FoV can be accomplished by selecting an FoV either in the FoV table or (with the mouse) in ds9, causing the input fields in the ObsVis window to reflect its attributes. Any of the input fields can be modified if enabled. By clicking the "Apply Changes" button, the selected FoV is updated and changes are reflected in the FoV table and in ds9. Should any group parameters be modified, these take precedence over changes to FoV parameters. Therefore, in this case the group parameters will be updated first, then those of the selected FoV. For Grids, if the group center and FoV's target coordinates have been modified, only the group center is considered and target coordinates are recalculated using the group center coordinates and X,Y position in the grid before FoV is updated. See 'Section on GROUPING' for detailed description of group behavior.
Deleting an FOV
FoV's can be deleted by pressing "Delete FoV", "Delete All" or "Delete Group" buttons. "Delete FoV" will delete the selected FoV, while "Delete Group" will delete all FoVs in the same group as the selected FoV. "Delete All" will delete all FoVs. If a frame with FoVs is deleted in ds9, those FoVs are deleted in ObsVis window as well. Single FoVs can only be deleted using the ObsVis window, not in ds9.
Manipulating an FOV
FoVs can be manipulated via ObsVis by editing FoV (see section 3.3 EDITING FoV) or by mouse actions in ds9. Manipulating FoVs in ds9 works the same way that regions are manipulated in ds9. FoVs can be selected, dragged and (using the Shift Key) rotated like normal ds9 regions. ObsVis restricts the extent to which those operations can be performed using Chandra instrument constraints. From ds9, the user may:
- 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.
ObsVis uses a calibration file to ensure that the instrument FoV displays are consistent with the best-calibrated current spacecraft configuration. The calibration file is automatically downloaded from the CXC and loaded into ObsVis when ObsVis is first started. This feature can be turned off by de-selecting the "Auto-Calibrate" button under the Calibration tab in the Preferences. If auto-calibrate is turned off the user can load the calibration file by selecting "Calibrate" from the main menu (see section 1.1 MENU ITEMS for more details). Due to network traffic or Smithsonian server being busy retrieval of calibration file might fail then ObsVis falls back on old calibration file that it finds in user's home directory ($HOME/.obsvis.cal). User can change retry count and timeout value for retrieval of calibration updates in preferences (see section 6.0).
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).
Execution Environment and Command-line Options
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