Celestia/Add-Ons

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.