IDL SKYMAP - USER'S GUIDE
NASA CONTRACT NAS5-30440
Goddard Space Flight Center
HUGHES - STX
Printed on Jul 22, 1998
User's Guide on January 1993
This document provides information on how to use
IDL version of SKYMAP. Section 1 contains a general
description of the
program. Section 2 lists the steps to execute the
program. The program
I/O interface is described in section 3.
TABLE OF CONTENTS
- General Description
- Program Purpose
- Program Description
- Applicable Documents
- Running the Program
- Hardware Requirements
- Preliminary Requirements
- I/O Interface
- Image Display
- Analysis Options
1 General Description
1.1 Program PurposeThe IDL
SKYMAP program reads and displays images stored in
files that contain a valid FITS image and header
or ASCII files generated from the EGRET scientific analysis program LIKE.
Additionally, the program features
a number of interactive data analysis tools that will allow the user to
locate the maximum bin, display the value and coordinates of a bin,
smooth the image, logarithmically scale the image, draw image contours,
project histograms reflecting bin value totals for each axis,
print the image, rescale
the pixel colors and zoom in on a subimage.
1.2 Program DescriptionThe
SKYMAP program runs from within IDL. When SKYMAP is run a window will
appear containing an area displaying instructions and information, an area
where all files in the directory set by the environment variable FITS_DIR
are listed, an image display area and data analysis tools menu. The user
will select a file from the File Listing area or select one of the
under the Alt File menu option to select a file that is not listed.
The image stored in the selected file will be displayed and
the program then waits for an analysis option, another file or the
menu option to be selected.
At input time, the user will only need to know what file is to be
displayed and its location on the system.
DocumentsAdditional information related to the SKYMAP program may be
found in the
- MAPGEN Program Definition
- Implementation of the Flexible Image Transport System NOST
- EGRET Telemetry and Data Formats, # 82-3-5
2 Running the Program
2.1 Hardware RequirementsThe
IDL version of SKYMAP will run in the windowing environment
on Sun4 systems and SPARCstations onto which IDL software has been
RequirementsPrior to running the program, a number of environment
be properly set. The default values of these variables are normally set by
adding an entry for each in the user's .cshrc file.
The specific environment variable declarations that should be included
in the user's .cshrc file are:
IDL_PATH ........ directory path specifying the locations of all IDL
FITS_DIR ........ directory location of files containing images that are
to be displayed
MISC_DIR ........ directory location of files containing the data used
to display sources and the color tables.
To manually set an environment variable, use the setenv command e.g.
setenv FITS_DIR ~userid/fits
The program will use these variables to access all necessary IDL
and data files.
2.3 ExecutionThe SKYMAP
program may normally be run from any directory in a windowing
environment. To run SKYMAP, the user can type skymap at the Unix
This command runs a shell script that invokes IDL and runs the SKYMAP
routine. Optionally, the user can run SKYMAP from within IDL by typing
idl at the Unix prompt and then skymap at the IDL prompt.
3 I/O interfaceAll I/O takes
place from the one SKYMAP window seen in Figure 1 as it
first appears. The top left area, hereafter called the
Instructions/Information area, will display instructions
and information, providing a history of the user's selections.
Underneath this area is the File Listing area where, initially, files
located in the directory specified by the environment variable FITS_DIR
are displayed. The EXIT
button is below the File Listing area. On the right side of the window is
the Image Display area and along the bottom is the Data Analysis Tools
menu. Files and menu items are selected by moving the cursor
to the file name or menu button and clicking once. Arrows
displayed next to the button label of or an extra "box" around the Data
Analysis Tools menu item indicate that there are suboptions for this menu
item. These suboptions will appear when you click once on the menu button
with the left mouse button. The user then selects one of the suboptions,
again by clicking on it once. If user input is required after selecting
a menu item, a separate window will be displayed to accept the input.
Whenever possible, the program automatically moves the focus to this input
Figure 1: Skymap window
Skymap Window (figure 1)
- Select a file: the user must specify the file that contains
the image that is to be displayed. There are three ways to select this
- Point and click once on the file in the File Listing area.
- Select the Alternate File suboption under the Alt File
item that is located in the Data Analysis Tools menu along the bottom of
the window and enter
the full path of the file. This file may contain a FITS or ASCII format
- Select the Display Alternate Directory suboption from the
Alt File menu item,
enter the directory that contains the desired file or select one of the
"commonly used" directories displayed. Edit the default file name filter,
if required, and then point and
click on this file after the selected directory is displayed in the
File Listing area.
If the selected file does not contain a header that is recognizable by
the program, an error message will appear in the Instructions/Information
and the user will be prompted to select a different file.
- Select an energy range: if the selected file is in FITS format
and contains image data for more than one energy level,
a menu will appear indicating the available energy levels.
An option to quit will also be part of the menu and, if selected, will
allow the user to abandon the current selection.
If an energy level is selected or if the selected
file contains data for only one energy level, the image is displayed
in the Image Display area.
3.2 Image DisplayThe image
is displayed in the Image Display area with a grid overlay
reflecting the coordinate system of the image.
Along with the selected image the Image Display area contains the image
legend and information about the image that was extracted from the
header of selected file.
The color legend is located to the right of the image plot and is
used to determine the values of bins.
The legend initially consists of twelve color sections each corresponding
range of bin values. When an image is originally displayed, the top
and bottom section represent only one value,
the highest bin value and the lowest bin value respectively. The other
ten sections correspond to all other values divided into ten
ranges of bin values. By locating the color section that matches
the color of any bin, the user can determine in what range of
values the bin value is.
The ranges of the color legend can be changed by selecting the
analysis option Rescale Pix. The colors of the bins in the image
and the color legend can be changed by selecting the Change Color
Table suboption under the Display menu option. The number and
values of the color legend labels can be changed by selecting the Change
Colorbar suboption also under the Display menu option.
If the image is in FITS format and the corresponding keywords are present
the FITS header the following information is displayed along the left
side of the image plot. This information
can also be picked up from headers in certain files that contain
images in ASCII format.
- Map Units: if the file containing the displayed image is a standard
EGRET FITS exposure, counts or intensity map, units will be displayed.
Additionally, if the displayed map is an exposure map, a note indicating
whether the map has been scaled to be in units of cm2 s will be
- Start Time: the date and time that the accumulation of image data
- End Time: the date and time that the accumulation of image data
- Map Type: the type of map.
- Energy Range: the range of energy the displayed image represents.
- Pointing Direction: the pointing direction of the spacecraft at
the time the image data was accumulated. The coordinate system is
indicated by the text along each axis of the image. The pointing
direction is always in degrees.
- File Name: the name of the file. If the file
name is too large to be displayed along the
left side of the image display, it is displayed at the top of the image.
Depending on which analysis options have been performed on the image,
the following information may also appear in this area of the display.
- If an image has been smoothed the sigma value in degrees will be
- If the image has been logarithmically scaled the words Log
will be displayed.
- If the pixels have been rescaled the words Rescaled Pixels
3.3 Analysis OptionsAlong
the bottom of the window are buttons used to select the image analysis
options. Some buttons have a submenu indicated by the arrow next to the
button label or an extra box around the button. The submenu is displayed
the user clicks anywhere on the button.
- Hardcopy: the options associated with this feature are
Default Printer, PostScript File Only, Choose
Print Setup, Mosaic Mode, Aitoff Projection and
Write to FITS File
- Default Printer: the current image will be saved in a
file named idl_skymap.ps
in the user's HOME directory and, if the user is running IDL and SKYMAP
from a local machine, it is also sent to the default printer. The
default printer for a black & white image is lpr and the default for a
color image is the printer indicated by the environment variable
EGRET_PRINTER. If the user is not on a local machine, the PostScript
file will be created but will not be sent to a printer. The PostScript file
name and default printers can be changed by selecting the Print
- PostScript File Only: the current image will be saved in the
HOME directory in a PostScript file named idl_skymap.ps. The name of this
file can be changed within the Print Setup option. No
files will be sent to the printer.
- Choose Printer: the user will be prompted for the name of the
printer to which the PostScript file is to be sent. Only the current
image will be sent to this print. Print Setup can be used to
change the default printers for the remainder of the current SKYMAP
- Print Setup: the user selects this option to change the format
of the output. A user interface will be displayed to allow the user to
the header information, remove the color bar, change the size of the axis
characters, erase or change the title above the image and change the axis
labels. The options to save the image as encapsulated PostScript and to
the name of the PostScript file from the default name are also included.
Also, the default printer can be changed. To do this the user should
the Alternate printers button and then change one or both printer
These new printers will be used for printer output for the remainder of
current SKYMAP session or until the user changes them. To change back to
default system printers the button Default system printers should
- Mosaic Mode: this option was added to allow users to generate
printouts of enlarged sections of images to use for posters. The current
image is divided into sections and each section is then enlarged as much
as possible to fill the printout page. A slight overlap will be included
in each section to make cutting and pasting easier. The user is prompted
to select the number of sections. Only numbers that will result in an even
division of sections will be displayed for selection. PostScript files
be created for each section and will be located in the user's HOME
These files will be named skymap_sectX.ps where X is the section number
starting from the left side of the map. The header information will be in
a separate PostScript file named skymap_section_head.ps. No files will
be sent to the printer.
- Aitoff Projection: this option was added to allow users to
the current image in Aitoff projection. There are three options under
menu item, Display Aitoff, Print Aitoff and
Return to Rectangular Projection . Display Aitoff displays
image in Aitoff projection to the screen. Print Aitoff will
a user interface that provides the user with print options.
Return to Rectangular Projection will switch the image back to its
original rectangular projection. All image manipulation or plotting
functions such as smoothing, plotting sources, plotting circles, etc.
be performed before selecting this option. Only the Print Aitoff
the Return to Rectangular Projection functions under the
Aitoff Projection menu can be performed while the image is Aitoff
projection. The selection of any other function will result in a change
to the original rectangular projection before the function is performed.
- Write to FITS File: the user will be prompted for the name of
the FITS file into which the current image will be written. Not all
of the current image will be perserved in the new FITS file. Smoothing and
zooming will be perserved but rescaling and any overlays of contours and
sources, etc. will not.
- Alt File: the user selects this option to select
a file that is not listed in the File Listing area.
When the user clicks on the option two suboptions will appear.
- Alternate File: the user selects this option to select a file
that does not appear in the File Listing area. An input box will appear
and the user
types the full path name of the file that contains the image to be
The ~ character can be used.
- Alternate Directory: the user selects this option to display
in the File Listing area the files from any directory. An input box will
appear and the user can type the full path of the directory or select one
of the default directories listed. When entering a directory path, the
~ character can be used. The user can enter a Unix filter to
limit the number of files displayed otherwise all files located in the
entered directory will be listed in the File Listing area. Subdirectories
are not listed. The user can then select a file by clicking on the file
- Refresh Directory: the user selects this option to redisplay
the current directory. This option may be useful if image files are
being created in the currently displayed directory as SKYMAP is running.
- Histogram: the user selects this item to plot histograms
showing the total bin values for each axis. A separate window will appear
to accept changes to the default bin ranges and to display the plots.
The user presses the button labeled Display Histogram
after making any range changes and the histogram plots will be displayed.
The user may continue to change the range values and plot the histograms,
send the current histogram display to a PostScript file, or press the
button labeled Done to exit.
- Smooth: the user selects this item to perform Gaussian smoothing
on the image. There are two options under this menu item, Linear
- Linear: the user selects this option to perform standard linear
gaussian smoothing. The user is prompted for the sigma value in
degrees and the image is smoothed and displayed accordingly.
- Logarithmic: the user selects this option to perform both linear
gaussian smoothing and logarithmic scaling. The user will be prompted
for the smoothing sigma value in degrees and after the image has been
logarithmic scaling is performed. The resulting image is then displayed.
Smoothing is always performed on the original image data even if prior
logarithmic scaling and smoothing have been performed. To smooth a
logarithmically scaled image the user should select the Smoothed
suboption under the Log Scaling menu option. If linear smoothing
selected after the color scheme has been changed using the Rescale
option, the revised color scheme will remain. However, if logarithmic
smoothing has been selected, the revised color scheme will be eliminated
and the color legend will be recalculated to reflect the color scheme of
new image. If the displayed image is a subimage of the original image the
smoothing will be performed on the original image and then the subimage
will be taken from that and displayed.
- Log Scaling: the user selects this item to perform logarithmic
scaling on the displayed image. There are two options under this menu
Unsmoothed and Smoothed.
- Unsmoothed: if this option is selected, the image
is logarithmically scaled and displayed.
- Smoothed: the user selects this option to smooth a
scaled image. The user will be prompted for the sigma value in degrees
smoothing will be performed after the logarithmic scaling has taken place.
Logarithmic scaling is always performed on the original image data even
if prior logarithmic scaling and smoothing have been performed. To
logarithmically scale a smoothed image the user should select the
Logarithmic option under the Smooth menu option.
Any pixel rescaling that was performed before this item is selected will
be eliminated and the color legend will be recalculated to reflect
the color scheme of the new image. If the displayed image is a subimage
of the previous image the scaling will be performed on the original image
and then the subimage will be taken from that and displayed.
- Contours: the user selects this item to draw contours on the
displayed image. There are two options under this item, LHOOD
- LHOOD Predefined: the user selects this item to draw contours in
one or both of the standard likelihood contour modes. A listing of the
two modes are displayed as suboptions when this option is selected.
- Fine: the user selects this suboption to display the 4 contours
Fine map contours. These 4 contour levels are defined as the peak minus
1.4, peak - 2.3, peak - 6.0 and peak - 9.1. These contours represent
confidence levels of 50%, 68%, 95% and 99%, respectively.
- Survey: the user selects this suboption to display contours
at the absolute test statistic values. These values are 3.9, 16.5 and
- Other: A separate window will appear displaying the default
of contour levels and values. The user may change the number of contour
levels, at which time new contour level values will be calculated.
The contour values can also be editted by changing the maximum and minimum
values which will result in the values being recalculated, or by directly
editting the displayed values. The user also has the
option to erase the image when the contours are drawn, select the line
of the contours, disable the labelling of the contour lines, and draw the
default Fine map contours. The actual labels can also be changed.
(The default labels are the contour values.) In the lower section
of the window a color bar is displayed to allow the selection of the color
the contour lines. The ability to change the color table is also provided.
The user presses the Change Color Table button to perform this function.
When the window reflects all desired contour criteria, the user presses
Draw Contours button. If contours have been drawn previously
with the image erased, the next time this Contour option is selected the
user will have the option to redraw the image or to select new contour
criteria as just described.
Figure 2: Contour window
Contour Window (figure 2)
- Reset: the user selects this option to re-display the original
image in the most recently selected file. All changes to this
image made after it was originally displayed will be eliminated.
- Zoom: the user selects this item to display a subimage of
the currently displayed image. The maximum and
minimum coordinates of this image are displayed in the
area to remind the user of the size of the original image. A window
will appear giving the user three options to define
the subimage: Point and Click, Enter Coordinates from
and Wrap-Around Zoom. At any time The user may select CANCEL to
the Zoom function without further processing.
- Point and Click: if this button is pressed the user will click
two diagonal corners of the desired subimage. To aid in selecting
coordinates, the coordinates of the cursor position are displayed as the
cursor moves across the image.
- Enter Coordinates From The Keyboard: if this button is pressed,
entry boxes will be enabled to accept the new beginning and ending
along the X and Y axis. Error checking will be performed to ensure
that the new coordinates are within the limits of the current map.
- Wrap-Around Zoom: this option allows the user to connect the
edges of the map and display the resulting image. In other words, if the
is a full sky map with coordinates ranging from 180 to 180 degrees the
can be displayed as a full sky map with coordinates ranging from 0 to 360.
A subimage can also be displayed, e.g., a subimage of the 180 to 180 map
ranging from 150 to 210, centered on the 180 degree line.
After new coordinates have been successfully entered or clicked upon the
subimage will then be displayed. The subimage will reflect any scaling or
smoothing that has been performed on the previous image.
- Bin Info: the user selects this item to get coordinate and bin
value information. The user points and clicks the left mouse button on
location on the image and the value of the bin and the coordinates in both
coordinate systems will be displayed in the Instructions/Information area.
The right mouse button is pressed to exit this function.
- MaxBin: the user selects this item to locate the bin with the
maximum bin value. A circle will be drawn around and a crosshair drawn
through the bin with the maximum value. The bin value and coordinate
information will be displayed in the Instructions/Information area.
If more that one bin contains the maximum bin value, the first of these
bins nearest the bottom of the display will be used.
- Rescale Pix: the user selects this item to change the
color scheme of the map. The color legend along the right side of
the image shows the colors and their respective range of values.
When the image is originally displayed, the top color (white) is the color
the bin with the highest bin value and
the color at the bottom of the color legend is the color of the bin
with the lowest bin value. The other colors represent the bin values
between the highest and lowest value and the these value ranges are
divided according to the color distribution of the EGRET Skymap color
table. The user may change this color range by entering the new values
to be represented by the top and bottom colors of the color legend. The
color legend will be recalculated to reflect these new maximum and minimum
values and the pixels of the image will be changed accordingly.
When this item is first selected, a window appears with the calculated
minimum and maximum pixel values. At this point the user can select Done
to set these values as the rescale values, or edit the displayed values.
If the user wants to see how any new values will affect the image, the
Show Changes To The Screen option can be selected. Cancel is selected
to abandon any changes made (i.e., previous minimum and maximum values will
be restored). Done is selected to accept the currently displayed values.
Pixel rescaling can be performed on any image no matter what other analysis
options have been performed (i.e., Smooth, Log Scaling).
- Maps: this option allows the user to process Fine maps
the LIKE program. There are two suboptions Process Fine Maps-One Per
Page and Process Fine Maps-Six Per Page.
If the first option is selected, the processing includes displaying the
drawing the default Fine map contours, plotting sources from the source
or from a different source list formatted in the same way as the standard
source list, displaying the history from the FITS header and saving the
in a PostScript file. The user will be prompted for the location
of the Fine maps which can be in the displayed directory, the current
working directory or the directory indicated by the environment variable
FITS_DIR. A Unix filter will can also be used to select the files. The
default filter is GROJ*[0-9] which is the default name format from the
LIKE program. The user also has the option to draw contours with no image.
The second option Process Fine Maps-Six Per Page processes maps in
same way as the first option except that the plots are 6 per page with
contours but no image and no history is displayed. The option to create
encapsulated PostScript files is included in this second option.
- Overlay: the user selects this option to overlay the contours of
one image onto another image. To implement this option the user displays
the image to be overlaid on a second image and then draws contours on the
image using the Other option under Contours menu item. The user then
selects the Save Contours option under the Overlay menu item to save the
current image and contours to a file named skymap_overlay.dat in the
HOME directory. The user can then display another image and select the
Overlay Contours option under the Overlay menu item to draw the saved
contours on the current image.
- Display: the user selects this option to perform miscellaneous
display functions. When selected a sub menu appears listing
seven suboptions, Change Color Table, Grid Off/On,
Alternate Coordinate Grid, Display/Erase History,
Draw/Erase Circle around Pointing Direction, Exp Map unit
conversion Off/On and Change Colorbar.
- Change Color Table: the user selects this option to change
the color scheme of the image by changing the color table. A menu listing
all possible color tables will appear and the image and color legend will
change according to the table that is chosen. The menu will remain until
the user has selected the QUIT button which is located at the end of the
- Grid Off/On: the user selects this item to remove the grid
that overlays the image. If the grid has already been removed, selecting
this option will cause the grid to reappear.
- Alternate Coordinate Grid: the user selects this item to
the grid of coordinate systems other than the one that is currently
The original grid will be removed. To re-display the original grid the
selects the Grid Off/On option.
- Display/Erase History: the user selects this item to display
information from the FITS file header associated with the first
ten occurences of the keyword HISTORY. If the keyword HISTORY does not
exist in the header no information will be displayed. If this history
information has been displayed, it will disappear the next time the
option is selected.
- Draw/Erase Circle around Pointing Direction: the user selects
item to display circles on the image around the pointing direction or
some user-defined set of coordinates. The user can also select the radius
color of the circle. There is also the option to erase the circle.
- Exp Map unit conversion Off/On: if the map being displayed is
a EGRET exposure map (the value of the FITS keyword BUNIT is 'Exposure')
the image will be converted to cm2 s. This option is selected
prevent this conversion from taking place. If this option has been turned
off, selecting this option again will turn it back on.
- Change Colorbar: with this option the user can change the color
legend. A user interface will be displayed that will allow the user to
change the number of labels, change the location of the labels and change
the actual label text. The initial color
bar legend displayed with each image displays labels at the border of each
color section (according to the EGRET skymap color table) reflecting the
associated bin value. If the number of label sections is changed, the new
labels will be be calculated to display at even intervals along the color
As an example, imagine the current image contains bin values between 0 and
The initial color legend will display 12 labels, one at the border of each
color section, with values 0, .597, 15.5, 30.5, 46.0, 61.5, 76.5, 92, 107,
122, 137, and 152. If the user selects 4 as the new number of label
the new labels will be 0, 36.1, 76.2, 114 and 152.
The interface also allows the user to change the value of the labels
individually, thus changing the location of the label along the color
The text of the labels can also be changed. By default the text is the
same as the value of the label.
- Restore Session: this option can be selected to restore
the image and directory listing that were displayed when the most recent
SKYMAP session was exited. This information from the previous session is
stored in the user's HOME directory in a file named skymap_session.dat.
- Sources: the user selects this item to mark
the location of sources. There are six suboptions for this item, five
of which are the possible locations from which the source coordinates are
- From Source List: the user selects this option to display
with coordinates located in the file MISC_DIR/src.list. A window
appear to prompt the user for the symbol to be plotted at the source
and the symbol color.
- From Keyboard: the user selects this option to enter
from the keyboard. A window will appear to accept any number of
pairs. The user must press RETURN after each set of coordinates is
The coordinates will then be stored and the input area will be cleared to
accept a new pair. The user presses the DISPLAY SOURCES button when the
coordinate entry is complete. The symbol to be plotted at the source
locations and the symbol color will also be selected in this window.
- From User-created File: the user selects this option to read
coordinates from a user-created file. A window will appear to accept
the name of the file and to provide the option to select the symbol to be
plotted and the symbol color. In order for the coordinates to be read
correctly, the format of the user-created file should be the same as that
the file MISC_DIR/src.list. Galactic coordinates are
read from offset positions 66 and 75, and celestial coordinates from
positions 84 and 93. The coordinates used for plotting will match the
coordinate system of the current image.
- Proposal Sources: the user selects this option to display Phase
3 and Phase 4 proposal sources that are within 30 degrees of the pointing
direction. The user will be prompted for the symbol to be plotted, the
color and the viewing period.
- From PSF File: the user selects this option to display sources
from an output file generated in the LIKE program under the PA/O option.
The user is prompted for the file name, the symbol to be plotted and the
symbol color. If the coordinate system of the
PSF and the current image differs, coordinate conversion will be attempted.
- Erase Sources: the user selects this option to erase all
sources that have been plotted on the current image
A legend will be displayed above the image to enable the user match the
with the source type. The plotted symbols will remain on the image after
other image manipulation tools have been selected.
3.4 OutputsWhen EXIT
is selected, a file named skymap_session.dat is created in
the user's HOME directory. This file contains all current local and system
variables and will be read in the user's next SKYMAP session if the
Restore Session option is selected. The only other output from
occurs if the Hardcopy option has been selected and is in the form
PostScript file. This PostScript file is named idl_skymap.ps and is
in the user's HOME directory unless Print Setup has been used to
change the name and location of this file. If the user is running SKYMAP
a local machine the PostScript file may be sent to a local printer.
File translated from TEX
by TTH, version 1.56.