Celestia/SSC File

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 "⁄" : "⁄") 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,

$P={\sqrt {(q/(1-e))^{3}}}$
or
$P=a^{1.5}$

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

$P={\sqrt {(q/(e-1))^{3}}}$

where:

P

is the period measured in years,

q

is the pericenter distance measured in AU,

e

is the eccentricity, and

a

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 $A$ constant in the Buratti disk function: $I/F=A{\frac {\mu _{0}}{\mu +\mu _{0}}}f(\alpha )+(1-A)\mu _{0}$ .^[1] A value of $A=0$ causes this function to reduce to the Lambert scattering law, while $A=1$ 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.