1THIS DIRECTORY:
2---------------
3This directory contains tools used to analyse the data used in
4KStars. It has tools to test, read and create the binary files used
5for star data amongst other things.
6
7Most of these programs (particularly the C / C++ programs) are rather
8poorly written code, but somehow happen to work. Also, this directory
9can be a pain to build (read the note in the Makefile for details). I
10really don't know if it is worth spending time cleaning all this up,
11since it's anyway something that very few people would be interested
12in building (or so I think).
13
14Most of the perl scripts are due to James Bowlin, who can be contacted
15at <bowlin@mindspring.com>. Most of the C programs are my work, and I
16can be contacted at <akarsh@kde.org>
17
18Some of the Perl scripts require the HTMesh perl wrapper, which is
19also present in this directory. The library is released under a
20license more liberal than GPL, and the details are found in the README
21file in the relevant directory. This library needs to be built (it
22depends on the HTMesh C++ library, available in kstars/kstars/htmesh)
23and installed before running many of the Perl scripts in this
24directory.
25
26Many of the Perl scripts and C++ programs as of this writing require a
27MySQL database server to be available on localhost. The database is
28used as an intermediary to hold the data loaded from ASCII data files
29in a nice format.
30
31DESCRIPTIONS OF FILES:
32----------------------
33
34read-hippo.pl        Reads the Hipparcos catalog files
35
36reformat-hip.pl      Converts old format star data files into the new format,
37                     where the fixed length Genetive name comes before the
38                     variable length long name
39
40mag-linenum.pl       Write the line number magnitude index file
41
42max-length.pl        Find the longest line in a file
43
44sort-hip-by-pm.pl    Sort the Hipparcos catalog data by proper motion
45
46hipdatatomysql.pl    Reads Hipparcos star catalog text files and puts them into
47                     a MySQL database (server on localhost). CAUTION: This script
48                     will empty the table that it is writing into.
49
50tycdatatomysql.pl    The Tycho star catalog text files used by KStars are in a
51                     different format from the Hipparcos catalog files. This script
52                     puts the data from the Tycho star catalog into a MySQL
53                     database. It's just a modified version of hipdatatomysql.pl
54
55binfiletester.c      C Program to test KStars' star data in binary format
56
57nomadbinfiletester.c C Program to test KStars' deep star data from the
58		     NOMAD catalog in binary format
59
60mysql2bin.c          C Program to put data from the MySQL database (generated
61		     using datatomysql.pl) into the binary data format defined
62		     by KStars. [See README.fileformat in the kstars/data
63		     directory]. To make this, you will need to have the
64		     libmysqlclient-dev package or equivalent installed
65
66nomaddatatomysql.pl  Reads the NOMAD catalog data in ASCII format and puts it into a
67                     MySQL database for easy processing. This is just a modified
68                     version of tycdatatomysql.pl
69
70nomadbinfile2mysql.c Reads binary NOMAD catalog data and puts it in a
71		     MySQL database for easy processing.
72
73# TODO: Document the split and merge stuff.
74
75BUILDING THE PROGRAMS:
76----------------------
77
78To build both the C programs, use:
79
80   make
81
82To build only mysql2bin, use: [Requires MySQL client library]
83
84   make mysql2bin
85
86To build only binfiletester, use:
87
88   make binfiletester
89
90To clean up, use:
91
92   make clean
93
94CREATING THE DATA FILES:
95------------------------
96
97To create and put the binary data files in kstars/data, first export
98your MySQL DB username and password:
99
100   export KSTARS_MYSQL_DB_USER='<your DB username>'
101   export KSTARS_MYSQL_DB_PASS='<your DB password>'
102
103If the database in which the star data table is stored is not
104identical to the DB username, export that too:
105
106   export KSTARS_MYSQL_DB_DB='<the DB name>'
107
108If the table in which the data is present is not allstars (default if
109you used datatomysql.pl to generate the tables), then export that too:
110
111   export KSTARS_MYSQL_DB_TBL='<table name>'
112
113Then, finally do:
114
115   make datafiles
116
117This will build mysql2bin, collect the data, and put it in
118kstars/data.
119
120If 'make datafiles' hangs (it typically takes about 5 - 10 minutes),
121then you should first double check that it is really hanging by
122setting VERBOSE to 1 on line 17 of mysql2bin.c and retry. If it shows
123no progress, reduce the value of MYSQL_STARS_PER_QUERY in the #define
124directive on line 24 of mysql2bin.c till it works. This is because the
125database query may hang if the query results are too large in size. I
126don't know why this happens, but it seems to work that way.
127
128LICENSING INFORMATION:
129----------------------
130Copyright (c) 2008-2011 Akarsh Simha <akarsh.simha@kdemail.net>
131This document is released under the terms of the GPL v2.
132