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.
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.
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.
The objects drawn currently include:
starpost for PostScript, allow
for continuous scaling of the size. Color is determined from the star's
spectral class.
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.
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.
As many chart controls as feasible may be set by various methods of user interaction.
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.
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.
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.
All are in equinox 2000.0 coordinates, and should also be in epoch 2000.0.
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
starX11 is the X11 version of starchart. It has the following
special arguments which are accessed through `-a', e.g.
`-a p'.
starpost chart. starpost landscape format chart.
Usage example:
`starX11 -c ori -g 5 -a p'.
starXaw
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"'.
Usage example:
`starXaw -c sgr -a p -a "t -geometry -0-0 -bg red"'.
starpost
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"'.
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
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.
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.