Warning, /education/kstars/README.md is written in an unsupported language. File is not indexed.

0001 # A Desktop Planetarium for KDE
0003 KStars is free, open source, cross-platform Astronomy Software.
0005 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.
0007 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!
0009 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.
0011 ## Copyright
0013 Copyright (c) 2001 - 2020 by The KStars Team:
0015 KStars is Free Software, released under the GNU Public License. See COPYING for GPL license information.
0017 ## Downloads
0019 KStars is available for Windows, MacOS, and Linux. You can download the latest version from [KStars official website](https://edu.kde.org/kstars).
0021 On Linux, it is available for most Linux distributions.
0023 Latest stable version is v3.4.2
0025 ## Important URLs and files.
0027 * The [KStars homepage](https://edu.kde.org/kstars)
0028 * KStars [Git Repository](https://invent.kde.org/education/kstars)
0029 * KStars [Web Chat](https://webchat.kde.org/#/room/#kstars:kde.org)
0030 * Forum [where KStars is often discussed](https://indilib.org/forum.html)
0032 ## KStars documentation
0034 The KStars handbook can be found in your $(KDEDIR)/share/doc/HTML/<lang>/kstars/
0035 directory.  You can also easily access it from the Help menu, or by pressing
0036 the [F1] key, or by visiting https://docs.kde.org/?application=kstars
0037 Unfortunately, it's a bit out-of-date. We welcome volunteers to help
0038 update it.
0040 In addition, there are the following README files:
0042 README:             This file; general information
0043 README.planetmath:  Explanation of algorithms used to compute planet positions
0044 README.customize:   Advanced customization options
0045 README.images:      Copyright information for images used in KStars.
0046 README.i18n:        Instructions for translators
0048 ## Development
0050 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.
0051 Note: Previously KStars used Phabricator for its merge requests. That system is no longer in use.
0053 ### Integrated Development Environment IDE
0055 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.
0057 To open KStars in QtCreator, select the CMakeLists.txt file in the KStars source folder and then configure the build location and type.
0059 ### Building
0061 1. Prerequisite Packages
0063 To build and develop KStars, several packages may be required from your distribution. Here's a list.
0065 * Required dependencies
0066     * GNU Make, GCC -- Essential tools for building
0067     * cmake -- buildsystem used by KDE
0068     * Qt Library > 5.9.0
0069     * Several KDE Frameworks: KConfig, KDocTools, KGuiAddons, KWidgetsAddons, KNewStuff, KI18n, KInit, KIO, KXmlGui, KPlotting, KIconThemes
0070     * eigen -- linear algebra library
0071     * zlib -- compression library
0072     * StellarSolver -- see [https://github.com/rlancaste/stellarsolver](https://github.com/rlancaste/stellarsolver)
0074 * Optional dependencies
0075     * libcfitsio -- FITS library
0076     * libindi -- Instrument Neutral Distributed Interface, for controlling equipment.
0077     * xplanet
0078     * astrometry.net
0079     * libraw
0080     * wcslib
0081     * libgsl
0082     * qtkeychain
0085 2. Installing Prerequisites
0087 Debian/Ubuntu
0089 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.
0090 ```
0091 sudo apt-add-repository ppa:mutlaqja/ppa
0092 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|libkf5doctools-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
0093 ```
0095 Fedora
0096 ```
0097 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
0098 ```
0100 3. Compiling
0102 Open a console and run in the following commands:
0103 ```
0104 mkdir -p ~/Projects/build/kstars
0105 cd ~/Projects
0106 git clone https://invent.kde.org/education/kstars.git
0107 cd build/kstars
0108 cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=RelWithDebInfo ~/Projects/kstars
0109 make -j16
0110 sudo make install
0111 ```
0113 To run KStars, simply type **kstars** in the terminal.
0115 ### Code Style
0117 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:
0118 ```
0119 --style=allman
0120 --align-reference=name
0121 --indent-switches
0122 --indent-modifiers
0123 --indent-classes
0124 --pad-oper
0125 --indent-col1-comments
0126 --lineend=linux
0127 --max-code-length=124
0128 ```
0129 Some IDEs (e.g. QtCreator) support automatic formatting for the code every time you save the file to disk.
0131 ### Making Updates to the Handbook
0133 On linux run the following to install the necessary programs:
0135 ```
0136 sudo apt-get install docbook docbook-utils
0137 ```
0139 The source for the handbook is in kstars/doc.
0140 You can edit those files, include them in commits and MRs like you would c++ files (see below).
0141 You could figure out the markup by example, or learn from [online doc for docbook](https://opensource.com/article/17/9/docbook).
0142 In general, it is best to first copy the entire kstars/doc directory to a temporary directory, and edit and generate the handbook there,
0143 because if you ran meinproc in the main source directory, you would generate many .html files there,
0144 and you don't want to commit the generated files to your git repository.
0146 ```
0147 cp -pr kstars/doc ~/DOCBOOK
0148 cd ~/DOCBOOK
0149 meinproc5 index.docbook
0150 ```
0152 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
0153 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.
0155 To check syntax, you might want to run:
0157 ```
0158 checkXML5 index.docbook
0159 ```
0161 Once you're happy, copy your modified files back to kstars/doc, and treat the edited/new files as usual with git,
0162 including your modified files in a new commit and eventually a new merge request.
0164 ### Merge Request Descriptions
0166 See the section below, Git Tips, on technical specifics of how to generate a Merge Request.
0167 In the process of making the request, you will need to describe the request.
0168 Please use a format similar to [this one](https://invent.kde.org/education/kstars/-/merge_requests/33)
0169 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.
0171 ### Git Tips
0173 You must be familiar with git to make changes to KStars, and this is not the place for such a tutorial. There
0174 are many excellent resources for that on the web. The paragraph below, though, will give an overview of one way
0175 to make a Merge Request, given you already have sufficient git experience to clone KStars, make a local branch,
0176 modify the code as you like, commit your changes to your local branch, and test your code thoroughly.
0178 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.
0180 **One-time KStars git environment setup.**
0182 * [Make your KDE identity](https://community.kde.org/Infrastructure/Get_a_Developer_Account)
0183 * **Login.** Go to the [KStars gitlab page](https://invent.kde.org/education/kstars) and login in the upper right corner.
0184 * **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.
0185 * **Copy your URL.** Note the url of your fork. It should be https://invent.kde.org/YOUR_KDE_NAME/kstars
0186 * **Clone KStars.** Back on your computer run these commands
0187     * mkdir -p ~/Projects
0188     * cd ~/Projects
0189     * git clone https://invent.kde.org/YOUR_KDE_NAME/kstars
0190     * cd kstars
0191 * **Add your upstream.** Add the KStars main repo to your forked repo.
0192     * git remote add upstream https://invent.kde.org/education/kstars
0194 You are set up now.
0196 **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.
0198 * **Create your feature branch.**
0199     * git checkout -b YOUR_BRANCH_NAME
0200 * **Make your changes**
0201 * **Commit your changes**
0202     * git commit -a
0203 * **Push changes to your forked repo.**
0204     * git push origin YOUR_BRANCH_NAME
0205 * **Create a Merge Request**
0206     * Use your browser to visit your forked repo at  https://invent.kde.org/YOUR_KDE_NAME/kstars
0207     * You should see an option to create a Merge Request for YOUR_BRANCH_NAME. Fill in the details (see the above section).
0208     * You should be able to see a new URL dedicated to that Merge Request.
0209 * **Make Some Changes.** You may get requests to modify some of your code.
0210     * If so, you simply go back to your local branch, make and test your changes.
0211     * Commit your changes as above, inside your branch, with: git commit -a
0212     * Push your branch's changes to your forked repo as above with: git push origin YOUR_BRANCH_NAME
0213     * Your changes should automatically be added to your Merge Request. Check the Merge Request's page to be sure.
0214     * You may need to rebase your code--see below for details.
0216 **Rebasing your changes.** Others may be making changes to KStars at the same time you are working on your feature.
0217 Rebasing is updating your version of KStars and your particular changes to make it as if you changed the latest KStars version,
0218 e.g. reflect changes to the codebase made after you cloned or updated your own KStars copy. This is a significant topic
0219 you can Google, but the following instructions work most of the time.
0221 Note that this is done before you create your merge request, when you are the only one seeing your code changes. 
0222 Once you have started your merge request, your code is "public" and instead of rebasing, you should follow the merge procedure below.
0224 ```
0225 cd ~/Projects/kstars
0226 git checkout master
0227 git pull upstream master  # Get the master from the main KStars repo onto your local clone
0228 git push origin master    # Then push your updated local clone into your forked repo
0229 git checkout YOUR_BRANCH_NAME
0230 git rebase master
0231 git push origin YOUR_BRANCH_NAME -f
0232 ```
0234 If there are complications with the rebase, git will make suggestions on how to correct the issues.
0236 **Merging others' changes.** Once you submit a merge request, your code can be seen (and edited) by
0237 others. At this point, though you still may need to update to the latest KStars version, rebasing destroys
0238 change information and can overwrite what others are doing. Instead it is best to 'merge' in the current 
0239 version of KStars into your code.
0241 ```
0242 cd ~/Projects/kstars
0243 git checkout master
0244 git pull upstream master  # Get the master from the main KStars repo onto your local clone
0245 git push origin master    # Then push your updated local clone into your forked repo
0246 git checkout YOUR_BRANCH_NAME
0247 git merge master
0248 git push origin YOUR_BRANCH_NAME 
0249 ```
0251 The differences from the rebase section are the last 2 commands: 'git merge master' is used instead of 'git rebase master'.
0252 Also the 'git push' doesn't use the -f option. The first time you run the 'git push',
0253 you may be asked by git to add 'set-upstream origin' to the command. In that case, follow those instructions.
0255 If you follow this procedure, you will find a new 'merge commit' added to your branch's git log.
0258 **Your next change**. Once your Merge Request is complete (and possibly integrated into KStars), you may wish to move on and develop again.
0259 The next change will use another (new) feature branch, and the first feature branch could be deleted.
0260 You may want to run the following regularly to keep your master branch up-to-date with KStars.
0261 ```
0262 cd ~/Projects/kstars
0263 git checkout master
0264 git pull upstream master  # Get the master from the main KStars repo onto your local clone
0265 git push origin master    # Then push your updated local clone into your forked repo
0266 ```
0268 ## Writing Tests
0269 Tests are stored in the `Tests` folder and use QTest as support framework:
0270 * Unitary tests can be found in `auxiliary`, `capture`, `fitsviewer`, etc. They try to verify the behavior
0271   of a minimal set of classes, and are support for feature development.
0272 * 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
0273   interface, and focus on availability of visual feedback and stability of procedures.
0275 ### Writing Unitary Tests
0276 1. Decide where your new unitary test will reside in `Tests`.
0277 KStars classes should live in a folder matching their origin: for instance, auxiliary class tests live in `auxiliary`.
0278 Find a suitable place for your test, based on the part of the system that is being tested.
0279 As an example, a folder named `thatkstarscategory`.
0281 2. Create a new unitary test class, or copy-paste an existing unitary test to a new one.
0282 Check `Tests/kstars_ui_tests/kstars_ui_tests.h` as an example.
0283 Name the `.h` and `.cpp` files as "test[lowercase kstars class]" (for instance "testthatkstarsclass"), and update them to match the following:
0284 ```
0285 /* [Author+Licence header] */
0289 #include <QtTest>
0290 #include <QObject>
0292 class TestThatKStarsClass: public QObject
0293 {
0294     Q_OBJECT
0295 public:
0296     explicit TestThatKStarsClass(QObject *parent = null);
0298 private slots:
0299     void initTestCase();                    // Will trigger once at beginning
0300     void cleanupTestCase();                 // Will trigger once at end
0302     void init();                            // Will trigger before each test
0303     void cleanup();                         // Will trigger after each test
0305     void testThisParticularFunction_data(); // Data fixtures for the test function (Qt 5.9+)
0306     void testThisParticularFunction();      // Test function
0307 }
0309 ```
0310 ```
0311 /* [Author+Licence header] */
0312 #include "testthatkstarsclass.h"
0313 TestThatKStarsClass::TestThatKStarsClass(QObject* parent): QObject(parent) {}
0314 TestThatKStarsClass::initTestCase() {}
0315 TestThatKStarsClass::cleanupTestCase() {}
0316 TestThatKStarsClass::init() {}
0317 TestThatKStarsClass::cleanup() {}
0319 TestThatKStarsClass::testThisParticularFunction_data()
0320 {
0321     // If needed, add data fixtures with QTest::AddColumn/QTest::AddRow, each will trigger testThisParticularFunction
0322 }
0324 TestThatKStarsClass::testThisParticularFunction()
0325 {
0326     // Write your tests here, eventually using QFETCH to retrieve the current data fixture
0327 }
0329 QTEST_GUILESS_MAIN(TestThatKStarsClass);
0330 ```
0331 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.
0333 3. Update the CMake configuration to add your test.
0334 If you created a new folder, create a new `CMakeLists.txt` to add your test:
0335 ```
0336 ADD_EXECUTABLE( testthatkstarsclass testthatkstarsclass.cpp )
0337 TARGET_LINK_LIBRARIES( testthatkstarsclass ${TEST_LIBRARIES})
0338 ADD_TEST( NAME ThatKStarsClassTest COMMAND testthatkstarsclass )
0339 ```
0340 Have the `CMakeLists.txt` residing one folder higher in the filesystem include that `CMakeLists.txt` by adding:
0341 ```
0342 include_directories(
0343     ...
0344     ${kstars_SOURCE_DIR}/kstars/path/to/the/folder/of/the/kstars/class/you/are/testing
0345 )
0346 ...
0347 add_subdirectory(thatkstarscategory)
0348 ```
0349 Make sure you add your `add_subdirectory` in the right dependency group. Ekos tests require `INDI_FOUND` for instance.
0351 4. Write your tests
0352 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.
0353 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.
0354 Also pay attention to Qt library version support. For instance, data fixtures require Qt 5.9+.
0356 ### Writing User Interface Tests
0358 Follow the same steps as for unitary tests, but locate your test classes in `kstars_ui_tests`.
0360 One important thing about UI tests is that they must all use `QStandardPaths::setTestModeEnabled(true)`, so that they execute with a separate user
0361 configuration that is initially blank. User interface tests thus require a preliminary setup to function properly, such as using the new configuration
0362 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`,
0363 in `main()`, **after** the execution of `TestKStarsStartup`.
0365 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.
0366 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...
0368 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
0369 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).
0370 Fortunately, these hacks do not alter the execution of the tested code.
0372 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
0373 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
0374 `QVERIFY(Ekos::Manager::Instance()->mountModule()->sync(ra,dec))`. Remember that sometimes you need to leave time for asynchronous signals to be emitted and caught.
0376 ## Credits
0377 ### The KStars Team
0378 #### Original Author
0379 Jason Harris <kstars@30doradus.org>
0380 #### Current Maintainer
0381 Jasem Mutlaq <mutlaqja@ikarustech.com>
0382 #### Contributors (Alphabetical)
0383 * Akarsh Simha <akarsh.simha@kdemail.net>
0384 * Alexey Khudyakov <alexey.skladnoy@gmail.com>
0385 * Artem Fedoskin <afedoskin3@gmail.com>
0386 * Carsten Niehaus <cniehaus@kde.org>
0387 * Chris Rowland <chris.rowland@cherryfield.me.uk>
0388 * Csaba Kertesz <csaba.kertesz@gmail.com>
0389 * Eric Dejouhanet <eric.dejouhanet@gmail.com>
0390 * Harry de Valence <hdevalence@gmail.com>
0391 * Heiko Evermann <heiko@evermann.de>
0392 * Hy Murveit <murveit@gmail.com>
0393 * James Bowlin <bowlin@mindspring.com>
0394 * Jérôme Sonrier <jsid@emor3j.fr.eu.org>
0395 * Mark Hollomon <mhh@mindspring.com>
0396 * Martin Piskernig <martin.piskernig@stuwo.at>
0397 * Médéric Boquien <mboquien@free.fr>
0398 * Pablo de Vicente <pvicentea@wanadoo.es>
0399 * Prakash Mohan <prakash.mohan@kdemail.net>
0400 * Rafał Kułaga <rl.kulaga@gmail.com>
0401 * Rishab Arora <ra.rishab@gmail.com>
0402 * Robert Lancaster <rlancaste@gmail.com>
0403 * Samikshan Bairagya <samikshan@gmail.com>
0404 * Thomas Kabelmann <tk78@gmx.de>
0405 * Valentin Boettcher <hiro@protagon.space>
0406 * Victor Cărbune <victor.carbune@kdemail.net>
0407 * Vincent Jagot <vincent.jagot@free.fr>
0408 * Wolfgang Reissenberger <sterne-jaeger@t-online.de>
0409 * Yuri Chornoivan <yurchor@ukr.net>
0411 ### Data Sources:
0413  Most of the catalog data came from the Astronomical Data Center, run by
0414  NASA.  The website is:
0415  http://adc.gsfc.nasa.gov/
0417  NGC/IC data is compiled by Christian Dersch from OpenNGC database.
0418  https://github.com/mattiaverga/OpenNGC (CC-BY-SA-4.0 license)
0420  Supernovae data is from the Open Supernova Catalog project at https://sne.space
0421  Please refer to the published paper here: http://adsabs.harvard.edu/abs/2016arXiv160501054G
0423  KStars links to the excellent image collections and HTML pages put together
0424  by the Students for the Exploration and Development of Space, at:
0425  http://www.seds.org
0427  KStars links to the online Digitized Sky Survey images, which you can
0428  query at:
0429  http://archive.stsci.edu/cgi-bin/dss_form
0431  KStars links to images from the HST Heritage project, and from HST
0432  press releases:
0433  http://heritage.stsci.edu
0434  http://oposite.stsci.edu/pubinfo/pr.html
0436  KStars links to images from the Advanced Observer Program at
0437  Kitt Peak National Observatory.  If you are interested in astrophotography,
0438  you might consider checking out their program:
0439  http://www.noao.edu/outreach/aop/
0441  Credits for each image used in the program are listed in README.images
0444 # Original Acknowledgement from the Project Founder
0446  KStars is a labor of love.  It started as a personal hobby of mine, but
0447  very soon after I first posted the code on Sourceforge, it started to
0448  attract other developers.  I am just completely impressed and gratified
0449  by my co-developers.  I couldn't ask for a more talented, friendly crew.
0450  It goes without saying that KStars would be nowhere near what it is today
0451  without their efforts.  Together, we've made something we can all be
0452  proud of.
0454  We used (primarily) two books as a guide in writing the algorithms used
0455  in KStars:
0456  + "Practical Astronomy With Your Calculator" by Peter Duffett-Smith
0457  + "Astronomical Algorithms" by Jean Meeus
0459  Thanks to the developers of Qt and KDE whose peerless API made KStars
0460  possible.  Thanks also to the tireless efforts of the KDE translation
0461  teams, who bring KStars to a global audience.
0463  Thanks to everyone at the KDevelop message boards and on irc.kde.org,
0464  for answering my frequent questions.
0466  Thanks also to the many users who have submitted bug reports or other
0467  feedback.
0470 You're still reading this? :)
0471 Well, that's about it.  I hope you enjoy KStars!
0473 Jason Harris
0474 kstars@30doradus.org
0476 KStars Development Mailing list
0477 kstars-devel@kde.org
0479 Send us ideas and feedback!