
Notes for Users of the !Spotter Application, version 1.10
=========================================================

Introduction
============

   To my knowledge, !Spotter is the first satellite orbit prediction utility
implemented on the Archimedes, although many similar programs exist on other
platforms. !Spotter reads in a set of NORAD two line elements (from the
elements file provided), and allows the user to perform real time analysis
on these elements. This means that the user can display the location of the
satellite in any of three ways, and/or the position of the satellite as
viewed from any number of locations on the Earth's surface, all in real time.
In addition to this, it is possible to create a printout, (or WIMPY *) for any
time period, detailing the visibility coverage for up to five stations within
that period, and plots in the form of !Draw files showing the path of a
satellite during a given interval.

   The !Spotter package comprises two Wimp applications. The first of these
is the front end, which installs itself on the Icon bar when the application
is first run. This program controls the contents of the configuration file
(details later), and also launches any number of instances of the second type
of application. These are the satellite tasks. Each satellite task controls all
the functions (i.e. position displays and WIMPY (*) generation) for a
particular satellite, and any number of satellite tasks may be running
simultaneously. In addition, when a satellite task is running, the front end
task is no longer required and so may be cancelled.

   The following sections describe the two types of task in more detail. These
notes are by no means exhaustive, but I hope that they will eventually evolve
into a complete user guide. In the meantime, please do not hesitate to contact
me in the event of queries, bug reports, suggestions etc.

(*) Within ESOC, a spacecraft visibility printout is known as a WIMPY for
    historical reasons. (The best explanation that I have heard is that it is
    colloquial expansion of the initials W.M.P., from World Map Prediction).
    The reason I have used this accronym in !Spotter is that WIMPY is a lot
    easier to fit in a menu list than any alternative I could think of !!


The !Spotter Frontend
=====================

   Double-clicking on the !Spotter icon from within a filer window will start
the application, and the icon will then appear on the icon bar. Clicking SELECT
over the iconbar icon will display a welcome window, but the main functions are
reached via the MENU button. The items in this menu are presented in order below:

         Info: Leads to window containing standard application info

         Load Satellite: This item leads to a menu structure from where any 
             satellite currently known to !Spotter can be loaded. Clicking on
             a satellite name from a list will start a satellite task for
             that satellite. Clicking with the 'Alt' key pressed on any menu
             other than the 'User List' submenu will toggle inclusion of that 
             satellite in the user list menu. The 'Find Sat' option leads to
             a writable menu. Entering a string in this field will initiate a
             search for this string in the satellite list, and a menu of matches
             (if any) will be displayed.

         Add Satellite: Not currently implemented. Presently, to add to the
             list of available satellites, a set of NORAD format elements  
             must be preprepared, and then dragged to the icon bar icon.

         Save Elements: This menu item leads to a "save_as" dialogue for storing
             the currently loaded element sets, including the information on the
             satellite user list contents. The default save file is the !Spotter
             internal file, so to update the elements loaded by !Spotter on
             start up, simply click on the OK icon.

         Load Planet: Not currently implemented. This is something I intend   
             to add in the near future, as it has been requested.

         Change Setup: This option enables the user to edit the configuration
             file. Clicking on this option displays the configuration control
             panel, and the contents of the file can be edited from here. More
             information on the configuration file can be found below.

         Quit: Quits the application. Any satellite tasks started by the task
             now being cancelled will, however, remain active.


     Files Read By !Frontend 
     -----------------------

        The Elements File
        -----------------

              The names of satellites along with the two line elements are read
        from the file 'elements', which should reside in the !Spotter directory.

          Updating The Elements File
          --------------------------

                 To use a different elements file, drag the new file to the
          !Spotter icon on the icon bar. The FrontEnd task will then read in
          the contents of the new file, and then open a window above the icon
          bar. This window displays the total number of element sets in the new
          file, how many of these sets are more recent elements for satellites
          already in the database, and how many of them are for satellites not
          presently defined. The user can update the elements currently loaded
          by clicking on the OK icon, but the nature of the update is determined
          by the status of the radio icons as follows:

             "Replace old data": If this option is selected, the data from the 
                  new file will completely overwrite the data currently loaded.
                  The currently defined "User List" will be lost.

             "Merge data": If this option is selected, the new data will be
                  merged with the old data, with the manner of the merging
                  being determined by the following radio icons:

                    "New": All satellites in the new file that do not appear in
                         the currently loaded satellite database will be
                         appended to the database.

                    "Updated": All satellites for which newer elements have
                         been received will be updated in the loaded database.

                    "Selection": Satellites explicitly selected from the list
                         of elements in the new file (list obtained by clicking
                         menu) will be updated. Useful if you need to load old
                         elements for some reason.

              In order that the updated elements are available to !Spotter the
        next time the application is started, the elements should be saved. To
        do this, simply Click OK in the "Save Elements" submenu.

          
        The Configuration File
        ----------------------

              This file is intended to hold any user configurable parameters.
        Currently, this file contains only two types of information. The first
        of these is the local time offset from Coordinated Universal Time
        (UTC, or, more often GMT). All orbit work is done in UTC, and the 
        offset is needed to relate this time to the time read from the computer
        clock. If your computer is running in GMT, then the offset should be
        set to 0 hours, 0 minutes, 0 seconds. If your computer uses British
        Summer Time (1 hour ahead of GMT), set the offset to 1 hour, 0 minutes
        and 0 seconds, and similarly for other locations. It is worth noting
        that the sign of the time offset applies to all three fields, i.e.
        - 02 hours 30 minutes means -2.5 hours, and not -1.5 hours. 

              The second type of information currently contained in the
        configuration file is the list of observation stations set up by the
        user. The list comprises names and coordinates of any number of
        stations, where the coordinates are given as longitude, geodetic
        latitude and altitude relative to the WGS 72 geoid. The stations
        provided in the file with the distribution are a few of the locations
        that I have used in the past, with varying levels of precision. It is
        unlikely that any of these will be of any use to you, so you will
        probably need to delete them and add your own.

              All information in the configuration file may be edited via the
        'Change Setup' option in the !FrontEnd main menu. Stations may be
        added, deleted or modified, and coordinates may be entered as geodetic,
        geocentric or cartesian. Alternatively, the 'config' file may be
        edited directly, but make sure that the numer of stations given in the
        second line matches the number of stations following.
                     

     Some Additional Points 
     ----------------------

        When a satellite task is loaded, the configuration is the same as the 
     configuration in the Front End task, i.e. any changes made in the 'Change 
     Set Up' panel will be transmitted to any initialised satellite tasks. This
     does not apply to versions previous to 1.02.


The Satellite Subtasks
======================

   As described in the previous section, satellite specific subtasks are
started from the !FrontEnd menu. These tasks start by displaying their main
window in the centre of the screen, and are quit by clicking on the exit icon
of this window. While this window exists, the task is still active. The main
window displays some basic information on the satellite that has been loaded,
i.e. the satellite name, NORAD number, epoch of the loaded two-line elements
(which gives an indication of the accuracy of predictions), the orbital
period and the orbital inclination. Clicking MENU within this window displays
the following list of options:

   Time Control: This menu item leads to a window controlling the epoch used
       for the display windows, and also for the frequeny of update of the
       control windows. To set the epoch to a particular time, simply enter the
       time and click the 'SET' icon. The time can then be reset to the
       computer time (i.e. actual time) by clicking on 'RESET EPOCH', and the
       epoch can be frozen by toggling the 'Freeze Epoch' radio icon. To reduce
       the update frequency of the display windows, deselect the 'Update
       Frequency' icon, and change the interval to the desired value. This can
       be useful to improve the response time for other applications.

   Display: This menu item controls the real time displays for this satellite
       task. Hanging off of this menu is a list of the types of display
       available, and these are dealt with in more detail in the next
       section.

   Create Hardcopy: All output product files generated by the satellite task are
       controlled by this submenu. This enables generation of ephemeris & WIMPY
       files, as well as the creation of groundtrack plots in !Draw format.
       A WIMPY is a chronological list of pass events for up to five
       different locations. Additionally, the WIMPY contains details of when the
       spacecraft is lit by the Sun, and hence when the satellite is potentially
       visible to the naked eye. Presently this is the only way of obtaining
       this information from within !Spotter (although I intend to rectify
       this). Details on hardcopy generation are given below.

   Edit Elements: This opens a window displaying the orbital parameters of the
       spacecraft currently loaded. I will not explain in detail what each
       parameter is (orbital mechanics is a vast subject in itself !!), but you
       might like to see the effect of varying a few parameters on the orbit.
       The elements stored in the elements file will not be effected by any
       changes made in this menu.


   Save Choices: Most of the initial settings for parameters and flags in the
       !SpotSat menu system are read in from a choices file. This file (in the
       "Resources" directory under "SS_Choices") may be edited directly to
       change the defaults, or you can click on this option to save the current
       settings in the defaults file.

     Types of Display Windows
     ------------------------

        As mentioned above, the Display option on the satellite task main menu
     leads to a submenu containing a list of the different types of real time
     displays available. The items on this submenu are presented in order below:

         UTC Epoch: Clicking on this item opens a window in which the UTC time
             for which the other display windows are valid is displayed.

         Inertial State: Clicking on this item opens a window displaying the
             current Earth Centred Inertial state vector (as defined by NORAD:
             mean equinox, true equator of date).

         Earth-Fixed State: This item displays the current Earth-Fixed state,
             calculated by rotating the ECI state through an angle
             corresponding to the current Greenwich Mean Sidereal Time.     
            
         Lat/Lon/Altitude: This menu item opens a window containing the
             Earth-Fixed state expressed as latitude, longitude and altitude
             relative to the WGS-72 geoid.

         Station View: This menu item leads to another submenu containing a list
             of the stations in the configuration file. Each of these submenu
             items opens a window containing the position of the spacecraft
             relative to the viewing station. This information is presented as
             range (in km), azimuth (in deg), and elevation (in deg), but it is
             the last two of these that will enable you to see the satellite.
             Azimuth is defined as 0 deg due North, increasing to the East, i.e.
             due East is 90 deg, South is 180 deg, and West is 270, or -90
             deg). Elevation is defined as elevation above the horizon, so that
             if the satellite is visible, the elevation will be in the range 0
             to 90 deg.
         
         World View: This option displays a map of the world, with the position
             of the satellite depicted by a cross. The contents of the map    
             display can be modified from the menu, which can be obtained by 
             clicking MENU anywhere in the map window. The main menu has the 
             following entries:

               Visibility, Terminator, Path, Stations, Resize

             The first two items toggle the inclusion of the satellite
             visibility and the terminator respectively in the map display. The
             Path item leads to a sub-menu with three items referring to the
             previous, current and next orbit. These items toggle the inclusion
             of the groundtrack for the appropriate orbits to be shown in the
             plots. The Stations main option leads to a list of the stations
             currently loaded, any of which may be shown on the plot. Finally,
             the 'Resize' option leads to a scale window, from where the display
             can be scaled by any quantity (as a percentage of the background
             sprite), or even scaled to fit the screen. In the scale window,
             is also an 'Auto' flag, which, when set will ensure that the window
             is automatically scaled to fit the screen on mode changes. All
             these options can be switched on or off by default using the
             choices file (see above).
               The sprite used for the backdrop is taken from the file Map_16 in
             the "Resources" directory. The size of the window is taken from
             the sprite, so you can put any sprite you like there to replace the
             one I have provided. If you have a nice 256 colour sprite, then you
             can put this in file Map_256, and this will be loaded for 256
             colour modes. I am currently working on such a sprite (made up
             from composite satellite images), which I will not distribute with
             the package due to its size. If you would be interested in
             obtaining it when it is ready, please contact me.

        When any of these windows are opened, then the menu item that was used 
     to open the window is greyed out to avoid duplicate windows. When the
     window is closed (by clicking on the close icon), then the appropriate
     menu option is reenabled.


     WIMPY Generation
     ----------------

        If you wish to find out when (or if) a particular satellite will be 
     visible within a specific time interval, then the WIMPY will give you this
     information. To generate a WIMPY for a particular satellite, select the
     'WIMPY' option from the 'Create Hardcopy' submenu of the satellite task
     main menu, and then a WIMPY options panel will appear. Either by clicking
     on the raise and lower icons,or entering the times manually, set the start
     and end times for the new WIMPY to cover the desired interval. The list of
     available stations is obtained by clicking MENU in the central section of
     the control panel. Clicking on a station name toggles its inclusion in
     the WIMPY, up to the  maximum of 5 stations. As is standard RISC OS
     practise, clicking with ADJUST will keep the menu on the screen. Next, you
     can change the time step used between records in the WIMPY by directly
     overwriting the default value. However, the default value of 60 seconds
     should be adequate for most purposes. In a future release, it may be
     possible to change the elevation cutoff applied to the rise and set times,
     but this is not presently implemented. Clicking on GO will begin present
     the user with a "save_as" box, where the user can drag the file icon to a
     filer window to indicate where the WIMPY should be stored. When this has
     been done, the WIMPY generation will commence.

        Whilst the WIMPY generation is in progress, a window will be present in
     the centre of the screen showing the status of the generation. Although
     the generation does multitask, it will go much faster if no other display
     windows are active at the same time.


     Ephemeris Generation
     --------------------

        For some purposes (for example when making plots), a list of state
     vectors (called an ephemeris) is required. Three types of ephemeris can be
     created by !Spotter - Inertial, Earth-Fixed, or the groundtrack of the
     subsatellite point (as latitude & longitude). Selecting any of these
     options from the 'Create Hardcopy' submenu will pop up a options menu for
     the required ephemeris. There, you can select the time range required and
     the step size, and also (by dragging the filer icon) select the name of
     the file to hold the ephemeris. When ready, a click on the 'OK' icon will
     begin ephemeris generation. If sufficient RAM is available, then the
     ephemeris will be generated into RAM and written to the file in one go
     when complete. Otherwise, writing to the output file will begin straight
     away.

        As for the WIMPY generation, a window displaying the status of the
     ephemeris generation will be created.


     Groundtrack Plot Generation
     ---------------------------

        To visualise the path of a spacecraft over the Earth, it is possible to
     create a plot of the path of the sub-satellite point over the Earth's
     surface. Selecting 'Groundtrack Plot' from the hard copy submenu will open
     a plot options window. Here you can set a number of options defining the
     features of the plot. First, the time range for the groundtrack path can
     be chosen, and by clicking on the node arrows, it is possible to force the
     path to start or end at an ascending node. It is also possible to select
     the page size for the plot if it is to be printed, and the longitude to be
     at the centre of the map is also selectable. The Map can contain a
     latitude/longitude grid, with the step size configurable, and may also be
     surrounded by tick marks (to enable labelling). Large tick marks are put at
     specified interval, with 10 smaller tick marks in between. Clicking MENU
     over colour icons opens up a !Draw-like colour selection menu, where the
     colours for the land and sea in the plot can be selected. Clicking menu
     over the 'Stations' selection of the window will open a list of available
     ground stations, and selecting any of these will put the visibility circle
     for this station in the ground track plot. Unlike WIMPY generation, there
     is no limit to the number of stations used for the groundtrack plot.
     Finally, by dragging the file icon, it is possible to choose where the
     file will be stored. Clicking on the OK icon will start the generation of
     the plot. The path and map data are read first into RAM, and then all data
     is written to the output file in one go.

         As for the other hardcopy generation, a window displaying the status
     of the groundtrack generation will be created.




Final Remarks
=============

   As I mentioned in the introduction, these notes are just that, notes, and do
not describe every detail of the !Spotter application. However, I hope that they
contain enough information to enable you to make some use of the program, and
also to inform you of some of the drawbacks of the current version. I have tried
to point out where I think improvements are necessary, but a more specific list
of my intended updates is given in the file 'To_Do' in this directory. Of
course, if you have any comments yourself, I would be delighted to hear them.

Finally, to those new to satellite spotting, I have include a file 'Hints'
which contains a few pointers that should enable you to find you first
satellite.

Happy Spotting,

Stuart Martin, 7th December 1993.
