Star Catalogue Format
This document describes how Stellarium records it's star catalogues, and the related file formats.
Stellarium's Sky Model
The celestial sphere is split into zones, which correspond to the triangular faces of a geodesic sphere. The number of zones (faces) depends on the level of sub-division of this sphere. The lowest level, 0, is an icosahedron (20 faces), subsequent levels, L, of sub-division give the number of zones, n as:
Stellarium uses levels 0 to 7 in the existing star catalogues. Star Data Records contain the position of a star as an offset from the central position of the zone in which that star is located, thus it is necessary to determine the vector from the observer to the centre of a zone, and add the star's offsets to find the absolute position of the star on the celestial sphere.
This position for a star is expressed as a 3-dimensional vector which points from the observer (at the centre of the geodesic sphere) to the position of the star as observed on the celestial sphere.
Star Catalogue File Format
Stellarium's star catalogue data is kept in the stars/default sub-directory of the Installation Directory and/or User Directory (see section [sec:filesanddirectories]).
The main catalogue data is split into several files:
There also exist some control and reference files:
When Stellarium starts, it reads the stars.ini file, from which it determines the names of the other files, which it then loads.
The stars_hip_cids_0v0_0.cat and stars_hip_sp_0v0_0.cat files contain reference data for the main catalogue files.
A given catalogue file models stars for one and only one level (i.e. for a fixed number of zones), which is recorded in the header of the file. Individual star records do not contain full positional coordinates, instead they contain coordinates relative to the central position of the zone they occupy. Thus, when parsing star catalogues, it is necessary to know about the zone model to be able to extract positional data.
|File||Data Type||Data Record Size||Geodesic Level||#Records||Notes|
For a given catalogue file, there may be one of three formats for the actual star data. The variation comes from the source of the data - the larger catalogues of fainter stars providing less data per star than the brighter star catalogues. See tables [tab:Stellarium's-star-catalogue] and for details.
The catalogue files are split into three main sections as described in table File sections.
|File Header Record||0||Contains magic number, geodesic subdivision level, and magnitude range|
|Zone Records||32||A list of how many records there are for each zone. The length of the zones section depends on the level value from the header|
|Star Data Records||32+4n||This section of the file contains fixed-size star records, as described below. Records do not contain zone information, which must be inferred by counting how many records have been read so far and switching zones when enough have been read to fill the number of stars for the zone, as specified in the zones section above. The value of n used in the offset description is the number of zones, as described above.|
File Header Record
The File Header Record describes file-wide settings. It also contains a magic number which servers as a file type identifier. See table Header Record.
|Magic||0||int||4||The magic number which identifies the file as a star catalogue. 0xde0955a3|
|Data Type||4||int||4||This describes the type of the file, which defines the size and structure of the Star Data record for the file.|
|Major Version||8||int||4||The file format major version number|
|Minor Version||12||int||4||The file format minor version number|
|Level||16||int||4||Sets the level of sub-division of the geodesic sphere used to create the zones. 0 means an icosahedron (20 sizes), subsequent levels of sub-division lead to numbers of zones as described in section [sub:Zones]|
|Magnitude Minimum||20||int||4||The low bound of the magnitude scale for values in this file. Note that this is still an integer in Stellarium's own internal representation|
|Magnitude Range||24||int||4||The range of magnitudes expressed in this file|
|Magnitude Steps||28||int||4||The number of steps used to describes values in the range|
The Zone Records section of the file lists the number of star records there are per zone. The number of zones is determined from the level value in the File Header Record, as described in section [sub:Zones]. The Zones section is simply a list of integer values which describe the number of stars for each zone. The total length of the Zones section depends on the number of zones. See table Zones section.
|num stars in zone 0||0||int||4||The number of records in this file which are in zone 0|
|num stars in zone 1||4||int||4||The number of records is this file which are in zone 1|
|num stars in zone n||4n||int||4||The number of records is this file which are in zone n|
Star Data Records
After the Zones section, the actual star data starts. The star data records themselves do not contain the zone in which the star belongs. Instead, the zone is inferred from the position of the record in the file. For example, if the Zone Records section of the file says that the first 100 records are for zone 0, the next 80 for zone 1 and so on, it is possible to infer the zone for a given record by counting how many records have been read so far.
The actual record structure depends on the value of the Data Type, as found in the File Header Record.
See tables Star Data Record Type 0, Star Data Record Type 1 and Star Data Record Type 2 for record structure details.
It should be noted that although the positional data loses accuracy as one progresses though the Star Record Types, this is compensated for by the face that the number of zones is much higher for the files where the smaller precision position fields are used, so the actual resolution on the sky isn't significantly worse for the type 1 and 2 records in practice.
|hip||0||int||3||Hipparcos catalogue number|
|component_ids||3||unsigned char||1||This is an index to an array of catalogue number suffixes. The list is read from the stars_hip_component_ids.cat file. The value of this field turns out to be the line number in the file - 1|
|x0||4||int||4||This is the position of the star relative to the central point in the star's zone, in axis 1|
|x1||8||int||4||This is the position of the star relative to the central point in the star's zone, in axis 2|
|b_v||9||unsigned char||1||This is the magnitudemagnitude level in B-V colour. This value refers to one of 256 discrete steps in the magnitude range for the file|
|mag||10||unsigned char||1||This is the magnitudemagnitude level in the V-I colour. This value refers to one of 256 discrete steps in the magnitude range for the file|
|sp_int||11||unsigned short int||2||This is the index in an array of spectral type descriptions which is taken from the file stars_hip_sp.cat, the index corresponds to the line number in the file - 1|
|dx0||13||int||4||This is the proper motionproper motion of the star in axis 1|
|dx1||17||int||4||This is the proper motion of the star in axis 2|
|plx||21||int||4||This is the parallaxparallax of the star. To get the actual value, divide by 10000.|
|x0||0||int||20 bits||This is the position of the star relative to the central point in the star's zone, in axis 1|
|x1||20 bits||int||20 bits||This is the position of the star relative to the central point in the star's zone, in axis 2|
|dx0||40 bits||int||14 bits||This is the proper motionproper motion of the star in axis 1|
|dx1||54 bits||int||14 bits||This is the proper motion of the star in axis 2|
|b_v||68 bits||unsigned int||7 bits||This is the magnitudemagnitude level in B-V colour. This value refers to one of 256 discrete steps in the magnitude range for the file|
|mag||75 bits||unsigned int||5 bits||This is the magnitudemagnitude level in the V-I colour. This value refers to one of 256 discrete steps in the magnitude range for the file|
|x0||0||int||18 bits||This is the position of the star relative to the central point in the star's zone, in axis 1|
|x1||18 bits||int||18 bits||This is the position of the star relative to the central point in the star's zone, in axis 2|
|b_v||36 bits||unsigned int||7 bits||This is the magnitudemagnitude level in B-V colour. This value refers to one of 256 discrete steps in the magnitude range for the file|
|mag||43 bits||unsigned int||5 bits||This is the magnitudemagnitude level in the V-I colour. This value refers to one of 256 discrete steps in the magnitude range for the file|