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