Prerequisites (verified on Kubuntu 18.04.3):
- Build kstars from source according to https://indilib.org/forum/general/210-howto-building-latest-libindi-ekos.html
- Install Android SDK
- Download and install NDK version android-ndk-r17c.
- Install JDK java-8-openjdk-amd64:
    sudo apt-get install openjdk-8-jdk
- Install Qt open source for Android (newest version 5.13.1) under your home directory to be writable.
- After installation of Qt, enter the correct paths to the NDK, JDK and SDK in Tools>Options>Devices>Android and make sure Qt shows no warnings regarding these paths.
- Qt does not work with the newest SDK Tools, you must use v25 as suggested here:
  https://stackoverflow.com/questions/42754878/qt-creator-wont-list-any-available-android-build-sdks/42811774#42811774

  Basically, download https://dl.google.com/android/repository/tools_r25.2.5-linux.zip and replace the ANDROID_SDK_DIR/tools directory,
  or just use the Android SDK download tool to use this version.
- Some tools are needed for the compilation: sudo apt-get install dos2unix ccache subversion ant libconfig-yaml-perl

Edit /etc/environment and add the following environmental variables before building:
    PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:$ANT_HOME/bin"
    JAVA_HOME="/usr/lib/jvm/java-8-openjdk-amd64"
    QT_ANDROID="/$HOME/Qt/5.13.1/android_armv7"
    CMAKE_ANDROID_NDK="/$HOME/Android/Sdk/ndk/android-ndk-r17c"
    ANDROID_NDK="/$HOME/Android/Sdk/ndk/android-ndk-r17c"
    ANDROID_SDK_ROOT="/$HOME/Android/Sdk"
    ANDROID_API_LEVEL=17
    ANDROID_PLATFORM=17
    KSTARS_ROOT="/$HOME/Projects/kstars"
    ANT_HOME="/usr/share/ant"

If you want to generate signed release package set the following variables:
    export ANDROID_KEYSTORE=your_keystore_file
    export ANDROID_KEYSTORE_ALIAS=your_keystore_alias
    export KSTARS_ROOT=KStars Path (e.g. /$HOME/Projects/kstars)

Configure git (if you haven't done this already):
    git config --global user.email "you@example.com"
    git config --global user.name "Your Name"

Make a build directory in a separate location form source (e.g. /$HOME/Projects/build/kstars-android):
    - Run build_kf5.sh and verify that the script builds everything without any problem.
    NOTE: Ki18n often fails to build the first time, but it should succeeds when you rebuild kf5 again.

    $KSTARS_ROOT/packaging/android/build_kf5.sh

Configure out-of-source build (MinSizeRel build type is recommended for Android):
    cmake -B. -H$KSTARS_ROOT -DBUILD_KSTARS_LITE=ON -DCMAKE_TOOLCHAIN_FILE=$CMAKE_ANDROID_NDK/build/cmake/android.toolchain.cmake \
      -DEIGEN3_INCLUDE_DIR=/usr/include/eigen3/ -DCMAKE_INSTALL_PREFIX=$(pwd)/android/export -DCMAKE_BUILD_TYPE=MinSizeRel \
      -DECM_DIR=/usr/share/ECM/cmake/ -DCMAKE_PREFIX_PATH=$QT_ANDROID \
      -DCMAKE_AR=${ANDROID_NDK}/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar

Compile:
    make -j4

Download and convert the translations:
    make convert_translations_to_android

Install:
    make -j4 install

Generate the Android debug package:
    make create-apk-debug-kstars

Install the Android debug package to your phone:
    make install-apk-debug-kstars

Generate the Android release package:
    make create-apk-release-kstars

To sign a release package:
    make sign-apk-kstars

KStars Customization Guide.
copyright 2002 by Jason Harris and the KStars team
This document is licensed under the terms of the GNU Free
Documentation License
---------------------------

This document provides a brief overview of the many advanced customization
features provided in the program.  If you have a useful customization that
you would like to share with the KStars community, please consider
submitting it to kstars@30doradus.org; we may incorporate your data into
a future version of KStars!


1. Color Schemes

In the "Colors" tab of the KStars Configuration window, the colors of
all items drawn in the sky map can be customized.  At any time,
you can save the current collection of colors into a custom color scheme.
Saved schemes will appear in the listbox on the right of the Colors
tab, as well as in the "Settings|Color Schemes" menu.  In addition,
the custom color schemes are automatically reloaded when KStars starts up,
so they will always be available.

You can remove a custom color scheme at any time by highlighting it in the
listbox and then pressing the "remove" button.


2. Geographic Locations

The Change Location window allows you to set the geographic location
by choosing from a list of over 2000 predefined cities around the world.
If you would like to use a location that is not on the list, enter the
relevant information (longitude, latitude, city name, province name, and
country name), then press "Add to list".  All fields must be filled, except
the optional province field.

In addition, you can also modify the values for an existing city, by
simply changing the values in the window, and adding it to the list.


3. Object Catalogs

You can easily add your own object data to KStars.  First, prepare the
object catalog data file.  Each line in the file should contain the
following space-separated fields:

for stars:
type(0 for stars), RA, Dec, mag, SpType, name(optional)

other types:
type(3-8), RA, Dec, mag (optional), flux(optional), name(optional)

The types are:
0: star
1: star (in object catalog...probably don't want to use this)
2: planet (don't use this in custom catalog)
3: open cluster
4: globular cluster
5: gaseous nebula
6: planetary nebula
7: supernova remnant
8: galaxy
18: radio source

The SpType is a short string for the spectral type.  For example, "B5" or "G2"
The coordinates should be given as floating-point values, in the J2000.0 epoch.
The name can be anything you wish.  If the name is more than one word, it
must be enclosed in quotation marks.

Once you have constructed a custom data file, open the Configuration window
to the Catalogs tab, and press the "Add Custom Catalog" button.  A popup
window appears in which you can specify a name for the catalog, and the
name of the file (including the path).

When you press Ok, KStars will attempt to read the lines of your data file.
It will report any problems, and if any lines at all were successfully parsed,
you are given a choice to accept the data file (ignoring any unparsed lines),
or to cancel the operation to attempt to resolve the problems first.

Once the data file has been accepted, your custom catalog will be loaded on
startup along with the standard catalogs, and there will be a checkbox in the
Configuration window to toggle the display of your catalog objects.

You can remove custom catalogs by highlighting its checkbox in the
Configuration window, and pressing the "Remove Custom Catalog" button (this
button is only active if a custom catalog is highlighted in the list
of checkboxes).

+ Radio Sources Catalogs:

For radio sources catalogs, you must include the flux frequency and units. For example:

# Flux Frequency: 1420 Mhz
# Flux Unit: mJy

The following is a simple catalog file:

# Name: my_catalog
# Prefix: et_radio
# Color: #00ff00
# Epoch: 2000
# Flux Frequency: 1420 Mhz
# Flux Unit: mJy
# ID  RA  Dc  Tp  Mj  Mn  PA  Nm  Flux
J0001 12:31:23.1 +11:29:34 18 180.60 360.30   45  my_radio_source   70

4. URL Links

You can add your own internet links to any object by selecting the
"Add Link..." item from the object's right-click popup menu.  A
window opens in which you can enter text to appear in the new menu item,
and the URL which should be opened.  You should also specify whether the
link points to an image or an HTML page (Image links open the Image Viewer,
HTML links open a Konqueror window).  The menu text is filled
with a default string at first; feel free to modify it.

Note that the URL can point to a file on your hard drive, so this is an
interesting way to catalog your own astrophotos, or perhaps to keep
observing notes about different objects...

KStars keeps track of thousands of comets and asteroids.
It uses orbital data published by NASA's Jet Propulsion
Laboratory (JPL); these data are known as "orbital elements".
Because these small bodies are easily perturbed as they
wander about the solar system, their orbital elements must
be updated regularly.  Updating the elements will also add
any recently-discovered bodies.


How to update the orbital elements of comets and asteroids:

-=( 1 )=-  The Easy Way.

Start KStars, then open the "Get New Stuff" Tool by selecting
"Download Data..." from the File menu, or by pressing Ctrl+D.

If a new "ephemerides" package is available, select it and press
the Install button.  Voila!

If the "ephemerides" package available from the "Get New Stuff"
Tool is too old, you can use the menu items under
"Settings" > "Updates" to download the last ephemerides from
NASA's Jet Propulsion Laboratory website.


-=( 2 )=-  Doing it Manually.

It is possible that the ephemerides package is not completely
up-to-date.  Fortunately, it's relatively simple to update the
files manually whenever you want.

::NOTE:: If you find that the ephemerides package is woefully
outdated, and you follow this manual-install procedure, PLEASE
send your final comets.dat and asteroids.dat files to
kstars-devel@kde.org!  Now is your chance to be a KStars Hero!


Step 1: The Comets

You can use the following command to download comets.dat file
from JPL website :
wget -O comets.dat --post-data="obj_group=all&obj_kind=com&obj_numbered=all&OBJ_field=0&OBJ_op=0&OBJ_value=&ORB_field=0&ORB_op=0&ORB_value=&combine_mode=AND&c1_group=OBJ&c1_item=Af&c1_op=!%3D&c1_value=D&c2_group=OBJ&c2_item=Ae&c2_op=!%3D&c2_value=SOHO&c_fields=AcBdBiBgBjBlBkBqBbAiAjAgAkAlApAqArAsBsBtCh&table_format=CSV&max_rows=10&format_option=full&query=Generate%20Table&.cgifields=format_option&.cgifields=field_list&.cgifields=obj_kind&.cgifields=obj_group&.cgifields=obj_numbered&.cgifields=combine_mode&.cgifields=ast_orbit_class&.cgifields=table_format&.cgifields=ORB_field_set&.cgifields=OBJ_field_set&.cgifields=preset_field_set&.cgifields=com_orbit_class" http://ssd.jpl.nasa.gov/sbdb_query.cgi

Delete or comment (with a '#') the first line.

Finally, copy your modified "comets.dat" to
~/.kde/share/apps/kstars/ (for a single-user install) or
$KDEDIR/share/apps/kstars/ (for a system-wide install).


Step 2: The Asteroids

You can use the following command to download asteroids.dat
file from JPL website :
wget -O asteroids.dat --post-data="obj_group=all&obj_kind=ast&obj_numbered=num&OBJ_field=0&ORB_field=0&c1_group=OBJ&c1_item=Ai&c1_op=%3C&c1_value=12&c_fields=AcBdBiBhBgBjBlBkBmBqBbAiAjAgAkAlApAqArAsBsBtCh&table_format=CSV&max_rows=10&format_option=full&query=Generate%20Table&.cgifields=format_option&.cgifields=field_list&.cgifields=obj_kind&.cgifields=obj_group&.cgifields=obj_numbered&.cgifields=combine_mode&.cgifields=ast_orbit_class&.cgifields=table_format&.cgifields=ORB_field_set&.cgifields=OBJ_field_set&.cgifields=preset_field_set&.cgifields=com_orbit_class" http://ssd.jpl.nasa.gov/sbdb_query.cgi

Delete or comment (with a '#') the first line.

Finally, copy your modified "asteroids.dat" to
~/.kde/share/apps/kstars/ (for a single-user install) or
$KDEDIR/share/apps/kstars/ (for a system-wide install).


-=( 3 )=-  Another way.

The last method is to point your browser to the following
URL:
http://ssd.jpl.nasa.gov/sbdb_query.cgi
and generate the file using the form

You must select the following columns to make the file
compatible with kstars :

- for comets
1 full name
2 modified julian day of orbital elements
3 perihelion distance
4 eccentricity of orbit
5 inclination angle of orbit in degrees
6 argument of perihelion in degrees
7 longitude of the ascending node
8 time of perihelion passage
9 orbit solution ID
10 absolute magnitude
11 slope parameter
12 Near-Earth Object (NEO) flag
13 comet total magnitude parameter
14 comet nuclear magnitude parameter
15 object diameter
16 object bi/tri-axial ellipsoid dimensions
17 geometric albedo
18 rotation period
19 orbital period
20 earth minimum orbit intersection distance
21 orbit classification

-for asteroids
1 full name
2 Modified Julian Day of orbital elements
3 perihelion distance
4 semi-major axis
5 eccentricity of orbit
6 inclination angle of orbit in degrees
7 argument of perihelion in degrees
8 longitude of the ascending node in degrees
9 mean anomaly
10 time of perihelion passage
11 orbit solution ID
12 absolute magnitude
13 slope parameter
14 Near-Earth Object (NEO) flag
15 comet total magnitude parameter
16 comet nuclear magnitude parameter
17 object diameter
18 object bi/tri-axial ellipsoid dimensions
19 geometric albedo
20 rotation period
21 orbital period
22 earth minimum orbit intersection distance
23 orbit classification

The advantage of this method is that you can play with
several filters and get a file containing exactly what
you want.

Don't forget to delete or comment (with a '#') the first
line.

Finally, copy your files to
~/.kde/share/apps/kstars/ (for a single-user install) or
$KDEDIR/share/apps/kstars/ (for a system-wide install).

README.i18n:  Instructions for Translating KStars
copyright 2002 by Jason Harris and the KStars team.
This document is licensed under the terms of the GNU Free Documentation License
-------------------------------------------------------------------------------


Some parts of i18n in KStars are a bit complicated, so we provide
this document to answer some questions you might have.

+ Strings in data files.

  KStars has many data files that contain strings that you may want
  to translate:  cities.dat, cnames.dat, image_url.dat, info_url.dat

  We have modified our Makefile to automatically parse these files
  and generate a "dummy" source file that only contains the translatable
  strings from our data files.  The file is called "kstars-i18n.cpp".
  Once the kstars.pot file is generated, this file is destroyed.

  The advantage to this is that it requires no special effort on the
  part of the translation teams; the data file strings are automatically
  added to our POT file.  The disadvantage is that our POT file is now
  quite large!  Especially because of the city names.  Probably, most of
  the city names won't need to be translated.  We added a comment to
  these strings indicating that they are optional.

  cnames.dat contains constellation names, in Latin.  We include
  an option in the program to display "Localized" names instead of
  Latin names; if you want this to work for your language, you'll
  need to provide translations for the strings in the POT file which
  have a comment like: "Constellation name (optional)".


+ Alternate internet URL lists

  KStars provides many internet links to images and information on
  specific objects in the sky.  The links appear in an object's
  right-click popup menu.  The POT file already provides the link
  text for translation, but there's still a problem:  the websites
  that the links go to are all in English!

  If you want to provide internet links that point to websites
  in your native language, you can.  Add a file to the SVN tree at:
  l10n-kde4/<lang>/data/kdeedu/kstars/info_url.dat (where <lang> is
  the two-letter code for your language).  This file should contain
  the list of internet links you want KStars to use when localized
  for your language.  You can look at the default info_url.dat to
  figure out the file format; briefly, it's a colon-delimited line
  with fields: object name, link text, link URL

  Note that your alternate info_url.dat file will completely replace
  the default, so if you want to include some links from the original,
  you will need to copy them over.  Some of the sites we link to provide
  versions of their pages in other languages (e.g., seds.org).  So
  for these sites, you can just modify the URLs from the default file.

  (you can also provide a localized version of image_url.dat, but this
  is probably unnecessary since these are only image links).

     Credits for Images used in KStars

     Jason Harris and the KStars team

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

KStars uses images in the skymap that are under copyright.
All of the images that ship with KStars are in the public
domain or have a permissive license.  Some images which are
available via the "Get New Stuff" tool are free for
non-commercial use only; these images are listed here as well.
When required, we have obtained permission from the image's
author.  For each image, we credit the author or source and
provide a link to their website, when available.

Key:
FFNP:     Free for non-profit/non-commercial use
FFE:      Free for educational use
FWC:      Free to use, with credit
UWP:      Used with Permission
PD:       Public Domain
CR:       Authorship Credit Requested
GPL:      Released under the General Public License

DSS:      Digitized Sky Survey
KPNO AOP: Kitt Peak Nat'l Observatory Advanced Observing Program
NOAO:     National Optical Astronomical Observatories
AURA:     Association of Universities for Research in Astronomy
NSF:      National Science Foundation
ESO/VLT:  European Southern Observatory / Very Large Telescope
ING:      Isaac Newton Group of Telescopes (La Palma)
2MASS:    2-Micron All-Sky Survey
NASA/GSFC:Nat'l Aeronautics and Space Admin./Goddard Spaceflight Center


Messier Catalog Inline Image Credits (these are not shipped
with KStars; they are available via the "Get New Stuff" tool):

M   1: Till Credner and Sven Kohle (FFNP)
M   2: Doug Williams, N. A.Sharp NOAO/AURA/NSF (FFE/FFNP)
M   3: KPNO AOP (FFNP)
M   4: DSS (FFE/FFNP)
M   5: KPNO AOP (FFNP)
M   6: N. A. Sharp, Mark Hanna, AURA/NOAO/NSF (FFE/FFNP)
M   7: no image
M   8: KPNO AOP (FFNP)
M   9: DSS (FFE/FFNP)
M  10: Till Credner and Sven Kohle (FFNP)
M  11: 2MASS (FWC)
M  12: KPNO AOP (FFNP)
M  13: KPNO AOP (FFNP)
M  14: DSS (FFE/FFNP)
M  15: KPNO AOP (FFNP)
M  16: KPNO AOP (FFNP)
M  17: KPNO AOP (FFNP)
M  18: no image
M  19: DSS (FFE/FFNP)
M  20: KPNO AOP (FFNP)
M  21: no image
M  22: N. A. Sharp NOAO/AURA/NSF (FFE/FFNP)
M  23: no image
M  24: no image
M  25: no image
M  26: no image
M  27: ESO/VLT (FFE/FFNP)
M  28: 2MASS (FWC)
M  29: no image
M  30: N. A. Sharp NOAO/AURA/NSF (FFE/FFNP)
M  31: Jason Ware (UWP)
M  32: DSS (FFE/FFNP)
M  33: Brad Wallis and Robert Provin (FFNP)
M  34: no image
M  35: no image
M  36: no image
M  37: no image
M  38: no image
M  39: no image
M  40: no image
M  41: no image
M  42: Brad Wallis and Robert Provin
M  43: no image
M  44: no image
M  45: Dean Jacobson (UWP)
M  46: no image
M  47: no image
M  48: no image
M  49: DSS (FFE/FFNP)
M  50: Till Credner and Sven Kohle (FFNP)
M  51: ING (FFNP)
M  52: no image
M  53: DSS (FFE/FFNP)
M  54: DSS (FFE/FFNP)
M  55: DSS (FFE/FFNP)
M  56: DSS (FFE/FFNP)
M  57: HST image (FWC)
M  58: KPNO AOP (FFNP)
M  59: N.A.Sharp AURA/NOAO/NSF (FFE/FFNP)
M  60: DSS (FFE/FFNP)
M  61: KPNO AOP (FFNP)
M  62: 2MASS (FWC)
M  63: KPNO AOP (FFNP)
M  64: KPNO AOP (FFNP)
M  65: KPNO AOP (FFNP)
M  66: KPNO AOP (FFNP)
M  67: Jan Wisniewski (FFNP)
M  68: DSS (FFE/FFNP)
M  69: DSS (FFE/FFNP)
M  70: DSS (FFE/FFNP)
M  71: Till Credner and Sven Kohle (FFNP)
M  72: DSS (FFE/FFNP)
M  73: DSS (FFE/FFNP)
M  74: DSS (FFE/FFNP)
M  75: DSS (FFE/FFNP)
M  76: Scott J. Wolk and Nancy R. Adams (FFE/FFNP)
M  77: KPNO AOP (FFNP)
M  78: KPNO AOP (FFNP)
M  79: DSS (FFE/FFNP)
M  80: DSS (FFE/FFNP)
M  81: N.A.Sharp AURA/NOAO/NSF (FFE/FFNP)
M  82: KPNO AOP (FFNP)
M  83: ESO/VLT (FWC)
M  84: Grasslands Observatory (UWP)
M  85: N. A. Sharp AURA/NOAO/NSF (FFE/FFNP)
M  86: Grasslands Observatory (UWP)
M  87: KPNO AOP (FFNP)
M  88: N. A. Sharp AURA/NOAO/NSF (FFE/FFNP)
M  89: N. A. Sharp AURA/NOAO/NSF (FFE/FFNP)
M  90: KPNO AOP (FFNP)
M  91: KPNO AOP (FFNP)
M  92: DSS (FFE/FFNP)
M  93: N. A. Sharp AURA/NOAO/NSF (FFE/FFNP)
M  94: KPNO AOP (FFNP)
M  95: KPNO AOP (FFNP)
M  96: KPNO AOP (FFNP)
M  97: KPNO AOP (FFNP)
M  98: N. A. Sharp AURA/NOAO/NSF (FFE/FFNP)
M  99: KPNO AOP (FFNP)
M 100: KPNO AOP (FFNP)
M 101: N.A. Sharp AURA/NOAO/NSF
M 102: no image
M 103: Hillary Mathis, N. A. Sharp AURA/NOAO/NSF (FFE/FFNP)
M 104: ESO/VLT (FWC)
M 105: N. A. Sharp AURA/NOAO/NSF (FFE/FFNP)
M 106: KPNO AOP (FFNP)
M 107: DSS (FFE/FFNP)
M 108: KPNO AOP (FFNP)
M 109: KPNO AOP (FFNP)
M 110: N. A. Sharp AURA/NOAO/NSF (FFE/FFNP)


Planets Inline Image Credits:
Mercury:  NASA/GSFC (PD/CR)
Venus:    NASA/GSFC (PD/CR)
Moon:     based on a photo contributed by Frank Stefani (GPL)
Mars:     NASA and Hubble Heritage team (PD/CR)
Jupiter:  NASA/GSFC (PD/CR)
Saturn:   NASA and Hubble Heritage team (PD/CR)
Uranus:   Erich Karkoschka (University of Arizona) and NASA (PD/CR)
Neptune:  NASA Voyager 2 (PD/CR)
Pluto:    NASA/GSFC (PD/CR)


Credits and permissions, listed by author/source:


Individual Authors:

Till Credner and Sven Kohle: http://www.allthesky.com
Images copyright Till Credner and Sven Kohle.  They may be used for
private and non-profit educational purposes.

Martin Germano: http://home.earthlink.net/~mcgermano/
Images copyright Martin Germano.  Used with permission.

Dean Jacobson: http://www.astrophoto.net
Images copyright Dean Jacobson.  Used with permission.

Brad Wallis and Robert Provin:
http://voltaire.csun.edu/wallis_provin.html
Images copyright Brad Wallis and Robert Provin.  They may be used
for non-profit purposes, as long as proper credit is given.

Jason Ware: http://www.galaxyphoto.com
Images copyright Jason Ware.  Used with permission.

Jan Wisniewski: http://jwisn.freeyellow.com/list.htm
Images copyright Jan Wisniewski.  They may be used
for non-commercial purposes, as long as proper credit is given.

Scott J. Wolk and Nancy R. Adams:
http://hea-www.harvard.edu/~swolk/pretty.html
Image copyright Scott J. Wolk and Nancy R. Adams.  They may be used
for non-commercial purposes, as long as proper credit is given.


Organizations:

DSS: http://archive.stsci.edu/dss/index.html
The Digitized Sky Survey is in the public domain.  The DSS
was produced at the Space Telescope Science Institute under U.S.
Government grant NAG W-2166. The images of these surveys are based
on photographic data obtained using the Oschin Schmidt Telescope on
Palomar Mountain and the UK Schmidt Telescope. The plates were
processed into the present compressed digital form with the
permission of these institutions.

KPNO AOP: http://www.noao.edu/outreach/aop/
The Advanced Observing Program at Kitt Peak National Observatory
is a public program in which participants use the high-tech
resources of the Kitt Peak Visitor Center Observatory to create
their own film or digital images of objects in the night sky.  All
images are freely available for non-commercial use in electronic
form, but may not be printed on paper without written permission.

ESO/VLT: http://www.eso.org/outreach/gallery/astro/
Images taken using the European Southern Observatory's
Very Large Telescope in Chile.  Images published in the ESO
Image Gallery may be reproduced for non-commercial purposes.

HST Public Pictures: http://oposite.stsci.edu/pubinfo/pictures.html
HST Image Gallery:   http://hubble.stsci.edu/gallery/
Hubble Heritage Project: http://heritage.stsci.edu/
Images published by the Space Telescope Science Institute are
in the public domain.

Grasslands Observatory: http://www.3towers.com/index.htm
Owned by Tim Hunter, who operates the observatory with
James McGaha.  Images of the entire Messier catalog as well as many
NGC objects are published on their website.  Images in KStars are
used with permission.

Isaac Newton Group of Telescopes Gallery:
http://www.ing.iac.es/PR/science/pictures.html
Images courtesy of the Isaac Newton Group of Telescopes, La Palma.

NOAO/AURA/NSF Image Gallery:
http://www.noao.edu/image_gallery/
NOAO allows reproduction, authorship of derivative works, and other
transformations of the original work strictly for educational and
research purposes without further permission.

2MASS Messier objects:
http://www.ipac.caltech.edu/2mass/gallery/messiercat.html
Images obtained as part of the Two Micron All Sky Survey (2MASS),
a joint project of the University of Massachusetts and the Infrared
Processing and Analysis Center/California Institute of Technology,
funded by the National Aeronautics and Space Administration and the
National Science Foundation.

Stellarium:
http://bazaar.launchpad.net/~stellarium/stellarium/trunk/files/head:/skycultures/western/
Western Skyculture images obtained from Stellarium as a part of
the Constellation Art project in Google Summer of Code 2015.

# A Desktop Planetarium for KDE

KStars is free, open source, cross-platform Astronomy Software.

It provides an accurate graphical simulation of the night sky, from any location on Earth, at any date and time. The display includes up to 100 million stars, 13,000 deep-sky objects,all 8 planets, the Sun and Moon, and thousands of comets, asteroids, supernovae, and satellites.

For students and teachers, it supports adjustable simulation speeds in order to view phenomena that happen over long timescales, the KStars Astrocalculator to predict conjunctions, and many common astronomical calculations. For the amateur astronomer, it provides an observation planner, a sky calendar tool, and an FOV editor to calculate field of view of equipment and display them. Find out interesting objects in the "What's up Tonight" tool, plot altitude vs. time graphs for any object, print high-quality sky charts, and gain access to lots of information and resources to help you explore the universe!

Included with KStars is Ekos astrophotography suite, a complete astrophotography solution that can control all INDI devices including numerous telescopes, CCDs, DSLRs, focusers, filters, and a lot more. Ekos supports highly accurate tracking using online and offline astrometry solver, autofocus and autoguiding capabilities, and capture of single or multiple images using the powerful built in sequence manager.

## Copyright

Copyright (c) 2001 - 2020 by The KStars Team:

KStars is Free Software, released under the GNU Public License. See COPYING for GPL license information.

## Downloads

KStars is available for Windows, MacOS, and Linux. You can download the latest version from [KStars official website](https://edu.kde.org/kstars).

On Linux, it is available for most Linux distributions.

Latest stable version is v3.4.2

## Important URLs and files.

* The [KStars homepage](https://edu.kde.org/kstars)
* KStars [Git Repository](https://invent.kde.org/education/kstars)
* KStars [Web Chat](https://webchat.kde.org/#/room/#kstars:kde.org)
* Forum [where KStars is often discussed](https://indilib.org/forum.html)

## KStars documentation

The KStars handbook can be found in your $(KDEDIR)/share/doc/HTML/<lang>/kstars/
directory.  You can also easily access it from the Help menu, or by pressing
the [F1] key, or by visiting https://docs.kde.org/?application=kstars
Unfortunately, it's a bit out-of-date. We welcome volunteers to help
update it.

In addition, there are the following README files:

README:             This file; general information
README.planetmath:  Explanation of algorithms used to compute planet positions
README.customize:   Advanced customization options
README.images:      Copyright information for images used in KStars.
README.i18n:        Instructions for translators

## Development

Code can be cloned, viewed and merge requests can be made via the [KStars repository](https://invent.kde.org/education/kstars). If you are new to remote git repositories, please see the Git Tips section below.
Note: Previously KStars used Phabricator for its merge requests. That system is no longer in use.

### Integrated Development Environment IDE

If you plan to develop KStars, it is highly recommended to utilize an IDE. You can use any IDE of your choice, but QtCreator(https://www.qt.io/product) or KDevelop(https://www.kdevelop.org) are recommended as they are more suited for Qt/KDE development.

To open KStars in QtCreator, select the CMakeLists.txt file in the KStars source folder and then configure the build location and type.

### Building

1. Prerequisite Packages

To build and develop KStars, several packages may be required from your distribution. Here's a list.

* Required dependencies
    * GNU Make, GCC -- Essential tools for building
    * cmake -- buildsystem used by KDE
    * Qt Library > 5.9.0
    * Several KDE Frameworks: KConfig, KDocTools, KGuiAddons, KWidgetsAddons, KNewStuff, KI18n, KInit, KIO, KXmlGui, KPlotting, KIconThemes
    * eigen -- linear algebra library
    * zlib -- compression library
    * StellarSolver -- see [https://github.com/rlancaste/stellarsolver](https://github.com/rlancaste/stellarsolver)

* Optional dependencies
    * libcfitsio -- FITS library
    * libindi -- Instrument Neutral Distributed Interface, for controlling equipment.
    * xplanet
    * astrometry.net
    * libraw
    * wcslib
    * libgsl
    * qtkeychain


2. Installing Prerequisites

Debian/Ubuntu

The apt-add-respository command is needed for the apt-get's libstellarsolver-dev. Alternatively, you can skip the apt-add-repository, remove the libstellarsolver-dev from the apt-get, and build & install stellarsolver from https://github.com/rlancaste/stellarsolver.
```
sudo apt-add-repository ppa:mutlaqja/ppa
sudo apt-get -y install build-essential cmake git libstellarsolver-dev libeigen3-dev libcfitsio-dev zlib1g-dev libindi-dev extra-cmake-modules libkf5plotting-dev libqt5svg5-dev libkf5xmlgui-dev libkf5kio-dev kinit-dev libkf5newstuff-dev kdoctools-dev libkf5notifications-dev qtdeclarative5-dev libkf5crash-dev gettext libnova-dev libgsl-dev libraw-dev libkf5notifyconfig-dev wcslib-dev libqt5websockets5-dev xplanet xplanet-images qt5keychain-dev libsecret-1-dev breeze-icon-theme
```

Fedora
```
yum install cfitsio-devel eigen3-devel stellarsolver-devel cmake extra-cmake-modules.noarch kf5-kconfig-devel kf5-kdbusaddons-devel kf5-kdoctools-devel kf5-kguiaddons-devel kf5-ki18n-devel kf5-kiconthemes-devel kf5-kinit-devel kf5-kio-devel kf5-kjobwidgets-devel kf5-knewstuff-devel kf5-kplotting-devel kf5-ktexteditor-devel kf5-kwidgetsaddons-devel kf5-kwindowsystem-devel kf5-kxmlgui-devel libindi-devel libindi-static qt5-qtdeclarative-devel qt5-qtmultimedia-devel qt5-qtsvg-devel wcslib-devel xplanet zlib-devel
```

3. Compiling

Open a console and run in the following commands:
```
mkdir -p ~/Projects
git clone https://invent.kde.org/education/kstars.git
mkdir -p kstars-build
cd kstars-build
cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=RelWithDebInfo ../kstars
make -j8
sudo make install
```

To run KStars, simply type **kstars** in the terminal.

### Code Style

KStars uses [Artistic Style](http://astyle.sourceforge.net) to format all the C++ source files. Please make sure to apply the following astyle rules to any code that is submitted to INDI. On Linux, you can create ***~/.astylerc*** file containing the following rules:
```
--style=allman
--align-reference=name
--indent-switches
--indent-modifiers
--indent-classes
--pad-oper
--indent-col1-comments
--lineend=linux
--max-code-length=124
```
Some IDEs (e.g. QtCreator) support automatic formatting for the code every time you save the file to disk.

### Making Updates to the Handbook

On linux run the following to install the necessary programs:

```
sudo apt-get install docbook docbook-utils
```

The source for the handbook is in kstars/doc.
You can edit those files, include them in commits and MRs like you would c++ files (see below).
You could figure out the markup by example, or learn from [online doc for docbook](https://opensource.com/article/17/9/docbook).
In general, it is best to first copy the entire kstars/doc directory to a temporary directory, and edit and generate the handbook there,
because if you ran meinproc in the main source directory, you would generate many .html files there,
and you don't want to commit the generated files to your git repository.

```
cp -pr kstars/doc ~/DOCBOOK
cd ~/DOCBOOK
meinproc5 index.docbook
```

The above should generate html files. Then, in a browser, you can simply open DOCBOOK/index.html and navigate your way to the part you want, e.g. just type something similar to this in the url bar of chrome: file:///home/YOUR_USER_NAME/DOCBOOK/doc/tool-ekos.html
Make changes to some of the .docbook files in ~/DOCBOOK/*.docbook. Regenerate the html files, and view your changes in the browser, as before. Iterate.

To check syntax, you might want to run:

```
checkXML5 index.docbook
```

Once you're happy, copy your modified files back to kstars/doc, and treat the edited/new files as usual with git,
including your modified files in a new commit and eventually a new merge request.

### Merge Request Descriptions

See the section below, Git Tips, on technical specifics of how to generate a Merge Request.
In the process of making the request, you will need to describe the request.
Please use a format similar to [this one](https://invent.kde.org/education/kstars/-/merge_requests/33)
which has sections for a summary of what was done, what was modified in each file, other relevant notes, and how to test your changes.

### Git Tips

You must be familiar with git to make changes to KStars, and this is not the place for such a tutorial. There
are many excellent resources for that on the web. The paragraph below, though, will give an overview of one way
to make a Merge Request, given you already have sufficient git experience to clone KStars, make a local branch,
modify the code as you like, commit your changes to your local branch, and test your code thoroughly.

Here's one good resource for a [fork-branch-git-workflow to make KStars changes](https://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow). The steps below are inspired by that page.

**One-time KStars git environment setup.**

* [Make your KDE identity](https://community.kde.org/Infrastructure/Get_a_Developer_Account)
* **Login.** Go to the [KStars gitlab page](https://invent.kde.org/education/kstars) and login in the upper right corner.
* **Fork the project.** Then, still on the KStars gitlab page, Click FORK in the upper right hand corner, to create your own fork of the project.
* **Copy your URL.** Note the url of your fork. It should be https://invent.kde.org/YOUR_KDE_NAME/kstars
* **Clone KStars.** Back on your computer run these commands
    * mkdir -p ~/Projects
    * cd ~/Projects
    * git clone https://invent.kde.org/YOUR_KDE_NAME/kstars
    * cd kstars
* **Add your upstream.** Add the KStars main repo to your forked repo.
    * git remote add upstream https://invent.kde.org/education/kstars

You are set up now.

**Steps used for each change.** After the one-time setup (above), the steps below could be used for each new feature submission. In summary, you will make a feature branch in your local repository, make your desired changes there and test, push them to your fork, create a request to merge your fork with the main KStars repo, wait for feedback, and possibly iterate on your changes hoping for approval from an authority.

* **Create your feature branch.**
    * git checkout -b YOUR_BRANCH_NAME
* **Make your changes**
* **Commit your changes**
    * git commit -a
* **Push changes to your forked repo.**
    * git push origin YOUR_BRANCH_NAME
* **Create a Merge Request**
    * Use your browser to visit your forked repo at  https://invent.kde.org/YOUR_KDE_NAME/kstars
    * You should see an option to create a Merge Request for YOUR_BRANCH_NAME. Fill in the details (see the above section).
    * You should be able to see a new URL dedicated to that Merge Request.
* **Make Some Changes.** You may get requests to modify some of your code.
    * If so, you simply go back to your local branch, make and test your changes.
    * Commit your changes as above, inside your branch, with: git commit -a
    * Push your branch's changes to your forked repo as above with: git push origin YOUR_BRANCH_NAME
    * Your changes should automatically be added to your Merge Request. Check the Merge Request's page to be sure.
    * You may need to rebase your code--see below for details.

**Rebasing your changes.** Others may be making changes to KStars at the same time you are working on your feature.
Rebasing is updating your version of KStars and your particular changes to make it as if you changed the latest KStars version,
e.g. reflect changes to the codebase made after you cloned or updated your own KStars copy. This is a significant topic
you can Google, but the following instructions work most of the time.

Note that this is done before you create your merge request, when you are the only one seeing your code changes.
Once you have started your merge request, your code is "public" and instead of rebasing, you should follow the merge procedure below.

```
cd ~/Projects/kstars
git checkout master
git pull upstream master  # Get the master from the main KStars repo onto your local clone
git push origin master    # Then push your updated local clone into your forked repo
git checkout YOUR_BRANCH_NAME
git rebase master
git push origin YOUR_BRANCH_NAME -f
```

If there are complications with the rebase, git will make suggestions on how to correct the issues.

**Merging others' changes.** Once you submit a merge request, your code can be seen (and edited) by
others. At this point, though you still may need to update to the latest KStars version, rebasing destroys
change information and can overwrite what others are doing. Instead it is best to 'merge' in the current
version of KStars into your code.

```
cd ~/Projects/kstars
git checkout master
git pull upstream master  # Get the master from the main KStars repo onto your local clone
git push origin master    # Then push your updated local clone into your forked repo
git checkout YOUR_BRANCH_NAME
git merge master
git push origin YOUR_BRANCH_NAME
```

The differences from the rebase section are the last 2 commands: 'git merge master' is used instead of 'git rebase master'.
Also the 'git push' doesn't use the -f option. The first time you run the 'git push',
you may be asked by git to add 'set-upstream origin' to the command. In that case, follow those instructions.

If you follow this procedure, you will find a new 'merge commit' added to your branch's git log.


**Your next change**. Once your Merge Request is complete (and possibly integrated into KStars), you may wish to move on and develop again.
The next change will use another (new) feature branch, and the first feature branch could be deleted.
You may want to run the following regularly to keep your master branch up-to-date with KStars.
```
cd ~/Projects/kstars
git checkout master
git pull upstream master  # Get the master from the main KStars repo onto your local clone
git push origin master    # Then push your updated local clone into your forked repo
```

## Writing Tests
Tests are stored in the `Tests` folder and use QTest as support framework:
* Unitary tests can be found in `auxiliary`, `capture`, `fitsviewer`, etc. They try to verify the behavior
  of a minimal set of classes, and are support for feature development.
* UI tests can be found in `kstars_lite_ui` and `kstars_ui`. They execute use cases as the end-user would do from the user
  interface, and focus on availability of visual feedback and stability of procedures.

### Writing Unitary Tests
1. Decide where your new unitary test will reside in `Tests`.
KStars classes should live in a folder matching their origin: for instance, auxiliary class tests live in `auxiliary`.
Find a suitable place for your test, based on the part of the system that is being tested.
As an example, a folder named `thatkstarscategory`.

2. Create a new unitary test class, or copy-paste an existing unitary test to a new one.
Check `Tests/kstars_ui_tests/kstars_ui_tests.h` as an example.
Name the `.h` and `.cpp` files as "test[lowercase kstars class]" (for instance "testthatkstarsclass"), and update them to match the following:
```
/* [Author+Licence header] */
#ifndef TESTTHATKSTARSCLASS_H
#define TESTTHATKSTARSCLASS_H

#include <QtTest>
#include <QObject>

class TestThatKStarsClass: public QObject
{
    Q_OBJECT
public:
    explicit TestThatKStarsClass(QObject *parent = null);

private slots:
    void initTestCase();                    // Will trigger once at beginning
    void cleanupTestCase();                 // Will trigger once at end

    void init();                            // Will trigger before each test
    void cleanup();                         // Will trigger after each test

    void testThisParticularFunction_data(); // Data fixtures for the test function (Qt 5.9+)
    void testThisParticularFunction();      // Test function
}
#endif // TESTTHATKSTARSCLASS_H
```
```
/* [Author+Licence header] */
#include "testthatkstarsclass.h"
TestThatKStarsClass::TestThatKStarsClass(QObject* parent): QObject(parent) {}
TestThatKStarsClass::initTestCase() {}
TestThatKStarsClass::cleanupTestCase() {}
TestThatKStarsClass::init() {}
TestThatKStarsClass::cleanup() {}

TestThatKStarsClass::testThisParticularFunction_data()
{
    // If needed, add data fixtures with QTest::AddColumn/QTest::AddRow, each will trigger testThisParticularFunction
}

TestThatKStarsClass::testThisParticularFunction()
{
    // Write your tests here, eventually using QFETCH to retrieve the current data fixture
}

QTEST_GUILESS_MAIN(TestThatKStarsClass);
```
You can use a single file to hold both declaration and definition, but you will need to `#include "testthatkstarsclass.moc"` between the declaration and the definition.

3. Update the CMake configuration to add your test.
If you created a new folder, create a new `CMakeLists.txt` to add your test:
```
ADD_EXECUTABLE( testthatkstarsclass testthatkstarsclass.cpp )
TARGET_LINK_LIBRARIES( testthatkstarsclass ${TEST_LIBRARIES})
ADD_TEST( NAME ThatKStarsClassTest COMMAND testthatkstarsclass )
```
Have the `CMakeLists.txt` residing one folder higher in the filesystem include that `CMakeLists.txt` by adding:
```
include_directories(
    ...
    ${kstars_SOURCE_DIR}/kstars/path/to/the/folder/of/the/kstars/class/you/are/testing
)
...
add_subdirectory(thatkstarscategory)
```
Make sure you add your `add_subdirectory` in the right dependency group. Ekos tests require `INDI_FOUND` for instance.

4. Write your tests
Make sure you document behavior with your tests. If you happen to find a bug, don't fix it, mark it with an `QEXPECT_FAIL` macro.
The test will document the incorrect behavior while the bug is alive, and will fail when the bug is fixed. Then only after that the test may be updated.
Also pay attention to Qt library version support. For instance, data fixtures require Qt 5.9+.

### Writing User Interface Tests

Follow the same steps as for unitary tests, but locate your test classes in `kstars_ui_tests`.

One important thing about UI tests is that they must all use `QStandardPaths::setTestModeEnabled(true)`, so that they execute with a separate user
configuration that is initially blank. User interface tests thus require a preliminary setup to function properly, such as using the new configuration
wizard or setting the geographical location up. For this reason, you need to add the execution of your test in `Tests/kstars_ui_tests/kstars_ui_tests.cpp`,
in `main()`, **after** the execution of `TestKStarsStartup`.

A second important thing about QTest generally is that test functions have no return code. One therefore needs to write macros to factor duplicated code.
You will find many existing macros in the header files of `kstars_ui_tests` test classes, to retrieve gadgets, to click buttons or to fill `QComboBox` widgets...

A third important thing about the KStars interface is that it mixes KDE and Qt UI elements. Thus, sometimes tests require verification code to be moved
to a `QTimer::singleShot` call, and sometimes even clicking on a button has to be made asynchronous for the test to remain in control (modal dialogs).
Fortunately, these hacks do not alter the execution of the tested code.

When testing, you need to make sure you always use elements that the end-user is able to use. Of course, if a test requires a setup that is not actually part of the
interesting calls, you may hack a direct call. For instance, some Ekos tests requiring the Telescope Simulator to be pointing at a specific location use
`QVERIFY(Ekos::Manager::Instance()->mountModule()->sync(ra,dec))`. Remember that sometimes you need to leave time for asynchronous signals to be emitted and caught.

## Credits
### The KStars Team
#### Original Author
Jason Harris <kstars@30doradus.org>
#### Current Maintainer
Jasem Mutlaq <mutlaqja@ikarustech.com>
#### Contributors (Alphabetical)
* Akarsh Simha <akarsh.simha@kdemail.net>
* Alexey Khudyakov <alexey.skladnoy@gmail.com>
* Artem Fedoskin <afedoskin3@gmail.com>
* Carsten Niehaus <cniehaus@kde.org>
* Chris Rowland <chris.rowland@cherryfield.me.uk>
* Csaba Kertesz <csaba.kertesz@gmail.com>
* Eric Dejouhanet <eric.dejouhanet@gmail.com>
* Harry de Valence <hdevalence@gmail.com>
* Heiko Evermann <heiko@evermann.de>
* Hy Murveit <murveit@gmail.com>
* James Bowlin <bowlin@mindspring.com>
* Jérôme Sonrier <jsid@emor3j.fr.eu.org>
* Mark Hollomon <mhh@mindspring.com>
* Martin Piskernig <martin.piskernig@stuwo.at>
* Médéric Boquien <mboquien@free.fr>
* Pablo de Vicente <pvicentea@wanadoo.es>
* Prakash Mohan <prakash.mohan@kdemail.net>
* Rafał Kułaga <rl.kulaga@gmail.com>
* Rishab Arora <ra.rishab@gmail.com>
* Robert Lancaster <rlancaste@gmail.com>
* Samikshan Bairagya <samikshan@gmail.com>
* Thomas Kabelmann <tk78@gmx.de>
* Valentin Boettcher <hiro@protagon.space>
* Victor Cărbune <victor.carbune@kdemail.net>
* Vincent Jagot <vincent.jagot@free.fr>
* Wolfgang Reissenberger <sterne-jaeger@t-online.de>
* Yuri Chornoivan <yurchor@ukr.net>

### Data Sources:

 Most of the catalog data came from the Astronomical Data Center, run by
 NASA.  The website is:
 http://adc.gsfc.nasa.gov/

 NGC/IC data is compiled by Christian Dersch from OpenNGC database.
 https://github.com/mattiaverga/OpenNGC (CC-BY-SA-4.0 license)

 Supernovae data is from the Open Supernova Catalog project at https://sne.space
 Please refer to the published paper here: http://adsabs.harvard.edu/abs/2016arXiv160501054G

 KStars links to the excellent image collections and HTML pages put together
 by the Students for the Exploration and Development of Space, at:
 http://www.seds.org

 KStars links to the online Digitized Sky Survey images, which you can
 query at:
 http://archive.stsci.edu/cgi-bin/dss_form

 KStars links to images from the HST Heritage project, and from HST
 press releases:
 http://heritage.stsci.edu
 http://oposite.stsci.edu/pubinfo/pr.html

 KStars links to images from the Advanced Observer Program at
 Kitt Peak National Observatory.  If you are interested in astrophotography,
 you might consider checking out their program:
 http://www.noao.edu/outreach/aop/

 Credits for each image used in the program are listed in README.images


# Original Acknowledgement from the Project Founder

 KStars is a labor of love.  It started as a personal hobby of mine, but
 very soon after I first posted the code on Sourceforge, it started to
 attract other developers.  I am just completely impressed and gratified
 by my co-developers.  I couldn't ask for a more talented, friendly crew.
 It goes without saying that KStars would be nowhere near what it is today
 without their efforts.  Together, we've made something we can all be
 proud of.

 We used (primarily) two books as a guide in writing the algorithms used
 in KStars:
 + "Practical Astronomy With Your Calculator" by Peter Duffett-Smith
 + "Astronomical Algorithms" by Jean Meeus

 Thanks to the developers of Qt and KDE whose peerless API made KStars
 possible.  Thanks also to the tireless efforts of the KDE translation
 teams, who bring KStars to a global audience.

 Thanks to everyone at the KDevelop message boards and on irc.kde.org,
 for answering my frequent questions.

 Thanks also to the many users who have submitted bug reports or other
 feedback.


You're still reading this? :)
Well, that's about it.  I hope you enjoy KStars!

Jason Harris
kstars@30doradus.org

KStars Development Mailing list
kstars-devel@kde.org

Send us ideas and feedback!

README.planetmath:  Understanding Planetary Positions in KStars.
copyright 2002 by Jason Harris and the KStars team.
This document is licensed under the terms of the GNU Free Documentation License
-------------------------------------------------------------------------------


0. Introduction: Why are the calculations so complicated?

We all learned in school that planets orbit the Sun on simple, beautiful
elliptical orbits.  It turns out this is only true to first order.  It
would be precisely true only if there was only one planet in the Solar System,
and if both the Planet and the Sun were perfect point masses.  In reality,
each planet's orbit is constantly perturbed by the gravity of the other planets
and moons.  Since the distances to these other bodies change in a complex way,
the orbital perturbations are also complex.  In fact, any time you have more
than two masses interacting through mutual gravitational attraction, it is
*not possible* to find a general analytic solution to their orbital motion.
The best you can do is come up with a numerical model that predicts the orbits
pretty well, but imperfectly.


1. The Theory, Briefly

We use the VSOP ("Variations Seculaires des Orbites Planetaires") theory of
planet positions, as outlined in "Astronomical Algorithms", by Jean Meeus.
The theory is essentially a Fourier-like expansion of the coordinates for
a planet as a function of time.  That is, for each planet, the Ecliptic
Longitude, Ecliptic Latitude, and Distance can each be approximated as a sum:

  Long/Lat/Dist = s(0) + s(1)*T + s(2)*T^2 + s(3)*T^3 + s(4)*T^4 + s(5)*T^5

where T is the number of Julian Centuries since J2000.  The s(N) parameters
are each themselves a sum:

  s(N) = SUM_i[ A(N)_i * Cos( B(N)_i + C(N)_i*T ) ]

Again, T is the Julian Centuries since J2000.  The A(N)_i, B(N)_i and C(N)_i
values are constants, and are unique for each planet.  An s(N) sum can
have hundreds of terms, but typically, higher N sums have fewer terms.
The A/B/C values are stored for each planet in the files
<planetname>.<L/B/R><N>.vsop.  For example, the terms for the s(3) sum
that describes the T^3 term for the Longitude of Mars are stored in
"mars.L3.vsop".

Pluto is a bit different.  In this case, the positional sums describe the
Cartesian X, Y, Z coordinates of Pluto (where the Sun is at X,Y,Z=0,0,0).
The structure of the sums is a bit different as well.  See KSPluto.cpp
(or Astronomical Algorithms) for details.

The Moon is also unique, but the general structure, where the coordinates
are described by a sum of several sinusoidal series expansions, remains
the same.


2. The Implementation.

The KSplanet class contains a static OrbitDataManager member.  The
OrbitDataManager provides for loading and storing the A/B/C constants
for each planet.  In KstarsData::slotInitialize(), we simply call
loadData() for each planet.  KSPlanet::loadData() calls
OrbitDataManager::loadData(QString n), where n is the name of the planet.

The A/B/C constants are stored hierarchically:
 + The A,B,C values for a single term in an s(N) sum are stored in an
   OrbitData object.
 + The list of OrbitData objects that compose a single s(N) sum is
   stored in a QVector (recall, this can have up to hundreds of elements).
 + The six s(N) sums (s(0) through s(5)) are collected as an array of
   these QVectors ( typedef QVector<OrbitData> OBArray[6] ).
 + The OBArrays for the Longitude, Latitude, and Distance are collected
   in a class called OrbitDataColl.  Thus, OrbitDataColl stores all the
   numbers needed to describe the position of any planet, given the
   Julian Day.
 + The OrbitDataColl objects for each planet are stored in a QDict object
   called OrbitDataManager.  Since OrbitDataManager is static, each planet can
   access this single storage location for their positional information.
   (A QDict is basically a QArray indexed by a string instead of an integer.
   In this case, the OrbitDataColl elements are indexed by the name of the
   planets.)

Tree view of this hierarchy:

OrbitDataManager[QDict]: Stores 9 OrbitDataColl objects, one per planet.
|
+--OrbitDataColl: Contains all three OBArrays (for
   Longitude/Latitude/Distance) for a single planet.
   |
   +--OBArray[array of 6 QVectors]: the collection of s(N) sums for
      the Latitude, Longitude, or Distance.
      |
      +--QVector: Each s(N) sum is a QVector of OrbitData objects
         |
         +--OrbitData: a single triplet of the constants A/B/C for
            one term in an s(N) sum.

To determine the instantaneous position of a planet, the planet calls its
findPosition() function.  This first calls calcEcliptic(double T), which
does the calculation outlined above: it computes the s(N) sums to determine
the Heliocentric Ecliptic Longitude, Ecliptic Latitude, and Distance to the
planet.  findPosition() then transforms from heliocentric to geocentric
coordinates, using a KSPlanet object passed as an argument representing the
Earth.  Then the ecliptic coordinates are transformed to equatorial
coordinates (RA,Dec).  Finally, the coordinates are corrected for the
effects of nutation, aberration, and figure-of-the-Earth.  Figure-of-the-Earth
just means correcting for the fact that the observer is not at the center of
the Earth, rather they are on some point on the Earth's surface, some 6000 km
from the center.  This results in a small parallactic displacement of the
planet's coordinates compared to its geocentric position.  In most cases,
the planets are far enough away that this correction is negligible; however,
it is particularly important for the Moon, which is only 385 Mm (i.e.,
385,000 km) away.

README.timekeeping:  Keeping time in KStars
copyright 2002 by Jason Harris and the KStars team.
This document is licensed under the terms of the GNU Free Documentation License
-------------------------------------------------------------------------------


1. The Basics

Timekeeping is handled by the SimClock class.  SimClock stores the
simulation time as the Julian Day, in a long double variable
("julian").  A long double is required to provide sub-second resolution
in the Julian Day value.  The date can be converted to a calendar date
(QDateTime object) with the UTC() function.  julian is updated every
0.1 sec by an internal QTimer, using the SimClock::tick() SLOT,
connected to the internal QTimer's timeout() SIGNAL.

We make a distinction between "system time" and "simulation time".
System time is real time, according to the computer's CPU clock.
Simulation time is the time according to KStars; since the time and
date are adjustable, system time and simulation time can have an
arbitrary offset.  Furthermore, SimClock has an adjustable Scale
parameter that determines how many seconds of simulation time pass for
each second of system time.  Scale can even be negative, indicating
that the simulation clock is running backwards.

The simplest way to advance the simulation time would be to add
(0.1*Scale) seconds to julian every time tick() is called.  However,
this is not accurate, because there is always some error associated
with the time it takes to execute tick(), and these errors would
accumulate during each cycle.  Instead, tick() measures the elapsed
time since some fixed system-time marker ("sysmark"), and adds
(elapsed_time*Scale) seconds to "julianmark", a fixed simulation-time
marker that was the exact simulation time at the moment the system-time
marker was set.  This is much more accurate, because any errors in
tick() do not accumulate.  Any time the clock is started, or its
scale changed, the sysmark and julianmark markers are reset (they are
also reset if they have not changed in more than 24 hours of real time).

tick() emits the timeAdvanced() signal, which is connected to
KStarsData::updateTime(), which takes care of updating object
coordinates and drawing the skymap (see below for details).

Note also that the SimClock class only handles the Julian Day and the
Universal Time, not the local time.  Time zone corrections and daylight
savings time are handled by KStarsData::updateTime().


2. Manual Mode

The above procedure works well, as long as tick() takes less than 0.1 sec,
on average (including the time taken by KStarsData::updateTime()).  In
practice, large values of Scale cause more calls to updateTime() than the
CPU is able to handle.  This results in some time steps being skipped
altogether, which makes the simulation seem jerky.

To compensate for this, we implemented a "Manual Mode" for SimClock.  In
Manual mode, the internal QTimer is stopped, so that tick() is not
triggered every 0.1 seconds.  Instead, a similar function (manualTick())
is called whenever KStarsData::updateTime() has finished.  manualTick()
adds Scale seconds to the simulation time.  So, the Scale parameter has
a slightly different meaning in Manual mode.  The simulation time
no longer runs at strictly Scale seconds per real-time second; rather,
every update of the simulation occurs exactly Scale simulation-seconds
after the previous update, no matter how long the update takes.

There are two bool variables in SimClock, ManualMode and ManualActive.
The first controls whether the clock is using Manual Mode (accessed by
isManualMode()); the second controls whether the clock is running in
Manual Mode (recall that the internal timer is halted when in Manual
Mode).  The function isActive() returns whether the clock is running,
for both the standard mode and Manual Mode.


3. KStarsData::updateTime()

updateTime() is a SLOT connected to the SimClock's timeAdvanced()
SIGNAL, which is emitted every tick() or manualTick().

KStarsData keeps its own representation of the universal time as a
QDateTime object (UTime); the first thing that updateTime() does is to
reset this with clock->UTC().  It then sets the local time QDateTime
object (LTime) by adding 3600*geo->TZ() seconds to UTime.  It then
checks if it has reached the next daylight savings time change point,
and adjusts the Time Zone offset, if necessary.

There is a group of time-dependent numbers such as the obliquity and
the sun's mean anomaly; these are kept in the KSNumbers class.  The next
thing updateTime() does is create a KSNumbers object appropriate for the
current julian day value [we may be able to save some time by keeping a
persistent KSNumbers object, and not updating it on every call to
updateTime(), as the values stored there don't change very quickly].

There are several things that don't need to be updated on every call to
updateTime().  To save time, we only update them if a certain amount of
time has passed since the last update.  For example, the LastNumUpdate
variable stores the julian day of the last time object coordinates were
updated for precession/nutation/aberration.  This needs to happen once
per simulation day, so whenever (CurrentDate-LastNumUpdate) exceeds 1.0,
it signals the update (by setting needNewCoords=true) and resets
LastNumUpdate to CurrentDate.  Similarly, we use LastPlanetUpdate to
update planet coordinates 100 times per day.  LastSkyUpdate monitors
the last time the horizontal coordinates were updated (the update
interval is dependent on the current zoom setting).

Next, we update the focus position.  If no object is being tracked, and
useAltAz=true, then the focus RA needs to advance at the sidereal rate
(one second on the sky per sidereal second of time).  If the simulation
is tracking an object, then the focus is set to the object's coordinates.
(See README.skymap for details on the focus position and animated
slewing)

Finally, the last thing updateTime() does is to re-draw the sky by calling
SkyMap::update(); see README.skymap for details.