Search https://cxc.harvard.edu/ciao/
Contact the CXC HelpDesk
Last modified: December 2023

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/Obsvis.html
/ ciao4.16 / ahelp / Obsvis.html
Jump to: · Overview · GUI · OBSVIS Main Menu · FOV Parameters Input Area · Instrument Details Area - ACIS · Instrument Details Area - HRC · FOV Table · Action Buttons · FOVs · Grouping · Configuration · Preferences · Execution Environment and Command-line Options · Caveats · See Also

AHELP for CIAO 4.16

obsvis

Context: proposaltools

Synopsis

ObsVis is the Observation Visualizer created at the Chandra Science Center in Cambridge Massachusetts, USA.

Overview

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.

Further information is available: the ObsVis manual; ObsVis home page; and SAOImabgeDS9 home page.

GUI

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:

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.

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

File.Print

Prints all FoVs to default printer.

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

Edit.Cut

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

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

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

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

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

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

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

Adjust-FOV.Calibrate

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

Adjust-FOV.Image Auto Reload

Sets user preference for auto reloading of images. Auto image reloading would occur when the user presses 'Apply Changes' button and either:

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.

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

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

Help.About

Invokes a window to display version information for ObsVis.

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

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.

This is the end of the grouping options.

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.

This is the end of the compound group options.

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 synchronized 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:

Instrument Details Area - ACIS

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.

Instrument Details Area - HRC

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

FOV Table

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.

Action Buttons

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

FOVs

FoV layout consists of the following elements:

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:

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

Grouping

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.

Configuration

Instrument Calibration

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.

Preferences

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.

Caveats

See Also

proposaltools
colden, dates, pimms, precess, prop-coords, prop-time, prop-tools
/ ciao4.16 / ahelp / Obsvis.html