Celestia/STC File

Introduction
An STC file, or ST ar C atalog, 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  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 ("<tt>Eris:2003 UB313</tt>").

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)
 * Orbital elements (not listed here: see Trajectories § EllipticalOrbit)
 * 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.

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 "&alpha; 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 "&mu; 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 <tt>f</tt>
 * Dec <tt>f</tt>
 * Distance <tt>f</tt>

or
 * OrbitBarycenter "<tt>object path</tt>"
 * 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
or
 * AbsMag <tt>f</tt>
 * AppMag <tt>f</tt>

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 <tt>f</tt>

SpectralType controls the type of the star. It is a string, such as <tt>G2V</tt>, 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]

Mesh "accretion_disk.cmod"
 * The default spherical shape of a Star can be replaced by using the optional model declaration Mesh.


 * A Mesh may be a 3DS model, or one of Celestia's proprietary model types, either CMOD or CMS, which are described elsewhere.

Texture "image filename"
 * The default surface texture of a Star (normally determined from its SpectralType) can be replaced by using a Texture declaration
 * 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  is the Hipparcos/TYC index of the star you want to rename, and   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.