Go to the first, previous, next, last section, table of contents.


The Starchart Programs

The starchart programs are variations of a single program, producing output for different output devices. All the programs produce astronomical star charts from available databases.

Purpose of Starchart

The starchart programs have many potential uses: in education, preparing illustrations, becoming familiar with the constellations and the sky; but it is primarily useful for preparing for observing. It can prepare large scale maps, finder charts, variable star charts, and illustrations for inclusion in an observing notebook.

A variety of map projections are available for various needs.


There are many many features of potential use. The programs can:

Starchart is intended to produce useful displays on any available device, and to produce best results on high quality graphics printers, especially those using PostScript. Output may be captured in files to be edited for especially customized maps. Comments are included in the output whenever possible to facilitate this editing. Given a good object-oriented editor, professional quality maps may be easily produced.

The program has a set of core routines for user interface and data input, while a set of specialized driver routines is provided for each output device.

Non- and Mis- Features

There are some limitations remaining.

The output is limited by the capabilities of the device. However, even the best of the drivers has the following problems: it cannot detect and avoid overlapping labels and stars, and it cannot allow the user to interact with the display and move the labels. These limitations are what distinguish the output from these programs from a professionally prepared map.

The current programs do not have user configurable Legend areas.

Objects Drawn

The objects drawn currently include:

Size represents the magnitude. For most devices, this is done by rounding to the nearest integer magnitude, and drawing the star based on this; however, some versions, e.g. starpost for PostScript, allow for continuous scaling of the size. Color is determined from the star's spectral class.
On some devices, separate symbols are drawn for each planet, on others they are all represented by the same symbol. Major planets should be distinguished from comets and asteroids. Color may be assigned in the database file.
Diffuse, planetary and unspecified nebulae may be distinguished. If the device can support it, size may represent the diameter of the nebulae (if provided in the database). Color may be assigned in the database file.
Spiral, elliptical and unspecified galaxies may be distinguished. If the device can support it, size may represent the diameter of the galaxy (if provided in the database). Color may be assigned in the database file.
Open, globular and unspecified clusters may be distinguished. If the device can support it, size may represent the diameter of the cluster (if provided in the database). Color may be assigned in the database file.
Other identified objects. If the device can support it, size may represent the diameter of the object (if provided in the database). Color may be assigned in the database file.
For objects which haven't been identified. If the device can support it, size may represent the diameter of the object (if provided in the database). Color may be assigned in the database file.
Solid, dashed, or dotted lines may be drawn using commands in a database. Lines are drawn as projected segments of great circles, or by linear interpolation in latitude and longitude between endpoints. Not all line styles may be supported on some devices. Color may be assigned in the database file.
Invisible objects in a database are used to place text labels in the chart.
Lines for comments are allowed in database files. They have no effect on displayed output.
`Filled areas'
Implemented as filled areas when possible for the device, otherwise as outlines. Area boundaries may be segments of great circles or defined by linear interpolation in latitude and longitude between endpoints.

Projection Modes

There are currently five projection modes available for a map. The default is Sanson's sinusoidal projection, which is area-preserving, but fails near the poles. This projection preserves both area and linearity in Declination (y axis). It gives good conformality (angle correctness) near the equator, so it is useful along the Ecliptic. Lines of RA converge at the poles (unlike cylindrical projections), though Cassiopeia and the Dipper reproduce well.

Stereographic projection keeps circles circles, and can be used near the poles.

Orthographic projection is simple but very distorting; it is as if the sphere of the sky were finite in size and viewed from infinity.

Gnomonic projection projects great circles as straight lines, and is therefore very useful for charts to be used to plot meteor paths. See for example the October 1988 Sky and Telescope.

Rectangular projection is the simplest: latitude and longitude are translated directly to x and y of the map. Note that this is neither cylindrical nor Mercator projection.

Only the main map projection mode may be changed through the command line and `.starrc' format control files; `mapwin' control may change the projection mode of the thumbnail map.

The Chart

A chart is a single page or display region. Within that region are one or more map windows, each of which may have an associated legend region. Each map window is independent of others. Its attributes are defined in a structure which contains its location and size, and parameters and flags used in determining what is placed in the window. The detailed appearance of each graphic element to be displayed in the window is up to the driver. The starchart main routines only define the location of the element, and report which routine is calling the display function. For each line in every star, planet, vector, or other file, the main routines determine only what is to be drawn, and where on the entire device page it appears. The device specific drivers determine exactly how it appears on the device.

The page may have a title region, which is drawn once per page. This region is entirely left to the driver.

The initial values of map window structures are set in the device driver. User input from the `.starrc' file and the command line may change these values, and then the driver has an opportunity to override all settings, possibly through additional user input. The structure may be read and written to `mapwin' files, which may be used for input to different drivers and (carefully) editted by the user.


A map window consists of several layers. All layers are optional. The order of layers is determined independently for each map window.

A map window has an `outline', which is determined by the projection mode. For the Sanson's projection, RA and DEC tick axes are drawn.

A grid of arbitrary origin and spacing in RA and DEC may be drawn. The RA and DEC lines are in two separate layers, called `ra_grid' and `dec_grid'.

The `ecliptic' is a separate layer.

A file defining constellation `boundaries' is provided, in `lineread' format. The file contains vectors which are drawn in a separate layer. Similarly, a `patterns' file contains figures for the constellations. A third file and layer provides names for the constellations (`constlnames').

Finally the set of files defined by the user is plotted. These currently include by default and in order a star file `yale.star', a file which is an index to files separated by region of sky called `index.indx', a nebula database `neb.star', and a planet location file `planet.star'. Additional files may be furnished by the user.

The default is to treat these as one layer, `allfiles', and draw the objects in each file in order. Alternatively, for each map window, the order may be changed to draw all the symbols in all the files followed by all the names in all the files, etc. The supported elements which are controlled by the data files are: glyph (symbol of object), name (text to the right of object), magnitude label (text below and to the right of object), vectors, and filled areas. These are layers `allfiles', `allglyphs', `allnames', `allmaglbls', `allvectors', and `allareas'.

Each file has its own cutoff magnitudes for visibility of objects symbol (maglim) name label (lbllim) and Bayer/Flamsteed label (gklim).

Finally, a `legends' layer displays the legends area, if any, for a window.

To stress: any layer in any window may be skipped, and they may be drawn in any order, independently.

User Controls

As many chart controls as feasible may be set by various methods of user interaction.

Command Line Controls

Currently defined command line arguments are described below. Additional flag interpretation may be done by the device driver: unidentified flags are passed to a driver-specific function which attempts to interpret the flag. All others are undefined, and produce a usage message and error exit.

Control and Specification Files

The controlling variables of the chart are set by default at compile time, and many may be overridden by command line arguments. However, more control is afforded by `.starrc' and `-e extra' files. The starchart programs attempt to read an initialization file, whose name is set at compile time (default `./.starrc'). Additional such files may be read through the `-e' commandline argument. The file contains lines of the form `variable value' or `variable=value', with comments beginning with `#' ignored. The variables and their values are given below. These definitions reset the values of program variables, overriding their current value. These may in turn be overridden by later command line arguments or additional `.starrc' files specified with `-e'. Any variables not understood by the main program are passed to a driver specific function which may interpret it.

Interactive Controls

The `-u' option activates interactive mode, where the same commands as in the `.starrc' file may be typed to control the program options. In addition, `end_input' ends interactive input and draws the chart. After the chart is drawn, control returns to the keyboard. The `quit' command exits the program. The command `show' shows the current state of the control variables. The command `help' may be used to get a brief description of the commands and controls available.

Some, especially window based, versions will allow the user final control over each map of the chart. The chart is specified by an array of large C structures, one for each map on the page. The `mapwin' file contains the values in this structure. Advanced interactive versions of starchart, such as starXaw, allow the components of the structures to be edited individually, providing full access to the flexible controls of the program.

The sequence of control of the program is:

1) read the `./.starrc' file.

2) process the command line: options are processed in order, later arguments may override earlier arguments, additional `.starrc' format files are read as they are encountered in `-e' options. However, if the file specified in the `-e' option is in `mapwin' format, it is read later. After the command line is processed, if the `-u' option is active, keyboard interaction is performed. Next, any `mapwin' format files are read. If there is more interaction available (e.g. as in starXaw), the details of the chart may now be controlled. If a `mapwin' file is to be written, it is written now. Then the chart is drawn to specification. Finally, after the chart is drawn, the program returns to the first interaction (i.e. returns to the point after the command line has been processed).

One more form of interaction is available on some systems: A mouse or other pointing device may be used to either select points on a map and the coordinates of that point are displayed, or the databases may be searched for objects near the selected point and the database entries for the objects found are displayed.

Standard Data Files

All are in equinox 2000.0 coordinates, and should also be in epoch 2000.0.

stellar information (mandatory)
nebulae (optional)
planets (optional)
constellation boundaries (optional)
constellation names (optional)
constellation patterns (optional)
index file for additional star files (optional)
default mnemonic locations

Particular Starchart Programs

Some starchart programs have coadditional driver-specific controls which are accessed throught the `-a' command line option, or the `additional' (= `driver_control') variable.

These programs and other versions of starchart with special needs are documented in this section.


starX11 is the X11 version of starchart. It has the following special arguments which are accessed through `-a', e.g.
`-a p'.

PostScript preview: use screen size and shape to approximate coverage of starpost chart.
PostScript landscape preview: use screen size and shape to approximate coverage of starpost landscape format chart.
hide: display is generated invisibly, which may save time.
backup: use backup pixmap, allows window to be hidden and redrawn.
monochrome: prevents use of color on displays otherwise capable of it.

Usage example:
`starX11 -c ori -g 5 -a p'.


starXaw is the X11 version of starchart with interactive control using Athena Widgets. In addition to the controls for starX11, it has the following special arguments which are accessed through `-a', e.g.
`-a "t -geometry -0-0"'.

" toolkit_args" for access to the standard X toolkit controls, such as for geometry, fonts, etc.

Usage example:
`starXaw -c sgr -a p -a "t -geometry -0-0 -bg red"'.


starpost is the PostScript version of starchart. It has the following special arguments which are accessed through `-a', e.g.
`-a "m9 8 7 6 5 4 3.5 2.5 2 1.5 1 0.5"'.

notebook: The chart is shifted to the right on the page, and the "thumbnail" map is replaced with prompts and space for recording observing conditions. The rest of the argument string is taken to be a list of floating point numbers separated by `:' or ` '. These are taken to be the radii in degrees of fields of view of the instrument or finder. Circles with these radii are drawn, centered on the center of the chart.
magnitude: 0.1 magnitude quanta are to be used (the default is 1.0 magnitude, e.g. a 4.6 magnitude star is represented by the same symbol as a star of magnitude 5.4). The rest of the argument string is taken to be a list of floating point numbers separated by `:' or ` '. These are taken to be the radii of the symbols for stars of magnitude -1, 0, 1, 2, 3 etc. The sizes of symbols for stars with magnitudes between these magnitudes are determined by linear interpolation. Note that the last value given is the value assigned to all magnitudes fainter than that magnitude. Current default sizes are "9 8 7 6 5 4 3.25 2.5 2 1.5 1 0.5".
size: this argument provides an alternative way of specifying magnitude symbol sizes, using a formula proposed by Andrew Young in Sky and Telescope, March 1990, p. 311, D = D0 * 10^(k*(v0 - v)). He proposes a k of between 0.07 and 0.16, with 0.11 as probably the best. If `s' uses 0.1 magnitude quanta as does `m'. The default values for D0, v0, and k are 0.5 (points), the limiting magnitude of the first main map, and 0.11, respectively. These may be altered with the optional arguments to `s', which set D0, v0 and k in that order, e.g. `s 0.7 6.6' sets D0 to 0.7 point, and v0 to magnitude 6.6 so that a magnitude 6.6 star will be printed as 0.7 point in diameter, and k will remain 0.11. `s 0.7 6.6 0.07' will set D0 and v0 as above, and also set k to 0.07.
`f file' may be used to specify an output file, otherwise the PostScript produced is sent to the standard output.
may be used to produce color postscript output.
may be used to specify landscape mode (as opposed to the default portrait orientation). Landscape mode can only used with a fullpage map.

Since the resolution of PostScript is much higher than other common devices, `mapwin' files must be edited when transferred between starpost and other drivers. The controls for window `width', `height', `x_offset' and `y_offset' must be changed.

The `-a p' or `-a l' option used with starX11 or starXaw can be used to produce a `mapwin' file which can be converted for use in starpost through an awk script named postconv.awk, provided with the source to this program.

Usage example:
`starpost -a "n 6:1.5:.5" -a "m9 8 7 6 5 4 3.5 2.5 2 1.5 1 0.5" -a "f orion.PS" -c ori -g 5'.


startool uses the tooltool program, not included in the starchart distribution, to provide an interface to starsunv. ttooltool is available from your local Sun sources archive.

Writing a New Version for a New Device


There are several layers of functions in starchart. The top level is in `starmain.c', `starm2.c', and `readfile.c'. It is (I hope) general enough to enable any additions to be made by users in the form of modified drivers, leaving these files stable. `starmain.c' and `starm2.c' are in charge of the user interface and file reading, with `readfile.c'. Generally, this top level controls what is to be drawn, and where it appears. The device specific section controls how it appears.

Information is passed to the drivers via externs and function parameters. The externs are for runtime values, the function parameters are for values taken from the data files. Information is passed from the driver to the starchart.c routines via externs.

There are three layers of functions, in several source files. The top level functions are in `starmain.c' and `starm2.c'. You should not have to change anything in this file, except perhaps #defines for default file names and file types, and these may also be set in the Makefile.

The `starcust.c' file contains customizing functions, including functions to define additional command line flags, which may apply to several drivers.

The `starXXXX.c' or `starimages.c' + `starXXXX.c' files define the more device dependent functions. There is one function, called `drawobj', which is the interface between the top level functions and the device for drawing the stars, planets, and other objects read from a database file. In addition, standard functions to open and close the device, draw a line, move without drawing, etc. are required. These may then call the lowest level device dependent functions. The `starimages.c' file provides a standard definition for drawobj and supporting functions for bitmapped devices; the device dependent code remaining (e.g. line drawing), is in the file `starXXXX.c'.

User input functions also may be defined in `starXXXX.c'.

The layer currently being drawn and/or the subroutine currently active is passed to the driver in an extern. This allows the driver to for example draw vectors differently for the constellation boundaries. Additionally, each window has a map type field which is for efficiency also passed as an extern, which may be used by the driver to for example draw certain layers differently in certain windows.

The source to other drivers, especially starXaw and starpost, should be a valuable reference to developing new drivers.


For the drivers distributed, there are many `#defines' and global variables whose values may be altered to suit your tastes and your particular piece of hardware. Default file names are `#defined' in the code, and may also be set in the Makefile.

It is easy to write a driver for other devices, based on the drivers and the driver skeleton provided.

More extensive customization is possible through modifying the driver functions to take fullest advantage of the device you are using. It is also possible to add controls accessed through the `-a' command line option and the `additional' (= `driver_control') variables.

Please try to send me (ccount) a note before writing any new drivers, so I can let you know if a driver for that device is in the works. Any improvements to drivers should be sent to me or the author (if they are not the same), when you're sure they work and are happy with the changes.

Things you define in `starcust.c', if you think they are generally useful, should be sent to me. If possible, they may be incorporated in future releases.

Improvements to top level routines should be made with great caution. Such changes will make it harder for you to use future refinements. If you're sure you're change (a) works and (b) is better/stronger/faster, please send it to me.

Do report any bugs/problems.

Go to the first, previous, next, last section, table of contents.