PRoVis Reference Manual

1.0 OVERVIEW
PRoVis is a web based application that allows viewing and interactive manipulation of Roll, Pitch and Visibility Plots. There are a number of options that users can modify to customize the resulting plots. PDF version of plots can also be generated. PRoVis uses a recent projected Chandra spacecraft ephemeris to generate plots. Since Chandra's orbit does not change much from year-to-year, plots are also closely applicable for any mission year. The plots are generated directly into the browser, unless PDF is requested, for which the browser needs to have an external viewer configured to retrieve and view PDF. The PRoVis GUI consists of 4 elements: buttons frame, target parameters frame, plot options frame and actual plot frame. To use: enter the J2000 sky coordinates of the source of interest in the boxes on the left in the target parameters frame and press enter or click on 'Generate Plot' button in the buttons frame. A number of different formats for RA and Dec coordinates of the target are accepted (see Target Coordinates). Alternatively, type in a target name in the 'Target Name' input box in the target frame and either press return which will resolve the name to sky coordinates or click on "Generate Plot' which will resolve the name to coordinates and generate plot in one step. See Plot Frame for info on plot layout.

2.0 ACTION BUTTONS TOP
Action buttons allow the user to perform the following tasks:

resolve target name to coordinates
clear target input boxes
reset start and end dates to defaults
reset plot options to defaults
(re)generate plots
generate PDF version of a plot
cancel pending request
show PRoVis help

The buttons are enabled/disabled based on the current state of PRoVis. Initially only the help button is enabled. Target coordinates or target name must first be entered to enable other buttons. Some of the buttons are enabled if target input or plot options have changed. The cancel button is enabled whenever there is a pending request in progress.

2.1 RESOLVE NAME TOP
PRoVis accepts target name in the target frame. If the 'enter' key is pressed or 'Resolve Name' button is clicked in the buttons frame after typing in a target name, PRoVis will attempt to resolve this target name into sky coordinates using the SIMBAD server. Users can click on Cancel if SIMBAD is busy and the request is taking too long. If there are too many hits that match the target name, a 'Multiple results' message is displayed in target coordinates input box. If no target was found, a 'No results found' message is displayed.

2.2 CLEAR TARGET TOP
Clears the information in Target Coordinates and Target Name input boxes in Target Frame

2.3 RESET DATES TOP
Resets Start and End Dates in target frame. The dates are reset to the default values for observation cycle.

2.4 RESET OPTIONS TOP
Resets values of options in the plot options frame to defaults.

2.5 GENERATE PLOT TOP
Generates new plot or regenerates the existing one if a plot is already displayed. Values from target frame and plot options frame are used to set attributes of the new plot. If a target name is present and target coordinates box is empty in target frame, then this target name is resolved first and then a plot is generated.

2.6 GET PDF TOP
Values from target frame and plot options frame are used to generate PDF version of a plot. Your browser must be configured to correctly handle application/pdf mime type.

2.7 CANCEL TOP
Cancels any pending requests.

2.8 HELP TOP
Displays this reference manual in the plot frame. The 'Generate Plot' button will return you to the plot, as long as a Target Name or Coordinates have been entered.

3.0 TARGET PARAMETERS INPUT FRAME TOP
Target parameters input frame allows the user to specify start and end dates, target coordinates and/or target name for a desired observation.

3.1 START AND END DATES TOP

For start and end dates, default values change with every observation cycle. Users may enter dates within the ephemeris provided to either zoom in or out.

If the dates entered are not within the ephemeris dates for the current cycle, the date will be displayed in yellow.

3.2 TARGET COORDINATES TOP
Target coordinates should be specified as right ascension and declination in succession. 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

4.0 PLOT OPTIONS INPUT FRAME TOP
Plot options are used to set some of the attributes of the generated plots:

curves to be included in plot (pitch,roll,visibility,bad pitch) By default the plot shows the source visibility in blue, the roll angle in magenta, and the pitch angle in red as a function of time on the x-axis.
line colors,types and widths for curves
fill type and colors for regions
plot target visibility
auto fitting of plot into frame with resizing of window/frame
zoom factor and move factor used to change axis limits
size of PDF plot
font type and size for plot
axis line width Autofitting and plot data visibility automatically implement refreshing of data or regeneration of plot if one is loaded. Crosshair and curve cursors visibility take immediate effect when selected. All other options require the plot to be regenerated by clicking on 'Generate Plot' button to reflect changes in already loaded plot.

4.1 VIEW PITCH ANGLE TOP
Selecting pitch angle will include the pitch angle vs. date curve in the generated plot and plot data display. The following attributes for the curve can be modified:

line type
line color
line width

'Generate Plot' button must be clicked to update the plot with new attributes.

4.2 VIEW PITCH CURSOR TOP
Selecting this option will display a marker projecting the cursor position onto pitch curve.

4.3 VIEW ROLL ANGLE TOP
Selecting roll angle will include roll angle curve in generated plot and plot data display. The following attributes for the curve can be modified:

line type
line color
line width

The 'Generate Plot' button must be clicked to update the plot with new attributes.

4.4 VIEW ROLL CURSOR TOP
Selecting this option will display a marker projecting the cursor position onto roll curve.

4.5 VIEW AVERAGE VISIBILITY TOP
Selecting average visibility will include average visibility curve in generated plot and plot data display. The following attributes for the curve can be modified:

line type
line color
line width

The 'Generate Plot' button must be clicked to update the plot with new attributes.

4.6 VIEW VISIBILITY CURSOR TOP
If selected, a marker will be displayed on the visibility curve at the date selected by the cursor location.

4.7 VIEW PITCH ANGLE RESTRICTIONS TOP
Selecting this option will include bad pitch restriction regions in generated plot and plot data display. The following attributes for the curve can be modified:

region color
line style
line width
fill type

The 'Generate Plot' button must be clicked to update the plot with new attributes.

Plot regions are labeled as Forbidden to indicate pitch angle constraints imposed by satellite thermal and safety considerations,as detailed in the Pitch Angle Constraints in the Proposers' Observatory Guide .

4.8 SHOW CROSSHAIR TOP
If selected, crosshair will be displayed in the plot whenever mouse pointer hovers over it.

4.9 VIEW PLOT DATA TOP
If selected, plot data will be displayed in tabulated format in a lower frame on the same webpage. It will be refreshed each time the date limits change. Selecting this option will automatically open another frame, while deselecting will close that frame. If autofit is selected, the plot will be regenerated to fit new frame size. Rolling mouse pointer over rows in the table will display (if selected) the cursor, crosshair and curve values in the plot for the corresponding date in the table. Clicking on a row in the table will select a row and generate shaded area on the plot corresponding to data in this row. Clicking on selected row will deselect it and corresponding shaded region in the plot will be removed.

4.10 AUTOFIT PLOT IN FRAME TOP
If selected, autofit causes PRoVis to regenerate the plot each time the frame size changes to fill the plot framesize considering min and max allowable dimensions for the plot image.

4.11 AXIS ZOOM FACTOR TOP
A float value which is used when zooming in and out plot limits using mouse pointer. It determines what the new limits will be in relation to the current ones whenever zooming in/out takes place. Zoom factor of 2, when zooming in will decrease interval between lower and higher limit by factor of 2, when zooming out will increase this interval by factor of 2.

4.12 AXIS MOVE FACTOR TOP
A float value which is used when moving limits using mouse pointer. It determines what the new limits will be in relation to the current ones whenever limits are moved up or down using mouse pointer. This factor specifies by how much limits are moved in relation to the current interval between low and high limits.

4.13 PDF SIZE TOP
Specifies the width and height in inches of desired PDF version of plot. If left blank, the size will be matched to the actual screen size of plot image.

4.14 FONT TYPE AND SIZE TOP
Size and type of font to be used in text in plots.

4.15 AXIS LINE WIDTH TOP
Width of axis line.

5.0 PLOT FRAME TOP
Plot frame contains image of a plot, buttons to manipulate the limits of x axis and fields to display position of mouse pointer in axis units.

5.1 MOUSE POINTER POSITION TOP
The y-axis values for the target/spacecraft at the appropriate x-axis value (date) are automatically displayed when the mouse hovers over the plot image. In addition PRoVis displays calendar date as well.

5.2 AXIS BUTTONS TOP
The bottom side of plot contains a set of buttons that allow

moving of limits up and down by an amount specified in the options frame 'move factor'
zooming in and out of limits by an amount specified in the options frame 'zoom factor'
resetting of limits to initial values

5.2.1 MOVE LIMITS UP TOP
Button right arrow moves limits up by specified fraction (taken from 'Axis Move Factor' in Plot Options frame) of current limits interval for selected axis. Axis can be reset to old values using reset button.

5.2.2 MOVE LIMITS DOWN TOP
Button right arrow moves limits down by specified fraction (taken from 'Axis Move Factor' in Plot Options frame) of current limits interval for selected axis. Axis can be reset to old values using reset button.

5.2.3 ZOOM IN TOP
Button zoom zooms in limits by specified fraction (taken from 'Axis Zoom Factor' in Plot Options frame) of current limits interval for selected axis. Axis can be reset to old values using reset button.

5.2.4 ZOOM OUT TOP
Button zoom zooms in limits by specified fraction (taken from 'Axis Zoom Factor' in Plot Options frame) of current limits interval for selected axis. Axis can be reset to old values using reset button.

5.2.5 RESET LIMITS TOP
Button resets the values of selected axis limits to original values set when the last 'Generate Plot' was performed.

6.0 GENERATING PLOTS TOP
Plots can be generated in 3 ways:

enter target coordinates in target frame and press enter
enter target coordinates in target frame and click on 'Generate Plot' button
enter target name in target frame (make sure target coordinates entry box is empty) and click on 'Generate Plot' button

PRoVis disables 'Generate Plot' button if there is an error in the target parameters (dates or coordinates) or if the existing plot matches the parameter values entered. Date problems are highlighted in appropriate field.

6.1 TARGET NAME RESOLUTION TOP
PRoVis uses the SIMBAD catalog (located at http://simbad.harvard.edu/) to resolve the target name to celestial coordinates. To use it, type in the name of target to be resolved in 'Target Name' entry box in the target frame and press enter or click on the "Generate Plot" button (make sure though the Target Coordinates box is empty). PRoVis will only display resolved coordinates if a single result is found. If multiple matches are found, PRoVis will display a "Multiple results" message in the Target Coordinates field. If no matches are found it displays "No results found" message.

7.0 MANIPULATING PLOTS TOP
Plots can be manipulated using buttons at the bottom of the plot image. In addition, the mouse pointer and mouse buttons can be used to various degrees depending on your browser. For all browsers:

Left mouse button click will center plot using current mouse pointer coordinates as the new center of plot

In Mozilla Firefox, SeaMonkey, Netscape and Internet Explorer the following additional functionality is supported:

Shift+Left mouse button click will zoom in on the plot using the current mouse pointer coordinates as new plot center
Ctrl+Left mouse button click will zoom out the plot using the current mouse pointer coordinates as new plot center
Shift+Ctrl+Left mouse button click resets the plot to the original state set by your last "Generate Plot" request

8.0 MAXIMUM EXPOSURE TIMES TOP
For proposers whose observations require constraints for scientific reasons, once the pitch angle for a given target is known, e.g., using PRoVis, you may need to examine detailed projected estimates of usable orbit intervals (and their unusable complement during the radiation zone) at the Orbits page.

9.0 CAVEATS TOP

Works best with Mozilla Firefox(v1.5.0.5 or newer), SeaMonkey(v1.1.8 or newer), Safari(v3.1.2 or newer) and Internet Explorer (v6 and newer) browsers.
Accuracy of mouse pointer display is 1 pixel which may translate to significant number in data units depending on axis limits set.
On Windows, you might have to configure your mouse pointer 'precision select' cursor to 'crosshair' in Controll Panel/Mouse Properties if it is does not show up when hovering over the plot.
IE v6 does not render properly transparent png graphics so selected data rows will show up as non transparent blocks in the plot. Newer versions of IE: v7 and v8 beta work properly.

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

TABLE OF CONTENTS