How do you Compile your Own Catalogues of Objects?

Introduction

User text files (see the section How to define your own catalogues of objects) are useful when the databases to be loaded are not too large and when the user does not wish to associate with objects in these databases information other than a name and a comment. Otherwise, load and screen refresh times become prohibitive.

C2A lets you compile a database, that is, to produce a binary file which can be read directly by the program, from any ASCII file whose syntax is described by the user. The reading of a binary file is very much quicker than the reading of a text file. Furthermore, the user can define his own fields whose values will be displayed in the identification of the objects in a compiled database.

To enable a textual database to be compiled, the user must provide some information in a text file named “template”. This information will allow the database compiler to find relevant data in the text file to be placed in the binary database.

The database compiler in C2A is called “DC” and must be run from the Windows command line. This tool is available for downloading from the Tools section of the C2A site (http://astrosurf.com/c2a/english/download.htm).

The figure below shows how to produce a binary file that can be loaded in C2A, from a textual database and a template file which describes the different fields in the database.

Note that some already compiled databases are available to download from the C2A website (http://astrosurf.com/c2a/english/download.htm).

Format of textual database files

To be compiled by the compiler DC, input data provided in text files must meet a number of constraints:

-   the data relating to a particular object must be given in a single line of text (one line per object),

-   the data for an object must be formatted in columns: a particular data item must begin in a given column and must have a fixed length for all objects (however, a field may contain "space" characters),

-   each item of data must be defined as a character string (string type), an integer (int type) or as floating point (float type).

Syntax of template files

The syntax of template files is based on the concept of “field”. A field is defined by its beginning (a column number in the textual database file) and a length (the number of characters comprising the field). The following definition can thus be given for the field concept:

<field> = <start> <length>
<start> = INTEGER
<length> = INTEGER

In a template file, all information is provided by commands and arguments. A command (and arguments) must be expressed in a line, and the main character string in the line represents the name of the command. This name can be in upper or lower case

The general syntax of a template file is as follows:

INPUT_FILE <file name>

OUTPUT_FILE <file name>

DATABASE_TYPE full | zones1 | zones2

LINE_LENGTH <integer>

DESCRIPTION "<string of characters, 32 maximum>"

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=<multiplier>] [defaut=<floating point number>]

SET_MAGNITUDE < floating point number>

LUMINOSITY <field> [ignore='<character to be ignored>']* [mult=<multiplier>] [defaut=<floating point number>]

SPECTRAL_TYPE <field> [default='<default character>'] [ignore='<character to be ignored>']*

SET_SPECTRAL_TYPE '<character>'

MAJOR_AXIS <champ> [mult=<multiplier>]

MINOR_AXIS <champ> [mult=<multiplier>]

INCLINATION <field>

SIZE <field> [mult=<multiplier>]

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="<character string>"]

IGNORE_LINE <list of lines to be ignored>

The syntactic elements placed between square brackets (“[” and “]”) are optional. The character "*" means that the syntactic element to which it applies may be repeated a number of times. In the description above, the characters ' and " are part of the syntax and must be used in template files.

Details of each command are given in the following paragraphs.

input_file

This command lets you define the file name of the textual database to be analysed. The file name in the argument may have a DOS path name (e.g. C:\DATA\FILE1) but this is not mandatory (in which case the file cited is looked for in the current directory). It does not matter if the file name is in upper or lower case characters.

output_file

This command lets you define the file name of the binary file to be produced by the compiler. The file name in the argument may have a DOS path name (e.g. C:\DATA\FILE1) but this is not mandatory (in which case the file cited is looked for in the current directory). It does not matter if the file name is in upper or lower case characters.

 

database_type

The binary database produced by the compiler (and directly readable by C2A) can be of two different types:

-        full” type: the database will be displayed on the screen in its entirety when loaded in C2A (i.e. all objects visible in the current display will be systematically displayed). This type is suitable for databases which are not too big (a few thousand objects) else display time will be prohibitive on moderately powerful machines.

 

-        zones1” or "zones2" type: this type allows you to produce a database which will be displayed in zones when loaded into C2A. The celestial sphere is divided into 24 x 18 zones (corresponding to 24 hours in right ascension and 180 degrees in declination) and one zone therefore corresponds to 1 hour in right ascension and 10 degrees in declination. C2A determines which zones contribute to the view to be displayed and will attempt to find objects belonging to these zones. This improves display efficiency. This method is used to display the SAO database provided with C2A. The values "zones1" and "zones2" in effect mean the same thing. They are retained for reasons of compatibility with earlier versions of C2A.

 

line_length

This optional command lets you indicate that you wish to pad, with spaces, lines of the catalogue used as input to a length specified in the argument of this command. This length must not exceed 1023 charcters.

This command is useful for textual catalogues which have shorter lines that do not contain all the information present in other lines. This avoids error messages during compilation.

description

This optional command lets you describe succinctly the content of the database using a string of up to 32 characters. This string must be enclosed in quotation marks (").

So that a file can be automatically recognized as a compiled user file, it must have the extension "ccc" (which means C2A Compiled Catalogue). In the absence of this convention, user files will not be recognised in the directory of data specified with the command “Add…” in the user catalogues dialogue box.

equinox

This command lets you specify a transformation of equinox when converting a textual database to a binary file. The two parameters in this field must be integers. The first gives the original year of equinox; the second the year of the destination equinox.

Example: equinox 1950 2000

object_type

A database compiled by the DC compiler may not contain objects of a single type (stars, galaxies, etc…). The authorised types are the same as those in textual databases that can be loaded in C2A

The following table lists these types and also the key words associated with them which must be used as arguments with the command OBJECT_TYPE :

 

Object Type

Key Word

 

Star

star

 

Any source

source

 

Galaxy

galaxy

 

Open cluster

open_cluster

 

Globular cluster

globular_cluster

 

Diffuse nebula

diffuse_nebulae

 

Dark nebula

obscure_nebulae

 

Planetary nebula

planetary_nebulae

 

Asteroid

asteroid

 

Comet

comet

 

Supernova

supernova

 

Pulsar

pulsar

 

Quasar

quasar

 

Galaxy cluster

galaxy_cluster

 

Double star

binary_star

 

Object (user object without type)

object

The type of object can be given in either upper or lower case characters.

ra / de

Right ascension and declination are defined by at least three fields. Only the first is obligatory and defines the hours of right ascension (and respectively, the degrees of declination). The optional fields define the minutes and seconds of right ascension (and respectively, the minutes and seconds of declination). If one or both of these optional fields are absent, the value of right ascension (declination) is calculated only from the fields present.

 

In declaring right ascension, you can put the key word deg in front of the first field which specifies that in the text file to be analysed, right ascension is expressed in degrees, minutes and seconds of arc, and not in hours, minutes and seconds.

 

In the locations specified by these fields, the compiler expects to find integer or real numbers in the textual data files to be analysed.

magnitude

The magnitude command is optional in template files, even for databases of stars (i.e. in which the objects are of type star). This keyword must immediately be followed by the field definition (number of column and length of field in characters). If the magnitude of stars is not defined (absence of commands magnitude and set_magnitude), stars will be displayed as simple undifferentiated points on the screen, and their magnitude will not be reported when identified.

The optional argument ignore can be repeated any number of times and lets you specify the characters to ignore when reading character strings which define magnitudes (when reading textual data files). For instance, if the character ‘(‘ is to be ignored (this is the case in databases defining variable stars), you use the argument:

ignore=‘(‘

The user must specify with this argument all characters which might interfere with the recognition of floating point numbers or integers (as magnitudes must be defined by floating points or integers if they are actually to be used).

The optional argument default allows you to specify a default value for magnitudes. This default value is used when a problem arises in reading a magnitude value in a textual data file (recognition of a character string which does not represent a floating point number or integer, pure and simple absence of characters etc…). For example: the following argument could be used:

default=10.0

This argument can appear only once in the magnitude command in a template file. For stars, if no default value is specified and an error occurs when reading a magnitude, the program will just display points.

You can also use the optional field mult to specify a multiplier which will be applied to the value found in the textual data file. The default value is 1. For example, you could have the following argument:

mult=0.01

set_magnitude

This command lets you define a unique value for magnitude which will be used for all objects in the database. This command must not be used if the magnitude command is used in the file.

luminosity

The luminosity command lets you specify the luminosity associated with objects in the database and therefore, indirectly, their magnitude. This is especially useful for  objects with the type source (sources of X-rays, etc…) as these catalogues usually provide apparent luminosity rather than apparent magnitude.

The magnitude of objects (which will be used to display objects of type star and source or will just be reported at identification for other types) is calculated with this formula:



where mag is the apparent magnitude of an object and lum the apparent luminosity. You can also use the optional mult field to specify a multiplier which will be applied to a value found in the textual data file. The default value is 1.

spectral_type

This command lets you define the spectral type of stars in a database. The keyword must be immediately followed by the field definition (column number and length of field in characters).

Once purged of spaces at the beginning and end of a string, only the first character is analysed. This character must be one of those in the following list:

‘A’, ‘B’, ‘C’, ‘F’, ‘G’, ‘K’, ‘M’, ‘O’, ‘S’, ‘W’, ‘N’, ‘X’, ‘R’, ‘P’

If a character which does not appear in this list is detected, the default value is used (see below how to specify the default value). If no default value is specified, the spectral type ‘G’ is always assigned to the star and it is displayed in yellow.

The optional argument ignore can be repeated any number of times and allows you to specify the characters to be ignored when reading character strings which define spectral types. You use, for example, the argument:

ignore=‘:’

to ignore ‘:’ characters in fields which define spectral types.

The optional argument default lets you specify a default value for spectral types. This default value is used when:

-   a problem is encountered when reading the field defining the spectral type,
-   the character found is not in the list of authorised characters (see above).

set_spectral_type

This command allows you to specify a unique spectral type for all stars in a database. It cannot be used if the command spectral_type is used in the template file.

major_axis

This command lets you define the major axis of a galaxy which can be represented by an ellipse (defined by its major and minor axes and its inclination with respect to North in an easterly direction).

The three commands major_axis, minor_axis and inclination are used for galaxies, but nothing prevents them from being used for other types of objects (they will not be used apart from major_axis) except if the field size is also defined (in this case an error is reported).

Values in databases to be compiled must be expressed in arc minutes. You can also use the optional field mult to specify a multiplier which will be applied to the value found in the textual data file. The default is 1.

minor_axis

This command lets you define the minor axis of an extended object which can be represented by an ellipse (defined by its major and minor axes and its inclination with respect to North in an easterly direction).

Values in databases to be compiled must be expressed in arc minutes. You can also use the optional field mult to specify a multiplier which will be applied to the value found in the textual data file. The default is 1.

inclination

This command allows you to define the inclination of a deep sky object (it is used in conjunction with the commands major_axis and minor_axis). This inclination must be calculated from North towards East and must be expressed in degrees.

size

This command lets you define the dimension of an extended object which can be represented as a circle.

The command size can be used for objects of the following types: open cluster, globular cluster, diffuse nebula, dark nebula, planetary nebula, supernova, galaxy cluster and object (user object of undefined type).

Values in databases to be compiled must be expressed in arc minutes. You can also use the optional field mult to specify a multiplier which will be applied to the value found in the textual data file. The default is 1.

comment

This command allows you to associate a comment with each object, a comment which will be displayed in the message area at the bottom of the information screen in response to an identification. This ability is useful for a long field (in terms of characters) which you cannot define as a user field (see the next command). The length of the associated field must be smaller or equal to 80 characters.

Example:comment 47 70

user_field

This command lets you define user fields. Besides the field definition (column number and length of field in characters), some obligatory arguments must be supplied. These are:

-        name="<field name>" : <filed name> is a character string (enclosed by the characters "). The name must not be more than 20 characters.

-        type=<integer | float | string> : the second element of this expression must be one of the keywords “integer” (integer between -32768 à +32768), “long” (32 bit long integer), “float” or “string”. A user field can therefore have as one of the types: integer, long, floating point or character string.

Optional arguments are as follows:

-        purge_be=<y | n> : this argument can take the value “y” or “n”. It allows you to specify that you want to delete all leading and trailing spaces in a character string representing the field to be analysed (“be” means “begin” and “end”).

 

-        purge_all=<y | n> : this argument can take the value “y” or “n”. It allows you to specify that you want to delete all spaces in a character string representing the field to be analysed (“all” means all “spaces”).

-        purge_mb : this argument can take the value “y” or “n”. It allows you to specify that you want to delete all multiple spaces in a character string representing the field to be analysed (“mb” means all “ multiple blanks”). Thus, 3 successive spaces are transformed into a single space.

 

-        search=<y | n> : this argument lets you define the field on which C2A will perform searches. A single user field can have this argument with the value “y” in a user file. The field which has the argument search will also be used to identify an object by its name (in the “Name” area of the object information dialogue box).

 

-        prefix="<character string>" : this argument can only be used with the argument “search”. It lets you to specify the prefix that will be placed before the filed value in the name area of the object information dialogue box. This character string must be enclosed within quotation marks (") and must not exceed 63 characters.

The user may specify up to 64 fields in a template file (see the syntax for launching the database compiler in this section).

Example: user_field 1 9 name="UGC number" type=string purge_all=y search=y

ignore_line

This command allows you to specify a list of lines to be ignored in the textual database. It can take any number of arguments (the numbers of the lines to be ignored) and can be repeated any number of times.

Example:ignore_line 124 453 765 787 1035

Example

Here is a simple example of a template file for the "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 "

Note that the prefix has a trailing space so that identifiers of objects from the catalogue will have the form 'QIGC 5463' in the name area of the object information dialogue box.

Here is an extract of the contents of the original file containing objects from the catalogue:

You can verify that the declarations of the fields in the template file match.

Launching the complier

The launching of the compiler requires the following syntax:

DC [/?] [/check] [/line] [/notmp] [/quiet] [/64] <template file>

The meaning of these parameters is as follows:

-        /? : display a help screen,
/check : operate only to verify the template file and textual database,

-        /line : display the line number if it produces a warning,

-        /notmp : do not create temporary files. These temporary files are created for databases compiled “in zones”. They speed up the compilation process but require more disc space,

-        /quiet : do not display warning messages,

-        /64 : allow up to 64 user fields (the default value is 16),

Note: a parameter between [ ] means “optional argument”.

 

Table of Contents