Celestia/print version

Introductory Text

Celestia provides photo-realistic, real-time, three-dimensional viewing of the Solar System, the galaxy and the universe. It is an easy to use, freely-distributed, multi-platform, open source, software package which has become a valuable tool for astronomy education. Used in homes, schools, museums and planetariums around the world, it also is used as a visualization tool by space mission designers. Versions are available for computers running Windows, Macintosh (Mac OS X) and Linux operating systems.

Although it is optimized for 3D astronomical visualization, Celestia can be used to display and explore other 3D environments, too.

And, for some reason, many people seem to find exploring with Celestia to be a lot of fun.

Using Celestia

How to use Celestia is described in detail in Frank Gregorio's Celestia 1.6.0 User's Guide.

Go to Getting Started Template:Celestia/About this guide

Why would anyone want to use Celestia?

• Celestia is free. There are no charges or fees of any kind ever, and everything, including the source code, is open source, meaning that every part of it can be scrutinized, modified, and built on your own.

• You can explore the universe. Celestia allows you to travel throughout the solar system, stars, and galaxies in three dimensions. It shows the objects as they are in real time. You can go forward or back thousands of years as it can predict the trajectory of many different objects, or slow down time to a crawl. You can accurately view positions of objects from the Earth's position, or leave its confines should you wish.

• It's easy to use. You can easily explore anything from the scale of tiny asteroids to massive galaxies with simple controls and a simple interface.

• It's expansive. The default version of Celestia contains over 100,000 stars, 10,000 galaxies, the Solar System and its planets, moons, and dozens of smaller bodies.

• It's expandable. If Celestia doesn't have what you want to see, you can easily download and install hundreds of different add-ons created by the community, covering everything from high-resolution textures to new stars and planets, and even fictional systems from sci-fi franchises.

• It can be educational. Many people, such as Frank Gregorio, have made comprehensive lesson plans for educating and entertaining curious minds.

• You can customize it however you want. Celestia easily allows you to build your own worlds and creations, making it useful for everyone from artists to astronomers.

Why not use some other program?

Free and open source:

• Gaia Sky
• Stellarium
• OpenSpace
• WorldWide Telescope

Free and closed source:

• Orbiter
• NASA's Eyes

Commercial:

• SpaceEngine
• Universe Sandbox
• Starry Night

All of the above software titles are useful in their own right. However, Celestia is open-source, meaning it is open to all kinds of collaboration and improvement from anybody, and it allows thorough journeys to the planets, their moons, the stars, asteroids, comets, and galaxies — all in one place, and while being quite light on processing power. These visits are up-close and personal and in vivid detail with exceptional graphics and animations. If it's missing in Celestia, you can install any of hundreds of add-ons that include spacecraft, nebulae, and others, and see what they look(ed) like in space.

What can't Celestia do?

• Telescope control

• 180 degree field of view

• Sound (prior to recent builds of 1.7.0)

• 3D stereoscopic or anaglyph viewing

• ?

Using Celestia

Getting Celestia to Run

• You can easily install Celestia on computers running Windows, macOS or Linux. If you are experienced in compiling programs from source code, you can also install it on computers running other operating systems. There are also mobile versions available on various app stores.

For computers, the current version of Celestia is available at the download page of Celestia's website. For mobile devices, the current version of Celestia can be downloaded from an app store, or from celestia.mobi.

Older versions of Celestia are also available from the archive on GitHub or the releases section of the current GitHub repository. In the past, Celestia's source code was hosted on SourceForge, and older versions may also be found there.

Prereleases of the next version of Celestia are announced on the Celestia Web Forum in its Development Sub-forum. If you build Celestia from source code, you can also generate a pre-release of Celestia v1.7 which is quite stable.

Windows

If you have downloaded the Windows version of the Celestia installation executable, then you simply need to run the .exe file that you downloaded. It will install Celestia wherever you specify.

Celestia works fine when installed in any version of Windows, from Vista through Windows 10. Celestia v1.6.1 and earlier also works on Windows XP.

Recommendations:

Vista and later versions of Windows, including Win7 through Win10, are particularly protective of software installed in the Program Files directory tree. You will have far fewer problems modifying Celestia if you install it somewhere else. You could, for example, create the directory C:\MyPrograms\ and install Celestia there. The installation program lets you browse to wherever you want to install it.

Note that if you already have a previous version of Celestia installed, the installer for v1.6.2 (the current version as of this writing) will try to install it in the same directory. This can be fixed by temporarily renaming the directory to "Celestia161" or similar.

Installing Celestia v1.7.0 pre-releases

An experimental Windows installer for Celestia v1.7.0 can be found here. On Windows 10, Celestia v1.7.0 can also be installed through the Microsoft Store, though this version has several limitations.

Alternatively, you can set up a pre-release version of Celestia v1.7.0 on Windows through GitHub. This requires some step-by-step instructions. You may need 7-Zip or a similar program to extract some of the files. You can also use the second step of these instructions to update the binaries in an existing install.

First, download the files from GitHub. Go to Celestia's GitHub repository and click the green "Code" button, then "Download ZIP", or if you have GitHub Desktop, "Open with GitHub Desktop". Make a folder somewhere (e.g. "C:\MyPrograms\") called "Celestia 1.7.0" or similar, and move the files there. You will also need to download the files from the CelestiaContent repository and put them in the same folder.

Second, download the binaries (i.e. the actual program). Currently, Windows builds of Celestia v1.7.0 are generated through GitHub Actions and require a GitHub account to download. Click on the latest build (at the top of the list), then under "Artifacts", click on either "celestia-x64" (64-bit) or "celestia-x86" (32-bit). Within the zip file, there will be a folder called "celestia", which contains three more zip files - "celestia-dep.7z", "celestia-qt.7z", & "celestia-win.7z". Extract all three of these, and move all files from the "RelWithDebInfo" folder of each zip file to your Celestia 1.7.0 folder.

Now you can run Celestia, either "celestia-qt.exe" or "celestia-win.exe". You may want to create a desktop shortcut to one of these.

Windows Vista-specific information

A few words of caution to Windows Vista users... (These may also apply to Windows 7.)

If you run the setup program as a Windows XP-compatible application, you'll find that the program runs fine and that Celestia operates as it should. You can also run the Celestia executable in the native Windows Vista mode too.

Savvy Windows XP users will find that there are a lot of things to get used to in the XP-compatible mode though. If you modify a planet texture, for example, you may find that your modified texture was NOT saved to the Celestia program directory where you got it from originally.

Vista likes to create shortcuts to modified textures, and these - for some reason - aren't readily available to the Celestia program. If you're using Windows Explorer to view the Celestia texture files, click on the "Compatibility Files" area at the top of your screen to see your modified texture. If you like, you can then copy and/or move the new texture to the C:\Program Files\Celestia\textures directory of your choice.

Recommendations:

Vista users should install Celestia as a native Vista program. When Celestia is installed as a previous version of Windows-compatible program, it simply causes more problems than it solves.

macOS

Celestia is provided for macOS in a disk image. Once you have downloaded the file, simply open it and then copy the application file "Celestia" from the window that shows up to the "Applications" folder, as for most applications in macOS.

Celestia can also be installed from the Mac app store - this is a beta version of Celestia v1.7.0.

Linux

The below information may be outdated; see the GitHub repository's INSTALL.md file for up-to-date information.

Every Linux distro does things a bit differently but the major ones do have some version of Celestia in their software repos.
For example:

fedora -- "yum install celestia"
-- but this is WITHOUT spice support

OpenSUSE -- "zypper in celestia"
-- also WITHOUT spice support

Debian -- "apt-get install celestia"

To be sure you have the most recent version of Celestia, you should consider building your own copy from source. Then consider contributing your results to the appropriate repo. Many repos have OLD versions in them since nobody has contributed an updated version. Some of the repos even have Celestia v1.5 in them. Celestia v1.6.1 was the last officially released version. If you build from source, you can generate a pre-release of v1.7, which is quite stable.

Few repos, if any, provide Celestia with SPICE support, so NO spice kernels will work if you install Celestia from an rpm or deb or xz.
Also there ARE NO prebuilt packages using qt 4 for KDE4, so no kde4 /qt 4 prebuilt rpm's, or deb's or xz's.

In the case of Ubuntu and other Debian derivatives, Celestia is split into free and non-free versions because of their strict interpretation of how licensing should be handled. Both are needed for Celestia to work properly.

Mobile

For mobile devices, the current version of Celestia can be downloaded from an app store, or from celestia.mobi.

Building from sourcecode

See Celestia/Development

Introduction

Celestia uses OpenGL graphics routines to draw its pictures of the universe. Unlike DirectX, which is available only on computers running Windows, OpenGL graphics libraries are available for many different types of operating systems. OpenGL was originally developed by SGI but now is available for use on almost all computers and graphics hardware. The OpenGL WikiBook has more details.

Celestia can run on most computers, but to see all of its "eye candy" a modern graphics card implementing OpenGL v2.0 is essential. Even when the best available graphic cards have been installed, some computers have problems running Celestia because their graphics drivers are out of date or buggy. Regularly check the Web site of the manufacturer of your computer or of your graphics card to make sure you have the current driver version. Updated drivers are provided often.

Graphics Card Limitations

Many graphics card limitations are described in Celestia's list of Frequently Asked Questions:

What graphics card should I get?

Operating System Limitations

Many computer and O/S limitations are described in Celestia's list of Frequently Asked Questions.

Linux

• OpenGL is distributed in many Linux flavors since is open source, but the graphic drivers not always are open source, thus, aren't included in all Linux distros.

Mac OS X

• Graphics driver updates for Mac OS X are available in updates to Mac OS X itself, not in general as separate driver updates by NVIDIA or ATI. This means "upgrade your driver" on OS X means "make sure your version of OS X is up-to-date". You may have to spend money in order to get the current version of OS X.

• Point sprite primitives do not work on versions of OS X earlier than 10.4.
• Point sprites are not supported properly on Tiger (PPC and Intel architectures). Colors may appear incorrect, and hard freezes requiring a reset have been seen. VBO seems to be involved. Apple has been made aware that this is almost certainly a driver bug, but no fixes have been promised. Behavior on Leopard is unknown.
• The OpenGL 2.0 render path is only supported on Tiger 10.4.3 or later, regardless of the graphics card.
• Holes may appear in orbit paths on certain ATI configs. A workaround is being investigated. Fixed in 1.5.0.

Windows

• The graphics drivers provided with your brand new computer hardware already are obsolete. Usually several months have passed between the time its software was configured and it was provided to you. Be sure to download and install the most recent graphics drivers provided on the Web site of the manufacturer of your computer's graphics hardware.

• Windows XP includes a software-only OpenGL library. It's used on systems without 3D hardware or when hardware acceleration is disabled in the Display Control Panel. It implements only OpenGL v1.1, Celestia's Basic rendering path, so it has limited functionality and runs rather slowly, but it is relatively bug-free.

• Celestia does not use DirectX, which is Microsoft's proprietary 3D graphics programming library. Unfortunately, whenever Microsoft's DirectX libraries are updated, the manufacturer's OpenGL drivers are replaced by obsolete versions provided by Microsoft. Whenever you update DirectX, be sure to reinstall the graphics drivers using the most recent versions provided by the manufacturer of your computer's graphics hardware.

• Introduction

  When Celestia starts, by default it shows a 3D image in a window on the computer's main screen. Depending on its user interface, Celestia may be able to occupy the entire screen.

  Image quality can be improved somewhat, too.

  
  

  Size

  Linux

  Celestia starts in a window, you can exter/exit fullscreen mode by typing Alt-Enter.

  Mac OS X

  Celestia starts in a window whose position and size are saved. Enter/exit fullscreen mode by typing Cmd(Apple)+F. Move your mouse to the top of the screen when in fullscreen mode to access the menu bar.

  Right-clicking (control-clicking) on objects to bring up a context menu, switching to other applications, hide, and opening panels like Preferences and Help continue to work 100% in full screen mode. Multiple screens should be detected properly, although when switching to fullscreen mode Celestia currently only targets the screen which is most covered by the Celestia window.

  Various display options can be accessed from Celestia > Preferences or the Display menu.

  Windows XP, Vista and 7

  Celestia starts in a window which is located in the same place and at the same size as when Celestia previously exited. The menu "Render / Select display mode..." provides access to the list of full-screen resolutions claimed to be supported by the graphics display. Once the default resolution has been configured using that menu, you can exter and exit fullscreen mode by typing Alt-Enter.

  Edges

  By default, Celestia does not enable anti-aliasing. This means that you'll see stair-step jaggies and moving dots on the edges of objects, especially on diagonal lines. Turning on anti-aliasing will make the display run more slowly, but objects will look better.

  Celestia includes two different anti-aliasing options: a menu and keyboard option to smooth the orbital path lines, and a configuration file option to enable full-screen anti-aliasing.

  You can separately enable various levels of full-screen antialiasing in the controls for your graphics hardware. This will affect all 3D programs, not just Celestia.

  Menu and keyboard (orbit smoothing)

  The Windows menu option Render/Antialiasing turns on hardware smoothing of the orbital path lines.

  (What are the corresponding Linux, and MacOS menu options?)

  The keyboard command Ctrl-X is available in all versions of Celestia to toggle this display rendering option.

  celestia.cfg (full screen)

  To enable full-screen antialiasing within Celestia, edit the file celestia.cfg. Find the line which currently says

  # AntialiasingSamples 4

  and delete the #. If your graphics hardware supports higher levels of antialiasing, you can increase its value appropriately. This feature will work only if your graphics hardware has been configured to allow application control of antialiasing.

  hardware control panel (full screen)

  Alternatively, you can open the software control panel for your graphics hardware and turn on its antialiasing features permanently. This will affect all 3D programs, not just Celestia.

  In either case, while the edges of objects will look much better, Celestia will run more slowly. The framerate reduction will depend on the quality of your graphics hardware.

  Introduction

  A Render path is Celestia's way of classifying graphics capabilities. Its different Render paths correspond to different sets of OpenGL functions.

  Not all render paths may be available on your computer. A render path will be available only if your computer's graphics software includes the OpenGL functions that it uses. More sophisticated render paths require more recent graphics hardware, but not the most expensive version of a card.

  When it is first started, Celestia automatically selects the best render path based on the graphics capabilities advertised by the computer's OpenGL library. However, you can interactively select any available render path. Celestia remembers which path you selected last and will use it when the program is restarted. Choosing another render path may be necessary if there are problems due to bugs in your computer's graphics drivers.

  To select an alternate render path, type a Ctrl-V. That is, press the "V" key while holding down the "control" key. This causes Celestia to switch to the next available render path. The name of the newly selected render path will be shown briefly in the lower left hand part of Celestia's window.

  Render Paths under Linux

  see the windows it is THE SAME

  Render Paths under MacOS X

  Some of the render paths available on computers running MacOS X are

  • Basic
  • Multitexture
  • DOT3+ARB VP
  • NV C/VP
  • NV C+ARB VP
  • OpenGL 2.0

  Render Paths under Windows

  Some of the render paths available on computers running Windows are

  • Basic
  • Multitexture
  • OpenGL Vertex Program
  • OpenGL Vertex Program/Nvidia combiners (only on Nvidia graphics cards)
  • OpenGL 2.0

  Celestia can show more and improved "eye candy" when using the later render paths:

  • Basic requires OpenGL v1.1.

  It shows the fewest effects. It's available even on systems which have only Microsoft's software support for OpenGL and have no 3D hardware acceleration.

  • Multitexture requires OpenGL v1.2.

  It adds NightTextures and the shadow of a planet on its rings.

  • OpenGL Vertex Program requires OpenGL v1.4.

  It adds specular highlights on oceans, shaded mountainsides and the shadows of rings on a planet.

  • Nvidia Combiners adds a rudimentary haze effect. (Only for Nvidia graphic cards)
  • OpenGL 2.0 requires OpenGL v2.0.

  It improves the edges of eclipse and ring shadows, draws the shadows cast by as many as four separate light sources, allows for point sprites, and adds sophisticated atmospheric effects, including cloud shadows on the ground. Haze can be drawn, too, based on Mie and Rayleigh scattering functions. (These scattering functions are available only with Celestia v1.5.0 or later.)

  OpenGL Versions

  To find out what version of OpenGL the graphics drivers on your computer claim to support, select Celestia's Help menu. The entry "OpenGL Info..." will list details about your computer's graphics hardware and software.

  Introduction

  Celestia can be started either by clicking on its icon or by typing a command into a terminal window. Under Windows, the terminal window is often called a DOS window or CMD window.

  A typical command to run Celestia might be

  cd Celestia
  ./Celestia
  

  The command line can optionally include the following qualifiers. These qualifiers are different depending on which command interface Celestia was built for. Each command qualifier (aka switch) should be prefixed by two hyphens

  Windows command qualifiers

  • --dir <path>

  Change root celestia directory to <path>

  • --fullscreen

  Start Celestia in fullscreen mode

  • --once

  Send the command line to a running instance of Celestia. If no running instance exists, a new one is started.

  • --url <url>|<filename>

  Start in the given <url> or if the parameter is the name of a script file, execute <filename>.

  • --verbose >    <filename>

  Write debug messages to <filename> (Although --verbose can only write to a file, the redirection > is required.)

  gtk command qualifiers

  • --conf

  Use alternate configuration file

  • --dir

  Use alternate installation directory

  • --extrasdir

  Use additional "extras" directory

  • --fullscreen

  Start full-screen

  • --nosplash

  Disable splash screen

  • - v [0|1]

  Enable debug mode.

  KDE command qualifiers

  • --conf

  Use alternate configuration file

  • --dir

  Use alternate installation directory

  • --extrasdir

  Use additional "extras" directory

  • --fullscreen

  Start full-screen

  • --nosplash

  Disable splash screen

  • +[url]

  Start and goto URL

  • <url>

  Start in the given url/execute script file.

  • - - help

  Command-line help

  Exploring Celestia's Universe

  Introduction to using Celestia

  To start Celestia, you should double-click on its icon. As it starts, it first shows the Sun, and then takes your viewpoint to the sunlit side of the Earth. When you get there, you can tell Celestia to show you other interesting sights.

  Initially, Celestia opens in a window on your screen. For a more immersive experience, you can tell Celestia to take over the entire display. Open Celestia's menu Render/Select Display Mode and choose an appropriate screen resolution. When it's in full-screen mode, if you move the cursor up to the top of the screen, you should see Celestia's menu bar again, where you can choose to go back to windowed mode.

  Some may think Celestia is a game. In a way it is but it is much more than that. Like most programs (with graphics and objects) of today the mouse is the primary way of getting around. Celestia does use the mouse to rotate/panned the observers POV with a combination of left and right mouse click and drag functions. However to truly get the most out of Celestia the keyboard shortcut letters bring the full power and beauty of the program into play. People who are more game enthusiasts may find the interface of Celestia boring after a few minutes if they only use the mouse. So, start learning and memorizing the keyboard shortcuts. You can find a quick look of the keyboard shortcut commands in the Help/Control pulldown while the program is running. You can also find them in the Celestia User's Guide.

  Below are some introductory events and places you can explore in Celestia, using the keyboard and mouse. You will notice below some letters and words are in bold face. These are the keyboard shortcuts that can be typed to control Celestia.

  Earth's rotation and the pole star

  This needs a fairly wide field of view – use the comma (,) and dot (.) keys to adjust the window to around 60°. If you don't have the Earth on the screen, press the three keys H3G to go there. Then back away a little with the End key or your mouse's wheel. Adjust the number of stars with the [ and ] keys, setting a limiting magnitude of around 5.

  Adjust the rate of time to 1000 times faster (LLL) so the Earth can be seen slowly turning. The Earth spinning is what gives us day and night. Type a "y" to hover over one point on the Earth and see it enter light and shadow (day and night) as the Earth turns. Use the arrow keys Shift-← and Shift-→ to move round the Earth and see where night and day start and end. You can put the mouse cursor over a piece of land and just watch that point as day and night pass over it. This is best done with the clouds turned off (I). To turn the "sync orbit" off again, you can press F to return to "follow" mode.

  With the synchronous orbit on, back away from the Earth a little using the End key (or the rotary wheel of your mouse if it has one) so you can see more stars. You can press the Home key to move closer again. As you watch the stars go past, you might see distinctive patterns of stars go by. People used to imagine people and animals in the patterns in the stars. Press / to turn on the constellation lines, and = to turn on their names. You can use the space-bar to pause time and take a longer look at any interesting shapes.

  With the mouse, right-click and drag upwards to turn to look more Northwards. By the time you are looking squarely at the South pole of the Earth, the pole star Polaris should be visible. It's the star that's at the end of the tail of Ursa Minor, the "Small Bear", often called "the Little Dipper". If you watch for a while, you will see that all stars seem to revolve around that point while Polaris itself doesn't move much at all.

  Keeping this view, zoom closer to the Earth (Home) and notice the way day and night look on Earth from this view. Depending on the time of year, the Antarctic ice-cap might be on permanent daylight or permanent shadow. This can be easier to see if you speed up to 10000x (L). You can briefly speed up even more (use K to slow down again) to hop between seasons.

  Other Planets

  Start Celestia. You are looking at the Earth from the direction of the Sun. We want to look at the Earth from the other side. Back away from the Earth using the End key until the Earth is about the size of a pea, and then use Shift-← and Shift-→ to rotate around the Earth until the Sun is visible in the background. The Earth might be easier to see if you turn up the background illumination with the } key, although this is not realistic as it makes planets glow in the dark (only stars really do that). Now turn the time rate up to a million times faster by typing LLLLLL.

  You should notice the Moon whizzing round the Earth. Move closer or further away (Home/End) until the moon uses the whole width of the screen. The Moon takes about 28 days to go round the Earth. If you slow down time a bit by pressing K, you should be able to count the number of days (turns of the Earth) it takes for the Moon to go round once. You can turn the Moon's name on and off by pressing M. If you see a giant mass of names appear, all together, it's probably the names of all Jupiter's moons in the distance – Jupiter has a lot of moons. Speed back up to a million times again.

  You will notice that every year as the Sun goes past, it is accompanied by a collection of small bright dots. These are other planets. You can turn their names on and off with P. It's time to leave the Earth. Type HFC to follow and centre the Sun. Leave planet names on (P). Back away from the Sun a little and you will be able to see Mercury, Venus, Earth and Mars moving from side to side as they orbit the Sun. If you back away further you will be able to see 9 planets. The outer ones don't seem to be moving much, so press L speed things up a little. Time is passing at about a year every 4 seconds now.

  Let's turn on the planet's orbit lines – press O. They're not very clear seen edge on, so use the right mouse button to drag downwards until the orbits look circular, seen from above. You can't see all the orbit lines at once – if you move far enough away to get Pluto's orbit in, then the inner planet's orbits disappear. Move in to see the inner planet's orbits and the outer orbits are off the screen. By right-dragging, you can get a good edge-on view that shows that all the orbits are in almost exactly the same plane except for Pluto.

  You may notice as Jupiter goes past that it has a huge mass of orbit lines for its many moons. Four of them are big enough to be seen from the Earth by using binoculars.

  Time for a quick tour. This is possible best done with the orbit lines switched on. First, to about 1000x time rate (K,L). Then we can visit the 9 planets by typing 1G, 2G etc. Each of the number keys corresponds to a planet. Use Home and End (or the mouse scroll wheel) to zoom in and out, and right-drag to change the viewpoint and get a good look at each planet.

  While visiting the outer planets, it is worth looking from above to see just how much like a little solar-system their moons make. You may occasionally see a black spot move across the sunlit surface of Jupiter – this is the shadow of one of the moons as it passes between Jupiter and the Sun.

  Other Stars

  Not all stars are like the Sun. Some stars are hotter than the sun, some cooler, bigger, smaller, brighter and dimmer, redder, bluer. Actually the blue ones are hotter, and the red ones cooler.

  You cannot tell how far away stars are by just looking at them. So when people invented the constellations, they drew lines using stars that might be nearby, or far away. A good demonstration of this is to see how distorted familiar constellations would look if seen from a different angle – from a different place.

  Turn on the constellation lines (/) and use dot and comma to set the field of view to around 60°. Centre a star in the constellation of the plough (Ursa Major, also called the Big Dipper) by pressing the Enter (↵)key, typing the name megrez and enter again. Then type CF to centre and follow the star. Now hold down the right mouse key and drag around the screen. Your viewpoint is now many light years away from the Earth, orbiting around the distant star Megrez. Try both with and without the constellation lines. You can plainly see the 3D pattern of the stars. If you move right round the back of the Plough (or Big Dipper), you can see that all the constellation lines seem to point roughly in the same direction – the direction of Earth.

  It is interesting to return to the Sun while maintaining your view on Megrez – press T to track Megrez (keep it centred), then HG to go home. You can see the constellations return to their familiar shapes as we get back to the Sun. Press T again (or Esc) to stop tracking Megrez.

  Another good star to do this with is Arcturus in the constellation of Boötes.

  The constellations are all drawn with stars that are visible from the Earth, and are therefore the nearest stars to us. Turn the constellation lines on and then back a long way away (hold End), until all the lines are visible on the screen. Turn on more stars by holding the ] key and raise the limiting magnitude to about 10. Back away a little more until the whole of the galaxy is visible on the screen. Then right-drag so the galaxy is seen edge-on. You can see that the stars in the Celestia program form a sphere round the Sun. This is because we don't know the distances of all the other stars in the galaxy well enough to put their positions in the program – so the rest of the galaxy is just shown as a 'mist' of stars.

  Reduce the limiting magnitude to 10 or less again with the [ key.

  Other Galaxies

  You can fly to many other galaxies, much like our own. For example, pressing ↵M 31↵g takes you to the Andromeda Galaxy (aka M 31), the closest spiral galaxy to the Milky Way. You can always go home again by typing the keys H3G.

  • Introduction

    Celestia includes several catalogs of Locations on the Earth and on objects elsewhere in the Solar System. They're short, only containing lists of major features, like the Earth's oceans, continents and capital cities of nations. More extensive catalogs of Locations are available as Addons.

    Locations are labeled positions, usually on the surfaces of objects defined in SSC catalog files. They're shown if you select the option "Label Features" in the menu Render / Locations...

    When Locations are enabled, you can use Celestia's goto functions to travel to them.

    For more information, please see SSC Location

    • =Mouse and Keyboard Controls Used for Navigation in Celestia=

    Mouse Functions

    Celestia works best with a three-button wheel-mouse. Very inexpensive ones are available which work well with Linux, Mac and Windows computers.

    Left drag: Orient the view.

    Right drag: Orbit the selected object.

    Wheel: Adjust the distance to your current selection.

    Right + Left drag: Adjust your distance to the selection.

    Ctrl + Left drag: Adjust your distance to the selection.

    Shift + Left drag: Changes your field of view (e.g. => Telescopic view.)

    Wheel click: Toggles the field of view between 45 degrees and the previous field of view.

    Left click: Select the object you click on.

    Left double click: Center the selection.

    Right click: Brings up the context menu.

    Keyboard Navigation Commands

    H  : Select the sun. (Home.)

    C  : Center on the currently selected object.

    G  : Go to the currently selected object.

    F  : Follow the selected object.

    Y  : Orbit the selected object at a rate synchronized to its rotation.

    :  : Lock on the selected object.

    "  : Chase the selected object. (The orientation is based on the selected object's velocity.)

    T  : Track the currently selected object. (Keep the selected object centered in the view.)

    HOME : Move closer to the currently selected object.

    *  : Look back. Causes the view to shift from objects forward in the direction of motion, to objects rearward.

    END  : Move farther from the selected object.

    ESC  : Cancel the currently executing motion or script.

    Shift+C  : Center/orbit. (Center the selected object without changing the position of the reference object.)

    Left : Move (or roll) the camera view left.

    Right: Move (or roll) the camera view right.

    Up  : Move (or pitch) the camera view up.

    Down : Move (or pitch) the camera view down.

    Shift+ Arrow: Orbit the currently selected object in the direction indicated by the arrow selected.

    1-9  : Select any of the planets orbiting our Sun. (2=Venus, 4=Mars, etc.)

    ENTER  : Select a star or planet by typing its name.

    Ctrl+C, or Ctrl+INS  : Copy location URL to your clipboard.

    Time Control

    Spacebar : Pause/Resume the flow of time and scripts (toggle)

    J : Reverse/Forward time (toggle)

    \ : Set time rate: 1x forward (norm), cancels faster/slower x factors

    L : Change time rate : 10x faster

    K : Change time rate : 10x slower

    Shift+L : Change time rate: 2x faster

    Shift+K : Change time rate: 2x slower

    ! : Set time to current system date and time

    ? : Display light-travel delay between ovserver / selected object

    - (hyphen) : Subtract light-travel delay from current simulation time

    Labels (on/off Toggles)

    E : Galaxies

    Shift+E : Globulars

    B : Stars

    P : Planets

    Shift+P : Dwarf Planets

    M : Moons

    Shift+M : Minor Moons

    W : Asteroids

    N : Spacecraft

    = : Constellations

    & : Locations

    Render/Display (on/off Toggles)

    U : Galaxies

    Shift+U : Globulars

    ^ : Nebulae

    Ctrl+A : Atmospheres

    I : Clouds

    Ctrl+L : Night side maps

    Ctrl+T : Comet Tails

    Ctrl+E : Eclipse Shadows

    Ctrl+B : Constellations bounaries

    / : Constellation diagrams

    ; : Earth-based equatorial coordinate sphere

    Ctrl+K : Markers (placed on objects)

    O : Orbits (toggle ALL selected orbits)

    Render Options

    { : Decrease Ambient Light

    } : Increase Ambient Light

    ( : Decrease Galaxy Light Gain

    ) : Increase Galaxy Light Gain

    [ : Decrease Magnitude Limit :

              -  If AutoMag OFF : Decrease limiting magnitude (fewer stars)
              -  If AutoMag ON  : Decrease limiting magnitude at 45 deg FOV
    

    ] : Increase Magnitude Limit :

              -  If AutoMag OFF : Increase limiting magnitude (fewer stars)
              -  If AutoMag ON  : Increase limiting magnitude at 45 deg FOV
    

    Ctrl+Y : Toggle Auto Magnitude (auto adaptation of start visibility of FOV)

    , : Narrow Field of View [Shift+Left Drag]

    . : Widen Field of View [Shift+Left Drag]

    Ctrl+X : Toggle Antialias lines

    Alt+Enter : Toggle Display mode (Full-Screen / Windowed)

    Ctrl+P : Mark selected object

    + : Toggle Planet Texture type (Artisitic / Limit of Knowledge)

    % : Star color table toggle (classic / Blackbody D65)

    Ctrl+S : Cycle the Star Style (points / fuzzy discs / scaled discs)

    V : Cycle the Info text verbosity (None / Terse / Verbose)

    Ctrl+W : Toggle Wireframe mode

    Spaceflight

    F1 : Stop.

    F2 : Set velocity to 1 km/s.

    F3 : Set velocity to 1,000 km/s.

    F4 : Set velocity to speed of light.

    F5 : Set velocity to 10x the speed of light.

    F6 : Set velocity to 1 AU/s.

    F7 : Set velocity to 1 ly/s.

    A  : Increase velocity.

    Z  : Decrease velocity.

    Q  : Reverse direction.

    X  : Set movement direction toward center of screen.

    Number pad

    4  : Yaw left.

    6  : Yaw right.

    8  : Pitch down.

    2  : Pitch up.

    7  : Roll left.

    9  : Roll right.

    5  : Stop rotation.

    Joystick Controls

    X axis  : Yaw.

    Y axis  : Pitch.

    L trigger : Roll left.

    R trigger : Roll right.

    Button 1  : Slower.

    Button 2  : Faster.

    Introduction

    Celestia provides you with very powerful and flexible ways to control your view into Celestia's simulation of the cosmos. Once you understand how to manipulate its interactive controls, you can quickly and easily position yourself to view the astronomical phenomena that interest you. If is helpful to think of Celestia as providing a remotely-controlled camera that is at your command. The view that you see on your screen is determined by the location of the camera, the direction the camera is pointing, and the magnification of the camera's zoom lens. Each of these factors can be controlled independently.

    One important thing to understand is that both the location and direction of the camera are specified relative to some frame of reference. The frame of reference may be attached to a moving object (such as a planet or moon). If so, then the actual location and direction of the camera (with respect to absolute space) will automatically change as the object moves. This is often very convenient, because it means that you do not have to continuously change the camera location and direction manually in order to keep the object in view.

    Commands which change Celestia's view of the universe are described in the file Celestia/controls.txt

    Zoom Control

    The magnification of the camera's zoom lens determines how large or small objects will appear on your screen, and also how much of the environment around you is visible (the field of view). If you increase the magnification then objects will appear larger, but you'll have a smaller area in view. (You can also make objects appear larger by moving the camera closer to them. The difference between zooming and moving the camera is important, as we will explain below.) Celestia displays the current magnification factor and field of view in the lower right hand corner of the window. As you zoom in, the magnification factor will increase, and the field of view will decrease. Zooming out has the opposite effect. If you zoom out to a very large field of view, the view will become distorted, much like what you would see with a fish-eye lens.

    Repeatedly typing a comma (,) narrows the field of view, increasing the magnification. Repeatedly typing a period (.) widens the field of view, decreasing the magnification.

    

    Mars zoomed in at 4411.19X in Celestia

    There are several keys that can be used to control the rate and direction of the passage of time.

    
    

    Table of keys

    Key	Effect
    J	Reverse time
    K	Decrease rate by 10x
    Shift+K	Decrease rate by 2x (new in version 1.5.0)
    L	Increase rate by 10x
    Shift+L	Increase rate by 2x (new in version 1.5.0)
    Space	Stop time
    !	Set time to the computer's current time
    ?	Display travel time for light between observer and selected object
    -	Subtract the above light travel time from Celestia's current time
    \	Set time to real time

    Introduction

    A Cel: URL is a bookmark that saves the time, location, rendering options and other settings of a specific Celestia event or place. These URLs can be exported and published as regular HTML, so that any Celestia user can share a Celestia scene with any other.

    The Windows version of Celestia includes a Bookmark menu. Those bookmarks are not the same as Cel: URLs.

    To record a Cel: URL to your computer's "clipboard", type a Ctrl-C, or the usual "copy selected region" keyboard shortcut. On a Windows system, you can type a Ctrl-Insert.

    To paste a Cel: URL into a document, type a Ctrl-V, or the usual "paste clipboard".

    Potential incompatibility warning

    Unfortunately URLs recorded by one version of Celestia often are not compatible with other versions. The origin of Celestia's coordinate system changed in V1.5. As a result, URLs recorded by previous versions of Celestia place the viewpoint hundreds of AU from the intended viewpoint. Similarly, the rotation of the Earth was greatly improved in Celestia v1.6. As a result, URLs recorded by V1.5 for viewpoints on the Earth's surface will place the viewpoint tens of kilometers from the intended viewpoint. Also, although URLs recorded by previous versions of Celestia can be read by V1.6, the URLs generated by V1.6 cannot be used by previous versions of Celestia.

    Fix for Linux if clicking on a Cel: URL does not work

    Depending on the specifics of your installation, Celestia might not have been registered to handle the Cel: URLs. If that is the case, you can remedy as follows (this should work on any system compliant with the XDG specifications).

    1. Enter xdg-mime default celestia.desktop x-scheme-handler/cel in a terminal. (This registers Celestia as the program that handles cel: links.)
    2. Edit celestia.desktop, replacing the line Exec=celestia-gnome with Exec=celestia-gnome %u, so that the system knows that it has to pass the URL argument to Celestia, when launching it. The desktop file is usually found in /usr/share/applications/ and if you don't want to edit files with root, you can instead copy it to $HOME/.local/share/applications/ and edit it there (or more generally copy it from $XDG_DATA_DIRS/applications to $XDG_DATA_HOME/applications/). Optionally, you can also add MimeType=x-scheme-handler/cel; to the desktop file. (See the XDG desktop entry spec.)

    • Introduction

      Under some operating systems, Celestia can create a snapshot, recording its current on-screen display to a file. It also may be able to create a video recording of a sequence of frames while it is running. Other operating systems may require an external screengrab or video recording program.

      Linux

      Currently video recording from within celestia does not work. A file is created, however it is empty.

      Image screenshots work as expected.

      MacOS X

      Screenshots and movie recording have not yet been implemented in the osX version of Celestia. For the moment you can use system commands to take some screenshots.

      Some people have reported that CaptureMe does a reasonable job of recording movies.

      Windows

      When running the Windows version of Celestia, both snapshots and movies can be created:

      • Select the menu option "File/Capture Image..." or type the <F10> key to record a snapshot of the current view.
      • Select the menu option "File/Capture Movie..." or type <Shift-F10> to start recording a movie of what Celestia is showing.
      • Type <F11> to actually start (or pause) the recording.
      • Type <F12> to finish recording.

      Understanding Celestia

      What is Celestia?

      Celestia is a freely-distributed, multi-platform, open source software package that provides photo-realistic, real-time, three-dimensional viewing of the solar system, the galaxy and the universe. It has proved a valuable tool for astronomy education, and is used in homes, schools, museums and planetariums around the world. Versions are available for Windows, Macintosh (MacOS X) and Linux computers.

      Where can I get more information about Celestia?

      The Celestia Website has some additional information about Celestia.

      The Celestia Forum is a good place to look for or ask for additional information. You'll find lots of friendly people there.

      The Celestia Motherlode has many Celestia resources. (Unavailable 2020-11-18)

      Where can I get the most recent version of Celestia?

      You can download the latest version of Celestia (v1.6.1) from SourceForge.

      Prerelease versions are announced in the Celestia Web Forum in its Users Forum.

      What changes have been made to Celestia since the last version?

      The developers maintain a list of all new functionality and bug fixes in the Celestia ChangeLog, which is located at SourceForge (most recent changes listed at bottom).

      Questions about how Celestia works

      Celestia crashes, what it draws is messed up or it's extremely slow. What can I do?

      Celestia makes use of the most advanced features of OpenGL that your computer's graphics driver claims to support. Many older OpenGL implementations have serious bugs. Here are some options for improving Celestia's display, with the most likely ones first:

      1. Make sure full hardware acceleration is enabled in your display properties.
      2. Upgrade to the most recent drivers for your graphics card. Download them for free from the Web site of the manufacturer of your card, not from Microsoft.

      Nvidia drivers can be downloaded from http://www.nvidia.com/content/drivers/drivers.asp

      ATI drivers can be downloaded from http://ati.amd.com/support/driver.html

      Notes:

      1. Graphics chipsets integrated into laptop systems usually require drivers provided by the manufacturer of the laptop itself. Too often proprietary "glue chips" prevent the chip vendor's drivers from working properly.
      2. Reduce or disable hardware acceleration to verify that the problem is hardware related.

      Square Stars

      Intel graphics chipsets and drivers have had this problem for many years. The only fix is to type Ctrl-S several times while running Celestia. That'll select other "Star Styles", one of which might be drawn better.

      Windows 7, 8, 8.1 or 10

      Update your computer's graphics drivers. Follow the instructions on the Web site of the manufacturer of your graphics hardware.

      Windows XP

      1. Whenever you upgrade Microsoft's DirectX software, you must upgrade or reinstall the graphics hardware manufacturer's graphics drivers afterward. Installing DirectX installs Microsoft's copies of the drivers, which usually are several generations old.
      2. To disable hardware acceleration under Windows, open the "Display Properties" window. Select the "Settings/Advanced/Troubleshoot" tab. (not the "Troubleshoot..." button). Move the "Hardware acceleration" slider all the way to the left. Click on the "OK" buttons to change the settings in use. This will cause Windows to use Microsoft's Generic OpenGL v1.1 library, which is limited, but seems to have relatively few bugs. It does everything in software, works on 2D displays, and is quite slow.
      3. Driver Upgrade Procedure
         1. download driver installation program
         2. use the Control Panel / Add or Remove Programs menu to delete the current graphics drivers.
         3. Reboot
         4. Cancel out of XP's offer to install new drivers.
         5. Run the Installation program for the new drivers.
         6. Reboot
         7. Configure desktop resolution and other desirable features.

      The two reboots are essential in order to cause the old low-level drivers to be deleted. Without those reboots, the old low-level drivers will not be deleted and the new installation will not work properly, although it may not generate any error messages.

      MacOS X

      For Apple PPC and Intel computers running MacOS X, you must upgrade to the most recent version of the operating system. Updated drivers usually are not available separately.

      Apple's OpenGL on MacOS X often has serious bugs which sometimes are not fixed in the most recent release of MacOS. You must report those problems to Apple, otherwise they will not get fixed.

      Linux

      For computers running Linux, you usually can download the drivers for free from the Web site of the manufacturer of your graphics card.

      ATI's fglrx drivers for Linux often have serious bugs. Try to use the driver shipped with the most recent version of Xorg's X server software.

      Celestia draws the Moon in shades of purple, blue and red. Why is it doing that and what can I do?

      Your graphics chipset and its drivers aren't drawing bumpmaps and normalmaps properly: their OpenGL routine "GL_ARB_vertex_program" is defective. (This is often seen with the newer Intel graphics chips.) Assuming you've already installed the most recent drivers,

      1. Download and install a different version of Celestia. The program is frequently revised.
      2. Turn off some of Celestia's advanced display features.
         1. Type a [Ctrl-V] several times to select "Basic" or "Multitexture" render paths instead of the OpenGL Vertex programs. This disables the use of vertex and shading programs temporarily. If this does improve things after you've followed the previous suggestions, then you need to do the next step:
         2. Tell Celestia to ignore specific features that your OpenGL library claims (falsely) to support. To do this, edit celestia.cfg. Remove the # that's in front of the line

      IgnoreGLExtensions [ "GL_ARB_vertex_program" ]
      

      Celestia's Help menu lists all of the routines in your system's OpenGL library. Add equivalent Ignore lines for other suspicious routines.

      
      Addendum provided Tech Sgt. Chen:

      Shut down all background programs on your system before running Celestia (i.e., antivirus software, multimedia software such as REAL Player, Musicmatch, etc.) Graphics programs are notorious for consuming system resources and even the best of graphics cards are better off without competing for those resources.

      Celestia still crashes, draws funny stuff or is extremely slow. What can I do?

      Report the exact circumstances and details of your hardware and software in the "Celestia Bugs" section of the "Celestia forum". Celestia runs on many different hardware and software configurations. It is not appropriate to ask people to guess what you have. For example:

      Problem: Celestia crashes when I look at Saturn with Ring Shadows enabled 
      System: 256MB 1GHz Pentium 4, Windows 98 2nd ed 
      Graphics: 128MB Radeon 9700, Catalyst 3.2, OpenGL v1.3.9088 
      Program: Celestia v1.3.0 
      

      Hopefully you know the System information. If you're running Windows, System details usually are available in the Control Panel's System Properties menu.

      Some of the Graphics information can be found in Celestia's Help menu. If you're running Windows, more details can be found in the Control Panel's Display Properties menu.

      Where can I get another version of Celestia that might work better?

      Older versions of Celestia are available on SourceForge v1.2.4 is extremely robust, but does not include many recent features.

      Visit the "Celestia Forum" and ask for help if you are having problems with Celestia v1.6.1.

      I want to see all possible Celestia eye candy. What kind of graphics card should I get?

      As of 2017, you can get whatever graphics card you like. More memory will allow more and higher resolution objects to be viewed, but the most advanced features of Celestia use only the features provided by OpenGL v2.0. All modern graphics hardware, including Intel's embedded graphics support OpenGL v3 or later. The current version of the Mesa software graphics library also provides OpenGL v3.

      Sometimes a screenshot captured in Celestia will have multiple boxes around it, as if Multiview was on. How can I get rid of it?

      To make a good clean screenshot image, press [Ctrl + D] before you capture the image. This cancels Multiview.

      (provided by ElPelado)

      I can't turn off the Red/Green diamond in the center of the selected planets.

      You are seeing a Mark. Disable Marks by pressing Ctrl+k (the "Control" key and the "k" key). Marks also can be turned on and off in the "Render/View Options..." menu of Celestia v1.3.1 pre3 and later.

      (provided by ElPelado)

      I want to write some scripts for Celestia. How can I do it?

      Briefly:

      Celestia includes a very simple scripting language of its own which understands commands like "go here, look there, set flag, display text". These commands should go into a file with the filetype .CEL

      Celestia also includes Lua, a sophisticated, general-purpose scripting language. Scripts written in that language should be put into a file with the filetype .CELX

      For more information see Celestia/Scripting

      Questions about objects (not) seen in Celestia

      Why are my favorite stars not in Celestia?

      Celestia v1.6.1 includes only stars that had their distances measured by the Hipparcos satellite. Hipparcos was not used to measure the distances to many dim, variable or close double stars. Someone may have created an Add-on that includes your stars, though. Or consider creating the necessary STC file yourself and contributing it.

      Celestia v1.6.1 also includes all of the stars within 20 LY of the Sun, as well as about 200 double stars. (There are actually many more double stars than that, but relatively few have had their orbital parameters accurately measured.)

      The Sun and the Moon are much too small in Celestia. What's wrong?

      Their diameters are exactly right. As seen from the earth, they both are about a half-degree across. Celestia's default window is about 45 degrees across, so the Sun and Moon are about 1% of that. They are drawn only 10 pixels wide if your screen is 1024x768.

      Remember that your computer screen is only about 10-20 degrees wide in your own field of view. Celestia's 45 degree field provides a "wide angle" view of the sky. This makes objects look smaller than you might expect.

      The apparent large size of the Sun and Moon as we see them in the sky is a psychological illusion. There are several different explanations for this. If you take a picture of the moon with a camera lens that has the same field of view as Celestia, you may be surprised at the small size of its image.

      At least one book has been written about this effect: The Mystery of the Moon Illusion: Exploring Size Perception, by Helen Ross and Cornelis Plug. Review of their book

      A simple experiment was suggested by "HarrieS", a guest on the Celestia forum:

      Here is something you might try: a finger at arm's length is about two degrees wide for most people. That means that you can fit four moons side by side. Go outside and check it. Now have a direct look at your finger indoors. Can you still believe that four moons will fit on it?

      And Dalle of the Forum wrote

      But if your head is positioned e.g. 70 cm away from your e.g. 17" monitor, which measures 32 cm across (at least mine does), then the effective field of view looking at the Celestia sky "through" your monitor screen is 2*arctan((32/2)/70)) ~ 26 °. Hence, if you decrease the Celestia field-of-view to 26° you may get a more accurate appearence of what you would see looking out the window.

      Celestia's galaxies are ugly, dim, grey blobs. How can I get colorful galaxies that look like the real things?

      The real things are dim, grey blobs. Your eyes are not sensitive to color at the very low light levels emitted by distant galaxies.

      Many of the colorful pictures you're used to seeing are enhanced by long exposures on sensitive color film. Others are imaginative "false color" combinations of narrow-band CCD images designed to make visible the specific features of interest to the investigators. The colors of those pictures aren't realistic at all.

      You can add a colorful object to Celestia by creating a 3DS model with appropriate images as surface textures. Define it as a Nebula in a DSC file. Use the Search command in the Celestia "Development" and "Add-On" forums to find examples.

      Why are there no stars beyond about 16,000 light years? Why are there no stars in distant galaxies?

      Hipparcos could only measure parallax to a value of about 1 milli-arc-second. For details, please read the thread [1] Celestia currently has technical limitations which prevent it from drawing stars beyond a distance of about 13 million LY from the sun.

      On the second page of the thread mentioned above [2], Chris wrote about some of the tradeoffs in the current version of Celestia.

      Sometimes the planets and moons are way far away from where their orbits are drawn. Why?

      To draw the orbits, Celestia only calculates 100 or so precise locations and then draws straight lines between them. If the orbiting body doesn't happen to be close to one of those 100 points, then it won't be very close to the line, either. The position of the orbiting body is calculated very accurately. The lines aren't.

      Celestia only calculates a few points around the orbit in order to minimize the amount of computation needed between frames. The more calculations are required, the slower the frame rate is. You can specify the number of segments in an orbit track. Use your favorite text editor to modify the file celestia.cfg. Change the line

      OrbitPathSamplePoints  100
      

      Increase 100 to 500 or larger.

      Why does the illumination level in Celestia not fall off the farther from the Sun I go - surely it should be very dark by the time I get to Pluto?

      The human eye can adapt to a very wide range of illuminations, so it wouldn't be as dark out there as you think - about the level of moderate indoor lighting, in which you can see very well. At the other end of the scale, your computer monitor is physically incapable of generating the brightness of illumination that pertains on the inner planets. Fortunately it doesn't need to, since all that would happen would be that your pupils would constrict to reduce the incoming light to a more comfortable level.

      So in summary -

      1. There's no way Celestia can display "realistic" brightnesses on your computer screen; but
      2. such "realism" is unnecessary because your eyes merely adapt to compensate.

      (Provided by Grant Hutchison)

      When I try to capture a picture or movie, the image is stretched out of proportion.

      (Thanks to DaveMc for these tips!) Here are three things you can try...

      1. Check the OpenGL anti-aliasing setting of your graphics card. If it is on, try turning it off, or setting it to another option. This seems unrelated to the anti-aliasing setting inside of Celestia.
      2. Set your graphics card OpenGL options to "default".
      3. Get the most recent drivers for your graphics card.

      (Provided by Don G.)

      How can I make Celestia work like a planetarium? I want to see how the sky should look from my backyard.

      If you're running Celestia v1.3.0 or later

      1. Select the body from which to observe; e.g. type H then 3 to select Earth,
      2. Use the GoTo menu to specify your Longitude and Latitude and GoTo there (lat & long are entered in decimal format - there are websites that convert to/from degrees/minute/seconds format, such as this one,)
      3. Type y = Sync Orbit (this locks you into position above the location you set),
      4. Type (Windows:Ctrl-G) (Linux:Alt-S) = Goto Surface,
      5. Type (Windows:Ctrl-F) (Linux:Alt-F) = change Arrow keys to AltAzimuth mode (this keeps the horizon level when panning left & right),
      6. Use the arrow keys to look toward the sky, you can adjust the field of view (FOV - how much sky you see at once) with the , & . keys.

      Celestia provides a Horizontal (alt-az) coordinate system display which can be selected in its Render menu. Also, typing a ; will turn on the equatorial coordinate system display. There are some scripts which add alt-az display, such as Planetarium.

      Why can't I see Mir or Galileo? I know they're defined in Celestia.

      Set Celestia's simulation time to be when the spacecraft was in orbit. Celestia does not display spacecraft if they are not in orbit at the time of the simulation.

      For example, Mir was launched on February 20, 1986, and reentered the Earth's atmosphere on March 23, 2001, at 05:55 GMT. Celestia will show Mir only if you set the time to be somewhere between those two dates.

      This is controlled by Beginning and Ending directives in the definition of Mir in solarsys.ssc. If you remove those statements, Celestia will always draw Mir in orbit.

      Addendum provided Tech Sgt. Chen:

      Mir, along with certain other spacecraft models, were modeled within an historical time frame and can only be viewed between the mission start and end dates. You can override ending dates by opening the solarsys.ssc or other specific craft related .SSC files and placing a pound sign (#) in front of the ending date string. Then save the new setting. This way you can always view your installed Space Crafts. Consequently, removing the pound sign will return the craft to its natural time frame.

      Positions on Mars are on the opposite side of the planet or bumps seem to be half a world away from the mountains or it's dark where it should be daylight. Why????

      You have a misaligned map.

      Celestia requires that all maps have 0 degrees of longitude in the center, with 180 degrees of longitude at the edges. All of the surface texture image maps of all of the moons and planets that come with Celestia have this alignment.

      In contrast, many maps of Mars have been created with 0 degrees of longitude at the left and right edges, and with 180 degrees of longitude in the center.

      Using a map with 0 at the edge would cause the symptoms you describe. You need to cut the map in half and exchange the halves or you need to find a map that's properly aligned.

      My planet's rings are drawn as a featureless oval. It used to work. What's wrong?

      You need to use a smaller ring image, one that is no wider than your graphic card's OpenGL texture buffer.

      To see how large your OpenGL texture buffer is, use Celestia's menu Help "OpenGL Info". Near the beginning it has a line that starts with "Max texture size:"

      Older versions of Celestia scaled down large ring texture images so they'd fit into the smaller texture buffer of your OpenGL graphics driver. Celestia v1.3.1 and later no longer do that.

      Some older cards, like 3dfx Voodoos, only have a 256 byte buffer. Modern cards have a 2K or 4K buffer. Microsoft's software version of OpenGL only has a 1K buffer.

      Celestia's orbit for the ISS is out of date. How can I get a better one?

      The orbit of the International Space Station changes continuously in ways that are almost impossible to predict due to things like atmospheric drag, light pressure, cargo ship docking, etc. If you want an accurate orbit, you'll have to update it on a daily basis.

      ISS TLEs (Two Line Elements) are posted to the AMSAT SAREX mailing list regularly by "Dave Larsen PhD". [3]

      Current values are also available at http://heavens-above.com/orbit.aspx?satid=25544

      Here are the ISS TLE orbital parameters for August 16th, 2004:

         ISS
         1 25544U 98067A   04229.23839543  .00019757  00000-0  15906-3 0  4532
         2 25544  51.6323  19.1941 0005251 117.9988 304.8582 15.70921896327755
      

      and here are the corresponding values for September 30, 2017:

         1 25544U 98067A   17273.74686146  .00016717  00000-0  10270-3 0  9043
         2 25544  51.6413 232.1027 0004759 326.7128  33.3724 15.54058911 38162
      

         Epoch (UTC): 	30 September 2017 17:55:28
         Eccentricity: 	0.0004759
         inclination: 	51.6413°
         perigee height: 	401 km
         apogee height: 	408 km
         right ascension of ascending node: 	232.1027°
         argument of perigee: 	326.7128°
         revolutions per day: 	15.54058911
         mean anomaly at epoch: 	33.3724°
         orbit number at epoch: 	38162
      

      Grant Hutchison has provided a spreadsheet to convert TLEs into Celestia SSCs [4]

      Also, don't forget that Celestia models the shape of the Earth using a spheroid. The actual shape of our planet is much more complicated. As a result, a view from the Earth's surface in Celestia is not accurate enough to show the correct path across the sky of satellites in low Earth orbit like the ISS. Another issue is that Celestia v1.5.1 and earlier use a fixed rotation speed for the Earth. Since the Earth's rotation is variable, the surface of Celestia's Earth is displaced from where it should be. Celestia v1.6.1 uses a more accurate variable rotation speed. In other words, you can't use Celestia to find out where to look in the sky to see the ISS.

      I have a previous version of Celestia with tons of addons, custom textures, etc. How can I update to the latest version without having to reinstall all of those addons, textures, etc?

      You can have more than one copy of Celestia on your system at the same time.

      Rename the directory (folder) where you have Celestia now, maybe to Celestia131.

      Verify that things still work: Double-click on the icon for Celestia131\Celestia.exe and look around in your universe.

      Install the new copy of Celestia and tell it to use the directory Celestia. It'll create the folder again and install itself there.

      Move your Addons at leisure.

      Cel:// URLs run the copy of Celestia that is in the folder named Celestia. If you want to change back to using your old Celestia that way, just rename the directories again: rename Celestia to be Celestia132 and rename Celestia131 to be Celestia.

      A description of how to organize your Addons so they can be moved easily. [5]

      I've compared the Celestia texture for Venus/Ida/Miranda with one I've found in a book or on the Web, and Celestia's map is upside down. What's going on?

      Many sources for planetary maps (such as the USGS) use a mapping convention called "ecliptic north" - the north pole of any planet or asteroid is defined as being whichever rotational pole points north of the plane of the ecliptic (the plane of the Earth's orbit around the Sun). Each planet or asteroid can then be classified as a "direct" rotator, if it rotates in the same direction as the Earth when observed from above its north pole (i.e. counterclockwise); or as a "retrograde" rotator, if it rotates in the opposite direction.

      But Celestia uses an equally valid mapping convention called "rotational north" - north is defined as being the pole around which the planet appears to rotate counterclockwise, irrespective of that pole's orientation relative to the ecliptic.

      For direct rotators, this difference is irrelevant - "north" turns out to be the same direction in both mapping conventions. But for retrograde rotators, Celestia's north pole corresponds to ecliptic south - so you will find many maps of retrograde rotators like Venus, Ida and the moons of Uranus that appear to be upside down relative to those in Celestia. If you want to convert such maps for use in Celestia, you'll have to turn them through 180 degrees.

      (Provided by Grant Hutchison)

      What if I have more questions?

      If you have a question about Celestia that is not answered above or elsewhere in this WikiBook, please ask your question in the Celestia Web Forum, not here. There are many experts reading the Forum, but very few knowledgeable people read the WikiBook. If a question is asked more than once or twice in the Forum, it'll be added to this FAQ.

      Introduction

      This is a glossary of Celestia terminology. Many of the terms used with Celestia are very similar to the corresponding astronomical terminology. For a glossary of astronomical terms, see the Astronomical Terms: Appendix to the Wiktionary

      Glossary

      Barycenter

      A (possibly moving) invisible position in space defined in an STC catalog file, around which other STC and SSC objects can orbit.

      catalog

      A text file used to define objects and their positions. Different catalogs are used to define a Star (STC), a planetary system which orbits around a Star (SSC) and objects not associated with a Star (DSC).

      CMOD

      Celestia MODel file: a proprietary format used to define a 3D object.

      DSC

      Deep Space Catalog; used to define glowing Nebulae or Galaxies or invisible OpenCluster objects around which nothing can orbit. Celestia v1.6 adds Globular Clusters.

      EllipticalOrbit

      One of several different types of periodic trajectories, defined using traditional Keplerian parameters. Used in STC and SSC catalog files.

      Galaxy

      A glowing object defined in a DSC catalog file using a PNG template and astronomical coordinates.

      GlobularCluster

      A spherical group of dots defined in a DSC catalog file using parameters which determine how tightly grouped the dots are.

      Hipparcos

      An astrometric satellite and the database created from its observations; used to define the positions of more than 100,000 stars in Celestia.

      Horizons

      JPL's on-line solar system data and ephemeris computation service. Often used to generate orbit and trajectory data files.

      Julian Date

      Julian dates are a continuous count of days and fractions since noon Universal Time on January 1, 4713 BCE (on the Julian calendar). Almost 2.5 million days have transpired since this date. Julian dates are used in Celestia's SSC and STC catalogs for the fields Epoch, Beginning and Ending. These fields use 64-bit floating point (double precision) variables, and can represent a Julian date to about 1 millisecond of precision. The time scale that is the basis for Julian dates is Universal Time. Starting with v1.5, Celestia uses TDB internally and UT for its on-screen display. 0h UT corresponds to a Julian date fraction of 0.5: Julian days go from Noon to Noon instead of from Midnight to Midnight. This is so that the date doesn't change in the middle of nocturnal observations.

      Location

      A Celestia object: defines a label for a position on a body.

      map

      1. An image file providing information about the visual characteristics of an object.
      2. A mathematical transform between the geometry of a spheroidal object and a flat surface. The mapping known as "simple cylindrical projection" or "Plate Carré" is used by Celestia to map between flat images (surface texture files) and spherical planets and moons.

      Mesh

      1. A 3D model used to display an object with an arbitrary shape.
      2. A list of connected vertices specified in a CMOD 3D model file.

      NAIF

      NASA's Navigation and Ancillary Information Facility. A source for SPICE trajectory files.

      Nebula

      A glowing or invisible object defined in a DSC catalog file by specifying a Mesh and astronomical coordinates.

      normal

      1. A vector perpendicular to the surface at a position. I.e. a surface normal vector. Used to indicate irregularities and provide dynamic shading on surfaces.
      2. conventional or standard surface texture; not an AltSurface.

      object

      A body which has its appearance and position defined in a catalog.

      OpenCluster

      A labeled, fixed position defined in a DSC catalog file. It is not necessarily associated with any particular glowing object.

      path

      1. A line drawn on the screen to indicate the orbit or trajectory of an object.
      2. The hierarchical list of objects around which the object currently being defined is orbiting.

      position

      A place in a coordinate system. Not to be confused with a Location.

      ReferencePoint

      A (usually moving) invisible position in space defined in an SSC catalog file, around which other SSC objects can orbit. A ReferencePoint has only positional characteristics. It cannot be used to provide any orientation information.

      SPICE

      Spacecraft, Planet, Instrument, C-matrix and Events kernels; not to be confused with Simulation Program with Integrated Circuit Emphasis. A type of NASA trajectory information file. Use of SPICE kernels was introduced in Celestia v1.5.0.

      SpiceOrbit

      A trajectory defined using NAIF SPICE kernels.

      SSC

      Solar System Catalog; used to define non-glowing objects which orbit around Stars, Barycenters and each other.

      Star

      A glowing object defined in an STC catalog file, around which STC and SSC objects can orbit.

      STC

      STar Catalog; used to define glowing Stars or invisible Barycenter objects around which other objects can orbit.

      trajectory

      The positions traversed by a moving object.

      Universal Coordinate System

      The default coordinate system used by Celestia is Ecliptic J2000:

      The fundamental plane is the J2000 Earth ecliptic, and the preferred direction (x-axis) is the J2000 equinox.

      Enhancing Celestia

      The following reference pages will help you to add features and make Celestia easier to use in your environment.

      Scripting

      Introduction

      Typing commands on the keyboard can be tiring and error prone. If you are using Celestia to show the universe to others, a script may be an effective way to tour the stars.

      Types of Scripting

      Celestia supports two different Scripting languages, CEL and CELX (Lua). These can be used to add new functionality to the program, or to run educational activities.

      CEL scripting

      See the page Celestia/Cel_Scripting

      CELX scripting

      See the page Celestia/Celx_Scripting

      Other Languages

      You can use any other language you want if it can pass commands to the operating system's command interpreter. It can issue the command to run Celestia and can include on that command line the instruction to run a .CEL Celestia script or .CELX Lua script.

      When invoked from a command line, Celestia can be passed the name of a .CEL or .CELX script to run at startup:

      ./celestia --url name-of-script.cel
      

      When the command line includes the qualifier "--once", the command line will be passed to the running copy of Celestia instead of starting a new copy of the program. (note: use two hyphens)

      ./celestia --once --url name-of-script.celx
      

      (Starting with Celestia v1.3.1, scripts may be in any folder. Previously they had to be in Celestia's "root" folder.)

      External Links

      Visit the Celestia Scripting Forum

      Read and contribute to the Celestia Scripting Guide

      Many resources for both CEL and CELX scripting can be found at Don G's Celestia Scripting Resources page.

      CEL scripting

      CEL scripts are short text-based programs that Celestia can read. They contain simple commands that take control of Celestia (once it is launched) and enable a script writer to design a specific journey or set of scenes that a user of the script will see and experience. For example, a script may take the user on a short tour of the solar system, pausing briefly at all of the planets. In that way, a CEL script is used to change the position of Celestia's viewpoint.

      CEL scripting is basically a sequence of commands similar to key-presses, which are executed in specific timing and at a particular speed to give viewers a visual experience that the script writer wants to display. There is however no interactivity with the user during the execution of a CEL script.

      
      Scripts can take users to very specific locations in the Celestia universe. For example, a script can be written to take them into orbit around Venus, or take them outside the Milky Way to view it from intergalactic space. What happens when they get there is controlled by the script as well. There may be a 30 second pause, followed by a movement to another location. There may also be text displayed, to teach the user some information about a particular place.

      Scripts also have the ability to change specific Celestia (render) settings. For example the rendering of orbits can be turned on/off or planets can be given a marker or alternative surface texture. Note however, when a CEL script ends or is terminated by the user, there is NO ability to reset those settings to the values they were before running the script. It is advised for the user to have their own reset.cel script, so specific Celestia (render) settings can be easily restored after running other CEL scripts.

      
      A script can be launched from the Celestia/File/Open script... or Celestia/File/scripts drop down menu and it will run until it is complete. Meanwhile it can be paused by the user by pressing the [Spacebar] key or it can be stopped at any time by pressing the [Esc] key.
      When the file extension ".cel" of a script is also correctly associated with the Celestia program, it is also possible to launch the script externally, e.g. from a hyperlink or by double clicking.

      
      Scripts offer a Celestia user several key advantages:

      1. A Celestia script writer can give inexperienced users a beautiful visual tour of a particular Celestia environment.
      2. Important celestial events can be displayed for a user, controlled by script. For example, a script can take a user to 1957 to see Sputnik 1 orbiting Earth on its maiden flight. The script can put the viewer into a position just 10 meters from Sputnik, and pace it as it flies over the Soviet Union, then display a paragraph of text explaining the significance of Sputnik.
      3. If no script were available, it might take a user many minutes to set up Celestia to go to the same spot at the same time. Also, no text would be displayed.
      4. In the special Celestia-ED version of the Celestia program, CEL scripts have been given the ability to also command sound and music files to play. As such, scripts can be designed which choreograph complex movements of planets or spacecraft, while moving to music.

      
      

      Writing Celestia Script Commands

      Anyone can write a CEL script. Some knowledge of how to do so is required and is summarized below, but you do not have to be a very experienced Celestia user to write a CEL script.

      The very first character in a CEL script must be an opening curly brace "{". The very last character in a script must be a closing curly brace "}".

      Therefore, an empty, but valid Celestia CEL script file looks like the following:

      { }
      

      Every script you create for Celestia will have at least one command line in it, which is a line of text instructing Celestia to set or do something.

      A typical single Celestia script command line consists of the following pieces:

      • A command name, such as wait
      • A space (spacebar)
      • An opening curly brace "{"
      • Zero or more argument names, along with the value you want the argument set to.
      • A closing curly brace "}"

      The "#" character can be used as the first character in a script line to make that line a comment line, which the script engine will ignore (not execute).

      
      Examples:

      Assign a <number> value of 5.5, to the argument duration, in the command wait, which tells Celestia to pause for the number of seconds you enter.

      Note: there are no double quote marks (") around the <number> value (5.5) because double quote marks are used only to specify a <string> value.

      wait { duration 5.5 }
      

      Assign a <string> value of "Mars", to the argument object, in the select command:

      Note: Here, double quote marks tell Celestia that a <string>, or text value (Mars), is being sent to it. When sending a <string> to Celestia, the value must be enclosed in double quote marks.

      select { object "Mars" }
      

      Example of a comment line.

      # This is a comment line
      

      Some Celestia CEL script commands, such as print, send more than one argument. In these cases, you enclose all arguments and their associated values between the command's opening and closing curly braces, such as:

      Note: All arguments for each command must be enclosed within the command's curly braces, such as the example above shows. You may include as much white space (spaces, blank lines, etc.) as you deem necessary, and you may even specify each argument and its associated value on a different line – all for clarity.

      print { text "Hello universe."  row -4  column 1  duration 5 }
      

      -- OR --

      print { text "Hello universe."
              row -4
              column 1
              duration 5 }
      

      When you save a Celestia CEL script file to disk, the file extension must be ".cel", which allows your operating system to recognize the file as belonging to Celestia, and allows Celestia to know this file is one of its CEL scripts. Also, you must save the file as plain text. Rich Text Format files do not function in Celestia because they also contain embedded formatting information.

      Index of available CEL commands

      An index of the available CEL commands can be found at the CEL command index section of the CEL to CELX migration chapter.

      By clicking on a specific command, you will be routed to the explanation of its functionality. The index also contains an explanation on how that CEL command can be migrated to equivalent CELX objects and methods. Before starting with CELX scripting however, you may need to have some programming experience with CEL scripting first.

      CEL scripting versus CELX scripting

      A main advantage of CEL scripting is that it's MUCH easier to use than CELX scripting. The syntax is easy due to the simple structure of the commands, and most of the time it's very easy to translate keyboard commands directly into their CEL counterparts.

      The primary disadvantage in using CEL-scripting versus CELX-scripting is its limited flexibility, its inability to respond to keyboard commands, the absence of a possibility to reset changed user settings to the values they were before running the CEL script and a lack of support for many of the new Celestia features that appeared in Celestia version 1.6.0 and newer Celestia versions/releases.

      
      The main differences between CEL scripting and CELX scripting are summarized below:

      • The extension of CEL and CELX scripts differ from each other:
        • CEL script: .CEL
        • CELX script: .CELX
      • More words and more commands make CELX scripts look more complex than CEL scripts, but it also gives your scripts more possibilities, including the usage of Lua logic (like building loops, make decisions on what to do, calculations, etc.), and interactive keyboard input.
        The CEL to CELX migration section will help you with the more complex CELX equivalents of the CEL commands, so you can use these equivalents in your own script. Besides the equivalents, there are also examples included. You can copy the equivalents into your own script and modify them according your own wishes. After a while you’ll become more familiar with CELX scripting and copying or typing a sequence of CELX methods and objects will become easier each time.
      • Keyboard interaction is possible in CELX, but not in CEL scripting. Within CELX you can use the callback for keyboard input, which must have the name celestia_keyboard_callback. After a script activates the handling keyboard-input by calling celestia:requestkeyboard(true), any keypress will result in a call to a method with this name.
      • Angles in CELX are defined in radians instead of degrees in CEL.
        180 degrees (half a circle) is the same as π radians = 3.14159265 radians.
        You can use the Lua math.rad() and math.deg() functions to convert degrees to radians and [i]vice versa[/i]:
        • radians = math.rad( <number:degrees> )
        • or you can convert yourself: radians = ( <number:degrees> / 180 * 3.14159265)
        • or use Lua math.pi: radians = ( <number:degrees> / 180 * math.pi)
        • degrees = math.deg( <number:radians> )
        • or you can convert yourself: degrees = ( <number:radians> * 180 / 3.14159265)
        • or use Lua math.pi: degrees = ( <number:radians> * 180 / math.pi)
      • The units of the components of a position object in CELX are millionths of a light-year. When you have position components defined in km (CEL scripting) or miles, you first have to convert those components to millionths of a light year.
        Therefore, you can use a constant, which must be initialized first within your CELX script:
        • From km to millionths of a light year, use constant: uly_to_km = 9460730.4725808.
        • From miles to millionths of a light year, use constant: uly_to_mls = 5912956.5453630.
      • Next you can convert km or miles to millionths of a light year as follows:
        • millionths_of_a_light_year = <number:km> / uly_to_km
        • millionths_of_a_light_year = <number:miles> / uly_to_mls
      • Be aware that some default parameter values have changed in CELX compared with the equivalent defaults in CEL scripting.
      • Time in CELX is defined in TDB (Barycentric Dynamical Time) instead of UTC or Juliandate, because UTC includes "leap seconds" in order to stay aligned with the Earth's varying rotation. Leap seconds happen essentially randomly, when they are needed. Although Celestia does incorporate a table of leap second times, the use of UTC in versions of Celestia before v1.5.0 caused problems when used with ephemerides which are defined using TDB.
        Starting with version 1.5.0, although it still displays UTC on the screen, Celestia uses the TDB time scale internally for everything else. As a result, Celestia places objects much more accurately than before.
        • To convert from Juliandate and/or UTC to TDB is explained in the section: CEL: time.
      • Transparency of markers can be true or false in CELX (starting from Celestia version 1.6.0). In CEL scripting there’s no possibility to enable or disable the transparency of markers. The Celestia releases 1.5.0/1.5.1 and older always displayed the markers, but from Celestia version 1.6.0 (or Celestia-ED version 1.5.1), the default marker transparency is true, resulting in disappearing markers in case of Occultations, or partially show markers on the surface of celestial objects. To overcome this, the usage of the false parameter in the CELX: object:mark() method is necessary, which also makes CELX scripting necessary, instead of CEL scripting!
      • Sometimes, timing can be more sensitive in CELX scripting than it is in CEL scripting, especially when lots of Lua commands and Celestia (related) methods are used within a short period of time with a high timerate value ([i]i.e.[/i] when time has been speeded up). Solving those timing issues on your own computer may not always give the same result on other computers with different CPU speeds. In those cases, the usage of a CEL equivalent part within your CELX script may give a more consistent result.
      • It is possible to insert CEL script parts within a CELX script by defining the following function at the beginning of your CELX script:

      function CEL(source) 
         local script = celestia:createcelscript(source) 
         while script:tick() do 
            wait(0) 
         end 
      end
      
      -- Within the subsequent part of your CELX script you can now use CEL script commands as follows:
      CEL([[{ <one or more lines with CEL script commands> }]])
      

      • CEL and CELX Scripts can be temporarily paused, by pressing the [Spacebar] key. Pressing the [Spacebar] key again will result in the continuation of the script.
        Note: When using CEL script parts and functions within a CELX script, this pause function will not work completely correctly. Although the scene you’re looking at will pause directly, the CEL script parts and functions will continue to run in the background, resulting in a part of the script being visually skipped when you press the [Spacebar] key again to continue the script.

      External Links

      A slightly out-of-date summary of .CEL commands.

      A list of more of the .CEL scripting commands, somewhat cryptically organized.

      An example .CEL script

      Some helpful .CEL and .CELX scripts for Celestia are available on Don G's Celestia Scripting Resources

      CELX Scripting

      CELX scripts can be used to interact with the user, change Celestia's viewpoint and what it shows, and do sophisticated calculations.

      CELX first appeared in Celestia v1.3.1. CELX consists of the Lua-programming language combined with a Celestia-specific API. That is, CELX uses Lua syntax and most of the basic Lua-libraries, and adds Celestia-specific functionality.

      CELX's biggest advantage over CEL scripting is that it is a real programming language, including control structures like functions and loops, and offers a lot more possibilities, such as interactivity. However this power also makes CELX harder to learn and use, and provides the main disadvantage over CEL scripting.

      • Introduction to CELX Scripting
      • CELX Lua Methods: a list of CELX Methods (functions).
      • CELX Questions and Answers
      • CELX Development Suggestions

      External Links

      A few example Lua scripts for Celestia are available on SourceForge.

      A comprehensive list of Celestia's Lua functions is available on Harald Schmidt's Web site.

      Some helpful .CEL and .CELX scripts for Celestia are available on Don G's Celestia Scripting Resources Celestia/Celestia/Celx Scripting/Simple CELX Scripting Celestia/Celestia/Celx Scripting/CELX Lua Methods Celestia/Celestia/Celx Scripting/Q&A Finding the angles between two objects is a handy thing to be able to do in a script. It would mostly be useful for finding angular separations and phase angles (illustrated below) which can be used for a variety of other purposes.

      

      The angular separation between two objects seen is a measure of how far apart they are in the sky as seen by the observer.

      The phase angle is usually described for non-emissive objects orbiting stars (e.g. planets, asteroids, comets, moons, etc.) and is the angle of illumination of the object seen by an observer. It is the angle between the Star-Target line and the Target-Observer line. Using the image as an example, a phase angle of 0 degrees means that the observer is directly between the star and the planet - thus, the star is behind the observer, and the planet would appear "Full" to the viewer. A phase angle of 90 or 270 degrees means that the observer is over the terminator of the planet (the line dividing day and night), so he would see a 'Half-Full" planet. A phase angle of 180 degrees means that the planet is directly between the observer and the star, so the observer is in the planet's shadow and would see a "New" planet. At intermediate phase angles the observer would see a crescent or gibbous planet.

      Theory

      Celestia stores the positions of objects as a table consisting of an x-coordinate, y-coordinate, and z-coordinate. The line connecting two points is known as a vector, so basically we're finding the angle between two vectors. First we have to calculate each of the vectors. To do this we find the positions of the objects at either end of the line, and then simply subtract one from the other. So in order to calculate a Phase Angle, the vector of the Star-Planet line is (position of the planet - position of the star), and the vector of the Observer-Planet line is (position of the planet - position of the observer).

      Once we have these vectors, we need to use a special mathematical function used for vectors called the Dot Product. This is reproduced below:

      $\mathbf {a} \cdot \mathbf {b} =a\,b\cos \theta \;$

      
      We'd refer to this as "a dot b", where a and b are the vectors involved. The ab on the right-hand-side of the equation are the lengths of the two vectors multiplied together, and the angle theta is the angle between the two vectors. In this case, Celestia already knows what the vectors are (and how long they are and what the angle is between them) and so can calculate the dot product - we just need to extract the information we want in a script. We can also normalise the vectors so that the lengths equal 1 - this makes the calculation a little simpler (and conveniently enough there's a 'normalize' script command that does this). This reduces the equation we need in the script to:

      $\theta =\arccos(\mathbf {a} \cdot \mathbf {b} )\;$

      The script below illustrates how to perform this calculation in Celx.

      Download the script

      This is a complete script that you can run as-is to display the phase angle to a target in the solar system. The target must already be selected before the script is run.

      camera = celestia:getobserver()			-- set camera object
      target = celestia:getselection()	 		-- set target object
      sunpos = celestia:find("Sol"):getposition()		-- find sun position
      campos = camera:getposition()				-- find camera position
      planpos = target:getposition()				-- find target position
      sun_target_vector = planpos - sunpos			-- determine sun-target vector
      obs_target_vector = planpos - campos			-- determine observer-target vector
      phase_angle = math.acos(sun_target_vector:normalize() * obs_target_vector:normalize())	-- find phase angle (in radians) 
      celestia:flash("Phase angle to target is "..string.format("%.2f", math.deg(phase_angle)).." degrees\n")
      wait(2)
      

      Celestia/Celestia/Celx Scripting/Q&A/Assigning Custom Key Functions with CELX Celestia/Celestia/Celx Scripting/Development Suggestions

      Customizing Celestia

      Introduction

      Many of Celestia's display characteristics and the databases that it uses can be controlled by modifying its configuration file, celestia.cfg.

      More extensive changes and additions to Celestia can be provided using Addons and Celx Scripting.

      Celestia Configuration File

      The following information is from the comments in the Celestia Configuration File, celestia.cfg.

      This file contains configuration data read by Celestia each time it is run. Many of the items may be changed to suit your specific needs or requirements. It is HIGHLY recommended that you make a backup copy of this file before you make any changes to it.

      To learn more about Celestia, visit the Celestia forums at: https://celestiaproject.space/forum/ or the Celestia web site at: https://celestiaproject.space

      Data Files

      This section contains a list of data files that Celestia uses to load information about stars, constellations and locations. Do not change these file names or the order in which they are listed, unless you know exactly what you are doing. Most of these files can be viewed with a plain text editor. Discussion about their content and formats can be found on the Celestia forums: https://celestiaproject.space/forum/ If you want to load all your stars from .stc files, you can now comment out the StarDatabase entry.

       StarDatabase                 "data/stars.dat"
       StarNameDatabase             "data/starnames.dat"
       StarCatalogs               [ "data/revised.stc"
                                    "data/extrasolar.stc"
                                    "data/nearstars.stc" 
                                    "data/visualbins.stc"
                                    "data/spectbins.stc" ]
      
       HDCrossIndex                 "data/hdxindex.dat"
       SAOCrossIndex                "data/saoxindex.dat"
       GlieseCrossIndex             "data/gliesexindex.dat"
      
       SolarSystemCatalogs        [ "data/solarsys.ssc"
                                    "data/asteroids.ssc"
                                    "data/comets.ssc"
                                    "data/outersys.ssc"
                                    "data/spacecraft.ssc"
                                    "data/extrasolar.ssc"
                                    "data/solsys_locs.ssc"
                                    "data/world-capitals.ssc" ]
       DeepSkyCatalog               "data/deepsky.dsc"
       AsterismsFile                "data/asterisms.dat"
       BoundariesFile               "data/boundaries.dat"
      

      User Interface files

      Despite their ".cel" file extension, these are not CEL scripts, but rather data files that populate controls such as menus and dialog boxes.

      • FavoritesFile - This is where Bookmarks data are stored. The file does not exist until you save a Bookmark from within Celestia. You can view this file with a plain text editor and if you write CEL scripts, it contains some useful information.
      • DestinationFile - This is the list of Destinations used in the Tour Guide dialog box, accessed via the Navigation Menu. You can edit this file with a plain text editor to add your own destinations to the dialog box. The order in which the items are listed in the file is the order in which they will be listed in the Tour Guide dialog.

      Cursor

      This parameter allows you to select from three cursors, but currently only in the Windows version of Celestia ...

      • White crosshair ("crosshair") > default cursor
      • Inverting crosshair ("inverting crosshair")
      • Standard Windows arrow ("arrow")

      The inverting crosshair can be a better choice because it's more visible on bright backgrounds. However, should you decide to try this cursor, test it closely. Not all graphics chipsets support an inverting cursor, which will cause Windows to fall back to software emulation. The emulated cursor interacts with OpenGL applications in unfortunate ways, forcing a lot of extra redrawing and cutting by half the frame rate on a GeForce2-equipped laptop. So, if you change this, check your FPS rates to make sure you haven't kicked Windows into software emulation mode.

       FavoritesFile    "favorites.cel"
       DestinationFile  "guide.cel"
       Cursor           "crosshair"
      

      Included CEL script files

      The following CEL script files are included in the basic Celestia distribution. These script files may be viewed and edited with a plain text editor. They may both be modified or replaced to suit your specific needs. InitScript is the CEL script that is automatically run each time Celestia is started. The default script (start.cel) travels to Io, one of Jupiter's moons. DemoScript is the CEL script that is run when you press the "d" key on your keyboard from within Celestia. The default script (demo.cel) takes you on a short tour of some interesting places in our solar system. To learn more about how to use and write CEL scripts and Lua scripts in Celestia, please visit the Celestia Scripting forum at: https://celestiaproject.space/forum/viewforum.php?f=9

       InitScript  "start.cel"
       DemoScript  "demo.cel"
      

      Extras

      The 'extras' directory is located under the celestia root directory and is used for storing third-party add-ons to Celestia. To learn more about Add-Ons for Celestia, visit the Celestia Add-Ons forum at: https://celestiaproject.space/forum/viewforum.php?f=6 You may specify additional add-on directories by adding additional entries, such as the following example shows: ExtrasDirectories [ "extras" "myextras1" "myextras2" ] To specify absolute paths on windows, you either have to use "/" or double backslashes to separate path components. Example: ExtrasDirectories [ "D:/celestia-extras" ] or ExtrasDirectories [ "D:\\celestia-extras" ]

       ExtrasDirectories  [ "extras" ]
      

      Font definitions

      The following entries define the fonts Celestia will use to display text on the display screen. To view the list of fonts available with your distribution of Celestia, look in the fonts directory located under the Celestia root directory. The default fonts are UTF-8 compatible in order to display non-English characters.

      • Font: Used to display all informational text. Default: "sans12.txf"
      • LabelFont: Used to display all label text (objects, locations, etc.). Default "sans12.txf"
      • TitleFont: Used to display object names, messages, and script text. Default "sansbold20.txf"

       Font       "sans12.txf"
       LabelFont  "sans12.txf"
       TitleFont  "sansbold20.txf"
      

      Miscellaneous

      LogoTexture defines the graphic file to be displayed when Celestia is started. The default filename is "logo.png"

       LogoTexture  "logo.png"
      

      FaintestVisibleMagnitude defines the lowest magnitude at which a star will be displayed in Celestia. This setting may be adjusted real-time via the '[' and ']' keys in Celestia. The default value is 6.0.

       FaintestVisibleMagnitude 6.0
      

      RotateAcceleration defines the speed at which an object will be rotated in Celestia, when using a keypress, such as the left and right arrow keys. A higher value will rotate the object quicker, while a lower value will cause a slower rotation. The default value is 120.0.

       RotateAcceleration 120.0
      

      MouseRotationSensitivity defines the speed at which an object will be rotated in Celestia, when using the mouse press both mouse-buttons or Ctrl+LeftMouseButton, and move the mouse left or right. A higher value will rotate the object quicker, while a lower value will cause a slower rotation. A value of 0.0 (zero) will disable this particular feature. The default value is 1.0.

       MouseRotationSensitivity 1.0
      

      Scripting

      The following parameter is used in Lua (.celx) scripting. ScriptScreenshotDirectory defines the directory where screenshots are to be stored. The default value is "", i.e. Celestia's installation directory.

       ScriptScreenshotDirectory ""
      

      CELX-scripts can request permission to perform dangerous operations, such as reading, writing and deleting files or executing external programs. If granted, a malicious script could use this to destroy data or compromise system security. The following parameter determines what Celestia does upon such requests: "ask": ask the user if he wants to allow access (default) "allow": always allow such requests "deny": always deny such requests.

       ScriptSystemAccessPolicy "ask"
      

      Rendering Resources

      The following lines are render detail settings. Assigning higher values will produce better quality images, but may cause some older systems to run slower. OrbitPathSamplePoints defines how many sample points to use when rendering orbit paths. The default value is 100. RingSystemSections defines the number of sections used to draw rings around a planet. The default value is 100. ShadowTextureSize defines the size* of shadow texture to be used. The default value is 256. Maximum useful value is 2048. EclipseTextureSize defines the size* of the eclipse texture to be used. The default value is 128. Maximum useful value is 1024. The ShadowTextureSize and EclipseTextureSize values should both be powers of two (128, 256, 512, etc.). Using larger values will reduce the jagged edges of eclipse shadows and shadows on planet rings, but it will decrease the amount of memory available for planet textures. The shadow and eclipse texture settings are not used with the OpenGL 2.0 render path, which uses a different technique to render shadows.

       OrbitPathSamplePoints  100
       RingSystemSections     100
      
       ShadowTextureSize      256
       EclipseTextureSize     128
      

      Set the level of multisample antialiasing. Not all 3D graphics hardware supports antialiasing, though most newer graphics chipsets do. Larger values will result in smoother edges with a cost in rendering speed. 4 is a sensible setting for recent, higher-end graphics hardware; 2 is probably better mid-range graphics. The default value is 1, which disables antialiasing.

       AntialiasingSamples        4
      

      The following line is commented out by default. Celestia enables and disables certain rendering features based on the set of extensions supported by the installed OpenGL driver and 3D graphics hardware. With IgnoreGLExtensions, you may specify a list of extensions that Celestia will treat as unsupported. This is useful primarily for the developers of Celestia.

        IgnoreGLExtensions [ "GL_ARB_vertex_program" ]
      

      LogSize

      The number of rows in Celestia's internal debug log. This log is displayable onscreen by pressing the ~ (tilde) key (tilde space on some keyboards). The default log size is 200 lines.

      LogSize 5000
      

      Labelled Stars

      The LabelledStars section defines which stars will have text labels assigned to them, which are visible when this option is turned on. (This section is obsolete as of Celestia v1.5.0. Star names are displayed depending on the brightness of the stars.)

       LabelledStars
       
          [	"Sol"
      	"Sirius"
      	"Canopus"
      	"\u03b1 Centauri"
      	"Arcturus"
      	"Vega"
      	"Capella"
      	"Rigel"
      	"Procyon"
      	"Achernar"
      	"Betelgeuse"
      	"\u03b2 Centauri"
      	"Altair"
      	"Aldebaran"
      	"Antares"
      	"Spica"
      	"Acrux"
      	"Pollux"
      	"Fomalhaut"
      	"Deneb"
      	"\u03b2 Crucis"
      	"Regulus"
      	"Adhara"
      	"Castor"
      	"\u03b3 Crucis"
      	"Shaula"
      	"Bellatrix"
      	"Elnath"
      	"Miaplacidus"
      	"Alnilam"
      	"Al Nair"
      	"Alioth"
      	"\u03b3 Velorum"
      	"Dubhe"
      	"Mirfak"
      	"Wezen"
      	"Alkaid"
      	"\u03b5 Carinae"
      	"\u03b2 Aurigae"
      	"Polaris"    ]
      

      Types of Catalog Files

      Celestia's universe contains three broad categories of objects:

      • Stars (STC)
      • Deep sky objects (galaxies and nebulae) (DSC)
      • Solar system bodies (planets, moons, asteroids, comets, and spacecraft) (SSC)

      Each is defined in a different type of catalog file. Solar system catalog (.ssc) files contain definitions for solar system bodies; .dsc files contain definitions for deep sky objects; and stars may be defined in either .stc files or in stars.dat, which is in binary format. A binary star format is used because Celestia's universe contains many more stars than deep sky objects or solar system bodies, so having a compact, quickly loadable format is very important.

      Common Syntax of Catalog Files

      Except for binary .DAT star catalogs, all other catalogs are text files that contain lists of object definitions of a similar format. Each definition has a name followed by a list of properties. Property lists are a collection of name and value pairs grouped by braces. Here is the list of properties for the star Proxima Centauri:

      {
         RA 217.429167
         Dec -62.679444
         Distance 4.225
         SpectralType "M5.5V"
         AppMag 11.09
      }
      

      The property names are particular to the type of object. Property values have a type. In the example above, all of the properties are numbers except for the SpectralType which is a string. Celestia catalog files may contain comments -- any text between a hash character (#) and the end of a line is ignored.

      Number Values

      A number in a Celestia catalog file is a scalar real value. Very large or small values can be written in C-like exponential form, e.g. 1.2e-3 instead of .0012. Examples of valid number values:

      1234
      3.14159265
      1.234e10
      0.1025
      -2.24
      
      .1025  (Celestia v1.5.0 or later)
      +2.24  (Celestia v1.5.0 or later)
      

      
      Note: Celestia v1.4.1 and earlier versions have two restrictions which have been fixed in v1.5.0. In Celestia v1.4.1 and earlier, all numbers must start with either a numeric character or a minus sign. A leading decimal point or a leading + should not be used. That is, values less than 1 must have a leading 0: 0.5 is OK, but .5 is not. Also, a leading + is assumed. Providing one will cause an error.

      String Values

      Strings are arbitrarily long sequences of characters enclosed by double quotes. They can span multiple lines, though any newlines inside a string will be interpreted literally. Some special characters may be represented by backslash-prefixed escape sequences.

      \"

      Double quote character

      \n

      Newline

      \\

      Backslash

      \uxxxx

      Unicode character, where xxxx is a sequence of four hex digits

      Vector Values

      A vector in a Celestia catalog file is a list of three real values enclosed by square brackets. Example vectors:

      [ 0 +1 0 ]
      [ 1.2 -3.4 5 ]
      [ 1.0e3 2.2 63 ]
      

      Property List Values

      Some properties in a list have complex values that are themselves property lists. Like top-level property lists, these are just brace enclosed lists of name-value pairs. Here is how you would set the value of the property named UniformRotation in a solar system catalog (.ssc) file:

      UniformRotation
      {
         Period 24.0
         Inclination 23.5
      }
      

      (This is just an example to show the format. The directive UniformRotation is not recognized by Celestia v1.4.1 and earlier. It requires Celestia v1.5.0.)

      Date Values

      A date value may be written either as a number or as a string. A number is interpreted as a Julian day number. Date strings contain the Gregorian year, month, and day of the month. They may optionally have an hh:mm:ss formatted time. A 24-hour clock is used for the time. Negative year values are used instead of BC or BCE; if you want a date in 1 B.C., you should set the year to be zero. (This is the astronomical convention, which is not the same as the Christian convention used in most calendars. The Christian calendar has no year numbered 0.)

      Examples of date values with explanatory comments:

      2451545.0              # J2000 - noon January 1, 2000
      2453023.1232
      "2006 11 8"            # midnight November 8, 2006
      "1984 12 25 1:30:00"   # 1:30am December 25, 1985
      "-4 8 23 10:00:00"     # 10:00am August 23, 5 B.C.
      "2130 4 1 22:10:34.15" # 22:10:34.15 April 1, 2130
      

      Starting with Celestia v1.5.0, all catalog times are specified using the TDB (Barycentric Dynamical Time) time scale. However, the on-screen time is shown in UTC. TDB is offset from UTC (Coordinated Universal Time) by 32.184 seconds plus some integer number of leap seconds. As of 2006, TDB is 65.184 seconds ahead of UTC. For further information, see the page on time scales. Celestia/Celestia/SSC File Celestia/Celestia/STC File Celestia/Celestia/DSC File

      • Positioning Objects: Flying through Time and Space
        • ==Introduction==

      The orbits and trajectories of objects in Celestia are predefined. Their definitions are loaded when Celestia starts.

      Celestia does not calculate any gravitational effects. All gravitational effects must be included in the orbit and trajectory definitions. Gravitational effects are already incorporated in Celestia's VSOP87 CustomOrbits and in the JPL DE405 ephemeris files which can be used in CustomOrbits, in NASA's SPICE ephemeris files which can be used in SpiceOrbits, and in the SampledOrbits of the spacecraft which are included with Celestia.

      In many cases, Celestia assumes that an object will always be at same place at the same time. Periodic orbits have an orbital path drawn for them.

      CustomOrbit, EllipticalOrbit and SampledOrbit directives are recognized by all versions of Celestia. FixedPosition, SpiceOrbit and ScriptedOrbit are new directives which require Celestia v1.5.0 or later.

      By default, if an SSC or STC object orbits a Star or STC Barycenter, then trajectories are defined relative to our Solar System's J2000 Ecliptic plane. If an SSC object orbits another SSC object, then its trajectory is defined relative to the parent body's J2000 equator. In Celestia v1.5.0 or newer, one also has the option of specifying any of a number of other Reference Frames in an SSC catalog. These new orbit and reference frame directives are not yet recognized in an STC file.

      The following is a list of the orbit and trajectory directives which are recognized in SSC files. More information is available on the page Celestia/SSC File.

      FixedPosition

      Requires Celestia 1.5.0

      The FixedPosition trajectory type makes the center of a body stationary within its Reference Frame.

      Usage:

      FixedPosition [ <x> <y> <z> ]
      

      Units for the coordinates are AU for bodies orbiting Stars or Barycenters, and kilometers for all other objects.

      Alternate Usage (Requires Celestia 1.6.0):

      It can be convenient to specify a fixed position using spherical rather than rectangular coordinates, thus Celestia offers an alternate form of FixedPosition:

      FixedPosition
      {
          Planetographic [ <longitude> <latitude> <altitude> ]
      }
      

      Longitude and latitude are in degrees; altitude is the height in kilometers above the surface of the parent object.

      EllipticalOrbit

      An EllipticalOrbit can be used either in an SSC file or in an STC file.

      Usage:

      EllipticalOrbit
      {
          Period <number>
      
          SemiMajorAxis <number>
          PericenterDistance <number>
      
          ArgOfPericenter <degrees> 
          LongOfPericenter <degrees> 
      
          MeanAnomaly <degrees> # default: 0
          MeanLongitude <degrees>
      
          Eccentricity <number> # default: 0
      
          Inclination <degrees> # default: 0.0
      
          AscendingNode <degrees> # default = 0.0 
      
          Epoch <date> # default: J2000.0
      }
      

      A valid EllipticalOrbit requires Period and SemiMajorAxis (or PericenterDistance) to be specified. All the other properties have default values and are optional.

      Period

      gives the orbital period in Earth years for bodies that orbit Stars or Barycenters, and Earth solar days for all other bodies.

      Several of the orbital parameters may be specified in two different ways.

      SemiMajorAxis

      The size of the orbit can be given as the SemiMajorAxis or PericenterDistance. The latter is more intuitive for hyperbolic orbits. If both SemiMajorAxis and PericenterDistance are specified, SemiMajorAxis overrides PericenterDistance. The units of both SemiMajorAxis and PericenterDistance are AU for bodies that orbit Stars or Barycenters, and kilometers for all other bodies.

      ArgOfPericenter

      The pericenter angle is given by either ArgOfPericenter or LongOfPericenter. ArgOfPericenter is measured from the ascending node, whereas LongOfPericenter is measured from the fundametal direction. If both ArgOfPericenter and LongOfPericenter are specified, ArgOfPericenter overrides LongOfPericenter.

      MeanAnomaly

      The position of the body on its orbit at Epoch is given by either the MeanAnomaly or the MeanLongitude. MeanAnomaly is measured from the pericenter angle, whereas MeanLongitude is measured from the fundamental direction. If both MeanAnomaly and MeanLongitude are specified, MeanAnomaly overrides MeanLongitude.

      Eccentricity

      determines the shape of the orbit. In fact, the name EllipticalOrbit is a bit misleading because the orbit may be circular, elliptical, parabolic, or hyperbolic depending upon the eccentricity:

      • eccentricity = 0 – circle
      • 0 < eccentricity < 1 – ellipse
      • eccentricity = 1 – parabola
      • eccentricity > 1 – hyperbola

      If Eccentricity is not provided, a circle is assumed.

      Inclination

      is optionally used to specify how much the orbit is tilted with respect to its reference plane. By default, that plane is the Ecliptic for bodies that orbit Stars or Barycenters, and the equator of the parent object for all other bodies. Starting with Celestia v1.5.0, any of a number of different reference planes can be specified. See Reference Frames for details. If Inclination is not specified, a value of 0 degrees is assumed.

      AscendingNode

      optionally defines the longitude of the point in its orbit where the orbiting body crosses the reference plane going "upward" or "northward". It is measured in degrees from the fundamental direction. If AscendingNode is not specified, a value of 0 degrees is assumed.

      Epoch

      optionally specifies the date at which these parameters are valid. It can be provided either as a number or as a quoted string. A number is interpreted as a Julian date. A quoted string is interpreted as a Gregorian date in the format "<year> <month> <day> <hours>:<minutes:<seconds>" e.g. "2007 10 09 12:13:14". If Epoch is omitted, a date of January 1, 2000, is assumed.

      Starting with Celestia v1.5.0, Epoch must be specified in TDB. See Celestia/Time Scales for more information about TDB and UTC.

      CustomOrbit

      A CustomOrbit is an orbit calculation that is built in to Celestia. Orbital theories for all the major planets and most of the larger satellites are available. The valid standard CustomOrbit names are listed below. Starting with Celestia v1.5.0, a JPL DE405 ephemeris can be provided. See JPL Ephemerides for details. A CustomOrbit takes priority over an EllipticalOrbit, but a CustomOrbit which specifies an unrecognized name is ignored.

      Usage:

      CustomOrbit <name>
      

      Example:

      CustomOrbit "vsop87-venus"
      

      The following list gives all of the available CustomOrbits in Celestia 1.5.0:

      VSOP87

      VSOP87 (Variations Séculaires des Orbites Planétaires) is an orbital theory for the major planets by P. Bretagnon et al. Celestia does not use the full set of terms. For a higher accuracy alternative to VSOP87, JPL Ephemerides may be used for the orbits of the major planets, Pluto, the Moon, and the Sun.

      • vsop87-mercury
      • vsop87-venus
      • vsop87-earth
      • vsop87-mars
      • vsop87-jupiter
      • vsop87-saturn
      • vsop87-uranus
      • vsop87-neptune
      • vsop87-sun (orbit of Sun about the Solar System Barycenter)

      Pluto

      Reference needed

      • pluto

      Galilean satellites

      From J. H. Lieske's "E5" theory as given in Jean Meeus's Astronomical Algorithms, pp. 301-315:

      • io
      • europa
      • ganymede
      • callisto

      Satellites of Saturn

      From Gérard Dourneau (1987), "Observations et étude du mouvement des huit premiers satellites de Saturne"

      • mimas
      • enceladus
      • tethys
      • dione
      • rhea
      • titan
      • hyperion
      • iapetus

      Satellites of Uranus

      From Laskar and Jacobson (1978), "An Analytical Ephemeris of the Uranian Satellites"

      • miranda
      • ariel
      • umbriel
      • titania
      • oberon

      The Moon

      Reference needed

      • moon

      SampledTrajectory

      This is available only in Celestia v1.5.0 or later.

      SampledTrajectory is used to import an ASCII file containing a list of time stamps and positions (or optionally, positions with velocities.) Typically, such files are generated by trajectory modeling and analysis software.

      SampledTrajectory
      {
          Source <filename>
          DoublePrecision <boolean>
          Interpolation <string>
      } 
      

      The Source property is required, while the others are optional. The contents of the Source file are the same as for a SampledOrbit file. Valid values for interpolation are currently "linear" and "cubic", with cubic the default. DoublePrecision defaults to true. The following two trajectories are equivalent:

      SampledTrajectory
      {
          Source "file.xyz"
          DoublePrecision false
          Interpolation "cubic"
      }
      

      SampledOrbit "file.xyz"
      

      Whenever accuracy is important, SampledTrajectory should be used with DoublePrecision true. Single precision floating point numbers are only precise to about one part in eight million; for an interplanetary trajectory to the outer solar system, this means errors of hundreds of kilometers.

      A sampled trajectory file is a list of time and position records. Here's an excerpt from a trajectory file for Galileo:

      2447818.615972 134114700.2612462193 64912642.6984842718 39861.799941
      2447819.615972 133153386.7785827518 66969511.3118158504 237125.784089
      2447820.615972 132137795.3581911474 69024279.8844281882 418499.867572
      2447821.615972 131079666.1268854141 71061806.8872888833 596914.157647
      

      The first value on each line is a Julian date (TDB), and that last three values are positions in kilometers. The reference frame for the positions is given in the ssc file. By default, Celestia uses a technique called cubic Hermite interpolation for smooth motion between points.

      
      Celestia 1.6.0 adds support for position and velocity trajectory files. These files have the extension xyzv, and can be used in exactly the same manner as xyz files in a SampledTrajectory:

      SampledTrajectory { Source "trajectory.xyzv" }
      

      The records in an xyzv file have the same layout as in an xyz file except that three velocity values are appended after each position. The units for velocity are kilometers per second. For a given file size, xyzv files give much more accurate positioning of objects. Thus, if it's possible to get velocities as well as positions for an object, an xyzv file should always be preferred over an xyz file.

      The web interface for HORIZONS can be used to produce trajectories with velocities as well as positions. There's also a new tool for Celestia called spice2xyzv that will generate an xyzv file from one or more SPICE kernels.

      SampledOrbit

      SampledOrbit is deprecated; SampledTrajectory is more flexible and provides the same functionality.

      SampledOrbit is used to import a file of times and associated coordinates.

      Usage:

      SampledOrbit <name>
      

      Example:

      SampledOrbit "galileo.xyz"
      

      The file must be located in the directory named data which is associated with the object.

      The file must contain sets of 4 numeric values which define positions along the object's trajectory. The individual values must be separated by spaces, tabs, or line terminators. Celestia reads 4 values for each set and doesn't care what "white space" is used to separate them. The file could contain one number per line or all of the numbers in the file could be on a single line.

      Each set of numbers consists of a TDB Julian date followed by x, y and z positions measured in kilometers. They are positions within the coordinate system associated with the object. By default, for example, the SampledOrbit for a spaceprobe orbiting the Sun would contain heliocentric Ecliptic J2000 coordinates. In Celestia v1.5, any of a variety of Reference Frames could be specified. See Celestia/Reference_Frames for details.

      Limitation:

      Although the x, y and z coordinates may be provided with any precision, Celestia stores them internally as single precision (32 bit) floating point numbers. V1.5.0 of Celestia implements double precision as a separate option. See SampledTrajectory above.

      SpiceOrbit

      Requires Celestia 1.5.0

      SpiceOrbit is used to import a trajectory from NASA's SPICE spacecraft information system into Celestia. Not all versions of Celestia are built with SPICE support.

      Usage:

      SpiceOrbit
      {
          Kernel <filename>
          Target <ID string>
          Origin <ID string>
          Beginning <date>
          Ending <date>
          BoundingRadius <number>
          Period <number>
      }
      

      The Kernel property specifies the name of the SPICE kernel (SPK) file to load. Celestia expects the kernel file to reside in an add-on's data directory.

      Target is the NAIF ID code for the object that you want to place in Celestia. A list of codes may be found here: http://www.gps.caltech.edu/~marsdata/req/naif_ids.html

      Either the integer ID or name may be used. The SpiceOrbit will be ignored if the kernel file does not contain a trajectory for specified object ID. The trajectory coordinates are relative to the position of the Origin object, which is specified with another NAIF ID code. It must match the origin of the reference frame. The coordinate system of the SpiceOrbit is the mean ecliptic and equinox of J2000. This matches the default reference frame that Celestia uses for Sun-orbiting bodies, but not the reference frame for other bodies. For an object that does not orbit the Sun and has its trajectory defined by a SpiceOrbit, you must explicitly specify an ecliptic reference frame:

      OrbitFrame
      {
          EclipticJ2000 { Center <object name> }
      }
      

      Beginning and Ending delimit the time range over which the SPICE trajectory is valid. The values can be either numeric Julian dates or Gregorian date strings. These times must be within the bounding times specified inside the SPICE kernel.

      The BoundingRadius of the orbit needs to be supplied in order for culling to work. Period is optional; it's used by Celestia only for orbit path rendering. If it's set to zero or not given at all, the orbit is assumed to be an aperiodic trajectory. The units for BoundingRadius and Period are AU and years for bodies that directly orbit a star, and kilometers and Earth solar days for other bodies. The use of two different units is for consistency with other Celestia trajectory types.

      Example: Pluto

      This example uses a SPICE kernel for the orbit of Pluto. Note that the origin "SUN" matches the reference frame center, given here by the parent object.

      "Pluto" "Sol"
      {
          SpiceOrbit
          {
               Kernel "de403_2000-2020.bsp"
               Target "Pluto Barycenter"
               Origin "SUN"
               Beginning "2000 1 1"
               Ending "2020 1 1"
               BoundingRadius 40
               Period 248.0
          }
      }
      

      ScriptedOrbit

      Requires Celestia 1.5.0

      A ScriptedOrbit is used to create custom trajectory functions with Lua scripts.

      Usage:

      ScriptedOrbit
      {
          Module <string>
          Function <string>
      
          ...additional properties...
      }
      

      Module gives the name of a package that will be loaded via Lua's require method. It searches a standard lists of paths for a script file with the specified name. An Addon's ScriptedOrbit's Module file should be located in a directory named celxx in the Addon's main directory. Function is the name of a factory function that produces a table with the orbit properties, including a function that returns the position at a particular time. All of the ScriptedOrbit properties other than Module and Function are passed on to the Lua function to create the orbit object. The function name is the only required parameter.

      To create your own ScriptedOrbit, you need to have some familiarity with the Lua scripting language used in Celestia's celx scripts. The Lua function specified in the ScriptedOrbit definition is a factory function that gets called immediately after the ScriptedOrbit is parsed. The factory function accepts a single table parameter containing all the properties from the ScriptedOrbit definition. The function must return a Lua orbit object, which is just a table with several standard fields. They are:

      • boundingRadius - A number giving the maximum distance of the trajectory from the origin; must be present, and must be a positive value.
      • period - A number giving the period of the orbit. If not present, the orbit is assumed to be aperiodic. The orbital period is only used for drawing the orbit path.
      • beginDate, endDate - optional values that specify the time span over which the orbit is valid. If not given, the orbit is assumed to be usable at any time. The orbit is invalid if end < begin.
      • position(time) - The position function receives a time value as input (TDB Julian day) and must return three values which are the x, y, and z coordinates. Units for the position are kilometers.

      ScriptedOrbits have a few limitations. The only allowed parameters are simple types: strings, numbers, and booleans. Complex types such as arrays and property lists will not be passed on to the Lua factory function. This limitation may disappear in a future version of Celestia. Also, Celestia expects that the position function will always return the same position for identical time values.

      Example ScriptedOrbit

      Here's an example ScriptedOrbit usage in an .ssc file.

      "Scripted" "Sol/Test Object"
      {
          Radius 500
      
          ScriptedOrbit
          {
              Module "orbits"
              Function "lissajous"
      
              PeriodX 1
              PeriodY 3.1
              PeriodZ 2.4
              PhaseX 0.5
              PhaseY 0.2
              PhaseZ 0.0
              AmplitudeX 1000
              AmplitudeY 800
              AmplitudeZ 540
          }
      }
      

      The above ssc fragment tells Celestia to load a file called orbits.lua and invoke the function lissajous to create a new script orbit object. The rest of the properties will all be passed to the lissajous function as fields of a table. Next, the actual Lua function:

      function lissajous(t)
         -- Create a new table
         local orbit = {};
      
         -- Save the parameter list 
         orbit.params = t;
      
         -- Set the required fields boundingRadius and position; note that position is actually a function
      
         -- Compute the bounding radius from the amplitudes
         orbit.boundingRadius =
             math.sqrt(t.AmplitudeX * t.AmplitudeX +
                       t.AmplitudeY * t.AmplitudeY +
                       t.AmplitudeZ * t.AmplitudeZ)
      
         -- The position function will be called whenever Celestia needs the position of the object
         function orbit:position(tjd)
             local t = tjd - 2451545.0
             local pi2 = math.pi * 2;
             local x = self.params.AmplitudeX * math.sin((t / self.params.PeriodX + self.params.PhaseX) * pi2)
             local y = self.params.AmplitudeY * math.sin((t / self.params.PeriodY + self.params.PhaseY) * pi2)
             local z = self.params.AmplitudeZ * math.sin((t / self.params.PeriodZ + self.params.PhaseZ) * pi2)
      
             return x, y, z
          end
      
          return orbit
      end 
      

      The Lissajous function may be used over and over with different ScriptedOrbit properties. As long as you know what parameters are expected, you can use an orbit script written by someone else without actually writing a line of code your self.

      • • • == Using JPL Ephemerides with Celestia ==

      Note: This information does not pertain to versions of Celestia prior to 1.5.0

      It is possible to use JPL's DE405/406 ephemerides with Celestia to compute the positions of the planets more accurately than the default VSOP87 theory does. The tradeoff is that since JPL's ephemeris files are essentially large lookup tables, a lot of memory is required to cover the same time span as VSOP87.

      First, you need to download the ephemeris files. They are available here:

      ftp://ssd.jpl.nasa.gov/pub/eph/planets/unix/de406/

      The ones named unxpNNNN.406 are probably of most interest. They contain 300 year blocks of the DE406 ephemeris beginning at year +NNNN. The files name unxmNNNN.406 cover the years prior 1 BCE. Each block is about nine megabytes, so the total size of the entire DE406 is about 180 MB. You don't need to use more than a single block, but if you want more than a 300-year ephemeris, there is a set of tools available on the JPL FTP site. The C tools may be found here:

      ftp://ssd.jpl.nasa.gov/pub/eph/planets/C-versions/hoffman/

      DE405 is a larger and slightly more precise ephemeris than DE406, but DE406 should be more than accurate enough for most usages. The differences are explained in this document:

      ftp://ssd.jpl.nasa.gov/pub/eph/planets/README.txt

      To use JPL ephemeris, you need to place in Celestia's data directory and name it 'jpleph.dat'. Then, you should modify the CustomOrbits of the planets defined in solarsys.ssc to use the JPL ephemeris instead of the default VSOP87 orbits. Here are the available CustomOrbit names:

      • Heliocentric orbits for the planets

      jpl-mercury-sun
      jpl-venus-sun
      jpl-earth-sun
      jpl-mars-sun
      jpl-jupiter-sun
      jpl-saturn-sun
      jpl-uranus-sun
      jpl-neptune-sun
      jpl-pluto-sun
      

      • Planet orbits relative to the solar system barycenter

      jpl-mercury-ssb
      jpl-venus-ssb
      jpl-earth-ssb
      jpl-mars-ssb
      jpl-jupiter-ssb
      jpl-saturn-ssb
      jpl-uranus-ssb
      jpl-neptune-ssb
      jpl-pluto-ssb
      

      • Position of the Earth-Moon barycenter relative to Sun and SSB

      jpl-emb-sun
      jpl-emb-ssb
      

      • Position of the Earth relative to the Earth-Moon barycenter

      jpl-earth-emb
      

      • Geocentric and barycentric position of the Moon

      jpl-moon-earth
      jpl-moon-emb
      

      • Position of the Sun relative to the SSB

      jpl-sun-ssb
      

      The positions computed for jpl-mars, jpl-jupiter, jpl-saturn, jpl-uranus, jpl-neptune, and jpl-pluto are the barycenters of the systems. Venus and Mercury have no moons, so the barycenters are exactly the center of the planets. Although Mars does have moons, they're so tiny relative to Mars that Horizons appears to treat the Mars system barycenter and the center of Mars as identical. There's a slight inconsistency with jpl-earth: it gives the position of Earth. If you want the Earth-Moon barycenter, then use jpl-emb.

      In case you are curious as to how much the positions of the giant planets deviates from their system barycenters, a rough calculation for Uranus and Titania gives ~20km. The mass ratio of the Galilean satellites and Jupiter is similar, though they are further away from Jupiter and will thus displace the barycenter more.

      Reference frame

      Although the native reference frame of the JPL ephemerides is the Earth mean equator and equinox of J2000.0. Celestia internally transforms these (via a fixed rotation) to the J2000 ecliptic frame. This allows the default VSOP87 orbits to be replaced with JPL orbits by simply changing the CustomOrbit. The sole exception is the Moon. The default reference plane for moons is the plane of the equator of date for the planet that the moon orbits. Thus, when changing the orbit of the Moon to use the JPL ephemeris, the orbit frame must be overridden:

      OrbitFrame {
          EclipticJ2000 { Center "Sol/Earth" }
      }
      

      Example

      There are two ways to switch to using from using VSOP87 series to JPL ephemerides for the planets. You can either directly modify data/solarsys.ssc, or you can create a simple add-on that takes advantage of the Modify disposition for SSC objects. Following is an example that replaces the orbits of the all the solar system's planets and the Moon. Copy and paste this example into a new .ssc file in your extras directory, and the next time you start Celestia, the positions of the planets will be computed from the JPL ephemeris in data/jpleph.dat.

      Modify "Mercury" "Sol"
      {
          CustomOrbit "jpl-mercury-sun"
      }
      
      Modify "Venus" "Sol"
      {
          CustomOrbit "jpl-venus-sun"
      }
      
      Modify "Earth" "Sol"
      {
          CustomOrbit "jpl-earth-sun"
      }
      
      Modify "Moon" "Sol/Earth"
      {
          OrbitFrame
          {
              EclipticJ2000 { Center "Sol/Earth" }
          }
          CustomOrbit "jpl-moon-earth"
      }
      
      Modify "Mars" "Sol"
      {
          CustomOrbit "jpl-mars-sun"
      }
      
      Modify "Jupiter" "Sol"
      {
          CustomOrbit "jpl-jupiter-sun"
      }
      
      Modify "Saturn" "Sol"
      {
          CustomOrbit "jpl-saturn-sun"
      }
      
      Modify "Uranus" "Sol"
      {
          CustomOrbit "jpl-uranus-sun"
      }
      
      Modify "Neptune" "Sol"
      {
          CustomOrbit "jpl-neptune-sun"
      }
      
      Modify "Pluto" "Sol"
      {
          CustomOrbit "jpl-pluto-sun"
      }
      

      • • • == Reference Frames ==

      A reference frame is an origin and set of axes which define the coordinate system used for a body's trajectory and orientation. The origin is some other body defined in a catalog file. There are a number of ways to set the coordinate system axes.

      The reference frames used for a body's trajectory and its orientation do not have to be the same. This is useful in some situations. For example, the orbit of a satellite may be given in a geocentric equatorial coordinate system, while the attitude is given in a local vertical-local horizontal system.

      All of the Reference Frames keywords require Celestia 1.5. They are ignored by earlier versions.

      OrbitFrame property

      Set the reference frame for the trajectory

      Default: For bodies which have a star as the parent, the default reference frame for the orbit is centered on the star. The fundamental plane is the J2000 Earth ecliptic, and the preferred direction (x-axis) is the J2000 equinox. For all other bodies, the default reference frame is the equatorial frame of the parent body.

      Usage

      OrbitFrame <reference frame>
      

      BodyFrame property

      Set the reference frame for the orientation

      Default: For bodies which have a star as the parent, the default reference frame for the orientation is the J2000 ecliptic and equinox. For all other bodies, the default reference frame is the equatorial frame of the parent body (which can in turn default to the J2000 ecliptic and so on).

      Usage

      BodyFrame <reference frame>
      

      Reference Frame object

      A reference frame is a list containing a single property that is one of the specific reference frame types.

      Usage

      {
          <J2000 ecliptic frame> | 
          <J2000 equator frame> |
          <body mean equator frame> |
          <body-fixed frame> |
          <two-vector frame>
      }
      

      
      

      EclipticJ2000 property

      EclipticJ2000 is a reference frame with the Earth ecliptic at epoch J2000 as the fundamental plane. The x-axis points along the J2000 vernal equinox, the z-axis points northward perpendicular to the ecliptic, and the y-axis completes the right-handed system.

      Usage:

      EclipticJ2000
      {
          Center <object name>
      }
      

      
      

      EquatorJ2000 property

      EquatorJ2000 is a reference frame with the Earth equator at epoch J2000 as the fundamental plane. The x-axis points along the J2000 vernal equinox, the z-axis is the mean north pole, and the y-axis completes the right-handed system.

      Usage:

      EquatorJ2000
      {
          Center <object name>
      }
      

      
      

      MeanEquator property

      MeanEquator defines a reference frame in which the body's equator of date is the xy-plane. The z-axis is perpendicular to the xy-plane, pointing in a direction such that the body rotates counterclockwise about it. The x-axis is the ascending node of the equatorial plane on the J2000 ecliptic plane.

      Usage:

      MeanEquator
      {
          Center <object name>
          Object <object name>
          Freeze <date>
      }
      

      Properties:

      • Object: the fundamental plane is the equatorial plane of this body
      • Freeze: if set, the equator of the freeze epoch is used instead of the equator of date

      BodyFixed property

      A BodyFixed reference frame rotates with the specified body.

      Usage:

      BodyFixed
      {
          Center <object name>
      }
      

      
      

      TwoVector property

      Usage:

      TwoVector
      {
          Center <object name>
          Primary <axis>
          Secondary <axis>
      }
      

      
      

      Axis object

      An axis object is a list containing a single direction property along with an axis label.

      Usage:

      {
          Axis "x" | "y" | "z" | "-x" | "-y" | "-z"
          <RelativePosition> | <RelativeVelocity> | <ConstantVector>
      }
      

      
      

      RelativePosition property

      Usage:

      RelativePosition
      {
          Observer <object name>
          Target <object name>
      }
      

      The default observer object is the coordinate frame center. The target object has no default and must always be specified.

      
      

      RelativeVelocity property

      Usage:

      RelativeVelocity
      {
          Observer <object name>
          Target <object name>
      }
      

      The default observer object is the coordinate frame center. The target object has no default and must always be specified.

      ConstantVector property

      Usage:

      ConstantVector
      {
          Vector <vector>
          Frame <reference frame>
      }
      

      Examples:

      Earth's north rotational pole:

      ConstantVector
      {
          Vector [ 0 0 1 ]
          Frame {
              EquatorJ2000 { Center "Sol/Earth" }
          }
      }
      

      Reference Frame Examples

      Heliocentric Earth Equatorial

      OrbitFrame {
          EquatorJ2000 { Center "Sol" }
      }
      

      Geocentric Solar Ecliptic

      This reference frame is based on an example from the SPICE Frames Required Reading document. The origin is the Earth, the xy-plane is the Earth's orbital plane, and the x-axis points from Earth toward the Sun.

      OrbitFrame {
          TwoVector {
              Center "Sol/Earth"
              Primary {
                  Axis "x"
                  RelativePosition { Target "Sol" }
              }
              Secondary {
                  Axis "y"
                  RelativeVelocity { Target "Sol" }
              }
          }
      }
          
      

      Sun-locked

      This reference frame for a Sun-orbiting object called 'Test' has its z-axis pointing toward the Sun, and the x axis pointing in the direction of travel. An object with a fixed orientation in this reference frame will always have the same side facing the Sun:

      BodyFrame {
          TwoVector {
              Center "Sol/Test"
              Primary {
                  Axis "z"
                  RelativePosition { Target "Sol" }
              }
              Secondary {
                  Axis "x"
                  RelativeVelocity { Target "Sol" }
              }
          }
      }
      

      JPL Solar System Dynamics pages

      The JPL Solar System Dynamics pages provide mean orbital parameters of planetary satellites using a variety of reference frames. Entering these in solarsys.ssc can be challenging.

      • When mean ecliptic elements are given (for a satellite of "object"):

      EllipticalOrbit {
      ...
      }
      
      OrbitFrame { EclipticJ2000 {
              Center "object"
      } }
      

      
      

      • When the elements are referred to the primary's equator:

      EllipticalOrbit {
      ...
      }
      
      OrbitFrame { BodyMeanEquator {
         Center "object"
         Object "object"
         [Freeze <date>]
      } }
      

      
      

      • When the elements are referred to the ICRF (which is very nearly identical to the Earth equatorial frame):

      EllipticalOrbit {
      ...
      }
      
      OrbitFrame { EquatorJ2000 {
          Center "object"
      } }
      

      
      

      • When the elements are referred to the local Laplace planes:

      This is the worst case. The Laplace plane for each satellite is defined by its polar right ascension and declination (in the EquatorJ2000 frame); this defines the local Laplace plane's ascending node longitude (90° plus the pole's RA) and inclination (the co-declination, i.e. 90° minus the dec).

      EllipticalOrbit {
      ...
      }
      
      OrbitFrame { TwoVector {
          Center "object"
          Primary { Axis "x"
              ConstantVector { Vector [<Laplace plane ascending node>] Frame { EquatorJ2000 { Center "object" } } }
          }
          Secondary { Axis "z"
              ConstantVector { Vector [<Laplace plane pole>] Frame { EquatorJ2000 { Center "object" } } }
          }
      } }
      

      
      

      Additional Examples

      Placing Several Objects Identically on the Earth's Surface

      Here's an example of defining a position and orientation relative to the Earth. One can then reference this definition while placing several models instead of replicating the same definition for each of them: corrections to the position only have to be made in one place instead of several.

      Note that some of the declarations which are included in this example could be omitted since their default values would place the objects appropriately.

      "Hale_position" "Sol/Earth"
      {
       Class "invisible"
       Radius 0.0001
      
      # Place the Hale Telescope on the peak of Mount Palomar
      
       OrbitFrame { BodyFixed { Center "Sol/Earth" }}
       FixedPosition  [ -2407.99 -4753.86 3507.91 ]
      
      # Orient it appropriately with respect to the surface
       
       BodyFrame { BodyFixed { Center "Sol/Earth" }}
       FixedRotation { MeridianAngle -116.86 AscendingNode 90 }
      
      }
      
      "Hale_model" "Sol/Earth/Hale_position"
      {
        Mesh "telescope.3ds"
        Radius 0.3
      
        OrbitFrame { BodyFixed { Center "Sol/Earth/Hale_position" }}
        FixedPosition  [ 0 0 0 ]
      
        BodyFrame { BodyFixed { Center "Sol/Earth/Hale_position" }}
        FixedRotation { }
      
        Albedo 0.1
      
      }
      
      "Dome_model" "Sol/Earth/Hale_position"
      {
        Mesh "dome.3ds"
        Radius 0.3
      
        OrbitFrame { BodyFixed { Center "Sol/Earth/Hale_position" }}
        FixedPosition  [ 0 0 0 ]
      
        BodyFrame { BodyFixed { Center "Sol/Earth/Hale_position" }}
        FixedRotation { }
      
        Albedo 0.1
      
      }
      

      External links

      • http://www.gps.caltech.edu/~marsdata/req/frames.html - SPICE Required Reading Documents: Reference Frames
        • • = Using SPICE with Celestia =

      SPICE is a software suite developed at NASA for making the geometric calculations needed to plan an interplanetary mission. SPICE is used by mission teams at NASA, ESA, JAXA, and other space agencies. Most versions of Celestia are built with the SPICE libraries, enabling Celestia to use navigational data direct from space missions.

      Audience

      This tutorial is targeted at two groups of people:

      • Mission operators and scientists who want to use Celestia for visualization
      • Experienced Celestia users interested in very accurate reconstructions of space missions

      Those already familiar with SPICE can skip the "Introduction to SPICE" section.

      Spice Introduction

      An in-depth discussion of SPICE is beyond the scope of this tutorial, but knowing few concepts should be enough to make most of this tutorial understandable. SPICE kernel files contain different types of data relevant to space missions. SPK files (typically with the extension bsp) are used to calculate the position of a spacecraft, planet or other body. A single SPK file may have data for multiple bodies. Finding the position of a body relative so some other object may require multiple kernels. For example, one SPK file might have the position of Cassini relative to Saturn. A second SPK kernel might give the positions of the planets relative to the Sun. In order to compute the heliocentric position of Cassini, we need both kernels. Kernel files have orbit or trajectory files covering a finite time span. For spacecraft, the mission is usually split into several kernels, each covering a different mission phase. The site from which you download the SPK files should have some sort of README files describing the source and time coverage for each file.

      There is extensive documentation on SPICE available here at the main NAIF site:

      http://naif.jpl.nasa.gov/naif/

      The NAIF site is a good place to look for SPICE kernels for many space missions, including both currently operational and historical ones:

      http://naif.jpl.nasa.gov/naif/data.html

      Celestia Introduction

      Celestia loads information about solar system bodies (including planets, natural satellites, asteroids, and spacecraft) from .ssc (Solar System Catalog) files. Each ssc file is a list of one or more body definitions. A solar system body has a trajectory, a rotation model, and a collection of attributes related to its appearance (since Celestia is after all a visual simulation.) The trajectory and rotation model specify the position and orientation of the body over a range of time. The possible sources of trajectory information include Keplerian elements, hardcoded calculations (e.g. VSOP87), and of course, SPICE kernels. The lists of rotation model types is similar.

      Simple Example

      Here's a sample solar system body definition:

      Body "Earth" "Sun"
      {
          Texture "earth.*"
          Radius 6378.140  # equatorial
          Oblateness 0.0034
       
          CustomOrbit "vsop87-earth"
          CustomRotation "earth-p03lp"
      }
      

      This example defines a body called Earth which orbits the Sun. Built-in calculations are used for both the trajectory and rotation of Earth. These particular built-in calculations assume that the coordinate system is the heliocentric J2000 ecliptic system. Indeed, this is the default system for heliocentric objects in Celestia. But, we can make it explicit by adding OrbitFrame and BodyFrame definitions:

      Body "Earth" "Sun"
      {
          Texture "earth.*"
          Radius 6378.140  # equatorial
          Oblateness 0.0034
      
          OrbitFrame { J2000Ecliptic {} }  
          CustomOrbit "vsop87-earth"
          BodyFrame { J2000Ecliptic {} }
          CustomRotation "earth-p03lp"
      }
      

      Here, the frame for the trajectory and orientation are set to the same thing. But, we can make the BodyFrame different than the orbit frame if we want. This is useful for spacecraft, where it may make more sense to specify local vertical / local horizontal system.

      Spacecraft Example

      This tutorial will go step by step through the process of introducing a new spacecraft object into Celestia that has a position and attitude calculated by SPICE. We'll use the Deep Impact mission as an example. All of the SPICE kernels required for the mission may be downloaded from the NAIF site:

      ftp://naif.jpl.nasa.gov/pub/naif/DEEPIMPACT/kernels/

      The first thing to do is to create a new folder for the Deep Impact add-on. Make a folder called deepimpact inside Celestia's extras folder. Then, make subfolders inside deepimpact called data and models. The folder structure should look like this:

      extras/
         deepimpact/
             data/
             models/
      

      The ssc file for the Deep Impact mission will go in the deepimpact folder. The models folder will contain a 3D studio mesh file representing the spacecraft. Finally, all the necessary SPICE kernel files will go in data.

      Getting the SPICE Kernel Files

      The first files that we need for the mission are the SPK files. These may be found in the SPK directory:

      ftp://naif.jpl.nasa.gov/pub/naif/DEEPIMPACT/kernels/spk/aareadme.txt

      There are a lot of kernels in this directory, but fortunately, most are unnecessary. The file aareadme.txt helpfully clarifies which kernel files are necessary.

        NOTE 4: The following four of these SPKs should be loaded in
        this order to make sure that the best trajectory solutions are
        available to the calling application at any given time:
      
           dii_preenc174_nav_v1.bsp
           dif_preenc174_nav_v1.bsp
           di_tempel1_ssd_v1.bsp
           di_finalenc_nav_v3_to2006048.bsp
      

      The note also specifies a loading order for the files. We will need to pay attention to that later. For now, just copy the four .bsp files into the data subfolder of the Deep Impact mission add-on.

      Comet Trajectory

      We will be begin by creating a new Celestia object representing Comet 9P/Tempel. Although we could define the comet in a separate ssc file, we'll keep things and define all of the objects relevant to the Deep Impact mission in a single file called deepimpact.ssc. Here's the definition for Comet 9P/Tempel using just Keplerian elements for the orbit:

      Body "9P Tempel" "Sol"
      {
          Class "comet"
          SemiAxes [ 3.1 2.1 2.1 ]
          Texture "asteroid.jpg"
      
          EllipticalOrbit {
              Epoch                "2005 7 4 00:00:00"
              Period               5.51521370
              SemiMajorAxis        3.121543768
              Eccentricity         0.517493300
              Inclination         10.530163779
              AscendingNode       68.938123883
              ArgOfPericenter    178.837987181
              MeanAnomaly        359.765094570
          } 
      }
      

      The orbital elements were derived from HORIZONS. If you have a SPICE kernel for an object, it's not necessary to begin with orbital elements. It's done here only to illustrate how an object definition is changed to add a SPICE trajectory.

      Converting to SPICE

      The README file in the SPK directory lists four SPK files that are required for the Deep Impact mission. The same file also recommends an order in which the files should be loaded. The order is important because when there's more than one trajectory segment valid for an object at a particular time, the most recently loaded one has priority. Celestia always loads SPICE files in the order that they're listed in an SSC file. The README doesn't mention two extra kernel files that are needed for the mission: di_tempel1_v01.tpc and di_v17.tf. Together, these define a SPICE frame for the comet Tempel 1. This frame is used for Deep Impact's trajectory right around the time of impact. Careful reading of the documentation accompanying a set of SPICE kernels is often necessary in order to understand which kernel files should be used.

      Here is Tempel 1 with the Keplerian orbit replaced by a SPICE orbit:

      Body "9P Tempel" "Sol"
      {
          Class "comet"
          SemiAxes [ 3.1 2.1 2.1 ]
          Texture "asteroid.jpg"
      
          SpiceOrbit {
              Kernel [
                  "dii_preenc174_nav_v1.bsp"
                  "dif_preenc174_nav_v1.bsp"
                  "di_tempel1_ssd_v1.bsp"
                  "di_finalenc_nav_v3_to06048.bsp"
                  "di_tempel1_v01.tpc"
                  "di_v17.tf"
              ]
      
              Origin "SUN"
              Target "TEMPEL 1"
              BoundingRadius 10
          }
      }
      

      We are using four parameters for SpiceOrbit. The list of kernel files appears first. Celestia will load these kernel files from the add-on's data directory. It will ignore already loaded kernels, thus it's harmless to repeat the kernel list in the definition of every object that requires it. However, it does mean that multiple objects will have to be updated if a kernel file name changes. Origin and target are both NAIF names or IDs. Instead of "TEMPEL 1", we could have used the NAIF ID code 1000093. The name is much clearer, and so it is favored when available. The SPICE origin must match the Celestia origin. In Celestia an origin is given by the orbit frame center; if an orbit frame isn't explicitly specified (as in our example), the default frame is centered on the parent object. In our example, the Sun is the parent object.

      The BoundingRadius field gives the radius of a sphere centered at origin that is large enough to completely contain the orbit. This information is used by Celestia to optimize rendering; with it, Celestia can do very quick checks to see whether an object might possibly be visible. Setting too small a value for BoundingRadius may make an object disappear when it should be visible. Making it too large will have no visible side effects, but can force Celestia to make extra calculations. There's no need to get too precise—bounding radii that are too large by a factor of two shouldn't cause any performance problems. On the other hand, setting all bounding radii to extremely large values like 1000 AU is to be avoided. Like other distances in Celestia, the units of BoundingRadius are AU for heliocentric objects and kilometers for everything else.

      Spacecraft Trajectory

      Now that we've tracked down the kernels file needed for the trajectories of the objects involved in the mission, it's quite straightforward to add the flyby spacecraft:

      Body "Deep Impact" "Sol"
      {
          Class "spacecraft"
          Radius 0.003
          Mesh "DeepImpact2.3ds"
      
          SpiceOrbit {
              Origin "SUN"
              Target "DEEP IMPACT FLYBY SPACECRAFT"
              BoundingRadius 10
          }
      }
      

      The kernel files are omitted, since they're already loaded in the Tempel 1 definition. The only other thing different from the comet's SpiceOrbit is that we've changed the name of the target object.

      Spacecraft Attitude

      Showing accurate attitude for a spacecraft is slightly more difficult than getting a correct trajectory. The main chore may be finding all the kernel files necessary. For spacecraft, four types of kernel files are usually necessary:

      • One or more C-kernels giving the orientation of the spacecraft at different times
      • A text frame kernel that defines a SPICE frame for the spacecraft
      • A spacecraft clock (SCLK) kernel for translating UTC to spacecraft clock time
      • A leap second kernel for converting ephemeris time to UTC

      Once the needed kernel files have been installed in the add-on's data directory, we just need to replace the spacecraft's existing rotation model (if any) with a SpiceRotation. The syntax is very similar to that for SpiceOrbit.

      SpiceRotation {
          Kernel [
              "dif_sc_050112_050809.bc"
              "di_v17.tf"
              "DIF_SCLKSCET.00036.tsc"       
              "naif0009.tls"
          ]
          Frame "DIF_SPACECRAFT"
          BaseFrame "eclipj2000"
      }
      

      Note that there are four kernel files lists: a C-kernel, a text frame kernel, a spacecraft clock kernel, and a leap second kernel. The frame kernel isn't actually necessary because it was already loaded in a SpiceOrbit. However, it's listed here anyway, because this is a tutorial, and in the more typical case, the .tf file will appear in the kernel list for the trajectory. Frame gives the name of a C-kernel frame defined for the spacecraft. BaseFrame should be set to the SPICE equivalent of whatever the object's BodyFrame is in Celestia. The default BodyFrame of a Sun-orbiting object in Celestia is the J2000 ecliptic. This matches the default BaseFrame for a SpiceRotation: eclipj2000. Still, it's a good idea to explicitly specify both frames. This is one situation where Celestia's defaults can be confusing: for objects that orbit something other than a star, the default BodyFrame is the equatorial frame of the parent object. This is rarely what you want when using SPICE!

      Debugging SpiceRotation

      There are a lot of things that may go wrong when orienting a spacecraft with SPICE. If you restart Celestia and find that you spacecraft is pointing in the wrong direction, here are some things to check:

      • Press the tilde key (~) to bring up Celestia's console log. See if there are any SPICE errors scrolling by, perhaps indicating that some required kernel files are missing. If not, press the up error to scroll backward in the log. See if any errors occurred when loading the add-on.
      • Make sure that you haven't forgotten the leap second kernel or frame kernel
      • Verify that the SPICE frame matches the Celestia frame for the object (i.e. BaseFrame is appropriate for the object's BodyFrame.)
      • Check to make sure that the spacecraft's 3D mesh is oriented correctly in the body frame. The 'Reference Vectors/Body Axes' option in the spacecraft's right click popup menu is very helpful here.

      Adding the Impactor

      SPICE Planets

      We'll now convert the Earth example to use a SPICE kernel for the orbit of Earth. The SPICE kernel de421.bsp may be downloaded from the NAIF FTP site:

      ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/

      • • ==Introduction==

      All information on this page is relevant only for Celestia 1.5.0 and later.

      Prior to v1.5.0, separate rotation statements were used. See the chapter on SSC files for descriptions of those declarations.

      UniformRotation

      Usage:

      UniformRotation
      {
         Period <hours>
         Inclination <degrees>
         AscendingNode <degrees>
         MeridianAngle <degrees>
         Epoch <date>
      }
      

      Period is the sidereal rotation period of the object; that is, the rotation with respect to some fixed background. Thus the rotation period for the Earth would be 23.93 rather than 24 hours. If no Period is specified, the object will be tidally locked (i.e. always showing the same face to the parent body).

      FixedRotation

      Usage:

      FixedRotation
      {
         Inclination <degrees>
         AscendingNode <degrees>
         MeridianAngle <degrees>
      }
      

      An object with a FixedRotation will maintain a constant orientation within its reference frame. A fixed rotation has properties identical to UniformRotation except that a rotation period isn't required.

      PrecessingRotation

      Usage:

      PrecessingRotation
      {
         Period <hours>
         PrecessionPeriod <years>
         Inclination <degrees>
         AscendingNode <degrees>
         MeridianAngle <degrees>
         Epoch <date>
      }
      

      SampledOrientation

      Usage:

      SampledOrientation <filename>
      

      Where the filename is the name of a Celestia orientation file, which by convention has the extension .q (for quaternion.) The orientation file is a text file containing a time tagged list of quaternions. Times are Julian dates specified in Barycentric Dynamical Time (TDB). Each record in the file has the form:

      <double: Julian Date> <float: w> <float: x> <float: y> <float: z>
      

      where w is the real part, and x, y, and z the imaginary parts of a quaternion. A rotation of angle theta about the axis V is given by the quaternion: $(\cos {\frac {\theta }{2}},\mathbf {V} \sin {\frac {\theta }{2}})$

      ScriptedRotation

      A ScriptedRotation is used create rotation model where the orientation is given by a function in Lua script file.

      Usage:

      ScriptedRotation
      {
          Module <string>
          Function <string>
      
          ...additional properties...
      }
      

      Module gives the name of a package that will be loaded via Lua's require method. It searches a standard lists of paths for a script file with the specified name. Function is the name of a factory function that produces a table with the rotation model properties, including a function that returns the orientation at a particular time. All of the ScriptRotation properties other than Module and Function are passed on to the Lua function to create the rotation object. The function name is the only required parameter.

      To create your own ScriptedRotation, you need to have some familiarity with the Lua scripting language use in Celestia's celx scripts. The Lua function specified in the ScriptedRotation definition is a factory function that gets called immediately after the ScriptedRotation is parsed. The factory function accepts a single table parameter containing all the properties from the ScriptedRotation definition. The function must return a Lua rotation model object, which is just table with several standard fields. They are:

      • period - A number giving the period of the rotation in days. If not present, the rotation is assumed to be aperiodic.
      • beginDate, endDate - optional values that specify the time span over which the rotation model is valid. If not given, the rotation model is assumed to be usable at any time. A rotation model with end < begin is not allowed.
      • orientation(time) - The position function takes a time value as input (TDB Julian day) and returns four values which are the quaternion (w, x, y, z). This quaternion is related to the axis angle rotation (A, theta) by:

      $w=\cos {\frac {\theta }{2}}$, $x=A_{x}\sin {\frac {\theta }{2}}$, $y=A_{y}\sin {\frac {\theta }{2}}$, $z=A_{z}\sin {\frac {\theta }{2}}$

      Here's an example of how to use a ScriptedRotation in an .ssc file:

      "Scripted" "Sol/Earth"
      {
          ScriptedRotation
          {
              Module "rotations"
              Function "wobble"
              Period 1
              Amplitude 180
          }
      }
      

      The above ssc fragment tells Celestia to load a file called rotations.lua and invoke the function named wobble to create a new rotation model object. The rest of the properties will all be passed to the wobble function as fields of a table. Next, the contents of rotations.lua:

      -- prototype for the wobble scripted rotation has default values for
      -- any parameters that are omitted in the ssc file.
      wobbleproto =
      {
         Amplitude = 0,
         Period    = 1,
      }
      
      -- constructor method
      function wobbleproto:new(o)
         o = o or {}  -- create table if one not provided
         setmetatable(o, self)
         self.__index = self
      
         -- set the period to whatever value was specified in the ssc file;
         -- slightly confusing because Celestia is case sensitive--period must
         -- be lowercase, but the field from the ssc file is capitalized.
         o.period = o.Period
      
         return o
      end
      
      -- The orientation function. This implementation produces a back and forth
      -- wobble of Amplitude degrees about the z axis.
      function wobbleproto:orientation(tjd)
         local t = tjd - 2451545.0
         local theta = self.Amplitude * math.sin((t / self.Period + 0) * math.pi * 2);
      
         -- convert from degrees to radians
         theta = theta * math.pi / 180
      
         -- compute a quaternion representing the orientation
         return math.cos(theta / 2), 0, 0, math.sin(theta / 2)
      end
      
      function wobble(sscvals)
         -- create a new wobble rotation object
         return wobbleproto:new(sscvals)
      end
      

      ScriptedRotations have a few limitations. The only allowed parameters are simple types: strings, numbers, and booleans. Complex types such as arrays and property lists will not be passed on to the Lua factory function. This limitation may disappear in a future version of Celestia. Also, Celestia expects that the orientation function will always return the same orientation for identical time values.

      SpiceRotation

      1.6.0

      Usage:

      SpiceRotation
      {
          Kernel <string|string array>   # optional
          Frame <string>
          BaseFrame <string>             # optional (defaults to ecliptic)
          Period <number>                # optional (units are hours)
          Beginning <number>             # optional
          Ending <number>                # optional
      }
      

      SpiceRotation is used to import a orientation information from NASA's SPICE system into Celestia. The orientation of a Celestia object will be locked to a SPICE frame.

      Not all versions of Celestia are built with SPICE support. SpiceRotation is not support in versions of Celestia earlier than 1.6.0.

      The Kernel property can be used to specify the name of one or more SPICE kernel (SPK) files to load. It can be omitted if all required kernel files were listed in the definition of a previously loaded object. Celestia expects the kernel file to reside in an add-on's data directory.

      Frame and BaseFrame are strings that give SPICE names for the frames. The orientation of the SpiceRotation is the orientation of the frame relative to the base frame. If no base frame is specified, the default is eclipj2000. The base frame should be the SPICE equivalent of whatever the BodyFrame of the Celestia object is.

      Beginning and Ending specify the valid time range of the SPICE rotation. If the Beginning and Ending are omitted, the rotation model is assumed to be valid at any time. It is an error to specify Beginning without Ending, and vice versa.

      Period specifies the principal rotation period; it defaults to 0 indicating that the rotation is aperiodic. It is not essential to provide the rotation period; it is only used by Celestia for displaying object information such as sidereal day length.

      Example:

      # Use the frame IAU_EARTH as defined by the constants in the SPICE text kernel pck00008.tpc
      SpiceRotation
      {
          Kernel              "pck00008.tpc"
          Frame               "IAU_EARTH"
          BaseFrame           "eclipj2000"
          Period              23.9344694
      }
      

      • • ==Fly Your Spacecraft, Buddy?==

      One of the not-so-obvious implications of the Scripted methods available in the SSC files of Celestia v1.5.0 (and later) is that objects can now be repositioned at arbitrary coordinates and orientations while Celestia is running.

      In other words, you can fly an interplanetary spacecraft anywhere in a solar system.

      Placement

      The return values of the ScriptedOrbit function are x,y,z in the object's coordinate system.

      Any x, y, z.

      Similarly, ScriptedRotation can return the components of any quaternion.

      You can minimize the complexity of the algorithm to be used in the ScriptedOrbit or ScriptedRotation if you specify appropriate Orbit and Body ReferenceFrames for the object in its SSC file.

      Unfortunately, ScriptedOrbit and ScriptedRotation aren't available in STC files yet. As a result, you're limited to defining movable objects within 1 LY of a Star or Barycenter, since Celestia only draws SSC objects when the viewpoint is within 1LY of the parent Star.

      Communicating with the User

      You still need a way for the user to communicate with ScriptedOrbit to tell it to generate a new x,y,z.

      The ScriptedOrbit and ScriptedRotation modules can't interact directly with the keyboard, mouse or joystick, or with a CELX script, but they can detect the name of the currently selected object by calling celestia:getselection()

      A solution is to define objects with unique names which can be selected by the user or by a script. One possibility is to define DSC OpenCluster objects for this.

      Temporal Anomalies

      In the positioning algorithms you use, you should take into account that the user can set the current time to be an arbitrary value. "Should" is the operative word. It really is no big deal if your algorithms don't work correctly if time runs backward: just be sure to document that limitation.

      • Keeping up Appearances
        • == Introduction ==

      This article describes the most common procedures for installing add-ons for the 3D astronomical visualization program "Celestia". It can be downloaded for free from Celestia. Most add-ons designed for this program can be downloaded from the Celestia Motherlode or Forum. This document does NOT describe how to create new add-ons. If you want to make your own add-ons or modify others, you should start by reading Selden Ball's Not-so Brief Introduction to Add-ons For further information, also see the Documentation Page of the Motherlode.

      If you are new to Celestia, please read this document from start to finish, since information that is relevant to later sections is covered in earlier ones. If you try to read just the section that you want help with right now, you might miss important information that would help with future problems.

      How Celestia determines what to display

      The Celestia application itself is a very small part of the package that you initially download. Most of the size of the package is due to the pictures and catalogs of the celestial objects that Celestia draws. When Celestia launches, it reads the data from a folder on your computer called "Celestia" (Windows systems) or "Celestia Resources" (Macs). It then uses that data to determine what to display. By editing a few files in this folder, you can change what Celestia displays on the screen.

      The Celestia Resources folder is in different places depending on your operating system.

      In Windows, by default it usually is located in C:\Program Files\ and is called "Celestia" (Double-click on My Computer to find it). However, the Celestia installation program will let you specify any directory you want. Windows is very protective of its Program Files directory, making it difficult to modify Celestia's files. Because of this, it's usually a good idea to specify some other directory.

      In Mac OS X, the folder is called "CelestiaResources" and it will be where the person who installed the original Celestia program put it. This is usually in /Users/<your username>/Library/Application Support/ or within the Celestia application bundle. To find it inside the bundle, hold down the {Ctrl} key, click on the Celestia icon and select "Show Package Contents" from the menu that appears.

      In Linux KDE, the folder can be installed anywhere, although /opt/kde3/share/apps/celestia is the default and most likely place. In Ubuntu the directory is /usr/share/celestia.

      Types of add-ons

      Add-ons fall roughly into two broad classes: replacement textures and extras. Since their methods of installation are different, we will deal with them differently.

      Replacement Textures

      If the files you download are nothing more than images, you are dealing with a replacement texture. Celestia supports the following image formats: JPEG, PNG, DDS and BMP. (BMP images should be avoided. Celestia does not implement most of the BMP standard.)

      An add-on containing replacement textures is designed to replace a texture that was included with the default distribution of Celestia that you downloaded. There are two ways to install new textures: by replacing the original image file, or by editing the catalog file that points to the texture, so that it points to your new image file instead.

      Replacing the image file

      Replacing the image file is simple. The tricky part is detailed in the note below about image resolutions.

      Open the textures folder in the Celestia resources folder, find the image file that you want to replace, and remember or write down its exact name. Then rename the original file to something else, like <old-name>-old.jpg. Place the new image file in the same folder as the old one, and re-name it so it matches the original name of the old image (paste the name from the clipboard.) When you relaunch Celestia, you should see the new texture in place of the old one.

      Resolutions

      Celestia allows you to provide images with the same name but with three different resolutions: low, medium and high. They are kept in the lores, medres and hires folders. You can type the letters "r" and "R" to switch among them. These resolution names are just for your convenience, though. There's otherwise nothing special about the images.

      Texture images must be a power-of-two on a side: 512x256, 4096x2048, etc. This restriction is in the design of most 3D graphics cards.

      Editing the catalog file to refer to your new Texture

      Instead of renaming files as above, you can change the catalog file that directs Celestia to the image file you want to replace. For all default textures, these catalog files are in the folder "data" inside the main Celestia resources folder. They are called "ssc" catalog files, and they end in the 3-letter extension (ssc).

      Based on the names of the files, find the one that describes the texture you want to replace. For safekeeping, copy the original catalog file to another name with a different filetype. Then open it with a text editor and scroll down until you see the entry for the object you are trying to improve. The syntax of the catalog file should be understandable. Replace the name of the old texture with the name of your new texture, but don't modify anything else. Save and close the catalog file.

      Place your new texture in the medres folder inside the textures folder inside the Celestia Resources folder.

      When you launch Celestia, you should see the new texture on the object whose catalog entry you edited.

      Extras

      Extras are add-ons which usually cause Celestia to display an object that is not present at all in the default distribution. They usually include several files including catalogs, models, textures, and, hopefully, a README that tells you what to do get the object to display properly. If there is a README included, follow its instructions to install the add-on. If there is no README, you will need to sort the add-on's files by their filetypes (the part of the name that is after the dot).

      Place the files in the following directories (folders) according their filetypes:

      • .cmod or .3ds or .cms -- Place these models in the models directory.
      • .jpg or .png or .dsc or .bmp -- Place these pictures in the textures/medres directory.
      • .ssc or .stc or .dsc -- Place these catalogs in the add-on's main directory.
      • .xyz -- Place these trajectories in the data directory.

      Testing the Add-on

      After you have installed the add-on, you'll need to quit and relaunch Celestia. This is because Celestia only reads the data files when it is launched. Any changes you make will not be apparent until you start Celestia again.

      If you are installing a new object in Celestia, visit the object by pressing the [Return] or [Enter] key to bring up the target entry prompt. As you begin to type the name of the object you want to visit, Celestia will try to guess what object you want. You can press the TAB key to cycle through Celestia's guesses. When the window displays the name you want, press [Return] (or [Enter]) again. If the object's name does not appear in the target entry window, you probably have not installed it correctly.

      The object has now been selected. Press the 'g' key to go to it. Celestia's viewpoint should move toward the object and it should come into view. If the viewpoint changes but an object does not become visible, make sure that rendering for that object is enabled in the Rendering menu. If the proper rendering is enabled, but you still see nothing, it is possible that the object is not defined at the time that Celestia is simulating. This could occur with comet Shoemaker-Levy 9, for example, which crashed into Jupiter during July 1994. Celestia will still take you to a location for objects which no longer exist, but nothing will be displayed. To view the object, set the time to something more appropriate. For Shoemaker-Levy, this would be any date before July 18, 1994.

      If you are installing a different texture for an object that already exists in Celestia, it might be defined in an SSC catalog as an AltTexture. To view such an alternate texture, right-click on the object and select the alternate texture from the popup menu. If you still have trouble getting your new add-on to work, you may want to read its ssc, stc or dsc catalog file for clues to how and where the object should appear in Celestia. Even the smallest error can cause Celestia to function incorrectly, so be careful.

      Error messages often are shown in Celestia's "console log." Type a tilde (~) to toggle the log on and off. The up- and down-arrow keys can be used to navigate within it.

      • • ==Introduction==

      The appearance of any object we see is determined in large part by the light that reaches your eye from each point on the object's surface. It is affected by the characteristics of the light reflected from the surface, the coloration of the surface, and any intervening translucent media (such as an atmosphere). Celestia uses mathematical models to calculate these effects, manipulating data which describe the relevant characteristics of each light source, and each point on the surface of each illuminated object. In reality, that's an enormous amount of data, and for Celestia compromises must be made.

      In many cases, Celestia uses images as "maps" to provide the needed information describing the characteristics of the object's surface. Each point on a map corresponds to a point on the surface. Celestia uses image files to determine how the corresponding point on the surface of the object should appear. This process is called texture mapping. If you see an analogy here with the kinds of maps you're familiar with from school, it's no coincidence. The term map is used here with something very close to its conventional meaning.

      The term texture may seem a bit puzzling in this context. It comes from the original usage of the technique in early computer graphics. At that time, because of hardware limitations, only very small images could be used, and so they could cover only a very small part of the surface of an object. However, a single small image could be used repeatedly to cover a large area of an object, giving it a textured appearance. Celestia generally uses a single texture image to cover the entire surface of an object, some of which are the size of planets. Technology has come a long way!

      Image basics

      Concepts

      Since texture mapping relies on image data, we'll begin with a brief review of basic image concepts. A digital image is essentially a rectangular grid of cells, called pixels (short for "picture element"). Each pixel has a specific digital value. The pixel values are commonly used to represent colors, but can be used for any kind of information. The number of possible values which any pixel can have is called the "depth" of the image. The depth of an image is usually expressed as a number of bits. The more bits provided, the greater the precision of the data representation. The (spatial) resolution of an image is determined by the number of rows and columns of pixels it contains. The more rows and columns, the higher the resolution of the image. Unfortunately, the more rows and columns of pixels, and the more bits per pixel, the greater the amount of storage needed for the image. Image file formats often include compression techniques to reduce the storage requirements, but this can lead to a loss of information, resulting in reduced quality.

      Artistic development of textures

      Since textures actually are pictures, you can use your favorite paint program to create them. Often public domain photographs by NASA can be used as starting points for surface textures of imaginary planets.

      Preserving quality

      It's usually best to work at a resolution that's at least twice the resolution that you'll be providing in an Addon. When scaled down, the results look much better than if you'd been working at the final resolution. Also, be sure to save your intermediate results using an image format that preserves the detail. Do not use either DDS or JPEG formats for anything other than the final released product.

      Texture File Formats

      Celestia supports three image file formats for textures: PNG , JPEG and DDS. Because of their differing characteristics, the different file formats are more suitable for some applications than others.

      PNG

      PNG, short for Portable Network Graphics, is a lossless compression format, i.e. it reproduces the original image without change. PNG images can contain an 8-bit alpha layer, which is used to determine where the image is transparent (think of a cloud-layer). Because it offers perfect quality and alpha layer, PNG can be used for all purposes in Celestia. However it typically has the biggest filesizes and may be a bad choice for textures offered for download. PNG is supported by all but the oldest image manipulation programs.

      JPEG

      JPEG (initials of Joint Photographic Experts Group, often shortened to JPG) is designed for a good visual appearance and a high compression ratio. It introduces small differences compared to the original image, but this is rarely visible when using default or better quality when saving the JPEG image. The JPEG format is well suited for surface textures, especially when the filesize has to be kept small, as for downloads. JPEG is supported by practically all image manipulation programs. Unfortunately, JPEG does not support an alpha channel, so it cannot be used for textures that require transparency.

      DDS

      DDS, short for Direct Draw Surface, supports several different specialized formats. Most relevant for Celestia are DXT1, DXT3 and DXT5. DDS is different from JPEG and PNG in several ways, as it's not a format typically used to store pictures. Instead it's designed to be used by 3D hardware, and is directly loaded into your graphics card. Very old graphic cards don't support DDS textures, so not everybody can use them. In some circumstances, DDS can have the worst quality of the supported image formats, considerably worse than JPEG with default compression. It also is not highly compressed, e.g. 1:6 for DXT1.

      Why is it used then? Because the compression of DDS textures also works after the image was loaded. Let's take a 2048x1024 image as an example. When stored as PNG or JPEG, an image may take little space on the harddisk (200 kB for JPEG, 1-2 MB for PNG), but once loaded into memory, it would expand to width*height*3 Bytes = 6MB. A DDS image will take only 1/6th of this, on disk as well as in memory. So you can use more or higher-resolution textures without hurting performance. Furthermore, DDS images don't have to be decompressed by the CPU, so loading is considerably faster too. This is very important when approaching planets which haven't had their textures loaded yet, and for Virtual Textures.

      Because of their relatively low quality and the kind of artifacts the compression causes, DDS textures are generally unsuited for Normalmaps. Nevertheless, a specialized NormalMap format has been defined by Nvidia which uses a special DXT5 encoding. Celestia calls this format DXT5nm.

      A DDS file usually includes several texture images, called "mipmaps". They are progressively lower-resolution versions of the primary image, automatically created by the software used to create DDS file. The graphics hardware chooses the mipmap that best fits the size of the object on the screen, minimizing the number of pixels that have to be rescaled and thus improving the graphics frame-rate.

      (additional details of the DXT formats is needed here)

      DXT1

      DXT3

      DXT5

      Celestia Texture Map Types

      The following are some of the different types of texture maps used by Celestia:

      Surface Texture Maps

      A Texture is like a photograph of the surface, looking much like a conventional map of the world. If the image file used as surface texture contains an Alpha layer (usually used to indicate transparency), this layer is used by Celestia as the object's specular texture map.

      Specular Texture Maps

      A JPG, PNG or DDS SpecularTexture controls which parts of a planetary surface seem to be shiny and which do not by causing a bright highlight to be drawn. In the texture image, white indicates areas which will display a highlight. Black indicates areas with no highlights. It can be very effective in showing a watery surface on an Oceanic planet.

      When using a SpecularTexture, both SpecularColor and SpecularPower must also be specified. See the chapter on SSC Catalog files for more information.

      Specular reflection highlights are visible only in Celestia's OpenGL Vertex Program and OpenGL 2.0 render paths. The graphics hardware must support OpenGL v1.4 or better.

      Normal Texture Maps

      A NormalMap is not "normal" in the sense of being a conventional map. Rather, it defines surface normal vectors: it contains information about the slope of the surface at each point in the texture image. This makes it possible for Celestia to draw shadows on what actually is a smooth surface, making it look like it contains bumps and creases due to mountains and valleys. This usually is much easier than actually molding craters and mountains into the model.

      Shadows drawn by NormalMaps are visible only in Celestia's OpenGL Vertex Program and OpenGL 2.0 render paths.

      Tools for creating these normal maps are available on the Celestial Matters Website.

      Bump Maps

      A BumpMap is an alternative to a NormalMap. It specifies the relative heights of positions on the surface of an object. A pixel corresponding to a position which has the highest altitude is colored white, while the lowest is black. BumpMaps often are created from heightmaps. Internally, Celestia translates BumpMaps into NormalMaps.

      When a BumpMap is used, BumpHeight must also be specified.

      Shadows drawn by BumpMaps are visible only in Celestia's OpenGL Vertex Program and OpenGL 2.0 render paths.

      Also keep in mind that a black & white copy of a texture is NOT a bump map and should not be used as one. Bump maps contain height or altitude data, while a texture is a "photo" with shadows caused by the sun.

      For more information, see:

      • http://en.wikipedia.org/wiki/Bumpmap
      • http://en.wikipedia.org/wiki/Normal_mapping

      Cloud Layer Texture Maps

      A CloudMap is a transparent, or semi-transparent image drawn above the surface Texture, used to render clouds. A Cloudmap must be in either png or dds (dtx3 or dxt5) format with an Alpha channel to provide its transparency. In an SSC catalog file (the properties declaration for the object), one can define the cloud´s height above ground, and the speed at which the clouds move relative to the Surface Texture.

      If the CloudMap is a Virtual Texture, CloudSpeed must be 0, or the image will appear to be broken.

      Cloud Layer Normal Maps

      This feature requires Celestia v1.5.0 or later.

      A CloudNormalMap adds shadows to the surface of a cloud image, making it appear to be bumpy.

      Night Light Texture Maps

      A NightTexture shows what the nightside of an object looks like, with lighted areas caused by cities, erupting volcanoes, forest fires, etc. It should include an Alpha channel to allow the surface Texture map to be seen through the NightTexture, but that isn't required.

      Texture resolution

      The (spatial) resolution of a texture image is determined by the number of rows and columns of pixels it contains. The more rows and column, the higher the resolution of the image. Most importantly, the higher the resolution of the texture, the more detail it contains, and the closer the distance you can view it from. If you view a texture too closely, it will appear blurry because it does not contain sufficient detail. The higher the resolution of the texture, the closer you can get with a clear view, and the more detail you can see. If a texture is mapped to a planet's surface, the size of the planet together with the resolution of the texture determines how close you can view the planet from with a satisfactory view. A larger planet will require a higher-resolution image to provide comparable detail at the same viewing distance.

      As many as three images with identical names but different resolutions can be used for textures if they're put into the subdirectories textures/lores, textures/medres and textures/hires. The keyboard commands "r" and "R" can then be used to select among them.

      It is common to refer to the texture resolution as 1k, 2k, 4k, 8k et cetera.

      What this means is:

      - a 1k texture has a width of 1024 pixels and a height of 512 pixels

      - a 2k texture is 2048 x 1024 pixels

      - a 4k texture is 4096 x 2048 pixels

      ... And so on.

      Any texture used in Celestia must be a power of two on each side, like the dimensions shown in the above example. This restriction is lifted in Celestia v1.5.0, but works best with graphics cards which support "non-power-of-two" texture sizes. Celestia will shrink textures to fit into cards that don't have that feature, possibly damaging the image significantly.

      When a texture becomes very large, it can be advantageous to cut it up into smaller parts, thus creating a Virtual Texture - this economizes on the memory Celestia needs to draw it.

      Virtual Textures

      A virtual texture is a special texture format used by Celestia to handle very large textures. It is made up of many little textures showing the small details on planets, moons etc.

      There are different levels to a virtual texture. The levels are numbered 0 to 10 (12 for v1.4.0 and later). Level 10 is for very fine details and Level 0 is pretty much a global view showing all the major features of Celestia's worlds. Level 0 is made up of 2 images, Level 10 can be made up of thousands of close-up images showing great detail.

      A ctx file defines the virtual texture and its filename is used when referring to the virtual texture in ssc files.

      For the details of creating a Virtual Texture, see the documentation on the Celestia MotherLode.

      • • ==Introduction==

      In addition to its internally defined spherical objects, Celestia can use 3D models to display bodies with complicated shapes.

      Usage in Celestia

      A 3D model will be displayed when Celestia encounters the Mesh directive in one of its catalog files. For example,

      Mesh "file.3ds"
      

      If a Texture declaration is included in the entry for the same object, that texture image will replace all diffuse material texture images specified in the model file.

      Model Types

      Celestia can display three different types of 3D model files.

      3DS

      Originally developed by the authors of 3D Studio Max, the .3DS binary file format is used by many different software packages. Model files usually can be created in this format by choosing it in the "Export" menu of your favorite 3D modeling program.

      CMS

      CMS Model Files are unique to Celestia. They use a simple textual format. The CMS format is deprecated.

      CMOD

      CMOD Model Files are unique to Celestia. They have both binary and textual forms. The format was designed for efficient use by OpenGL code. When drawing a CMOD model, Celestia's framerate is about 1.5-2x as fast as when drawing the equivalent 3DS model.

      A 3DS to CMOD conversion program is available. CMOD export scripts are available for Anim8or and Blender.

      Modeling Programs

      • Blender 3D - this is an open-source, free software that is extremely powerful. However, it is quite intimidating to use for beginners. Blender 3D: Noob to Pro is a Wikibook that has good guides to help you, if needed. Note: as of version 2.80, Blender no longer supports exporting 3DS models.
      • Anim8or - free modelling software. This is only available for Windows, however.

      Modeling Hints

      Limitations

      1. 3DS models have a limit of 65536 vertices and polygons, making extremely high-resolution models impossible. This limitation, however, does not exist for CMOD models.
      2. Models in Celestia do not (yet?) cast shadows on themselves or on other objects.
      3. Translucent model surfaces are not properly depth sorted. Some are drawn correctly, but some are not.
      4. DSC Nebula Meshes are not depth sorted at all. They always are drawn in the order that Celestia reads them.
      • • • Celestia/Celestia/3D Models/CMS File
          • [[Celestia/3D Models/CMOD File| CMOD models}}
      • Specifying the Correct Time: TDB is not UTC
        • == UTC vs TDB ==

      Versions of Celestia before v1.5.0 use UTC to calculate times and positions. Unfortunately, UTC includes "leap seconds" in order to stay aligned with the Earth's varying rotation. Leap seconds happen essentially randomly, when they are needed. Although Celestia does incorporate a table of leap second times, its use of UTC causes problems when used with ephemerides which are defined using TDB. Starting with v1.5.0, although it still displays UTC on the screen, Celestia uses the TDB time scale internally for everything else. As a result, Celestia places objects much more accurately than before.

      Time Scales

      It may be helpful for Celestia users to understand the various time scales that are used in the field of astronomy. The most familiar is local time, which is probably what you see if you look at a nearby clock. The local time zone determines the difference between local time and Coordinated Universal Time, or UTC. UTC is the current time at the zero degree meridian; it replaces Greenwich Mean Time as the standard world clock.

      Astronomical ephemerides are typically defined in terms of Barycentric Dynamical Time, or TDB. TDB is the time measured by a clock at the solar system barycenter. It differs from Terrestrial Time (TT)--the time measured by a clock on the Earth--because of relativistic effects, but the difference between the two scales is always less than 0.002 seconds. The two scales can usually be considered equivalent in Celestia.

      TT is ahead of International Atomic Time (TAI) by constant value of 32.184 seconds. Finally, UTC differs from TAI by some integer number of leap seconds. Leap seconds are inserted occasionally because the Earth's rotation is irregular, and it's desirable to keep our everyday time scale from drifting with respect to the terrestrial day-night cycle--except at the poles, the sun should be in the sky at noon. The most recent leap second occurred at 23:59:60 on December 31, 2016 and made UTC 37 seconds behind TAI. (See Wikipedia on TAI)

      To briefly summarize the relationship between time scales:

      TT = TAI + 32.184
      TAI = UTC + leap second count
      Thus, TT = UTC + 32.184 + leap second count
      

      UTC is used in the Celestia's Set Time dialog and it's also the time displayed in the upper right of the screen. Unless you're creating scripts or add-ons for Celestia, UTC is all that you will see. But everywhere else, the time scale is TDB: xyz trajectory files, attitude files, beginning, ending, and epoch times in .ssc files.

      Troubleshooting

      • Celestia/Celestia/Troubleshooting Celestia
      • Troubleshooting Scripts
        • Celestia/Celestia/Celx Scripting/Development Suggestions
      • Celestia/Celestia/Troubleshooting Addons

      Development

      • Celestia's source code is freely available on GitHub. Only official Celestia developers can upload modified code to the GitHub server, but anyone can download the code and modify it for their own purposes. If you would like to contribute code to the project, please discuss it on the Celestia Web Forum in its Celestia Development Forum.

        A sociological comment:

        As with most software projects with established developer communities and protocols, a potential contributor to Celestia will have to undergo a form of apprenticeship. The program is large and complex and its underlying design philosophy has to be understood. It also takes a while to gain the trust of the people currently working on the program. By themselves, programming skills aren't enough. Too often individuals unfamiliar with the program or with the people involved have suggested significant changes and have become discouraged because their ideas weren't incorporated immediately. Don't let this happen to you. Read the forum. Read the developers mailing list. Participate in discussions. Contribute ideas. Try out things with the code on your own. Be patient. It'll take a while.

        The following sections describe how to obtain the code and modify it for specific operating systems.

        • GNU/Linux and *BSD
        • macOS
        • Windows
          • ==Getting source from git==

        Use your favorite git client program to download Celestia from GitHub. If you're using the command line git client, use the following command line to update your local Celestia development directory:

        git clone https://github.com/CelestiaProject/Celestia.git
        

        The target directory is Celestia

        Basic installation steps

        First, change directory with "cd Celestia" and follow the instructions on page https://github.com/CelestiaProject/Celestia/blob/master/INSTALL.md

        • • ==Install XCode Tools==

        If you've not already done so, install Xcode 10 from Apple.

        GitHub

        Before compiling Celestia, you must obtain the source code. The very latest source code is kept in Celestia's GitHub repository. You can get the source code by following these instructions:

        1. Open Terminal
        2. See if Git is installed on your system. Type "git" in the terminal (without the quotes.) If you get a "command not found" error message, you need to install Git. See this guide for information on installing Git on Mac OS X.
        3. Type, or paste in: git clone https://github.com/CelestiaProject/Celestia.git
        4. Wait for a while, until the download is complete.
        5. cd Celestia and follow instructions from https://github.com/CelestiaProject/Celestia/blob/master/INSTALL.md
        • • Celestia development options using Windows-32 software packages:

        Subversion (svn)

        Celestia's source code is available on a Subversion (SVN) repository hosted on SourceForge.

        Several Subversion clients are available for Windows. A very popular one is TortoiseSVN, a Windows shell extension that lets you use SVN commands right from Windows Explorer. A command line version is available with Cygwin.

        To get the latest Celestia source using the command line client, cd to the desired directory and then issue the command

        svn co https://celestia.svn.sourceforge.net/svnroot/celestia/trunk
        

        With Tortoise SVN, select 'Checkout' from the Windows Explorer popup menu, and then enter this URL:

        https://celestia.svn.sourceforge.net/svnroot/celestia/trunk
        

        Microsoft C++ & SDK tools for Windows XP and Windows 7

        In order to build software for Windows, you need both an SDK (Software Development Kit) and a compiler. The SDK provides libraries and include files needed for building for a particular version of Windows. The compiler converts text files into binary programs, linking them to the SDK libraries. Microsoft provides free versions of their SDKs and compilers, although with limited features, in order to encourage development of software for use with their operating systems. They also sell enhanced versions for use by commercial software development organizations.

        VS2010

        Currently, there is no Visual Studio 2010 solution checked into the subversion repository. If you have VS2010, you will have several unsupported steps to perform, in addition to the steps outlined for previous versions of Visual Studio.

        • First, VS2010 will convert the previous version's project files into VS2010 format. These converted versions will have mismatching $(TargetFile) and linker output file definitions. These will have to be manually reconciled. One choice is to set the General project property "Target Name" to "$(ProjectName)" and the linker property "Output File" to "$(OutDir)$(TargetName)$(TargetExt)". This will allow you to build, but it will not run.
        • Second, and most significantly, the static libraries zlib and libpng in the repository are compiled to work only with the redistributable runtime dlls for VS2008, namely msvcm90.dll, msvcp90.dll and msvcr90.dll. These runtimes are incompatible with VS2010, so you will have to obtain zlib and libpng (and the debug versions) that will run with 2010. The easiest way to do this may be to grab the sources from sourceforge, build them yourself, put the new libs in windows\lib\x86, and change the entries in the linker's "Additional Dependencies" property.
        • Finally, you must ensure that the celestia.exe and the dlls in windows\dll are copied into $(ProjectDir), and that the Debugging "Command" property is set to "$(ProjectDir)\$(TargetFileName)" and the "Working Directory" property is set to $(ProjectDir).

        There may be other steps to perform, depending upon the versions of zlib and libpng that you obtain.

        VS2008

        In December 2007, Microsoft released Visual C++ 2008 Express Edition. As of Celestia version 1.6.0, this is the only version of the compiler recommended for building Celestia. Note that Visual C++ 2008 will not run on Windows 98. For this reason only, you may want to use Visual Studio 2005. If you have Windows 2000, XP, Vista or 7, compiling is much easier with Visual C++ 2008.

        • If you do not already have Microsoft Visual C++ 2008, you may download it for free from here:

        http://msdn.microsoft.com/en-us/express/future/bb421473

        When installing VS C++ 2008 SP1 using the Web installation , it automatically downloads and installs all of the correct SDK libraries, too. This happens under both Windows XP, 32bit, and Windows 7, 64bit. The SDK does not need to be downloaded or installed separately.

        • If you also need the Windows SDK, it is a free download from Microsoft:

        http://www.microsoft.com/downloads/details.aspx?FamilyId=E6E1C3DF-A74F-4207-8586-711EBE331CDC&displaylang=en

        Step by step instructions for Visual C++ 2008 Express Edition

        These instructions work for both Windows XP and Windows 7.

        This process assumes that you've followed the steps above, checked out the source from SVN, and installed the Visual C++ compiler and Windows SDK.

        1. Copy iconv.dll, intl.dll and lua5.1.dll from trunk\celestia\windows\dll\x86 into trunk\celestia
           • Celestia is a 32bit x86 application. There are no x64 libraries.
        2. Open celestia.sln in Microsoft Visual C++.Net 2008 and allow the updater to work.
           • In other words, select (double-click on) celestia.sln in the directory trunk\celestia
        3. Set the build type to "Release". (The project provided from svn has it set to "Debug")
           • Specifically, in the line of icons across the top of the VisualStudio window, where it initially says "Debug", open its dropdown menu and select "Release"
        4. Build!
           • Open the menu "Build" and select "Rebuild Solution"

        VS2005

        Recommended only for users of Windows 98/ME, where the Visual C++ 2008 is not supported. If you are running XP, Vista or 7, you should use the much easier process described in the previous section.

        • Windows Platform SDK: Web Install

        http://www.microsoft.com/downloads/details.aspx?familyid=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en

        • Windows Platform SDK: disk image

        http://www.microsoft.com/downloads/details.aspx?FamilyID=e15438ac-60be-41bd-aa14-7f1e0f19ca0d&DisplayLang=en

        • Visual Studio 2005 Express C++: Web install

        http://www.microsoft.com/express/2005/download/default.aspx

        • Visual Studio 2005 Express C++: disk image

        http://msdn2.microsoft.com/en-us/express/aa718401.aspx

        Celestia libraries for VS2005

        The libraries in the Celestia repository were built with VS2008, and will not work on Windows 98/ME:

        Celestia Libraries for Visual Studio 2005 Express:

        http://www.shatters.net/~claurel/celestia/winbuild/

        • As of October, 2007, use
          • cspice.lib
          • winbuild-2.zip
          • winlibs-2.zip

        Several source code files have been added to Celestia's svn repository since winbuild-2.zip was created. Insert these lines into the OBJS section of celestia/src/celengine/engine.mak if you're using makerelease.bat to build from the current subversion repository:

               $(INTDIR)\axisarrow.obj \
               $(INTDIR)\customrotation.obj \
               $(INTDIR)\frametree.obj \
               $(INTDIR)\precession.obj \
               $(INTDIR)\scriptrotation.obj \ 
               $(INTDIR)\timeline.obj \
               $(INTDIR)\timelinephase.obj \
        

        The SPICE include files are included in winlibs-2.zip.

        No binary DLLs (Dynamically Loaded Libraries) are included in these Zip files, so you'll have to get them from one of the precompiled Celestia installation kits. As of January 26, 2008, use the DLLs which are included in Celestia v1.5.0. The official release of Celestia v1.5.0 is available on SourceForge.

        
        The version of Celestia that's included in the Windows Celestia distribution kits is compiled using the script makerelease.bat. The older VS2003 versions of the build scripts are still what are in the cvs archive on SourceForge. The makefiles and .bat scripts which have been updated for VS2005/VS2008 are included in winbuild-2.zip [Remark: There is no makerelease.bat in winbuild-2.zip], which is in the VS2005 winbuild directory shown above.

        Don't forget that you'll have to configure the PATH, LIB and INCLUDE environment variables according to your particular development environment so that the build scripts will find the Visual Studio and Celestia programs, include files and libraries.

        Here's one example .BAT script for defining the search lists. It probably won't work for you: you probably have put the files in different directories. Change it appropriately.

        Set INCLUDE=C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\include;%INCLUDE%
        Set INCLUDE=C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\include\mfc;%INCLUDE%
        Set INCLUDE=C:\Program Files\Microsoft Visual Studio 8\VC\include;%INCLUDE%
        Set INCLUDE=C:\cvs\Celestia\celestia\inc;%INCLUDE%
        
        Set PATH=C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Bin;%PATH%
        Set PATH=C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;%PATH%
        Set PATH=C:\Program Files\Microsoft Visual Studio 8\VC\bin;%PATH%
        
        Set LIB=C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib;%LIB%
        Set LIB=C:\Program Files\Microsoft Visual Studio 8\VC\lib;%LIB%
        Set LIB=C:\cvs\Celestia\celestia\lib;%LIB% 
        

        • • Celestia/Development/Windows Vista platform
        • This page is obsolete. For current information, see Ideas for post 1.7 era on GitHub.

        Here's a development roadmap for Celestia (as of 6/22/07), with tasks roughly prioritized highest first.

        Celestia 1.5.0pre3

        • Don't require LuaHook for scripted orbits and rotations
        • Fix cloud shadows
        • ASAP

        Celestia v1.5.0pre3 for Windows was made available on May 24, 2007. A list of the accumulated changes and the location for downloading the Windows installer are at https://celestiaproject.space/forum/viewtopic.php?t=11082&

        Celestia 1.5.0pre4

        • Changes to standard data files:
          • new Eros model
          • new ISS and Mir models
          • new Itokawa model
        • Fix stars
        • Allow star orbits to be toggled separately from planet orbits
        • Eliminate OrbitBarycenter
        • Adjust near clip plane for FOV (to preserve depth buffer precision)
        • Don't show labels for star system barycenters
        • Fix SSC texture override for meshes

        Celestia v1.5.0pre4 for Windows was made available on October 29, 2007. Not all of the hoped-for improvements were included, but many bugs were fixed. A list of the accumulated changes and the location for downloading the Windows installer are at https://celestiaproject.space/forum/viewtopic.php?t=11605&

        Celestia 1.5.0pre5

        Celestia v1.5.0pre5 for Windows was made available on December 18, 2007. Not all of the hoped-for improvements were included, but many bugs were fixed. A list of the accumulated changes and the location for downloading the Windows installer are at https://celestiaproject.space/forum/viewtopic.php?t=11807

        Celestia 1.5.0pre6

        Celestia v1.5.0pre6 for Windows was made available on January 21, 2008. Not all of the hoped-for improvements were included, but many bugs were fixed. A list of the accumulated changes and the location for downloading the Windows installer are at https://celestiaproject.space/forum/viewtopic.php?t=11932

        Celestia 1.5.0 final

        Celestia v1.5.0 for Windows and MacOS X, as well as a tarball of its source code, was made available on January 26, 2008. It can be downloaded from SourceForge.

        Not all of the hoped-for improvements listed below were included, but many bugs were fixed. A list of the accumulated changes is available at https://celestiaproject.space/forum/viewtopic.php?t=11953

        • Changes to standard data files:
          • Switch to new rotation model forms
        • Atmospheres
          • Make dense atmospheres work better
          • Fix artifacts from linear interpolation across triangles
          • Fix too-dark sky at zenith
          • Automatic conversion of new style atmosphere parameters to old ones
        • Default body frame is based on parent, not center of orbit frame; is this right?
        • Fix depth sorting of labels

        Celestia 1.5.1

        Change of plans: Celestia v1.5.1 will be strictly a bug-fix release, plus translations which were not included in v1.5.0. Features listed below which weren't in v1.5.0 will be included in v1.6.0.

        • Script function to show / hide individual objects
        • Script menu Already completed for 1.5.0
        • Make quaternion slerp more robust Already completed for 1.5.0
        • Double precision SampledOrbits Already completed for 1.5.0
        • Pulsar catalog?
        • Triaxial ellipsoids for solar system bodies
        • Fix multiple star handling in star database builder
        • Bug fixing

        Celestia v1.5.1 for Windows and MacOS X was made available on May 5, 2008. It can be downloaded from SourceForge.

        Celestia 1.6.0

        For a more up-to-date list of features considered or implemented for Celestia v1.6.0, see the WikiPage Celestia/160Features.

        • User-definable object classes
        • Orbits:
          • More flexible means to choose which orbits to display (custom classes)
        • Allow orbits to be shown in any reference frame
        • Script:
          • Functions to deal with object classes
          • Expose 1.5.0 reference frames in scripts
          • Vector and orientation parameters for ScriptedOrbits and ScriptedRotations
        • Markers:
          • Labeled markers
          • Allow different reference frames for markers
        • Texture improvements:
          • Use lower resolution virtual texture tiles for surface patches farther from camera
          • Improve texture memory management
          • Multi-threaded texture loader
          • Optimize galaxy rendering: point sprites, vertex buffers instead of immediate mode.
        • SPICE
          • Allow lists of kernel files
          • Manage loaded kernels
          • C-kernel rotation model
          • Generic frame rotation model
        • Goto fixes:
          • Fix center orbit (currently assumes infinitely distant target)
          • Goto barycenter should pick a distance based on size of the orbits around the barycenter.
        • SampledOrbit / SampledOrientation:
          • Periodic SampledOrbits
          • Support cubic interpolation of SampledOrientation files
        • New Earth rotation CustomRotations--precession, nutation, IRTF93
        • Internal changes:
          • Implement velocity method for all orbit types
          • Change internal time scale to be Julian days relative to J2000.0
          • Use J2000 ecliptic coordinate system throughout Celestia
          • CachingRotation base class
        • More accurate lunar orbit
        • Depth sort location labels (new drawable type: label cluster)
        • New data:
          • Create model for comet Tempel 1
          • Create model for asteroid (66391) 1999 KW₄ and its moon
        • Eliminate the .cms format

        Celestia v1.6.0 for Windows and MacOS X, as well as a tarball of its source code, was made available on July 9, 2009. It can be downloaded from SourceForge.

        Celestia 1.7.0

        • Spacecraft fly mode
        • Network Server Separated
        • Dynamic milky way model
        • Earth, Moon, Saturn Ring Details
        • Support Collada (.dae)
        • Dynamic loading and unloading of add-ons
        • Make add-ons easier to install
        • Multiple names for solar system objects (done)
        • For stars, do antialiased points in shader
        • 3D graphic objects in scripts
        • Reference frames
          • Named frames
          • Rotation offset frames
          • Two-vector frames: closest point vectors
        • Self shadowing for complex objects
        • Address 16k light year limit (done)
        • Supernova catalog?

        Celestia 2.0

        • High dynamic range lighting - photorealism
        • Light scattering model for rings
        • Major UI improvements
        • Advance Visual effects
          • == Triaxial ellipsoids for solar system bodies ==

        SourceForge feature tracker item 1662019

        Code change, plus catalog updates. Code change is complete, but some discussion of specifics required before checkin.

        How should triaxial ellipsoids be specified? For stars, we specify the shape with SemiAxes [ x y z ] and this is multiplied by the radius. But this is slightly inconvenient for planets, where we'd like to be able to simply write:

        Mimas
        {
            SemiAxes [ 209.1 196.2 191.4 ]
        }
        

        However, it would be unfortunate to have star and planet sizes specified in different ways. We could have things both ways with a slightly more complex definition of how the Radius and SemiAxes interact:

        • SemiAxes specified, no Radius given: body semiaxes are (sa.x, sa.y, sa.z)
        • Radius specified, no SemiAxes given: body semiaxes are (r, r, r)
        • Both SemiAxes and Radius specified: body semiaxes are (r*sa.x, r*sa.y, r*sa.z)

        The order of the semiaxes for stars mismatches the coordinate system used elsewhere in ssc files--the y and z axes are switched, matching Celestia's internal coordinate system. Rather than copying this for planets, it may be a better idea to just change how stars work.

        Planet and satellite shapes from the IAU/IAG Working Group (WG) on Cartographic Coordinates and Rotational Elements

        Presumably stars would then behave as if they always had a Radius definition, from the blackbody calculation? Ajtribick (talk)

        Yes, that's what I was thinking: even if the radius is omitted in the stc file, a star always has an implicit radius based on the blackbody calculation. Does this seem sensible to you? --Claurel (talk) 01:07, 25 January 2008 (UTC)

        Implemented in revision 4077 --Claurel (talk) 07:16, 4 February 2008 (UTC)

        Coordinate display

        I think that these should all be considered together, not as separate features:

        • Observer position coordinates
        • Apparent RA/Dec
        • New coordinate grids
        • Ecliptic
        • Geodetic coordinates (instead of geocentric latitude/longitude)
        • Galactic coordinates

        One idea that came out of the RA/Dec discussion on the dev list is the need to show observer coordinates. I think that this is true whether or not they're needed to make sense of the position of the selection. At present, Celestia shows the observer's reference frame (followed object and target object, follow/sync orbit/chase/phase lock) and the speed within the reference frame. Showing velocity but not position seems like a serious omission! The observer position could be shown as either rectangular coordinates or spherical (longitude, latitude, altitude) relative to the center of the observer frame.

        Change HUD text

        There's some data on shown in the 3D view that really doesnt belong there: temperature, day length, rotation rate. These are either derived from potentially unreliable data, not interesting enough to merit using up space in the 3D view, or both. While I think that it is still worth showing this information, I believe that it should be displayed on an information panel in the GUI, where the data can be accompanied by some explanatory text.

        I believe that we when deciding what information goes in the 3D view, we should prefer values that are observer-dependent, such as distance and apparent size. There's an easy to grasp logic in showing observer-dependent value in the observer's view. There's a small practical consequence: observer dependent values tend to change every single frame, so it's convenient to show them in the view that gets refreshed every frame anyhow. There are some observer independent values fundamental enough that they belong in the HUD:

        • Object type (star, galaxy, planet, etc.)
        • Spectral type and absolute magnitude for stars
        • Hubble type for galaxies
        • Radius for planets/moons/asteroids; triaxial dimensions when appropriate

        Observer dependent values for all objects:

        • Distance
        • Apparent size (when non-negligible, > 0.1 arcsec)
        • Apparent coordinates

        For planets:

        • Phase angle

        Values that should be removed from the HUD:

        • Solar system bodies: temperature, day length
        • Stars: luminosity, surface temperature, presence of planets, rotation rate

        "Day length" as shown for planets is rather misleading. It actually shows the sidereal rotation rate, whereas 'day length' without any qualifiers is typically understood to mean the length of the solar day.

        
        Phase angle is now displayed for solar system bodies. --Claurel (talk) 16:47, 16 July 2008 (UTC)

        Add Vincent's compass

        A possible enhancement would be to add a mark that shows the direction of the currently selected object.

        Deferred until after 1.6.0 --Claurel (talk) 01:00, 2 October 2008 (UTC)

        Show/hide for objects

        Implemented, revision 4081 --Claurel (talk) 07:14, 4 February 2008 (UTC)

        Clickable/unclickable setting for objects

        SourceForge feature tracker item 371302

        (as requested by Martin and others)

        Implemented in revision 4073 --Claurel (talk) 19:35, 27 February 2008 (UTC)

        New solar system body classes

        • minormoon
        • surfacefeature
        • component
        • diffuse

        Classifying small moons as minor will let us get rid of the clutter of small moon orbits around the giant planets except in those rare cases when someone actually wants to look at them.

        feature and component give more options for classifying objects. In addition, objects of this class will never be rendered as star-like discs at a distance.

        Possibly want a dwarfplanet class too.

        The diffuse class would be used for objects like dust plumes and gas clouds.

        Default properties for the various classes are as shown in the table below.

                       Planet  Moon  Spacecraft  Component  Invisible  Diffuse
        Visible         yes     Yes    Yes         Yes        No         Yes
        VisibleAsPoint  yes     Yes    Yes         No         No         No
        Clickable       yes     Yes    Yes         Yes        No         No(?)
        Planetshine     yes     Yes    No          No         No         No
        

        Surfacefeature and component implemented in revision 4077 --Claurel (talk) 07:12, 4 February 2008 (UTC)

        "Minormoon and diffuse implemented in revision 4273" --Claurel (talk) 19:07, 14 April 2008 (UTC)

        Lighting from secondary sources

        For example, Earthshine, ring shine - what about spherical harmonics for approximating global illumination?

        Implemented, but not yet committed to SVN. Still need to properly consider phase when calculating amount of reflected light. --Claurel (talk) 17:24, 20 March 2008 (UTC)

        Planetshine implemented completely in revision 4237 --216.231.48.102 (talk) 18:12, 3 April 2008 (UTC)

        More high-resolution textures

        • Earth
        • Mars
        • Galilean satellites
        • More Saturnian satellites

        Possible official packages for these downloaded separately from the main package to save bandwidth?

        Data file updates

        • Add Andrew's CHARM2 catalog of measured stellar radii
        • Add Selden's pulsar catalog

        I haven't updated it in a while and have misplaced the program used to generate it :( Martin (Cham) did a more recent translation from the ATNF Web site. ... Selden (talk) 12:41, 23 January 2008 (UTC)

        CHARM2 catalog committed by Andrew, SVN revision 4462 --Claurel (talk) 01:02, 2 October 2008 (UTC)

        Model updates

        • Add Itokawa model
        • Add improved Eros model
        • Add improved ISS model

        Add depth sorting for markers

        Allow some markers to be marked as 'always in foreground'

        Implemented in revision 4119 --Claurel (talk) 00:34, 14 February 2008 (UTC)

        Make Modify work for star catalogs

        Feature tracker request from ajtribick

        Implemented in SVN revision 4416; Add and Replace dispositions added for consistency with ssc files. --Claurel (talk) 01:04, 2 October 2008 (UTC)

        Reference frame work

        (mostly internal stuff):

        • Clean up frame code; rewrite old frames ("Follow", "Sync Orbit", etc.) in terms of 1.5.0 frames.
        • Expose 1.5.0 frames in celx scripting.
        • Improve reference frame performance through caching
        • Implement reference frame hierarchy for solar system objects; use this frame hierarchy in the renderer and solar system browser.
        • Implement velocity methods for orbits

        In progress. Main cleanup completed, velocity methods and caching improvements being tested. --Claurel (talk) 00:39, 14 February 2008 (UTC)

        Implemented. More velocity methods still needed for orbits. Decided to continue using the namespace hierarchy in solar system browser, because the frame hierarchy changes over times. --Claurel (talk) 01:24, 24 February 2008 (UTC)

        All items implemented, though velocity methods for some orbit times not yet finished. Decided that for the solar system browser, the namespace hierarchy is more appropriate than frame hierachy, since it doesn't change over time. --Claurel (talk) 01:27, 15 March 2008 (UTC)

        Implemented velocity methods for EllipticalOrbit, SampledTrajectory, and SPICE Orbit (as of revision 4280) --Claurel (talk) 19:19, 16 April 2008 (UTC)

        Switch to int64 based BigFix

        (for performance) New class already coded, but needs extensive testing for compatibility with older version of Celestia. The new class includes a high precision multiplication operator, which will make it easier to code some frames stuff.

        Implemented; currently validating and characterizing performance of new class --Claurel (talk) 07:13, 4 February 2008 (UTC)

        Completed --Claurel (talk)

        Relative cel URLs

        Store reference frame coordinates in cel URLs instead of absolute coordinates; will result in more future-proof URLs.

        Implemented; patch being tested to verify compatibility with existing cel URLs --Claurel (talk) 20:47, 23 April 2008 (UTC)

        Code committed in revision 4318. Creating version 3 URLs currently just supported in Qt4 front-end --Claurel (talk) 20:07, 6 May 2008 (UTC)

        Toti's animated textures

        Deferred until after 1.6.0. --Claurel (talk) 01:10, 2 October 2008 (UTC)

        Improved SPICE support

        • Handle orientation kernels
        • Automatically determine valid time windows
        • Better handling of relative paths

        Added automatic time window determination and support for multiple kernels in a single SpiceOrbit (revision 4128). --Claurel (talk) 01:27, 24 February 2008 (UTC)

        Implemented rotation model based on SPICE frames, allowing use of spacecraft orientation kernels. (revision 4247). --Claurel (talk) 03:31, 9 April 2008 (UTC)

        Selectable markers

        It would be convenient if marked objects could be clicked on and selected regardless of their apparent magnitude. Feature tracker request from ajtribick

        Deferred until after 1.6.0. --Claurel (talk) 01:11, 2 October 2008 (UTC)

        Alternate star catalog support in celx scripts

        Celx scripts should be able to query the HD and SAO catalog numbers for stars. Feature tracker request from ajtribick

        SourceForge feature tracker item 1875572

        Implemented in revision 4116 --Claurel (talk) 00:37, 14 February 2008 (UTC)

        Add a globular cluster catalog

        Here's an interesting catalog of the Milky Way clusters, with locations (include distances), photometric parameters, metallicities, and more: http://physwww.physics.mcmaster.ca/%7Eharris/mwgc.dat

        Globular clusters were discussed earlier and there was some disagreement about whether they should be galaxies, open clusters, or a new type of deep sky object. My opinion at this point is that we should add a new type of deep sky object. If we do this, we need to choose an appropriate set of parameters.

        Implemented by Fridger, SVN revisions 4447-4449 --Claurel (talk) 00:58, 2 October 2008 (UTC)

        Object timelines

        Timeline is a new SSC property that addresses a frequent problem with complex add-ons. A motivating example is the Cassini-Huygens mission. The Huygens probe was initially attached to the Cassini spacecraft. On December 25, 2004, it detached from Cassini for three weeks of free flight before entering Titan's atmosphere and then landing on its surface. It's most convenient to describe the complete mission using three reference frames: the body-fixed frame of Cassini, a Saturn-centered inertial frame for the free flight section, and finally the body-fixed frame of Titan. In Celestia 1.5.0, an object only has a single reference frame, so an SSC file for Huygens must used three different objects for the probe. With a Timeline, it is possible to specify different reference frames, trajectories, and rotation models for the different phases of the mission.

        Here's an example of how the Huygens mission might look in an SSC file:

        "Huygens" "Sol"
        {
            Class "spacecraft"
            Mesh "huygens.3ds"
            Radius 0.00135
        
            Timeline
            [
                # Attached to Cassini
                {
                     Beginning "1997 10 15 09:27"
                     OrbitFrame { BodyFixed { Center "Sol/Cassini" } }
                     FixedPosition [ ... ]
                     BodyFrame { BodyFixed { Center "Sol/Cassini" } }
                     FixedRotation { ... }
                 }
        
                 # Free flight
                 {
                      Beginning "2004 12 25 02:01"
                      OrbitFrame { EclipticJ2000 { Center "Sol/Saturn/Titan" } }
                      SampledTrajectory { ... }
                      BodyFrame { EclipticJ2000 { } }
                      SampledOrientation { ... }
                  }
        
                  # Landed on Titan
                  {
                       Beginning "2005 1 14 09:00"
                       OrbitFrame { BodyFixed { Center "Sol/Saturn/Titan" } }
                       FixedPosition [ ... ]
                       BodyFrame { BodyFixed { Center "Sol/Saturn/Titan" } }
                       FixedRotation { ... }
                  }
             ]
        }
        

        Implemented and committed. Need to complete documentation. --Claurel (talk) 01:25, 24 February 2008 (UTC)

        CustomRotation

        Rotation of some solar system bodies is not adequately described by constant rotation about a fixed axis. We need custom rotation models for such bodies, with C++ functions to calculate orientation. They should be available through a CustomRotation SSC property, analagous to the way CustomOrbit works.

        We should have CustomRotations for:

        • Earth (precession and nutation)
        • the Moon
        • Major Saturnian satellites (especially Mimas)
        • Galilean satellites
        • Triton
        • IAU models for the planets

        The secular terms for pole positions should be clamped to avoid having the planets 'roll over' at times in the distant past or future.

        Implemented IAU models for planets, Moon, Martian, Jovian, and major Saturnian satellites. --Claurel (talk) 01:36, 24 February 2008 (UTC)

        Implemented precession for Earth: P03 model, and long period extension of P03 --Claurel (talk) 01:24, 15 March 2008 (UTC)

        Implemented IAU rotation models for major Uranian satellites. --Claurel (talk) 22:17, 2 May 2008 (UTC)

        Remove stellar distance limit

        Celestia 1.5.0 didn't handle stars more than 16,000 light years from the Sun. This limitation was addressed in revision 4198, with the maximum distance increased to 10 million light years.

        Implemented in revision 4198 --Claurel (talk) 01:35, 22 March 2008 (UTC)

        Support InfoURLs for stars

        In 1.5.0, solar system bodies and deep sky objects could have InfoURLs, but stars always used the default SIMBAD URL. It would be useful to have InfoURLs available for stars as well. Like other extended star attributes, InfoURLs would only be available for stars defined in stc files.

        Implemented in revision 4185 --Claurel (talk) 01:35, 22 March 2008 (UTC)

        Orbit display for reference points

        An often-reported issue in 1.5.0 was that Pluto's orbit was no longer visible. This is because the orbit of Pluto was redefined relative to the Pluto−Charon barycenter, and the heliocentric orbit of the barycenter wasn't shown. 1.6.0 will be changed to render the orbit of a reference point if one of the objects orbiting that reference point is either a planet, moon, asteroid, or spacecraft.

        Implemented in revision 4237 --Claurel (talk) 03:30, 9 April 2008 (UTC)

        SampledTrajectory files with velocities

        Adding velocity vectors to SampledTrajectory records can make the trajectory much more accurate for a given memory footprint (i.e. less samples required for the same accuracy.) HORIZONS can generate ephemerides with velocities, so there is a ready source of xyz+velocity trajectory data. Files with position and velocity will have the extension xyzv; such files can replace the xyz file in a SampledOrbit or SampledTrajectory without any other modification to an ssc or stc file.

        Implemented in revision 4236 --216.231.48.102 (talk) 18:17, 3 April 2008 (UTC)

        Update Cassini trajectory

        The current trajectory for Cassini only covers the nominal mission, which ends in June 2008. Now that the trajectory for the extended mission is available we should include it in Celestia. Also, the new Timeline feature can be used to define Huygens as a single object instead of as separate objects for the attached-to-Cassini and free flight mission segments.

        New Cassini mission added in SVN revision 4420. --Claurel (talk) 01:08, 2 October 2008 (UTC)

        Improved coordinate grids

        Add new grid types in addition to the existing equatorial grid: horizontal (alt-azimuth), ecliptic, and galactic. The grid lines drawn should change as the user zooms in, maintaining a roughly line density. Subdivision of grid arcs should be adaptive so that they always appear smooth. In order to make the labels useful, they must always be shown at points within the field of view, not in fixed locations as is the case in the current implementation.

        Implemented in SVN revision 4352 --Claurel (talk) 02:29, 31 May 2008 (UTC)

        Double stars

        1. Celestia 1.5.0 still does not calculate temperature if planet orbits a double star (like Tatooine in Star Wars).
        2. If both stars have planets, only planets of one star are listed in Solar System Browser. And always the same one, not the nearest one!

        The solar system browser problem is already fixed in the Qt version of Celestia. The temperature calculation will be addressed after 1.6.0. In my opinion, the temperature is not important enough that it should be displayed as part of the overlay text. It should instead be shown in a separate information window (possibly with some explanation of exactly what the equilibrium temperature is--people are understandably confused when they notice that Venus is cooler than Earth. --Claurel (talk) 16:52, 16 July 2008 (UTC)

        Update stars.dat

        Switch to a more rigorous and better documented method of building stars.dat from the HIPPARCOS data set. Use the new reduction as a starting point.

        New stars.dat produced by Andrew from the latest version of the HIPPARCOS catalog. SVN revision 4462 --Claurel (talk) 01:10, 2 October 2008 (UTC)

        Multiple names for solar system bodies

        Make it possible to assign multiple names to solar system bodies using the same colon separated name lists as for stars and deep sky objects.

        Ongoing projects

        • Qt4 interface
        • Atmosphere rendering
        • HDR
        • High-resolution tile rendering
        • Package system for add-ons
          • This page gives an explanation of some of the new features in Celestia 1.6.0. It is targeted at add-on creators who have some familiarity with making SSC files for earlier versions of Celestia. Each feature description is divided into two sections: background and 1.6.0 changes. The background section explains how a particular features of Celestia works in 1.5.0 and provides some motivation for why enhancements were made in 1.6.0. In all cases, backward compatibility with Celestia 1.5.0/1.5.1 has been maintained: add-ons written for 1.5.0 will work identically in 1.6.0.

        New Object Classes

        Background

        A body in an SSC files may be assigned a class that determines how it is categorized in Celestia's solar system browser. In some cases, the body's class also controls certain aspects of its appearance. For example, cometary dust tails are only shown for objects marked as class comet. Here is a typical usage in Celestia 1.5.0:

        "Ceres" "Sol"
        {
            Class "asteroid"
            Radius 487.5
            ...
        }
        

        The available classes in Celestia 1.5.0 are:

        * planet
        * moon
        * asteroid
        * comet
        * spacecraft
        * invisible
        

        1.6.0 Changes

        The 1.5.0 object classes are unchanged, but Celestia 1.6.0 adds several new object classes.

        dwarfplanet

        In 2006, the IAU passed a controversial resolution on the definition of a planet. Pluto was stripped of its planet status and reclassified as a member of the a new category of objects called dwarf planets. Ceres, the largest asteroid, and Eris, the largest known Kuiper belt object, were also designated dwarf planets. To date, these plus Makemake and Haumea are the only five objects recognized as dwarf planets by the IAU, but there are very likely to be more. A body may be marked as a dwarf planet by assigning it the class dwarfplanet:

        "Ceres" "Sol"
        {
            Class "dwarfplanet"
            Radius 487.5
            ...
        }
        

        In Celestia's 3D view window, dwarf planets are distinguished from planets with distinct orbit and label colors. Other than this, there is no difference between a dwarf planet and planet.

        minormoon

        There are over a hundred known moons in the Solar System. Most of these moons are small rocks that orbit the outer planets. While it is interesting to be able to visualize the orbits of these moons, there are so many of them that turning on moon orbits results in a confusing "ball of string" around the outer planets. The new object class minor moon was introduced to address this problem. In the default Celestia solar system files, the small moons of outer planets are now designated as minor moons. Orbit and label display for minor moons may be toggled separately from the major moon labels and orbits. It is important to note that unlike dwarf planet, "minor moon" is not a term recognized by the IAU. The class was added to Celestia purely for the convenience of users. There's no hard and fast rule about what a minor moon is, but in general outer planet moons with a diameter less than 100 km are marked as minor.

        Here's an example of using the minor moon class:

        "Sinope" "Sol/Jupiter"
        {
            Class "minormoon"
            Radius 19
            ...
        }
        

        surfacefeature

        Surface feature is a new class for objects that are fixed to the surface of another body, such as buildings and terrain features. Previously, there was simply no good classification for these objects. Lacking a better option, SSC creators tended to classify them as either asteroids or spacecraft. The surface feature class has one other useful property: surface features are not visible as points of light at a distance. While rendering very distant objects as points is a realistic effect for objects orbiting in space, it does not look good when applied to objects on the ground. In addition to this advantage, classifying appropriate objects means that they will be sensibly organized in the solar system browser.

        Example:

        "Space Needle" "Sol/Earth"
        {
            Class "surfacefeature"
            Mesh "needle.cmod"
            OrbitFrame { BodyFixed {} }
            FixedPosition [ ... ]
            ...
        }
        

        component

        Objects with moving parts can be implemented in Celestia with multiple SSC objects. For example, a spacecraft with two movable solar panels could be defined as three objects: one for the main body of the spacecraft, and one object for each panel. Rather than defining all of the parts as spacecraft, only the main body should be a spacecraft and the other parts assigned the new class component. Like surface features, components are not rendered as points of light when they're far away from the viewer. This prevents the problem with multipart objects appearing overly bright at a distance. Using the class component appropriately also means that objects are better organized in the solar system browser.

        Multi-part spacecraft example:

        "Orbiter" "Sol/Mars"
        {
            Class "spacecraft"
            Mesh "spacecraft-body.cmod"
            ...
        }
        
        "Solar Panel - Left" "Sol/Mars/Orbiter"
        {
            Class "component"
            Mesh "spacecraft-leftpanel.cmod"
            ...
        }
        
        "Solar Panel - Right" "Sol/Mars/Orbiter"
        {
            Class "component"
            Mesh "spacecraft-rightpanel.cmod"
            ...
        }
        

        diffuse

        Yet another set of objects that aren't good fits for any Celestia 1.5.0 class are dust clouds, accretion disks, volcanic plumes, and other extended, non-solid things. Celestia 1.6.0 adds a new class called diffuse for such objects. By default, diffuse objects cannot be clicked and selected by the user. They are never indicated with labels, nor are their trajectories shown when orbit paths are enabled. Lastly, they do not reflect light and result in "planetshine". This last point is important. Because diffuse objects are not solid, they may intersect other objects; under such circumstances, Celestia's reflected light calculation is not valid and will result in unrealistic lighting. Marking an object with class diffuse is the only way to tell Celestia that an object isn't solid and should be treated differently for the purpose of lighting.

        Example:

        "Loki Plume" "Sol/Jupiter/Io"
        {
            Class "diffuse"
            Mesh "plume.cmod"
            ...
        }
        

        Clickable property

        Background

        A Celestia user can select an object by clicking on it in the 3D view. However, there are times when this is undesirable. An SSC author may define an extended, gaseous object such as an accretion disc with the idea that the viewer may move freely through it. When the camera is inside such an object, a click in any direction will select it—behavior that is likely confusing to users.

        1.6.0 Changes

        Celestia 1.6.0 offers a new boolean SSC property, Clickable. Specifying clickable false in an SSC body definition prevents that body from being selected when clicked. When a user click selects, an unclickable object is treated as if it weren't there at all; if there is a more distant object under the click point, that object will be selected instead.

        Example:

        "Accretion Disc" "Fomalhaut"
        {
            Mesh "disc.cmod"
            Radius 1e9
            Clickable false
            ...
        }
        

        Note that objects of class diffuse are not clickable by default. Thus, the above example is better written like this:

        "Accretion Disc" "Fomalhaut"
        {
            Class "diffuse"
            Mesh "disc.cmod"
            Radius 1e9
            ...
        }
        

        If for some reason an SSC author wants to create a diffuse object that can be click selected, it is also possible to override the default unclickable status by setting the clickable property to true:

        "Dust Cloud" "Sol"
        {
            Class "diffuse"
            Mesh "cloud.cmod"
            Clickable true
            ...
        }
        

        Visible Property

        Background

        When designing a dynamic Celestia body or when debugging a catalog file, it often is useful to have Celestia not draw an object.

        1.6.0 Changes

        The SSC directives

         Visible true
        

        and

         Visible false
        

        determine whether or not an object is drawn.

        The default is

         Visible true
        

        For example:

        "Dust Cloud" "Sol"
        {
            Class "diffuse"
            Mesh "cloud.cmod"
            Visible false
            ...
        }
        

        causes the cloud to be defined but not drawn.

        
        The Visible property can be controlled in a CELX (Lua) script by calling the setvisible method:

         local obj = celestia:find("Sol/Dust Cloud")
         obj:setvisible(true)
        

        OrbitColor Property

        Background

        Celestia allows users to toggle the display of orbit paths for planets, stars, moons, and other bodies. In version 1.5.0 of Celestia, new script commands were added for changing the color of the orbits shown for each class. But, there are situations where it is useful to have finer control over the colors of orbit paths. For example, a planetary system overview may be clearer if each planet is given a distinct orbit color.

        1.6.0 Changes

        The color of an SSC object's orbit can be modified by setting the OrbitColor property. In this example, we'll set the color of the Moon's orbit to yellow:

        Modify "Moon" "Sol/Earth"
        {
            OrbitColor [ 1 1 0 ]
        }
        

        As with other color properties, the components of OrbitColor are values between 0 and 1, and are ordered red, green blue. The next example changes the orbit colors of all of the inner planets:

        Modify "Mercury" "Sol"
        {
            OrbitColor [ 1 0.7 0.2 ]  # brown
        }
        
        Modify "Venus" "Sol"
        {
            OrbitColor [ 1 1 0.7 ]  # light yellow
        }
        
        Modify "Earth" "Sol"
        {
            OrbitColor [ 0.5 0.7 1 ]   # light blue
        }
        
        Modify "Mars" "Sol"
        {
            OrbitColor [ 1 0.6 0.6 ]   # light red
        }
        

        Triaxial ellipsoids

        Background

        Celestia has two ways to set the shape of an object:

        • A 3D mesh file can be specified using the Mesh property, or...
        • Celestia will assume that the object is an ellipsoid if the Mesh property is omitted

        In Celestia 1.5.0, the size of the ellipsoid is controlled by the Radius property. The shape of the ellipsoid is given by the value of the oblateness property. Oblateness is the amount of flattening or stretching along the polar axis. The default value of oblateness is 0.0, indicating that the ellipsoid is a sphere. If the oblateness greater than zero, the planet will be appear squashed. This squashed sphere shape is called an oblate spheroid. Giant planets can be very noticeably non-spherical: fast rotation distorts them, causing a noticeable bulge at the equator. Even solid bodies such as Earth can be flattened to some extent, though less than giant planets.

        

        Example of an oblate spheroid (oblateness < 1)

        Oblateness is calculated as ${\frac {a-b}{a}}$, where a is the equatorial radius and b the polar radius. Saturn has the most extreme flattening of any planet in the Solar System, with an oblateness of 0.0980. Earth has an oblateness of about 0.00335--visually indistinguishable from a sphere when seen from space.

        While most large Solar System bodies are accurately represented as oblate spheroids, there are a few that cannot be. Some moons of giant planets are noticeably stretched along the equatorial axis pointing toward the planet. Three axis lengths have to be given: the polar axis, and two different equatorial axes. The term 'triaxial ellipsoid' refers to an ellipsoid with three axes that are all different lengths.

        1.6.0 Changes

        The new SemiAxes property for SSC bodies is used to specify a triaxial ellipsoid. Images from the Cassini spacecraft show Saturn's moon Mimas to have a noticeably triaxial shape.

        

        Its dimensions are 414.8×394.4×381.4 km. The first number is the length of the axis pointing toward Saturn, the second number is the axis along the orbit of Mimas, and the last number is the polar axis. In an SSC file, we'd write:

        "Mimas" "Sol/Saturn"
        {
            SemiAxes [ 207.4 197.2 190.7 ]
            ...
        }
        

        Notice that since we're specifying the semiaxes not the axes, and thus the values are half the axis lengths. The relationship between axis and semiaxis is analogous to that between diameter and radius. The usage of the SemiAxes property is quite simple: you're essentially specifying three radii instead of just one. There are some subtleties in the interactions between the Radius, Oblateness, and SemiAxes properties:

        • Radius is multiplied by the SemiAxes lengths if both properties are specified
        • Oblateness is ignored if SemiAxes are given
        • It is an error if neither SemiAxes nor Radius are specified

        You can keep things simple and ignore these technicalities if you obey these guidelines:

        • For spherical bodies, specify just the radius
        • For oblate bodies, specify just the radius and oblateness
        • For planets with triaxial ellipsoid shapes, specify just the semiaxes
        • For irregular objects, specify just the mesh and radius

        Object timelines

        Object timelines are a major new feature of Celestia 1.6.0. With a timeline, it is possible to describe the motion of an object over its entire lifetime, even when multiple trajectory types or reference frames are required. What used to require awkward SSC files with multiple definitions for the same object can now be done with a single object.

        Background

        The motivation for adding Timeline to Celestia is best explained via an example. We'll consider the Cassini−Huygens mission to Saturn and Titan, which is included in the base Celestia package. The Huygens probe was attached to Cassini from launch until December 25, 2004. On that day, Huygens separated from Cassini and then orbited Saturn for three weeks on its own until descending into Titan's atmosphere on January 14, 2005. Now, how do we describe the trajectory of Huygens in an SSC file? For Cassini, we use a SampledTrajectory (xyz file) that covers the entire lifetime of the spacecraft. We could do something similar for Huygens: the xyz file would be identical up to the point of separation from Cassini. However, this is a lot of data duplication. It's also extra maintenance: if the Cassini trajectory is updated (after the separation time), we must also update the Huygens trajectory file. Finally, this technique only works if Cassini is not rotating, which in reality is not the case at all.

        A more convenient and less wasteful approach would take advantage of the fact that Huygens and Cassini are joined together throughout their journey from Earth to Saturn. In Celestia 1.5.0, the only way to do this is to define two different versions of Huygens: one that's attached to Cassini, and another that's in orbit around Saturn. Here is the version that is attached to Cassini:

        "Huygens (with Cassini)" "Sol/Cassini" 
        {
            Class "spacecraft"
            Mesh "huygens.3ds"
            Radius 0.00135
        
            Beginning 2450736.893877314 # 1997 Oct 15 09:27:11
            Ending    2453364.5847      # 2004 Dec 25 02:01:58
        
            OrbitFrame { BodyFixed { Center "Sol/Cassini" } }
            BodyFrame { BodyFixed { Center "Sol/Cassini" } }
            FixedPosition [ -0.0013 0 -0.0002 ]
            FixedRotation { }
        

        }

        The Ending property is set to the time of separation. At that point the version of "Huygens" attached to "Cassini" will disappear. Both the position and orientation of this "Huygens" is fixed relative to "Cassini": "Huygens" will follow every movement and rotation of the Cassini spacecraft. After separation "Huygens (with Cassini)" is replaced by this version:

        "Huygens (free flight)" "Sol" 
        {
            Class "spacecraft"
            Mesh "huygens.3ds"
            Radius 0.00135
        
            Beginning 2453364.5847 # 2004 Dec 25 02:01:58
            Ending    2453384.8750 # 2005 Jan 14 09:00:00
        
            SampledOrbit "huygens.xyz"
        
            UniformRotation
            {
                Inclination 70
                Period 0.01
            }
        }
        

        Now, Huygens has its own trajectory and rotation. Its motion is defined relative to the Sun rather than to Cassini. But, there are drawbacks:

        • We have to replicate all the data about Huygens not related to trajectory or orientation: the mesh, class, radius, infoURL, etc.
        • A user is likely to be slightly confused by the fact that there are two instances of Huygens in the Solar System browser.
        • Following Huygens as it separates from Cassini will not work; the camera will not track "Huygens (free flight)" after "Huygens (with Cassini)" disappears.

        What we want is some way to give two different reference frames and trajectories for Huygens without creating to instances of the probe. This is exactly what object Timelines allow.

        1.6.0 Changes

        In Celestia 1.6.0, we can merge the two versions of Huygens into a single object.

        "Huygens" "Sol/Cassini" 
        {
            Class "spacecraft"
            Mesh "huygens.3ds"
            Radius 0.00135
        
            Timeline [
              # Phase 1: With Cassini
              {
                 Beginning "1997 19 15 09:27:11"
                 Ending    "2004 12 25 02:02:34"
        
                 OrbitFrame { BodyFixed { Center "Sol/Cassini" } }
                 BodyFrame { BodyFixed { Center "Sol/Cassini" } }
                 FixedPosition [ -0.0014 0 0.0002 ]
                 FixedRotation { Inclination 90 AscendingNode 90 } 
               }
        
               # Phase 2: Free flight to Titan
               {
                 Ending "2005 01 14 09:07:00"
        
                 OrbitFrame { EclipticJ2000 { Center "Sol/Saturn" } }
                 BodyFrame { EclipticJ2000 {} }
        
                 SampledTrajectory { Source "huygens.xyz" }
                 UniformRotation
                 {
                   Period 0.125            # 7.5 revolutions per minute
                 }
               }
             ] # End Timeline
        }
        

        Observe the inside of the Timeline block, there are two sets of frames and trajectories. Each of these timeline sections is called a phase. The only things that are allowed in a phase are the beginning and ending time, trajectory, rotation model, body frame, and orbit frame. Timeline is not intended to be a general purpose system for animation, so there is no way to effect changes to the appearance of an object in a timeline phase by, say, putting a different model in each phase. Some other techniques will eventually be implemented to allow animation in Celestia.

        Beginning and Ending

        The beginning and ending properties define the span covered by the phases of the timeline. Collectively, the phases cover a continuous span of time: no gaps are allowed. Continuity is guaranteed because for all phases but the first, the phase beginning time is automatically set to the ending time of the previous phase. The rules for beginning and ending times in timeline are summarized below:

        First phase

        Beginning may be specified, defaults to −infinity if it isn't

        Ending must be specified if there is more than one phase

        Last phase

        Beginning must be specified if there is more than one phase

        Ending may be specified, defaults to +infinity if it isn't

        Other phases

        Beginning is not allowed; it is automatically set to the Ending of the previous phase

        Ending must be specified; there is no default value

        A few examples will serve to illustrate various ways that a timeline can be divided into phases. In the first example, there is just a single infinite phase:

        "Satellite1" "Sol/Earth"
        {
            Radius 0.001
            Timeline [
              {
                  EllipticalOrbit { ... }
              }
            ]
        }
        

        Satellite1 is assigned an orbit that is valid over all time, because Beginning and Ending were omitted and have their defaults values of −infinity and +infinity. In this case, there's really no need to use a timeline at all. The object will behave identically to this simpler version:

        "Satellite1" "Sol/Earth"
        {
            Radius 0.001
            EllipticalOrbit { ... }
        }
        

        When there is just a single phase, there is no need to put the frames and trajectories in a timeline. A more useful timeline example is this definition of a lunar lander that is launched from Earth on 25 Feb 2010 and lands on the Moon on March 12th of the same year:

        "Lunar Lander" "Sol/Earth"
        {
            Radius 0.001
            Timeline [
              # Phase 1: Launch and cruise
              {
                Beginning "2010 2 25 12:30"
                Ending    "2010 3 12 15:30"
                OrbitFrame { EquatorJ2000 { Center "Sol/Earth" } }
                SampledTrajectory { Source "traj.xyzv" }
              }
        
              # Phase 2: Landed on the Moon
              {
                OrbitFrame { BodyFixed { Center "Sol/Earth/Moon" } }
                FixedPosition [ ... ]
              }
            ]
        }
        

        The landing time is defined in the first phase, so no beginning time is given (or allowed) in the second phase. Since there's no ending specified in the second phase, the lander will sit on the surface of the moon until the end of time.

        Position + Velocity Trajectories (xyzv files)

        Using a new trajectory file format can simultaneously improve positioning accuracy and decrease memory usage.

        Background

        Sampled trajectories are used when the trajectory of an object is not adequately described by an ellipse or one of Celestia's built-in orbit calculations. Typically, sampled trajectories are used for interplanetary spacecraft, but they can be useful for other objects as well. There are two ways to use sampled trajectories in an ssc or stc file. The old way uses SampledOrbit:

        SampledOrbit "trajectory.xyz"
        

        The new method added in 1.5.0 uses SampledTrajectory:

        SampledTrajectory { Source "trajectory.xyz" }
        

        SampledTrajectory should be preferred over SampledOrbit, as it offers options to control the precision (double or single) and the interpolation type (cubic or linear.) SampledOrbit always uses single precision positions, which is not adequate for serious spaceflight applications of Celestia.

        A sampled trajectory file is a list of time and position records. Usually the files are generated from SPICE kernels or JPL's [[6]] system. Here's an excerpt from the trajectory file for Galileo:

        2447818.615972 134114700.2612462193 64912642.6984842718 39861.799941
        2447819.615972 133153386.7785827518 66969511.3118158504 237125.784089
        2447820.615972 132137795.3581911474 69024279.8844281882 418499.867572
        2447821.615972 131079666.1268854141 71061806.8872888833 596914.157647
        

        The first value on each line is a Julian date, and that last three values are positions in kilometers. The reference frame for the positions is given in the ssc file. By default, Celestia uses a technique called cubic Hermite interpolation for smooth motion between points. For this discussion, the exact mathematics aren't important. What is relevant is that in order to interpolate between points, Celestia needs the velocity of the object as well as its position at each time. It's possible to estimate the velocity by looking at the difference in position between two successive points, but much improved accuracy is achievable saving velocities in the trajectory file.

        1.6.0 Changes

        Celestia 1.6.0 adds support for position and velocity trajectory files. These files have the extension xyzv, and can be used in exactly the same manner as xyz files in a SampledTrajectory:

        SampledTrajectory { Source "trajectory.xyzv" }
        

        The records in an xyzv file have the same layout as in an xyz file except that three velocity values are appended after each position. The units for velocity are kilometers per second. For a given file size, xyzv files give much more accurate positioning of objects. Thus, if it's possible to get velocities as well as positions for an object, an xyzv file should always be preferred over an xyz file. Celestia 1.6.0 will still support xyz files for backward compatibility and to cover situations where velocities are unavailable.

        The web interface for HORIZONS can be used to produce trajectories with velocities as well as positions. There's also a new tool for Celestia called spice2xyzv that will generate an xyzv file from one or more SPICE kernels. Documentation on this tool is forthcoming.

        Multiple Names for SSC Objects

        Objects defined in SSC files can now be assigned multiple aliases.

        Background

        In Celestia 1.5.1, it is possible to assign more than one name to a star or deep sky object. This is important because there is often several commonly used designations for stars and galaxies. For example, the red giant Betelgeuse is often referred to by its Bayer designation Alpha Orionis. The Andromeda Galaxy is also as NGC 598 and by its Messier number M 33. The definition for Andromeda in a DSC file might look something like this:

        "Andromeda Galaxy:M 33:NGC 598"
        {
            ...
        }
        

        The names are delimited by colons.

        1.6.0 Changes

        1.6.0 simply adds the same multiname capability for SSC objects. As with stars and deep sky objects, names are delimited by colons. A common situation in which multiple names are useful is for minor planets. When first reported, a minor planet is assigned a provisional designation. After further observation it will get a minor planet number, and the IAU may eventually approve a proper name for the object as well. Thus, in an SSC file, you may have a definition like this:

        Body "136199 Eris:Eris:2003 UB313" "Sol"
        {
            ...
        }
        

        The first name in the list will be the one that appears in labels and in the solar system browser. All of the names will be shown in the upper left corner of the screen when the object is selected. Any of the names is valid in a path, so you could refer to Eris's moon Dysnomia as "Sol/136199 Eris/Dysnomia", "Sol/Eris/Dysnomia", or "Sol/2003 UB313/Dysnomia".

        CustomRotation

        Simplified Surface Placement

        SurfaceObject "name" "path/parent" { ... }
        

        Use of the SurfaceObject keyword invokes several useful defaults:

        • The object's default OrbitFrame is the BodyFixed frame of the parent object
        • The object's default BodyFrame is topocentric, with its Z axis pointing toward the zenith, its Y axis pointing toward the parent body's north pole, and its X axis pointing to the east.
        • The object's default Class is "surfacefeature"

        Add/modify/replace for stars

        Mesh placement and scaling

        Background

        Celestia add-on creators face some difficulties when trying to place mesh objects precisely relative to each other. Celestia's "normalization" of mesh objects is the cause of some of these problems. When a mesh is normalized, it is scaled and centered so that its longest axis fits into a sphere with the specified radius of the object. The common workaround is to add identically sized invisible bounding box to objects that will be positioned close to each other. This ensures that the models will effectively share the same coordinate system.

        While effective, creating these bounding boxes adds extra work for add-on creators. It also means that meshes end up getting incorrectly flagged as translucent for purposes of depth sorting.

        1.6.0 Changes

        Two new ssc properties solve the problem of mesh placement without resorting to adding bounding boxes:

        
        

        # defaults to true for backward compatibility
        NormalizeMesh <boolean>
        
        # defaults to 1
        MeshScale <number>
        

        
        When an object has NormalizeMesh false specified, no automatic scaling and recentering of the mesh is done. The add-on creator must make sure to set the Radius of the object to a value large enough to contain it.

        MeshScale converts the internal units of the model into kilometers as required by Celestia. For example, it is much more convenient to build a spacecraft in a system where the unit is one meter instead of one kilometer. For such a model, you would specify the MeshScale as 0.001.

        Neither of these additions affect backward compatibility.

        • Celestia has gone through quite a few versions since it was first made available in the late 1990s. Some of the older versions are still available from SourceForge .

          • The next major release of Celestia, v1.7.0, is currently under development.
            • If the user interface changes to QT, which will be common to all operating systems, it may be called v2.0.
            • See the Development instructions if you'd like to try compiling the "pre-alpha" version yourself. It's very easy to do under Windows, at least.
          • Celestia v1.6.1 will be only a bug-fix release.
            • V1.6.1 has been delayed due to an intractable problem in the MacOS version.
          • Celestia v1.6.0 was made available on July 10, 2009.
            • Please visit the Celestia Web forum: Celestia 1.6.0 released for details.
          • Celestia v1.5.0 was made available on January 26, 2008.
            • Please visit the Celestia Web forum : Celestia 1.5.0 is ready for details.
          • The previous stable version of Celestia, v1.4.1, was released in February, 2006.
          • ==Bugs==

          If you think you've found something wrong in Celestia, please report it using Issues on GitHub. Please review the known bugs to make sure your report is not a duplication. When reporting a problem, be sure to include a description of your system, especially the operating system, graphics card and OpenGL driver you're using.

          Requests for New Features

          If you think of features which would be useful to Celestia users, please add them to the Requests on GitHub, not here. Please check already made requests before reporting a new.

          Old lists of suggested new features and Wish List items are included in this WikiBook, but they're very unlikely to be implemented if they aren't on the GitHub list. If you are interested in any of the features listed on those pages, you must take the responsibility of making sure they're requested on GitHub.

          • From v1.5, Celestia fully supports internationalization (often abbreviated as i18n). Celestia i18n is processed using gettext, a service that allows for translation between different languages.

          All the strings used in the program can be translated. For each language, the list of strings and their translation is saved in a .po file.

          Using Celestia in another language

          Celestia should automatically change the language it uses based on the computer's language. However, if you do not want to switch your computer's language and region, you can specially open Celestia using the command line:

          MacOS X

          1. Open Terminal.
          2. Change the directory using cd to the directory that has Celestia (the Unix executable file).
          3. Type ./Celestia -AppleLanguages '(aa)', where aa refers to the language code, for example es being Spanish.
          4. Press Enter.

          Windows

          1. Open Command Prompt (cmd.exe)
          2. Change the directory using cd to the directory that has Celestia
          3. Type set LC_MESSAGES=aa, where aa is the language code, and press Enter
          4. Type celestia and press Enter

          Getting .po files

          The .po files can be downloaded from the Celestia GitHub repository or from the table in the 'Celestia translation overview' section below.

          Editing .po files

          The .po files can be edited using the following software:

          • Poedit: for MacOS, Linux and Windows.
          • KBabel: for KDE

          Updating existing .po files

          The already existing .po files for a language can easily be updated to the latest version by using the celestia.pot. In poEdit this can be done with the command "Catalog/Update from POT file". This results then in the program showing a list of removed and changed or newly introduced strings. But be advised that the creation date of the .po file internally is not updated. KBabel should also have such a mechanism.

          Creating a new .po file

          • Download the celestia.pot file from the GitHub repository.
          • Rename it using the ISO 639-1 code of your language.
          • Edit it as described in the above 'Editing .po files' section.

          Adding completed .po files to Celestia

          Either:

          • Join https://www.transifex.com/celestia/celestia/ as your language translator and upload your file.
          • Create a new pull-request to our repository on Github
          • Or simply send .po files to someone of developers

          Building internationalization files from the source in MS Windows

          • Follow the Celestia build for Win 32 platform as described in Celestia/Development/Win32 platform. It is assumed that Celestia's source is in "c:\celestia" and other programs are installed in c drive, too.
          • Install perl (e.g. ActivePerl) and POEdit for Windows
          • Add path for POEdit (e.g. C:\Program Files\Poedit\bin). This is for msgfmt.
          • Open Windows command console (cmd.exe)
          • Execute "C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat"
          • Change directory with "cd C:\celestia\celestia\po" command
          • Run "perl translate_resources.pl". The translate_resources.pl script does:
            • translate resource files from po files -> src/celestia/rc/celestia_LL.rc
            • build dll files -> src/celestia/rc/celestia_LL.res -> locale/res_LL.dll
            • compile catalogs -> locale/LL/LC_MESSAGES/celestia[_constellations].mo

          Building .txf font texture files

          Celestia uses its own .txf font textures to display the OpenGL overlay text. Some non-Latin characters may be missing from the font textures wich are distributed with the standard Celestia package, though.
          In that case, please use the following process to build celestia .txf font textures from standard .ttf fonts:

          • Download the txf utilities from http://www.shatters.net/~claurel/stuff/txfutil.tar.gz (dead link)
            • This link has source code for what are probably the same utilities.
          • Generate the .txf files:

          ttf2txf -w 1048 -h 1048 -f codepoints_LL.txt -s 12 -o sans12_LL.txf font.ttf
          ttf2txf -w 1048 -h 1048 -f codepoints_LL.txt -s 14 -o sans14_LL.txf font.ttf
          ttf2txf -w 1048 -h 1048 -f codepoints_LL.txt -s 20 -o sansbold20_LL.txf font_bold.ttf
          

          This will create the following font textures which should be placed in the font/ dir:

          • sans12_LL.txf
          • sans14_LL.txf
          • sansbold20_LL.txf.

          Note for Windows users:

          • A pre-compiled version of ttf2txf is available at: http://gvince.perso.sfr.fr/celestia/dev/ttf2txf.zip
          • The codepoints_LL.txt file is generated by running the translate_resources.pl perl script from the po/ dir. See Building internationalization files from the source in MS Windows section above.

          Celestia translation overview

          The translation process currently applies to Celestia 1.6.1 (development version).

          >> Last celestia.pot file update: 2010-01-04

          Main .po files

          Language	File	Translated	Fuzzy	Untranslated	Revision Date	Last Translator
          ar	ar.po	58%	335	83	2006-06-05	saudilink@lycos.com
          be	be.po	100%	0	0	2010-11-15	375gnu@gmail.com
          bg	bg.po	68%	284	30	2008-01-27	kumbarov@gmail.com
          de	de.po	100%	0	0	2010-01-29	celestia-deutsch@gmx.net
          el	el.po	86%	128	2	2010-01-25	ckouz@uom.gr
          es	es.po	100%	0	0	2010-01-25	abramson@cab.cnea.gov.ar
          fr	fr.po	100%	0	0	2010-02-25	gvince@sfr.fr
          gl	gl.po	100%	0	0	2010-04-08	xabiercs@terra.com
          hu	hu.po	100%	0	0	2010-04-19	zoltanszekely@hotmail.com
          it	it.po	100%	0	0	2010-03-31	gvince@sfr.fr
          ja	ja.po	100%	0	0	2010-03-13	aqua@aqsp.net
          ko	ko.po	100%	0	0	2010-03-13	blcktgr73@gmail.com
          lt	lt.po	100%	0	0	2010-03-02	neoromancer@gmail.com
          lv	lv.po	95%	46	0	2010-02-06	sg30022@lanet.lv
          nl	nl.po	100%	0	0	2010-03-28	myckel@sdf.lonestar.org
          no	no.po	100%	0	0	2010-12-05	FreewareTips
          pl	pl.po	100%	0	0	2010-02-05	hippie_1968@hotmail.com
          pt	pt.po	74%	246	4	2009-01-13	zeraeiro@gmail.com
          pt_BR	pt_BR.po	100%	0	0	2010-04-03	igorborgo@gmail.com
          ro	ro.po	74%	246	4	2008-12-28	oanaradu32@queeq.com
          ru	ru.po	100%	0	0	2010-11-28	leserg@ua.fm
          sk	sk.po	100%	0	0	2010-04-13	acelists@atlas.sk
          sv	sv.po	99%	0	2	2010-03-27	po@danielnylander.se
          tr	tr.po	28%	0	681	2011-01-02	kde-i18n-doc@kde.org
          uk	uk.po	100%	0	0	2010-01-24	yurchor@ukr.net
          zh_CN	zh_CN.po	100%	0	0	2010-04-047	markerzli@gmail.com
          zh_TW	zh_TW.po	100%	0	0	2010-03-13	iychiang1809@gmail.com

          Constellation names .po files

          Language	File	Translated	Fuzzy	Untranslated	Revision Date	Last Translator
          ar	ar.po	98%	0	1	2006-06-05	saudilink@lycos.com
          be	be.po	100%	0	0	2010-11-02	375gnu@gmail.com
          bg	bg.po	100%	0	0	2007-12-19	kumbarov@gmail.com
          de	de.po	100%	0	0	2006-02-07	schreiberste@web.de
          el	el.po	100%	0	0	2009-05-08	ckouz@uom.gr
          en	en.po	100%	0	0	2005-08-06	chris@teyssier.org
          es	es.po	100%	0	0	2006-02-03	ElChristou
          fr	fr.po	100%	0	0	2008-11-23	vince.gian@free.fr
          gl	gl.po	100%	0	0	2010-04-08	xabiercs@terra.es
          hu	hu.po	100%	0	0	2009-01-15	zoltanszekely@hotmail.com
          it	it.po	100%	0	0	2006-08-11	mausan66@tiscali.it
          ja	ja.po	100%	0	0	2006-08-07	aqua@aqsp.net
          ko	ko.po	100%	0	0	2010-01-26	jaeuck@gmail.com
          lt	lt.po	100%	0	0	2008-12-04	neoromancer@gmail.com
          lv	lv.po	100%	0	0	2006-12-14	sg30022@lanet.lv
          nl	nl.po	100%	0	0	2006-08-02	myckel@sdf.lonestar.org
          no	no.po	100%	0	0	2010-12-05	FreewareTips
          pl	pl.po	100%	0	0	2008-10-21	hippie_1968@hotmail.com
          pt	pt.po	100%	0	0	2006-12-30	zeraeiro@gmail.com
          pt_BR	pt_BR.po	100%	0	0	2009-02-18	igorborgo@gmail.com
          ro	ro.po	100%	0	0	2008-12-28	oanaradu32@queeq.com
          ru	ru.po	100%	0	0	2006-05-27	leserg@ua.fm
          sk	sk.po	100%	0	0	2010-02-28	acelists@atlas.sk
          sv	sv.po	100%	0	0	2006-02-21	po@danielnylander.se
          uk	uk.po	100%	0	0	2008-??-??	dubyk@library.lviv.ua
          zh_CN	zh_CN.po	100%	0	0	2006-08-09	zhaozhengxu@yahoo.com
          zh_TW	zh_TW.po	100%	0	0	2009-08-10	alchen@tam.gov.tw

          Other localizable files

          The following files can be localized too: controls.txt, COPYING, demo.cel, guide.cel, start.cel.
          These files can be edited using a simple text editor. For UTF-8 encoding, please consider using, e.g., notepad++
          Once the translation is completed, just rename the file as controls_LL.txt, COPYING_LL, demo_LL.cel, guide_LL.cel, start_LL.cel, where LL represents the ISO 639-1 code of your language.
          Once the translation is completed, these files can be sent to team@celestia.space.

          Language			Localized Files
          bg	controls_bg.txt	COPYING_bg		guide_bg.cel	start_bg.cel
          be	controls_be.txt		demo_be.cel	guide_be.cel	start_be.cel
          de	controls_de.txt	COPYING_de	demo_de.cel	guide_de.cel	start_de.cel
          es	controls_es.txt	COPYING_es	demo_es.cel	guide_es.cel	start_es.cel
          fr	controls_fr.txt	COPYING_fr	demo_fr.cel	guide_fr.cel	start_fr.cel
          gl	controls_gl.txt	COPYING_gl	demo_gl.cel	guide_gl.cel	start_gl.cel
          hu					start_hu.cel
          it	controls_it.txt	COPYING_it	demo_it.cel	guide_it.cel	start_it.cel
          ja	controls_ja.txt	COPYING_ja	demo_ja.cel	guide_ja.cel	start_ja.cel
          ko	controls_ko.txt	COPYING_ko	demo_ko.cel	guide_ko.cel	start_ko.cel
          lt			demo_lt.cel	guide_lt.cel	start_lt.cel
          lv			demo_lv.cel		start_lv.cel
          nl	controls_nl.txt	COPYING_nl	demo_nl.cel	guide_nl.cel	start_nl.cel
          no	controls_no.txt		demo_no.cel
          pl	controls_pl.txt	COPYING_pl	demo_pl.cel	guide_pl.cel	start_pl.cel
          pt	controls_pt.txt	COPYING_pt	demo_pt.cel	guide_pt.cel	start_pt.cel
          pt_BR	controls_pt_BR.txt	COPYING_pt_BR	demo_pt_BR.cel	guide_pt_BR.cel	start_pt_BR.cel
          ru	controls_ru.txt	COPYING_ru	demo_ru.cel	guide_ru.cel	start_ru.cel
          sk	controls_sk.txt		demo_sk.cel	guide_sk.cel	start_sk.cel
          sv	controls_sv.txt	COPYING_sv	demo_sv.cel	guide_sv.cel	start_sv.cel
          tr			demo_tr.cel
          uk	controls_uk.txt	COPYING_uk	demo_uk.cel	guide_uk.cel	start_uk.cel
          zh_CN	controls_zh_CN.txt	COPYING_zh_CN	demo_zh_CN.cel	guide_zh_CN.cel	start_zh_CN.cel
          zh_TW	controls_zh_TW.txt	COPYING_zh_TW	demo_zh_TW.cel	guide_zh_TW.cel	start_zh_TW.cel