celestia/README

***************************************************************************
*                                 Celestia                                *
*                                                                         *
*  A real-time space simulation that lets you experience our universe in  *
*  three dimensions.                                                      *
*                                                                         *
* Copyright (c) 2001-2008, Celestia Development Team                      *
*                                                                         *
*-------------------------------------------------------------------------*
*  Celestia web site: http://www.shatters.net/celestia/                   *
*                                                                         *
*  Celestia documentation:                                                *
*    http://www.shatters.net/celestia/documentation.html                  *
*    Celestia WikiBook: http://en.wikibooks.org/wiki/Celestia             *
*                                                                         *
*  Celestia forums: http://www.shatters.net/forum/                        *
*                                                                         *
***************************************************************************

CONTENTS
--------
  License
  Installing in Unix
  Getting Started
  Mouse, Keyboard & Joystick Controls
  Solar System Browser
  Star Browser
  Selecting Objects by Name
  Known Issues
  User Modifiable Elements
  Celestia Resources
  Credits
 

LICENSE
-------
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details, which you should have received along with this program (filename:
COPYING).  If not, request a copy from:
  Free Software Foundation, Inc.
  59 Temple Place - Suite 330
  Boston, MA  02111-1307
  USA


INSTALLING IN UNIX
------------------
Type "./configure --help" for a list of options.  The basic commands are shown
below.  For more detailed information, refer to the INSTALL file.

This GTK version is built with...
  ./configure --with-gtk
  make
  make install

The KDE3 version is built with...
  ./configure --with-kde
  make
  make install

  Note: some systems may require configure to be executed with
        --with-qt-includes=/usr/include/qt3

The Gnome version is built with...
  ./configure --with-gnome
  make
  make install

If all else fails, try the gui-less version with...
  ./configure --with-glut
  make
  make install


GETTING STARTED
---------------
Celestia will start up in a window, and if everything is working correctly,
you'll see Earth in front of a field of stars.  Displayed on-screen, is some
information about your target (Earth), your speed, and the current time
(Universal Time, so it'll probably be a few hours off from your computer's
clock).

Right drag the mouse to orbit Earth and you might see the Moon and some
familiar constellations.  Left dragging the mouse changes your orientation
also, but the camera rotates about its center instead of rotating around
Earth.  Rolling the mouse wheel will change your distance to Earth--you can
move light years away, then roll the wheel in the opposite direction to get
back to your starting location.  If your mouse lacks a wheel, you can use the
Home and End keys instead.

When running Celestia, you will usually have some object selected.  Currently,
it's Earth, but it could also be a star, moon, spacecraft, galaxy, or some
other object.  The simplest way to select an object is to click on it.  Try
clicking on a star to select it.  The information about Earth is replaced with
some details about the star.  Press G (or use the Navigation menu), and you'll
zoom through space toward the selected star.  If you press G again, you'll
approach the star even closer.

Press H to select our Sun, and then G to go back to our Sun.  Right click on
the sun to bring up a menu of planets and other objects in the solar system. 
After selecting a planet from the menu, hit G again to travel toward it.  Once
there, hold down the right mouse button and drag to orbit the planet.

The Tour Guide is a list of some of the more interesting objects you can visit
in Celestia.  Select the Tour Guide option in the Navigation menu to display
the Tour Guide window.  Choose a destination from the list, click the Goto
button, and you're off.

That covers the very basics.  For a more in-depth look at Celestia and the
controls available to you, download the "Celestia User's Guide" (written by 
Frank Gregorio), available in several languages, from:
  http://www.shatters.net/celestia/documentation.html
This web page also includes links to the Celestia README file translated into
Japanese.


MOUSE, KEYBOARD & JOYSTICK CONTROLS
-----------------------------------
See the included file: KbdMouseJoyControls.txt.  In Windows, you can also use
the Help menu to display the Controls list.


SOLAR SYSTEM BROWSER
-------------------------------------------
The Navigation menu contains 'Solar System Browser' and 'Star Browser'
options.  The Solar System Browser displays a window with a tree view of all
the objects in the nearest solar system (if there is one within a light year
of your current position.)  Clicking on the name of any object in the window
will select it.  You can then use the Center or Go To buttons to display that
object in the main Celestia window.


STAR BROWSER
-----------------------------------
By default, the Star Browser window displays a table of the 100 nearest stars,
along with their Distance, Apparent and Absolute Magnitude, and Type. Clicking
on the column headers will sort the stars.  The table is not continuously
updated, so if you travel to another star, you should press the Refresh button
to update the table for your current position.  The radio buttons beneath the
table let you switch between viewing a list of Nearest, Brightest, or 'With
planets' stars.  As with the solar system browser, clicking on any star name
in the table will select it.  Use this feature along with the Center and Go
To buttons to tour the stars visible from any night sky in the galaxy.


SELECTING OBJECTS BY NAME
-------------------------
Celestia provides several ways to select an object by name...
  1. Choose 'Select Object' from the Navigation menu, type in the object
     name, and click OK.
 
  2. Press Enter, type in the entire object name, and press Enter again.
 
  3. Press Enter, type in the first few characters of the object name,
     press the Tab key to move through the displayed listing until the
     object is highlighted, then press Enter again.
 
You can use common names, Bayer designations, or HD catalog numbers for
stars.  HD catalog numbers must be entered with a space between HD and the
number.  Celestia handles star catalog numbers in a slightly kludgy way, to
keep the star database size to minimum -- only one catalog number is stored.
Normally, this will be a number from the HD catalog, but if a star isn't in
the HD catalog the number from another catalog will be used instead.
Currently, the secondary catalog is always the HIPPARCOS data set, for which
the prefix "HIP" should be used.


KNOWN ISSUES
------------
Many people have reported problems running Celestia with Matrox G400/G450 3D
accelerator cards.  As I don't have a Matrox card, I haven't made much
progress on this bug.  If you do have a G400, have Visual C++ installed, and
would be interested in testing a debug version of Celestia, please contact me.

The maximum texture size supported by the Voodoo 1/2/3 is 256x256, so many of
the planet textures will look blurry when running Celestia on one of these
cards.

On 3D accelerator cards with a limited amount of memory, resizing the main
Celestia window can cause textures to disappear.  This occurs because so much
memory is required for the frame buffer that there's not enough left for
textures.  There are a several workarounds:
  - Use a smaller window
  - Make sure your display is set to 16-bit (high color) mode
  - Try running Celestia in full screen mode

Celestia only barely works in 256 color mode.  If your display is set to 256
colors, change it to 16-bit or 32-bit if at all possible.

If objects look good at a distance but get too dark when you approach them
closely, your OpenGL driver does not support a required extension.  Try
upgrading to the most current version of drivers available for your card.  For
some older cards, this still won't fix the problem.  The next version of
Celestia will feature a workaround.

For up-to-the-minute answers to some common problems encountered when running
Celestia, please view the "preliminary Celestia User's FAQ" located on the
Celestia User's Forum:
  http://www.shatters.net/forum/viewtopic.php?t=2291


USER MODIFIABLE ELEMENTS
------------------------
You can modify how Celestia starts up each time you run it, by defining your
own start-up settings.  Simply open the file "start.cel" in a plain text
editor and follow the in-file instructions.  Also, view the celestia.cfg file
in a plain text editor to see additional settings.

Celestia allows you to create an entirely fictional universe, by modifying its
solarsys.ssc, stars.dat, and hdnames.dat files.  The easiest file to modify is
the solar system catalog (solarsys.ssc), since it's a plain text file and the
format is very text-editor friendly.  It's also quite verbose, but that's not
a problem yet.

The units used for the solar system data may not be obvious.  All angle fields
in the catalog are in degrees.  For planets, the period is specified in earth
years, and the semi-major axis in AU; for satellites, days and kilometers are
used instead.

When adding objects, they should be included in their own sub-directory under
Celestia's "extras" directory.  For example:
  celestia <dir>
    extras <dir>
      yourNewObject <dir>
        about.txt
        install.txt
        object.dsc
        object.ssc
        object.stc
        models <dir>
          object.3ds
          object.cmod
          object.cms
        textures <dir>
          medres <dir>
            objectTexture.??? (jpg, png, dds, or bmp)

YOU create each of the directories under the extras directory.  By using this
structure, activating and de-activating your new objects will be easy.  Simply
move the sub-directory "yourNewObject" outside of the extras directory.  Some
users have found that adding category-name sub-directories under extras to be
useful, such as:
  celestia
    extras
      Deep Sky Objects
        yourNewObject
      Galaxies
        yourNewObject
      Spacecraft
        yourNewObject

Texture files should be placed in textures/medres, as shown above.  Currently,
JPEG, PNG, BMP, and DDS are the only formats supported.

Models belong in the models directory.  Celestia can read 3DS models, and two
custom formats (.cms and .cmod).  The .cms files are currently used for rough
fractal displacement map likenesses of asteroids and small moons.  3DS meshes
are normalized to fit within a unit cube -- the Radius field determines how
big they appear within Celestia.

The stars.dat file is a binary database of stars, processed from the 50+ meg
HIPPARCOS data set.  The first four bytes are an integer (int) value
containing the number of stars in the database.  Following that are a bunch of
records of this form:
  4 byte int   : catalog number
  4 byte float : right ascension
  4 byte float : declination
  4 byte float : parallax
  2 byte int   : apparent magnitude
  2 byte int   : stellar class
  1 byte       : parallax error

RA, declination, and parallax are converted to x, y, z coordinates, and
apparent magnitude is converted to absolute magnitude when the database is
read.

For more detailed information about creating add-ons for Celestia, please
visit Selden's "Introduction to Celestia Add-ons" web page at:
  http://www.lns.cornell.edu/~seb/celestia/addon-intro.html


CELESTIA RESOURCES
------------------
Celestia Web Site:
  http://www.shatters.net/celestia/

Celestia User Forums:
  http://www.shatters.net/forum/

Selden's List of Resources for Celestia :
  http://www.lepp.cornell.edu/~seb/celestia/

Celestial Matters Website and Forums:
  http://www.celestialmatters.org/
  http://forum.celestialmatters.org/

Celestia Developer Center
  http://celestia.teyssier.org/

Celestia for Gnome
  http://pat.suwalski.net/celestia/

Celestia Source Code (SourceForge.net):
  http://sourceforge.net/projects/celestia/


CREDITS
-------

Authors
-------
  See the AUTHORS file

Contributors
------------
  Deon Ramsey ........... original GTK1 interface
  Christopher ANDRE ..... Eclipse Finder
  Colin Walters ......... Endianness fixes
  Peter Chapman ......... Orbit path rendering changes
  James Holmes ..........
  Harald Schmidt ........ Lua scripting enhancements, bug fixes

Documentation
-------------
  Frank Gregorio ........ Celestia User's Guide
  Hitoshi Suzuki ........ Japanese README translation
  Christophe Teyssier ... DocBook and HTML conversion of User's Guide
  Diego Rodriguez ....... Acrobat conversion of User's Guide
  Don Goyette ........... CEL Scripting Guide
  Harald Schmidt ........ Celx/Lua Scripting Guide


Other Contributors
------------------
Models of Mars Global Surveyor and Mars Odyssey were created by Shrox:
  http://www.shrox.com/
The Cassini and Huygens models are by Jack Higgins:
  http://homepage.eircom.net/~jackcelestia/

Most of the planet maps are from David Seal's site:
  http://maps.jpl.nasa.gov/.
A few of these maps were modified by me, with fictional terrain added to fill
in gaps.  The model of the Galileo spacecraft is also from David Seal's site
(though it was converted from Inventor to 3DS format.)

The Mars, Neptune, and Uranus textures and Mars, Moon and Mercury bump maps are
all from James Hastings-Trew's collection, and the Mercury texture is a recolored 
version of his. Some of the prettiest planet maps around are at: 
  http://gw.marketingden.com/planets/planets.html

Fridger Schrempp produced the 'available data' Pluto and Charon textures using
maps created by Marc Buie at Lowell Observatory.  Buie's maps were generated
from photometric data gathered during six years of mutual occultations of
Pluto and Charon.

Venus's clouds and the textures for Ganymede, Callisto and Saturn are from
Bj<EFBFBD>n J<>sson. His site at http://www.mmedia.is/~bjj/ is an excellent
resource for solar system rendering.

The Io and Europa maps are by Steve Albers. His planetary maps are at:
   http://laps.fsl.noaa.gov/albers/sos/sos.html

Saturn's rings were built by Grant Hutchison from Cassini imaging, with
transparency information derived from stellar transit data obtained from:
  http://pds-rings.arc.nasa.gov/ringocc/ringocc.html

Titan's cloud texture in natural colors and its surface map at
near-infrared wavelength were created by Fridger Schrempp. They are
based on resources available from the imaging site (Ciclops) of the
Cassini mission,  
  http://ciclops.lpl.arizona.edu/index.php

The texture of Iapetus was created by Fridger Schrempp, using all available
imaging resources both from the Voyager mission and the recent Cassini fly-bys
from
  http://photojournal.jpl.nasa.gov

Many cylindrical projections of photographs were performed by Fridger
Schrempp with Matthew Arcus 'mmps' software, 
  http://www.users.globalnet.co.uk/~arcus/mmps/

Venus's surface is a copyright-free NASA image, prepared from Magellan radar
data. The original is available at 
  http://www.solarviews.com/cap/venus/venmap.htm

The Earth texture was created by NASA using data from the MODIS instrument
aboard the Terra satellite.  Further information is available from:
  http://earthobservatory.nasa.gov/Newsroom/BlueMarble/

The textures for the Uranian satellites were created by Ivan Rivera from JPL
data.  His Celestia page is: http://bruckner.homelinux.net/celestia.html

The Hyperion and Enceladus maps are photomosaics assembled by Phil Stooke and
colored by Jens Meyer.

Amalthea is a shaded relief map by Phil Stooke, colored by Wm. Robert Johnston
(http://www.johnstonsarchive.net/spaceart/cylmaps.html), and further modified
by Jens Meyer and Grant Hutchison.

Proteus, Janus, Prometheus and Epimetheus maps are by Phil Stooke.

Dione and Rhea are USGS maps colored and modified by Jens Meyer.

Tethys is a USGS map colored and modified by Grant Hutchison.

The Moon map by Jens Meyer is based on data from PDS Map-A-Planet at
http://pdsmaps.wr.usgs.gov/maps.html with colors from Mark Robinson at
http://www.earth.northwestern.edu/research/robinson/MOON/clem_color.html.

The Ida and Gaspra photomosaic maps are by Phil Stooke.

The Eros map is a shaded relief generated by Grant Hutchison from the NEAR
laser rangefinder shape model at:
  http://pdssbn.astro.umd.edu/NEARdb/nlr/#shape

The asteroid.jpg texture was created by Paul Roberts.

The textures for the five classes of extrasolar giant planet were created by 
Andrew Tribick.

The lower resolution textures were all converted from their higher resolution
versions using Gimp.

3D asteroid models of Toutatis, Kleopatra, Geographos, 1998 KY26, Bacchus,
Castalia and Golevka are courtesy of Scott Hudson, Washington State
University.  His site is:
  http://www.eecs.wsu.edu/~hudson/Research/Asteroids/models.html

3D models of Phobos, Deimos, Amalthea, Janus, Epimetheus, Prometheus, Pandora,
Hyperion, Larissa, Proteus, Vesta, Ida, Gaspra and Halley are derived from
Phil Stooke's Cartography of Non-Spherical Worlds at:
  http://publish.uwo.ca/~pjstooke/plancart.htm
and optical shape model dataset at:
 
http://pdssbn.astro.umd.edu/SBNast/holdings/EAR-A-5-DDR-STOOKE-SHAPE-MODELS-
V1.0.html

The 3D model of Eros was prepared from the NEAR laser rangefinder shape model
at: http://pdssbn.astro.umd.edu/NEARdb/nlr/#shape

The Phoebe base texture was created by Fridger Schrempp from 
the cylindrical map recently published by the Cassini imaging team, 
http://photojournal.jpl.nasa.gov/catalog/PIA07775

The Phoebe mesh was designed by Jerry Gardner aka Jestr, jestr@ntlworld.com, 
based on Phoebe's bumpy topography display from Cassini, 
http://photojournal.jpl.nasa.gov/catalog/PIA06070
  
The Tethys texture was created by Fridger Schrempp from recent Cassini imaging, 
http://photojournal.jpl.nasa.gov/catalog/PIA07781
merged with reprojected images from earlier Voyager missions. It was 
color-mapped by computer, using the natural color template, 
http://photojournal.jpl.nasa.gov/catalog/PIA06140
  
The Iapetus texture was created by Fridger Schrempp from recent Cassini imaging, 
http://photojournal.jpl.nasa.gov/catalog/PIA07778
merged with reprojected images from earlier Voyager missions. It was 
color-mapped by computer, using the near true-color template, 
http://photojournal.jpl.nasa.gov/catalog/PIA06167
  
Fridger Schrempp created the Lunar topography map, using Clementine laser altimeter
data, merged in the polar regions with topographic data  from Clementine 750 nm 
oblique and nadir images, 
ftp://ftpflag.wr.usgs.gov/dist/pigpen/moon/usgs/topo/global/

Grant Hutchison supplied the correct orientations for the major planets, their
moons, and a number of asteroids.

Selden Ball deserves a special mention for suffering more prerelease versions
finding more bugs, and giving more feedback than anyone else.

Christophe Campos aka ElChristou created the splash screen for Celestia.

The MacOS X icon was designed by Chris Alford: http://www.chrisalford.com/

The txf font format used by Celestia was devised by Mark Kilgard.

The star database (stars.dat) was derived from the ESA's HIPPARCOS data set.

Constellation boundaries are drawn from Davenhall & Leggett's "Catalogue of 
Constellation Boundary Data": 
  http://cdsweb.u-strasbg.fr/viz-bin/ftp-index?/ftp/cats/VI/49

This software is based in part on the work of the Independent JPEG Group.

Some versions of Celestia may use the SPICE system for spacecraft and planetary
information, developed by Caltech/JPL under contract to NASA.

A special thank you goes to all Celestia users who submit bug reports,
suggestions, and fixes.  Celestia wouldn't be the program it is today, without
your help.


Chris Laurel
  <claurel@gmail.com>
  http://www.shatters.net/~claurel/
  http://www.shatters.net/celestia/