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).

database_type

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).

description

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

object_type

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.

inclination

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.

comment

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

user_field

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

ignore_line

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.