\documentclass[11pt,oneside] {article}
\usepackage{float}
\usepackage{html}

\setlength {\textheight} {22cm}
\setlength {\textwidth} {16cm}
\setlength {\oddsidemargin} {0cm}
\setlength {\evensidemargin} {0cm}

\begin{document}
\title{\textbf{Stellarium Developer guide} \\{v 0.2}}
\author{Fabien Ch\'ereau}

\maketitle

\begin{abstract}
This document is aimed at giving a global vision on the organization of the program source code.
\end{abstract}

\section{Introduction}
Stellarium is almost totally designed in an object oriented way. Its source code is thus quite easy to understand and is well subdivided.
The interface with the OS is done using the SDL library which has proven to be powerfull, truly multiplateform and fast.
Project managment is done using sourceforge.net services for cvs hosting, bug tracking, forums etc.. Globally, everything usefull for the project is available at the main project page \htmladdnormallink{http://sourceforge.net/projects/stellarium/}{http://sourceforge.net/projects/stellarium/}.

\section{I want to contribute in developing stellarium. How to start?}
First of all, as stellarium is mainly programmed in C++ you will need some knowledge in object oriented programming.
You will then need to use the GNU development tools and utilities that are required for working on free projects.

Stellarium source code is stored on sourceforge.net server using cvs (concurent version system). This enable everybody to download the last changes in the sources. The cvs version of stellarium is usually on development and might not work at all.


Here are the first steps to start working on the sourcecode : (see detailed instructions from \htmladdnormallink{sourceforge cvs page}{http://sourceforge.net/cvs/?group\_id=48857})
In the stellarium cvs repository, there is only one module called "stellarium"
containing all the project files. So, to get the files as anonymous developer, just type (as explained) :

{\tt cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/stellarium login}

and type {\tt enter} when a password is required.

{\tt cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/stellarium co stellarium}

(co = checkout)
And normally all the project files should be downloaded in a new {\tt stellarium/} directory.
In this directory you will find the script {\tt autogen.sh} that you need to execute in
order to run the automake/autoconf things.
After that you can launch the {\tt ./configure} script which will analyze your system.
If everything goes fine, the command {\tt make} should then compile all the sourcecode.

You can now try to launch the local version by typing {\tt ./src/stellarium}

Here you are!

You can now have a look at the {\tt src/} directory where you will find the source files described below.
Edit whatever you want in it and when your new great feature is done you will need to share it with the community of stellarium developers.

At this point, an official developer just have to type {\tt cvs commit} to update the repository version. But as you are not an official developer (yet!) you will need to create a patch file which will contain all the changes you did on the source code.

{\tt cd directory-you-want-to-diff}

{\tt cvs -z3 diff -u > mypatch.diff}

You can now submit mypatch.diff on the sourceforge stellarium page in the \htmladdnormallink{patches section}{http://sourceforge.net/tracker/?group_id=48857&atid=454375} with a clear comment on what is the patch doing.

The project administrator will then have a look at it and decide whether the patch is accepted or rejected for integration into stellarium.

\section{Main files description}
All the files starting with a s\_ are "theoricaly" independent of the main program. They manage textures, font and user interface and could be re-used for any other openGL application.

\begin{description}
	\item[stel\_sdl.h/cpp :] Class handling sdl functions. It contains the main loop intercepting all the system events and send them to the core.
	\item[stel\_core.h/cpp :] Main stellarium class. It manages all the main components of the program and stores all the attributes of the program.
The 3 main functions of the program are methods of his class. They are :
	\begin{description}
		\item[init() :] Initialize the core of the program : creates all the main objects and initialize them.
		\item[update() :] Update all the objects : time, viewing, planet positions, moves, user interface etc..
		\item[draw() :] Draw everything on the openGL buffer.
	\end{description}
update() and draw() are called in the main loop at each iteration.
The stel\_core class manages all the configuration file reading and saving.

	\item[navigator.h/cpp :]
Manage all the astronomical navigational functions. Used for frames conversions.

	\item[observator.h/cpp :]
Manage all the information relative to an observator (position, locales etc..)

	\item[projector.h/cpp and fisheye\_projector.h/cpp :]
One of the class i'm proud of :). Manage various kind of projections : perspective, fisheye.

	\item[init\_parser.h/cpp :]
Wrapper c++ class for the c library initparser.

	\item[stel\_object.h/cpp :]
Abstract mother class for all astronomical objects stars, planets and nebula.

	\item[hip\_star.h/cpp and hip\_star\_mgr.h/cpp :]
Manage stars from the hipparcos catalog and stars collections respectively.

	\item[grid.h/cpp :]
Used for optimization with grid structure while displaying the hipparcos star catalog.

	\item[planet.h/cpp and solarsystem.h/cpp :]
Manage any body which has a defined position inside the solar system.

	\item[nebula.h/cpp and nebula\_mgr.h/cpp :]
Manage nebula and nebula collection repectively.

	\item[constellation.h/cpp and constellation\_mgr.h/cpp :]
Manage constellations and collection of constellations respectively.

	\item[landscape.h/cpp :]
Manage landscapes.

	\item[stel\_atmosphere.h/cpp :]
Manage atmosphere rendering. Uses the classes sky\_bright and sky\_light to compute sky color and brightness and display it.

	\item[tone\_reproductor.h/cpp :]
The class which simulate the eye adaptation to luminance.

	\item[draw.h/cpp :]
Groups some classes used to draw various objects of the program : milky way, grids, astronomical lines, cardinal points.

	\item[stel\_ui.h/cpp :] manage the user interface for stellarium using s\_gui/s\_tui widgets.

	\item[s\_gui.h/cpp :]
All the Graphical User Interface (gui) classes. Used in the desktop version only.

	\item[s\_tui.h/cpp :]
All the Text User Interface (tui) classes. Used in planetarium version only.

	\item[s\_font.h/cpp :]
Manage fonts. The font in stellarium are not bitmap but taken from a real grey level texture.

	\item[s\_texture.h/cpp :]
Class which manages textures. Currently uses glpng library to handle png files.

	\item[callback.h/cpp :] Handfull class made by the boost library team used to handle callbacks. It's used for the widgets.
\end{description}

\section{External libraries (directories in src/)}
\begin{description}
	\item[glpng :] create openGL textures from .png files. Written in C and used thru the s\_texture class.
	\item[iniparser :] config files parsing. Used thru the wrapper class init\_parser.
	\item[stellastro :] miscelaneous astronomical functions.
	\item[stellplanet :] compute heliocentric positions of solar system planets.
\end{description}

\section{Stellarium data files format specification}

\begin{itemize}
\item commonname.fab and name.fab

\begin{description}
\item[desc :] Contains the commonly used stars names.
\item[type :] ascii file, fields separated by \verb1|1 (pipe), end of line is CR ('\verb1\1n')
\item[line example :] \begin{verbatim}62956|Alioth\end{verbatim}
\item[line format :] HPnum\verb1|1Star\_Name
	\begin{itemize}
	\item HPnum : (unsigned int) Hipparcos catalog star number
	\item Star\_Name : (string) The name string without spaces. The '\_' will be replaced by space in the program.
	\end{itemize}
\end{description}

\item constellationsart.fab

\begin{description}
\item[desc :] Contains the constellation art info : i.e. for drawing of mythologic figures.
\item[type :] ascii file, fields separated by SPACE, end of line is CR ('\verb1\1n')
\item[line example :] \begin{verbatim}Lep lepus_m 104 57 24305 90 29 24845 33 42 27288\end{verbatim}
\item[line format :] ConstRef TextureFile x1 y1 HP1 x2 y2 HP2 x3 y3 HP3
	\begin{itemize}
	\item ConstRef : Short international name abreviation in 3 characters, first char in Capital letter
	\item TextureFile : Texture file name without the extension (no space character). The texture file has to be in the stellarium texture directory.
	\item x1 y1 hp1 (respectively 2 and 3) : the x and y position of the matching star
	  with hipparcos number hp1 (respectively 2 and 3) on the texture image. The
	  values are in pixels with the (0,0) in the upper left corner.
	\end{itemize}
\item[note :] the associated texture file must be in png format and have no alpha channel. The drawing background must be black.
\end{description}


\item constellationship.fab

\begin{description}
\item[desc :] Contains the constellations lines shape.
\item[type :] ascii file, fields separated by SPACE, end of line is CR ('\verb1\1n')
\item[line example :] \begin{verbatim}And ANDROMEDE ANDROMEDA 3  9640 5447 5447 4436 4436 3881\end{verbatim}
\item[line format :] ConstRef ConstCommonName ConstInternationnalName NumberOfSegments seg11 seg12 seg21 seg22 etc...
	\begin{itemize}
	\item ConstRef : Short international name abreviation in 3 characters, first char
	  in Capital letter
	\item ConstCommonName : Commonly used name (currently in french!)
	\item ConstInternationnalName : The latin internationnal name.
	\item NumberOfSegments : the number of segments in the shape.
	\item segx1 segx2 : the hipparcos number of the stars 1 and 2 joined to form the xth segment.
	\end{itemize}
\end{description}


\item courierfont.txt and spacefont.txt

\begin{description}
\item[desc :] contains the characters position on the font texture.
\item[type :] ascii file, fields separated by SPACE, end of line is CR ('\verb1\1n')
\item[first line example :] \begin{verbatim}CourierFont LineSize 21\end{verbatim}
	\begin{itemize}
	\item Font Name
	\item LineSize s : s is the maximum character height.
	\end{itemize}
\item[other lines example :] \begin{verbatim}065 02 2 14 21 0\end{verbatim}
\item[other lines format :] ascii\# x y w h s
	\begin{itemize}
	\item ascii\# : ascii number of the character
	\item x y : position of the upper left corner of the character in the font texture (in pixel).
	\item w h : width and height of the character on the texture
	\item s : space to add at the end of the char when displaying.
	\end{itemize}
\end{description}

\item messier.fab

\begin{description}
\item[desc :] Contains the nebula list (not only messier)
\item[type :] ascii file, fields separated by SPACE, end of line is CR ('\verb1\1n')
\item[line example :] \begin{verbatim}1952 RS 05 34.5 +22 +01 8.2 06.0 0 M1_-_Crab_Nebula m1\end{verbatim}
\item[line format :] NGCnumber NebulaType hh min.mm deg min.mm mag size texRotation Name TexName
	\begin{itemize}
	\item NGCnumber : NGC catalog number
	\item NebulaType : TODO and change..
	\item hh min.mm : Right ascention hour and minutes and tenth of minutes
	\item deg min.mm : Declinaison in degree min and tenth of minutes
	\item mag : magnitude
	\item size : angular size in arcminute
	\item Name : Nebula name with '\_' replaced by spaces.
	\item TexName : texture file name. png file without alpha chanel.
	\end{itemize}
\end{description}

\item name.txt
\begin{description}
\item[desc :] More info about stars, not used anymore.
\end{description}


\item ssystem.ini

\begin{description}
\item[desc :] Solar system bodies informations.
\item[type :] ini file. One section per body.
\item[Section example :]
\begin{verbatim}

[io]                    // Section name, has to be unique
name = Io               // Body name
parent = Jupiter        // Body parent
radius = 1821.          // Radius in km
halo = true             // Do we have to draw a small halo like a star?
color = 1.,1.,1.        // Halo color
tex_map = io            // Texture map file without extension (has to .png)
tex_halo = star16x16    // Halo texture file
lightning = true        // Compute shadow on it
albedo = 0.61           // Body albedo (how it reflects light) range 0 to 1
rot_rotation_offset = 220.8   // For texture alignment
rot_obliquity = 0.0           // Planet Obliquity (rotation axe inclination
                              // relative to the orbit plane)
coord_func = ell_orbit        // Define the coordinate computation funcion :
                              // can be a custom func or "ell_orbit"
orbit_Epoch = 2443000.00038375// Ell_orbit calculation parameter
orbit_Period = 1.769138       //       "    "
orbit_SemiMajorAxis = 421600  //       "    "
orbit_Eccentricity = 0.0041   //       "    "
orbit_Inclination = 0.040     //       "    "
orbit_AscendingNode = 312.981 //       "    "
orbit_LongOfPericenter = 97.73//       "    "
orbit_MeanLongitude = 106.724 //       "    "
\end{verbatim}
\end{description}


\item landscape.ini

\begin{description}
\item[desc :] Landscape skins descriptions.
\item[type :] ini file. One section per landscape.
\item[note :] There can be 2 landscape types, the ones made from a fisheye picture and the ones made from many smaller textures. The fisheye textures must be centered on the zenith, north on the bottom.
\item[Section example for a fisheye :]
\begin{verbatim}

[palm]                              // Section name
name = Palm                         // Landscape name
type = fisheye                      // Type = fisheye
maptex = landscapes/horizonalpha512 // Fisheye texture file name
texturefov = 210                    // Field of View covered by the texture
                                    // (180 = half dome, 360 = full sphere)
author = Grard_Dupontd             // Author name
\end{verbatim}
\end{description}

\end{itemize}

\end{document}