Read Me

                          GLUNATIC README

CREDITS (incomplete)

Many thanks to Emil Persson, aka Humus (http://www.humus.name, humus@comhem.se),
for his fine cubemap textures, especially "Meadow.zip", which is the default
landscape texture for this software.

Bjorn Jonsson (http://www.mmedia.is/~bjj/planetary_maps.html)
produced very fine planetary maps.
Same for James Hastings-Trew (http://planetpixelemporium.com).
-------------------------------------------------------------

PREREQUESITES
  1) gcc
  2) gmake

-------------------------------------------------------------

SOFTWARE DEPENDENCIES
  1) Glx (for OpenGL)
  2) boost (headers+boost signals)
  3) libjpeg (/usr/include/jpegint.h is also required,
              you may have to install it manually)
  4) freetype


-------------------------------------------------------------

STAR CATALOGUES
Go into the catalogue directory and type

> g++ -O2 -Wall -Werror ConvertCatFrom0To1.C -o ConvertCatFrom0To1

This will produce an executable called ConvertCatFrom0To1.
With this program you can convert stellarium's star catalogues to major
version 1:

./ConvertCatFrom0To1 ~/.stellarium/stars/default/stars_0_0v0_1.cat
./ConvertCatFrom0To1 ~/.stellarium/stars/default/stars_1_0v0_1.cat
...and so on...

Now you have got the files

_your_path_is_here_/glunatic/catalogue> ls -l
total 1258976
-rwxr-xr-x 1 johannes users     13378 May 20 23:23 ConvertCatFrom0To1
-rw-r--r-- 1 johannes users      4349 May 20 23:23 ConvertCatFrom0To1.C
-rw-r--r-- 1 johannes users     42751 May 20 22:57 MakeCombinedCatalogue.C
-rw-r--r-- 1 johannes users     37165 May 20 22:56 ParseHipTyc.C
-rw-r--r-- 1 johannes users     17536 May 20 22:56 ParseNomad.C
-rw-r--r-- 1 johannes users    140476 May 20 23:24 stars_0_0v1_1.cat
-rw-r--r-- 1 johannes users    616324 May 20 23:24 stars_1_0v1_1.cat
-rw-r--r-- 1 johannes users   4240960 May 20 23:24 stars_2_0v1_1.cat
-rw-r--r-- 1 johannes users   4345792 May 20 23:25 stars_3_1v1_0.cat
-rw-r--r-- 1 johannes users  17275482 May 20 23:25 stars_4_1v1_0.cat
-rw-r--r-- 1 johannes users  46096018 May 20 23:25 stars_5_2v1_0.cat
-rw-r--r-- 1 johannes users 160019110 May 20 23:25 stars_6_2v1_0.cat
-rw-r--r-- 1 johannes users 348268348 May 20 23:26 stars_7_2v1_0.cat
-rw-r--r-- 1 johannes users 706781416 May 20 23:27 stars_8_2v1_0.cat

Leave the files where they are.

PS: You do not need all files.
If you want to, you can skip stars_8, stars_7, stars_6, ...

ALTERNATIVE:
Users with access to the NOMAD catalogue can use
ParseHipTyc, ParseNomad, MakeCombinedCatalogue for getting about
450000000 stars.

-------------------------------------------------------------

PLANET TEXTURES
You will need wget, and jpegtopnm,pnmtojpeg from the netpbm package.
Change into the 'data' directory and call "prepare_textures.sh".
By doing so you will download some textures from the internet
and convert then imto the required formats.
The textures have their own copyright and licenses, see prepare_textures.sh.

-------------------------------------------------------------

TEXT FONT
For displaying the GUI the program looks for
  /usr/share/fonts/dejavu/DejaVuSerif.ttf
You can also use other fonts by specifying
  font_file = /path/to/some/font,
in the window section of your config file.
You can also set a different font size:
  font_size = 18,

-------------------------------------------------------------

BUILDING
Go into the src directory and type 'make'. Now you have got an executable
called "glunatic". Leave it where it is.

-------------------------------------------------------------


RUNNING THE PROGRAM
In the src directory type './glunatic':

-----------ATI USERS BEGIN------------
Sadly enough the closed source ATI drive has really lots of bugs.
You can call:
> ./glunatic -c glunatic.config.ati
At least this work for me on ATI Radion express 1150.
Even though now all OpenGL windows use the same thread, the star searching and
preparation for rendering is done in multiple threads.

UPDATE: For my ATI Radion express 1150 I find ati driver 8.452 to be the best
version. With this I need no special config file.

-----------ATI USERS END--------------

No you have the following output on your console:
  [snip... default config when no config file was found ...snip]
main: reading of "mmap:../catalogue/stars_0_0v1_1.cat" ok; level: 0, nr_of_stars:      5013, mag_min: -2000, mag_range: 12800, mag_steps: 256
main: reading of "mmap:../catalogue/stars_1_0v1_1.cat" ok; level: 1, nr_of_stars:     21999, mag_min:  6000, mag_range: 12800, mag_steps: 256
main: reading of "mmap:../catalogue/stars_2_0v1_1.cat" ok; level: 2, nr_of_stars:    151416, mag_min:  7500, mag_range: 12800, mag_steps: 256
main: reading of "mmap:../catalogue/stars_3_1v1_0.cat" ok; level: 3, nr_of_stars:    434064, mag_min:  9000, mag_range:  1500, mag_steps:  30
main: reading of "mmap:../catalogue/stars_4_1v1_0.cat" ok; level: 4, nr_of_stars:   1725497, mag_min: 10500, mag_range:  1500, mag_steps:  30
main: reading of "mmap:../catalogue/stars_5_2v1_0.cat" ok; level: 5, nr_of_stars:   7669011, mag_min: 12000, mag_range:  1500, mag_steps:  30
main: reading of "mmap:../catalogue/stars_6_2v1_0.cat" ok; level: 6, nr_of_stars:  26615233, mag_min: 13500, mag_range:  1500, mag_steps:  30
main: reading of "mmap:../catalogue/stars_7_2v1_0.cat" ok; level: 7, nr_of_stars:  57826266, mag_min: 15000, mag_range:  1500, mag_steps:  30
main: reading of "mmap:../catalogue/stars_8_2v1_0.cat" ok; level: 8, nr_of_stars: 116923084, mag_min: 16500, mag_range:  1500, mag_steps:  30
ZoneArray::create(mmap:../catalogue/stars_9_2v1_0.cat): open failed: No such file or directory
main: reading of mmap:../catalogue/stars_9_2v1_0.cat failed
211371583 stars loaded

and a window labelled "glunatic".

Look into the menu: here you can change the planet/moon you are standing on,
and set some other things.

incomplete list of keyboard functions:
  up/down:                          CursorUp,CursorDown
  left/right:                       CursorLeft,CursorRight
  roll:                             Home,End
  zoom:                             PageUp,PageDown
  change brightness by +-0.1 mag:   '+','-'
  increase ephemeris time:          <ctrl>-m,m,<Shift>m,<Ctrl><Shift>m
  decrease ephemeris time:          <ctrl>-n,n,<Shift>n,<Ctrl><Shift>n
  disable/enable the stars:         's'
  disable/enable solar system:      'p'
  enable/disable the grid:          'g'
  enable/disable landsc./atmosph.:  'l'
  enable/disable fullscreen:        F1
  create a screenshot:              Ctrl-'s'

Or use the mouse: click&drag, mouse wheel for zoom.
Holding of left button can be combined with keystrokes, e.g. time control.
While holding middle or right button the mouse wheel changes the brightness.

-------------------------------------------------------------

EXPLANATION
Each window uses an own thread for OpenGL rendering plus 4 worker threads for
searching stars, coordinate transformation and preparation of vertex arrays
for the point sprites.
The rendering thread just takes these vertex arrays and stuffs them into the
graphic card. Here the GPU renders each of the stars by a pair of
vertex/fragment program. Both windows uses a different fragment programs.

This software architecture should allow fast rendering on multicore machines
with contemporary graphic cards (like NVidia series 8).

--------------------------------------------------------------

SPACENAVIGATOR (and similar) SUPPORT
3Dconnexion SpaceNavigator and other joysticks are supported via the XInput
extension. In your xorg.conf write something like:

           --------xorg.conf------------
Section "ServerLayout"
     ...
    InputDevice     "SpaceNav"
EndSection


Section "InputDevice"
        Identifier      "SpaceNav"
        Driver          "evdev"
        Option          "Name" "3Dconnexion SpaceNavigator"

# replace these with the values of your device obtained
# from /proc/bus/input/devices:
        Option "vendor" "1133"
        Option "version" "272"
        Option "product" "50726"

        Option          "XRelativeAxisMap"              "0"
        Option          "YRelativeAxisMap"              "1"
        Option          "ZRelativeAxisMap"              "2"
        Option          "RXRelativeAxisMap"             "3"
        Option          "RYRelativeAxisMap"             "4"
        Option          "RZRelativeAxisMap"             "5"
        Option          "ZRelativeAxisButtons"  "off"
        Option "Pass" "3"
EndSection
           --------xorg.conf end--------

Then with the command 'xinput list' determine the XID of your 3d device, let us
assume it is 4. Start glunatic with './glunatic -n 4'. You can move
around, turn and zoom with the navigator. While you hold the left button you
can increase/decrease the brightness by moving up/down.