Celestia/Tutorials/Simple Asteroids

This tutorial series will start with how to add asteroids into Celestia. Asteroids are one of the easiest objects to add to Celestia, because most of them can be simulated as bits of SSC code.

To add an asteroid to Celestia, you need an .ssc file. This can be created by taking any plain text file (.txt) and renaming the file extension to .ssc. This file can be named anything as long as it has the .ssc suffix. Then, it should be placed into the "extras" directory (i.e. a folder), or any folder within the "extras" directory.

Now, after you open the .ssc file, you need to define an asteroid by writing some code in it with your favorite text editor. Information for most asteroids can be found in various places, such as JPL's Small-Body Database Browser or Wikipedia. The basic definition looks like this:

Basic definition

"Name" "Sol"
{
	Class "asteroid"
	Mesh "mesh.*"
	Texture "texture.*"
	Radius <number>
	Color [ <number> <number> <number> ]
	BlendTexture true

	EllipticalOrbit
	{
	Epoch	        <number>
	Period		<number>
	SemiMajorAxis	<number>
	Eccentricity	<number>
	Inclination	<number>
	AscendingNode	<number>
	ArgOfPericenter <number>
	MeanAnomaly	<number>
	}

	Albedo <number>
	RotationPeriod <number>
}

We'll go through the parameters one by one. For fun, let's use the asteroid 24601 Valjean as an example.

Also, at any point you can add a comment to your .ssc code. A comment is started by a # sign and lasts until the next line break. It's a good idea to add comments explaining if you calculated parameters yourself, or if they are guesses.

List of parameters

Name

"Name" "Sol"

Here, "Sol" means to put the asteroid in orbit around the Sun, also known as "Sol". Name is just the name (or names) of the asteroid. If an asteroid has multiple names, separate them with colons (:). For asteroids it's customary to add the full name including its number, just the name itself, and the provisional designation (which looks like a four-digit number of year followed by some letters and numbers, usually two letters and several more numbers.) For Valjean, it would look like this:

"24601 Valjean:Valjean:1971 UW" "Sol"

Other asteroids haven't been named yet. These asteroids tend to be written like this, with one version containing the minor planet number:

"24601 1971 UW:1971 UW" "Sol"

Class

	Class "asteroid"

This line simply tells Celestia that the object is an asteroid.

Mesh

	Mesh "mesh.*"

This line tells Celestia what model to use. This line can left out, but it will result in the asteroid being a sphere, which most aren't in real life.

For most asteroids, their shape is unknown because we haven't imaged them in close detail. Celestia comes with two random models that are typically used for when the shape isn't known: asteroid.cms and roughsphere.cms. For Celestia, substitute mesh.* with one of the two models mentioned above.

If you want to model an asteroid's actual shape from a shape model, refer to Advanced Asteroids#Mesh.

Texture

	Texture "texture.*"

Textures are essentially maps that are wrapped around models. Again, most asteroids will not have textures because we haven't imaged them in close detail. In this case, asteroid.jpg is almost always used.

Radius

	Radius <number>

This parameter simply refers to the radius of the asteroid, in kilometers. If you're lucky, JPL's Small Body Database will have a diameter that you can divide by two to get the radius. However, many will not. In that case, the next best thing to use is the absolute magnitude parameter, for which a published value should exist for every asteroid.

The absolute magnitude parameter is essentially a value of how intrinsically bright it is, with a lower value meaning a brighter asteroid. Using this and the albedo value (explained in detail later), it is possible to estimate the size of the asteroid.

Unfortunately, many asteroids do not have known albedos either. So it is common to assume an albedo of about 0.4 for rocky objects and an albedo of about 0.08 for icy objects. To calculate the radius (in kilometers), use this formula:

$R={\frac {664.5}{\sqrt {p}}}10^{-0.2H}$

where $p$ stands for the albedo and $H$ stands for the absolute magnitude.

Color

	Color [ <number> <number> <number> ]
	BlendTexture true

The Color parameter is simply the RGB value of the object, when it appears as a dot. There are two ways to get this parameter: using the spectrum2rgb.c tool in the source code, and using color indices. BlendTexture true simply means that the texture is tinted the same color as the Color parameter. If you can't find any color-related information, leave it blank.

For ways of estimating the color of an asteroid from scientific data, refer to Advanced Asteroids#Color.

Orbit

	EllipticalOrbit
	{
	Epoch	        <number>
	Period		<number>
	SemiMajorAxis	<number>
	Eccentricity	<number>
	Inclination	<number>
	AscendingNode	<number>
	ArgOfPericenter <number>
	MeanAnomaly	<number>
	}

This bit of code defines how the asteroid orbits the parent body, in this case the Sun. Other parameters may be used, such as PericenterDistance, but this is the most common format.

Simply copy-paste values from a database, such as JPL's Small Body Database Browser. Note that the period is in years, not days, and the epoch is in Julian date format.

Albedo

	Albedo <number>

The albedo of an asteroid is a value from 0 to 1 that refers to what fraction of light gets reflected off the asteroid, with 0 being a complete dark object and 1 reflecting all of the light that hits it.

If you cannot find a published albedo value, you may have to estimate one. Counterintuitively, rocky objects tend to have higher albedos (around 0.4) than icy objects (around 0.08).

Rotation period

	RotationPeriod <number>

This is simply how long it takes for an asteroid to rotate once about its axis of rotation. The unit is in hours. For Valjean, there is a published value: 5.89 hours.

	RotationPeriod 5.89

Again, many asteroids do not have known rotation periods, so it is necessary to guess. As a rule of thumb, smaller asteroids haver shorter rotation periods.

For more accurate asteroid rotations that include things like axial tilt, refer to Advanced Asteroids#Rotational axis. These use different parameters from RotationPeriod.

Example code

For the sake of reference, here is what some .ssc code might look like for 24601 Valjean:

"24601 Valjean:Valjean:1971 UW" "Sol"
{
	Class "asteroid"
	Mesh "asteroid.cms"
	Texture "asteroid.jpg"
	Radius 1.1 # assuming albedo of 0.4

	EllipticalOrbit
	{
	Epoch	        2459000.5
	Period		3.31008102884
	SemiMajorAxis	2.22102586047
	Eccentricity	0.19003032943
	Inclination	6.40072085043
	AscendingNode	37.6267058410
	ArgOfPericenter 348.001749666
	MeanAnomaly	253.443255341
	}

	Albedo 0.4 # guess
	RotationPeriod 5.89
}