Wikibooks

Celestia/Print Version

< Celestia
The latest reviewed version was checked on 14 June 2017. There are template/file changes awaiting review.
This is the print version of Celestia
You won't see this message or any elements not part of the book's content when you print or preview this page.


This is an initial attempt to create a printable version of the Guide to Celestia. It is only a start. Don't even bother trying to print it just yet.


Celestia

The current, editable version of this book is available in Wikibooks, the open-content textbooks collection, at
https://en.wikibooks.org/wiki/Celestia

Permission is granted to copy, distribute, and/or modify this document under the terms of the Creative Commons Attribution-ShareAlike 3.0 License.


Celestia

 

Wikimedia Commons has media related to: Celestia

 

Wikipedia has related information at Celestia

 

A printable version of Celestia is available. (edit it)



 


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, macOS, and Linux operating systems, with mobile (iOS and Android) versions recently released.

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.

About this guide

This Guide to Celestia is intended to be a comprehensive source of information for students, educators, and other users of Celestia. It includes instructions for obtaining, installing, using, customizing, and troubleshooting the Celestia software, as well as explanations of concepts and techniques from astronomy and computer graphics as needed to fully explore and understand Celestia and its universe. It is intended to address the needs of novice, casual, and advanced users.

The Guide to Celestia is very far from complete. You can help by adding useful content. Members of the Celestia community are encouraged to be bold in editing this WikiBook to provide the additions and corrections needed to make it useful for themselves and others. Please share your knowledge here.


Icons indicate approximate development status.
Of course, all pages are subject to improvement at any time.

Wikibook Development Stages
Sparse text   Developing text   Maturing text   Developed text   Comprehensive text  

Using Celestia

Currently, this section only contains basic explanations of how to use Celestia. If you would like more detail, please refer to Frank Gregorio's Celestia 1.6.1 User's Guide (also available as a PDF).

Getting Celestia to Run

Exploring Celestia's Universe

Understanding Celestia

Enhancing Celestia

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

Scripting

Customizing Celestia

Development

Addon Tutorials for Beginners

The following pages are for beginners. These are tutorials for creating different kinds of celestial bodies in Celestia.

  • Tutorials: a few things you should know before making addons for Celestia.  

1. Creating Solar System Objects

2. Creating Extrasolar Objects

3. Creating Deep-Sky Objects

Credits

Celestia Web Sites

Celestia Add-ons

Note: the Motherlode and Celestial Matters (both hosted on ibiblio.org) went offline on 2020 August 27. As of December 22 the Motherlode is back online, but Celestial Matters is still unavailable.

Articles about Celestia

Why Celestia?

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?

This section is a stub.
You can help Wikibooks by expanding it.
  • Telescope control
  • 180 degree field of view
  • Sound (prior to recent builds of 1.7.0)
  • 3D stereoscopic or anaglyph viewing
  • ?

Installation

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

This section is a stub.
You can help Wikibooks by expanding it.

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

This section is a stub.
You can help Wikibooks by expanding it.

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

This section is a stub.
You can help Wikibooks by expanding it.

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

Graphics Hardware

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.

Getting Started

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.

Celestia's Command Line

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

Locations

A reader has identified this chapter as an undeveloped draft or outline.
You can help to develop the work, or you can ask for assistance in the project room.

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

Navigation

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.

View Control

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

Time Control

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

Bookmarks

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.)

Display Options

A reader has identified this chapter as an undeveloped draft or outline.
You can help to develop the work, or you can ask for assistance in the project room.

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.

This section is a stub.
You can help Wikibooks by expanding it.

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.

Render Paths

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

This section is a stub.
You can help Wikibooks by expanding it.

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.

Snapshots and Movies

A reader has identified this chapter as an undeveloped draft or outline.
You can help to develop the work, or you can ask for assistance in the project room.

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

This section is a stub.
You can help Wikibooks by expanding it.

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

Image screenshots work as expected.

MacOS X

This section is a stub.
You can help Wikibooks by expanding it.

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

This section is a stub.
You can help Wikibooks by expanding it.

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.

FAQs: Frequently Asked Questions

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.

Glossary of Celestia terminology

A reader has identified this chapter as an undeveloped draft or outline.
You can help to develop the work, or you can ask for assistance in the project room.

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.

Scripting overview

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.)

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 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.

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 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.

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

Introduction to CELX Scripting

Read on to learn about simple CELX scripting...

If you have comments or questions, please put them on the Celx Questions and Answers page.

Introduction

This is a tutorial on simple CELX scripting. It is based on the philosophy that the best way to learn is by example, so there are lots of examples. Each example is usually a small step beyond the previous one, but understanding it may depend on any previous example, so make sure you understand each example completely before you go on to the next.

Getting Started

To get started, you should create a script file for testing purposes. You could call it "test.celx" or something similar. Be sure it has the ".celx" file type suffix so it will be recognized as a Celestia CELX script file. Then you should be able to just double-click on the file icon to cause Celestia to run the script. This is a lot faster than running the script from the Celestia menus. You can keep both Celestia and your text editor running; when you're ready to test your script just save your changes and double-click the file icon. The Celestia window should pop to the front and run your script. After you've observed the result you can return to the editor window to make further changes in the script. And don't overlook the fact that you can cut and paste code directly from the tutorial examples!

Starting Simple

Here's a simple CELX script: 

celestia:flash("Hello, Universe!")
wait(2.0)

When you run this script, the message "Hello, Universe!" will briefly appear in the lower left corner of the Celestia window. The script instructions here are very simple. First, we asked the object named "celestia" to perform its function named "flash" to display the message "Hello, Universe!". Then we asked the script to wait for 2 seconds (so we'd have time to see the message).

The format of our request to the object named "celestia" to perform its function named "flash" is basic to Lua. First we wrote the name of the object, in this case, "celestia". Then we wrote a colon (:) to indicate that we were requesting the object to perform a function. Then we wrote the name of the function we want the object to perform, in this case, "flash". Finally, we wrote the parameters to the function, in this case the string "Hello, Universe!", enclosed in parentheses. (Note that we didn't use quotes around the name of the object or the function, just the parameter.) Other requests to objects to perform a function have a similar format.

Here's another example: 

celestia:flash("Hello, Universe!")
wait(2.0)
celestia:flash("Goodbye, Universe!")
wait(2.0)

In this example we've made two requests to the object named "celestia". Both requests asked the object to perform the same function (the one named "flash"), but we specified different message strings as the parameter to the function in each, causing the object to evaluate the function differently in each case, displaying a different message.

A Simple Function

Now let's write our own function: 

 function flash(message)
  celestia:flash(message)
  wait(2.0)
 end
 
 flash("Hello, Universe!")
 flash("Goodbye, Universe!")

In this example we defined our own "flash" function, to include the 2 second wait. Then we asked the script to perform our new function twice, using a different string each time.

Our new function is named "flash", but it's different from the function of that name which belongs to the object named "celestia". Instead, the new function belongs to our script. When we ask the script to perform our "flash" function, we don't need to write the name of an object or a colon (:). We just write the name of the function, followed by the parameter enclosed in parentheses.

But note that when we defined our new function, we did use the object name and colon, because there we do want to ask the object named "celestia" to perform its function named "flash".

The format of a function definition is another Lua basic. First we write the keyword function. Then we write the name of the function, in this case "flash". Then we write the name of the parameter, enclosed in parentheses. In this case, the parameter is named "message". Then we write the sequence of instructions that the script will follow to perform the function. Finally, at the end of the function, we write the keyword end. (Note that we didn't use quotes around the name of the function or its parameter. We only need quotes for literal strings, not for names.)

In this case, the instructions needed to perform our function are to ask the object named "celestia" to perform its function named "flash" using our function's parameter named "message" as the parameter to the object's function. Then we asked the script to wait for 2 seconds.

Note that first we defined our function, then we called it (twice). (When we say "called", we mean that we asked the script to perform the function.) When we defined the function, we named its parameter "message". And we referred to that name in the instructions we used to specify how the function will be performed. Then each time we called the function, we specified a particular string to be the "message" which the script used when performing the function.

But you can also uses names rather than actual strings in a function call, as in the following example 

 function flash(message)
  celestia:flash(message)
  wait(2.0)
 end
 
 flash("Hello, Universe!")
 farewell = "Goodbye, Universe!"
 flash( farewell)

In this example, we first gave the name "farewell" to the string "Goodbye, Universe!". Then we asked the script to perform our "flash" function using that name, rather than the string itself. The syntax of the instruction by which we gave the name to the string is another Lua basic. It consists of the name, in this case "farewell", followed by an equals sign (=) to indicate that we're assigning the name to what follows, followed by the actual string. The association of a name with a value in this way is called a variable assignment. The reason it's called a variable is that we can later assign the same name to a different value if we choose to. We can also assign a different name to the value. In that case, the value has more than one name. (The parameter name in our function definition is not a variable, strictly speaking, but works very much like one.)

By the way, there's another, slightly different format for function definitions, which we'll use in the next example: 

 flash = function (message)
       celestia:flash(message)
       wait(2.0)
       end
 
 flash("Hello, Universe!")
 farewell = "Goodbye, Universe!"
 flash( farewell)

In the format we've used in this example, the name of the function doesn't come after the function keyword. Instead it comes first, followed by an equals sign (=). Next comes the function keyword, followed directly by parameter enclosed in parentheses. Then comes the sequence of instructions that define the function, ending with the end keyword. The only difference from the way we defined the function previously is the position of the function name, and the addition of the equals sign.

If this new format for a function definition looks a lot like a variable assignment, it's no coincidence: that's exactly what it is. We're simply giving a name to a function, just the way we gave a name to a string in the previous example. We will return to the very important implications of this fact later on. Note that it doesn't matter which format you use. Their meaning is identical.

From this point on, for the sake of brevity, our examples will assume that we've already defined our flash function as in one of the previous examples.

More Examples

Now let's try using another function provided by the object named "celestia": 

 time = celestia:gettime()
 flash(time)

In this example, we asked the object named "celestia" to perform its function named "gettime", and we gave the name "time" to the result (a number) that the object returned to us. Then we asked script to perform our "flash" function, using the number named "time" as the "message" parameter.

No parameters were needed for the object named "celestia" to perform its function named "gettime", so the parentheses following the function name are empty.

The syntax of the instruction by which we gave the name to the result of this function request is another Lua basic. It consists of the name, in this case "time", followed by an equals sign (=) to indicate that we're assigning the name to what follows, followed by the request to the object to perform the function (and return its result).

When you run this script, you'll see a large number briefly displayed. This number is the current time setting in Celestia, expressed as a Julian date. (it's the number of days since the beginning of the Julian epoch).

In the next example, we'll make this clear: 

 time = celestia:gettime()
 timeMessage = "The current time is " .. time .. " (Julian date)."
 flash(timeMessage)

More To Come...

WARNING: Construction area ahead! Proceed at your own risk!

In the next example, we'll convert this to a more recognizable form:

Fortunately, the celestia object has a function to help us do that: 

 jdate = celestia:gettime()
 flash(jdate)
 date = celestia:fromjulianday(jdate)
 flash(date.year)

In this example, we asked the celestia object to give us the time, then asked it to give us the result of converting that Julian date to a calendar date, and finally asked the script to use our "flash function" to display the part of the date that indicates the year.

To display the full date, we'll need to join the parts of the date for the year, month and day: 

 jdate = celestia:gettime()
 flash(jdate)
 date = celestia:fromjulianday(jdate)
 dateString = date.year.."/"..date.month.."/"..date.day
 flash(dateString)

The following additional examples await explanation. In the meantime, you're invited to see if you can figure them out on your own! 

 saturn = celestia:find("Saturn") -- finds object named Saturn
 radius = saturn:radius() -- gets radius of Saturn
 flash("The radius of Saturn is "..radius.." km.")

 flashRadius = function (bodyName)
              body = celestia:find(bodyName) -- finds object 
              radius = body:radius() -- gets radius
              flash("The radius of " .. body:name() .. " is " .. radius .. " km.")
            end
    
 flashRadius("Jupiter")

 jupiter = "Jupiter"
 flashRadius(jupiter)

 reallyBigPlanet = "Jupiter"
 flashRadius(reallyBigPlanet)

 selectedPlanet = celestia:getselection() -- gets the planet currently selected by the user
 flashRadius(selectedPlanet:name())

 flashRadius = function (body)
             if type(body) == "string" then
               body = celestia:find(body) -- finds object 
             end
             radius = body:radius() -- gets radius
             flash("The radius of " .. body:name() .. " is " .. radius .. " km.")
            end
 selectedPlanet = celestia:getselection()
 flashRadius(selectedPlanet)

In this example, we've defined a function to flash a message reporting the radius of a specified planet. Then we called the function twice, to display the radius of two different planets. This should all look familiar to you from previous examples. (In future examples, you should assume our flashRadius function is already defined.) In the next example, we'll do the same thing just a bit differently: 

 planetList = { "Uranus", "Neptune" }
 flashRadius(planetList[1])
 flashRadius(planetList[2])

 planetList = { "Earth", "Moon", "Mars" }
 for index = 1,3 do
   flashRadius(planetList[index])
 end

 planetList = { "Earth", "Moon", "Mars", "Venus", "Mercury" }
 for index,name in ipairs(planetList) do
   flashRadius(name)
 end

 selectedObject = celestia:getselection()
 flashRadius(selectedObject:name())

 cassini = celestia:find("Cassini") -- finds object named Cassini
 saturn = celestia:find("Saturn") -- finds object named Saturn
 cassiniPosition = cassini:getposition() -- gets position of Cassini
 saturnPosition = saturn:getposition() -- gets position of Saturn
 distance = cassiniPosition:distanceto(saturnPosition) -- gets distance from position of Cassini to that of Saturn
 distance = distance-saturn:radius() -- adjusts for distance to surface
 flash("Current distance from Cassini to Saturn's surface is "..distance)

This one is a little more fun: 

 -- tour the moons of Saturn
 obs = celestia:getobserver()
 planet = celestia:find("Saturn")
 obs:goto(planet)
 wait(5)
 flash("Welcome to "..planet:name())
 moons = planet:getchildren()
 for index,body in ipairs(moons) do
   if body:type() == "moon" then
     obs:follow(body)
     obs:goto(body)
     wait(5)
     flash("Welcome to "..body:name())
     wait(1)
   end
  end

 -- tour the stars at random
 obs = celestia:getobserver() 
 stars = celestia:getstarcount() 
 for i = 1,stars do 
  j = math.random(stars) 
  obj = celestia:getstar(j) 
  obs:goto(obj,20) 
  while obs:travelling() do wait(0.5) end 
  celestia:flash("Welcome to "..obj:name(),2) 
 end


back to Celestia/Celx_Scripting
back to Celestia

CELX Lua Methods

This summary describes the support for Lua/CELX-scripting in Celestia and consists mostly of the CELX API. This documents as well as the CELX-support in Celestia probably contain a number of errors or bugs. Please report any problems you find.

Introduction

About this document

It was started to document the available functionality during development celestia v1.3.1pre11, and was then extended as new functionality was contributed.

CELX uses the Lua Programming Language, so you are writing real programs. This is completely different than older CEL Celestia scripts, which are just sequences of fixed commands. So you probably should have a little experience in programming, otherwise this document won't help you much.

It's also a good idea to read at least the first sections of the Lua-Documentation, available here:

How CELX works in Celestia

Celestia works roughly(!) by repeating this:

  • Check user input, change rendering settings accordingly (e.g. enable rendering of orbits, change observer position/orientation)
  • Update the simulation time
  • Update the observer's position if goto is active
  • Render all objects using the current settings (renderflags, time. positions)

If a CELX script has been started, it is executed just before rendering begins. Then Celestia gives control to the Lua interpreter, which continues to execute the script where it stopped the last time. When a CELX method is called in a script, e.g. celestia:print(), the Lua interpreter invokes a small C++ function which converts the arguments from Lua types to C++ types, calls the right Celestia-methods to perform the action, and, if necessary, converts the C++ return value back to a Lua value. Note that the Lua interpreter called this C++ function, so when the function returns, the script continues: there is never a chance to return control back to the Celestia loop. To do this, the script has to call the wait() function, which makes the Lua interpreter return control.

Forgetting to call wait() in Celestia 1.3.1 meant that Celestia never gained control again, and thus couldn't handle the command to stop or quit the script - it was completely blocked. Starting with version 1.3.2, Celestia periodically checks if the script has exceeded the maximum allowed time to execute (5 seconds), and if it has, it terminates the script.

It should be apparent that most actions don't really change anything immediately. Instead, scripts change a setting which is used later on during rendering, which from the point of view of the script happens while calling wait(). So if the position of the observer is changed ten times without calling wait() in between, this will have no effect - only the last position will actually be used in rendering.

Syntax

For a complete description of the syntax of Lua, please read http://www.lua.org/manual/5.0/
Celestia version 1.5.0 uses Lua version 5.1, which differs slightly from version 5.0 of Lua, used in earlier Celestia releases.
The Lua 5.1 manual can be found at http://www.lua.org/manual/5.1/
For details about what changed between Lua versions 5.0 and 5.1, see http://www.lua.org/manual/5.1/manual.html#7

Some quick starting notes:

  1. Lua commands can be terminated either by a textual line terminator or by a semicolon. To include several Lua commands on a single line of text, separate them by semi-colons (;), but if there is only a single Lua command on a line of text, no semi-colon is needed.
  2. Write your CELX script by using a line editor like "Notepad", "Notepad++" or "Wordpad", without text formatting;
  3. Short (singleline) comments start with two hyphens "--";
  4. Long (multiline) comments use "--[[ comment ]]".
  5. When you use the comment "-- Title: string:text" in the first line of the CELX script, the string:text title will be displayed in the Celestia/File/Scripts drop down menu instead of the filename.

Example: 

-- Title: Example script
-- This is a short comment line.
-- [[ This
      is
      a
      long
      comment
      line.]]
a = 5; b = 6 -- two Lua commands on a single line
c = 3        -- one Lua command on a line

Variables & Types

Lua variables don't have to be declared and don't have a type, but the content has a type.

There are eight basic types in Lua:

  1. nil
    • Nil is the type of the value nil, whose main property is to be different from any other value; it usually represents the absence of a useful value.
  2. boolean
    • Boolean is the type of the values false and true.
      Both nil and false make a condition false; any other value makes it true.
  3. number
    • Number represents real (double-precision floating-point) numbers.
  4. string
    • String represents arrays of any 8-bit characters.
  5. table
    • Tables can be used as arrays that can be indexed not only with numbers, but with any value (except nil).
      Tables also can contain values of all types (except nil).
  6. userdata
    • The objects to control Celestia are of this special type userdata.
  7. function
    • The function type is an executable expression, compiled from a block of Lua and CELX code.
  8. thread
    • Not further explained here.

Example:
The same variable "a" can have content of different type. 

a = 1                -- a is 1, an integer number
a = a / 2            -- a is now 0.5, changed into a floatingpoint number
a = "Hello World"    -- a contains a string now 
a = a / 3            -- ERROR, because a string is divided by a number! 
a = true             -- a is true, a boolean
a = not a            -- a is now false, a boolean

Example:
A table can be used like this. 

t = {}                                  -- define Table t
t["key1"] = "value1"                    -- long form to store a string
t.key2 = "value2"                       -- short form to store a string
u = { key1="value1", key2="value2" }    -- u is now the same as t 
v = { 1,2,3,4,5 }                       -- v[1] is now 1, v[2] is 2, etc.

To operate on userdata, you can call methods for the objects. To use Lua for Celestia, you mostly need to know only about the available objects, the methods defined on them and how to call them - everybody who already knows Object-Oriented-Programming should feel right at home.

At the beginning of a script, the celestia object is automatically defined, holding a reference to the core-functionality of Celestia! To operate on this celestia object you can call methods which are defined on it by using the "celestia:" prefix, as shown in section celestia methods.

Example: 

-- Get observer instance of the active view and store it in "obs"
obs = celestia:getobserver()

-- Find the celestial object representing Earth and store it in "earth"
earth = celestia:find("Sol/Earth")

-- Do something to confuse the reader, but possible in CELX
-- The object with name mars is made equal to the object with name earth
mars = earth

-- You can also use obs and earth like this.
obs:goto(earth)
-- This will start the goto-command, which moves the observer to Earth,
-- just as if you had pressed the [G] key in Celestia, after selecting Earth.

A function is an executable expression, compiled from a block of Lua and CELX code, whose value has type function.

A function can have arguments for input values and a function can also return zero, one or more values (see the Lua-documentation for details).

One or more functions can be defined at the beginning of your CELX script and they can be called once or several times from the main body of your CELX script.

Example: 

-- Define function with name "add_one" and parameterlist "i" (a number).
function add_one(i) 
   -- use 'local' to declare variables local to function: 
   local j = i + 1 
   -- return the value of "j", a number.
   return j 
end

-- Define function with name "divide" and parameterlist "i, j" (two numbers).
function divide(i, j) 
   -- return the value of the division "i / j", a number.
   return i / j 
end

-- Start of the main body of your script
<... other script code ...>
-- and now call the functions: 
a = add_one(1) 
b = divide(a, 2)
<... other script code ...>

The function "wait(number:n)" is predefined in Celestia and waits number:n seconds. It is special because it returns control to Celestia, which you have to do to avoid blocking Celestia.

Many more functions are defined in Lua (see Lua-docs), such as mathematical functions or string operations.

Notes:

  1. Not all Lua-libraries are loaded, you don't have access to io and debug-functions (which greatly reduces the danger of security problems from "evil" scripts). See the method celestia:requestsystemaccess() for more information.

Control Structures

Lua has the typical control structures, like for, while, repeat and if.

Examples: 

-- Execute the block of codelines (...) 10 times after each other,
-- where "i" is incremented with 1 during each loop.
for i = 1, 10 do 
   ... 
end

-- Execute the block of codelines (...)
-- as long as "i" is smaller than or equal to 11.
i = 1 
while i <= 11 do 
   ... 
   i = i + 1 
end

-- Execute the block of codelines (...) 
-- until "i" is equal to "j".
i = 1
j = 22
repeat 
   ... 
   i = i + 1 
until i == j

-- Compare "i" and "j" with each other and execute a
-- certain block of codelines (...1, ...2 or ...3),
-- depending on the result of this comparison.
if i > j then 
   ...1
elseif i < j then 
   ...2 
else 
   ...3
end

-- To loop over the contents of a table "tbl", you can use this:
for key, value in pairs(tbl) do
   -- tbl[key] == value
   ...
end

-- Use this for tables used as arrays, i.e. indexed by numbers 1..n: 
for i, value in ipairs(tbl) do	
   -- tbl[i] == value
   ... 
end

Objects and Methods (The CELX API)

This section documents the userdata classes (object types) available in CELX Lua scripting.

Besides the predefined celestia object, there are also other celestia related objects to control Celestia. You can't create an object (i.e. userdata) yourself, you must call some method to create one. As you only have the celestia object (ignoring methods which are not Celestia related) available when the script is starting, you must use it to create other objects.

The following celestia related objects can be used within a CELX script:

  1. Observer object:
    An observer object is used to access properties specific to a view, such as viewer position, viewer orientation, frame of reference, and tracking status. To operate on an observer objects, you can call observer methods which are defined on them, as shown in section observer methods.
  2. Object objects:
    An "object" object in CELX refers to a celestial object like a planet or a star. To operate on "object" objects, you can call "object" methods which are defined on them, as shown in section object methods.
  3. Position objects:
    A position object contains the exact coordinates of a point in space. To operate on position objects, you can call position methods which are defined on them, as shown in section position methods.
  4. Vector objects:
    A vector object is a geometric object that has both a length and direction [X,Y,Z] in a 3-dimensional Coordinate System. To operate on vector objects, you can call vector methods which are defined on them, as shown in section vector methods.
  5. Rotation objects:
    A rotation object is internally a Quaternion, which is one possibility to mathematically describe a rotation in 3 dimensions (i.e. it can be converted to a rotation matrix). A rotation can also be used to describe the orientation of objects or the observer (i.e. where the observer is looking to, and where "up" is). To operate on rotation objects, you can call rotation methods which are defined on them, as shown in section rotation methods.
  6. Frame objects:
    The frame object describes the celestia coordinate cystem and tells how the X, Y, and Z, axes of each 3-dimensional coordinate system are aligned. Coordinate systems are well documented in the available Celestia .Cel Scripting Guide v1-0g by Don Goyette, in the chapter: "Coordinate Systems". To operate on frame objects, you can call frame methods which are defined on them, as shown in section frame methods.
  7. Phase objects:
    The timeline of an object can be subdivided into one or more phases. Each phase object has its own trajectory, rotation model, orbit frame, and body frame. To operate on phase objects, you can call phase methods which are defined on them, as shown in section phase methods.
  8. CELscript objects:
    A CELscript object contains a string with a valid CEL script, which can be imbedded in a CELX script by using the "celestia:createcelscript()" method. To operate on CELscript objects, you can call CELscript methods which are defined on them, as shown in section CELscript methods.

Example:
To call the method getposition() of observer, you have to get an observer-instance from celestia first and then call getposition() on it: 

obs = celestia:getobserver() 
pos = obs:getposition()

Notes:

  1. While using names for the various classes in this documentation, these names have no real meaning in a script. Even "celestia" is just a variable, holding an object of type celestia and is not really special.

In the following section, each method is listed with its signature:

return_value_type object:methodname(type:parameter, type:parameter [, type:optional parameter])

This is followed by:

  • A short description of what the method does;
  • A list of the arguments/parameters and what they are for;
  • Possibly some notes about how to use this method, what it does exactly, some concerns etc..
  • Finally an example about the usage of the method is given.

Object and method index

celestia

observer

object

position

vector

rotation

frame

phase

1.6.0 Phases available only in Celestia 1.6.0 and later

celscript

Object and method index (alphabetical)

celestia

celscript

frame

object

observer

phase

1.6.0 Phases available only in Celestia 1.6.0 and later

position

rotation

vector

Callbacks

Callbacks are functions which are executed as a result of external events.

Right now there are two callbacks available in Celestia:

Note: Callbacks are limited in what you can do:

  • The callback must complete within 1 second, or it will be terminated;
  • You CANNOT use the wait() function in a callback !

CEL to CELX migration

The following section contains an index of the available CEL commands. By clicking on a specific command, you will be routed to the explanation on its functionality and how that CEL command can be migrated to equivalent CELX objects and methods.

CEL command index

The CEL commands below are organized following the sequence and explanation of CEL script commands in Celestia .Cel Scripting Guide v1-0g by Don Goyette. The explanations also contain many of Don's examples and syntax descriptions to aid in the migration from CEL to CELX.

Within this section, parameter values for CEL commands and CELX methods are printed like <type> or <name>. These parameter values need to be replaced when actually using these commands or methods.

Example: 

<string>    "Sol/Earth"
<duration>  1.5
<distance>  20000

Since Celestia version 1.6.0 and 1.6.1 the original listing of only 35 Cel commands has been expanded to 52 Cel commands. The additional commands are indicated with 1.6.0 and 1.6.1.

  1. cancel
  2. 1.6.0 capture
  3. center
  4. changedistance
  5. chase
  6. cls
  7. 1.6.0 constellationcolor
  8. 1.6.0 constellations
  9. 1.6.0 deleteview
  10. 1.6.0 exit
  11. follow
  12. goto
  13. gotoloc
  14. gotolonglat
  15. labels
  16. lock
  17. lookback
  18. mark
  19. move
  20. orbit
  21. 1.6.0 orbitflags
  22. preloadtex
  23. print
  24. renderflags
  25. 1.6.0 renderpath
  26. rotate
  27. select
  28. set
  29. 1.6.0 setactiveview
  30. 1.6.0 setambientlight
  31. setfaintestautomag45deg
  32. setframe
  33. 1.6.0 setgalaxylightgain
  34. 1.6.0 setlabelcolor
  35. 1.6.0 setlinecolor
  36. setorientation
  37. setposition
  38. 1.6.0 setradius
  39. setsurface
  40. 1.6.1 settextcolor
  41. 1.6.0 settextureresolution
  42. seturl
  43. setvisibilitylimit
  44. 1.6.0 singleview
  45. 1.6.0 splitview
  46. synchronous
  47. time
  48. timerate
  49. track
  50. unmark
  51. unmarkall
  52. wait

Notes

Typical Problems

  • Lua scripts are executed between Celestia's rendering phases. So if you do some lengthy calculation (or an endless loop), Celestia won't be able to update the screen or even check for key presses (i.e. you can't stop the script by pressing [Esc] key). From the script's point of view, rendering and UI-handling only happen during calls to wait(). If the script doesn't return control to Celestia for more than 5 seconds, then the script is terminated.
  • If you want to move the observer smoothly, do this by setting its position and then call wait(). But watch out: if "track" is activated on a body this can override any observer:setorientation() in the script. A high time rate will change the position of planets significantly before they are rendered, which can result in a jerky movement. If necessary, check and reset time and timerate in your script.
  • On Windows wait() can return very quickly without doing any rendering, while on Linux it reliably enforces a rendering pass.
  • The user can change settings while a script is running, including which body is selected, position, orientation, speed, timerate, renderflags etc. Don't rely on these to stay constant, if necessary you have to continuously reset them.
  • Reference frames can be difficult to master at first. If you are trying to set the observer to a position within the Solar System, but get distances to the Sun of about 206 au instead, you probably got your reference-frame wrong. Before version 1.5.0, 206 AU is the distance between the point of origin [0,0,0] in universal coordinates and the position of the Sun. Starting with version 1.5.0, Celestia places the Solar System's barycenter at [0,0,0].
  • If your script turns your screen completely black or other weird effects occur, check for any usage of observer:setorientation() or observer:lookat(). You probably have your orientation set to an "invalid" quaternion (for example all zero), possibly by using observer:lookat() with your up-vector parallel to the direction of view. If this happens, you should get Celestia usable again by running a script which sets the orientation to some sensible value (or simply by restarting Celestia).

CELX Questions and Answers

Introduction

This page is intended to be a repository of practical questions and answers (Q&A) on the subject of CELX Scripting. There are two ways to get something listed here:

- Just list your general questions in the Q&A section below, and someone will post an answer to them. Please post discussions about a specific answer (e.g. requests for clarification) to that answer's discussion page. Unfortunately, however, few, if any, CELX programming experts peruse this WikiBook on a regular basis.

or (preferred)

- Post your question on the Celestia Scripting Forum. Once the answer is determined to your satisfaction there, please transcribe the question and summarise the final answer here so that we can build up a knowledge base in this WikiBook.

Q&A

How do I calculate the angle between two objects?

Answer

How do I assign a CELX function to a particular key on the keyboard?

Answer

The questions & answers below have been moved here from one of the "discussion" pages. Those pages are for discussing issues related to editing WikiBook pages, not for providing content for a WikiBook.

If there's something that isn't clear, ask about it here.

Just click on the "edit this page" button immediately above and start typing. Or click on one of the [edit] buttons in this page and insert a new question or answer at its bottom.

Test Scripts and Questions

Using the very first, very simple CELX example script here, to wit:

celestia:flash("Hello, Universe!")
wait(2.0)

The "flash" function is defined within the object "Celestia." When this script is executed, I expected it to do nothing more than display the text "Hello Universe!"

Prior to executing this script, I had centered the Earth in my Celestia window, and I was in the "Follow" mode. When I execute this script, the viewpoint changes so that the Earth gets moved to one side or the other prior to seeing the "Hello Universe!" message.

Am I correct in thinking that this movement is caused by Celestia's definition of the "flash" function? In other words, the "flash" function in Celestia itself probably includes some movement function to be executed. Yes?

No. I don't see the earth move when I try this. How are you running the script?



After investigating the properties of the "flash" and "print" functions in Celestia, I tried the following script to center the message on my display. This also causes movement of the Earth, even though I thought I centered everything on the screen since I'm using 0 (zero) in the parameters list. Can anyone explain what's going on here?

celestia:print("Hello Universe!", 5, 0, 0, 0, 0)
wait (5)

I don't see this either. May be same problem as above.
Mystery explained... Open Scripts dialog and I double-clicked on the celx script in order to open it. If I simply use the dialogs provided by Celestia to open the script, the movement does not occur. Thanks.
In other words, do NOT double-click on the file name. Simply click on the OPEN dialog box.
One other note... If I do this using a CEL script, there is no apparent effect on the CEL script.

How do I execute celx scripts on Debian GNU/Linux (celestia 1.6.1)? I attempt with $ celestia --url test.celx and I greeted with invalid option -- '-'

Celestia on linux currently does not support the --url parameter. Celx scripts can be executed with the parameter "-f /path/to/script.celx". Note the script path must be the fully explicit path and not the relative path. See debian bug #682258

Test script from the BrainDead

  flashRadius = function (bodyName)
  body = celestia:find(bodyName) -- finds object 
  radius = body:radius() -- gets radius
  celestia:flash("The radius of " .. body:name() .. " is " .. radius .. " km.")
  wait(2.0)
  end
     
  flashRadius("Mercury")
  flashRadius("Venus")
  flashRadius("Earth")
  flashRadius("Mars")
  flashRadius("Jupiter")
  flashRadius("Saturn")
  flashRadius("Uranus")
  flashRadius("Neptune")
  flashRadius("Pluto")
  flashRadius("Charon")

  function flash(message)
  celestia:flash(message)
  wait(2.0)
  end

  message = "End of this test script"
  flash = celestia:flash(message,5)
Important point in the above... The variable "message" must be defined prior
to execution of the "flash" function or the script causes an error which says
that it expected a string. This makes sense. Still learning here.
I'm really confused by this though. How is it that this script shows the
text "End of this test script" if the flash function has been defined,
but it has NOT been called? In other words, why don't I need a line
which calls the function? i.e. - flash(message)
You didn't call "flash", but you did call "celestia:flash". The statement:
   flash = celestia:flash(message,5)
calls the "flash" method of the "celestia" object (that's what the right side of the assignment says to do) and then assigns the result (nil) to the variable "flash", redefining it. Probably not what you wanted. You only do an assignment to the "flash" variable when you define the function. Remember that:
   function flash(message)
   celestia:flash(message)
   wait(2.0)
   end
is equivalent to:
 flash =  function (message)
   celestia:flash(message)
   wait(2.0)
   end
The function name "flash" is just another variable. HankR 17:59, 18 October 2005 (UTC)
Okay, I think I understand what you mean. Appreciate the help.--BrainDead 22:45, 18 October 2005 (UTC)

Another test script

   camera = celestia:getobserver()
   tethys = celestia:find("Sol/Saturn/Tethys") -- finds object named Tethys.
   celestia:select(tethys) 
   camera:center(tethys,5)
   wait(5)
   camera:follow(tethys)
   cameraPosition = camera:getposition() -- gets position of observer.
   tethysPosition = tethys:getposition() -- gets position of Tethys.
   distance = tethysPosition:distanceto(cameraPosition) -- gets distance from position of Tethys to observer.
   celestia:flash("Current distance to Tethys is "..distance.. " km",5)
   wait(5)
   celestia:flash("Let's have a look...",5)
   wait(5)
   obs=celestia:getobserver()
   obs:gotodistance(tethys,10000,5)
   wait(5)
   celestia:flash("Here it is!",5)
   wait(5)
   newPosition = obs:getposition() -- gets NEW position of the observer.
   newdistance = tethysPosition:distanceto(newPosition) -- gets distance from position of Tethys to new observer position.
   celestia:flash("Current distance to Tethys is "..newdistance.. " km",5)
   wait(5)
Okay, this works, but I have questions again... First, thanks to Malenfant for the idea here.
How do I round the values presented by tethysPosition and newdistance?
Use <"Current distance to Tethys is "..string.format("%i",newdistance).." km"
Why does the newdistance value not show either 10000km or the value shown on Celestia's display?
Celestia's display shows the distance to the surface, you calculated the distance center to center. Plus, Tethys has moved since the time when you got its position. You calculated the distance to its old position, not its current position. You need to get the position again. Anytime you call wait(), time will pass and things will move. HankR 03:31, 24 October 2005 (UTC)
I'm still trying here. --BrainDead
Thanks again for the help, Hank. I understand this one now.--BrainDead 10:46, 24 October 2005 (UTC)

Corrected Script

   myobject = celestia:find("Sol/Saturn/Tethys") -- finds object named Tethys.
   celestia:select(myobject) 
   celestia:center(myobject,5)
   wait(5)
   celestia:follow(myobject)
   camera = celestia:getobserver()
   cameraPosition = camera:getposition() -- gets position of observer.
   tethysPosition = myobject:getposition() -- gets position of Tethys.
   distance = tethysPosition:distanceto(cameraPosition) -- gets distance from  position of Tethys to observer.
   celestia:flash("Current distance to Tethys is "..string.format("%i",distance).." km",5)
   wait(5)
   celestia:flash("Let's have a look...",5)
   wait(5)
   celestia:gotodistance(tethys,10000,5)
   wait(5)
   celestia:flash("Here it is!",5)
   wait(5)
   obs=celestia:getobserver()
   newPosition = obs:getposition() -- gets NEW position of the observer.
   newdistance = tethysPosition:distanceto(newPosition) -- gets distance from position of Tethys to   new observer position.
   celestia:flash("Current distance to Tethys is "..string.format("%i",newdistance).." km",5)
   wait(5)
This revision of the script corrects the errors I had earlier, and it reflects an integer value.
Can I ask though, HOW you knew about the integer correction? I can find that nowhere in any of
the documentation I have.
It's in the Lua 5.0 reference manual.
Where did you find "..string.format("%i").." and can I display, say two decimal places? Perhaps
using something like "..string.format("%2")???? --BrainDead 00:33, 25 October 2005 (UTC)
string.format uses a C-style output format control string. Use "%.2f" for two decimal places.
PS - Am I okay with the format here? Should I NOT post so much script? Should I use different
headers? Sorry, just me... Confused ol' Bob
It might be helpful if this material were reformatted as a FAQ page for CELX. Put each question in a separate section with the question as the section title. This would make it more useful for others.HankR 01:05, 25 October 2005 (UTC)


Angles Between Two Objects

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:

 


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:

 

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)

Assigning Custom Key Functions with CELX

With CELX it's easy to create custom key functions, and assign them to different keys on your keyboard. Here's how:

First, you create a Lua function using CELX to implement your custom function. In this example, we'll create a new key function which zooms the active view so that the currently selected object fills the view: 

 zoomToFit= function()
    obs = celestia:getobserver()
    obsPos = obs:getposition()
    sel = celestia:getselection()
    if sel == nil or sel:name() == "?" then return end
    selPos = sel:getposition()
    dist = obsPos:distanceto(selPos)
    rad = sel:radius()
    appDia = 2*math.atan(rad/dist)
    obs:setfov(appDia*1.20)
    celestia:flash("Zoom to fit "..sel:name(), 2) 
   end

Next, you create a table which maps a selected key to your new function. In this example, we'll use the "z" key: 

 keymap = {
    z = zoomToFit
 }

Then, you create a key handling function to call your new Lua function when the desired key is pressed, and assign it as the Celestia keyboard callback: 

   celestia_keyboard_callback = function(key) 
       f = keymap[key]
       if f then 
          f() 
          return true
       end
          return false
   end

Note that when there's a custom key definition for the input key, the callback returns true to indicate to Celestia that no further processing of the key is needed. Otherwise it returns false, and Celesta will handle the key according to the built-in key function assignments.

Finally, you tell Celestia that you want the callback to be called when a key is pressed, and then you wait for input: 

   celestia:requestkeyboard(true)
   repeat
       wait(10)
   until false

Note that the script has an infinite loop, so you'll need to use the escape key to terminate it.

Once you've got the basic script, you can assign other new key functions simply by defining the Lua functions to implement them, and adding them to the key map.

Give it a try!


Download the script

Below you can find the whole script (without comments) in a single text block. Copy everything in the grey box and paste it into a text file in your favourite text editor, and save that file in your scripts directory as zoomtofit.celx. Then open it (File/Open Script) from within Celestia to see the script in action. 

-- Zoom To Fit function script
syntaxhighlight lang="text"
zoomToFit= function()
  obs = celestia:getobserver()
  obsPos = obs:getposition()
  sel = celestia:getselection()
  if sel == nil or sel:name() == "?" then return end
  selPos = sel:getposition()
  dist = obsPos:distanceto(selPos)
  rad = sel:radius()
  appDia = 2*math.atan(rad/dist)
  obs:setfov(appDia*1.20)
  celestia:flash("Zoom to fit "..sel:name(), 2) 
 end

keymap = { z = zoomToFit }

celestia_keyboard_callback = function(key) 
     f = keymap[key]
     if f then 
        f() 
        return true
     end
        return false
 end

celestia:requestkeyboard(true)
repeat
     wait(10)
until false

</syntaxhighlight>

Distinguishing upper from lower case

Unfortunately, the example above does not distinguish between the typing of upper case (capital) letters and lower case letters.

When Celestia calls the function celestia_keyboard_callback, the function's argument ("key" in this example) contains the letter that was typed. A simple string of IF statements can distinguish among them: 

 celestia_keyboard_callback = function(key) 
      if key == "F" then 
         zoomToFit() 
         return true
      end
         return false
  end

This form of the callback calls the function zoomToFit if an upper-case F is typed, but lets Celestia handle all other letters, including lower-case f.

Configuring Celestia: celestia.cfg

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"    ]

Catalog Files: Defining new Objects

Types of Catalog Files

Celestia's universe contains three broad categories of objects:

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.

SSC: Solar System Catalogs of Planets and their Satellites

Introduction

Celestia uses catalogs to define its objects. It loads SSC catalogs only once, when it starts. First it loads the ones in its data directory in alphabetical order, then it loads the ones in the extras directories, also in alphabetical order.

What's an SSC file?

"Solar System Catalog" files are primarily used to define the objects which can be found in a stellar system, such as planets, moons, asteroids, comets, and spacecraft. They also have four other uses: they can define alternative surface textures, locations on or near an object, and orbital reference points. An SSC file can also edit objects which have been defined in other SSC catalog files.

  • Objects are defined by specifying a quoted name, the quoted path to the object, and a list of parameters. The type of object is specified by a Class statement among its parameters or will be assumed from the Radius specified for it.
  • Alternative surfaces are defined by prefixing the object's name by the keyword AltSurface. Their definitions can include any of the parameters related to surface textures.
  • Location labels are defined by prefixing the object's name by the keyword Location. Their definitions use special keywords.
  • Orbital reference points are available only in Celestia v1.5.0 or later. They are defined by prefixing the object's name by the keyword ReferencePoint. Their definitions can include any of the parameters related to orbits or trajectories.
  • Editing a previously defined object can be done by prefixing the object's name by one of the keywords Modify or Replace. The revised definition can include any of the parameters used to define objects.

SSC catalog files are either in the "data" directory of the Celestia root or in an Add-on's root subdirectory (itself in Celestia's extras directory).

Celestia's catalog files are plain text files, and can thus be modified with your favourite text editor. As with other code, the text must use straight ("dumb") quotes, not curly ("smart") quotes; for some text editors you will have to disable smart quotes.

Celestia uses the file Celestia/data/solarsys.ssc to define most of the bodies that are in our own Solar System.

Structure of an object definition

"object name" "object path" { ...parameters... }


The first elements in an SSC object's definition are its name and its "path".

object name = Name of the object, in quotes (e.g. "Mercury"). Provisional designations (e.g. "S/2006 S 5") are okay but won't be able to have secondaries (see below: confusion is caused by the "/" character.). As of Celestia 1.6.0, multiple names separated by colons are allowed ("Eris:2003 UB313").

object path = The sequence of primaries that lead to the object; in other words, the bodies that it orbits around. Paths start with a star and work down from there.

The path separator is a forward slash ("/"). For example, "Mercury"'s path is just "Sol". The path of "Romulus" and "Remus", the moons of the minor planet "(87) Sylvia", are both "Sol/(87) Sylvia". The path of a Lunar Excursion Module (LEM) on the surface of the Moon would be "Sol/Earth/Moon". Paths are also used in Celestia's browser menus.
Because of the path separator used by Celestia, the names of objects known only by their provisional designations may need to be represented differently should they have secondaries. Alternatively, one could represent the slash ("/") by a "fraction slash" (HTML "&frasl;" or "&#8260;" : "⁄") or a vertical bar ("|").

The object's descriptive parameters follow within the accolades ("braces" or "squiggly brackets": {} )

Representing colors

Color [ R G B ]

Colors are represented using the R G B (red green blue) convention. Each of the three numbers in the 0.0 to 1.0 range represents the saturation of that colour component. [0.0 0.0 0.0] is black, [1.0 1.0 1.0] is white, [1.0 0.0 0.0] is pure red, and so on.

Comments

#

The pound sign ("crosshatch" or "sharp sign") begins a comment: whatever lies after this sign up to the next line terminator is ignored by Celestia.

Object parameters

Below is an alphabetical list of the parameters used to define an SSC object. Some of these parameters themselves require another list of parameters within {}.

Albedo f

Deprecated in 1.7

The Bond albedo of the object: a number between 0.0 and 1.0 (black to white, perfect absorber to perfect reflector). This determines the brightness of the point used to represent the object when it is too small to draw. If set to 0, the object is never drawn.

Actual calculations in pre 1.7 versions treat this parameter as Geometric albedo, so in 1.7 it was deprecated and replaced with GeomAlbedo, old Albedo is an alias for GeomAlbedo. To represent Bond albedo a new parameter was added, BondAlbedo.

Atmosphere { ...parameters... }

Defines an object's atmosphere. This is not part of the surface texture of an SSC object. It's drawn surrounding the object. The possible parameters within the accolades ("{ }") are the following (some text from this forum thread):

CloudMap "filename"

The cloud texture (a transparent png or dds).
For more information, see the page Celestia/Textures.

CloudNormalMap "filename"

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.
For more information, see the page Celestia/Textures#Cloud_Layer_Normal_Maps.

CloudHeight f

The cloud altitude in kilometres.

CloudSpeed f

The cloud speed in km/h (in the direct rotation direction?).

Height f

Thickness of the atmosphere in kilometres. This parameter doesn't affect rendering of Mie/Rayleigh atmospheres, but the value determines if Celestia bothers rendering the vertical profile of the atmosphere. So high values make the atmosphere show up correctly even at high distances.

Mie f

The amount of Mie-scattered light. It gives a hazy appearance, but I don't understand Mie theory to be honest. Pushing the value too high makes the atmosphere go crazy instead of giving a thick appearance. Low values don't quite give a desired look of a thin atmosphere, like for Pluto.

MieScaleHeight f

Pretty much what it says. But it appears that a high value also makes the atmosphere go crazy thick instead of just scaling it vertically.

MieAsymmetry f

Determines the amount of forward- and back-scattered light.

Rayleigh [ R G B ]

The amount of red, green and blue light scattered by Rayleigh-scattering. In reality, it is proportional to (1/wavelength)^4. Using r=630nm, g=540nm and b=450nm I get relative intensities of r:g:b = 0.260:0.482:1. Also it seems Rayleigh scattering uses the MieScaleHeight parameter for scale height.

Absorption [ R G B ]

The amount of red, green and blue light absorbed.

The following parameters are deprecated in Celestia v1.5.0 and later. Mie and Rayleigh scattering parameters should be used instead.

Lower [ R G B ]

Colour of the atmosphere near the surface.

Upper [ R G B ]

Colour of the atmosphere near its top.

Sky [ R G B ]

Colour of the sky when seen from inside the atmosphere.

Sunset [ R G B ]

Colour of the sunset.

Beginning f or "YYYY MM DD HH:MM:SS"

Specifies a time before which the object doesn't exist.

The Beginning time may be provided as a floating point number, in which case it is interpreted an astronomical Julian date, or it may be provided as a quoted string, in which case it is interpreted as a Gregorian date.

If it is a quoted Gregorian date, YYYY MM DD = year, month, day (integers); HH:MM:SS = hour, minute, second (integers). Since version 1.3.1, Celestia converts these time-stamps into Julian Dates internally. A date to Julian Date and back converter can be found at the U.S. Naval Observatory.

BondAlbedo f

Available only in v1.7.0 or later.

The Bond albedo of the object: a number between 0.0 and 1.0 (black to white, perfect absorber to perfect reflector). This determines the temperature of the object.

BumpHeight f

Defaulting to 2.0, the f parameter defines the vertical scale of the Bumpmap.

BumpMap "filename"

A texture file (JPG, PNG, or DDS) used to generate relief.

For more information, see the page Celestia/Textures.

BlendTexture bool

The "bool" argument is either true or false. BlendTexture is used with "Color" to colorize the surface texture image. The Texture's individual color channels are multiplied by the corresponding Color values.

Class "class"

Class of object: one of planet moon spacecraft comet asteroid invisible. By default, Celestia assigns Class based on the object's Radius. It is used by Celestia's View Options menu and determines the color of the orbit path drawn for this body. You could assign an artificial satellite to the "moon" class so its orbit is displayed along with those of the true moons. An object with a class of invisible is not drawn. It can be used as an orbital barycenter, orbited by one or more visible objects.

1.6.0 Celestia 1.6.0 adds several new object classes. The complete list of object types is:

  • planet
  • moon
  • dwarfplanet
  • minormoon
  • asteroid
  • comet
  • spacecraft
  • surfacefeature
  • component
  • diffuse
  • invisible

Celestia treats planet, moon, dwarfplanet, minormoon, and asteroid as identical except for when showing labels and orbit paths in the 3D window, and object categories in the solar system browser. Whether an object is a planet or dwarf planet can be decided based on the criteria set forth in the IAU's 2006 resolution on the definition of a planet. Ultimately, it doesn't make too much difference in Celestia: the orbit and label of the body can be colored differently, but that is all. Asteroid is not a category officially defined by the IAU, but in Celestia this class is used for any natural, solid object that orbits a star and is too small to be a dwarf planet (i.e. it doesn't have enough mass to assume an ellipsoidal shape) and is not a comet.

A moon is a natural object in orbit around a planet. The distinction between moon and minor moon is arbitrary: Mars's two small satellites are both classified as moons, while dozens of objects of similar size orbiting the outer planets are minor moons. The minor moon class was introduced to eliminate the distracting clutter of moon orbits around the outer planets of the Solar System; a user now has a choice of whether or not to display the orbits of the swarm of rocks orbiting Jupiter, Saturn, Uranus, and Neptune.

Comets are treated very much like asteroids, but are drawn with dust tails when sufficiently close to the Sun and labeled in a distinct color. Some objects in the Solar System have both comet and asteroid designations, such as Chiron. Such dual classification is not possible in Celestia.

Human-made objects traveling through space should be assigned the class spacecraft. In addition to affecting label and orbit color, slightly different information is displayed for spacecraft than for natural objects. The surface feature class should be used for buildings and other landmarks fixed to the surface of a planet, moon, or asteroid. Objects floating in space are rendered as points of light when they occupy less than a pixel on screen. This effect looks unrealistic for objects on the surface of a planet, and so it is disabled by default for surface features. The component class is used for parts of either surface features or spacecraft that are defined as separate objects in an ssc file. As with surface features, they aren't shown as points of light at a distance.

The diffuse class should be used for gas clouds, dust plumes, and the like. By default, diffuse objects cannot be selected by clicking. They are also not labeled or visible at a distance as a point of light.

Class Visible Visible
as Point 		Labeled Clickable Planetshine
planet Yes Yes Yes Yes Yes
moon Yes Yes Yes Yes Yes
dwarfplanet Yes Yes Yes Yes Yes
minormoon Yes Yes Yes Yes Yes
asteroid Yes Yes Yes Yes Yes
comet Yes Yes Yes Yes Yes
spacecraft Yes Yes Yes Yes No
surfacefeature Yes No Yes Yes No
component Yes No Yes Yes No
diffuse Yes No No No No
invisible No No No No No

Warning: LongLat does not place objects correctly when used with Class "surfacefeature" in Celestia v1.5.0 and later. Use FixedPosition [ x y z ] or FixedPosition { Planetographic [ Long Lat Alt ] } instead.

Color [ R G B ]

Colorizes the object when there is no texture. Also specifies the color of the albedo point when the object is too small to resolve.

R, G and B should have values between 0 and 1, inclusive.

CustomOrbit "orbit name"

Invokes built-in high-precision orbit computations, such as "vsop87-mercury". CustomOrbit overrides EllipticalOrbit. If an invalid orbit name is provided, CustomOrbit is ignored.

For details, see Celestia/Trajectories, section CustomOrbit.

EllipticalOrbit { ...parameters... }

Defines an elliptical orbit (the generic case).

EllipticalOrbit parameters correspond to traditional Keplerian orbital parameters. A description of those parameters is in the Astrodynamics WikiBook, in its chapter on Classical Orbit Elements.

For more information, see Celestia/Trajectories, section EllipticalOrbit.

Eccentricity f

Optionally determines the shape of the orbit. In fact, the name EllipticalOrbit is a bit misleading since 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
Note: An eccentricity of exactly 1 does not work in Celestia.
If Eccentricity is not provided, a circle is assumed.

Epoch f or "YYYY MM DD HH:MM:SS"

Optional, the Epoch of the orbital elements (f, the date when they are valid, can be specified either with a number, which represents an astronomical Julian Date, or by a quoted string, which represents a conventional Gregorian date. If Epoch is omitted, 1 January 2000 is assumed.

For example,
2452583.763194445 # 2002 Nov 5 06:19UT (Galileo encounter)
is the same epoch value as
"2002 11 5 6:19:00"

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

SemiMajorAxis f

One of SemiMajorAxis or PericenterDistance is required. The Semi-major axis of the orbit is in astronomical units (AUs) for objects which orbit around Stars or Barycenters, kilometres for everything else.

Note: the SemiMajorAxis of an hyperbolic orbit has a negative value.

PericenterDistance f

Alternate for SemiMajorAxis, is in astronomical units (AUs) for objects which orbit around Stars or Barycenters, kilometres for everything else.

ArgOfPericenter f

Optional, the orbit's argument of pericenter, in degrees (measured from the ascending node). Specify either LongOfPericenter or ArgOfPericenter, not both. If both are specified, ArgOfPericenter is used.

LongOfPericenter f

Optional, the orbit's longitude of pericenter, in degrees. This is the sum of the argument of pericenter and the longitude of the ascending node. Specify either LongOfPericenter or ArgOfPericenter, not both. If both are specified, ArgOfPericenter is used.

AscendingNode f

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 fundametal direction. If AscendingNode is not specified, a value of 0 degrees is assumed.

Inclination f

Optional orbital inclination, in degrees. It is with respect to the Ecliptic for the Solar System's planets, with respect to the primary's equator for everything else. 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.

MeanAnomaly f

Optional, the object's mean anomaly for Epoch, in degrees. This is the time that has elapsed since pericenter, divided by the orbital period, times 360 degrees. Specify either MeanLongitude or MeanAnomaly, not both. If both are specified, MeanAnomaly is used.

MeanLongitude f

Optional, the object's mean longitude, in degrees. This is the sum of the longitude of pericenter and the mean anomaly. Specify either MeanLongitude or MeanAnomaly, not both. If both are specified, MeanAnomaly is used.

Period f

Required, the orbital period is given in Earth years for objects which orbit around Stars or Barycenters, Earth solar days for everything else.


For a closed, elliptical orbit around our Sun,

 
or
 

When defining an hyperbolic orbit around the Sun, set period to be

 

where:

  is the period measured in years,
  is the pericenter distance measured in AU,
  is the eccentricity, and
  is the semimajor axis of the orbit, also measured in AU, and which has a negative value for hyperbolic orbits.

Emissive boolean

Specifies whether the object should seem to glow (true) or should be illuminated by light sources (false). Its default value is false.

Emissive true objects are bright, but are not light sources. They do not provide any illumination for other objects or cause them to cast shadows.

Ending f or "YYYY MM DD HH:MM:SS"

Sets a time after which the object doesn't exist.

The Ending time may be provided as a floating point number, in which case it is interpreted the astronomical Julian date, or it may be provided as a quoted string, in which case it is interpreted as the Gregorian date.

If it is a quoted Gregorian date, YYYY MM DD = year, month, day (integers); HH:MM:SS = hour, minute, second (integers). Since version 1.3.1, Celestia converts these time-stamps into Julian Dates internally. A date to Julian Date and back converter can be found at the U.S. Naval Observatory.

EquatorAscendingNode f

Ascending node, in degrees, of the object's equatorial plane.

This object rotational parameter is deprecated in Celestia v1.5.0 and later.

FixedPosition [ f f f ]

Available only in v1.5.0 or later.

An orbital specification which positions the object at a fixed position relative to its OrbitFrame. See the page on orbits and trajectories for more information.

GeomAlbedo f

Available only in v1.7.0 or later.

The Geometric albedo of the object. This determines the brightness of the point used to represent the object when it is too small to draw. If set to 0, the object is never drawn.

HazeColor [ R G B ]

Removed in 1.7

Atmospheric haze colour. Only works for Nvidia graphics cards. In Celestia v1.5.0 one can use Atmosphere Mie and Rayleigh scattering parameters instead, which work for all graphics cards which support OpenGL v2.0.

HazeDensity f

Removed in 1.7

Atmospheric haze density, a number in the 0.0 to 1.0 range. Only works for Nvidia graphics cards. In Celestia v1.5.0 one can use Atmosphere Mie and Rayleigh scattering parameters instead, which work for all graphics cards which support OpenGL v2.0.

InfoURL "URL"

The URL of a Web page which describes the object.

LongLat [ Long Lat Alt ]

Obsolete Deprecated in Celestia v1.5.0 and later

Previously used to define a place's position, in the object's reference frame. Long is the East longitude (in degrees), Lat its latitude, and Alt the altitude (in kilometres). Longitude is measured toward the East. West longitude can be specified as a negative value.

Warning: LongLat does not place objects correctly when used with OrbitFrame, SurfaceObject, or Object "Surfacefeature" in Celestia v1.5.0 and later. Use FixedPosition [ x y z ] or FixedPosition { Planetographic [ Long Lat Alt ] } instead.

 
The Moon in Celestia with LunarLambert values of 0.0, 0.5, 1.0

LunarLambert f

Increasing this value changes the way light is scattered. Higher values cause more light to get scattered forwards. See the picture at right for an example.

More technically, it corresponds to the   constant in the Buratti disk function:  .[1] A value of   causes this function to reduce to the Lambert scattering law, while   corresponds to Lommel-Seeliger (i.e. lunar-like) scattering.

The default value is 0.

Mesh "filename"

A 3D model file (cmod, cms, or 3ds) describing a non-spherical object. If no Mesh is specified, the object is assumed to be spherical. These files must be in a directory named "\models". A Texture may be draped onto the mesh. See the page on 3D Models for more information.

MeshCenter [ x y z ]

Offset of the mesh with respect to its center.

MeshScale scaleFactor

MeshScale is only used when an object has a mesh file and NormalizeMesh is set to false. It specifies the scale factor needed to convert the mesh's internal units into kilometers. For example, if the mesh file has coordinates given in units of meters, the MeshScale should be set to 0.001: 

MeshScale 0.001

When NormalizeMesh is true (the default), MeshScale is ignored, and Celestia automatically scales the mesh to fit inside the sphere with a size equal to the value of the object's Radius property.

NightTexture "filename"

The night-side texture of the object (JPG, PNG, or DDS; use PNG or DDS for transparency).

For more information, see the page Celestia/Textures.

NormalMap "filename"

A map of surface normal vectors used to describe the irregularities in the surface.

For more information, see the page Celestia/Textures.

NormalizeMesh boolean

Specifies whether Celestia should apply automatic scaling and centering to a mesh file. This property is true by default.

Overriding automatic scaling of meshes is useful when creating multicomponent spacecraft which have their parts in different mesh files. Celestia's automatic scaling and centering can make it very difficult to get the components to align with each other. When NormalizeMesh is false, the mesh is scaled by an amount specified by the MeshScale property. The Radius property doesn't affect the size of the mesh; it effectively just gives the radius of a bounding sphere for the object. The add-on creator must take care to ensure that the Radius is large enough to contain the scaled mesh, otherwise the Celestia may skip rendering the mesh even at times when it is actually in view.

Oblateness f

The oblateness of a spherical object when no Mesh is specified. Oblateness is defined as 1 minus the ratio of the polar to equatorial diameters.

Obliquity f

The object's rotational obliquity, in degrees. The name of this property is misleading: obliquity is angle between the rotation axis and the normal to the mean orbital plane, but in Celestia this quantity is the angle between the rotation axis and the normal to the body's reference plane, typically the ecliptic for planets. Along with "EquatorAscendingNode", defines the axis of rotation.

This object rotational parameter is deprecated in Celestia v1.5.0 and later. The new rotation model syntax should be used instead.

OrbitColor [ R G B ]

Changes the color of an object's orbit.

OrbitFrame { ...parameters... }

Available only in v1.5.0 or later.

An OrbitFrame defines the reference coordinate system for the other orbital parameters of the SSC object. See the page on orbits and trajectories for details.

Warning: LongLat does not place objects correctly when used with OrbitFrame in Celestia v1.5.0 and later. Use FixedPosition [ x y z ] or FixedPosition { Planetographic [ Long Lat Alt ] } instead.

Orientation [ angle x y z ]

Mesh orientation specified in angle-axis format.

Orientation is applied to the model before the rotation model. It is typically used to transform a mesh into a different coordinate system. Unlike the rotation model, Orientation does not affect the body fixed frame of an object.

angle in degrees (positive or negative)

x, y, z: 1 or 0 (1 designates the axis concerned)

example: Orientation [90 1 0 0] means 90° rotation on the x axis.

OverlayTexture "filename"

A texture overlaid onto the main texture (PNG or DDS for transparency).

For more information, see the page Celestia/Textures.

Note: there is a bug in Celestia v1.4.1 which causes OverlayTextures not to be drawn when the OpenGL 2.0 render path is selected. They are drawn by the other render paths. This problem is fixed in Celestia v1.5.0.

PrecessionRate f

The axis or rotation's precession rate, in radians per day.

This object rotational parameter is deprecated in Celestia v1.5.0 and later. The new rotation model syntax should be used instead.

Radius f

The equatorial radius of a spherical object, in kilometres. Also scales 3D models to the specified size.

SemiAxes [ x y z ]

Specifies the sizes of the three dimensions of an ellipsoid. These are the dimensions of the object if no Radius property is specified, and the relative sizes if one is specified (the SemiAxes values are multiplied by the Radius value). The radius shown in Celestia is the longest axis, not the average.

Rings { ...parameters... }

Description of an object's rings.

Inner f

The rings' inner edge, in kilometres from the object's centre.

Outer f

The rings' outer edge, in kilometres from the object's centre.

Texture "filename"

The ring texture (PNG or DDS for transparency).

For more information, see the page Celestia/Textures.

Color [ R G B ]

The ring colour, when no texture is specified.

R, G and B should have values between 0 and 1, inclusive.

RotationEpoch f

The epoch of the rotation description (?).

This object rotational parameter is deprecated in Celestia v1.5.0 and later. The new rotation model syntax should be used instead.

RotationOffset f

Celestia lines the object up with its prime meridian; the offset (in degrees) is the object's phase, in order for the textures and mesh to line up correctly.

This object rotational parameter is deprecated in Celestia v1.5.0 and later.

RotationPeriod f

The object's rotation period in hours.

This object rotational parameter is deprecated in Celestia v1.5.0 and later. (see UniformRotation {})

SampledOrbit "filename"

File of Julian date and xyz coordinates.

Takes priority over EllipticalOrbit.

For details, see Celestia/Trajectories, section SampledOrbit.

SampledTrajectory { ...parameters... }

Requires v1.5.0 or later.

Specifies a trajectory based on a file of Julian date / xyz coordinate records. SampledTrajectory is very similar to SampledOrbit with some added control over precision and interpolation.

Takes priority over SampledOrbit.

For details, see Celestia/Trajectories, section SampledTrajectory.

ScriptedOrbit { ...parameters... }

Requires v1.5.0 or later.

See Celestia/Trajectories, section ScriptedOrbit.

SpecularColor [ R G B ]

Colour of the specular reflection. SpecularColor must be specified if a SpecularTexture is used. Without it, no specularity is shown.

SpecularPower f

The intensity of the reflection; f must be a positive number with a value of 1 or more. Smaller values produce a larger, more diffuse spot, while larger values produce a smaller, more intense spot. SpecularPower must be specified if a SpecularTexture is used. No SpecularPower or a value less than 1 will cause Celestia's rendering engine to do strange things.

SpecularTexture "filename"

A .jpg, .png, .dds or .ctx image used to define areas with a specular reflection. White = reflective, black = dull. Requires both SpecularPower and SpecularColor.

For more information, see the page Celestia/Textures.

SpiceOrbit { ...parameters... }

Requires v1.5.0 or later.

See Celestia/Trajectories, section SpiceOrbit.

Texture "filename"

For more information, see the page Celestia/Textures.

A texture image (any of the filetypes PNG, JPG, or DDS) draped over the object's mesh or spheroid. An asterisk wildcard (*) may be used for the extension (e.g. Texture "mercury.*"). Textures are rooted in the "\textures" directory, and sorted in three subdirectories: "\hires" for high resolution, "\medres" for medium resolution, and "\lores" for low resolution.

When looking for texture image files, by default Celestia looks first in "medres", then "lores", and finally in "hires". The keyboard shortcuts "R" and "r" change which directory is searched first.

Timeline

This section is a stub.
You can help Wikibooks by expanding it.

requires Celestia v1.6.0 or later (or build from SourceForge svn repository)

See https://celestiaproject.space/forum/viewtopic.php?t=12050 and Celestia/160Features#Object_timelines

Provides a way to structure multiple, sequential objects as a single object. A space mission consisting of multiple parts can be organized with a single name.

UniformRotation { ...parameters... }

Available only in Celestia v1.5.0 or later.

UniformRotation replaces the older stand-alone SSC object rotational parameters by a block containing appropriate parameters describing the object's orientation. In addition to UniformRotation, blocks for FixedRotation, PrecessingRotation, SampledOrientation, and ScriptedRotation also are available.

An object's rotation is defined to be relative to its BodyFrame {}.

See the pages on Rotation Models and Reference Frames for details.

Visible boolean

Available only in Celestia v1.6.0 or later.

The setting of the visible property determines whether an object can be seen. This property affects the visibility of the object's geometry, label, and orbit path. The default value of Visible is true for all objects other than reference points. Usually, setting an object's visibility to false is only done if when it's expected that a user may run a script to reveal the object. Setting the visibility of a reference point to true is useful when you want its orbit and label to be shown (e.g. the Pluto−Charon barycenter in the standard Celestia 1.6.0 package.)

AltSurface "name" "object path" { ...parameters... }

Used to define a set of alternate surface textures for an object, such as a "limit of knowledge" or "topography map".

"name"

is what shows up in the object's contextual menu in Celestia. This text need not be unique: the same name can be used for AltSurfaces of several different objects. When a particular AltSurface name is selected in the popup contextual menu for one object, the AltSurfaces with that same name are shown on all objects. If an AltSurface with the selected name does not exist for an object, the "normal" (default) surface is shown instead.

"object path"

is the full path of the object, including its own name, on which to draw this alternate surface. e.g. "Sol/Earth/Moon" would tell Celestia that this is an alternative surface for our own Moon.

parameters

An AltSurface's parameters can be any of the parameters which describe the surface textures of an SSC object. For details of each, see their corresponding entries above.

  • BlendTexture bool
  • BumpHeight f
  • BumpMap "filename"
  • Color [ R G B ]
  • LunarLambert f
  • NormalMap "filename"
  • OverlayTexture "filename"
  • SpecularColor [ R G B ]
  • SpecularPower f
  • SpecularTexture "filename"
  • Texture "filename"

ReferencePoint "name" "object path" { ...parameters... }

Available only in Celestia v1.5.0 or later.

A ReferencePoint can be used to define an orbital barycenter. It's an invisible position around which other bodies can orbit.

"name"

The name of the ReferencePoint

"object path"

The path to the ReferencePoint, specifying the bodies around which it orbits.

parameters

A ReferencePoint is defined using those SSC parameters which define an orbit: CustomOrbit, EllipticalOrbit and SampledOrbit. See their definitions above.

OrbitFrame, FixedPosition, SpiceOrbit and ScriptedOrbit also can be used. See the page on orbits and trajectories for more information about these new parameters.

Only orbit and position parameters are used. Rotation and orientation parameters are not relevant and are ignored.

SurfaceObject "name" "object path" { ...parameters... }

Available in Celestia v1.6.0 and later versions.

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"

Warning: LongLat does not place objects correctly when used with SurfaceObject in Celestia v1.5.0 and later. Use FixedPosition [ x y z ] or FixedPosition { Planetographic [ Long Lat Alt ] } instead.

Location "name" "object path" { ...parameters... }

Location is an SSC directive used to designate a point of interest on an object in Celestia, such as Earth's major cities, where Pathfinder landed on Mars, or Apollo 11 on the Moon, etc. Celestia includes several .SSC catalogs of Locations, such as "<object>_locs.ssc" in the "data" directory. The display of Locations is toggled by the "&" keystroke, and the "Render:Locations..." menu controls other aspects of their display.

"name"

The name of the Location

"object path"

The full path of the object on or near which the Location is to be placed, including the name of that object.

specify object path parameters

parameters

LongLat [ Long Lat Alt ]

Used to define a place's position, in the object's reference frame. Long is the East longitude (in degrees), Lat its latitude, and Alt the altitude (in kilometres). Longitude is measured toward the East. West longitude can be specified as a negative value.

Size f

the radius of the Location in km. Smaller sizes are not drawn until the viewpoint gets closer to them.

Importance f

alternative to Size

Type "string"

Celestia recognizes many of the two-letter topographical types defined in the USGS Gazetteer:

  • "AA" = Crater = a circular depression
  • "AL" = Albedo = geographic area distinguished by amount of reflected light - new in Celestia 1.7.0
  • "AR" = Arcus = arc-shaped feature - new in Celestia 1.7.0
  • "AS" = Astrum = radial-patterned features on Venus
  • "CA" = Catena = chain of craters
  • "CB" = Cavus = hollows, irregular steep-sided depressions usually in arrays or clusters - new in Celestia 1.7.0
  • "CH" = Chaos = distinctive area of broken terrain
  • "CM" = Chasma = a deep, elongated, steep-sided depression
  • "CO" = Colles = small hills or knobs - new in Celestia 1.7.0
  • "CR" = Corona = ovoid-shaped feature
  • "DO" = Dorsum = ridge
  • "ER" = EruptiveCenter = active volcanic centers on Io
  • "FA" = Facula = bright spot - new in Celestia 1.7.0
  • "FE" = Flexus = a very low curvilinear ridge with a scalloped pattern - new in Celestia 1.7.0
  • "FL" = Fluctus = flow terrain
  • "FM" = Flumen = channel on Titan that might carry liquid - new in Celestia 1.7.0
  • "FO" = Fossa = long, narrow depression
  • "FR" = Farrum = pancake-like structure, or a row of such structures
  • "FT" = Fretum = strait, a narrow passage of liquid connecting two larger areas of liquid - new in Celestia 1.7.0
  • "IN" = Insula = island (islands), an isolated land area (or group of such areas) surrounded by, or nearly surrounded by, a liquid area (sea or lake)
  • "LA" = Labes = landslide - new in Celestia 1.7.0
  • "LB" = Labyrinthus = complex of intersecting valleys or ridges - new in Celestia 1.7.0
  • "LC" = Lacus = "lake" or small plain; on Titan, a "lake" or small, dark plain with discrete, sharp boundaries - new in Celestia 1.7.0
  • "LE" = Lenticula = small dark spots on Europa[2] - new in Celestia 1.7.0
  • "LF" = LandingSite = Lunar features at or near Apollo landing sites
  • "LG" = LargeRinged = cryptic ringed features - new in Celestia 1.7.0
  • "LI" = Linea = a dark or bright elongate marking, may be curved or straight
  • "LN" = Lingula = extension of plateau having rounded lobate or tongue-like boundaries - new in Celestia 1.7.0
  • "LU" = Lacuna = irregularly shaped depression on Titan having the appearance of a dry lake bed - new in Celestia 1.7.0
  • "MA" = Macula = dark spot, may be irregular - new in Celestia 1.7.0
  • "ME" = Mare = "sea"; on the Moon, low albedo, relatively smooth plain, generally of large extent; on Mars, dark albedo areas of no known geological significance; on Titan, large expanses of dark materials thought to be liquid hydrocarbons
  • "MN" = Mensa = a flat-topped prominence with cliff-like edges
  • "MO" = Mons = mountain
  • "OC" = Oceanus = a very large dark area on the moon - new in Celestia 1.7.0
  • "PA" = Palus = "swamp"; small plain - new in Celestia 1.7.0
  • "PE" = Patera = an irregular crater, or a complex one with scalloped edges
  • "PL" = Planitia = low plain
  • "PM" = Planum = plateau or high plain
  • "PR" = Promontorium = "cape"; headland promontoria - new in Celestia 1.7.0
  • "PU" = Plume = cryo-volcanic features on Triton - new in Celestia 1.7.0
  • "RE" = Regio = a large area marked by reflectivity or color distinctions from adjacent areas, or a broad geographic region
  • "RI" = Rima = fissure
  • "RT" = Reticulum = reticular (netlike) pattern on Venus
  • "RU" = Rupes = scarp
  • "SA" = Saxum = boulder or rock - new in Celestia 1.7.0
  • "SC" = Scopulus = lobate or irregular scarp - new in Celestia 1.7.0
  • "SE" = Serpens = sinuous feature with segments of positive and negative relief along its length - new in Celestia 1.7.0
  • "SF" = Satellite = a feature that shares the name of an associated feature - new in Celestia 1.7.0
  • "SI" = Sinus = "bay"; small plain; on Titan, bays within seas or lakes of liquid hydrocarbons - new in Celestia 1.7.0
  • "SU" = Sulcus = subparallel furrows and ridges - new in Celestia 1.7.0
  • "TA" = Terra = extensive land mass
  • "TE" = Tessera = tile-like, polygonal terrain
  • "TH" = Tholus = small domical mountain or hill
  • "UN" = Undae = dunes
  • "VA" = Vallis = valley
  • "VI" = Virga = a streak or stripe of color - new in Celestia 1.7.0
  • "VS" = Vastitas = extensive plain - new in Celestia 1.7.0
  • "XX" = Other

plus a few longer categories:

  • "City"
  • "Observatory"
  • "Landing Site"
  • "Crater" (but "AA" is preferred)
  • "Capital" - new in Celestia 1.7.0
  • "Cosmodrome" - new in Celestia 1.7.0
  • "Ring" or "RG" - new in Celestia 1.7.0
  • "Historical" - new in Celestia 1.7.0

Editing Directives

Available in Celestia v1.4.0 and later versions.

An SSC file can be used to edit objects that were defined in previously loaded SSC files. You do not have to use a text editor to change their contents. This makes it possible for an Addon to update the SSC catalogs that are included in Celestia's distribution. You do not have to edit them manually every time Celestia is upgraded to a new version.

There is no Delete editing directive. However, one can use the Replace directive and define the undesired object to be
Class "invisible"


The editing directives are

Add "object name" "object path" { ...parameters... }

Add creates a new object. This is the default action if no edit directive is specified.

Modify "object name" "object path" { ...parameters... }

Modify changes only the parameters listed in its block. Other parameters defined for the specified object are not affected.

Replace "object name" "object path" { ...parameters... }

Replace deletes all of the parameters associated with the specified object and replaces them by the new block of parameters.

Distance limits

SSC objects orbit around Stars or Barycenters.

Objects defined in SSC files cannot be seen when the viewpoint is more than 1 light-year from their Star or Barycenter.

Prior to Celestia v1.6.0, Stars or Barycenters could not be drawn reliably if they were farther than 16,000 light-years from the Sun. This limit resulted both from the Hipparcos catalogue parallax precision limit, of about 1 milli-arc-second, and from technical limitations within Celestia.

Starting with Celestia v1.6.0, the maximum distance is 10,000,000 light-years. However, star placement has an angular precision of about 1/10 of an arcsecond as seen from Earth. This is adequate for observationally derived data, but if you want to create a dense globular cluster, stars might end up getting stacked on top of each other because of the limited precision.


References

  1. ↑ Buratti, Bonnie J. (1984). "Voyager disk resolved photometry of the Saturnian satellites". Icarus. 59 (3): 392–405. Bibcode:1984Icar...59..392B. doi:10.1016/0019-1035(84)90109-X.
  2. ↑ https://link.springer.com/referenceworkentry/10.1007%2F978-1-4614-9213-9_217-1

STC: STar Catalogs

Introduction

An STC file, or STar Catalog, specifies the position and other parameters of a Star or Barycenter.

This is a brief description of the STC parameters recognized by Celestia v1.4.1 and newer versions of the program. STC functionality has undergone a substantial improvement when compared to the previous versions of Celestia, v1.3.2 and earlier.

  • Objects are defined by specifying a quoted name, and a list of parameters. Barycenters and Hipparcos/Tycho designations are optional, and modify the star.
  • Editing a previously defined object can be done by prefixing the object's name by one of the keywords Modify or Replace. The revised definition can include any of the parameters used to define objects. Note that if you are modifying/replacing a Barycenter, the keyword must come before Barycenter, not after.

STC catalog files are either in the "data" directory of the Celestia root or in an Add-on's root subdirectory (itself in Celestia's extras directory).

Celestia's catalog files are plain text files, and can thus be modified with your favourite text editor. As with other code, the text must use straight ("dumb") quotes, not curly ("smart") quotes; for some text editors you will have to disable smart quotes.

Most stars in Celestia are defined in the file Celestia/data/stars.dat, which uses a different format. (See Binary Star File for more information).

Structure of an object definition

type index "object name" { ...parameters... }

The first elements in an STC object's definition are its name, and an option for Hipparcos/TYC designations, and stellar barycenters.

type = Either Barycenter or Star (you can also leave it blank for a star).

index = Optional, a number between 0 and 4294967295, that specifies the Hipparcos or Tycho designation of the star.

object name = Name of the object, in quotes (e.g. "Sirius"). As of Celestia 1.6.0, multiple names separated by colons are allowed ("Eris:2003 UB313").

The object's descriptive parameters follow within the accolades ("braces" or "squiggly brackets": {} )

The list of parameters is:

  • RA
  • Dec
  • Distance
  • AppMag or AbsMag
  • SpectralType
  • Radius (optional; the default value is calculated from the Star's SpectralType and magnitude.)
  • SemiAxes or Mesh (optional)
  • Texture (optional)
  • EllipticalOrbit (optional)
  • Rotational elements (not listed here: see Rotation Models; optional)

Comments

#

The pound sign ("crosshatch" or "sharp sign") begins a comment: whatever lies after this sign up to the next line terminator is ignored by Celestia.

Description

Type and Identifier

  • Barycenter or Star

An STC catalog file can be used to describe either Stars or Barycenters around which Stars, Barycenters and SSC objects can orbit.

A Barycenter defines only a position in space. You can't see it, as it is the center of mass of a collection of bodies. A Barycenter can orbit around another Barycenter, or around a Star.

A Star is a glowing object described by a position plus visual parameters like SpectralType, AppMag or AbsMag and optional Mesh, Radius, SemiAxes and Texture declarations. A Star can orbit around another Star or around a Barycenter.

There are three optional fields used to introduce an STC object. They specify the type of object it is and provide unique identifiers for it. In their required order of appearance, they are

  • (Optional) type of object: either Barycenter or Star. If omitted, Star is assumed.
  • (Optional) Hipparcos catalog number: if this Hipparcos catalog number is the same as the Hipparcos catalog number of a previously existing Star or Barycenter, that object is replaced by this one. Barycenters and Stars can replace each other or objects of the same type.
  • (Optional) quoted name: can be a list separated by colons (:). This will replace the names of a previously defined object with the same catalog number. If no name is specified, the original names will be retained.

Of the three, at least a HIP number or a Star name is required.

Examples:

  • Type of object, Hipparcos catalog number, and two names
Barycenter 100000 "My Barycenter:My System" { ... description ... }

This creates a barycenter with the Hipparcos number 100000, with the names "My Barycenter" and "My System".

  • Name of object (type of object is assumed to be Star)
"My Star" { ... description ... }

This creates a star with the name "My Star".

All of the other parameters used to describe a particular STC object are enclosed within curly-brackets: { }

Bayer Star Names

When a Bayer star name is specified, the 3-character abbreviation for the Greek letter as used in the Hipparcos catalog should be specified. These abbreviations are 

   alpha = ALF   beta= BET   gamma= GAM   delta= DEL   epsilon= EPS
   zeta  = ZET   eta = ETA   theta= TET   iota = IOT   kappa  = KAP
   lambda= LAM   mu  = MU    nu   = NU    xi   = XI    omicron= OMI
   pi    = PI    rho = RHO   sigma= SIG   tau  = TAU   upsilon= UPS
   phi   = PHI   chi = CHI   psi  = PSI   omega= OME

For example, the following would create a star labeled "α Cen": 

Star "ALF Cen" { ...description... }

Unfortunately these abbreviations do not distinguish between Bayer designations and variable star designations for "MU" and "NU". For example, HIP 35355 is known as MU CMa, but in Celestia that name would be rendered as "μ CMa".

This table is taken from HD-DM-GC-HR-HIP-Bayer-Flamsteed Cross Index Kostjuk N.D., Institute of Astronomy of Russian Academy of Sciences (2002), which is available at http://cdsarc.u-strasbg.fr/viz-bin/Cat?IV/27

Constellation Names

Similarly, when specifying a constellation name as part of a star's name, use its official 3 letter abbreviation. The International Astronomical Union provides a list of constellation abbreviations.

Position

  • RA f
  • Dec f
  • Distance f

or

  • OrbitBarycenter "object path"
  • SSC-style EllipticalOrbit parameters (optional)

The nominal location of a Star or Barycenter can be specified using either RA, Dec and Distance or by using the keyword OrbitBarycenter to specify the name (and thus the position) of a previously defined Barycenter or Star.

To specify using RA, Dec, and Distance, add the coordinates of the star. The RA and Dec are the right ascension and declination of the star. Note that in an STC catalog, RA must be specified in degrees. This is unlike a DSC catalog, where RA must be specified in hours.

Usually the RA will be in hours/arcminutes/arcseconds format, and the Dec will be in degrees/arcminutes/arcseconds format. To convert to Celestia's format, use a tool like this RA Dec Flexible Converter, and select the eleventh option down.

For example: 

     RA 299.0    # in fractional degrees, 0-360
     Dec -10.5   # in fractional degrees, -90 to + 90
     Distance 30 # in light years

OrbitBarycenter puts the object in orbit around another object, which is specified by putting the name in quotes. For example, this puts the object in orbit around a star called "My Star": 

     OrbitBarycenter "My Star"
  • A Star or Barycenter can orbit around its own nominal position, around another Star or around a Barycenter.
  • The orbit of a Star or Barycenter is specified using the same EllipticalOrbit declaration as is used in SSC files.
    • A list of parameters is omitted: see the chapters on SSC files and Trajectories. Celestia v1.5.0 Frame declarations are not yet supported in STC catalogs.
    • The usual orbital parameters listed in papers are in a different reference frame compared to the one in Celestia. Therefore, they must be converted to Celestia's frame using Grant Hutchinson's Star Orbit Translation Spreadsheet.
  • A Star's or Barycenter's elliptical orbit is defined relative to the object's nominal location, which is specified using either an RA, Dec, Distance triplet or by OrbitBarycenter.

Specifying RA, Dec, and Distance is slightly more efficient than OrbitBarycenter, but only at load time, when Celestia has to lookup the position of the Barycenter. Despite this, OrbitBarycenter should be used for multi-star systems so that Celestia can determine that two stars orbiting the same point are actually associated.

Magnitude

  • AbsMag f

or

  • AppMag f

AppMag and AbsMag control how bright the star is. The AppMag is the apparent magnitude (how bright the star is from Earth). AbsMag is the absolute magnitude. This is how bright the star would be if it were 10 parsecs (32.6 light-years) away, with no extinction (dimming, caused by dust that is blocking light).

In Celestia, the AppMag corresponds to the V-magnitude in the Johnson UBV photometric system. This means that the magnitudes correspond to the brightness in a specific passband: only a range of frequencies count.

Confusion may arise, since Celestia uses data from the Hipparcos catalog and that has introduced its own visual filter profile. The Hipparcos "visual" magnitude is called Hp. This profile is much wider in wavelength than the "standard" Johnson one.

Moreover, Tycho data again use different photometry, designated with VT and BT for the visual and blue magnitudes, respectively.

There exist detailed mutual transformation algorithms and/or lookup tables. The relations are quite non-trivial in general. A list of them can be found at http://www.aerith.net/astro/color_conversion.html.

SpectralType

  • SpectralType f

SpectralType controls the type of the star. It is a string, such as G2V, that describes the color and luminosity class of the star.

Spectral types as defined in Celestia have three parts to it: the spectral class, a number, and a luminosity class. Spectral types may also have extra symbols for spectral peculiarities, but these are not included in Celestia.

The spectral class is one of these characters/strings: O, B, A, F, G, K, M, L, T, C, R, N, S, WC, WN, D, Q, or X. O through M represent normal stars, with O being the hottest and bluest and M being the coolest and reddest. L and T represent brown dwarfs: objects that are too small to fuse hydrogen (Spectral class Y is implemented in v1.7). C, R, and N represent carbon stars: red giant stars with noticeable amounts of carbon in their atmospheres (i.e. greater than oxygen concentrations). S represents a class of star with approximately equal amounts of carbon and oxygen in their atmospheres. WC and WN represent Wolf-Rayet stars, D represents white dwarfs, Q represents neutron stars, and X represents black holes. The number after that modifies the original class: for stars from O to T, a lower number represents a hotter number. Finally, a luminosity class is one of these strings: Ia0, Ia, Ib, II, III, IV, V, or V, with decreasing luminosity. Note that the number and the luminosity class may be left blank.

Spectral types can often be estimated from other values, such as mass, radius, or temperature. A table can be found here: http://www.isthe.com/chongo/tech/astro/HR-temp-mass-table-byhrclass.html.

Appearance

  • Radius f (optional)
  • SemiAxes [f f f] (optional)
  • Mesh <filename> (optional)
  • Texture <filename> (optional)
  • SSC-style orientation parameters (optional)


  • By default, the appearance of a Star is controlled by its SpectralType (coloration) and magnitude (brightness: either AbsMag or AppMag). Celestia's spectral type field can include any of the standard astronomical spectral type and luminosity codes. See below for a description of the magnitude standard used by Celestia.
  • The size of a Star is usually calculated from its SpectralType and its Magnitude. Optionally one can force a Star to be a particular size by specifying its Radius in km.
  • The default spherical shape of a Star can be modified by the optional declaration SemiAxes. SemiAxes specifies the relative sizes of a Star's radii in three dimensions:
     SemiAxes [1 0.85 1]
  • The default spherical shape of a Star can be replaced by using the optional model declaration Mesh.
     Mesh "accretion_disk.cmod"
A Mesh may be a 3DS model, or one of Celestia's proprietary model types, either CMOD or CMS, which are described elsewhere.
  • The default surface texture of a Star (normally determined from its SpectralType) can be replaced by using a Texture declaration
     Texture "image filename"
Note: as of Celestia v1.4.0, only one default texture is used for all stars: astar.jpg. Its coloration is determined by the Star's SpectralType.
  • The orientation of a Star is controlled by the same optional rotational element declarations as are used in SSC catalogs, although v1.5.0's BodyFrames and related functions are not yet available. (A list of rotational parameters is available in the SSC documentation.)
  • Other SSC parameters are not supported. In particular, Bumpmaps, Normalmaps, NightTexture and Atmosphere (including CloudTextures) are ignored.
Also, AltSurface and Location declarations are not (yet?) supported.

Example STC definition

This example is taken from Grant Hutchison's star catalog file Celetia/data/nearstars.stc. It's one of the catalogs which are included with Celestia v1.4.0 and later. 

Barycenter "Rigel Kentaurus:Toliman:ALF Cen:Gliese 559"
{ 
 RA 219.917516 # mass ratio 1.09:0.92 
 Dec -60.837128 # 
 Distance 4.365 
}

71683 #  ALF Cen A
{  
 OrbitBarycenter "ALF Cen"
 SpectralType "G2V"
 AppMag 0.01
 EllipticalOrbit
 { 
  Period 79.914
  SemiMajorAxis 10.765 # mass ratio 1.09:0.92
  Eccentricity 0.5179
  Inclination 82.980
  AscendingNode 67.708
  ArgOfPericenter 3.774
  MeanAnomaly 200.119
 }
}

71681 # ALF cen B
{
 OrbitBarycenter "ALF Cen"
 SpectralType "K0V"
 AppMag 1.34
 EllipticalOrbit
 {
  Period 79.914
  SemiMajorAxis 12.755 # mass ratio 1.09:0.92
  Eccentricity 0.51479
  Inclination 82.980
  AscendingNode 67.708
  ArgOfPericenter 183.774
  MeanAnomaly 200.119
 }
}

Renaming stars

To rename a Star or Barycenter in Celestia, add this STC template code: 

Modify 123456789 "FOO"
{
}

where 123456789 is the Hipparcos/TYC index of the star you want to rename, and FOO is a string containing the new names in quotes, separated by colons.

If you also wish to change the star's properties, the parameters can be put inside the curly brackets {}. So the following code, which renames Betelgeuse, will work as well: 

27989 "Betelgeuse:Al Mankib:Almerzamo nnagied:Gula:Besn:ALF Ori:58 Ori"
{
 RA 88.792958
 Dec 7.407064
 Distance 419.13
 AppMag 0.58
 SpectralType "M1Iab"
}

The alternative names above are from Star Names, Their Lore and Meaning by Richard Allen, Dover, 1963. The location and spectral information are from the Simbad catalog server.

As of 1.6.1, it is currently only possible to rename a star if it has a Hipparcos/TYC index.

Hipparcos and Tycho Catalog Numbers

Celestia uses Hipparcos catalog numbers as the primary identifier for its Stars. Hipparcos catalog numbers, often identified in documents with the prefix HIP, range from 1 to 120404. In Celestia, Tycho catalog numbers start at 1 000 000 000.

Tycho catalog numbers can be used, but they have to be "encoded" into fake Hipparcos numbers. They all are encoded into a 10 digit number with a value greater than 1 000 000 000. To do this, the three numeric fields of a Tycho catalog number are reversed and concatenated into a single number: 

     TYC aaaa-bbbbb-c becomes cbbbbbaaaa

E.g. TYC 654-32-1 becomes 1000320654. (Note, however, that this number does not correspond to an actual Tycho catalog entry. It is only used to show how the numeric fields are rearranged.)

Celestia rearranges these numbers to display the correct Tycho catalog number on the screen.

The following STC catalog entry defines the star TYC 654-32-1 named "TycStar" 

1000320654 "TycStar"
{
 RA 123.45
 Dec 45.67
 Distance 89
 SpectralType "G1V"
 AppMag 8.7
}

Note that Celestia uses 32-bit integers to represent star numbers, so cannot use star numbers above 4294967295 (which would correspond to TYC 7295-29496-4): this should not limit the implementation of real Tycho stars.

DSC: Deep Space Catalogs

Introduction

This is a brief description of the parameters recognized by Celestia in DSC files (Deep Space Catalogs). DSC Galaxy functionality underwent a substantial improvement in Celestia v1.4.1 when compared to the previous versions of Celestia.

A DSC catalog file can be used to describe four classes of objects: OpenCluster, Globular (i.e. Globular Cluster), Nebula or Galaxy.

A DSC object definition consists of its class, a quoted name, and its parameters enclosed in braces: 

Class  "name" { ...parameters... }

Unlike STC and SSC files, DSC files don't support Modify and Replace directives, so to modify an object defined in a DSC file you have to edit the original file.

List of Parameters

Class:

  • OpenCluster "name"
  • GlobularCluster "name"
  • Nebula "name"
  • Galaxy "name"


Location:

  • RA f, Dec f, Distance f

or

  • Position [f f f]

Orientation:

  • Axis [f f f]
  • Angle f

Size:

  • Radius f

Information:

  • InfoUrl "URL"

Appearance:

  • Mesh "filename"
  • Type "string"
  • CustomTemplate "filename"
  • AbsMag f or Appmag f

OpenCluster "name"

    "name" is the name of the object. Multiple names can be specified within the quotes if they're separated by colons (:). OpenCluster currently is used only to associate the specified "name" with a position in space. The members of an OpenCluster are defined separately in one or more .STC files or in stars.dat. The parameters used to define an OpenCluster are

    placement

    A deep space object's position can be defined either by specifying a single position vector or by specifying its three astronomical coordinates.

    • Position [ f f f ]
      The position vector's [x y z ] coordinates are in Light Years, specifying a position in Celestia's Ecliptic J2000 "Universal" coordinate system
      • or
    • Distance number (default: 1.0) in LightYears
    • RA number (default: 0.0) Right Ascension in fractional Hours (unlike STC catalogs, which use fractional degrees)
    • Dec number (default: 0.0) Declination in fractional degrees

    orientation (optional)

    • Axis 3 vector (default: [ 1.0 0.0 0.0] )
      a unit vector specifying the orientation of the object's axis in Celestia's Ecliptic J2000 "Universal" coordinate system
    • Angle number (default: 0.0 degrees)
      the amount the object is rotated around that Axis.

    size

    • Radius number (default: 0.0) in Light Years.

    information (optional)

    • InfoUrl "string"
      "string" should be the URL of a web page describing the object.

Globular "name"

    Places a glowing spherical image of stars at the specified position.
    Uses all of the parameters used for OpenCluster plus the following:

    size

    • Radius number, in light-years.
    The Radius specifies the size of the globular. Note that this does not affect the placement of sprites. It does, however, change the "bounding box". For a larger Radius, the red markers will be appear farther away from the center of the globular. The Radius parameter also controls how far you are from the center of the globular, when you select and go-to that object.

    shape

    • Detail number
    Detail is a value between 0 and 1 that controls how many point sprites the globular has. The default value is 1, and this places the maximum amount of point sprites. A value of 0 creates a globular with no stars but a glowing central "core". Using a value greater than 1 or less than 0 is equivalent to using 1 or 0, respectively.
    • CoreRadius number
    • KingConcentration number

    example

 Globular "M 4:NGC 6121:GCl 41:C 1620-264"
 {
       RA          	   16.3931  # [hours]
       Dec         	  -26.5253  # [degrees]
       Distance    	      7176  # [ly]
       Radius      	     37.57  # [ly], mu25 Isophote
       CoreRadius  	      0.83  # [arcmin]
       KingConcentration     1.59  # c = log10(r_t/r_c)
       AbsMag      	      -7.2  # [V mags]
       Axis       	[  0.1967  -0.6744  -0.7117]
       Angle       	     171.8  # [degrees]
       InfoURL  "http://simbad.u-strasbg.fr/sim-id.pl?Ident=NGC+6121"
 }


Nebula "name"

    Places a glowing model at the specified position and orientation.
    Uses all of the parameters used for OpenCluster plus the following:

    shape

    • Mesh "filename" (optional)
    "filename" must be the name of a 3DS, CMS or CMOD model file which determines the Nebula's shape.
    The model's internal material may require an associated PNG, JPG or DDS surface texture image file to be in the object's subdirectory /textures/medres to define the Nebula's coloration.
    If Mesh is omitted, no object is drawn.

Galaxy "name"

    Places a glowing image of a galaxy at the specified position and orientation
    Uses all of the parameters used for OpenCluster plus the following:

    shape

    • Type "string"
      "string" should be one of: S0, Sa, Sb, Sc, SBa, SBb, SBc, E0, E1, E2, E3, E4, E5, E6, E7, Irr
      The Type is shown in Celestia's on-screen informational display. It also determines which PNG image in Celestia's Models directory is used to define the shape of the Galaxy's image.
      If no Type is specified, it defaults to "Irr".

    or

    • CustomTemplate "filename" (optional)
      "filename" must be a the name of a PNG image defining the shape of this Galaxy. The PNG image must be located in the main /models directory (where all the other custom template files are).

    brightness

    • AppMag number

    or

    • AbsMag number

Example

  Nebula "M16" 
  {
     Mesh "1995-44-a.3ds"
     Axis    [0.205007 -0.737927 -0.642989]
     Angle 146.298
     RA 18.31404
     Dec -13.8311
     Distance 7002
     Radius 3.45 
  }

Orbits & Trajectories

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.

JPL Ephemerides

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

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

This section is a stub.
You can help Wikibooks by expanding it.

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

}

Rotation Models

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:  

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:

 ,  ,  ,  

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
}

Simple Add-Ons: Replacing Textures & Locating Catalogs

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.

Creating Textures: Painting Planets

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:

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.

3D Models: Scupting Satellites

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

This section is a stub.
You can help Wikibooks by expanding it.
  • 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

This section is a stub.
You can help Wikibooks by expanding it.

Limitations

This section is a stub.
You can help Wikibooks by expanding it.
  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.

CMS Models

CMS File Reference

The CMS model format is deprecated. This means that its usage is discouraged and that it is likely to go away in a future version of Celestia.

What's a CMS file?

"Celestia? Model? Simple?" files define simple shapes by deforming a sphere. Although deprecated, they are still used for a few generic objects such as asteroids, minor moons and the like.

They lie in the "models" directory of the Celestia root, or in an add-on's root subdirectory (itself in Celestia's "extra" directory).

They are plain text files, and can thus be modified with your favourite text editor.

#

The pound sign begins a comment: whatever lies after this sign up to the next carriage return is ignored by Celestia.

"SphereDisplacementMesh" { ... }

All of the cms stuff is within this block. The parameters appearing within the accolades are:

"Size [ x y z ]"

When a model is placed in a circular orbit around a parent body without rotation settings (so it is tide-locked) and with a mean longitude of 0,

  • x is the radial axis (running from the parent body to the model and through it: near-far)
  • y is the polar axis (running perpendicular to the orbital plane: north-south)
  • z is the orbital axis (running parallel to the orbit: forward-backward)

It defaults to [1.0 1.0 1.0].

"NoiseOffset [ a b c ]"

This is some kind of implementation of Perlin noise, and NoiseOffset (probably) moves the origin of the noise.

It defaults to [10 10 10].

"FeatureHeight f"

This controls the height of the bumps. Small numbers like 0.2 define a body that is roughly spherical with low hills, while larger numbers like 1.0 define a body with large hills.

It defaults to 0.0.

"Octaves i"

This defines the bumpiness of the model. Small values like 1 define a body with a fairly regular distortion, whereas large values like 9 define a very bumpy body. A value of zero gives a spherical body.

It defaults to 1.

"Slices i"

The Slices parameter controls the number of longitude lines. Together with Rings, this defines how much detail there is in the mesh. The default value of 20 defines a blocky mesh, while 200 defines a much smoother mesh that can take several seconds to render when displayed for the first time.

Setting Slices to a low value and Rings to a high value gives a mesh that is shaped like a peeled orange.

"Rings i"

The Rings parameters controls the number of latitude lines. Together with Slices, this defines how much detail there is in the mesh. It also defaults to 20.

Setting Slices to a high value and Rings to a low value gives a mesh that is shaped like a pile of doughnuts of varying thicknesses stacked on each other.

CMOD Models

Introduction

Celestia's internal Model object consists of a set of "materials" followed by a set of "meshes". Each "mesh" consists of a list of vertex definitions followed by several "groups". Each "group" consists of a specification of the type of "group" that it is, followed by an enumeration of previously defined vertices belonging to the group. This structure exactly corresponds to the items contained in a CMOD file.

BN description of CMOD format

The following description has been adapted from comments in Celestia's source code.

This is an approximate Backus Naur form for the contents of ASCII cmod files. For brevity, the categories <unsigned_int> and <float> aren't defined here--they have the obvious definitions. 

 <modelfile>           ::= <header> <model>
              
 <header>              ::= #celmodel__ascii
              
 <model>               ::= { <material_definition> } { <mesh_definition> }
              
 <material_definition> ::= material
                           { <material_attribute> }
                           end_material
 
 <material_attribute>  ::= diffuse  <color>  |
                           specular <color>  | 
                           emissive <color>  | 
                           specpower <float> | 
                           opacity   <float> |
                           texture0 <string> |
                           blend add |             (v1.5.0 and later)
                           normalmap   <string> |  (v1.5.0 and later)
                           specularmap <string> |  (v1.5.0 and later)
                           emissivemap <string>    (v1.5.0 and later)

 <color>               ::= <float> <float> <float>
              
 <string>              ::= """ { letter } """
             
 <mesh_definition>     ::= mesh
                           <vertex_description>
                           <vertex_pool>
                          { <prim_group> }
                           end_mesh
 
 <vertex_description>  ::= vertexdesc
                           { <vertex_attribute> }
                           end_vertexdesc

 <vertex_attribute>    ::= <vertex_semantic> <vertex_format>
              
 <vertex_semantic>     ::= position | normal | color0 | color1 | tangent |
                           texcoord0 | texcoord1 | texcoord2 | texcoord3
 
 <vertex_format>       ::= f1 | f2 | f3 | f4 | ub4
              
 <vertex_pool>         ::= vertices <count>
                           { <float> }
 
 <count>               ::= <unsigned_int>
              
 <prim_group>          ::= <prim_group_type> <material_index> <count>
                           { <unsigned_int> }
 
 <prim_group_type>     ::= trilist | tristrip | trifan |
                           linelist | linestrip | points | 
                           sprites    (v1.5.0 and later)
              
 <material_index>      :: <unsigned_int> | -1

Clarification of some of the elements

In Celestia v1.5.0 or later, a full Material definition would look like 

material
diffuse 0.5 0.5 0.2
specular 1 1 1
specpower 30
opacity 1
texture0 "basetex.jpg"
normalmap "norm.png"
specularmap "specmask.jpg"
emissivemap "lights.jpg"
end_material

Some of the vertex attributes are

  • position - position (required)
  • texcoord0 - primary texture coordinate
  • texcoord1 ... texcoord3 - additional texture coordinates (for multitexturing)
  • color0 ... color1 - primary and secondary colors
  • tangent - surface tangents (for bump mapping)

The vertex formats are

  • f1 - one float
  • f2 - two floats (typical for texture coordinates)
  • f3 - three floats (positions and normals)
  • f4 - four floats
  • ub4 - four unsigned bytes (the usual format for colors)

The primitive types are

  • trilist
  • tristrip
  • trifan
  • linelist
  • linestrip
  • points
  • sprites (v1.5.0 and later)

Tristrips and trifans can be much more efficient than triangle lists.

Example ASCII CMOD File

#celmodel__ascii
# The above line is the 16-byte header; for binary files, it's
# #celmodel_binary

# material definitions follow--these must precede any meshes in the file
material       # index 0
emissive 0 1 0
opacity 0.5
end_material

# A material with a texture.  Texture filenames may use the wildcard
# character, which behaves exactly as it does within a .ssc file.
material	# index 1
emissive 1 1 1
texture0 "tropical-beach.*"
end_material

# There may be one or more meshes in a model file--this file happens
# to have just a single one
mesh

# The vertex description tells what attributes the vertices for this mesh
# have.  Each attribute in the description consists of a semantic and a
# data format.
vertexdesc
position f3
normal f3
texcoord0 f2
end_vertexdesc

# The vertex data--the number right after the keyword vertices is the
# number of vertices in the pool.
vertices 6
0 0 0 0 0 1 0 0
1 1 0 0 0 1 1 1
0 1 0 0 0 1 0 1
0 1 0 0 0 -1 0 1
1 1 0 0 0 -1 1 1
0 0 0 0 0 -1 0 0

# An arbitrary number of primitive groups follow

# The primitive group type is followed by a material index, then
# a count of the number of vertex indices in the group
trilist 0 3
0 1 2
trilist 1 3
3 4 5

# End of the mesh
end_mesh

# ---- end of cmod file ----

Point Sprites

Starting with Celestia v1.5.0, the CMOD format supports point sprites. These can be used for a variety of different volumetric rendering effects for phenomena such as nebulae, accretion disks, volcanic plumes, or engine exhaust.

The changes to the cmod format relevant to point sprites are minor. There's a new material attribute (blend add), a new primitive type (sprites), and a new vertex attribute type (pointsize). The sprite texture is texture0 from the material definition. Here is a very basic example of a sprite CMOD with three red sprites: 

#celmodel__ascii
material
diffuse 1 0 0
texture0 "gaussian.jpg"
end_material

mesh
vertexdesc
position f3
pointsize f1
end_vertexdesc

vertices 3
1 0 0 0.25
2 0 0 0.25
3 0 0 0.25

sprites 0 3
0 1 2

end_mesh

Blending

There are three options available in the CMOD format which affect how the geometry--triangles, lines, points or sprites--is blended with the background. They are normal, blend and premultiplied, with 'normal' the default.

For nebula meshes, it may be useful to specify additive blending in the material definition by adding the line 'blend add'. This is especially appropriate for emission nebulae, but definitely not to be used for dark nebulae like the Horsehead. Additively blended objects have the advantage of not needing to be depth sorted with respect to each other. Here's a slightly more complex sprite cmod that uses additive blending and per vertex colors so that each sprite has a different color: 

#celmodel__ascii
material
diffuse 1 0 0
texture0 "gaussian.jpg"
blend add
end_material

mesh
vertexdesc
position f3
pointsize f1
color0 f3
end_vertexdesc

# row of sprites: red, green, blue
vertices 3
1 0 0 0.25  1 0 0
2 0 0 0.25  0 1 0
3 0 0 0.25  0 0 1

sprites 0 3
0 1 2

end_mesh

For point sprites, each sprite has a color and an alpha value that are multiplied by the sprite texture color and alpha values to produce the fragment color/alpha (Fr Fg Fb) and Fa. The alpha value can be thought of as the opacity, though as you'll see, it's not always treated exactly that way.

Add is the simplest mode. If the background color is (Br Bg Bb), the final color will be: 

Fa * (Fr Fg Fb) + (Br Bg Bb)

Normal mode causes the background to be obscured; fragments with an alpha of 1 will completely block the background. 

Fa * (Fr Fg Fb) + (1 - Fa) (Br Bg Bb)

Finally, premultiplied is somewhat like normal except it omits the multiplication by the fragment alpha. It assumes that any reduction of the color due to transparency was already done when the geometry was created, hence the name premultiplied: 

(Fr Fg Fb) + (1 - Fa) (Br Bg Bb)

The advantage of premultiplied blending is that it can simulate either the add or normal blending modes with appropriately chosen alpha and color values. For example, setting alpha to zero gives the same result as additive blending. Cham: I think this is what you were talking about when you said you wanted to enable add individually for particles.

For nebulae, add is good for glowing, diffuse gases where absorption isn't too much of a factor. Premultiplied would in principle let you mix emissive and absorbing particles, but there's a catch: premultiplied and normal blending aren't generally commutative. For correct results, it's necessary to sort the particles from back to front and render them in order, which isn't something that Celestia currently does, as sorting a large number of particles can dramatically reduce performance. In fact, this order dependence of blending has been a big headache in realtime 3D graphics for a long time, and there's still no completely satisfactory solution for the problem.

Using TriStrips (by Toti)

A tristrip is an OpenGL primitive that draws a set of triangles this way: 

     1-----2 

     1-----2 
     \     / 
       \ / 
        3 

     1-----2 
     \     /\ 
       \ /    \ 
        3-----4 

     1-----2 
     \     /\ 
       \ /    \ 
        3-----4 
        \     / 
          \ / 
           5


So we can store this as: 1,2,3,4,5 (5 entries) With a trilist the same three triangles must be stored this way: 1,2,3 2,3,4 3,4,5 (9 entries, spaces are only to make text legible) Basically the first two vertices define a basis. For each added vertex v a new triangle is defined. This triangle if formed by the vertices [v-2][v-1][v].

In general, for a trilist of T triangles we need 3*T entries, but for a tristrip of T triangles T+2 entries are enough. So for large meshes you are saving 2/3 of the resources. The same can be applied to linestrips: 

     1---2 

     1---2 
         / 
       / 
       3 

     1---2 
         / 
       /  
       3----4 

     1---2 
         / 
       /  
       3----4 
           / 
         / 
         5


If the above mesh is defined as a linelist: 1,2 2,3 3,4 4,5 (8 entries). If it is defined as a linestrip: 1,2,3,4,5 (5 entries) A linelist needs 2*L entries for a set of L lines. A linestrip only needs L+1 entries for the same set. For large meshes the saving is about 50% of resources.

The usual way to work with these primitives is to model the object as usual and then use an optimization utility to convert from raw triangles to tristrips, etc. I don't know of any free program/library that can do this, though. Surely Chris does.

Using Trifans (by Toti)

            1-------2 
             \     / 
              \   / 
                3 

            1-------2 
          /  \     / 
         /    \   / 
        4------ 3 

       5------ 1-------2 
        \    /  \     / 
         \  /    \   / 
           4------ 3


Using trifans, the above mesh can be described as 1,2,3,4,5 Each tringle has the vertices [v0][v-1][v], where v0 is the first vertex of the set.

As you see, it's similar to a tristrip, but the first vertex is always the center of the trifan. You need T+2 entries to define T triangles, so it is as efficient as a tristrip (but often it can be used where a tristrip can't)

The advantage of using these primitives is that you save disk, bus and memory resources, because mesh descriptions are less voluminous.

Time Scales

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/Troubleshooting Scripts

Troubleshooting Addons

Celestia/Troubleshooting Addons

Development

A reader has identified this chapter as an undeveloped draft or outline.
You can help to develop the work, or you can ask for assistance in the project room.

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.

Developing Under Linux

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

Developing Under MacOS X

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

Developing Under Windows Vista

Celestia/Development/Windows Vista platform

Developing Under Windows XP

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%

Win CVS

How to get the C++ source code for Celestia with the latest WinCVS

This page is obsolete. Celestia code development now uses Subversion (SVN). CVS no longer works. For details of building Celestia under Windows, please read the page Windows XP 32bit & Windows 7, 64bit


December 30, 2005


Step 1 Get Python. To download Python, go to the official Website. http://www.python.org/

Step 2 Get WinCVS, the Concurrent Versions System 2.0.51d http://www.wincvs.org/

Step 3 Enter info into WinCVS to prepare for getting source code

Step 3b Create a new folder on your Hard Disk. I suggest to use a folder in the root. As an example my folder is: C:\CVS. This folder will be the base for our local CVS tree.

Step 3c Use menu Admin:Preferences to set Home to c:\CVS

Step 3d Understand that the Sourceforge Repository is a remote website. You will get your own copies of the source code into your computer directory c:\CVS\celestia (or c:\celestia if you make a mistake like I did).


Step 4 Communicate with the SourceForge website where the C++ source code is kept

Step 4a Use the WinCVS menu Admin:Login... A dialog window appears called Login settings. Put a checkmark in the CVSROOT box

Step 4b Paste this line in the login line for cvsroot

pserver:anonymous@celestia.cvs.sourceforge.net:/cvsroot/celestia


Step 4c When you are prompted for a password, do not type in anything, just hit the OK button

The console should report your success with code 0, as shown on 3 lines here:

cvs -d :pserver:anonymous@celestia.cvs.sourceforge.net:/cvsroot/celestia login Logging in to :pserver:anonymous@celestia.cvs.sourceforge.net:2401:/cvsroot/celestia

          • CVS exited normally with code 0 *****

If you get code 1, try again. Maybe the connection is too busy to service your login.


Step 4d Checkout the files with these commands. The first time this is a checkout. Future WinCVS sessions are updates, and the commands are the same.

Step 4e Use the menu Admin:Command Line...

Step 4f check the box for CVSROOT and put this line in the space next to that box:

pserver:anonymous@celestia.cvs.sourceforge.net:/cvsroot/celestia


Step 4f2 : check the box for Execute in directory, enter c:\CVS

Step 4g paste the command on the next line into the big empty command line box: cvs -z3 -d:pserver:anonymous@celestia.cvs.sourceforge.net:/cvsroot/celestia co -P celestia


Wait while files are then listed as they are sent to your computer. The console will show stuff like this :


cvs -d :pserver:anonymous@celestia.cvs.sourceforge.net:/cvsroot/celestia -z3 -d:pserver:anonymous@celestia.cvs.sourceforge.net:/cvsroot/celestia co -P celestia (in directory C:\CVS) cvs checkout: cwd=C:\CVS ,current=C:\CVS cvs checkout: Updating celestia U celestia/ABOUT-NLS U celestia/AUTHORS . . .

Wait while files are then listed as they are sent to your computer.

The files were put in c:\CVS\celestia

Also, download the Windows-specific shared libraries that aren't included with Celestia on SourcForge. http://shatters.net/celestia/files/winlibs-new.zip Unzip these files and put them in a directory with the other library files.

Now you have the C++ files.

Tortoise CVS

This page is obsolete. Celestia code development now uses Subversion (SVN). CVS no longer works. For details of building Celestia under Windows, please read the page Windows XP 32bit & Windows 7, 64bit


Acquiring Celestia CVS with TortoiseCVS (by Wcomer)

Celestia no longer uses CVS. Use ToroiseSVN instead.

  1. Download the latest version here: (1-2 min, 3.7 MB) http://www.tortoisecvs.org/download.shtml
  2. Follow the TortoiseCVS installation instructions. Note – you may be asked to reboot your machine but in my experience this wasn’t necessary.
  3. Create a new folder on your hard drive. Mine is called “C:\TortoiseCVS”. This will be your CVS repository
  4. Right-click your CVS repository folder and select “CVS Checkout”. If you do not see this option, then you must reboot your machine and try again.
  5. Enter “:pserver:anonymous@celestia.cvs.sourceforge.net:/cvsroot/celestia” as your CVSROOT. This should cause several other fields to fill in:
    1. Protocol - “Password server (:pserver:)”;
    2. Server – “celestia.cvs.sourceforge.net”;
    3. Repository folder – “/cvsroot/celestia”;
    4. User name – “anonymous”.
  6. Enter “celestia” as your Module.
  7. Press OK. Now the CVS client will attempt to download the Celestia source code. Expect the download time to be about 20 minutes mostly because the CVS server is a bit slow. If it is successful then there will be a subfolder called “celestia” within your CVS repository which will contain the current Celestia CVS archive.
    1. The checkout process may timeout, especially if you started it during a time of heavy traffic (that's late in the evening if accessing from Europe). You can continue the checkout at any time. Tortoise will restart with the incompletely checked out directory.
    2. If you normally use a dialup modem, you may safely do the initial checkout at an external broadband access and then copy the complete CVS directory to your local computer. Tortoise marks all CVS directories and will recognize the copied one instantly. Subsequent checkouts are usually only some dozen kB in size, and can be easily accessed from a dialup line.


Also, download the Windows-specific shared libraries that aren't included with Celestia on SourcForge. The libraries for use with Visual Studio 2003 are at http://shatters.net/celestia/files/winlibs-new.zip Unzip these files and put them in a directory with the other library files.


Development Road Map

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 KW4 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

Versions

A reader has identified this chapter as an undeveloped draft or outline.
You can help to develop the work, or you can ask for assistance in the project room.

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.
  • The previous stable version of Celestia, v1.4.1, was released in February, 2006.

Bugs and Feature Requests

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.

Acknowledgements

Celestia was created by Chris Laurel.

The Celestia AUTHORS file lists the following people:

  • Chris Laurel <claurel@gmail.com>
  • Clint Weisbrod <cweisbrod@cogeco.ca>
  • Fridger Schrempp <t00fri@mail.desy.de>
  • Bob Ippolito <bob@redivi.com>
  • Christophe Teyssier <chris@teyssier.org>
  • Hank Ramsey <hramsey@users.sourceforge.net>
  • Grant Hutchison <grant.celestia@xemaps.com>
  • Pat Suwalski <pat@suwalski.net>
  • Toti
  • Da Woon Jung <dirkpitt2050@users.sf.net>
  • Vincent Giangiulio <vince.gian@free.fr>
  • Andrew Tribick
  • Dmitry Brant
  • Hleb Valoshka
  • Levin Li
  • Łukasz Buczyński

Other contributors to the Celestia software distribution are cited in the README file.

Authors who have generously contributed material from their previously written documentation to this wikibook include:

  • Chris Laurel
  • Selden Ball

Add yourself here if appropriate

People who have made original contributions to this wikibook include:

  • Chris Laurel
  • Selden Ball
  • John Van Vliet
  • LukeCEL
  • SevenSpheres

add yourself here if appropriate

Many other people have also made valuable contributions to the Celestia community in various ways. Those that deserve special mention here are:

  • add deserving individuals (not yourself, of course!) with their permission here

And if we've inadvertently left out anyone you think should be mentioned, please add them!

GNU Free Documentation License

Version 1.3, 3 November 2008 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. <http://fsf.org/>

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

The "publisher" means any person or entity that distributes copies of the Document to the public.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

  1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
  2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
  3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
  4. Preserve all the copyright notices of the Document.
  5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
  6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
  7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
  8. Include an unaltered copy of this License.
  9. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
  10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
  11. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
  12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
  13. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified version.
  14. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
  15. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

11. RELICENSING

"Massive Multiauthor Collaboration Site" (or "MMC Site") means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A "Massive Multiauthor Collaboration" (or "MMC") contained in the site means any set of copyrightable works thus published on the MMC site.

"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

"Incorporate" means to publish or republish a Document, in whole or in part, as part of another Document.

An MMC is "eligible for relicensing" if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:

with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Retrieved from "https://en.wikibooks.org/w/index.php?title=Celestia/Print_Version&oldid=3229333"