SKYMAP: Exploring the Universe in Software, Douglas J. Mink (1993), presented at the Second Annual Conference on Astronomical Data Analysis Software and Systems (ADASS 92) in Boston, Massachusetts November 1992, published in Astronomical Data Analysis Software and Systems II, A.S.P. Conference Series, Vol. 52, 1993, R.J. Hanisch, R.J.V.Brissenden, and Jeannette Barnes, eds., p. 499.

SKYMAP: Exploring the Universe in Software

Douglas J. Mink
Smithsonian Astrophysical Observatory, 60 Garden St., Cambridge, MA 02138


SKYMAP is a computer program which produces maps of arbitrary portions of the sky in a variety of projections and coordinate systems. Over the past 10 years it has been used to produce finder charts for occultations by planets, display scan and image data from the Spacelab 2 Infrared Telescope, and make maps of fields for astronomical observations at X-ray, optical, infrared, and radio wavelengths. It can display multiple source catalogs, including the HST Guide Star Catalog, as well as solar system objects with astrometric accuracy. SKYMAP can be tuned to a specific task using an ASCII parameter file which controls how information is displayed on any Tektronix-compatible graphics display or hardcopy device. The program contains a variety of interactive graphic and image processing features and has been ported to a variety of computer systems.


SKYMAP is an interactive astronomical display program which projects a map of the sky in any of several coordinate systems in any of several projections. This map can be displayed on any Tektronix-compatible graphics terminal, such as xterm, and printed to any hard-copy device which supports Tektronix graphics code or for which a translator exists. Star catalogs, planet positions, images, or telescope scan directions can be plotted over the coordinate grid. SKYMAP can access the IRAS, SAO, PPM, and HST Guide Star catalogs, as well as planetary positions from 1950 to 2000. Additional catalogs (and ephemerides) can be accommodated as well. Images can be displayed in halftones or contours with any of the other information overplotted.


Creation of finder charts is the most common use of SKYMAP. The ability to plot at a particular plate scale, such as that of the Palomar Sky Survey, is particularly useful. The map can be centered on a specific catalog object and include up to two catalogs plus HST Guide Stars. Planet positions can be plotted over time to aid in planning observations. All-sky maps can also be produced to show large structures or the position of a catalog in the big picture. Catalogs can also be plotted over contour or halftone images.


Almost everything in the program is parameterized; the map format can be modified to fit the user's requirements, and there are many possibilities for plotting information over images or other spatial information. Parameters which define a SKYMAP session are stored in an ASCII parameter file, which is modified by all of the interaction modes. A default parameter file, "skymap.par", is moved into the current working directory when SKYMAP is invoked there for the first time.

An ASCII parameter file format has been designed based on the FITS image file header format The parameter file structure is clear enough that such a file can be edited by an ASCII file editor such as vi or Emacs. In addition, parameters can be modified on the command line or values returned, so the Unix shell can be used for batch operation of programs. Although this is a fairly rudimentary system, it has been in use for several years and is fairly well debugged.

The parameter file is very simple. Each parameter gets one line of the form "keyword = value / comment" where "/ comment" is optional, and each line is terminated with a linefeed. As in FITS, the final line of the file is simply "END". Character strings get no special treatment. The comment "/" is differentiated from any "/"s which may occur legitimately in character strings by the fact that character string values are surrounded by quotes. Quotes, which may be single or double as long as they're matched, are only needed if "/"s are in the strings, but they may be used to delimit any character string. While the order of the elements of the line is important, the parsing subroutines will omit leading and trailing spaces and tabs from each element, so they may be positioned for clarity.


SKYMAP knows about Aitoff, Mercator, Lambert cylindrical, gnomonic, orthographic, polar, and linear projections and can plot a grid or a set of tick-marked box axes for any of them. All of the IRAS map projections are included so objects can be plotted against contoured IR sky flux. Equatorial (J2000 or B1950), galactic, and ecliptic coordinates may be specified, as well as orbital, where an arbitrary pole position in right ascension and declination is specified.

The map may be labeled using terminal or computer-generated characters. Computer drawn characters use the Hershey font set and are, in decreasing detail, Complex, Italic, Duplex, and Simplex. Four standard font sizes, corresponding to the four Tektronix sizes, plus arbitrary sizes in Tektronix coordinates (height=10 to 4095) are available. The font size may be set separately for headings, tickmark labels, axis labels, time tag, plate scale, and magnitude scale table. Font type is the same for heading, tick, and axis labels.

Portions of the displayed map may be enlarged using the Zoom menu or cursor command. The original display parameters are remembered and may be recovered using the Unzoom commands. If the default automatic grid spacing has been specified, an optimum spacing is program-selected when zooming. If plotting to a specific plate scale, the size of a zoomed map can be specified by plate scale. By zooming, portions of images can be selected in sky coordinates rather than in rows and columns.

Plotting Objects on the Sky

SKYMAP can plot sources from the HST Guide Star Catalog plus up to two other catalogs and any number of solar system objects on a map. The SAO Catalog, the Yale Bright Star Catalog, the IRAS Point Source Catalog, and the PPM Catalog are available in a rapid-plotting binary format. Catalogs also may be plotted from the simple ASCII format,

<catalog name>

<one-line catalog description>

<number> <RA as hh.mmsssss> <Dec as dd.mmssss> <magnitude> <name>


A program, STARCAT, exists to turn files in this format into binary files for faster plotting in SKYMAP.

Magnitude and flux limits may be set, and the size of the plotted source scaled by its flux. Foreground objects may be labeled and plotted as open crosses or half-crosses as well as circles. Sources may be identified using the cursor. A table of source size vs. magnitude may be plotted in an arbitrary location on the display. Sources may be labeled with their number, or if plotting from an ASCII file, their name. The location of this label is specified in display (Tektronix) coordinates, where coordinates less than 100 are used as offsets from the plotted source position. The font types and sizes of the star labels may also be specified. Optional log files (one per catalog) may be kept which lists positions and magnitudes of all of the stars plotted in the current region.

If the Hubble Space Telescope Guide Star Catalog CD-ROM set is mounted on the computer as a Unix file system, SKYMAP can plot sources directly from the CD-ROMs. If only one CD-ROM drive is available, only the hemisphere of interest need be mounted. As with other catalogs, magnitude limits may be set. In addition, objects may be selected by whether or not they have been flagged as non-stellar. Guide Stars may be plotted in the same way as the other catalogs. If the stars are labeled, the number of the region is omitted. An optional log file listing all Guide Stars with region and source number may be kept. Another program, RGSC, is a standalone version of this searching software.

Positions of many solar system objects, including the sun, the moon, the other eight planets, and the satellites of Uranus, Neptune, and Pluto, may be plotted for any time between 1980 and 2000. The positions are from the current JPL DE-130 ephemeris and are the most accurate available. More than one object can be displayed, and variation in position over time can be plotted. Rings may be plotted by selecting the appropriate data base entry. Additional objects may be added to the planet database if ephemeris files in a simple ASCII format

<Julian date> <right ascension> <declination> <distance>

exist. In this file, <right ascension> is in fractional hours, <declination> is in fractional degrees, and <distance> is the distance from Earth in Astronomical Units. Planet positions and distances for any object in the planet database may be printed using a separate program called PLANET.

Time series of pointing directions, such as those of the Spacelab 2 Infrared Telescope can be plotted on the sky.

User Interface

Of the four ways to interact with SKYMAP, parameter file editing, command line, menu/prompt, and cursor, the menu system is the most user-friendly. It is a fairly bomb-proof interface perfected over the past ten years with are several levels of menus. The top level handles action commands, parameter file actions, and selection of submenus. The submenus handle information concerning source catalogs, planets, mapping, image characteristics, IRT scan data, display format, and image operations.

A single keyboard character chooses the menu selection; the main menu is displayed if a space or "?" is entered in response to the top level prompt, "SKYMAP?". Lists of submenu commands can be obtained by responding with a space or "?" after the submenu is selected. A "=" in response to a submenu prompt lists the values of all of the parameters which can be set within that submenu. Out of range numbers and illegal characters are trapped, and the prompt is repeated without crashing the program.

Menu interaction can be bypassed by setting the parameter MENU=F; SKYMAP can then be run directly from the Unix shell. In this mode, parameter values can be checked and modified from the Unix command line. SKYMAP can thus be run in a Unix shell script, and selected parameters, which are returned on standard output, can be tested. Parameter names are included if the parameter PARVAL is "N". If PARVAL=Y, "skymap cra cdec" returns the single line " 19.3936 -1.". Typing "skymap cra cdec" returns the following if PARVAL=N:

CRA = 19.3936 [Center right ascension in hh.mmssss]

CDEC = -1. [Center declination in dd.mmsss]

Comments from the parameter file are included if they are present. Parameter values may be changed on the command line:

skymap <keyword1>=<value1> <keyword2>+<value2> ...

where parameter parameter <keyword1> will be set to <value1> and <keyword2> will be incremented by <value2>. Because SKYMAP's command line parser allows arithmetic on parameters, Unix shell scripts can be written to generate reams of finding charts. SKYMAP may also be run from an alternate parameter file by typing

skymap -par <parameter file name>.

The most commonly used parameters are listed with their current values when you type "skymap help". To set parameters without plotting anything, or to simply install the default parameter file in the current working directory, add "stop" to the command line, and SKYMAP will process the preceding parameter entries on the command line and stop without attempting to plot anything.

The cursor command set is based on the Tektronix GIN mode which is available to a wide variety of graphics terminals. Cursor mode is entered from menu mode after a plot has been made or automatically after the plot is complete if the CURSOR parameter is set. When the cursor is moved to the appropriate position using a mouse or other pointing device, a single keyboard character selects the use to which the cursor coordinates will be put. Scaling, zooming, coordinates, image values, and source identifications are available in this way. A menu of cursor commands appears when a space or "?" is entered.

Image display

SKYMAP reads FITS images from disk files which are specified in two parts: the image file name and the image directory pathname. When plotting different images from the same directory, only the image name needs to be retyped. Mapping parameters may be read from the FITS image header or set using the Mapping submenu. Image pixels are assumed to be square. If an image is displayed, it is plotted before axes or other information. Only 2-byte integer (Fortran Integer*2, C short) images are supported; SHRINK, a separate program, reduces 4-byte integer images to 2-byte images.

Two modes of image display are currently implemented, halftone and contour, on any Tektronix-emulating terminal. Contour intervals and gray levels for halftones are separately maintained. Halftones may be scaled linearly, logarithmicly, or by a power law. Two halftone modes differ in the way they fill the display. One plots dots randomly, the other repeats patterns. The image is centered with in a defined display area on the terminal, as is any map that is drawn. The image is redisplayed whenever the range of values or scaling technique is changed as these affect the mapping of image pixels to display pixels.

Hardcopy Output

Hardcopy output is available for line graphs by dumping a log file whose name is specified in the PLOTFILE parameter. It may also be specified by the ">" menu command. While the default file is skymap.plot in the current working directory, it is safer to send complicated plots to a file in /tmp to avoid quota or disk overflows. This log file contains all Tektronix commands and character strings which were sent to the display between the time the "P" command was issued and the "SKYMAP?" prompt or cursor appeared. It may be displayed on a Tektronix-compatible terminal or printed on any Tektronix-compatible output device such as a plotter or a laser printer. A program, IMTEK, has been written to print this log file to Imagen laser printers using the best resolution possible. The public domain program TEK2PS can be used to produce Postscript files for most laser printers or publication. Separate log files containing lists of plotted stars and their positions or responses to cursor commands may also be kept and printed.

Future Features

It would be nice to reimplement the color image display functions written for AED color graphics terminals for the X Window System, though this could require restructuring of the whole program. The graphic image display, color map graph, and linear cross section could all be plotted in separate windows from the command window, the latter two being popped up only when needed. If a color graphics terminal emulator were written for X, porting would be much easier as the image refresh function would be taken care of by the terminal emulator rather than the image display program.
Doug Mink