How to compile your own object catalogues?
Introduction
The user textual files are useful when the object databases are not too voluminous and that the user does not want to associate to the objects of these databases other information than the name and a commentary. In the opposite case, the load times and the refresh rate of the screen become prohibitive.
C2A for Windows offers the possibility to compile a catalogue of objects, that is to say, to produce a binary file directly readable by the C2A program. This is acheived by the means of an ASCII file (called a "model file"), where the syntax of the input catalogue is described by the user. Reading a binary file is a lot quicker than reading a textual file. Moreover, the user has the possibility to define it's own fields, of which the values will be displayed at the time of the identification of the compiled catalogue objects.
In order to compile a catalogue, it is necessary for the user to provide a number of informations in a text file called a “model” file. This information will allow the catalogue compiler to rediscover in the text file the data to be included in the compiled catalogue.
The compiler of data for C2A for Windows is called “DC” and must be launched from the Windows command line. This tool is available for downloading in the Tools section of the C2A for Windows site (http://www.astrosurf.com/c2a/tools.htm).
The diagram below shows how a C2A compiled catalogue is produced from a text
data file and a model file that describes the different fields in the text
file.
It is helpful to note that catalogues already compiled are available for downloading on the C2A Website (http://www.astrosurf.com/c2a/catalogues.htm).
Format of the Text Data Files
To be able to be compiled by the compiler DC, the input data in the text files must satisfy a number of constraints:
- the data concerning a specific object must be provided on single text line (one line per object),
- the data for an object must be formatted in columns: a specific data must begin on a given column and must have a well defined length, and this for all the objects (nevertheless, a field can contain characters “space”),
- Every entry must be able to be defined as a chain of characters (type string), an integer (type int) or a float (type float).
Model File Syntax
The syntax of the model file uses the notion of “field”. A field is defined by its beginning (a column number in the text file) and a length (the number of characters that compose the field). One can therefore give the following definition of the field notion:
<field> = <start> <length>
<start> = INTEGER
<length> = INTEGER
In a model file, all the information is expressed under the form of commands and arguments. A command (and its arguments) must be provided on a single line, and the first chain of characters on the line represent the name of the command. This name can be provided either in upper or lower case.
The general syntax of a model file is the following:
INPUT_FILE <file name>
OUTPUT_FILE <file name>
DATABASE_TYPE full | zones1 | zones2
DESCRIPTION "<string with 32 characters max>"
EQUINOX <equinox 1> <equinox 2>
OBJECT_TYPE star | galaxy
| open_cluster | globular_cluster
| diffuse_nebulae | obscure_nebulae
| planetary_nebulae | asteroid
| comet | supernova
| pulsar | galaxy_cluster
| binary_star | object
| quasar | source
RA [deg] <field> [<field>] [<field>]
DE <field> [<field>] [<field>]
MAGNITUE <field> [ignore='<character to be ignored>']* [mult=<multiplicative factor>] [defaut=<float>]
SET_MAGNITUDE <float>
LUMINOSITY <field> [ignore='<character to be ignored>']* [mult=<facteur multiplicatif>] [defaut=<float>]
SPECTRAL_TYPE <field> [defaut='<default character>'] [ignore='<character to be ignored>']*
SET_SPECTRAL_TYPE '<character>'
MAJOR_AXIS <field> [mult=<multiplicative factor>]
MINOR_AXIS <field> [mult=<multiplicative factor>]
INCLINATION <field>
SIZE <field> [mult=<multiplicative factor>]
COMMENT <field>
USER_FIELD <field> name="<field name>"
type=<integer | long | float | string> [purge_be=<y | n>]
[purge_all=<y | n>] [purge_mb=<y | n>] [search=<y | n>]
[prefix="<string>"]
IGNORE_LINE <list of lines to be ignored>
The syntax elements placed between “[” and “] ” are optional. The character “*” means that the syntax element to which it applies can be repeated several times. In the description above, the characters ' and " participate in the syntax and must be used in the model file.
The detail of each of the commands of the syntax is given in the following
paragraphs.
input_file
This comand allows the user to define the name of the input text file to be analyzed and compiled (e.g. C: \DATA\FILE1). This file name can be provided either in upper or lower case.
output_file
This command defines the name of the output file, i.e. the compiled catalogue. Note that in order for a file to be recognized as a compiled catalogue, it must have an extension ".ccc" (stands for C2A Compiled Catalog).
The binary data file produced by the compiler (and directly readable by C2A for Windows) can be of two different types :
- Type “full” : the compiled catalogue will be fully analyzed without any zone consideration at the time data is displayed on the screen. This type is not valid that for catalogues which are too voluminous (some thousands of objects), otherwise time of display becomes prohibitive on average powerful machines.
- Type “zones1” or "zones2": The celestian sphere is divided in 24 x 18 zones and only those which are in the current view are analyzed by CEA for Windows. This accelerates the display of very large compiled catalogues. There is no difference between zones1 and zones2 (these two values are kept to ensure compatibility with a former version of the C2A Planetarium program).
This command quickly describes the content of the compiled catalogue. This string must be provided between " " and must be 32 characters maximum.
equinox
This commands allows the user to specify an equinox transformation during the compilation process. The first year is the equinox of the text catalogue to be compiled and the second year is the equinox that must be used in the compiled catalogue.
Example: equinox 1950 2000
A compiled catalogue can only contain objects of a single type (star, galaxy, ...). The following table describes the allowed types as an argument of the OBJECT_TYPE command:
Object Type | Keyword | |
Star | star | |
Source | source | |
Galaxy | galaxy | |
Open Cluster | open_cluster | |
Globular Cluster | globular_cluster | |
Diffuse Nebulae | diffuse_nebulae | |
Dark Nebulae | obscure_nebulae | |
Planetary Nebulae | planetary_nebulae | |
Asteroid | asteroid | |
Comet | comet | |
Supernovae | supernova | |
Plulsar | pulsar | |
Quasar | quasar | |
Galaxy Cluster | galaxy_cluster | |
Double Star | binary_star | |
Object (User object without a specific type) | object |
ra / de
Defines right ascension and declination fields. Only the first field is mandatory. The "deg" argument in the RA command allows the user to specify that Right Ascensions are expressed in degrees, minutes and seconds of arc and not in hours, minutes and seconds of time. At the positions specified through these commands, the compiler expects to find integers or float numbers in the source textual files.
magnitude
The magnitude command is optional, exven for the start catalogues. This keywork must be immediately followed by a field definition (column number and length). If the magnitue command is not used, stars will be displayed as simple points within C2A. The optional argument "ignore" allows the user to specify characters that can be ignored during parsing. As an example, if the character '(' must be ignored, one can use the following argument:
ignore=‘(‘
The optional argument "default" allows the user to specify a default value of the magnitude. This value will be used in case of a problem while parsing the magnitude value. One can have for instance:
default=10.0
The optional argument "mult" can be used to transform the magnitudes found in the source file by a given multiplying factor. One can have for instance:
mult=0.01
set_magnitude
This command allows the user to define a unique value of the magnitude to be used for all the objects of the database.This command cannot be used if the "magnitude" command is used in the same model file.
luminosity
The "luminosity" command can be used to specify the luminosity associated to the objects of a database (and therefore their magnitude). The following formula is used to calculate the magnitude from the luminosity information:
where "mag" is the apparent magnitude of the object and "lum" is its apparent luminosity. The same optional argument as in the case of the "magnitude" command can be used.
spectral_type
This command allows the user to specify the spectral type of the stars in a catalogue. This keywork must be imeditely followed by a firrld definition.
Once all the "space" characters at the beginning of the field are purged, only the first character is analyzed. This character must be one of the following:
‘A’, ‘B’, ‘C’, ‘F’, ‘G’, ‘K’, ‘M’, ‘O’, ‘S’, ‘W’, ‘N’, ‘X’, ‘R’, ‘P’
If a character that doees not belong to this list iss found, this is the default value which is used (see below). If no default value is specified, the spectral type 'G' (yellow) is used.
The optional argument "ignore" can be used to ignore characters during the parsing process. This argument can be repeated several times. One can have for instance:
ignore=‘:’
The optional argument "default" allows the user to specify a default value for the spectral types. This default value is used when a problem is met during parsing or when the chacarecter found is not part of the list of valid spectral types.
set_spectral_type
This command allows the user to define a unique value of the spectral type to be used for all the objects of the database.This command cannot be used if the "spectral_type" command is used in the same model file.
major_axis
This command allows the user to define the major axis of a galaxy that can be represented under the form of an ellipse (defined by its major and minor axis as well as inclination from North to East). Values are expected in minutes of arc. An optional "mult" field can be used to transform the unit found in the source file.
minor_axis
This command allows the user to define the minor axis of a galaxy that can be represented under the form of an ellipse (defined by its major and minor axis as well as inclination from North to East). Values are expected in minutes of arc. An optional "mult" field can be used to transform the unit found in the source file.
This command allows the user to define the inclination of a galaxy that can be represented under the form of an ellipse (defined by its major and minor axis as well as inclination from North to East). Values are expected in degrees.
size
This command allows the user to define the dimension of an object that can be represented under the form of a disk (e.g. open cluster, globular cluster, ...). Values are expected in minutes of arc. An optional "mult" field can be used to transform the unit found in the source file.
This command allows the user to associate a comment to the objects. This comment will be displayed in the identification windows within C2A. Field length must be smaller than or equal to 80 characters.
Example: comment 47 70
This command can be used to create user defined fields. Beside the usual field definition (start and length), a certain number of arguments are mandatory. These are:
- name="<field name>" : <field name> is a string (between " ") and cannot exceed 20 characters.- type=<integer | float | string> : this second argument must be one of the following keywords: “integer” short integer from -32768 to+32768), “long” (long integer on 32 bits), “float” or“string”.The optional arguments are the following:
- purge_be=<y | n> : this argument can take the value “y” or“n”. It allows the user to specify that all the space characters at the beginning and at tthe end of the field must be purged.- purge_all=<y | n> : this argument can take the value “y” or“n”. It allows the user to specify that all the space characters in the field must be purged.- purge_mb=<y | n> : this argument can take the value “y” or“n”. It allows the user to specify that multiple space characters in the field must be transformed into a single space character.- search=<y | n> : this argument allows the user to define the field on which C2A will perform searches. There can be only one field with this search argument in a model file. This field will also be used to name the object in the information window within C2A.- prefix="<string>" : This argument can only be used jointly with the "search" argument. It allows the user to specify a prefix that will be used at the front of the field value displayed in the "Name" zone within the information window. This string must be put between double-quotes and cannot exceed 63 characters.User can specify up to 64 user fields.
Example: user_field 1 9 name="UGC number" type=string purge_all=y search=y
This command allows the user to specify a list of lines to be ignored in the textual data file. This command can take as argument several line numbers and the command itself can be repeated several times.
Example: ignore_line 124 453 765 787 1035
Example
Here is an example of a model file for the catalogue "QMW IRAS galaxy catalogue" (QIGC):
INPUT_FILE Qigc.txt
OUTPUT_FILE Qigc.ccc
DATABASE_TYPE full
DESCRIPTION "QMW IRAS galaxy catalogue"
EQUINOX 1950 2000
OBJECT_TYPE galaxy
RA 8 2 11 2 14 4
DE 20 3 24 2 27 2
MAGNITUDE 72 5
USER_FIELD 1 5 name="QIGC #" type=integer purge_all=y search=y prefix="QIGC "
One can notice that the prefix has a space character as the last character so that the object names are reported under the form 'QIGC 5463' in the name zone of the identification window.
Here is an extract from the input data file that contains the catalog objects:
One can easily check that the field declaration in the model file match the content of the file.
How to Launch the Compiler
The compiler is used with the following syntax:
DC [/?] [/check] [/line] [/notmp] [/quiet] [/64] <model file>
The arrgument have the following meaning:
- /? : display an help screen,- /check : only check the model file and the textual data file and does not actually compile the catalogue,- /line : display the faulty line in case a warning is reported by the compiler,- /notmp : avoid the creation of temporary files. Temporary files are normally created when compiling catalogues by "zone". They accelerate the compilation process but require more disk space,- /quiet : prevent the display of warning messages,- /64 : allows the user to specify up to 64 user fields (default value is 16)
Remark: a parameter between [ ] means that the argument is optional.