Category : Printer + Display Graphics
Archive   : VGASTARS.ZIP
Filename : VGASTARS.DOC

Program VGASTARS Version 8911 Page 1




DOCUMENTATION for VGASTARS

by David H. Ransom, Jr.

Version 8911
March 13, 1989


VGASTARS is a program to plot realistic-looking star maps on the
screen of your computer. VGASTARS is written in BASIC using the
Microsoft Quick BASIC compiler, Version 4.50. (An earlier version of
the program was tested with Borland Turbo BASIC, Version 1.00, but it
ran MUCH slower on my Zenith computer!) The program and the
accompanying data files are freely available for any non-commercial
use. The basic idea for the program was inspired by the program
STARS.BAS by Richard Berry (published in ASTRONOMY magazine and
available on various bulletin boards) along with other similar
programs and the usual star maps frequently published, but the scope
of the present program has been greatly expanded.
VGASTARS allows you to work interactively with the display on the
screen, searching for individual stars or constellations and marking
them with distinctive screen colors for easy recognition. Using either
a mouse or an on-screen crosshair, you can move about the screen at
will. A grid system, using the stellar coordinate system (Right
Ascension and Declination), may be superimposed upon the screen to
help you maintain your point of reference. When the field of view,
measured as the horizontal distance across the center of the screen,
is 180 degrees or more you can also superimpose the horizon; this
produces a display which is essentially the same as a typical star map
for the given coordinates.
For a novice, one of the problems with this type of program is
that the terms used and the frame of reference may be unfamiliar. To
some extent, of course, this is unavoidable; as in any other special
field, you can't tell the players without a program. Finding that
information, however, can be a considerable chore. For some
interesting programs (in BASIC) and to understand the stellar
coordinate system and other important concepts, I recommend CELESTIAL
BASIC by Eric Burgess (SYBEX, 1982) as a good starting point. The
figure on Page 20 showing the celestial sphere will help you to
understand Right Ascension and Declination, the coordinate system used
to uniquely locate a star (or other object) in the sky. ASTRONOMY
MAGAZINE by Kalmbach Publishing Co. contains an excellent star map on
its centerfold each month, as well as interesting articles and a
calendar of "celestial events" for the coming month.
The Latin names for some of the constellations are familiar: Ursa
Major (The Great Bear and containing the Big Dipper); Ursa Minor (The
Little Bear) which includes Polaris, the North star; Orion and the
twelve constellations of the Zodiac. Recognizing the name when you see
it and coming up with the "standard" three-letter abbreviation used by
astronomers are two different things, however. And there are 88
constellations to try to remember! I've included a number of help
screens in VGASTARS so you hopefully won't have to rush off to the
library to be able to run and use the program.
Program VGASTARS Version 8911 Page 2


Most of the "star map" programs I've seen or used (including
several commercial versions) were designed for the older CGA (Color
Graphics Adapter) for the PC. In my opinion, the quality of the
display is not really adequate for the job, and no one program
provided all of the information I sought. Hence was born EGASTARS. It
was designed to take advantage of the hardware available on my own
system, the principal feature of which is the EGA (Enhanced Graphics
Adapter) with a high resolution color display. With the advent of the
VGA, the program has been upgraded to take advantage of it's superior
graphics. How well my efforts have succeeded I'll leave to others to
judge.
VGASTARS works with the standard VGA 640x480 pixel screen of the
VGA Analog Monitor on the IBM PC and compatibles; it's been tested on
my Zenith Z-248, an IBM PC/AT compatible. Sorry, the program will not
work with any other display type. While I haven't checked, the program
uses quite a bit of memory and it's only been tested on systems
equipped with 640K of memory. Because of the amount of numerical
computation required, a computer of at least the capabilities of the
IBM PC-AT or compatible is definitely recommended. However, an early
version of EGASTARS was tested on a Zenith Z-151 (IBM PC/XT
compatible) and, except for being considerably slower, executed
correctly.
VGASTARS requires a number of files for proper operation. All
files must be on the current disk drive. The program automatically
detects whether or not the executing computer is equipped with a math
coprocessor and either emulates coprocessor operation or uses the
coprocessor automatically. On a Zenith Z-248 equipped with a
coprocessor, VGASTARS runs better than twice as fast when plotting
stars and doing other number crunching operations.

VGASTARS.EXE Program VGASTARS

VGASTARS.DAT Database of stars
VGASTARS.NAM List of approximately 150 brightest stars
VGASTARS.CON List of standard constellation names
VGASTARS.LIN List of constellation figure segments
VGASTARS.DOC Program documentation (this file, optional)

The database hopefully contains every star brighter than 4.5
magnitude and a selection of fainter stars that complete the
constellation figures. All star data is for Epoch J2000.0.
VGASTARS.DAT is almost identical to the star database used with
Richard Berry's program STARS.BAS. For compatibility, I have retained
the same database format, although the star order is slightly
different. [For those interested, I've corrected one apparent
constellation naming error (CNV instead of CVN), one apparent star
naming error (NU TAU should be ETATAU), and one apparent star
coordinate error (in LEP).] According to Mr. Berry's documentation
file STARS.DOC, his database is essentially the same database used for
the StarDome map printed in the center spread of ASTRONOMY every
month; I guess he should know, being the Editor-in-Chief of ASTRONOMY!
I have spent only a limited time entering the constellation
figure segments in file VGASTARS.LIN, and there are lots more to be
done. The format of the file is straightforward, for those who wish to
add their own; use the present file as a sample. VGASTARS does little
Program VGASTARS Version 8911 Page 3


checking, however, so observe the format exactly. Spaces in star names
ARE significant.
The following description of the data base format is paraphrased
from the file STARS.DOC. Each file is in standard ASCII code (except
for the constellation Bootes, where the second 'o' has an umlaut) and
may be output on the display or on a printer. Be advised that
VGASTARS.DAT lists 1573 stars (current version) and will require quite
a few printed pages! For the novice, printing the list of
constellations in VGASTARS.CON may be helpful.
VGASTARS.DAT has the following format:

GGGCCC HHMMD+DDMM +M.M +C.CC
----------------------------
GAMCAS 00567+6043 +2.4 -0.15
GA2AND 02039+4220 +2.3 +1.37
39 ARI 02479+2915 +4.5 +1.11
HR961 03203+7744 +5.5 +0.19

where GGG is the first three characters of the Greek name of the star
OR the first two characters and a superscript number OR the Flamsteed
number of the star. Alpha is ALP, beta is BET, gamma is GAM, and so
on. Omicron and Omega are abbreviated OI and OE to distinguish them.
CCC is the standard three-letter abbreviation of the constellation
name -- ORI for Orion, UMA for Ursa Major, CVN for Canes Venatici. If
the star has neither Greek letter nor Flamsteed number, then GGGCCC
becomes is "HR" plus the four-digit Yale Bright Star Catalog number.
If you aren't completely up to date on the Greek alphabet, the
following abbreviations for the Greek letters or letter/superscript
combinations have been used:

SINGLE LETTER LETTER+SUPERSCRIPT
------------- ------------------
ALP Alpha AL2 Alpha 2
BET Beta BE2 Beta 2
GAM Gamma GA2 Gamma 2
DEL Delta DE2 Delta 2
EPS Epsilon EP2 Epsilon 2
ZET Zeta ZE2 Zeta 2
ETA Eta ET2 Eta 2
THE Theta TH2 Theta 2
IOT Iota IO2 Iota 2
KAP Kappa KA2 Kappa 2
LAM Lambda LA2 Lambda 2
MU Mu MU2 Mu 2
NU Nu NU2 Nu 2
XI Xi XI2 Xi 2
OMI Omicron OI2 Omicron 2
PI Pi PI2 Pi 2
RHO Rho RH2 Rho 2
SIG Sigma SI2 Sigma 2
TAU Tau TA2 Tau 2
UPS Upsilon UP2 Upsilon 2

PHI Phi PH2 Phi 2
CHI Chi CH2 Chi 2
PSI Psi PS2 Psi 2
Program VGASTARS Version 8911 Page 4


OME Omega OE2 Omega 2

HHMMD+DDMM is the star's location in right ascension and
declination coordinates for epoch 2000. HH is hours, MM is minutes,
and D is decimal minutes of RA. +DD is declination degrees and MM is
declination minutes. The coordinates, as given, are precise enough for
virtually any computer graphics application.
+M.M is the star's visual magnitude in yellow light, essentially
how bright the star appears to the eye. The sign is necessary because
some of the brightest stars, like Sirius, have negative magnitudes.
The dimmest objects on the list are 6th magnitude.
Finally +C.CC is the B-V "color index" of the star. This number
ranges from -0.25 to +2.5. The "bluest" stars have the lower or
negative B-V color, while red stars have color indices over 1.6 or so.
The Sun has a B-V of +0.62, and is a yellow-white star. VGASTARS does
not use the color data for the current version, since color is used
for other purposes in the program.
We thus decode the examples as: Gamma Cassiopeiae, a medium-
bright blue star at 0 hours 56.7 minutes right ascension and +60
(degrees) 43' declination; Gamma-2 Andromedae as a reddish star of
approximately the same brightness; 39 Arietis doesn't have a Greek
letter name; and HR 961 is the 961st entry in the Yale Bright Star
Catalog, barely visible to the naked eye.
Program VGASTARS Version 8911 Page 5




Operating Instructions for VGASTARS


VGASTARS switches to the VGA 60-line 640x480 graphics display
mode upon entry and saves the original display mode. Upon exit, the
display will revert to 25-line mode if the system was originally set
to other than 43-line mode. It will stay in 43-line mode if it was set
to 43 lines upon entry; other display modes such as 35 or 50 lines,
which are unsupported by Microsoft QuickBASIC, will cause a return to
25-line mode upon exit.
VGASTARS begins by loading the various data files into memory,
displaying a message for each file as it is being loaded. Depending
upon the computer's speed and the type of disk drive, this may take
from approximately 10 seconds to several minutes. In order to present
a pleasing opening display, and to allow the novice user to see
something without knowing very much, VGASTARS then picks an initial
point in the sky (11 hours 9 minutes Right Ascension and +50 degrees
41 minutes Declination) and a convenient screen width (120 degrees)
which will show a major portion of the northern sky; this turns out to
be roughly centered on Ursa Major and the Big Dipper. The database is
then scanned and all stars which will appear on the display are
plotted, with those of Ursa Major shown in YELLOW. Note that the
brightness and size of the dots plotted correspond, in a rough way, to
the magnitude of the star. See the help screen (Function Key F1) for
an illustration of the way stars are plotted by magnitude.
Next, in order to help orient the viewer, VGASTARS plots a grid
of the celestial coordinates, every hour of Right Ascension (RA) from
0 hours to 23 hours, and every 15 degrees of Declination (DEC) from
+75 degrees to -75 degrees. The lines at 0 hours RA and 0 degrees DEC
are plotted in a brighter blue than the other lines. For viewers
familiar with the area of the sky being plotted, the grid display may
subsequently be turned on and off (Function Key F4), thereby
considerably reducing the plotting time.
Finally, VGASTARS draws line segments connecting the seven stars
of Ursa Major which form the familiar Big Dipper. VGASTARS then
displays its opening credits, including the current coordinates for
the red crosshair (no mouse) or mouse pointer (mouse enabled) in the
center of the screen, and reminds the viewer that Function Key F1 can
be pressed to obtain a help screen. This help screen gives a brief
explanation for many of the commands available in VGASTARS.
Because of space limitations on the screen, however, several
items are not mentioned or are explained in a very minimum manner.
First, the SPACE bar can be used to interrupt grid plotting. If, for
example, you are in the PAN mode and want to zoom in several times,
there's no point in waiting for the grid to be drawn before you enter
the next zoom in command. (Turning the grid plotting function off will
speed things up by a factor of three or so!) The rest of the time, the
SPACE bar clears the bottom status line and displays the three letter
abbreviations of any constellations which have been tagged in color.
Not everyone (including myself initially) may be familiar with
all the standard three letter abbreviations for the various
constellations. This could make it very difficult to get around in
VGASTARS, so I've included a special help function associated with
Program VGASTARS Version 8911 Page 6


Function Keys F7, F9, and F10. Just press the RETURN key when asked
for a constellation name and you'll see a complete list. There are 88
standard constellations, too many for a single screen; press again to
cycle through the list, then enter the three letter abbreviation
(upper or lower case is accepted) to display the selected
constellation. Use the ESC key to cancel the function.
I thought of a number of different ways to have VGASTARS look up
the various constellations -- and then couldn't decide which of them I
preferred. Function Keys, F7, F9, and F10, are therefore available for
locating and/or marking constellations; the descriptions on the help
screen may be just a bit cryptic. F7 simply "tags" each star of a
requested constellation for the "next" color. Colors are assigned in
the sequence YELLOW, MAGENTA, RED, CYAN, GREEN, and BLUE. (A maximum
of five constellations may be tagged at any one time.) The screen is
then repainted to show the new color, which is very rapid (less than a
second on my Zenith Z-248 plus grid drawing time). Since the stars
visible on the screen are unchanged, the newly tagged stars may or may
not be visible. Tagging a constellation in Southern sky with F7 while
looking at the Northern sky could cause such a situation. F9 also
"tags" each star in a requested constellation for the "next" color,
but it then computes a best guess for the approximate center of the
constellation and redraws the screen with that point at the center.
Previously tagged constellations may or may not still be visible on
the screen. F10 clears all previous color tags, assigns the color
YELLOW to each star of the requested constellation, computes a best
guess for the approximate center of the constellation, and redraws the
screen with that point at the center.
Using any one of the constellation functions, F7, F9, or F10,
causes VGASTARS to check the display width (shown as W=120, for
example, at the bottom right of the screen). This corresponds to the
approximate field of view in degrees, measured across the center of
the screen. Since some constellations cover a considerable arc in the
sky, the width is reset to 90 degrees if it is less than 90 degrees
and left unchanged if it is greater than 90 degrees.
The field of view may be changed using the W command. Simply
enter the desired angle, in degrees, in response to the prompt. The
screen will then be redrawn and the new width shown in the lower right
of the screen. This corresponds, more or less, to a "zoom" feature and
lets you examine the relative location of stars more closely. If the
width or field of view is 180 degrees or more, the H command will draw
the viewer's horizon on the screen in GREEN. When the width is 270
degrees or more, a complete star map of the visible sky is shown on
the screen. For example, requesting the coordinates (using Function
Key F5) of 5 hours (RA), 34 degrees (DEC), and 270 degrees width, then
pressing H to draw the horizon, will produce a star map display
corresponding to mid January at about 9 P.M. (standard time) for a
latitude roughly equal to Los Angeles. To obtain a star map
corresponding to your location, enter a Declination (DEC)
corresponding to your lattitude. North lattitude is positive, south
lattitude is negative.
Visualize the display screen upside down over your head with the
top of the screen pointing North. Alternatively, if you find this
method somewhat impractical, utilize a PrintScreen utility which will
operate properly with the VGA. If you have a Hewlett-Packard LaserJet
II, press P and the screen image will be printed (although the process
Program VGASTARS Version 8911 Page 7


is rather slow!). CAUTION: THE 'P' COMMAND WILL ONLY WORK WITH THE HP
LASERJET! Print the screen and compare it to published star maps, then
take it outside and hold it over your head with the top of the page
pointing North. For use at night, a red flashlight will enable you to
see the star map without destroying your night vision.
There are a couple of additional commands which are sometimes
useful. When you have tagged so many stars and/or constellations that
you are beginning to lose track of what is what, enter Z to clear all
color tags. If you enter R (for Redraw) just after you have identified
a star with the S command, the screen will be redrawn with that star
at the center of the screen. The SPACE BAR will interrupt star
plotting and grid drawing in progress. Be advised, however, that the
star find function (S command or left mouse button) looks for stars
that are actually plotted on the screen. If they aren't on the screen,
the star find function won't find them.
When the S command (or the left button on the mouse) is used to
identify the star nearest the crosshair or mouse pointer, the data
read from VGASTARS.NAM is searched to see if it is a commonly known
star. Approximately one hundred and fifty of the better known stars
are included. The data consists of the abbreviation for the star (such
as ALPUMI), the constellation name (in the Latin genetive case, Ursae
Minoris in this example), and the common name (POLARIS, the North
Star, in this case). Many of the brighter stars have been identified
in this way. The array which holds this data has room for 200 entries.
Use any editor to add any names you wish (non-document mode for you
WordStar users!).
When you know the Bayer designation of a star (rather than its
common name), Function Key F8 lets you enter the six letter
abbreviation for that designation and the screen is redrawn with the
requested star marked in GREEN located at the center of the screen. A
good test is ALPUMI, Alpha Ursae Minoris (better known as POLARIS, the
North Star). Try this display with the grid on (Function Key F4) to
draw the coordinate system and help you orient your view. [You might
then want to then press Function Key F7, enter UMA to display Ursa
Major in magenta, and see if you can pick out the two pointer stars in
the Big Dipper.]
Function Key F6 enables and disables the line drawing mode. When
the line drawing mode is active, a small orange UP/DOWN arrow is shown
next to the cursor mode at the lower right of the screen. To draw line
segments manually, turn on the line drawing mode with F6 then move the
cursor (or crosshair) from star to star. Press the left mouse button
or the S key at each star you wish to connect; you do not need to
point exactly to the star since VGASTARS automatically picks the star
closest to the cursor or crosshair. To stop drawing line segments,
turn off the line drawing mode with F6. If you use Function Keys F7,
F9, or F10 while the line drawing mode is on, the line segment
database is checked and if a sequence is given for the requested
constellation, it is automatically drawn. Since line segments are lost
when the screen is redrawn, use F7 to tag constellations and add their
line segments to the existing screen. If the stars are difficult to
see with the line segments drawn, use the Z command to remove the
color tags from the stars displayed.
For users without a Microsoft mouse, Function Key F2 switches the
function of the cursor keys between the CURSOR and PAN modes. (The
cursor keys are always in the PAN mode when a mouse is available.)
Program VGASTARS Version 8911 Page 8


When the screen shows CURSOR at the lower right, the arrow keys move
the red crosshair about the screen; when the screen shows PAN at the
lower right, the arrow keys move the stars in the direction shown (for
the Northern hemisphere) and PgUp zooms in and PgDn zooms out. For all
modes, HOME returns the center of the screen to the last entered
coordinates.
For users with a Microsoft mouse, ALT+F2 enables and disables the
mouse. I'm not sure why you might want to disable the mouse, but this
function helped me to debug the program in both modes. A word of
caution about mice: I have found MOUSE.COM (Version 6.0) to operate
more reliably on my system than MOUSE.SYS (also Version 6.0). I got
some really weird colors sprayed around my earlier program EGASTARS
and other programs when MOUSE.SYS was used to enable my mouse. [I have
also noted that entering MOUSE OFF at the system prompt tell me that
the mouse driver is disabled, and it does not work, but my program's
code still thinks there's a mouse present. Entering MOUSE ON brings my
mouse back to life correctly, but I have to reboot to completely
eliminate the mouse. VGASTARS then correctly tells me that no mouse
driver is present.]
Program EGASTARS included a feature for simulated animation.
Because the VGA does not provide multiple screens, one active and one
available for updating, this feature has been eliminated in VGASTARS.
Last but not least: enter Q to QUIT and return to DOS.

VGASTARS has required many hours of effort and ideas from many
places. My own enjoyment of the program has prompted me to make it
available for general use. If you wish to experiment with versions of
your own, please send a check for $10.00 (to cover postage and
handling) to me at the address below and I'll send a diskette (please
specify 5-1/4" 360K or 3-1/2" 720K DSDD MS-DOS) with the complete
program, source code and documentation. Please note that two Microsoft
products, QuickBASIC (Version 4.50) and Mouse Programmer's Reference
Guide (Version 6.0) are required to compile the source without
modifications. These Microsoft products are NOT included.
The complete program, including source, is also available on my
bulletin board system (BBS) at 213-541-7299, 2400/1200/300 baud, in
the ASTRONOMY file area. The BBS has a power controller; if it hasn't
answered by the third ring, hang up, wait TWO MINUTES, then call back.

There are still a few minor "bugs" in VGASTARS that I am aware
of, and probably a few more that I haven't discovered. I don't know of
any major problems -- at least on the equipment I've used for testing.
What started out as a simple two page program has grown to almost
twenty pages and it is inevitable that a few errors crept in during
the development and experimentation process. It may be that I'll find
and fix them in due course. If you have any comments or suggestions,
feel free to drop me a line or visit the BBS. Please do NOT telephone.
In the meantime, I hope you'll find it an enjoyable and educational
program.

David H. Ransom, Jr.
7130 Avenida Altisima
Rancho Palos Verdes, CA 90274
Program VGASTARS Version 8911 Page 9


VGASTARS Revision History

8911 03/13/89 -File VGASTARS.DAT for Version 8910 was corrupt.
File is now repaired.

8910 03/06/89 -VGA Version
-Program converted for operation with VGA. Motion
eliminated and program renamed VGASTARS.

8803 01/10/88 -Compiler Upgrade
-Program was converted from QuickBASIC Version 3.0
to Version 4.0, eliminating the need for a
separate compilation for systems with math co-
processors.
-Internal operation of EGASTARS was converted to
the EGA 43-line mode from 25-line mode.
-Several minor bugs and quirks repaired.
-Added ALT-F1 command to restart from signon
(otherwise undocumented).
Added M command for motion display using alternate
display and active screens.

8729 07/06/87 -Major Upgrade
-Various mathematical and database errors
corrected.
-Line segment and figure drawing features added.
Database EGASTARS.LIN added.
-Star lookup-by-name feature added.
-Code optimized for improved drawing speed.
-8087/80287 version added.

8728 06/28/87 -Initial Release.
[Beta Versions 8728A and 8728B were also
distributed on a limited basis.]

8727 06/22/87 -Initial EGASTARS Beta Test Version.