Celestia/Catalog File Reference

Types of Catalog Files

Celestia's universe contains three broad categories of objects:

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

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

Common Syntax of Catalog Files

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

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

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

Number Values

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

1234
3.14159265
1.234e10
0.1025
-2.24

.1025  (Celestia v1.5.0 or later)
+2.24  (Celestia v1.5.0 or later)

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

String Values

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

\": Double quote character
\n: Newline
\\: Backslash
\uxxxx: Unicode character, where xxxx is a sequence of four hex digits

Vector Values

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

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

Property List Values

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

UniformRotation
{
   Period 24.0
   Inclination 23.5
}

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

Date Values

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

Examples of date values with explanatory comments:

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

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