This document briefly explains the binary file format used by KStars
to store star data.

The use of binary data has improved the effeciency of loading of star
data significantly. 

The binary file consists of a header followed by data. The header
consists of three parts - a preamble, a machine readable field
descriptor and an index table. The data consists of two parts - an
variable-sized region for expansion and a series of records.

1. The header
=============

1.1. Preamble
-------------

 The preamble consists of the following:

 * A 124 byte-long string containing human-readable information about
   the file

 * A 2 byte-long endinanness indicator field, preinitialized to 'KS'
   (0x4B53) on the host machine

 The purpose of the endianness indicator is to make the file portable
 across machines of different endianness. A machine on which the
 endianness indicator field is read as 'SK' instead of 'KS' is of
 different endinanness from the machine on which the file was
 generated, and hence byteswapping must be performed.

1.2. Field Descriptor
---------------------

 The field descriptor describes the various fields used in the latter
 half of the data region. The field descriptor consists of the
 following:

 * A 2 byte-long unsigned integer, indicating the number of fields per
   record

 * A set of entries describing the fields, amounting to the number
   previously mentioned, each consisting of:

     - A 10 byte-long character array, providing a human-readable name
       for the field

     - A 1 byte-long integer carrying the size of the field in bytes

     - A 1 byte-long unsigned integer carrying the data type (see
       Appendix A)

     - A 4 byte-long integer storing a scale factor to divide the
       contents of the associated field by, to interpret it
       correctly. This is used for storing fixed-point fields. (Eg: A
       fixed-point number with 2 decimal places would have a scale
       factor of 100)

1.3. Index Table
----------------

 The format permits an index on one parameter. The parameter is to be
 represented by 2-bytes (eg: A running index from 0 to 65535). The
 index table consists of the following:

 * A 2 byte unsigned integer indicating the number of index entries

 * Index table entries, each consisting of:

     - A 2 byte-long parameter, which is the index
     
     - A 4 byte-long unsigned integer, storing the offset of the first
       record with this index parameter in the file

     - A 2 byte-long unsigned integer, storing the number of records
       under this index parameter.

2. The Data
===========

2.1. Expansion Fields
---------------------

 Certain specific information about the contents of the field may be
 added here. The contents could be specific to each application, and
 could be empty. For KStars star data files, the entries in this
 region are:

   + Faint magnitude limit * 100, stored as a 16-bit integer

   + HTM Level for this file, stored as a 8-bit integer. The
     convention followed is that "N0000" would belong to a HTMesh of
     level 3.

   + Maximum Stars per Trixel, stored as a 2-byte unsigned integer.

2.2. Data records
-----------------

 This region starts at the offset pointed out in the first entry of
 the index table. The data consists of a series of records, the
 details of whose fields (assumed to be placed continuously, without
 any gaps) are as described in the field descriptor in the header.

 NOTE: KStars _overrides_ the above defined convention for performance
 gains and ease of programming in the star names file, where records
 are stored as single blocks of the "starName" structure defined in
 kstars/kstars/skycomponents/starcomponent.h

3. Licensing Information
========================

(c) 2008. Akarsh Simha <akarshsimha@gmail.com>

This document is released under the GNU GPL v2 or, at your option, any
later version.

