Simtel MSDOS - Coast to Coast/simteldosarchivecoasttocoast2.iso/astrnomy/sfs101.zip/SFS.RO

Text File | 1991-10-21 | 75KB | 1,946 lines

..    \"===================================================
..    \"
..    \"    sfs.ro
..    \"
..    \"    documentation for Space Flight Simulator
..    \"    copyright (c) 1991, Ted A. Campbell
..    \"
..    \"
..    \"    NOTE: this documentation is in a format com-
..    \"    patible with the "ro" text formatter. The file
..    \"    sfs.doc is an ASCII output version of this file
..    \"    with no formatting marks.
..    \"
..    \"    To print this file to an ANSI terminal, use:
..    \"
..    \"        ro -Tansi.tab sfs.ro | more
..    \"
..    \"    To send it with no underline or bold to a
..    \"    printer, use:
..    \"
..    \"        ro -Tnull.tab sfs.ro >prn
..    \"
..    \"    For further details on ro usage and formatting,
..    \"    see the ro documentation.
..    \"
..    \"===================================================
.so tmac.m
..    \"===================================================
..    \"    String "V" -- current version number
.ds V "1.01"
..    \"===================================================
..    \"    String "Y" -- copyright year
.ds Y "1991"
..    \"===================================================
..    \"    Page Headers and Footers
.PF "''''"
..    \"===================================================
.sp 12
.ce
Bywater Software
.sp 2
.ce
SPACE FLIGHT SIMULATOR
.sp 5
.ce
Version \*V
.sp 2
.ce
Copyright (c) \*Y,
.ce
Ted A. Campbell
.sp 4
.ce
Bywater Software
.ce
P. O. Box 4023
.ce
Duke Station
.ce
Durham, NC  27706
.sp 2
.ce
email: [e-mail]
.SK
.PF "''Page  #''"
.sp 4
.ce
CONTENTS
.sp 4
.nf
.ne 6
0. Quick Start Information ..................................

.ne 6
1. Introduction .............................................

   1.1 Description ..........................................
   1.2 Copyright and Distribution Information ...............
   1.3 Hardware Requirements ................................
   1.4 Unpacking SFS ........................................
   1.5 Starting SFS .........................................
   1.6 Exiting SFS ..........................................
   1.7 Running the Default SFS Program ......................

.ne 6
2. Developing Orbital Simulations ...........................

   2.1 Selecting a SFS Program File .........................
       2.1.1 Using Bywater UI Menus .........................
   2.2 The Main Modeling Menu ...............................
       2.2.1 Set Program Title ..............................
           2.2.1.1 Using Bywater UI Dialogue Boxes ..........
       2.2.2 Set Current Orbit ..............................
           2.2.2.1 Mass of the Orbital Focus ................
           2.2.2.2 Radius of the Orbital Focus ..............
           2.2.2.3 Sidereal Period of the Orbital Focus .....
           2.2.2.4 Semiminor Axis of the Orbit ..............
           2.2.2.5 Eccentricity of the Orbit ................
           2.2.2.6 Orbital Period ...........................
.ne 6
       2.2.3 Set Orbital Parameters .........................
           2.2.3.1 Set Orbital Focus ........................
           2.2.3.2 Set Orbit/Spacecraft Name ................
           2.2.3.3 Set Surface Datafile .....................
           2.2.3.4 Set Orbital Periapsis ....................
           2.2.3.5 Set Orbital Apoapsis .....................
           2.2.3.6 Set Orbital Inclination ..................
           2.2.3.7 Set Argument of the Periapsis ............
           2.2.3.8 Set Longitude of the Ascending Node ......
           2.2.3.9 Exit from Orbital Parameters Menu ........
       2.2.4 Set Insertion Parameter ........................
.ne 6
       2.2.5 Set System Parameters ..........................
           2.2.5.1 Set Time Factor ..........................
           2.2.5.2 Set Screen Update Interval ...............
           2.2.5.3 Set Trig Precision Level .................
           2.2.5.4 Exit from System Parameters Menu .........
       2.2.6 View Current Orbit .............................
       2.2.7 Exit from Main Modeling Menu ...................

.ne 6
3. Advanced Control of the Simulation Module ................

.ne 6
   3.1 Simulation Module Information Panels .................
.ne 6
   3.2 Simulation Module Displays ...........................
       3.2.1 The Visual Simulation ..........................
       3.2.2 The Ground Track Display .......................
       3.2.3 The Distant Perspective Display ................
.ne 6
   3.3 The Escape Menu ......................................
       3.3.1 Changing the Display ...........................
       3.3.2 Changing System Parameters .....................
       3.3.3 Exits from the Simulation Module ...............
.ne 6
   3.4 Simulation Module Toggles ............................

.ne 6
4. Compiling SFS ............................................

.ne 6
   4.1 File and Directory Hierarchies .......................
.ne 6
   4.2 Using Script Files to Build SFS ......................
.ne 6
   4.3 Include Files ........................................
.ne 6
   4.4 Implementing the Input/Output System and the UI ......
       4.3.1 Implementing the Graphics (gr) System ..........
       4.3.2 Implementing the Keyboard (kb) System ..........
       4.3.3 Implementing the Directory (dr) System .........
       4.3.4 Building the User Interface (ui) ...............
.ne 6
   4.5 Compiling the Space Flight Simulator .................

.ne 6
5. SFS Data File Formats ....................................

.ne 6
   5.1 SFS Program Files (*.sfs) ............................
   5.2 Focal Data Files (*.fd) ..............................
   5.3 Spherical Projection Data Files (*.spd) ..............

.ne 6
6. The MAP Utility ..........................................

.ne 6
   6.1 Change Position ......................................
   6.2 Enter Title or Comments ..............................
   6.3 Begin Sequence .......................................
   6.4 Set Default Attitude .................................
   6.5 Exit .................................................

7. Communications ...........................................

.fi
.PH "''''"
.PF "''Page  #''"
.SK
.sp 4
.ce
QUICK START INFORMATION
.sp
.TA
.TZ
.BA
If you have the executable \fIPC version\fR of the Space Flight
Simulator and want a quick start, copy all the files (possibly
from two 5.25" diskettes) into one directory. Change to this
directory, and enter "sfs" to run the program. If you are using
Hercules (tm) graphics, you must run the program "msherc" before
running "sfs." The program is menu-driven, and should largely be
self-explanatory from this point.
.P
If you are planning to install the Space Flight Simulator on a
\fIUnix\fR or other system, the program will have to be compiled
(and possibly implemented for your system). Implementations
currently exist for Unix based systems using the X Windows
system, and for the AT&T Unix PC (tm). Turn to chapter four for
further information on compiling the software.
.BZ
.TA
.TZ
.SK
.PH "''''"
.PF "''Page  #''"
.sp 4
.ce
Chapter 1
.sp
.ce
INTRODUCTION
.PH "'SFS \*V'Chapter 1'Page #'"
.sp 3
.TA
.na
.ne 5
.ce
1.1 \fBDescription\fR
.P
The development of microcomputers has been directly related to
the progress of the U.S. and Soviet space programs. Not only did
the space programs demand increasing miniaturization of computer
hardware and software, thus preparing the way for the
development of microcomputers, but they also began to develop
software techniques for spacecraft tracking and eventually
visualization. It is not surprising, then, that computers and
space technology are closely associated in the minds of many
people.
.P
The Space Flight Simulator by Bywater Software offers a means of
simulating orbital flight, and since all space flight is, one
way or another, orbital flight, it can appropriately be called a
"space flight simulator." The fact of the matter is, however,
that orbital flight involves a fair degree of mathematics, and
once an orbit has been selected space flight does not at all
involve the kind of instantaneous (and personal) "piloting" that
makes atmospheric craft (airplanes, jets, helicopters) exciting.
Orbital Flight, that is, can be dull by comparison.
.P
Bywater's Space Flight Simulator can keep track of a number of
orbital spacecraft (simultaneously) in its current version, and
offers three visual representations of orbital flight: a ground
track map (of all orbits around a particular orbital focus, such
as the earth or the moon), a "visual simulation" showing the
orbital focus as it might appear from the space craft, and a
"distant perspective" that shows all orbits around a particular
focus.
.TZ
.BA
\fIRoom for Improvement\fR. The Space Flight Simulator does not
yet have the capability of calculating and executing transfer
orbits, or transfers from one orbital focus to another (e.g.,
from the earth to the moon). These are areas for future
development of the program.
.BZ
.TA
.P
The Space Flight Simulator has two principal parts: a modeling
module (including the main program menu) that allows the
development of particular orbital models, and a simulation
module that attempts to display the orbits selected in real
time. The program begins by displaying a main menu that allows
the user to select a previously written SFS program file, alter
a SFS program file, proceed to orbital simulation, or exit the
program. This document attempts to explain the various options
available to the SFS user.
.sp 2
.ne 5
.PF "''''"
.ce
1.2 \fBCopyright and Distribution Information\fR
.P
The Space Flight Simulator is distributed under the following
agreement:
.TZ
.BA
.P
All U.S. and international copyrights are claimed by the author.
The author grants permission to use this code and software based
on it under the following conditions:
.P
(a) in general, the code and software based upon it may be used
by individuals and by non-profit organizations;
.P
(b) it may also be utilized by governmental agencies in any
country, with the exception of military agencies;
.P
(c) the code and/or software based upon it may not be sold for a
profit without an explicit and specific permission from the
author, except that a minimal fee may be charged for media on
which it is copied, and for copying and handling;
.P
(d) the code must be distributed in the form in which it has
been released by the author;
.P
and (e) the code and software based upon it may not be used for
illegal activities.
.BZ
.TA
.P
This answers roughly to what some call a "freeware" agreement.
One can use the program as one wishes for non-profit, peaceful,
and legal purposes, one can copy it freely and give it to
whomever one pleases, and the author expects no compensation for
these uses. Users are not allowed to sell the program, to use it
for military uses, or to use it for illegal activities. I am not
naive, actually, but I do not consent for my program to be used
for these purposes.
.sp 2
.ne 5
.ce
1.3 \fBHardware Requirements\fR
.P
CPU and Coprocessor (MSDOS version):  SFS version \*V will run
under MSDOS or PCDOS on any of the 8088 and upwardly-compatible
CPUs.  Speed of the processor is critical in this program. The
presence of a math coprocessor will be automatically detected by
the program, and will also greatly enhance the performance of
the program.
.P
Graphics (MSDOS version):  SFS version \*V is configured to work
with Hercules (tm), EGA, or VGA graphics, and must support at
least two pages of memory.  Because CGA does not allow multiple
pages of video memory, it cannot be used. The program
automatically detects these graphics systems, except the
Hercules-type cards.  For systems with Hercules-compatible
graphics, run the program "msherc.com" first.
.TZ
.BA
What about CGA graphics? Actually, SFS will try to run on these
systems, but the result will not be very attractive, for two
reasons: (a) the fonts are too coarse to be read easily and will
probably overwrite each other, and (b) the lack of paged memory
will mean that the system will write all over the existing
screen in simulation mode, very sloppy.
.BZ
.TA
.sp 2
.ne 5
.ce
1.4 \fBUnpacking SFS\fR
.P
Before using the Space Flight Simulator it is necessary to copy
all the binary and data files to a single directory, preferably
on a hard disk drive.  SFS is distributed in two different
forms: (a) executable binaries (with supporting data files) for
the IBM PC and compatible computers, and (b) C source code (also
with supporting data files) to be compiled on Unix computer
systems, at this point supporting the X windows system and the
AT&T Unix PC "tam" interface library.
.P
The PC (binary) version may be archived utilizing one of a
number of different archiving systems. Documentation for the
archiving system should explain how to extract the files. Also,
note that the PC binary version will not fit on a single 5.25"
floppy diskette, so that binaries and data from 5.25" diskettes
will have to be copied to a single directory on a hard disk
drive (or possibly to a single 720k or larger diskette).
.TZ
.BA
Does the Space Flight Simulator require a hard disk drive? SFS
will run, in fact, on a single 720k diskette (thus, on a 720k
3.5" drive, or possible a 1.2 megabyte 5.25" diskette), but the
PC versions require the reading of the disk drive every time a
font must be changed. This can be extremely time consuming, and
is why the use of a hard disk drive is recommended.
.BZ
.TA
.P
The source code for SFS will be supplied in the form of Unix
"sh" archives. File headers and tails should be removed, then
the files should be executed with "sh" to extract the individual
source code files and data files. See chapter 4 below on
compiling SFS.
.sp 2
.ne 5
.ce
1.5 \fBStarting SFS\fR
.P
To run SFS version \*V on most computers (including
PC-compatible computers with EGA and VGA graphics), simply type
.nf
    sfs<RET>
.fi
(<RET> denotes a carriage return).  To run the program on a
PC-compatible computer with Hercules graphics, first run the
program "msherc." The following commands will run the program
with Hercules graphics:
.ls 1
.nf

    msherc<RET>
    sfs<RET>

.ls 2
.fi
The sfs program will load the menu and modeling module
(sfsm.app). It will then display the SFS logo (which will remain
on the screen for a few seconds), after which it will show the
main sfs menu.
.TZ
.BA
\fINote for Advanced Users\fR:  The name of an SFS program file
(see below) can be specified on the SFS command line.  For
instance,
.nf
    sfs moon.sfs
.fi
will start the program using "moon.sfs" for its initial program
data.
.BZ
.TA
.sp 2
.ne 5
.ce
1.6 \fBExiting SFS\fR
.P
From the main SFS menu a number of different options may be
selected. The SFS main menu is one of a number of menus that
work similarly (they all employ the Bywater Grpahical User
Interface). The up and down arrow keys can be used to select
items, then <ENTER> or <RETURN> will execute a selected item.
With a mouse, click once on an item to select it, then click a
second time to execute it. There may be unseen menu items above
or below the current position; to expose these use the window
sliders or arrows with the mouse. (See 2.1.1 below for more
information on Bywater UI menus.)
.P
The last item on the SFS main menu is an the exit from the
program. Select and execute this item to return to the operating
system.
.sp 2
.ne 5
.ce
1.7 \fBRunning the Default SFS Program\fR
.P
To run the default SFS program (a view of the earth from an
orbiting spacecraft), enter the SFS program described above
(with no command line argument; just "sfs"). From the main SFS
menu, select and execute the "Visual Simulation" item. This will
begin running the default program.
.P
The screen will go entirely blank for a while. Don't panic: SFS
is a fairly large program, and had to be divided into a few
smaller pieces. The sfs (under MSDOS, "sfs.exe") program itself
is very small and only loads the two main programs:
.ls 1
.nf

      sfsm.app (which contains the main menu
               and the modeling module), and

      sfsx.app (which contains the simulation module).

.fi
.ls 2
When the screen goes blank, sfsm.app has relinquished control to
sfs (sfs.exe), which is loading sfsx.app. In a moment or two the
simulation module will appear on screen.
.P
After the simulation module shows the program logo, it reads in
maps and data about the object(s) to be orbited. Then it has to
make some initial calculations. After a while (depending greatly
on the speed of a computer, and whether it has a math
coprocessor), two windows will open on the screen. A simulation
of the orbital focus (probably the earth) as seen from the
spacecraft will appear in the top window, and a ground track map
will appear in the bottom window. After a while (again,
depending on the speed of the computer at performing
trigonometric calculations), the visual simulation will appear
in the upper window and will change as the spacecraft continues
on its path (as indicated in the lower window).
.P
To exit from the simulation module, either press <ESCAPE> or
click the mouse once on the top bar of the screen. This will
bring up the simulation module escape menu in the middle of the
screen, and it is used just like the main SFS menu described
above (and in 2.1.1 below). The last item on the main simulation
menu will allow a return to the main SFS menu. If this option is
chosen, the screen will again go blank (while sfs loads
sfsm.app). The program can then be exited altogether by choosing
the last (exit) item from the main SFS menu. Alternatively, the
next to last item on the main simulation menu is a short cut to
exit from SFS altogether (i.e., without reloading the main menu
and modeling module, sfsm.app).
.TZ
.PH "''''"
.SK
.sp 4
.ce
Chapter 2
.sp
.ls 1
.ce
DEVELOPING ORBITAL SIMULATIONS:
.ce
THE MAIN MENU AND MODELING MODULE (sfsm.app)
.ls 2
.PH "'SFS \*V'Chapter 2'Page #'"
.PF "''Page  #''"
.sp 2
.TA
.na
.ne 5
.P
The main menu and modeling module are contained within the
executable file "sfsm.app" which is first loaded by "sfs"
("sfs.exe" in the PC version). The main menu allows users to set
an appropriate SFS program file, to go to the modeling menu, to
run the simulation, or to exit from the program. The modeling
module allows users to develop and customize their own SFS
programs. We begin with a discussion of the menu items available
from the main menu.
.sp 2
.ne 5
.ce
2.1 \fBSelecting a SFS Program File\fR
.P
The first item on the main menu allows users to select a SFS
program file. These files have the extension "*.sfs". A number
are supplied with the program, and users can develop their own
simulations using the modeling menu (see below). When a user
selects this option from the main menu, she is provided with a
menu listing all SFS program files found in the current
directory. The user selects (see below) the file wanted, and
will then return to the main menu.
.sp 2
.ne 5
2.1.1 Utilizing Bywater User Interface Menus
.P
Since both the main menu and the program selection menu utilize
the Bywater User Interface menu system, a word is needed at this
point on the use of this menuing system. The Bywater User
Interface menu presents the user with a list of menu items to be
selected. The menu can be controlled either by a pointer device
(such as a mouse or track ball) or by the computer's arrow keys.
Using the \fIarrow keys\fR, the UP and DOWN keys will move
through the various menu items, highlighting the current item.
Use the RETURN or ENTER key to select a particular item. If
there are items below the bottom item (moving down) or above the
top item (moving up), the menu items will be scrolled as the
keys move above or below the currenly shown items. Using a
\fIpointer device\fR (mouse or track ball), place the cursor on
the item to be selected and click once (down and up on the
pointer device button). Once an item has selected, the user can
either select a different item by pointing and clicking, or
choose the selected item by clicking on it a second time.
.PF "''''"
.P
The pointer device is not capable of scrolling up and down
simply by pointing at menu items. For this reason, some of the
menus will have scroll bars and arrows that the pointer device
can use. Pressing an arrow area (up, down, left, or right,
although left and right are irrelevant to the Spavce Flight
Simulator, since it only uses vertical menus) will cause the
menu items to be scrolled in that direction. Alternatively, one
can press the pointer button on the "elevator" in the scroll
bar, then release the button at a higher or lower position in
the scroll bar. This will cause the screen to scroll in the
appropriate direction. Using the scroll bars, a user can scroll
instantly from the top to the bottom (and vice versa) of a menu
list very quickly.
.sp 2
.ne 5
.ce
2.2 \fBThe Orbital Modeling Menu\fR
.P
The orbital modeling menu allows users to develop and customize
their own SFS programs. A number of orbital parameters can be
set, and certain aesthetic features can be controlled.
.sp 2
.ne 5
2.2.1 Set Program Title
.P
The first option from the modeling menu allows the user to set a
title for the program one is developing. After selecting this
item, the user is presented with a dialogue box (see 2.2.1.1
below) for entering the title. Although there is theoretically
no limit to the length of the title, none of the SFS programs
can display more than a few words of titles, so users are
advised to make their titles rather short.
.P
To begin a new SFS program, a user simply starts with an old
one, and then alters the parameters for the new program. When a
user exits from the orbital modeling menu, she can specify a new
filename under which the program can be stored.
.sp 2
.ne 5
2.2.1.1 Using Bywater User Interface Dialogue Boxes
.P
Dialogue Boxes will be encountered at several points in the
Space Flight Simulator. A dialogue box will prompt the user for
a text string. Enter the string from the keyboard, concluding it
with a RETURN or ENTER. Although it is possible to write beyond
the bounds of the dialogue box, the area written over beyond the
bounds of the box will not be restored when the dialogue box is
completed. The user can use the BACKSPACE key to correct errors
if they are made in a dialogue box session.
.sp 2
.ne 5
2.2.2 Set Current Orbit
.P
The Space Flight Simulator can simulate a number of orbits
(around multiple orbital foci) concurrently. Orbital parameters
have to be set for one orbit at a time; consequently the user
must select which orbit she wishes to work on, and the "set
current orbit" item (the second item in the orbital modeling
menu) allows this. After selecting this menu item, the user is
presented with a dialogue box and is prompted for an orbit
number. Enter the number, then the program will return to the
orbital modeling menu.
.P
When a new program is initialized, only one orbit (number 1) is
available. If a user selects a different orbit than those
available, the new orbit is initialized with a set of default
orbital parameters before returning to the orbital modeling
menu. The user is not required to enter new orbits in sequence,
so that one could conceivably have a simulation with three
orbits with numbers 1, 5, and 9, but it makes conceptual sense
to proceed in sequence.
.TZ
.BA
\fIRoom for Improvement\fR. At this point, there is no display
showing how many orbits have already been initialized in a given
program, and there is no provision from deleting an orbit from a
program. Both of these matters may be addressed by looking
directly at the program file (*.sfs) with an ASCII text editor
(see the file format information in 5.1 below).
.BZ
.TA
The Space Flight Simulator displays (in the lower right-hand
corner of the orbital modeling screen a list of information
concerning the selected orbit. Although it appears in the form
of a Bywater UI menu, it is read-only information, and is
updated whenever new orbital data is entered. The information in
this display is as follows.
.sp 2
.ne 5
2.2.2.1 Mass of the Orbital Focus
.P
The mass of the orbital focus (the object around which this
orbit is focused) is given in grams, as read from the focal data
file (see 5.2 below).
.sp 2
.ne 5
2.2.2.2 Radius of the Orbital Focus
.P
The (average) radius of the orbital focus is given in
kilometers, as read from the focal data file (see 5.2 below).
.sp 2
.ne 5
2.2.2.3 Sidereal Period of the Orbital Focus
.P
The sidereal period of the orbital focus (the period in which it
completes one revolution in relation to the stellar background)
is given in seconds, as read from the focal data file (see 5.2
below).
.sp 2
.ne 5
2.2.2.4 Semiminor Axis of the Orbit
.P
The "semiminor axis" of an orbit is one of the six classical
orbital elements and represents a distance (in kilometers) of
one half of the smallest diameter of the orbit. It is calculated
on the basis of orbital parameters entered in the orbital
parameters menu.
.sp 2
.ne 5
2.2.2.5 Eccentricity of the Orbit
.P
The "eccentricity" of an orbit is one of the six classical
orbital elements and represents the ratio between the semiminor
and semimajor axes of the orbit. An eccentricity of "0" denotes
a perfectly circular orbit, whereas a higher eccentricity (1.0
is the maximum) denotes a greater difference between semiminor
and semimajor axes. The eccentricity is calculated on the basis
of orbital parameters entered in the orbital parameters menu.
.sp 2
.ne 5
2.2.2.6 Orbital Period
.P
The period of an orbit is one of the six classical orbital
elements and represents the time (in seconds) to complete one
revolution around the orbital focus. The orbital period is
calculated on the basis of orbital parameters entered in the
orbital parameters menu.
.sp 2
.ne 5
2.2.3 Set Orbital Parameters
.P
[Discussion now returns to the orbital modeling menu.] The third
option in the orbital modeling menu is the "set orbital
parameters" item. After selecting this item, the orbital
modeling menu itself will be deactivated, and an orbital
parameters menu will be activated in the top right-hand corner
of the screen. This menu allows the user to set specific
parameters for the currently selected orbit.
.sp 2
.ne 5
2.2.3.1 Set Orbital Focus
.P
The orbital focus is the object around which a satellite orbits.
The Space Flight Simulator is supplied with a number of files
(with extention "*.fd") that give focal data for astronomical
objects (see section 5.2 below for a description of focal data
files). After selecting this item from the orbital parameters
menu, the user is presented with a Bywater UI menu showing all
the focal data files in the current directory. One of these must
be selected.
.TZ
.BA
\fIRoom for Improvement\fR. The Space Flight Simulator does not
offer in this revision a facility for creating new focal data
files. The user can create these directly by using an ASCII text
editor (see 5.2 below for information on the file format).
.BZ
.TA
.sp 2
.ne 5
2.2.3.2 Set Name of Orbit/Spacecraft
.P
The user can enter a name for the spacecraft (or a particular
orbit) which will appear on some of the simulation screens.
After selecting this item, the user is presented with a Bywater
UI dialogue box (see above), in which the name should be
entered. Again, there is a limit to the number of words that the
programs can be displayed, so a short title is to be preferred.
.sp 2
.ne 5
2.2.3.3 Set Surface Datafile
.P
It is possible to utilize different surface datafiles (extension
"*.spd", for "spherical projection data"), even for the same
orbital focus. The earth ("earth.spd") is the only object for
which significant surface data is available at this time. The
file "null.spd" is a null which can be used in other cases. In
these cases, only the latitude-longitude grid will be shown.
After selecting this item, the user will be presented with a
Bywater UI menu, from which a surface data file can be selected.
.TZ
.BA
\fIAdvanced Use\fR. The Space Flight Simulator has a special
program (the map utility) which allows users to enter their own
spherical projection data and thus create spherical projection
data files (e.g., to show maps of planets, etc.). The map
utility is not supplied with the executable versions of SFS, and
will be released separately. See Chapter 5.3 below for further
information on the SPD file format, and Chapter 6 below for further
information on the MAP utility.
.BZ
.TA
.sp 2
.ne 5
2.2.3.4 Set Orbital Periapsis
.nf
    Default:  0.1 x the radius of the focus
.fi
The "periapsis" (also referred to by the specific term "perigee"
for terrestrial orbits) is the lowest point in an orbit. Any
positive number of kilometers lower than or equal to the
apoapsis can be specified for the periapsis, although
terrestrial orbits below about 250 kilometers begin to run into
serious problems with atmospheric drag. (SFS does not account
for atmospheric drag.)
.sp 2
.nf
2.2.3.5 Set Orbital Apoapsis
.nf
    Default:  4 x the radius of the focus
.fi
The "apoapsis" (also referred to by the specific term "apogee"
for terrestrial orbits) is the highest point in an orbit. Any
positive number of kilometers greater than or equal to the
periapsis can be specified.  An orbit having an equal apoapsis
and periapsis will be perfectly circular; all other orbits will
be elliptical.  The greater the difference between the two, the
greater will be the "eccentricity" of the orbital ellipse.
.P
It may be helpful to remember, as a rule of thumb in setting
terrestrial orbital altitudes, that the altitude of the moon is
378,014 kilometers, and this can serve as a practical limit for
terrestrial orbits, since relatively small spacecraft or
satellites beyond this range would be controlled more by the
gravitational effect of the sun than by the earth.
.sp 2
.ne 5
2.2.3.6 Set Orbital Inclination
.nf
    Default:  25 degrees
.fi
The "inclination" of an orbit is the amount that the orbit is
inclined or "tilted" away from the equator of the orbital focus.
The inclination must be specified in degrees between 0 and 180.
An orbit having an inclination of 0 is "equatorial," that is,
it follows the equator of the orbital focus.  An orbit with an
inclination of 90 degrees is "polar," that is, it will go over
the north and south poles of the orbital focus every orbit.
.sp 2
.ne 5
2.2.3.7 Set Argument of the Periapsis
.nf
    Default:  0 degrees
.fi
The next two orbital parameters are somewhat more difficult to
understand, but can be mastered by experimenting with different
settings.
.P
The "argument of the periapsis" is the point in the orbit where
periapsis occurs, measured in degrees (0-360) from the point of
the "ascending node," which is the point in the orbit where the
ground track crosses the equator, moving in a northward
direction.
.P
For a non-equatorial orbit, the argument of the periapsis will
have the following general effects:
.TZ
.BA
\fI0\fR Periapsis will occur at the point over the equator where
the spacecraft crosses it heading northward, and apoapsis will
occur at the point over the equator where the spacecraft crosses
it heading southward (0 is the default setting).
.P
\fI90\fR Periapsis will occur at the northernmost point in the
orbit, and apoapsis will occur at the southernmost point.
.P
\fI180\fR Periapsis will occur at the point over the equator
where the spacecraft crosses it heading southward, and apoapsis
will occur at the point over the equator where the spacecraft
crosses it heading northward.
.P
\fI270\fR Periapsis will occur at the southernmost point in the
orbit, and apoapsis will occur at the northernmost point.
.BZ
.TA
.sp 2
.ne 5
2.2.3.8 Set Longitude of the Ascending Node
.nf
    Default:  0 degrees longitude
.fi
.P
The "longtude of the ascending node" is the point on the focal
equator at which ascending node occurs.  For SFS, the longitude
of the ascending node is specified in degrees (-180 to 180),
with west negative and east positive.
.P
The longitude of the ascending node changes each orbit, so what
is set here is the longitude for the first orbit.
.P
SFS calculates orbits beginning at periapsis; consequently,
either the argument of the periapsis or the longitude of the
ascending node (or the insertion parameter -- see below) can be
altered to change what portion of the focus will be displayed
when the program begins.
.TZ
.BA
\fIExamples\fR:  (a)  The default settings have the argument of
the periapsis at 0 degrees (periapsis over the equator), and the
longitude of the ascending node at 0 degrees. For a terrestrial
orbit (the default), this means that the orbit will begin at
latitude 0, longitude 0, which is just off the coast of West
Africa.  The orbital direction will be northeastward, so one
will first see the African continent, the Mediterranean Sea, and
Europe beyond them.
.P
(b) By retaining all the default settings except the longitude
of the ascending node, and by setting it to -120 degrees, the
orbit will begin at periapsis over the equator, latitude 0 and
longitude -120, which is just off of the western coast of
Central American.  Since, again, the orbital direction is
northeastward, one will first see Mexico and North America in
the visual display.
.BZ
.TA
.sp 2
.ne 5
2.2.3.9 Exit from Orbital Parameters Menu
.P
The last item in the orbital parameters menu allows the user to
return to the orbital modeling menu. The orbital parameters menu
will be deactivated, and the orbital modeling menu reactivated.
.sp 2
.ne 5
2.2.4 Set Insertion Parameter
.P
.nf
    Default:  0 seconds
.fi
.P
The "point of insertion" is the moment in the first orbit when
the orbit begins. Imagine a rocket or spaceplane delivering a
spacecraft to a certain altitude where the spacecraft would take
up the orbital track -- this would be the point of insertion.
The moment of insertion is specified in seconds from periapsis,
and is limited by the orbital period (which is given on this
screen).
.TZ
.BA
\fIExample\fR:  If one wants to begin by seeing the orbital
focus from apoapsis, one should specify the insertion moment as
one half of the orbital period.  If the period is 60000 seconds,
one should set the moment of insertion to 30000 seconds and the
program will effect insertion at apoapsis.
.BZ
.TA
.sp 2
.ne 5
2.2.5 Set System Parameters
.P
.P
The system parameters menu allows a user to set three parameters
controlling the manner in which calculations are made and the
screen is updated.  Note that one can also change the system
parameters later, while the program is running, but it is best
to specify system parameters from the beginning.
.sp 2
.ne 5
2.2.5.1 Set Time Factor
.P
.nf
    Default:  1 x real time
.fi
.P
The "time factor" is the ratio of flight time to real time. If
the time factor is set to one (the default), the program will
try to run in real time).  If the time factor is set to two, the
program will calculate two flight seconds for every real second,
and so forth.  Increasing the time factor allows users to speed
up the orbital progress.
.sp 2
.ne 5
2.2.5.2 Set Screen Update Interval
.P
.nf
    Default:  15 seconds
.fi
.P
The "screen update interval" denotes the number of real-time
seconds between each update of the screen.  Users need to find
out, by experimentation, what the best update interval is for
their computer systems.  The default 15 second rate works
nominally on a computer with a 10 mhz 8088 CPU and no math
coprocessor.  An 80286 machine with a math coprocessor can
easily make a 5 second update interval.  A Unix workstation such
as the DecStation 2100 (tm) can make a 2 second rate, thus allowing
an extremely smooth animated effect. Slower computers may not be
able to keep up with the 15 second update interval rate.
.sp 2
.ne 5
2.2.5.3 Set Trig Precision Level
.P
.nf
    Default:  1 (fast)
.fi
.P
The "trig precision level" specifies the level of accuracy at
which trigonometric functions are calculated by the program.
Trig functions take up most of the processing time for the
program, so by default SFS utilizes a look-up table for
calculating trig functions.  By specifying "2 (precise),"
however, one can force the program to perform much more accurate
(and much slower) trig calculations.  The look-up tables work
acceptably well, so we would recommend setting the trig
precision level to 2 only if a math coprocessor is present.
.sp 2
.ne 5
2.2.5.4 Exit from System Parameters Menu
.P
The last item in the system parameters menu returns the user to
the orbital modeling menu.
.sp 2
.ne 5
2.2.6 View Current Orbit
.P
[Discussion now returns to items in the orbital modeling menu.]
The "View Current Orbit" item, next to last in the orbital
modeling menu, allows the user to see a simulation of the
orbital focus with orbits around it. This display is equivalent
to the "distant perspective" display in the simulation module
(see 3.2.3 below). When this item is selected, SFS has first to
calculate the parameters for the display, then the display is
drawn in the background memory, and finally it is blitted to the
screen. NOTE that the display window for the "View Current
Orbit" display (the window at the bottom left) is normally
blanked, and will be blanked again after any parameters are
changed (because the display would no longer be appropriate).
.sp 2
.ne 5
2.2.7 Exit from Orbital Modeling Menu
.P
The last item in the orbital modeling menu returns the user to
the main SFS menu. When exiting, the user is asked whether she
wishes to save the parameters entered (or altered). The user
must answer "Yes" to the prompt to save the work done, and then
she is prompted for a filename. By simply pressing RETURN, the
current filename will be used. However, if a user has begun with
a previously existing SFS program and altered it, the user may
wish to enter a new filename at this point. Remember to end the
filename with ".sfs", or the item of the main menu which selects
SFS program files will not recognize the filename as a program
file.
.TZ
.PH "''''"
.SK
.sp 4
.ce
Chapter 3
.sp
.ce
ADVANCED CONTROL OF THE SIMULATION MODULE
.PH "'SFS \*V'Chapter 3'Page #'"
.PF "''Page  #''"
.sp 2
.TA
.na
.ne 5
.P
Although chapter one gave an indication of how a simple SFS
program could be viewed using the simulation module, there is a
range of controls available to the user of the simulation
module. This chapter explains the use of these controls. It is
important to remember, however, that once the simulation module
is entered the basic parameters for the orbit are set, and one
must exit to the modeling module to change basic parameters.
.sp 2
.ne 5
.ce
3.1 \fBSimulation Module Information Panels\fR
.P
The simulation module constantly updates a number of information
panels in the display. At the very top of the display, on the
left-hand half of the top window bar, is the program name and
version. The right-hand half of the top bar is a message area
where the user may look for a clue as to available options.
.P
On the left-hand side of the display are three information
panels, one on top of each other. The top panel gives the title
and description of the SFS that is currently being executed. The
middle panel gives timing information as the simulation
progresses. The top item in the timing display panel is the
simulated time expressed as Coordinated Universal Time (UTC).
The second item is local time, but this will differ from UTC
only if one has set the "TZ" environment variable to indicate
your timezone's difference from Coordinated Universal Time.
.TZ
.BA
\fISetting the "TZ" Environmental Variable\fR.  If you want the
system to set UTC correctly based on your internal clock, you
need to set the environmental variable TZ before running the
program.  A sample command, which might be included in your
".profile", ".login", or "autoexec.bat" file would be:
.nf

    set TZ=EST5EDT

.fi
which would set the system for the Eastern time zone of the U.S.
Other North American settings would be:
.nf

    set TZ=CST6CDT
    set TZ=MST7MDT
    set TZ=PST8PDT

.fi
for Central, Mountain, and Pacific time zones, respectively.
(Note that for some Unix systems, the command "set" is
unnecessary. Unix users will have to learn how to set
environmental variables on their respective systems.)
.BZ
.TA
The next two lines after the simulated time lines give Mission
Elapsed Time (MET) expressed as hours, minutes, and seconds, and
as days. The lowest of the three information panels at the left
is a status panel that will be updated frequently, informing the
user what SFS is currently doing.
.sp 2
.ne 5
.PF "''''"
.ce
3.2 \fBSimulation Module Displays\fR
.P
The simulation module offers three different types of displays
which can be selected by the user through the simulation module
escape menu (see 3.3 below). When tracking multiple orbits, the
user may even choose to view two displays of the same type, but
with different orbital foci or orbits. (For example, if tracking
two terrestrial satellites concurrently, visual simulation
displays for each satellite could be displayed in the upper and
lower display windows.) The three display types are described in
this section.
.sp 2
.ne 5
3.2.1 The Visual Simulation
.P
The visual simulation offers the user a simulation of how the
orbital focus would appear from the spacecraft. For an orbital
focus for which there is relatively complete surface information
(such as the earth), the display will show a considerable amount
of detail. For other orbital foci for which there is not surface
data (such as Pluto) or for which surface data is irrelevant
(such as the Sun), a simple latitude-longitude grid for the
focus will be shown. The focus will be seen to grow larger in
the display as the spacecraft approaches periapsis, and will
seem to grow smaller as the spacecraft approaches apoapsis. The
visual simulation screen represents about thirty degrees of arc
in horizontal length. The simulation module constantly
calculates the forward track of the spacecraft, and on the basis
of these calculations it tries to keep the point on the horizon
in focus towards which the spacecraft is currently headed. For
this reason, the orbital focus will often appear to rotate while
a simulation is in progress.
.P
At the bottom of each visual simulation display there is a
status line indicating the latitude and longitude of the current
"subsatellite point," that is, the point on the surface of the
orbital focus immediately below the spacecraft. The status line
also shows the current altitude of the spacecraft (in
kilometers) over the surface of the orbital focus.
.sp 2
.ne 5
3.2.2 The Ground Track Display
.P
The ground track display shows a flat surface map of the orbital
focus on which the orbital track is superimposed. If there are
multiple orbits and color is supported, the orbital tracks will
appear in (up to six) different colors. One portion of each
orbital track will appear solid -- this is the portion of the
track that the spacecraft has already traversed. Another portion
appears in a dotted line of the same color, and represents the
forward track for one orbit, i.e., the path over the surface of
the orbital focus that the spacecraft will follow on its next
orbit.
.TZ
.BA
\fINote\fR. The track of an orbit will not always stretch around
the orbital focus. At higher earth orbits, for instance, the
track will almost appear to stand still, due to the rotation of
the earth under the spacecraft. Similar effects should be
expected for other orbital foci.
.BZ
.TA
It is important to note that whereas the visual simulation
applies to a specific orbit, the grund track (and distant
perspective) display applies to all orbits around a specific
orbital focus. (For example, a SFS program showing three earth
orbits would display all three orbits on the one earth ground
track map.)
.sp 2
.ne 5
3.2.1 The Distant Perspective Display
.P
The distant perspective display offers a perspective on an
orbital focus and all orbits associated with it from a
hypothetical position approximately ten times the apoapsis of
the highest orbit. Like the ground track display, the simulation
module will try to show multiple orbits in different colors, and
will display both the portion of the track that has been
traversed in solid color, and the untraversed (forward) track in
dotted color. Like the ground track display, the distant
perspective display shows all orbits around a specific orbital
focus.
.sp 2
.ne 5
.ce
3.3 \fBThe Escape Menu\fR
.P
A number of options in the simulation module are made available
through the escape menu. The escape menu can be accessed in two
ways. Using the keyboard, pressing the ESCAPE key will bring up
the escape menu. Using the pointer device (mouse), pointing the
cursor to the top window bar and clicking (down and up) will
bring up the escape menu. The user will recognize the simulation
module escape menu as a standard Bywater UI menu (see 2.1.1
above).
.sp 2
.ne 5
3.3.1 Changing the Display
.P
The first three items in the escape menu allow the user to
change the available displays. Although each of these items
specifies a different display window, they each work the same.
The three display windows are areas on the screen where displays
can be shown, and they are not to be confused with the three
display types. (That is, any of the three display windows can
hold any of the three display types.) The three display windows
are: (a) the top window, (b) the bottom window, and (c) the
"zoom" window. Whenever the zoom window is specified, it takes
the place of the top and bottom windows and is activated.
Conversely, whenever a user selects either the top or bottom
window, both bottom and top windows are activated and the zoom
window is deactivated. The advantage of using the bottom and top
windows is that two displays can be viewed concurrently (by
default, the visual simulation for orbit 1 in the top window,
and the ground track for the focus of orbit 1 in the lower
window). The advantage of the zoom window is that a larger
screen area can be devoted to a single display.
.P
When any of the first three escape menu items is selected, the
user is offered a number of options. There will be at least
three: the visual simulation for orbit 1, the ground track for
the focus of orbit 1, and the distant perspective for the focus
of orbit 1. But the visual simulation for each active orbit will
also be offered, as well as ground track displays and distant
perspective displays for all orbital foci. The user selects one
of these items to fill the window she chose from the escape
menu. The display will return immediately to its previous
contents, but the next time the display is updated the newly
selected display window and type will be activated.
.sp 2
.ne 5
3.3.2 Changing System Parameters
.P
The fourth item in the escape menu allows the user to change
certain system parameters while the simulation module is active.
The system parameters are the same as those described in section
2.2.5 above, but they are entered here temporarily and will not
become part of the program under execution. This is useful when,
for example, a user executes a SFS program on a machine which is
considerably slower or faster than the producer of the SFS
program anticipated, in which case the user can more or less
immediately shift the speed of simulation or the speed at which
the simulation module tries to update the screen. Note that it
may take a few screen updates before the new parameters go into
effect. To change system parameters permanently for a SFS
program file, use the systems parameters option from the orbital
modeling module.
.sp 2
.ne 5
3.3.3 Exits from the Simulation Module
.P
Two exits are provided from the simulation module as the fifth
and sixth entries in the escape module. The fifth (next to last)
entry allows the user to escape completely from SFS. The sixth
and last escape menu option allows the user to return to the
main SFS menu.
.sp 2
.ne 5
.ce
3.4 \fBSimulation Module Toggles\fR
.P
In addition to pressing ESCAPE to get the escape menu, a user
may press four keys ("G", "S", "O", or "C") that serve as
toggles for the visual simulation displays. The status of each
of these keys is shown at the top right hand corner of the
visual simulation display: reverse video means that the item is
activated, and normal video for the letter indicates that the
item is currently inactive. The four letters stand for the
following:
.nf
.fl
.ne 8
.ls 1
    G - Grid
    S - Surface features
    O - Orb
    C - Crosshairs

.ls 2
.fi
The "grid" element refers to the latitude-longitude grid shown
in the visual display. The "Surface features" are such features
as landmass boundaries, craters, mountains, gas bands, and the
like. The "Orb" denotes the circle which represents the extent
of the orbital focus. "Crosshairs" denotes a crosshair display
which shows increments of ten degrees of arc in the display. By
default, all elements are activated except the crosshair
element. (The crosshair element can confuse users of monochrome
systems). By pressing one of these four letters while the
simulation module is running, the element will be switched on or
off. The display itself will be updated with (or without) the
newly toggled elements the next time the screen is updated.
.TZ
.BA
\fIExample\fR. If the user wants to see a somewhat more realistic
representation of the earth from space, she might toggle off the
grid display element, leaving only the earth's orb filled in with
surface features.
.P
\fIRoom for Improvement\fR. SFS currently supports element
toggles for the visual simulation alone. future versions may
implement this for the ground track or distant perspective
displays.
.BZ
.TA
.PH "''''"
.SK
.sp 4
.ce
Chapter 4
.sp
.ce
COMPILING THE SPACE FLIGHT SIMULATOR
.PH "'SFS \*V'Chapter 4'Page #'"
.PF "''Page  #''"
.sp 3
.TA
.na
.ne 5
.P
The source code for the Space Flight Simulator, version \*V,
will be released at the same time as PC-compatible binaries.
Users of Unix based systems will have to compile the entire set
of programs -- no small task. Implementations of the program
exist for the IBM PC and compatibles utilizing Microsoft QuickC
(tm) compiler, for the AT&T Unix PC (tm) utilizing the native
TAM graphics system, and for X Windows version 11. Users of
other systems than these will face the substantial task of
implementing the graphics, keyboard, and directory routines
necessary to build the Space Flight Simulator on their machines.
Also, there are some built-in facilities for converting the SFS
software to utilize other languages than English. In some cases,
users may want to implement the software utilizing different
languages.
.P
In general, the procedure for implementing the software will
fall into two general stages. (a) In the first place, the user
must build the implementations of the Bywater specifications for
graphics output and mouse input (gr), keyboard input (kb), and
directory reading (dr), and then combine these to produce the
Bywater User Interface (ui). The object files produced in these
steps are then transferred (copied) to the Space Flight
Simulator file hierarchy. (b) The second stage is the building
of the SFS programs themselves. This may involve editing some of
the makefiles for particular implementations, and then copying
produced binary files to the SFS "bin" subdirectory where they
can be executed. In what follows, some more detailed
explanations of these processes are given.
.sp 2
.ne 5
.ce
4.1 \fBFile and Directory Hierarchies\fR
.P
The development of the SFS software presupposes the existence of
a specific file hierarchy, which must be related
as described. In the
tables that follow, the slash ("/") is used as the directory
delimiter, but on MSDOS systems the delimiter will be the
backslash ("\\"). Although the name of the directory from
which all the following subdirectories will grow can be
whatever one wishes, the hierarchy should contain the
following subdirectories:
.TZ
.BA
.nf
.ne 9
\fIGeneral\fR:

    ./include    directory for include files
    ./lib        directory for completed object files

.ne 9
\fIThe Input/Output and UI Hierarchy\fR:

    ./io
    ./io/bw    Bywater error-handling subsystem
    ./io/gr    Graphics subsystem
    ./io/kb    Keyboard subsystem
    ./io/dr    Directory subsystem
    ./io/ui    User interface system
    ./io/tw Text Window subsystem (not used by SFS)

.ne 9
\fIThe SFS Hierarchy\fR:

    ./sfs
    ./sfs/sfs    SFS program code
    ./sfs/as    Astronomical subsystem
    ./sfs/map    Map utility
    ./sfs/bin    Datafiles and binary (executable) files
.fi
.BZ
.TA
Depending upon how a user receives the source code, she may have
to create these file hierarchies before moving the source code
into them.
.PF "''''"
.sp 2
.ne 5
.ce
4.2 \fBUsing Script Files to Build SFS\fR
.P
There are a few script files designed to make compilation of
SFS easier on some systems; all are included in the "./io/ui"
and "./sfs/sfs"
subdirectories. The "./io/ui" subdirectory has two scripts
that will allow the user to build the input/output and user
interface systems. The file "buildlib.bat" will build the
input/output system and user interface on a PC-compatible
microcomputer, utilizing the Microsoft QuickC compiler.
The file "buildlib.sh" will allow users to build the input/output
system and user interface on three Unix systems: the X windows
system, the AT&T Unix PC utilizing the TAM interface, and the
AT&T Unix PC utilizing the MGR interface.  The Unix script
("buildlib.sh" should be run from the "./io/ui" sudbirectory
as "sh buildlib.sh".  The user will be prompted for a number
corresponding to the version you wish to
build, and from there is all is well the script will carry
through the building of the program. Both od the scripts
("buildlib.bat" for MSDOS and "Buildlib.sh" for Unix) will
copy all appropriate header files and object libraries to
their appropriate storage directories ("./include" for header
files and "./lib" for object libraries).
.P
The file "buildsfs.bat" will build SFS on a
PC-compatible microcomputer on which the SFS code is properly
loaded, and on which Microsoft QuickC has been installed. The
script file "buildsfs.sh" will allow you to build the program
on three Unix platforms: the X Windows system, the AT&T Unix
PC using the TAM interface, and the AT&T Unix PC using the MGR
user interface. This latter (Unix) script should be run from
the "./sfs/sfs" directory as "sh buildsfs.sh". You will be
prompted for a number corresponding to the version you wish to
build, and from there is all is well the script will carry
through the building of the program.
.sp 2
.ne 5
.ce
4.3 \fBInclude Files\fR
.P
There are a number of include files for the input/output system
and the user interface that need to be available in the standard
include file directory. These are the following:
.TZ
.BA
.ne 9
\fIInclude Files\fR:

    ./io/bw/bw.h    Bywater error-handling header
    ./io/gr/gr.h    Graphics header
    ./io/kb/kb.h    Keyboard header
    ./io/dr/dr.h    Directory header
    ./io/ui/ui.h    User interface header
    ./io/tw/tw.h    Text Windows header (not used in SFS)

.BZ
.TA
These files should be copied to the SFS hierarchy's include
file directory in a user's system, i.e., "./include". The supplied
"buildlib" scripts (see above) will automatically copy the include
files to the appropriate directory.
.P
Programmers may note that the "bw.h" file does not stand for a
subsystem, but simply contains a few overhead lines for a
standard set of Bywater error-handling routines and data sets.
These allow us to generate error messages in low-level graphics
and input/output functions, which may be handled by applications
programs in a variety of ways.
.sp 2
.ne 5
.ls 1
.ce
4.4 \fBImplementing the Input/Output System\fR
.ce
\fBand the User Interface\fR
.ls 2
.P
Note to PC implementers: in order to implement the Space Flight
Simulator, you must use the LARGE memory model for compiling
all modules of the program. If you are interested in using the
User Interface or other libraries for other purposes, you may
be able to compile with other memory models.
.P
For each of the input/output subsystems, there will be a
specification file giving information on how specific functions
should perform. These are as follows:
.TZ
.BA
.ne 9
\fISpecification Files\fR:

    ./io/gr/gr_spec.c    Graphics specification
    ./io/kb/kb_spec.c    Keyboard specification
    ./io/dr/dr_spec.c    Directory specification

.BZ
.TA
Existing implementations of the standards are in files labeled,
e.g., "kb_ibmpc.c" for the PC compatible implementation of the
keyboard standards, "gr_tam.c" for the implementation of the
graphics standards under the AT&T Unix PC's TAM system, and
"dr_unix.c" for a generic Unix implementation of the directory
standards.
.P
Since the specification files include the bare shells of
functions which must be implemented, programmers who want to
develop new implementations of the standards are encouraged to
copy the specification file to a new filename, and then to fill
in the function shells as appropriate. In each case there will
be a test program (for example, "gr_test.c") with a makefile to
test the standards. (Note that if you develop a newly named
implementation, the makefile[s] will have to be changed to
reflect the new names.) A suggested order for implementation is:
directory subsystem, keyboard subsystem, and graphics subsystem.
The graphics subsystem test program requires an implementation
of the keyboard subsystem. However, there are many cases (such
as the implementation under X Windows) where the graphics and
keyboard subsystems must be developed in tandem.
.sp 2
.ne 5
4.4.1 Implementing the Graphics (gr) System
.P
The graphics subsystem also includes pointer device (mouse)
routines, since these are usually intimately connected with
computer graphics systems. The graphics subsystem will be,
almost unquestionably, the most difficult to implement, and
requires that you know how to draw pixels, lines, rectangles
(filled in various ways), circles, and the like both to the
computer screen and to memory buffers which can be copied
(blitted) back and forth (from screen to memory and vice versa).
The graphics system must also be able to address text lines to
pixel-specific locations on the screen. Note that there are some
default routines (file "gr_def.c") for lines, rectangles, and
circles which can be built from a single pixel routines. These
may, however, be extremely slow. Use the file "gr_test.c" with
its associated makefile to test the graphics subsystem.
.sp 2
.ne 5
4.4.2 Implementing the Keyboard (kb) System
.P
The keyboard system may be rather more straightforward, but
should allow two critical abilities: (a) it needs to implement a
keyboard scan routine which will tell if a key has been pressed
\fIwithout\fR waiting for a key to be pressed, and (b) it should
return certain eight-bit codes (defined in "kb.h") for arrow
keys, function keys, and the like. Use the "kb_test.c" file with
its associated makefile to test the keyboard subsystem, or (if
developed in tandem with the graphics subsystem), use
"gr_test.c" to test both the keyboard and graphics subsystems
together.
.TZ
.BA
\fINote to Old-Timers\fR. Remember CP/M? CP/M had the keyboard
scan routine built into its operating system. Unix offers nothing
quite so straightforward.
.BZ
.TA
.sp 2
.ne 5
4.4.3 Implementing the Directory (dr) System
.P
The directory subsystem implements two simple subroutines (also
present to the CP/M operating system, but lacking from more
sophisticated machines): one gives the first file that matches
an ambiguous specification (like "*.c"), the other returns the
next file that matches that specification. Either routine may
return BW_ERROR, indicating that there are no files (or no more
files) matching the specification. Use the "dr_test.c" program
and its associated makefile to test the directory subsystem. The
existing implementation of the directory subsystem for Unix
machines simply breaks out to a shell, calls "ls -1c
[specifier]", and reads the files from a temporary file
containing the filenames. Clumsy, but it works.
.sp 2
.ne 5
4.4.4 Building the User Interface
.P
Once the graphics, keyboard, and directory subsystems have been
implemented, the user may proceed to build the Bywater User
Interface, using "ui_test.c" and its associated makefile.
Remember that specific filenames in the makefile may have to be
changed if a programmer has developed new implementations. The
"ui_test" program should illustrate all of the basic abilities
of the Bywater User Interface. Once the implementation is
completed, copy or move all the object files (except
"ui_test.o[bj]) to the library subdirectory (./sfs/lib) of the
SFS file hierarchy, where they will be used in building the
Space Flight Simulator itself.
.sp 2
.ne 5
.ce
4.5 \fBCompiling the Space Flight Simulator\fR
.P
Once the User Interface has been implemented, the hard work is
over. The Space Flight Simulator code is built from the
./sfs/sfs subdirectory of the SFS file hierarchy. (It will also
compile some files from the ./sfs/as directory, but normally one
does not have to switch to that directory.) Makefile systems
vary, and thus there are currently two forms of makefile for the
SFS program building process.
.P
For \fIPC compatible computers using Microsoft QuickC\fR, there
are separate makefiles for sfs (the program loader), sfsm (the
main menu and orbital modeling module), and sfsx (the simulation
module). Each of these must be built separately from the
"./sfs/sfs" subdirectory. \fIImportant notes\fR: When using
Microsoft QuickC, it is important that the global SPAWN should
be defined in the file "sfs.c". Moreover, once the files have
been built, they will exist in the ./sfs/sfs subdirectory as
"sfs.exe", "sfsm.exe", and "sfsx.exe". The file "sfs.exe" should
be copied as is to the ./sfs/bin subdirectory. The file
"sfsm.exe" should be copied to the ./sfs/bin subdirectory as
"sfsm.app". Similarly, the file "sfsx.exe" should be copied to
the ./sfs/bin subdirectory as "sfsx.app".
.TZ
.BA
\fIQuery: Why the name changes\fR? The files "sfsm" and "sfsx"
must be loaded from the program loader ("sfs") and the system
cpuld crash if they are not. For this reason, we have elected to
change the name of their binary files to "*.app" so as to
prevent them from being executed from the command line. It is
for this reason that it is important that the global "SPAWN"
should be defined in "sfs.h": this instructs the compiler to use
the spawn() routine which can execute the "*.app" files.
.BZ
.TA
.P
For \fIUnix\fR based computers, there will be a single makefile
for the SFS system. You
will have to edit the makefile if you want to include the
correct object filenames for your graphics, keyboard, and
directory subsystem files. Three makefiles supplied are
"makefile.x" for X Windows systems, "makefile.tam" for the
AT&T Unix PC using the TAM interface, and "makefile.mgr" for
the AT&T Unix PC using the MGR implementation. It is suggested
that you copy or move one of these
files to "makefile" (with no extension) to build the programs.
For new Unix or other implementations, you may have to do more
extensive editing to the makefiles. The Unix makefiles should
handle moving the binaries to the ./sfs/bin subdirectory. The
X implementations have been tested only on DECstation 2100 and 3100
workstations, and may not prove adequate on other X platforms.
.PH "''''"
.SK
.sp 4
.ce
Chapter 5
.sp
.ce
SFS DATA FILE FORMATS
.PH "'SFS \*V'Chapter 5'Page #'"
.PF "''Page  #''"
.sp 3
.TA
.na
.ne 5
.P
The Space Flight Simulator uses a number of data files which are
accessible to users as ASCII text files. Users may wish to alter
these files for use with SFS, or may find other applications for
the data. The data formats are described in the following
paragraphs. Users should note that in all SFS data files, lines
beginning with a semicolon (";") are discarded, and thus can be
used to enter comments into a data file.
.sp 2
.ne 5
5.1 SFS Program Files (*.sfs)
.P
Space Flight Simulator program files have the extension "*.sfs"
and give data describing particular orbits. These files can be
developed using the orbital modeling module. Each SFS program
file has a header of one line which contains the program title
(can be more than one word). From this point, the program file
is an interpreted language, in which any of the following
keywords may appear:
.TZ
.BA
.nf
.ne 6
The following apply to the program in general, and require
a single integer (i) following the keyword. They should appear
only once in a program file:

.ne 6
tfactor     i  time factor in multiples of real time
update      i  screen update interval in seconds
trig        i  trig precision level (1 = fast, 2 = accurate)
insertion   i  insertion point in seconds

.ne 6
The following apply to a specific orbit, and require both
an integral orbit number (o) and another argument which may
be a string (s), or a double-precision number (d). They may
appear once for each orbit in a program:

.ne 11
name        o  s  name of spacecraft/orbit
focus       o  s  name of focal data file for this orbit
periapsis   o  d  periapsis in kilometers above the surface
apoapsis    o  d  apoapsis in kilometers above the surface
inclination o  d  inclination in degrees
argper      o  d  argument of the perigee in degrees
lonan       o  d  longitude of the ascending node in degrees
orb         o  s  spherical data file for orb
grid        o  s  spherical data file for lat-lon grid
surface     o  s  spherical data file for surface features

.fi
.BZ
.TA
Users might study examples of SFS program files before
attempting to alter them. Only the items "grid" and "orb" cannot
be specified from the orbital modeling module (and altering them
can have grotesque results). For this reason, users are
cautioned to use the modeling module, where more precautions are
available.
.sp 2
.ne 5
5.2 Focal Data Files (*.fd)
.P
Focal data files have the extension "*.fd" and describe a
particular orbital focus. They are rather more straightforward,
and have the following structure (elements must appear in this
order):
.TZ
.BA
.nf
.ne 4
\fIElements in a Focal Data File\fR:

.ne 6
the name of the orbital focus (a single word)
an adjective describing the focus (a single word)
the diameter of the focus in kilometers
the mass of the focus (earth = 1.0)
the sidereal period of the focus in seconds

.ne 4
\fIAn Example ("earth.fd")\fR:

.ne 6
Earth
terrestrial
6378
1.0
86164

.fi
.BZ
.TA
.PF "''''"
Again, users are advised to study existing focal data files
before creating new ones.
.sp 2
.ne 5
5.3 Spherical Projection Data Files (*.spd)
.P
Spherical projection data (SPD) files have the extension "*.spd"
and describe points in three-dimensional space by latitude,
longitude, and altitude. The spherical projection data format is
derived distantly from the binary format employed by the Micro
World Database (tm). The Space Flight Simulator uses spherical
projection data files to describe surface features of orbital
foci (for example, the earth's landmasses in "earth.spd"). Each
line in a SPD file describes a single point, and consists of the
following elements:
.sp
.nf
    code    latitude    longitude    altitude
.fi
The code is either a number above 1000 indicating the beginning
of a new line, or a number below 1000 indicating the continuation
of a line.
.TZ
.BA
\fIAn Example\fR: The following is a simple spherical data file
("meridian.spd") that draws a central meridian on the surface of
a planet:

.ne 6
.nf
;    meridian.spd
;
;    display single central meridian
;
;
1001    -90.0    0.0    6000.0
5    -80.0    0.0    6000.0
5    -70.0    0.0    6000.0
5    -60.0    0.0    6000.0
5    -50.0    0.0    6000.0
5    -40.0    0.0    6000.0
5    -30.0    0.0    6000.0
5    -20.0    0.0    6000.0
5    -10.0    0.0    6000.0
5    0.0    0.0    6000.0
5    10.0    0.0    6000.0
5    20.0    0.0    6000.0
5    30.0    0.0    6000.0
5    40.0    0.0    6000.0
5    50.0    0.0    6000.0
5    60.0    0.0    6000.0
5    70.0    0.0    6000.0
5    80.0    0.0    6000.0
5    90.0    0.0    6000.0

.ne 6
.fi
\fIRoom for Improvement\fR: At present all codes for beginning a
new line are set to 1001 and all codes for continuing a line are
set to 5. Future versions of the software might develop a more
elaborate set of codes above 1000 which could indicate, e.g.,
gas forms (for describing gas giants such as Jupiter), landmass
delimiters, craters, mountains, rifts, and the like. Then the
program might assign various colors to different features. Also,
the SFS programs currently ignore the altitude, presuming that
all points are on the surface (thus, the altitude of each point
is set equal to the focal radius). Future versions might
recognize altitudes, thus enabling the display of irregular
orbital foci. Also, future versions of SPD files might allow a
comment or title at the end of a point, so that titles could be
shown on a focal surface.
.BZ
.TA
.PH "''''"
.SK
.sp 4
.ce
Chapter 6
.sp
.ce
The MAP Utility
.sp 2
.PH "'SFS \*V'Chapter 6'Page #'"
.PF "''Page  #''"
.P
The MAP utility (source code and binaries are distributed
separately from the PC version of the SFS software) allows users
to enter spherical projection data points by pointing and
clicking the pointer device within a latitude-longitude grid.
The MAP utility thus requires the use of a pointer (mouse) device.
.P
The MAP utility is entered from the command line with an
optional argument specifying the SPD datafile to be worked on.
Thus the command line,
.nf
    map earth.spd
.fi
would enter the MAP utility and begin work on the file "earth.spd".
The filename "test.spd" is used as a default if no argument is
specified on the command line. Once the MAP utility has been
entered, the working file cannot be changed.
.P
The MAP utility utilizes the same user interface as the Space
Flight Simulator, and has a main menu that is accessible by pressing
the ESCAPE key or by clicking the pointer device on the top
(title) bar.  The following are the options available in the main
MAP menu.
.sp 2
.ne 5
6.1 Change Position
.P
This option from the main menu allows the user to focus on a
particular position of the latitude-longitude grid, or to look at
the entire latitude-longitude grid.  By pressing the arrow keys,
a dark outline of the selected area can be moved around.  By
pressing the RETURN or ENTER key, the currently selected area is
chosen, and the screen will be redrawn accordingly.
.sp 2
.ne 5
6.2 Enter Title or Comments
.P
The Space Flight Simulator's Spherical Projection Data (SPD)
format allows for embedded title and comment lines.  This option
from the main MAP utility menu allows the user to enter a line of
text that will be embedded in the working data file as a title or
comment. Since comment lines will not be entered at run time,
they are used solely for making sense of an SPD data file when it
is read by a text editor, and users are encouraged to document and
comment their SPD files as elaborately as possible.
.sp 2
.ne 5
6.3 Begin Sequence
.P
This is where the serious work of the MAP utility is done. This
option from the main MAP utility menu allows users to enter a
sequence of points on the latitude-longitude grid, which are
recorded in the working data file.  After selecting this item,
the user points the pointer device at specific points on the
grid, and presses and releases the left button to mark the point.
At the next point entered, a line will be drawn from the previous
point to the new point, and so on.  The sequence is ended by
clicking in the "QUIT" label in the top (title) bar.
.P
By pressing in the "BACKUP" label in the top (title) bar, the
user can erase the most recently added point. The user should be
careful, then, to check each point as it is entered, and BACKUP
if it has not been positioned correctly.
.P
Users of the MAP utility should remember that all of the points
in a sequence will be joined by direct lines. For this reason,
the user should only enter points in a particular sequence that
will be tied together. It is recommended that complex figures be
broken up into smaller units, even when unbroken sequences of
lines are desired (begin a new sequence at the last point of the
old one to carry through the appearance of unbrokenness).
.sp 2
.ne 5
6.4 Set Default Attitude
.P
Although the present version of the Space Flight Simulator takes
all surface points to be at the (average) radius of an orbital
focus, the SPD specification allows an altitude for the point to
be entered.  This will eventually allow SFS to develop more
elaborate three-dimensional simulations.  Typically, the altitude
is simply set to the radius of the rbital focus.  This option
from the main MAP utility menu allows the user to specify a
default altitude that will be used for all subsequent points
entered.
.sp 2
.ne 5
6.5 Exit
.P
This item allows the user to exit from the MAP utility. The
current working data file is saved with all changes that have
been entered.
.BZ
.TA
.PH "''''"
.SK
.sp 4
.ce
Chapter 7
.sp
.ce
COMMUNICATIONS
.sp 3
.ls 1
.nf
Bywater Software
P. O. Box 4023
Duke Station
Durham, NC  27706

email: [e-mail]
.fi
.TA
.sp 2
.ne 6
About the author:
.sp
.P
Ted A. Campbell is an Assistant Professor of Church History at
the Divinity School, Duke University. Programming is an
avocational interest. In addition to books and articles in the
field of Church History, he is the author of the program
"Stardate," published by the National Collegiate Software
Clearinghouse.
.ls 2
.TZ
..    \"===================================================
..    \"    end of sfs.ro
..    \"===================================================