**** **** **** **** *********          ****  *****************
**** **** **** **** *********          ****   *****************
**** **** **** **** ***                ****    *****************
     **** ****      ***                ****     *****************
**** **** **** **** ********* ******** ****      *****************
**** **** **** **** ********* ******** ****       *****************
**** **** **** ****       *** ***  *** ****      *****************
**** **** **** ****       *** ***  *** ****     *****************
**** **** **** ****       *** ***  *** ****    *****************
**** **** **** **** ********* ******** ****   *****************
**** **** **** **** ********* ******** ****  *****************
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~A Modern Orrery~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~By William L. Davis~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~Written May 2, 2008~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~wldavis89@gmail.com~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

************************ Table of Contents ************************
1. Motivation				   ************************
2. Program Details                         ************************
3. Description of Mathematics              ************************
4. Compilation/Installation                ************************
5. Running                                 ************************
*******************************************************************

1. Motivation *****************************************************

Welcome to illiSol, a modern incarnation of the mechanical orreries
of the days of old.  My goal in  developing this  application is to
provide  the  capabilities  of  accurate  visualization  of the Sol
Star  System,  using  a  concrete set of  equations provided by Jet
Propulsion  Laboratories and the OpenGL graphics libraries and GLUT
utilities in the context of the  C/C++  programming languages.  The
ultimate goal in this project is to run it in the immersive virtual
environments at the Beckman Institute at the University of Illinois
at Urbana-Champaign,  and be used and  expanded upon in the future.
			      Enjoy!
*******************************************************************

2. Program Details ************************************************

The program has come to encompass several features, and, over time,
has  evolved  to  be  significantly  different  than  the  original
"drawing  board"  concept  developed  in the first quarter of 2008.
The following is a basic structure of illiSol:
The user defaults to a spacecraft view,  in which the spacecraft is
significantly displaced from the solar system. 
	^  y		   Imagine the solar system in the xy plane
	|   		   (approximately)  and  the camera,  where 	
	|   /		   the  user's  location is at  the  camera
     *  |  /     *	   on  the  positive z axis  looking toward
   *   *| / *		   the xy plane.  In actuality,  the camera 
<_______Sun________> x	   is  at  the  origin  and the xy plane is 
       */ *		   shifted  in the negative  z direction by
       /		   15 astronomical units,  but this is only
      /    *		   a trivial difference.  For our purposes,
    Cam Z  		   Sol  will  lie at the  origin  as in the 
			   diagram to the left. 
The positions of the planets are computed  using a set of equations
that will be described in section (3). Initially, the system is set
to the date August 20, 1977,  the date of the launch of Voyager II.
Each planet is texture mapped with its corresponding surface image,
and, for the Earth,  Jupiter,  and Saturn,  the visible satellites,
which include  the Moon, Io, Europa, Ganymede, Callisto, and Titan,
are drawn as spheres with solid colors (no texture mapping). I only
refrained from this  because the method of  texture mapping that is
implemented in this  version is far less than efficient,  and would
slow down the program to unusable even on some faster machines. The
planets move in  their orbits fairly accurately,  but the orbits of
satellites are approximated as circlular (only inclination from the
ecliptic is used).  These orbits do not  change over time,  and are
therefore  not meant to be  taken as accurate in any way.  They are
merely present for visual effect.
*******************************************************************

3. Description of Mathematics *************************************

I won't go through the tedious derivation of the mathematics of the
system, mostly because I don't know them. JPL has provided on their
website for us a simple step by step guide to computing approximate
planetary positions  for each  major planet,  and also supplies the
necessary Keplerian elements  to complete the computations.  I have
a link  to this  document,  along with  a short  description of the
process, on my project webpage at
http://cheer.math.uiuc.edu/reulab/web/wldavis
*******************************************************************

4. Compilation/Installation ***************************************

Currently,  I don't have a  version yet that is  able to compile on
a Mac, so illiSol is only availabe as a Windows application. If you
have the standalone,  all  that  is  required to run  illiSol is to
double-click on the illiSol.exe. If you have the source  code, here
are the steps to compiling it. 

i) Precompile Checklist
	- You must have  the  Aszgard  development  environment for
	  Windows compiled on your machine.  This guide is only for
	  machines running Aszgard.
	- You need to have Syzygy in Aszgard,  with a folder called
	  "skeleton",  which should have some demos called skeleton
	  and oopskel. Don't worry about those.

ii) Put everything in the right place
    This assumes Aszgard is installed to the folder "aszgard"
	- The folder "iSImages",  which holds all of the  planetary
	  surface raw images, should go in the folder
	  >aszgard/szg/bin/win32
	- The three required sourcefiles,
		illiSol.cpp
		KeplerianElements.h
		opengl_stars.c
	  should go in skeleton's source folder:
	  >aszgard/szg/skeleton/src
	- To compile it, we'll need to put our makefile,
		Makefile.my_app
	  into the makefiles folder for skeleton
	  >aszgard/szg/skeleton/build/makefiles

iii) Compile it!
	- Now you're ready, so change directories so that you're at
	  the root of the  skeleton directory.  This should be done
	  from within the Aszgard shell (I used the mingw shell).
	  >aszgard/szg/skeleton
	- Type "make" and return
	  >make

     	The process  may take a few  seconds,  and give quite a few
	warnings,  but if your  Aszgard is set up right,  it should
	compile with no errors. If it doesn't, well...  I proabably
	cannot  help you,  but  checking your  Aszgard  environment
	variables to make sure they are correct may help.  To check
	that everything went well, type "illiSol" and return.
	>illiSol

	You should get the  solar system,  but all of the planetary
	surfaces will not map  properly,  so you will  probably see
	white spheres instead.
*******************************************************************

5. Running ********************************************************

Running illiSol is easy once you have it compiled.  Simply navigate
to the directory where you put the  texture images,  and you should
find a new executable there, called illiSol.exe.
>aszgard/szg/bin/win32/illiSol.exe
Double click on this and you should get illiSol,  along with all of
the pretty texture maps!

All of the included keypress commands are displayed on screen,  but
I will review them briefly here for completeness.
(ESC) - Pressing the escape key will automatically close illiSol.
(H)   - Pressing Shift + h will increase  the size of every body in
	the system non-uniformly.
	-> The Sun's radius is increased by a factor of 5
	-> Every planet's and satellite's radius is increased by a
	   factor of 40
(h)   - Pressing the h key will decrease  the size of every body in
	the system non-uniformly.
	-> The Sun's radius is decreased by a factor of 5
	-> Every planet's and satellite's radius is decreased by a
	   factor of 40
(K)   - Pressing Shift + k will increase  the size of every body in
	the system uniformly.
	-> The Sun's radius is increased by a factor of 5
	-> Every planet's and satellite's radius is increased by a
	   factor of 5
(k)   - Pressing the k key will decrease  the size of every body in
	the system uniformly.
	-> The Sun's radius is decreased by a factor of 5
	-> Every planet's and satellite's radius is decreased by a
	   factor of 5
(V)   - Pressing Shift + v will increase the timestep of the
	simulation.
	-> The current timestep is multiplied by 1.2, and the
	   result becomes the new timestep. Timestep is in
	   days.
(v)   - Pressing the v Key will decrease the timestep of the
	simulation.
	-> The current timestep is divided by 1.2, and the result
	   becomes the new timestep. Timestep is in days.
(f)   - Pressing the f key has two effects:
	-> The simulation will enter fullscreen mode
	-> If the timestep is not zero, the timestep is set to zero
	-> If the timestep is zero, the timestep is set to two days
(Z)   - Pressing Shift + z will "fastforward" the simulation a year
	-> The number 365.0 is added to the current JDN (Julian Day
	   Number)
(z)   - Pressing the z key will "rewind" the simulation a year
	-> The number 365.0 is subtracted from the current JDN 
	   (Julian Day Number)
*******************************************************************
