Stellarium 26.2 User Guide
Georg Zotti, Alexander Wolf (editors)
2026
Copyright © 2014-2026 Georg Zotti.
Copyright © 2011-2026 Alexander Wolf.
Copyright © 2006-2013 Matthew Gates.
Copyright © 2013-2014 Barry Gerdes († 2014).
STELLARIUM.ORG
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU
Free Documentation License, Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of
the license is included in the appendix G entitled “GNU Free Documentation License”.
All trademarks, third party brands, product names, trade names, corporate names and company names
mentioned may be trademarks of their respective owners or registered trademarks of other companies and
are used for purposes of explanation and to the readers’ benefit, without implying a violation of copyright law.
Version 26.2-1, June 24, 2026
Contents
I
Basic Use
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Historical notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Version Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Scientific use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.5 About this User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.1 Minimum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.2 Recommended . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Downloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.2 macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.3 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.4 *BSD/Solaris/OpenIndiana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.5 Haiku . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4 Running Stellarium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.2 macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.3 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.4 *BSD/Solaris/OpenIndiana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.5 Haiku . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.5 Script Launch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.6 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3 A First Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1 Time Travel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2 Moving Around the Sky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3 The Main Tool Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.4 Taking Screenshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.5 Observing Lists (Bookmarks) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.6 Custom Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.7 Copy Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.8 Speech Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4 The User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.1 Setting the Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.2 Setting Your Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.2.1 Time Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.2.2 Geographical Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.2.3 Observers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.3 The Configuration Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.3.1 The Main Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.3.2 The Information Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.3.3 The Extras Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.3.4 The Time Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.3.5 The Tools Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.3.6 The Speech Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.3.7 The Scripts Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.3.8 The Plugins Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.4 The View Settings Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.4.1 The Sky Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.4.2 The Solar System Objects (SSO) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.4.3 The Deep-Sky Objects (DSO) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4.4 The Markings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4.5 The Landscape Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4.6 The Sky Culture Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.4.7 The Surveys Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.5 The Search Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.5.1 The Object tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.5.2 The SIMBAD tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.5.3 The Position tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.5.4 The Lists tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.5.5 The Options tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.6 The Astronomical Calculations Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.6.1 The Positions Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.6.2 The Ephemeris Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.6.3 The “Risings, Transits, and Settings” (RTS) Ta b . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.6.4 The Phenomena Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.6.5 The Graphs Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.6.6 The “What’s Up Tonight” (WUT) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.6.7 The “Planetary Calculator” (PC) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.6.8 The Eclipses Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.6.9 The Almanac Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.7 The Help Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.7.1 The Help Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.7.2 The About Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.7.3 The Log Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.7.4 The Config Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.8 Editing Keyboard Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.8.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
II
Advanced Use
5 Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1 Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1.2 macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.1.3 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.1.4 *BSD/Solaris/OpenIndiana . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.1.5 Haiku . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.1.6 Customized Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.2 Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.3 The Logfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.4 The Main Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.5 Getting Extra Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.5.1 More Stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.5.2 More Deep-Sky Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.5.3 Alternative Planet Ephemerides: DE430, DE431, DE440, DE441 . . . . . . . . . . . . . 62
5.5.4 GPS Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.5.5 Modernized MESA3D libraries (Software OpenGL on Windows) . . . . . . . . . . . . 64
6 Advanced Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.1 Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.2 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.2.1 Logfile tweaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.3 GUI Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.3.1 Panel transparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.3.2 Button brightness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.3.3 Text shadow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.3.4 User interface colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.4 Spout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.5 Show effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.5.1 Sky Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.5.2 Star Trails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.6 Spherical Mirror Mode for Planetarium Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.6.1 360° Projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.6.2 Projector Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.6.3 Computer Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.6.4 System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.6.5 Stellarium Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.6.6 Further notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7 Landscapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.1 Stellarium Landscapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.1.1 Location information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.1.2 Polygonal landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.1.3 Spherical landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
7.1.4 High resolution (“Old Style”) landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.1.5 Fisheye landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.1.6 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.1.7 Gazetteer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.1.8 Packing and Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
7.2 Creating Panorama Photographs for Stellarium . . . . . . . . . . . . . . . . . . . . . . . . 82
7.2.1 Panorama Photography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
7.2.2 Hugin Panorama Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
7.2.3 Regular creation of panoramas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
7.3 Panorama Postprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.3.1 The GIMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.3.2 ImageMagick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.3.3 Final Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
7.3.4 Artificial Panoramas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.3.5 Nightscape Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
7.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
7.5 Other recommended software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
7.5.1 IrfanView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
7.5.2 FSPViewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
7.5.3 Clink and GNUWin32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
7.5.4 WSL – Windows Subsystem for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
8 Deep-Sky Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
8.1 Stellarium DSO Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
8.1.1 Modifying catalog.dat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
8.1.2 Modifying names.dat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
8.1.3 Modifying textures.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
8.1.4 Modifying outlines.dat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8.2 Adding Extra Nebula Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
8.2.1 Image requirements for inclusion in Stellarium . . . . . . . . . . . . . . . . . . . . . . . . . 101
8.2.2 Processing requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.2.3 Manual processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.2.4 Automated processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.2.5 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
9 Sky Cultures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
9.1 Text description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
9.1.1 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
9.1.2 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.1.3 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.1.4 Technical Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
9.2 Technical data: index.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
9.2.1 Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.2.2 Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.2.3 Constellation boundaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.2.4 Constellations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.2.5 Asterisms and help rays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.2.6 Culture Relevant Coordinate Systems: Zodiac and Lunar Systems . . . . . . . . . 119
9.2.7 Names of Stars, Planets and Nonstellar Objects . . . . . . . . . . . . . . . . . . . . . . . 121
9.2.8 Deep-Sky Objects Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.2.9 User Settings for the Skycultures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.3 Territory description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
9.4 The Skyculture Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
9.5 Publish Your Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
10 Surveys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.2 Hipslist file and default surveys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.3 Solar system HiPS survey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.4 Digitized Sky Survey 2 (TOAST Survey) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.4.1 Local Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
11 Stellarium’s Skylight Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
11.2 The Skylight Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
11.2.1 Legacy Mode: The Preetham Skylight Model . . . . . . . . . . . . . . . . . . . . . . . . . 129
11.2.2 Advanced Mode: The ShowMySky Skylight Model . . . . . . . . . . . . . . . . . . . . . 130
11.2.3 Intermediate Mode: The Lightweight Skylight Model . . . . . . . . . . . . . . . . . . . 131
11.3 Light Pollution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11.4 Tone Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
III
Extending Stellarium
12 Plugins: An Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
12.1 Enabling plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
12.2 Data for plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
13 Interface Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
13.1 Angle Measure Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
13.2 Equation of Time Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
13.2.1 Section
EquationOfTime
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
13.3 Pointer Coordinates Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
13.3.1 Section
PointerCoordinates
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . 140
13.4 Time Navigator Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
13.5 Text User Interface Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
13.5.1 Using the Text User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
13.5.2 TUI Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
13.5.3 Section
tui
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
13.6 Remote Control Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
13.6.1 Using the plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
13.6.2 Remote Control Web Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
13.6.3 Remote Control API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
13.6.4 Developer information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
13.6.5 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
13.7 Remote Sync Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
13.7.1 Developer notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
13.7.2 Finetuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
13.8 OnlineQueries Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
13.8.1 Section
OnlineQueries
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
13.9 Sky Culture Maker Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
13.9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
13.9.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
13.9.3 Converting an Existing Sky Culture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
13.9.4 Creating a New Sky Culture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
13.9.5 Creating a New Constellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
13.9.6 Exporting the Sky Culture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
13.9.7 Closing the Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
13.9.8 Further Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
13.9.9 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
13.10 Solar System Editor Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
13.11 Nebula Textures Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
13.11.1 Online Solving and Texture Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
13.11.2 Manual Texture Addition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
13.11.3 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
13.12 Calendars Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
13.12.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
13.12.2 The Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
13.12.3 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
13.12.4 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
13.12.5 Further development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
13.12.6 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
14 Object Catalog Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
14.1 Bright Novae Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
14.1.1 Section
Novae
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
14.1.2 Format of bright novae catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
14.1.3 Light curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
14.2 Historical Super novae Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
14.2.1 List of supernovae in default catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
14.2.2 Light curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
14.2.3 Section
Supernovae
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
14.2.4 Format of historical supernovae catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
14.3 Exoplanets Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
14.3.1 Potential habitable exoplanets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
14.3.2 Proper names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
14.3.3 Section
Exoplanets
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
14.3.4 Format of exoplanets catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
14.4 Pulsars Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
14.4.1 Section
Pulsars
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
14.4.2 Format of pulsars catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
14.5 Quasars Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
14.5.1 Section
Quasars
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
14.5.2 Format of quasars catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
14.6 Meteor Showers Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
14.6.1 Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
14.6.2 Section
MeteorShowers
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
14.6.3 Format of Meteor Showers catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
14.6.4 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
14.6.5 Further Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
14.7 Navigational Stars Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
14.7.1 Section
NavigationalStars
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
14.8 Satellites Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
14.8.1 Satellite Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
14.8.2 Satellite Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
14.8.3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
14.8.4 The approximated visual magnitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
14.8.5 Sources for TLE data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
14.9 ArchaeoLines Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
14.9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
14.9.2 Characteristic Declinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
14.9.3 Geographical Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
14.9.4 Custom Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
14.9.5 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
14.9.6 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
15 Scenery3d – 3D Landscapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
15.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
15.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
15.3 Hardware Requirements & Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
15.3.1 Performance notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
15.4 Model Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
15.4.1 Exporting OBJ from Sketchup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
15.4.2 Notes on OBJ file format limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
15.4.3 Configuring OBJ for Scenery3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
15.4.4 Concatenating OBJ files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
15.4.5 Beyond 3D: Temporally evolving Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
15.4.6 Working with non-georeferenced OBJ files . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
15.4.7 Rotating OBJs with recognized survey points . . . . . . . . . . . . . . . . . . . . . . . . . 215
15.5 Predefined views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
15.6 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
15.7 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
16 Stellarium at the Telescope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
16.1 Oculars Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
16.1.1 Using the Ocular plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
16.1.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
16.1.3 Scaling the eyepiece view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
16.2 TelescopeControl Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
16.2.1 Abilities and limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
16.2.2 Using this plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
16.2.3 Main window (’Telescopes’) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
16.2.4 Telescope configuration window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
16.2.5 Supported devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
16.2.6 RTS2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
16.2.7 INDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
16.2.8 ASCOM 7 (Windows only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
16.2.9 StellariumScope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
16.2.10 Other telescope servers and Stellarium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
16.3 Observability Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
16.4 Mosaic Camera Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
16.4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
16.4.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
16.4.3 Cameras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
16.4.4 Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
17 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
17.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
17.2 The Script Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
17.2.1 The Tabs in the Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
17.2.2 The Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
17.2.3 German Keyboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
17.3 Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
17.4 Minimal Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
17.5 Critical Scripting Differences introduced with version 1.0 . . . . . . . . . . . . . . . . 247
17.5.1 Pause/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
17.5.2 The Vec3f problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
17.6 Example: Retrograde motion of Mars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
17.6.1 Script header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
17.6.2 A body of script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
17.7 More Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
IV
Practical Astronomy
18 Astronomical Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
18.1 The Celestial Sphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
18.2 Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
18.2.1 Altitude/Azimuth Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
18.2.2 Right Ascension/Declination Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
18.2.3 Fixed Equatorial Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
18.2.4 Ecliptical Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
18.2.5 Galactic Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
18.2.6 Planet Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
18.3 Distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
18.4 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
18.4.1 Sidereal Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
18.4.2 Julian Day Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
18.4.3 Delta T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
18.5 Angles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
18.5.1 Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
18.5.2 Handy Angles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
18.6 The Magnitude Scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
18.7 Luminosity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
18.8 Precession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
18.9 Parallax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
18.9.1 Geocentric and Topocentric Observations . . . . . . . . . . . . . . . . . . . . . . . . . . 269
18.9.2 Stellar Parallax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
18.10 Aberration of Light . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
18.11 Proper Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
18.11.1 Binary Star s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
19 Astronomical Phenomena . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
19.1 The Sun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
19.1.1 Twilight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
19.2 Stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
19.2.1 Multiple Star Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
19.2.2 Constellations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
19.2.3 Star Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
19.2.4 Spectral Type & Luminosity Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
19.2.5 Variable Stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
19.3 Our Moon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
19.3.1 Phases of the Moon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
19.3.2 The Lunar Magnitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
19.4 The Major Planets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
19.4.1 Terrestrial Planets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
19.4.2 Jovian Planets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
19.4.3 Apparent Magnitudes of the Planets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
19.5 The Minor Bodies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
19.5.1 Asteroids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
19.5.2 Comets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
19.6 Meteoroids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
19.7 Zodiacal Light and Gegenschein . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
19.8 The Milky Way . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
19.9 Nebulae . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
19.9.1 The Messier Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
19.9.2 The Caldwell catalogue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
19.10 Galaxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
19.11 Eclipses and Transits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
19.11.1 Solar Eclipses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
19.11.2 Lunar Eclipses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
19.11.3 Transits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
19.11.4 Contact Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
19.12 Observing Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
19.13 Atmospheric effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
19.13.1 Atmospheric Extinction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
19.13.2 Atmospheric Refraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
19.13.3 Light Pollution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
20 A Little Sky Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
20.1 Dubhe and Merak, The Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
20.2 M31, Messier 31, The Andromeda Galaxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
20.3 The Garnet Star, µ Cephei . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
20.4 4 and 5 Lyrae, ε Lyrae . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
20.5 M13, Hercules Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
20.6 M45, The Pleiades, The Seven Sisters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
20.7 C41, The Hyades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
20.8 Algol, The Demon Star,
β Persei . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
20.9 Sirius, α Canis Majoris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
20.10 M44, The Beehive, Praesepe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
20.11 27 Cephei,
δ Cephei . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
20.12 Betelgeuse,
α Orionis, 58 Orionis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
20.13 M42, The Great Orion Nebula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
20.14 La Superba, Y Canum Venaticorum, HIP 62223 . . . . . . . . . . . . . . . . . . . . . . . . 291
20.15 52 and 53 Bootis,
ν
1
and
ν
2
Bootis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
20.16 Almach,
γ Andromedae . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
20.17 Algieba,
γ Leonis, 41 Leonis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
20.18 Castor,
α Geminorum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
20.19 PZ Cas, HIP 117078 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
20.20 VV Cephei, HIP 108317 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
20.21 AH Scorpii, HIP 84071 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
20.22 Albireo, β Cygni . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
20.23 31 and 32 Cygni, o
1
and o
2
Cygni . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
20.24 The Coathanger, Brocchi’s Cluster, Cr 399 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
20.25 Kemble’s Cascade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
20.26 The Double Cluster,
χ and h Persei, NGC 884 and NGC 869 . . . . . . . . . . . . . . 294
20.27 Large Magellanic Cloud, PGC 17223 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
20.28 Tarantula Nebula, C 103, NGC 2070 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
20.29 Small Magellanic Cloud, NGC 292, PGC 3085 . . . . . . . . . . . . . . . . . . . . . . . . . 295
20.30
ω Centauri cluster, C 80, NGC 5139 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
20.31 47 Tucanae, C 106, NGC 104 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
20.32 The Coalsack Nebula, C 99 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
20.33 Mira, o Ceti, 68 Cet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
20.34 α Persei Cluster, Cr 39, Mel 20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
20.35 M7, The Ptolemy Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
20.36 M22, NGC 6656, The Great Sagittarius Cluster . . . . . . . . . . . . . . . . . . . . . . . . . 297
20.37 M24, The Sagittarius Star Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
20.38 IC 4665, The Summer Beehive Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
20.39 The E Nebula, Barnard 142 and 143 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
21 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
21.1 Find M31 in Binoculars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
21.1.1 Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
21.1.2 For Real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
21.2 Handy Angles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
21.3 Find a Lunar Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
21.4 Find a Solar Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
21.5 Find a retrograde motion of Mars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
21.6 Analemma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
21.7 Transit of Venus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
21.8 Transit of Mercury . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
21.9 Triple shadows on Jupiter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
21.10 Jupiter without satellites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
21.11 Mutual occultations of planets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
21.12 The proper motion of stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
V
Appendices
A Default Hotkeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
A.1 Mouse actions with combination of the keyboard keys . . . . . . . . . . . . . . . . . 305
A.2 Display Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
A.3 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
A.4 Movement and Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
A.5 Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
A.6 Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
A.7 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
A.8 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
A.8.1 Angle Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
A.8.2 ArchaeoLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
A.8.3 Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
A.8.4 Equation of Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
A.8.5 Exoplanets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
A.8.6 Meteor Showers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
A.8.7 Oculars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
A.8.8 Pulsars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
A.8.9 Quasars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
A.8.10 Satellites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
A.8.11 Scenery3d: 3D landscapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
A.8.12 Solar System Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
A.8.13 Telescope Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
A.8.14 Text User Interface (TUI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
A.9 Special local keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
B The Bortle Scale of Light Pollution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
B.1 Excellent dark sky site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
B.2 Typical truly dark site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
B.3 Rural sky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
B.4 Rural/suburban transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
B.5 Suburban sky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
B.6 Bright suburban sky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
B.7 Suburban/urban transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
B.8 City sky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
B.9 Inner-city sky . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
C Star Catalogues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
C.1 Stellarium’s Sky Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
C.1.1 Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
C.2 Star Catalogue File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
C.2.1 General Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
C.2.2 File Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
C.2.3 Record Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
C.3 Variable Stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
C.3.1 Variable Star Catalog File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
C.3.2 GCVS Variability Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
C.4 Double Stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
C.4.1 Double Star Catalog File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
C.4.2 Designations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
C.5 Cross-Identification Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
C.5.1 Cross-Identification Catalog File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
C.6 Binary Star System Orbital Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
C.6.1 Binary Star System Orbital Parameters Catalog File Format . . . . . . . . . . . . . . 343
D Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
D.1 Program Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
D.1.1
astro
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
D.1.2
astrocalc
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
D.1.3
audio
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
D.1.4
color
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
D.1.5
custom_selected_info
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
D.1.6
custom_time_correction
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
D.1.7
devel
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
D.1.8
dso_catalog_filters
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
D.1.9
dso_type_filters
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
D.1.10
fov
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
D.1.11
gui
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
D.1.12
init_location
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
D.1.13
landscape
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
D.1.14
localization
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
D.1.15
main
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
D.1.16
navigation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
D.1.17
plugins_load_at_startup
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
D.1.18
projection
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
D.1.19
proxy
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
D.1.20
scripts
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
D.1.21
search
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
D.1.22
speech
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
D.1.23
spheric_mirror
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
D.1.24
stars
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
D.1.25
tui
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
D.1.26
video
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
D.1.27
viewing
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
D.1.28
DialogPositions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
D.1.29
DialogSizes
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
D.1.30
hips
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
D.2 Solar System Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
D.2.1 File ssystem_major.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
D.2.2 File ssystem_minor.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
D.2.3 JPL Horizons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
D.2.4 Multiple Epochs for Minor Planets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
E Planetary nomenclature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
E.1 Format of nomenclature data file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
E.2 Planetary Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
E.3 How names are approved by the IAU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
E.4 IAU rules and conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
E.5 Naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
E.6 Descriptor terms (feature types) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
E.6.1 Chart of landform types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
F Accuracy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
F.1 Date Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
F.2 Stellar Astrometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
F.3 Planetary Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
F.4 Minor Bodies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
F.5 Precession and Nutation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
F.6 Planet Axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
F.7 Eclipses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
F.8 The Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
F.9 Comparison to Reference Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
G GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
G.1 PREAMBLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
G.2 APPLICABILITY AND DEFINITIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
G.3 VERBATIM COPYING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
G.4 COPYING IN QUANTITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
G.5 MODIFICATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
G.6 COMBINING DOCUMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
G.7 COLLECTIONS OF DOCUMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
G.8 AGGREGATION WITH INDEPENDENT WORKS . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
G.9 TRANSLATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
G.10 TERMINATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
G.11 FUTURE REVISIONS OF THIS LICENSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
G.12 RELICENSING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
H Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
H.1 Contributors to this User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
H.2 Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
H.2.1 Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
H.2.2 Former Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
H.2.3 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
H.3 How you can help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
H.4 Technical Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
H.5 Included Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
H.6 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
H.7 Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
H.7.1 Full credits for “earthmap” texture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
H.7.2 License for the JPL planets images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
H.7.3 DSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Index
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Foreword for Stellarium 26.1
Welcome to the latest edition of this software.
Over its project history of over 25 years, Stellarium has grown better every year as an easy to use
simulator that shows on screen what you would see if the night sky outside was void from clouds but else
filled with the quietly shining stars which have inspired humans around the globe from time immemorial
with their unbreakable solemnity. The past decades have however challenged this “unbreakable” state. Light
pollution from excessive artificial light at night has diminished the number of stars and especially visibility
of the Milky Way for large parts of the population, and it is getting worse every year. And another technical
development acts as solemnity breaker. The first artificial satellites were greeted as signs of technical
progress, and nobody would doubt that telecommunication, navigation, weather observation, or general earth
observation and other remote sensing satellites are useful. The International Space Station, once established
as a bright beacon of international collaboration for the benefit of humankind, is still always a spectacle to
observe. Unfortunately it seems to be already a monument of a better past.
Observing the once-solemn starry skies nowadays appears to be permanently disturbed by some moving
dot of light, or even several dots, crossing the field of view. Whenever I ask Stellarium’s Satellites plugin for
identification, almost every time it is a member of always the same “satellite constellation” which is still
permanently growing and — simply has taken the joy out of one-shot astrophotography. Yes, “just make a
hundred exposures and let the AI remove the criss-cross scratches while stacking”. Did I then experience this
artificially restored view into the great solemn awe-inspiring infinity? Is it still “my photo” then? How would
I stack wide-angle photos including a foreground landscape without evil tricks? And generally, it’s not really
about pretty pictures. Scientific astronomy is highly concerned, especially about newly announced projects
like mirrors in space illuminating the ground where nature wanted to give darkness and allow recreation,
or data centers in space where they just don’t belong. (The envisioned benefit of free radiative cooling is
inefficient and needs large radiators – how does a million of moving dots in permanent sunlight sound to
your observing plan?) All this is connected with a spectrum of environmental problems you can surely find
discussed elsewhere. It does not help to look away. Also climate change is happening despite irresponsible
world leaders ignoring it.
Back to the wonders of the night sky and how to enjoy them while we still can. When you take a laptop
under the skies, battery life is often a concern. The latest ARM based processors allow much longer battery
life than previous CPU gemerations. Thanks to a laptop donation from Microsoft we now could finalize our
adoption of the Windows for Arm64 platform. Especially telescope support should now work stable together
with the ASCOM7 platform. You may be able to work with a lighter battery pack and less cables now. A
little caveat: currently the build pipelines available to us do not provide the latest Qt versions, so the Arm64
build lacks support for the internal webbrowser of the OnlineQueries plugin (section 13.8) and also speech
output (section 4.3.6). We hope this issue will go away in the next months.
On the desktop, Stellarium has become the de-facto most relevant simulation environment for cultural
astronomy, be it archaeoastronomical simulation of old standing stone rows under simulated skies of
yesteryear, or explaining the constellations and how they can be used in the lives of the many cultures living
on our planet.
After a year with many changes: Star catalog, skyculture file format, mosaic camera, restored ASCOM
telescope support, speech output, . . ., this first version in 2026 is mostly about consolidating. Speech
output is more complete and should have become more translator friendly, but surely is a challenge for our
translation teams. We hope speech output in your language and your operating system is becoming usable,
but there are factors which we surely have missed. If you know something better, please fix it and tell us.
The new skyculture file format looks at least almost finished, closing the deficiencies of the old system
that we and some of you had identified in the last years. Stellarium can now display multiple linguistic
variants of constellation and star labels, can show “single star constellations” and “dark constellations” formed
by dust clouds in the Milky Way, can properly identify Morning and Evening star, and for those cultures
where it is relevant, illustrate the zodiac and lunar stations or lunar mansions in various culture-dependent
versions, and some more.
The creation of new skycultures is supported by a new plugin created by a student team around our
skyculture researcher Susanne M. Hoffmann, the Sky Culture Maker (SCM) described in section 13.9, which
guides you through the process in wizard style. Authors can now define skyculture regions as polygons on a
map. Moritz Rätz finalized the plugin and also developed a new map-based skyculture selection interface that
sorts skycultures by geographic regions. (We aim at supplying the map polygons for the existing skycultures
over the next few releases.) All details of the new format can be found in chapter 9.
The advanced format for sky cultures however poses a new challenge around font display. So far we
don’t see need for installation of additional fonts, but some platforms (esp. Windows) have to get “nudged”
somewhat to show the more exotic characters. Please report errors when you see boxes instead of character
glyphs. The “Gravity Labels” which are useful in planetarium domes do not work well for Arab and certain
Asiatic fonts. While we can see that, we have no easy fix in sight. If you know what to do, please feel invited
to get involved.
And we welcome another new contributor who finally got involved! Atque developed a simple plugin
which shows a window full of buttons four our many time stepping commands which were previously only
accessible when assigned to hotkeys (section 13.4). We have so many of these commands that it is hard to
find a good key layout, though, so until now it was up to you to configure your favourite subset. For easy
access to these functions, this plugin is very welcome. He also implemented dynamic scaling for the Moon,
which means a visually enlarged Moon which is so useful for wide-angle views eventually takes its natural
size when zooming in, and has started fixing long-standing bugs.
Developing and maintaining a project of this size needs dedication, especially when done as unpaid side
occupation. Large progress needs funding which is sometimes hard to find. We want to thank all sponsors
and backers of the project as by last year we had collected substantial funds to support this development
also in work hours. We like working on this project and would like to be able to run future similar focused
improvements, but also must pay our bills, so please keep up your kind support!
In the name of all prior and current developers we wish you much enjoyment with this and future
versions of the Stellarium desktop planetarium!
Georg Zotti and Alexander Wolf, March 2026
I
Basic Use
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Historical notes . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Version Numbers . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Acknowledgements . . . . . . . . . . . . . . . . . . . . . 5
1.4 Scientific use . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.5 About this User Guide . . . . . . . . . . . . . . . . . . . . 6
2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 System Requirements . . . . . . . . . . . . . . . . . . . . . 7
2.2 Downloading . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4 Running Stellarium . . . . . . . . . . . . . . . . . . . . . . . 9
2.5 Script Launch . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.6 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . 10
3 A First Tour . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1 Time Travel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2 Moving Around the Sky . . . . . . . . . . . . . . . . . . 13
3.3 The Main Tool Bar . . . . . . . . . . . . . . . . . . . . . . . . 14
3.4 Taking Screenshots . . . . . . . . . . . . . . . . . . . . . . 16
3.5 Observing Lists (Bookmarks) . . . . . . . . . . . . . . . 16
3.6 Custom Markers . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.7 Copy Information . . . . . . . . . . . . . . . . . . . . . . . . 17
3.8 Speech Output . . . . . . . . . . . . . . . . . . . . . . . . . 17
4 The User Interface . . . . . . . . . . . . . . . . . . . 19
4.1 Setting the Date and Time . . . . . . . . . . . . . . . . 19
4.2 Setting Your Location . . . . . . . . . . . . . . . . . . . . 20
4.3 The Configuration Window . . . . . . . . . . . . . . . . 21
4.4 The View Settings Window . . . . . . . . . . . . . . . . . 27
4.5 The Search Window . . . . . . . . . . . . . . . . . . . . . . 37
4.6 The Astronomical Calculations Window . . . . . 40
4.7 The Help Window . . . . . . . . . . . . . . . . . . . . . . . . 54
4.8 Editing Keyboard Shortcuts . . . . . . . . . . . . . . . 56
1. Introduction
Stellarium is a software project that allows people to use their home computer as a virtual planetarium.
It calculates the positions of the Sun and Moon, planets and stars, and draws how the sky would look to
an observer depending on their location and the time. It can also draw the constellations and simulate
astronomical phenomena such as meteor showers or comets, and solar or lunar eclipses.
Stellarium may be used as an educational tool for teaching about the night sky, as an observational aid for
amateur astronomers wishing to plan a night’s observing or even drive their telescopes to observing targets,
or simply as a curiosity (it’s fun!). Because of the high quality of the graphics that Stellarium produces, it is
used in some real planetarium projector products and museum projection setups. Some amateur astronomy
groups use it to create sky maps for describing regions of the sky in articles for newsletters and magazines,
and the exchangeable sky cultures feature invites its use in the field of Cultural Astronomy research and
outreach.
Stellarium is under continuous development, and by the time you read this guide, a newer version may
have been released with even more features than those documented here. Check for updates to Stellarium at
the Stellarium website
1
.
If you have questions and/or comments about this guide, or about Stellarium itself, visit the Stellarium
site at GitHub
2
or our Google Groups forum
3
.
1.1 Historical notes
Fabien Chéreau started the project during the summer 2000, and throughout the years found continuous
support by a small team of enthusiastic developers.
Here is a list of past and present major contributors sorted roughly by date of arrival on the project:
1
https://stellarium.org
2
https://github.com/Stellarium/stellarium
3
https://groups.google.com/forum/#!forum/stellarium
4 Chapter 1. Introduction
Fabien Chéreau original creator, maintainer, general development
Matthew Gates maintainer, original user guide, user support, general development
Johannes Gajdosik astronomical computations, large star catalogs support
Johan Meuris GUI design, website creation, drawings of our 88 Western constellations
Nigel Kerr Mac OS X port (now macOS)
Rob Spearman funding for planetarium support
Barry Gerdes
user support, tester, Windows support. Barry passed away in October 2014 at age 80. He was
a major contributor on the forums, wiki pages and mailing list where his good will and enthusiasm is
strongly missed. RIP Barry.
Timothy Reaves ocular plugin
Bogdan Marinov GUI, telescope control, other plugins
Diego Marcos SVMT plugin
Guillaume Chéreau display, optimization, Qt upgrades, HiPS surveys
Alexander Wolf maintainer, DSO catalogs, AstroCalc module, user guide, general development
Georg Zotti
astronomical computations, Scenery 3D plugin, ArchaeoLines and Calendars plugins, general
development, user guide, user support
Marcos Cardinot MeteorShowers plugin
Florian Schaukowitsch
Scenery 3D plugin, Remote Control plugin, RemoteSync plugin, OBJ rendering,
Qt/OpenGL internals
Teresa Huertas Roldán Planetary nomenclature
Jocelyn Girod Observing Lists
Ruslan Kabatsayev ShowMySky Skylight model (based on Bruneton’s model)
Worachate Boonplod Eclipse computations
Unfortunately time is evolving, and most members of the original development team are no longer able
to devote most of their spare time to the project (some are still available for limited work which requires
specific knowledge about the project).
As of 2017, the project’s maintainer is Alexander Wolf, doing most maintenance and regular releases.
He has also introduced the AstroCalc module. Other new features are contributed mostly by Georg Zotti and
his team focusing on extensions of Stellarium’s applicability in the fields of historical and cultural astronomy
research (which means Stellarium is getting more accurate) and outreach (making it usable for museum
installations), but also on graphic items like comet tails, light pollution artwork or the Zodiacal Light.
A detailed track of development can be found in the
ChangeLog
file in the installation folder. A few
important milestones for the project:
2000 first lines of code for the project
2001-06
first public mention (and user feedbacks!) of the software on a French amateur astronomy news-
group
4
2003-01 Stellarium reviewed by Astronomy magazine
2003-07 funding for developing planetarium features (fisheye projection and other features)
2005-12 use accurate (and fast) planetary model
2006-05 Stellarium “Project Of the Month” on SourceForge
2006-08 large stars catalogs
2007-01 funding by ESO for development of professional astronomy extensions (VirGO)
2007-04 developers’ meeting near Munich, Germany
2007-05 switch to the Qt4 library as main GUI and general purpose library
2009-09 plugin system, enabling a lot of new development
2010-07 Stellarium ported on Maemo mobile device
2010-11 artificial satellites plugin
2014-06 high quality satellites and Saturn rings shadows, normal mapping for moon craters
2014-07
v0.13.0: adapt to OpenGL evolutions in the Qt5 framework, now requires more modern graphic
hardware than earlier versions
2015-04 v0.13.3: Scenery 3D plugin
2015-10 v0.14.0: Accurate precession
2016-07 v0.15.0: Remote Control plugin
2016-12 v0.15.1: DE430&DE431, AstroCalc, DSS layer, and Stellarium acting as SpoutSender
4
https://groups.google.com/d/topic/fr.sci.astronomie.amateur/OT7K8yogRlI/discussion
1.2 Version Numbers 5
2017-06 v0.16.0: Remote Sync plugin, polygonal OBJ models for minor bodies, RTS2 telescope support
2017-09 v0.16.1: Standard and extended DSO catalog, new subcatalogues for DSO
2017-12 v0.17.0: Nomenclature labels for planets and moons, INDI telescope support
2018-03 v0.18.0: Multiple image surveys
2019-12 v0.19.3: ASCOM telescope support
2020-09 v0.20.3: Accurate seasons’ beginnings
2021-03 v0.21.0: Accurate planet rotation (Libration, central meridians, subsolar points, . . .)
2021-09 v0.21.2: Annual aberration, DE440&441. Accuracy goals reached.
2022-10 Stellarium 1.0: Switch to Qt6, ShowMySky skylight model, Eclipse details.
2025-03 v25.1: New star catalog, parallax and revolving binary stars, new Skyculture file format.
1.2 Version Numbers
Since its inception, Stellarium’s version number had started with 0 to indicate “work in progress”. The
numbers after that have followed a year.release convention with approximately seasonal releases since 2018.
(For example, 0.18.2 was the third release in 2018 which appeared around autumn equinox, after 0.18.0 and
0.18.1.) If needed urgently, there can be additional releases which however break the simple season count.
A software version number of 1.0 signifies a milestone of some sort, like completion of a particular
original feature set, usability, or stability. With the completion of the original accuracy issues in 2021 we felt
it was time to finally change version number to 1. However, a major technical update in the underlying Qt
framework also forced some technical changes upon us to ensure Stellarium will remain working in the later
2020s, and therefore we decided to base the 1.* series on the new version of Qt.
Qt6 does not support old hardware, particularly 32-bit systems will not be able to run 1.* versions.
Therefore, we are going to keep both series alive for those with older hardware. Thanks to only minor
differences in the underlying frameworks, both series should retain feature equivalence. The only notable
difference for now lied in the Scripting functionality (see chapter 17). Our “internal” version numbers
therefore indicated which version of Qt was used: series 0.* continued to be based on Qt5, and series 1.*
was based on Qt6.
In 2023 we’ve changed the numbering scheme again to avoid new misunderstandings. Our “internal”
version has a standard of 3 components
5
, where the first indicates the two last digits of the year of release,
the second is the release within that year (0 is used before first release, from January to March) and the last
one can be 0 for releases, or the day number of the current year for snapshots. Our short (“public”) version
has 2 components: year and number of the release. Example: the first release in year 2023 has version 23.1.0
and short (public) version 23.1, the series has number 23.0.
In addition to the version number we are adding the name component
qtX
, where
X
is
5
or
6
respectively
and marks the major version of Qt which is used as the base for the package.
1.3 Acknowledgements
Stellarium has been kindly supported by ESA in their Summer of Code in Space initiatives, which so far
has resulted in better planetary rendering (2012), the Meteor Showers plugin (2013), the web-based remote
control and an alternative solution for planetary positions based on the DE430/DE431 ephemeris (2015), the
RemoteSync plugin and OBJ models (2016), and the planet nomenclature labels (2017). Some of Georg’s
work of 2015–2023 was supported by the Ludwig Boltzmann Institute for Archaeological Prospection and
Virtual Archaeology, Vienna, Austria.
Stellarium receives funding on OpenCollective. We thank all our sponsors and backers who help us
maintaining the software and expanding it with yet more features to come.
1.4 Scientific use
Stellarium has gained wide popularity in the research areas of cultural astronomy. Please note limitations
of Stellarium mentioned in Appendix F. If you used Stellarium in scientific work, please cite our overview
paper (Zotti, S. Hoffmann, et al., 2021) or those mentioned in the respective feature descriptions.
5
On Windows it has 4 components, where the last one is always 0.
6 Chapter 1. Introduction
1.5 About this User Guide
This guide is based on the user guide written by Matthew Gates for version 0.10 around 2008. The guide
was then ported to the Stellarium wiki and continuously updated by Barry Gerdes and Alexander Wolf up to
version 0.12. Unfortunately, some new features were not properly documented in the wiki, and generally,
without Barry the wiki started to fall out of sync with the actual program. In late 2015 we (Alexander and
Georg) started porting the texts back to L
A
T
E
X and updated and added information where necessary, or wrote
new chapters for the features which were introduced in the last years. We feel that a single book is the better
format for offline reading. The PDF version of this guide has a clickable table of contents and clickable
hyperlinks.
These new editions of the Guide (since v0.15) do not contain notes about using earlier versions than 0.13
or using very outdated hardware. Some references to previous versions may still be made for completeness,
but if you are using earlier versions of Stellarium for particular reasons, please use the older guides.
2. Getting Started
2.1 System Requirements
Stellarium has been seen to run on most systems where Qt5 is available, from tiny ARM computers like the
Raspberry Pi 2/3/4 or Odroid C1 to big museum installations with multiple projectors and planetaria with
fish-eye projectors. The most important hardware requirement is a contemporary graphics subsystem.
2.1.1 Minimum
•
Linux/Unix; Windows 7 and later; macOS 10.15 and later
1
•
3D graphics capabilities which support OpenGL 3.0 (2008 GeForce 8xxx and later, ATI/AMD Radeon
HD-2xxx and later; Intel HD graphics (Core-i 2xxx and later)) or OpenGL ES 2.0 (e.g., ARM SBCs
like Raspberry Pi 2/3/4). On Windows, some older cards may be supported via ANGLE when they
support DirectX9.
•
Screen resolution 1024× 768
2
•
512 MB RAM
•
250 MB free on disk
•
Keyboard
2.1.2 Recommended
•
Linux/Unix; Windows 10 and later; macOS 11.0 and later
•
3D graphics card which supports OpenGL 3.3 or higher
•
FullHD (1920× 1080 or 1920× 1200) or larger screen.
3
•
1 GB RAM or more
•
1.5 GB free on disk (About 3GB extra required for the optional DE430/DE431 files).
•
Keyboard and mouse or equivalent device (e.g. touchpad)
•
A dark room for realistic rendering — details like the Milky Way, Zodiacal Light or star twinkling
can’t be seen in a bright room.
1
Windows 10 and macOS 11.0 is minimal for Qt6-based Stellarium.
2
On Linux, an 800 × 600 screen can still be used by scaling the desktop e.g. to 1200 × 900:
xrandr --output HDMI -1 -- scale 1.5 x1 .5
To reset after running Stellarium, run
xrandr --output HDMI -1 -- scale 1 x1
3
HiDPI screens may work, but show occasional platform-dependent issues.
8 Chapter 2. Getting Started
2.2 Downloading
Download the correct package for your operating system directly from the main page,
https://stellarium.org
. An archive of all available versions is available at our GitHub page —
https://github.com/Stellarium/stellarium/releases.
2.3 Installation
2.3.1 Windows
1. Double click on the installer file you downloaded:
•
stellarium-26.2-qt6-win64.exe for 64-bit Windows 10 and later.
•
stellarium-26.2-qt6-arm64.exe for Windows 10 and later on ARM64 device.
•
stellarium-26.2-qt5-win64.exe for 64-bit Windows 7 and later.
2. Follow the on-screen instructions.
2.3.1.1 Unattended Install/Uninstall
The installation program allows for unattended installation (e.g., for lab setups) following official documen-
tation
4
.
You can uninstall the program like any other program from the Applications list in the system control
panel. The uninstaller asks if you want to remove (delete) all your Stellarium user data. Be sure to answer
NO when you plan to re-use landscapes, 3D sceneries and the like. For unattended uninstallation in larger
setups, also the uninstaller can be called with additional options, which will keep the user data.
"C :\ Progra m Files [ ( x86 )]\ S t e llarium \ unins00 0 . exe " / VE R Y S I LENT / SUP P R E S S M S G B O XES
2.3.2 macOS
1.
Locate the downloaded
Stellarium
file in Finder (Stellarium will be automatic unpack from archive
by operating system after downloading).
2. Drag Stellarium to the Applications folder.
2.3.3 Linux
Check if your distribution has a package for Stellarium already — if so you’re probably best off using it. If
not, you can download and build the source.
For Ubuntu Linux we provide a package repository with the latest stable releases. Open a terminal and
type:
sudo add - apt - reposi tor y ppa : stel lar ium / stellarium - rele ases
sudo apt - get update
sudo apt - get install s tel lar ium
You can also download and run universal binary packages for linux systems: flat
5
or snap
6
.
2.3.3.1 Raspberry Pi 2/3/4
These tiny ARM-based computers are very popular for small and energy-efficient applications like controlling
push-to Dobsonians. Stellarium requires Mesa 17 or later, available in the current Raspbian OS. To set up a
Raspberry Pi 2 or 3 with Raspbian Buster for use with Stellarium, activate the OpenGL driver in raspi-config.
The latest Raspberry Pi 4 comes with this driver by default and can even drive two HiDPI screens.
You must build Stellarium from sources. Please follow instructions from the wiki
7
.
For Ubuntu 16.04 LTS, follow instructions
8
.
Note that as of December 2019 the 3D planets do not work on Raspberry Pi 2/3, and DSS or HiPS
surveys seem to cause issues after a while.
4
https://documentation.help/Inno-Setup/topic_setupcmdline.htm
5
https://flathub.org/apps/details/org.stellarium.Stellarium
6
https://snapcraft.io/stellarium-daily
7
https://github.com/Stellarium/stellarium/wiki/Raspberry-Pi
8
https://ubuntu-mate.community/t/tutorial-activate-opengl-driver-for-ubuntu-mate-16-0
4/7094
2.4 Running Stellarium 9
2.3.4 *BSD/Solaris/OpenIndiana
Check if your operating system has a package or port for Stellarium already — if so you’re probably best off
using it. If not, you can download and build the source.
2.3.5 Haiku
Please use HaikuDepot or open Terminal and type:
pkgman install stellarium
to install the Stellarium.
2.4 Running Stellarium
2.4.1 Windows
The Stellarium installer creates a whole list of items in the Start Menu under the Programs/Stellarium
section. The list evolves over time, not all entries listed here may be installed on your system. Select one of
these to run Stellarium:
Stellarium
OpenGL version. This is the most efficient for modern PCs and should be used when you
have installed appropriate OpenGL drivers. Note that some graphics cards are “blacklisted” by Qt
to immediately run via ANGLE (Direct3D), you cannot force OpenGL in this case. This should not
bother you.
Stellarium (ANGLE mode)
Uses Direct3D translation of the OpenGL rendering via ANGLE library.
Forces Direct3D version 9.
9
Stellarium (ANGLE WARP mode)
Uses DirectX3D 11 software rendering via ANGLE library. This
should work on any PC without dedicated graphics card.
9
Stellarium (MESA mode)
Uses software rendering via MESA library. This should work on any PC without
dedicated graphics card.
Stellarium (200%)
On some systems with 4k screens, Stellarium appears too small. This link forces an
upscaling.
If for some reason Stellarium’s dialogs and buttons appear too large, and you want to scale them
down, edit the link and change the scaling parameter.
On startup, a diagnostic check is performed to test whether the graphics hardware is capable of running. If
all is fine, you will see nothing of it. Else you may see an error panel informing you that your computer
is not capable of running Stellarium (“No OpenGL 2 found”), or a warning that there is only OpenGL 2.1
support. The latter means you will be able to see some graphics, but depending on the type of issue you will
have some bad graphics. For example, on an Intel GMA4500 there is only a minor issue in Night Mode,
while on other systems we had reports of missing planets or even crashes as soon as a planet comes into
view. If you see this, try running in Direct3D 9 or MESA mode, or upgrade your system. The warning, once
ignored, will not show again.
When you have found a mode that works on your system, you can delete the other links.
2.4.2 macOS
Double click on the Stellarium application. Add it to your Dock for quick access.
2.4.3 Linux
If your distribution had a package you’ll probably already have an item in the GNOME or KDE application
menus. If not, just open a terminal and type stellarium.
2.4.4 *BSD/Solaris/OpenIndiana
If your operating system had a package or port you’ll probably already have an item in the GNOME or
KDE application menus. If not, just open a terminal and type stellarium.
2.4.5 Haiku
If you had installed a package you’ll already have an item in the Applications menus.
9
Stellarium series 0.* and Qt5-based builds only
10 Chapter 2. Getting Started
2.5 Script Launch
Stellarium can be automated in the sense that a sequence of commands can be executed written in a variant
of JavaScript. (See chapter 17.)
Stellarium scripting files use the filename extension
.ssc
and are registered during installation so that
usually a double click in your file explorer should start Stellarium and run this script. If you want to run a
script whenever you start Stellarium, add your commands into a script
startup.ssc
. To run an arbitrary
script from the command line, see section 6.1.
2.6 Troubleshooting
Stellarium writes startup and other diagnostic messages into a logfile. Please see section 5.3 where this file is
located on your system. This file is essential in case when you feel you need to report a problem with your
system which has not been found before.
At startup also a few pop-up windows may appear with information about possible troubles or warnings
to make those messages more visible for users.
On some Intel UHD systems users may see the screen blanking when Stellarium is working — the
startup of the program with --single-buffer parameter can help here. The same option also helps when on an
Nvidia system tooltips don’t appear in fullscreen mode.
On some older or weak systems, the option --low-graphics may be required. This forcefully disables
advanced graphics features of OpenGL 3.3 which otherwise would slow down or cause other issues on such
systems.
If you don’t succeed in running Stellarium, please see the online forum
10
. It includes FAQ (Frequently
Asked Questions, also Frequently Answered Questions) and a general question section which may include
further hints. Please make sure you have read and understood the FAQ before asking the same questions
again.
10
https://github.com/Stellarium/stellarium
3. A First Tour
Figure 3.1: Stellarium main view. (Combination of day and night views.)
When Stellarium first starts, we see a green meadow under a sky. Depending on the time of day, it is either
a day or night scene. If you are connected to the Internet, an automatic lookup will attempt to detect your
approximate position.
1
At the bottom left of the screen, you can see the status bar. This shows the current observer location,
vertical field of view (FOV), graphics performance in frames per second (FPS) and the current simulation
date and time. If you move the mouse over the status bar, it will move up to reveal a tool bar which gives
quick control over the program.
The rest of the view is devoted to rendering a realistic scene including a panoramic landscape and the
sky. If the simulation time and observer location are such that it is night time, you will see stars, planets and
1
See section 4.2 if you want to switch this off.
12 Chapter 3. A First Tour
the moon in the sky, all in the correct positions.
You can drag with the mouse on the sky to look around or use the cursor keys. You can zoom with the
mouse wheel or the
Page
or
Page
keys.
Much of Stellarium can be controlled very intuitively with the mouse. Many settings can additionally be
switched with shortcut keys (hotkeys). Advanced users will learn to use these shortcut keys. Sometimes
a key combination will be used. For example, you can quit Stellarium by pressing
Ctrl
+
Q
on Windows
and Linux, and
+
Q
on macOS. For simplicity, we will show only the Windows/Linux version. We
will present the default hotkeys in this guide. However, almost all hotkeys can be reconfigured to match
your taste. Note that some listed shortkeys are only available as key combinations on international keyboard
layouts, e.g., keys which require pressing
AltGr
on a German keyboard. These must be reconfigured, please
see 4.8 for details.
The way Stellarium is shown on the screen is primarily governed by the menus. These are accessed by
dragging the mouse to the left or bottom edge of the screen, where the menus will slide out. In case you
want to see the menu bars permanently, you can press the small buttons right in the lower left corner to keep
them visible.
3.1 Time Travel
When Stellarium starts up, it sets its clock to the same time and date as the system clock. However,
Stellarium’s clock is not fixed to the same time and date as the system clock, or indeed to the same speed.
We may tell Stellarium to change how fast time should pass, and even make time go backwards! So the
first thing we shall do is to travel into the future! Let’s take a look at the time control buttons on the right
hand ride of the tool-bar. If you hover the mouse cursor over the buttons, a short description of the button’s
purpose and keyboard shortcut will appear.
Button Shortcut key Description
J
Decrease the rate at which time passes
K
Make time pass as normal
L
Increase the rate at which time passes
8
Return to the current time & date
Table 3.1: Time Travel
OK, so lets go see the future! Click the mouse once on the increase time speed button . Not a
whole lot seems to happen. However, take a look at the clock in the status bar. You should see the time going
by faster than a normal clock! Click the button a second time. Now the time is going by faster than before. If
it’s night time, you might also notice that the stars have started to move slightly across the sky. If it’s daytime
you might be able to see the sun moving (but it’s less apparent than the movement of the stars). Increase the
rate at which time passes again by clicking on the button a third time. Now time is really flying!
Let time move on at this fast speed for a little while. Notice how the stars move across the sky. If you
wait a little while, you’ll see the Sun rising and setting. It’s a bit like a time-lapse movie.
Stellarium not only allows for moving forward through time – you can go backwards too! Click on the
real time speed button . The stars and/or the Sun should stop scooting across the sky. Now press the
decrease time speed button once. Look at the clock. Time has stopped. Click the decrease time speed
button four or five more times. Now we’re falling back through time at quite a rate (about one day every ten
seconds!).
3.2 Moving Around the Sky 13
Time Dragging, Time Scrolling
Another way to quickly change time is time dragging. Press
Ctrl
, press the left mouse button, and slide the
mouse along the direction of daily motion to go forward, or to the other direction to go backward.
Similarly, pressing
Ctrl
and scrolling the mouse wheel will advance time by minutes, pressing
Ctrl
+
and scrolling the mouse wheel will advance time by hours,
Ctrl
+
Alt
by days, and finally
Ctrl
+
+
Alt
by calendar years.
Enough time travel for now. Wait until it’s night time, and then click the real time speed button . If
all works as intended you will now be looking at the night sky.
3.2 Moving Around the Sky
Key Description
Cursor keys Pan the view left, right, up and down
Page
/
Page
,
Ctrl
+
/
Ctrl
+
Zoom in and out
Left mouse button Select an object in the sky
Right mouse button,
Ctrl
+
Clear selected object
Centre mouse button (wheel press) Centre selected object and start tracking
Mouse wheel Zoom in and out
Centre view on selected object
Forward-slash (
/
) Auto-zoom in to selected object
Backslash (
\
) Auto-zoom out to original field of view
+
N
Look towards North (keep altitude)
+
E
Look towards East (keep altitude)
+
S
Look towards South (keep altitude)
+
W
Look towards West (keep altitude)
+
Z
Look towards Zenith (south down)
Alt
+
+
N
Look towards North Celestial Pole
Alt
+
+
S
Look towards South Celestial Pole
Table 3.2: Moving Around the Sky
As well as travelling through time, Stellarium lets you look around the sky freely, and zoom in and out.
There are several ways to accomplish this, listed in table 3.2.
Let’s try it. Use the cursors to move around left, right, up and down. Zoom in a little using the
Page
key, and back out again using the
Page
. Press the
\
key and see how Stellarium returns to the original
field of view (how “zoomed in” the view is), and direction of view.
If you prefer stepwise zooming to fixed values for field of view, table 3.3 lists the keys to reach a certain
field of view.
Most users prefer to move around using the mouse. If you left-click and drag somewhere on the sky, you
can pull the view around.
Hotkey Field of view Hotkey Field of view
Ctrl
+
Alt
+
1
180°
Ctrl
+
Alt
+
6
10°
Ctrl
+
Alt
+
2
90°
Ctrl
+
Alt
+
7
5°
Ctrl
+
Alt
+
3
60°
Ctrl
+
Alt
+
8
2°
Ctrl
+
Alt
+
4
45°
Ctrl
+
Alt
+
9
1°
Ctrl
+
Alt
+
5
20°
Ctrl
+
Alt
+
0
0.5°
Table 3.3: Hotkeys to set fixed vertical fields of view
14 Chapter 3. A First Tour
Another method of moving is to select some object in the sky (left-click on the object), and press the
Space
key to centre the view on that object. Similarly, selecting an object and pressing the forward-slash
key
/
will centre on the object and zoom right in on it.
The forward-slash
/
and backslash
\
keys auto-zoom in and out to different zoom levels depending
on what is selected. If the object selected is a planet or moon in a sub-system with a lot of moons (e.g.
Jupiter), the initial zoom in will go to an intermediate level where the whole sub-system should be visible.
A second zoom will go to the full zoom level on the selected object. Similarly, if you are fully zoomed in
on a moon of Jupiter, the first auto-zoom out will go to the sub-system zoom level. Subsequent auto-zoom
out will fully zoom out and return the initial direction of view. For objects that are not part of a sub-system,
the initial auto-zoom in will zoom right in on the selected object (the exact field of view depending on the
size/type of the selected object), and the initial auto-zoom out will return to the initial FOV and direction of
view.
If you have a touch screen, you can even use one finger directly to drag the sky around and select objects,
and two fingers to zoom. The support for touch screens is incomplete though, and more advanced use of the
program requires the classical operation with keyboard and mouse.
3.3 The Main Tool Bar
Figure 3.2: Night scene with constellation artwork and moon.
Stellarium can do a whole lot more than just draw the stars. Figure 3.2 shows some of Stellarium’s visual
effects including constellation line and boundary drawing, constellation art, planet hints, and atmospheric
halo around the bright Moon. The controls in the main tool bar provide a mechanism for turning on and off
the visual effects.
When the mouse is moved to the bottom left of the screen, a second tool bar becomes visible. All the
buttons in this side tool bar open and close dialog boxes which contain controls for further configuration of
the program. The dialogs will be described in the next chapter.
Table 3.4 describes the operations of buttons on the main tool bar and the side tool bar, and gives their
default keyboard shortcuts.
3.3 The Main Tool Bar 15
Feature Button Hotkey Description
Constellations
C
Draw constellations as “stick figures”
Constellation Names
V
Draw name of the constellations
Constellation Art
R
Superimpose artistic representations of
the constellations
Constellation Boundaries
2
B
Draw boundaries of the constellations
Asterisms
2
C
Draw asterism “stick figures”
Asterism Names
2
V
Draw name of the asterisms
Equatorial Grid
E
Draw grid lines for the equatorial coor-
dinate system of date (RA/Dec)
Azimuth Grid
Z
Draw grid lines for the horizontal coor-
dinate system (Alt/Azi)
Galactic Grid
2
Draw grid lines for the galactic coordi-
nate system (Long/Lat)
Equatorial J2000 Grid
2
Draw grid lines for the equatorial
coordinate system at standard epoch
J2000.0 (RA/Dec)
Ecliptic Grid
2
Draw grid lines for the ecliptic coordi-
nate system of date (Long/Lat)
Toggle Ground
G
Toggle drawing of the ground. Turn
this off to see objects that are below the
horizon.
Toggle Cardinal Points
Q
Toggle marking of the North, South,
East and West points on the horizon.
Toggle Compass Marks
2
+
Q
Toggle degree marks along the horizon.
Toggle Atmosphere
A
Toggle atmospheric effects. Most no-
tably makes the stars visible in the day-
time.
Deep-Sky Objects
D
Toggle marking the positions of Deep-
Sky Objects.
Planet Hints
P
Toggle indicators to show the position
of planets.
Nebula images
2
I
Toggle “nebula images”.
Digitized Sky Survey
2
Toggle “Digitized Sky Survey”
(TOAST).
Hierarchical Progressive
Surveys
2
Ctrl
+
Alt
+
D
Toggle “Hierarchical Progressive Sur-
veys”.
Coordinate System
Ctrl
+
M
Toggle between horizontal (Alt/Azi)
& equatorial (RA/Dec) coordinate sys-
tems.
2
This button must be enabled first, see section 4.3.5
16 Chapter 3. A First Tour
Feature Button Hotkey Description
Center Center the view on the selected object
Night Mode
Ctrl
+
N
Toggle “night mode”, which applies a
red-only filter to the view to be easier
on the dark-adapted eye.
Full Screen Mode
F11
Toggle full screen mode.
Bookmarks
2
Alt
+
B
Toggle bookmarks window.
Flip view (horizontal)
2
Ctrl
+
+
H
Flip the image in the horizontal plane.
Flip view (vertical)
2
Ctrl
+
+
V
Flip the image in the vertical plane.
Quit Stellarium
Ctrl
+
Q
Close Stellarium.
Help Window
F1
Show the help window, with key bind-
ings and other useful information
Configuration Window
F2
Show the configuration window
Search Window
F3
or
Ctrl
+
F
Show the object search window
View Window
F4
Show the view window
Time Window
F5
Show the time window
Location Window
F6
Show the observer location window
(map)
AstroCalc Window
F10
Show the astronomical calculations
window
Table 3.4: Stellarium’s standard menu buttons. Those marked
2
must be
enabled first, see section 4.3.5.
3.4 Taking Screenshots
You can save what is on the screen to a file by pressing
Ctrl
+
S
. Screenshots are taken in PNG format,
and have filenames like
stellarium-000.png
,
stellarium-001.png
(the number increments to prevent
overwriting existing files).
The screenshots are stored to a directory depending on your operating system, see section 5.1 Files and
Directories. See also section 4.3.5 for more screenshot options.
3.5 Observing Lists (Bookmarks)
You can store your favourite objects or views in observing lists. Press
Alt
+
B
or to call up the
dialog. A bookmarks file from previous versions will be imported and converted to the new format. You can
however create an arbitrary number of lists.
The list display shows all entries from the current list. A double click on an entry selects the object.
To add/remove an object to/from the list, press
Edit list
. This changes the view. Highlight (select) your
object in the sky and press
Add object
. To remove an object from a list, select its entry in the list and press
Remove object
.
3.6 Custom Markers 17
Sometimes storing the object alone is not enough. Interesting views like planet conjunctions or eclipses
require at least a time entry, if not a particular location. Likewise, the displayed landscape may be nice to
restore. Additionally, the field of view may be relevant. To store these data and later retrieve them, use the
respective checkboxes.
You can also export the current list or all lists with the according button, or import such an exported list
on another system. To export the current list, keep the default
.sol
file type in the filename dialog. To export
all your lists, use the
.ol
file type in the filename dialog. Lists are identified with an Universally Unique
Identifier (UUID) which we call OLUD (Observing List Unique Identifier). On importing a list, existing lists
with the same OLUD may be replaced after a warning. During editing, storing a list with an existing name is
prevented. The list import may however import a list with an existing name as long as the OLUD is different.
You may want to change one of the duplicate list names after import. To transfer all your lists to another
system, export them as
.ol
file, or copy, rename and import (or just copy, to replace the existing) the full file
observingLists.json from the data/ subdirectory of your user directory (see section 5.1).
3.6 Custom Markers
You can set temporary markers anywhere in the screen. These may be useful for various purposes but cannot
be stored.
Actions Description
Shift
& left click Add custom marker
Shift
& right click Delete the one closest marker to mouse cursor
Alt
+
& right click Delete all custom markers
3.7 Copy Information
If you have selected an object and want to use the displayed information elsewhere, you may want to copy
it to the system clipboard with
Ctrl
+
+
C
. In case you want to use its numbers elsewhere, please see
Appendix F for known accuracy limitations.
3.8 Speech Output
Sometimes you may have dimmed down your field laptop or the font may be too small. Object information
v 25.4
can also be output audibly by a Text-to-Speech engine. After object selection, press
Shift
+
R
to let a voice
read ot to you. See section 4.3.6 for details and configuration.
4. The User Interface
This chapter describes the dialog windows which can be accessed from the left menu bar.
Most of Stellarium’s settings can be changed using the view window (press or
F4
) and the
configuration window (
or
F2
). Most settings have short labels. To learn more about some settings,
more information is available as tooltips, small text boxes which appear when you hover the mouse cursor
over a button.
1
You can drag the windows around, and the position will be used again when you restart Stellarium. If
this would mean the window is off-screen (because you start in windowed mode, or with a different screen),
the window will be moved so that at least a part is visible.
Some options are really rarely changed and therefore may only be configured by editing the configuration
file. See 5.4 The Main Configuration File for more details.
4.1 Setting the Date and Time
Figure 4.1: Date and Time dialog
In addition to the time rate control buttons on the main toolbar, you can use the date and time window
(open with the button or
F5
) to set the simulation time. The values for year, month, day, hour, minutes
and seconds may be modified by typing new values, by clicking the up and down arrows above and below
the values, and by using the mouse wheel.
The other tab in this window allows you to see or set Julian Day and/or Modified Julian Day numbers
(see 18.4.2).
20 Chapter 4. The User Interface
Figure 4.2: Location window
4.2 Setting Your Location
The positions of the stars in the sky is dependent on your location on Earth (or other planet) as well as the
time and date. For Stellarium to show accurately what is (or will be/was) in the sky, you must tell it where
you are. You only need to do this once – Stellarium can save your location so you won’t need to set it again
until you move.
After installation, Stellarium uses an online service which tries to find your approximate location based
on the IP address you are using. This seems very practical, but if you feel this causes privacy issues, you
may want to switch this feature off. You should also consider switching it off on a computer which does not
move, to save network bandwidth.
To set your location more accurately, or if the lookup service fails, press
F6
to open the location window
(Fig. 4.2). There are a few ways you can set your location in this dialog:
1. Just click on the map.
2.
Search for a city where you live using the search edit box at the top right of the window, and select
the right city from the list.
3.
Click on the map to filter the list of cities in the vicinity of your click, then choose from the shortlist.
4. Enter a new location using the longitude, latitude and other data.
5.
Click on
Get Location from GPS
if you have a GPS receiver. You activate a periodic request for GPS
fixes. After a few seconds, the button should change color and give a textual feedback. Green indicates
a good location fix, yellow indicates a 2D-fix only, which means altitudes are not available. (Leave the
GPS device running for a few minutes and/or search a place with better sky view.) You could leave it
running if you are operating a fast-moving observatory platform, but rather switch it off when you see
a good fix, so that other programs can use the serial GPS connection. Red signals an error, and further
positions are not retrieved but the button is reset. You may press the button again to start over.
Sometimes you have to try several times or let it run for a while to get a green button indicating a
valid 3D fix including altitude. See section 5.5.4 for configuration details.
On Windows, if there is no GPS device, a system location service will be queried as fallback.v 1.0
If you want to use the current location permanently, click on the “use as default” checkbox, disable “Get
location from Network”, and close the location window.
Two settings may influence the landscape when changing locations:
Auto select landscapes
When changing the planet, a fitting landscape panorama will be shown when
available. Also, when clicking on the earth map, a zero-altitude landscape is displayed in the
v 23.2
1
Unfortunately, on Windows 7 and later, with some Nvidia and AMD GPUs in OpenGL mode, these tooltips
sometimes do not work. Sometimes it is enough to leave fullscreen mode to see them.
4.3 The Configuration Window 21
approximate color of that location (taken from the map).
Auto-enable atmosphere
When changing planet during location change, the atmosphere will be switched
as required.
As a reverse functionality, loading landscapes may also change location. See section 4.4.5.
4.2.1 Time Zones
Locations in Stellarium’s location database include their respective time zone. When you click on a location
in the list, the time should be shown in the respective time zone. If daylight time rules exist and you have
selected “Enable daylight saving time”, also this abomination of modern civilisation is respected. Most users
will require to have this setting active.
When you select “Use custom time zone”, you can select other time zones. Those that start with UTC
have no daylight time rules.
Time zones were introduced in the 19th century, originally for purposes of railway traffic synchronization.
The first such action was taken in 1847, and therefore Stellarium by default will present Local Mean Solar
Time (LMST) for dates before 1847, and ignore all configured time zones unless you deliberately activate
“Use custom time zone”. The history of time zones and their rules is very complicated, though, and Stellarium
should not be expected to find the exact date when time zone use was introduced at a certain location or
country. Just be sure to use LMST when replaying historical observations before the 20th century.
For even earlier observations, you can also set Local True Solar Time (LTST), which is the time given
by sundials. Here, 12 o’clock is the time when the sun transits the meridian, strictly, daily. The difference
between LMST and LTST is called equation of time. See section 13.2 for more information.
When you click on the map to set your location, Stellarium has currently no way to guess the timezone of
the coordinate pair. In this case, Local Mean Solar Time is presented, which only depends on longitude and
was the “normal” time before the development of time zones. Either select a city from the list or manually
select a time zone.
4.2.2 Geographical Regions
The world is split into political entities called “countries”. Humans have an unappealing tendency of
fighting over the question to which country some territories should be counted. Stellarium is an astronomy
program which labels coordinates of locations like cities with a name. Earlier editions of Stellarium used
countries as further superordinate entities to locations for identification purposes. In consequence to much
unnecessary and unfriendly discussion we decided to completely drop the petty-minded assignment of
political country names to locations in favour of geographical regions. There is only one known habitable
planet, one humankind, and one sky. Stellarium users should overcome borders!
For the “region” classification of sky cultures we use the same regions (see 9.2.1), and we follow the
UN M49 geoscheme
2
with extensions for other planets.
4.2.3 Observers
In the list of Planets you can find entries called Solar System Observer, Jupiter Observer and similar for
each major planet that has moons: Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. These are specialized
locations. When switching to them, you will find yourself looking onto the respective observed object (Sun,
Jupiter, . . . ) from somewhat above the plane of the Solar system. By pressing
Alt
+
/
Alt
+
you can
rotate around a vertical axis through the observed object. Likewise, by pressing
Alt
+
/
Alt
+
you can
change the latitude of observation. Finally, with
Alt
+
Home
/
Alt
+
End
you can change the distance from
the observed object.
4.3 The Configuration Window
The configuration window contains general program settings, and many other settings which do not concern
specific display options. Press the tool button or
F2
to open.
4.3.1 The Main Tab
The Main tab in the configuration window (Fig. 4.3) provides control for changing the program language.
The next setting group allows to enable using DE430/DE431 and DE440/DE441 ephemeris files. These
files have to be installed separately. Most users do not require this. See section 5.5.3 if you are interested.
2
https://unstats.un.org/unsd/methodology/m49/
22 Chapter 4. The User Interface
Figure 4.3: Configuration Window: Main Tab
The tab also provides the buttons for saving the current view direction as default for the next startup, and
for saving the program configuration: most display settings have to be explicitly stored to make a setting
change permanent. If you prefer, you can activate
Immediate Save
. Then all settings changes will be stored
v 24.4
immediately and the program will use them the next time you launch it. Language and font settings have
to be stored explicitly with the buttons next to their settings to protect you from unwanted surprises. To
permanently set this mode, use
Save settings
a final time.
4.3.2 The Information Tab
Figure 4.4: Configuration Window: Information Tab
The Information tab (Fig. 4.4) allows you to set the type and amount of information displayed (left column)
or output by speech (right column; see 4.3.6) about a selected object. The Radio buttons on the top of the
v 25.4
dialog allow quick selection of some useful configurations for display.
4.3 The Configuration Window 23
4.3.3 The Extras Tab
Figure 4.5: Configuration Window: Extras Tab
The Extras tab (Fig. 4.5) allows you to customize information displayed about a selected object, download
more star catalogs and also allows to hide or show additional buttons in the lower button bar.
4.3.3.1 Customization of information displays
The information display can be tweaked a bit with the options found in the GUI section “Additional
information settings”.
Use mag/arcsecˆ2 for surface brightness instead of mag/arcminˆ2.
Short notation for units of surface brightness symbolic abbreviation.
Designations for celestial coordinate systems Use symbols like
α, δ instead of textual labels.
Tabular output for coordinates and time uses a more eye-friendly layout.
Use decimal degrees You can toggle usage of decimal degree format for coordinates.
Azimuth from South Some users may be used to counting azimuth from south.
Allow negative hour angles Count hour angles −12h. . . 12h instead of 0h. . . 24h. v 25.4
Polar distance, not declination Used by some telescopes. Using label p or PD instead of
δ. v 25.4
4.3.3.2 Customization of button visibility on bottom toolbar
If your screen is too narrow to show all buttons or you simply don’t need them because you prefer the
keyboard shortcuts, you can choose your optimal setup. The selection of buttons is stored immediately.
Constellation boundaries You can toggle display of constellation boundaries with this button.
Asterism lines You can toggle display of asterism lines with this button.
Asterism labels You can toggle display of asterism labels with this button.
Ecliptic grid You can toggle display of ecliptic coordinate grid with this button.
ICRS grid
You can toggle display of the International Coordinate Reference System (equatorial J2000
coordinate grid) with this button.
Galactic grid You can toggle display of galactic coordinate grid with this button.
Cardinal points You can toggle display of the “Cardinal points” button.
Compass marks You can toggle display of the “Compass marks” button.
Night mode You can toggle display of the nightmode button.
Centering button You can toggle display of the “Center on selected object” button.
Fullscreen button You can toggle display of the fullscreen button.
Quit button You can toggle display of the button to quit Stellarium.
Nebula background You can toggle display of DSO photographs with this button.
Flip buttons
When enabled, two buttons will be added to the main tool bar which allow the main view to
be mirrored in the vertical and horizontal directions. This is useful when observing through telecopes
which may cause the image to be mirrored.
24 Chapter 4. The User Interface
DSS survey You can toggle display of Digitized Sky Survey with this button (see section 10.4).
HiPS Surveys
You can toggle display of Hierarchical Progressive Surveys with this button (see section
4.4.7).
Bookmarks You can enable display of Bookmarks (Observing Lists) dialog with this button.
Use buttons background Applies a gray background under the buttons on the bottom bar.
4.3.3.3 Download more star catalogs
Stellarium comes with enough stars for casual stargazing with the unaided eye or binoculars. If you have a
telescope and want to see more stars, here you can download more catalogs. (See Appendix C)
4.3.4 The Time Tab
Figure 4.6: Configuration Window: Time Tab
The Time tab (Fig. 4.6) allows to specify what simulation time should be used when the program starts:
System date and time Stellarium will start with the simulation time equal to the operating system clock.
System date at
Stellarium will start with the same date as the operating system clock, but the time will be
fixed at the specified value. This is a useful setting for those people who use Stellarium during the day
to plan observing sessions for the upcoming evening.
Other some fixed time can be chosen which will be used every time Stellarium starts.
The middle field allows specify display formats for date and time on bottom toolbar:
JD Stellarium will display Julian Days (JD).
Date and time Stellarium will display date and time in selected format.
The lowest field allows selection of the correction model for the time correction
∆T
(see section 18.4.3).
Default is “Modified Espenak and Meeus (2006, 2014, 2023)”. Please use other values only if you know
what you are doing.
4.3.5 The Tools Tab
The Tools tab (Fig. 4.7) contains planetarium options (like enabling/disabling of keyboard shortcuts for
panning and zooming the main view) and options for screenshots.
Spheric mirror distortion
This option pre-warps the main view such that it may be projected onto a
spherical mirror using a projector. The resulting image will be reflected up from the spherical mirror
in such a way that it may shine onto a small planetarium dome (or even just the ceiling of your dining
room), making a cheap planetarium projection system.
Disc viewport
This option masks the main view producing the effect of a telescope eyepiece. It is also
useful when projecting Stellarium’s output with a fish-eye lens planetarium projector.
4.3 The Configuration Window 25
Figure 4.7: Configuration Window: Tools Tab
Gravity labels
This option makes labels of objects in the main view align with the nearest horizon. This
means that labels projected onto a dome are always aligned properly.
Auto zoom out returns to initial direction of view
When enabled, this option changes the behavior of the
zoom out key
\
so that it resets the initial direction of view in addition to the field of view.
Enable keyboard navigation
, i.e. moving the view with cursor keys. The tool button calls the keyboard
configuration panel. (See section 4.8.)
Enable mouse navigation , i.e. mouse dragging.
Enable mouse zooming use mouse wheel to zoom field of view.
Mouse cursor timeout
You can decide whether, and when, the mouse cursor should disappear from view
when not moved.
Include Topocentric coordinates
If you require planetocentric coordinates, you may switch this off.
Usually it should be enabled. (See 18.9.1)
Nutation
Compute the slight wobble of earth’s axis. This feature is active only about 500 years
around J2000.0.
Aberration
Add effect of annual aberration of light to the object’s position (see 18.10). Note:
This also influences the displayed position in the J2000 frame! For didactic purposes you can
exaggerate the effect by up to 5×.
Overwrite text color
— enabling this option will ignore the color settings for each celestial object and
enable one color for text on the info panel for all celestial objects. By default Stellarium uses white
color for this option, but you may re-define it through a color chooser.
Set keyboard focus to day input
— you may use this option to force setting the keyboard focus on the day
input field in the Date and Time dialog.
Important note: the focus in the sky will be lost when you open the Date and Time dialog after
enabling this option.
Use kinetic scrolling
Text fields in dialogs can either be moved on sidebar handles (with this switch
disabled) or by dragging the text itself (enabled), as it is known from touch-enabled devices like
smartphones.
Dithering options to allow select better simulation of sky on different hardware.
Indication for mount mode
You can activate the short display of a message when switching type of used
mount.
Info text color at daylight
— this is a color chooser for defining the text color for the info panel at daylight
to increase the contrast of the text. By default Stellarium use black color.
Multithreading
For every frame, the positions of all planets and minor bodies of the Solar system are computed. Most of the
other time between frame updates is needed for the actual frame drawing, and waiting for the next frame
26 Chapter 4. The User Interface
cycle if you have deliberately set a low frame rate (useful to conserve energy; see below). If you have many
thousands of solar system objects and a moderately new computer, you may feel that Stellarium becomes
slow (few frames/second) but see that mostly only one core of your CPU seems to be busy. You can try to
v 24.3
distribute the computation of solar system bodies to more CPU cores. But take note, thread synchronization
(combining all results ahead of drawing) takes its time, so it pays off only when your solar system is really
large. With more than 1000 objects, we recommend starting with 1 additional thread. Even with 25.000
objects, assigning more than 4 additional threads on a 20-core CPU does not show any further gain. Frame
drawing is still performed by the main thread, and too many objects still slow down the program. Just try out
what works best on your system.
Framerate intent
The pace of screen updates (frames per second, FPS) depends on several factors: CPU speed, graphics card
speed, screen size, number of displayed objects and grids, etc. As is common for interactive programs,
the main program thread runs on a single core also on a multicore system. For running Stellarium, a CPU
with few but fast cores will appear faster in total than a multicore system at slower CPU cycles. High-end
systems may deliver needlessly high framerates, at cost of energy consumption. The maximum FPS setting
limits the frame rate when Stellarium is interactively operated (zoomed, panned, settings switched, etc.)
After a few seconds, when Stellarium is not interactively operated, it falls back to a minimum FPS setting
to conserve energy. Of course, when the system cannot even reach this FPS, the factual FPS will be lower
and the system may be overloaded. Keep in mind that the minimum setting also applies to running scripts
(non-interactively).
Font size and font selection
You can change the font sizes for on-screen text and GUI dialogs separately. For some purposes like
presentations it may be helpful to enlarge screen font size while keeping GUI font regular, or vice versa. It
also depends on your screen size whether all the object info fits on screen. This may also depend on the
writing system and installed font. If you are using a non-Western character system and the default font
looks bad, you can select another system font. For this, edit
config.ini
(see chapter 5.1): locate the
[gui]
section and set the key
flag_font_selection=true
. On next start of Stellarium, you will find two
elements for font selection: one allows you to pre-select a writing system, the other will then allow selection
of a font installed in your system that includes the characters used in the selected writing system. When you
have found the best font, store your settings here or on the Main tab (see section 4.3.1), and you may edit
config.ini again to disable the font selection switches.
Screenshots
You can set the directory where screenshots will be stored, and also whether you want screenshots sized
like Stellarium’s window or some other, likely larger size. The maximum possible size depends on your
hardware.
4096× 4096
should be possible on most PCs, others may even create
16384× 16384
images. The
vertical field of view will be the same as in the current view.
You can also set the file format. The exact selection depends on platform and version of the underlying
Qt framework. Notable formats are PNG (lossless), JPG (lossy), JPEG (higher quality JPG), BMP (Windows
Bitmap), WEBP, TIF (LZW compressed), TIFF (uncompressed), PBM, PGM, PPM, XBM, XPM, and ICO
(thumbnails).
Some printing workflows require particular DPI (dots per inch) settings stored in the screenshots. You
can configure DPI which will be stored in the image metadata. The intended print size in
mm
is shown in
the tooltip of the dpi spinner.
4.3.6 The Speech Tab
The Speech tab (Fig. 4.8) allows configuring speech output.
3
You can select some speech engine, then
v 25.4
(hopefully) a list of voices for your user language becomes available from which you can choose. You can
influence pitch and speed (Rate) and balance volume against your system volume. Then test the content of
the text box with the
▶ Say
, or cut this off via
∎ Stop
.
Speech output is available for data of the currently selected object. In the Information tab (see 4.3.2), the
right checkbox colums let you select those information bits which should be output by voice. Most users
will keep coordinate readings off, but some physical or morphological data may be interesting to listen to.
The default hotkey for speech output is
Shift
+
R
. Pressing it another time will cut off narration.
3
This fully depends on capabilities of the operating system and is not available for builds/platforms with Qt version
less than 6.4.
4.4 The View Settings Window 27
Figure 4.8: Configuration Window: Speech Tab
Also the long texts in the Landscape (see 4.4.5) and Skyculture (4.4.6) tabs of the View Settings dialog
can be narrated with the
▶ Read text
/
∎ Stop
buttons near the respective text boxes.
4.3.7 The Scripts Tab
The Scripts tab (Fig. 4.9) allows the selection of pre-assembled scripts bundled with Stellarium that can be
run (See chapter 17 for an introduction to the scripting capabilities and language). This list can be expanded
with your own scripts as required. See section 5.2 where to store your own scripts.
When a script is selected it can be run by pressing the arrow button and stopped with the stop button.
With some scripts the stop button is inhibited until the script is finished.
Scripts that use sound or embedded videos will need a version of Stellarium configured at compile time
with multimedia support enabled. It must be pointed out here that sound or video codecs available depends
on the sound and video capabilities of you computer platform and may not work.
4.3.8 The Plugins Tab
Plugins (see chapter 12 for an introduction) can be enabled here (Fig. 4.10) to be loaded the next time you
start Stellarium. When loaded, many plugins allow additional configuration which is available by pressing
the
configure
button on this tab.
4.4 The View Settings Window
The View settings window controls many display features of Stellarium which are not available via the main
toolbar.
4.4.1 The Sky Tab
The Sky tab of the View window (Fig. 4.11) contains settings for changing the general appearance of the
main sky view and projections. Some highlights of sky field:
28 Chapter 4. The User Interface
Figure 4.9: Configuration Window: Scripts Tab
Figure 4.10: Configuration Window: Plugins Tab
4.4 The View Settings Window 29
Figure 4.11: View Settings Window: Sky Tab
Dynamic eye adaptation
When enabled this feature reduces the brightness of faint objects when a bright
object is in the field of view. This simulates how the eye can be dazzled by a bright object such as the
moon, making it harder to see faint stars and galaxies.
Light pollution
In urban and suburban areas, the sky is brightened by terrestrial light pollution reflected in
the atmosphere. Stellarium simulates light pollution and lets the user configure how bright the night
sky is. There are several ways to set it up:
Automatic from locations database
option makes Stellarium find sky brightness from its locations
database and simulate light pollution without any further user input.
Manual
mode lets the user choose the amount of light pollution by moving a slider. To make it easier
to orient in the resulting amount of light pollution, a tooltip will show the classification of the
sky according to the Bortle Dark Sky Scale (See Appendix B for more information), as well as
the naked-eye limiting magnitude.
Manual from SQM
mode lets one enter the reading of a Sky Quality Meter. Stellarium can accept it
in several units: physical (
cdm
2
,
mcdm
2
,
µcdm
2
) as well as astronomical,
magarcsec
2
. To
enter a value, first choose the unit, and then type the number into the spinbox.
Solar altitude for Twilight Finder
You can configure shortcut keys to go to the time when the sun reaches
this altitude below the mathematical horizon. See section 4.8.1.
Shooting stars
Stellarium has a simple meteor simulation option. This setting controls how many shooting
stars will be shown. Note that shooting stars are only visible when the time rate is 1, and might not
be visible at some times of the day. Meteor showers can be simulated using a dedicated plugin (see
section 14.6).
Some highlights of the stars field:
Absolute scale
is the size of stars as rendered by Stellarium. If you increase this value, all stars will appear
larger than before.
Relative scale
determines the difference in size of bright stars compared to faint stars. Values higher than
1.00 will make the brightest stars appear much larger than they do in the sky. This is useful for creating
star charts, or when learning the basic constellations.
Twinkle
controls how much the stars twinkle when atmosphere is enabled (scintillation, see section 19.13.2.1).
Since v0.15.0, the twinkling is reduced in higher altitudes, where the star light passes the atmosphere
in a steeper angle and is less distorted.
Limit magnitude
Inhibits automatic addition of fainter stars when zooming in. This may be helpful if you
are interested in naked eye stars only.
Labels and markers
you can independently change the amount of labels displayed for stars. The further to
the right the sliders are set, the more labels you will see. Note that more labels will also appear as you
zoom in.
Use designations for screen labels
— when this option is enabled you will see in the sky (on-screen labels)
only scientific designations (catalog numbers) of the stars instead of their common names. To
30 Chapter 4. The User Interface
customize the on-screen labels we added 3 additional options
4
— Dbl. stars, Var. stars and HIP
— which will show, in this sequence of preference, the first available occurrence of the traditional
designations of double stars, variable stars or HIP numbers, respectively.
4.4.1.1 The Projections field
Selecting items in this list changes the projection method which Stellarium uses to draw the sky (Snyder,
1987). Options are:
Perspective
Perspective projection maps the horizon and other great circles like equator, ecliptic, hour lines,
etc. into straight lines. The maximum field of view is 150°. The mathematical name for this projection
method is gnomonic projection.
Stereographic
Stereographic projection has been known since antiquity and was originally known as the
planisphere projection. It preserves the angles at which curves cross each other but it does not preserve
area. Else it is similar to fish-eye projection mode. The maximum field of view in this mode is 235°.
Fish-Eye
Stellarium draws the sky using azimuthal equidistant projection. In fish-eye projection, straight
lines become curves when they appear a large angular distance from the center of the field of view
(like the distortions seen with very wide angle camera lenses). This is more pronounced as the user
zooms out. The maximum field of view in this mode is 180°.
Orthographic
Orthographic projection is related to perspective projection, but the point of perspective is
set to an infinite distance. The maximum field of view is 180°.
Equal Area
The full name of this projection method is Lambert azimuthal equal-area projection. It
preserves the area but not the angle. The maximum field of view is 360°.
Hammer-Aitoff
The Hammer projection is an equal-area map projection, described by ERNST VON
HAMMER (1858–1925) in 1892 and directly inspired by the Aitoff projection. The maximum field of
view in this mode is 360°.
Mollweide
The Mollweide projection is a pseudocylindrical equal
-
area map projection, widely used for
whole
-
sky displays; it preserves relative areas across the sphere while trading off shape and angular
fidelity, especially near the poles. The maximum field of view in this mode is 360°.
Sinusoidal
The sinusoidal projection is a pseudocylindrical equal-area map projection, sometimes called
the Sanson–Flamsteed or the Mercator equal-area projection. Meridians are mapped to sine curves.
Mercator
Mercator projection is a cylindrical projection developed by GERARDUS MERCATOR (1512–
1594) which preserves the angles between objects, and the scale around an object is the same in all
directions. The poles are mapped to infinity. The maximum field of view in this mode is 233°.
Miller cylindrical
The Miller cylindrical projection is a modified Mercator projection, proposed by OS-
BORN MAITLAND MILLER (1897–1979) in 1942. The poles are no longer mapped to infinity.
Cylinder
The full name of this simple projection mode is cylindrical equidistant projection or Plate Carrée.
The maximum field of view in this mode is 233°.
Two more settings allow finetuning:
Vertical viewport offset
If you have a wide screen or like wide-angle views, you may feel that too much of
screen space lies below the horizon. This setting can shift the view up or down.
Custom FoV limit
Some projections allow very wide views, like 180° which covers a complete celestial
hemisphere (e.g. the entire skydome) or even more. In some cases like if you are running a planetarium,
you may want to limit the vertical field of view so that you won’t ever zoom out too far.
4.4.1.2 Atmosphere settings
An auxiliary dialog opens when you select and contains detail settings for the atmosphere. Here you can
choose visual model of atmosphere, set atmospheric pressure and temperature which influence refraction (see
section 19.13.2) and the opacity factor k
v
for extinction, magnitude loss per airmass (see section 19.13.1).
There are two visual models for the atmosphere available:
Preetham
This is the legacy model (see section 11.2.1), fallback for the cases when the other one doesn’t
work.
ShowMySky
This model is the more realistic visual model of the atmosphere colors (see section 11.2.2). It
relies on a precomputed dataset that can be chosen in the user interface after the ShowMySky model
is enabled.
4.4.2 The Solar System Objects (SSO) Tab
The Solar System Objects tab of the View window (Fig. 4.12) contains settings for changing the general
appearance of the view of Solar system objects. Some highlights:
4
These options are only used if the star does not have Bayer/Flamsted designations.
4.4 The View Settings Window 31
Figure 4.12: View Settings Window: SSO Tab
Simulate light speed
will give more precise positions for planetary bodies which move rapidly against
background stars (e.g. the moons of Jupiter).
Scale will increase the apparent size of the selected class of objects:
Moon
will increase the apparent size of the Moon in the sky, which can be nice for wide field of view
shots.
Dynamic (FOV-based) Moon size
When this option is enabled, the Moon’s display size is no
v 26.1
longer fixed, but interpolates smoothly between
1×
(natural size) and the scale factor set
above, depending on the current field of view (FOV).
Minor bodies
will increase the apparent size of minor bodies: planet satellites, all kinds of asteroids,
and comets. Forsome of these 3D models are available, which will be better discernible if
enlarged.
Sun
will increase the apparent size of the Sun in the sky, which can be nice for didactic purposes or
demonstrations.
Planets will increase the apparent size of major planets.
Mark minor bodies
Show a little circle at the location of every minor body (comet, asteroid, . . . ), down to
v 24.3
the configured visual magnitude. The marks are shown regardless of sky brightness, even in daytime.
Also, in this mode, markers for objects with highly outdated orbital elements are still plotted (see
13.10 and Appendix D.2.2). This is useful to show the distribution of asteroids and comets on the sky,
or especially when viewed from the Solar System Observer (see 4.2.3).
From the “Observer” viewpoints, the visual magnitude for minor bodies is computed as seen from the
Sun, so that objects in inferior conjunction ae not dimmed down and filtered away by effects of phase
angle, and comet tails are better visible.
Show orbits
adds a rendition of the orbit or trajectory of an SSO. For efficiency, orbits are not displayed
when the object is not inside the screen, unless you set the “permanently” option. You can further
fine-tune the selection and appearance (width and colors) of orbits with the additional settings.
Show trails plots the apparent path of SSO among the stars as seen from the current planet.
Show planetary nomenclature
displays positions and names of surface features officially named by the
IAU (See Appendix E). When the sun is below the horizon at the location of the feature, the label is
attenuated. A few special markers show Centre, North and South poles, east and west points along the
equator, and the subsolar point (where the sun is at the zenith as seen from that feature). Features like
craters are best visible when they are illuminated by a low sun. You can therefore limit the display to
v 1.2
items along the terminator (the border between light and dark on the surface). You can also mark
v 23.3
craters and lunar maria (the dark “seas”) with circles.
GRS details. . .
: The Great Red Spot (GRS) is slowly drifting along Jupiter’s System II coordinate system.
This button opens a new dialog in which you can adjust the longitude (Jupiter system II) and annual
32 Chapter 4. The User Interface
drift rate of this feature at a particular epoch. To help you, another button in this dialog opens a
website with relevant data. The central meridian data given in the object information on screen still
shows System II longitude.
Labels and markers
you can independently change the amount of labels displayed for Solar system objects.
The further to the right the sliders are set, the more labels you will see. Note that more labels will also
appear as you zoom in.
Planet magnitude algorithm
several ways to compute planet magnitudes have been made available from
the literature. Data by Müller (1893) provide visual magnitudes. The other models provide instrumen-
tal (Johnson V) magnitudes.
Earth shadow enlargement after Danjon
Earth’s shadow is enlarged by the atmosphere. You can select
whether the 2% enlargement used by the Astronomical Almanac should be applied (default), or the
formulation of DANJON (see section 19.11.2).
4.4.3 The Deep-Sky Objects (DSO) Tab
Deep-sky objects or DSO are extended objects which are external to the solar system, and are not point
sources like stars. DSO include galaxies, planetary nebulae and star clusters. These objects may or may
not have images associated with them. Stellarium comes with a catalog of over 90,000 extended objects
containing the combined data from many catalogs, with 500+ images.
The DSO tab (Fig. 4.13) allows you to specify which catalogs or which object types you are interested
in. This selection will also be respected in other parts of the program, most notably Search (section 4.5) and
AstroCalc/WUT (section 4.6.6) will not find objects from catalogs which you have not selected here.
See chapter 8 for details about the catalog, and how to extend it with your own photographs.
4.4.4 The Markings Tab
The Markings tab of the View window (Fig. 4.14) controls plotting various grids and lines on the celestial
sphere. Colors for grids, lines and points can be adjusted by clicking on the corresponding colored square.
The central column governs lines like equator, ecliptic, meridian etc., where each can optionally be fine-tuned
to show partition marks and labels. Color settings are stored immediately, all other flags need explicit saving
of the settings (see section 4.3.1).
4.4.5 The Landscape Tab
The Landscape tab of the View window (Fig. 4.15) controls the landscape graphics (the horizon which
surrounds you). To change the landscape graphics, select a landscape from the list on the left side of the
window. A description of the landscape will be shown on the right.
Note that while a landscape can include information about where the landscape graphics were taken
(planet, longitude, latitude and altitude), this location does not have to be the same as the location selected in
the Location window, although you can set up Stellarium such that selection of a new landscape will alter the
location for you.
The controls at the bottom right of the window operate as follows:
Use this landscape as default
Selecting this option will save the landscape into the program configuration
file so that the current landscape will be the one used when Stellarium starts.
Show ground This turns on and off landscape rendering (same as the button
in the main tool bar).
Show fog
This turns on and off rendering of a band of fog/haze along the horizon, when available in this
landscape.
Show illumination
to reflect the ugly developments of our civilisation, landscapes can be configured with a
layer of light pollution, e.g., streetlamps, bright windows, or the sky glow of a nearby city. This layer,
if present, will be mixed in when it is dark enough.
Show landscape labels
Landscapes can be configured with a gazetteer of interesting points, e.g., mountain
peaks, which can be labeled with this option. Color and font size can also be configured.
Location from landscape
When enabled, selecting a new landscape will automatically update the observer
location. Use this if the landscape is not just decoration, but a true representation of a particular site
you wish to visit in the simulation.
Minimal brightness
Moonless night on very dark locations may appear too dark on your screen. You may
want to configure some minimal brightness here.
from landscape, if given
Landscape authors may decide to provide such a minimal brightness value
in the landscape.ini file.
4.4 The View Settings Window 33
Figure 4.13: View Settings Window: DSO Tab
Figure 4.14: View Settings Window: Markings Tab
Figure 4.15: View Settings Window: Landscape Tab
34 Chapter 4. The User Interface
Draw only polygon
If a polygonal horizon line has been defined for the landscape, only draw this with the
given thickness and color.
Transparency Allow peeking below the horizon. Note that this may show graphical errors.v 23.3
Using the button
Add/remove landscapes. . .
, you can also install new landscapes from ZIP files which you
can download e.g. from the Stellarium website
5
or create yourself (see ch. 7 Landscapes), or remove these
custom landscapes.
Loading large landscapes may take several seconds. If you like to switch rapidly between several
landscapes and have enough memory, you can increase the default cache size to keep more landscapes loaded
previously available in memory. Note that a large landscape can take up 200MB or more! See section D.1.13.
4.4.6 The Sky Culture Tab
Figure 4.16: World map showing Stellarium’s built-in set of sky cultures. To avoid overcrowding,
smaller European sky cultures which are mostly derivatives or relatives of the “Modern” sky culture
are not shown. (Image: S. M. Hoffmann)
If you want to explore humankind’s cultural history, you could also switch to the viewpoint of ancient or
other contemporary peoples. Constellations are defined as patterns in the sky shaped from fixed celestial
objects, often serving to set calendar marks and to navigate while travelling on Earth. Which patterns are
seen depends on the natural environment and the cultural habits of the people, i.e., the Inuit in the arctic
area might have seen an Elk where the Chinese have seen a huge spoon or dipper. There cannot be any
astrological influence from these patterns as they had been seen differently and, thus, are a product of
human’s imagination. So, pointing out these cultural differences might have an educational function, too.
Caution
Some of our native peoples’ constellations have been contributed for noncommercial use only. Please
respect their heritage holders and check-out the CC licence version in the description before you use sky
cultures for broadcasting! See section 9.1.3 for details.
The Sky Culture tab of the View window provides two sub-tabs:v 26.1
Details and Appearance
(Fig. 4.17) provides textual information about the currently selected skyculture,
and user interface elements to fine-tune the display of available data.
Exploration and Selection
(Fig. 4.18) provides a list of available skycultures, sorted into blocks of geo-
graphic regions, together with a world map on which the available cultures are displayed
6
. Clicking
on a polygon will select the respective skyculture.
5
https://stellarium.org/landscapes.html
6
As of version 26.1 this is a new feature, and only Norse (Edda) so far has the polygons available.
4.4 The View Settings Window 35
Figure 4.17: View Settings Window: Sky Culture Tab, Details and Appearance
Figure 4.18: View Settings Window: Sky Culture Tab, Exploration and Selection
36 Chapter 4. The User Interface
On the tab “Details and Appearance”, you find numerous controls to configure how the current culture’s
constellations and bright star names will be used in the main display. Some cultures have constellation art
(e.g., Modern or Inuit), and the rest do not. Configurable options include
Use this sky culture as default Activate this option to load this sky culture when Stellarium starts.
Info and screen label styles
The new skyculture system has introduced a plethora of new name elements,
v 25.2
the complete set of which is not required to exist. There are name components that may come in
the skyculture’s original (native) language. If such a culture uses non-Latin glyphs in its writing,
non-native users need a transliteration that also helps pronunciation, which even depends on user
language. Then there are scientific transliteration systems for some cases. Finally, a pronunciation
aid can be given using the International Phonetic Alphabet (IPA). And, after the actual translation,
for reference, you may want to add the commonly used modern name to an object like star or planet.
There are two sets of settings, for the screen label and for the label used in the information area in the
top-left. The currently configured settings are immediately stored per-skyculture and retrieved when
you load another skyculture, so that you can adapt the system to your knowledge of languages and
character systems. See 9.2.9 for more.
Abbreviated names
To provide a less cluttered screen in case constellation names are long, you can
show abbreviations. The Modern skycultures use the 3-letter codes given by the IAU, for the other
skycultures we depend on our skyculture authors to define unique short labels that help memorizing.
Some skycultures still just show legacy numbers.
Select single constellation/Isolated See section 4.4.6.1 for details.
Constellation labels Activate display of constellation labels, like
or
V
.
Constellation lines
Activate display of stick figures, like or
C
, and you can configure constellation
line thickness in the right spinbox.
Constellation art
Activate display of constellation art (if available), like or
R
. You can also select
the brightness here.
Constellation boundaries
Activate display of constellation boundaries, like
B
. Currently, boundaries
have been defined only for “Modern” sky cultures.
Asterism labels Activate display of asterism labels, like
Alt
+
V
.
Asterism lines
Activate display of asterism stick figures (like the shortcut
Alt
+
A
), and you can configure
asterism line thickness as well.
Ray helpers
Activate display of special navigational lines which connect stars often from different constel-
lations (like the shortcut
Alt
+
R
), and you can configure thickness of those lines as well.
Constellation areas optional, advanced research feature. See page 117 for details.
Zodiac
If this skyculture has a concept of Zodiac (usually a region around the ecliptic split into 12 equal-
sized parts), you can enable it here.
Lunar Stations
If this skyculture has a concept of Lunar stations or mansions, you can enable them here.
For example, Indian skycultures observe 27 nakshatras along the ecliptic, and Chinese skycultures
have 28 Lunar mansions of unequal width in equatorial coordinates defined by particular stars.
4.4.6.1 Select single constellations
Some presenters may want to explain a particular storyline about the constellations of a sky culture, which
includes showing single constellations or showing a sequence of appearing constellations. To achieve this,
first activate “Select single constellation” mode (see fig 4.17). Then, click on a star which is part of a
constellation line set. Click another star which is part of another constellation to show that one in addition. If
you really only want to show a single constellation, also add the “Isolated” option.
If you explain a sky culture where constellations also have borders defined, a click anywhere in the
constellation area is enough. For other sky cultures, clicking onto a star which is not member of a constellation
line will display all constellations.
Press
W
to remove all but the last selected constellation. If you had deleted selection (right mouse
click) before pressing
W
, all constellations are hidden. Press
W
again to also hide the single displayed
one, or click another star to select the next constellation. If you need to keep the single constellation visible,
select the currently selected star again to select it again. Press
Alt
+
W
to show all constellations.
With a little training, you will be able to give inspiring constellation tours.
4.4.7 The Surveys Tab
The Surveys tab (Fig. 4.19) allows to toggle the visibility of online sky or solar system surveys (see chapter 10
for description of the surveys format). Currently, only HiPS surveys are supported.
4.5 The Search Window 37
Figure 4.19: View Settings Window: Surveys Tab
On the left side of the window we see the list of available surveys from the configured sources (See
section D.1.30 for how to change the default sources). On the right side a description of the selected survey
and its properties are displayed.
Surveys are grouped by types. The top combobox allows to filter the listed surveys according to a given
type (Deep Sky or Solar System).
You can toggle the visibility of a survey by checking the box on the left of the survey name in the list.
(Note that as of v0.18.0, only a single deep sky survey can be rendered at a time, so it makes no sense to
select more than one in the list!) Once a survey is visible you should be able to see its loading status in the
loading bar area of the sky view.
Deep sky surveys will be rendered aligned with the sky view, while solar system surveys automatically
map on the proper body.
4.5 The Search Window
4.5.1 The Object tab
The Object tab of the Search window provides a convenient way to locate objects in the sky. Simply type in
the name of an object to find, and press . Stellarium will point you at that object in the sky.
As you type, Stellarium will make a list of objects which contains what you have typed so far. The first
of the list of matching objects will be highlighted. If you press the or key, the selection will change
to the next item in the list. Pressing the key will bring you to the previous item. Hitting the key will
center on the currently highlighted object and close the Search window.
For example, suppose we want to locate Saturn’s moon Mimas (SI). Open the Search window ( ,
F3
, or
Ctrl
+
F
). Type the first letter of the name, m, to see a list of objects whose name contains m:
Miranda (UV)
Psamathe (NX)
Umbriel (UII)
. . .
You may want at this point to have Stellarium rather propose object names which start with the string
you enter. Do that in the Options tab of this panel (see section 4.5.5). The search result should update
automatically when you navigate back to the Object tab. Now the list is shorter and contains only objects
which start with m:
Mago
Maia
Mars
. . .
38 Chapter 4. The User Interface
Figure 4.20: The Search Window: Object
Figure 4.21: The Search Window: Object (Recent Searches)
Figure 4.22: The Search Window: SIMBAD
4.5 The Search Window 39
Figure 4.23: The Search Window: Position
Figure 4.24: The Search Window: Lists
Figure 4.25: The Search Window: Options
40 Chapter 4. The User Interface
The first item in this list, Mago, is highlighted. Pressing now would go to Mago, but we want Mimas
(SI). We can either press or a few times to highlight Mimas (SI) and then hit , or we can continue
to type the name until it is the first/only object in the list.
After you searched for an object, the next time the Search window opens, your most recently searched
object(s) will automatically appear in the search result of the Object tab. For instance, continuing with our
example, re-open the Search window’s Object tab. Mimas (SI) should already be populated and highlighted:
Mimas (SI)
The Object tab’s search result will now prioritize your most recent searches (which will be shown in bold).
To modify the search results, see section 4.5.5. From our earlier example, re-enter m into the Object tab.
Doing so will generate a slightly different list than before. In this case, Mimas (SI) will appear first, as shown
in Figure 4.21:
Mimas (SI)
Mago
Maia
Mars
. . .
4.5.2 The SIMBAD tab
The SIMBAD tab (Fig. 4.22) provides a convenient way to fetch and show a set of information for selected
object from the astronomical online database SIMBAD (Wenger et al., 2000). If some object is only visible
in a survey or DSS background (see section 10) and not in Stellarium’s catalogs, you can also set a custom
marker (see section 3.6), select it and query SIMBAD “tell me what’s known about objects at this location”.
4.5.3 The Position tab
The Position tab (Fig. 4.23) provides a convenient way to enter a set of coordinates.
4.5.4 The Lists tab
The Lists tab (Fig. 4.24) allows selection of an object from predefined sets. The number of choices is
governed by the loaded DSO catalogs and plug-ins. Scroll down the first window to select the type. Click on
the name and Stellarium will center on that object.
4.5.5 The Options tab
The Options tab (Fig. 4.25) provides a few settings to fine-tune your search experience.
Use SIMBAD
When the name of an object to find is typed in the Object tab and you are connected to the
internet and “Use SIMBAD” is ticked, Stellarium will search the SIMBAD on-line databases for its
coordinates. You can then click the button or press . Stellarium will point you at that object
in the sky even if there is no object displayed on the screen. The SIMBAD server being used can be
selected from the scroll window.
Server: for server selection
Search Options group allows for changes in the search result behaviour.
Use autofill only from the beginning of words
when checked, will search for object names that
begins with the same letters as your input. Example provided in section 4.5.1.
Lock position when coordinates are used
Show FOV center marker when position is search
Recent Searches
group allows modification to your recent search data. Any changes here will automatically
update the search results displayed in the Object tab. Example provided in section 4.5.1.
Max items to display amount of recent searches that can appear in the search result
button deletes your recent search history
4.6 The Astronomical Calculations Window
This window provides advanced functionality, some of which is still under development. You can call it by
pressing
F10
or the button on the left menu bar. The Astronomical Calculations window shows eight
tabs with different functionality.
4.6 The Astronomical Calculations Window 41
Most tabs allow exporting computed data to XLSX (Excel) files in addition to CSV files, and graphs
can be exported as PNG files.
4.6.1 The Positions Tab
This tab shows equatorial J2000.0 or horizontal positions, magnitudes and additional parameters (e.g. surface
brightness for deep-sky objects or angular separation for double stars) for various lists of celestial objects
above the horizon at the simulated time, filtered by magnitude. Double-clicking on an entry brings the object
into focus (Fig. 4.26). You may also export the list of positions into an XLSX or CSV file.
Figure 4.26: Astronomical Calculations (AstroCalc): Celestial positions / Seen now
This tab is split into 2 subtabs: “Seen now” and “Major planets”. The “Major planets” subtab (Fig. 4.27)
shows a table with heliocentric ecliptic positions of the major planets and a graphical representation of these
positions (in polar coordinates). You may also export the list of positions into an XLSX or CSV file.
Figure 4.27: Astronomical Calculations (AstroCalc): Celestial positions / Major Planets
4.6.2 The Ephemeris Tab
Select an object, start and end time, and compute an ephemeris (list of positions and magnitudes evolving
over time) for that object. The positions are marked in the sky with yellow disks (Fig. 4.28).
When you click on a date, an orange disk indicates this date and/or magnitude. Double-clicking sets the
respective date and brings the object to focus. Dates and/or magnitudes will show up near position markers
when Show dates and/or Show magnitudes checkboxes are active. To show a line between markers please
tick checkbox Show line. You may customize the format of displayed data near markers and their frequency
42 Chapter 4. The User Interface
Figure 4.28: Astronomical Calculations (AstroCalc): Plot trace of planet
Figure 4.29: Astronomical Calculations (AstroCalc): Extra options for ephemeris
Figure 4.30: Astronomical Calculations (AstroCalc): Analemma on the Earth
4.6 The Astronomical Calculations Window 43
in the Extra options window (Fig. 4.29). You can also define the color of markers and enable display markers
for all naked-eye visible planets.
You can export the calculated ephemeris into an XLSX or CSV file.
Another interesting option in this tool: using horizontal coordinates for plotting traces of the Solar
system objects. In this mode, the circle marks are not linked to the sky, but to the horizontal coordinate
system. For example, you can get an analemma of the Sun for any location (Fig. 4.30 and 4.31), or observe
the visibility of Mercury, Venus or a comet in the twilight sky.
You can draw an ephemeris of two objects at the same time and define custom time step for the
ephemeris (Fig. 4.32).
Note: The ephemeris is computed with the current settings for atmosphere, topocentric correction etc. In
consequence, e.g. magnitudes may be affected by atmospheric absorption and may show unexpected values.
Remember to switch off atmosphere etc. to create extinction free geocentric mean positions as found in
almanachs.
Two time steps require a bit of care to display well. The Sun at preset altitude displays an object’s
v 26.2
position when the Sun is at a specific altitude relative to the horizon. Once selected from the list of time steps,
the Custom interval window is enabled, and a preset solar altitude can be selected (only values
≤ 0
○
are
valid), and the ephemeris is computed accordingly. If the Sun never reaches the altitude selected, during the
specified interval, e.g.
−12
○
during Scandinavian summer solstice, no marker is drawn. (Fig. 4.33). Using it
as intended requires the ephemeris to be drawn in horizontal coordinates!
The other time step that requires some care is the Opposition of planet. This is useful for displaying
where and when a planet will be at its opposition for a given year in relation to background stars. For it to
make sense, the planet in question needs to be selected both in the ephemeris list and in the Custom interval
window Fig. 4.34.
It is only applicable for the outer planets, i.e. Mars through Neptune. The computation is quite intense,
so showing e.g. Neptune oppositions throughout its 165 year orbit might take a while if you’re on a weak
system.
4.6.3 The “Risings, Transits, and Settings” (RTS) Tab
This tab allows you to compute meridian transits and rising and setting times of selected celestial object
(except unnamed stars and artificial satellites) for a specific date range. The tool is useful for planning
observations, and it suggests the best time and conditions for visual observations or astrophotography
(Fig. 4.35).
You may also export the list of transits into an XLSX or CSV file.
4.6.4 The Phenomena Tab
This tab allows you to compute phenomena like conjunctions, oppositions, occultations and eclipses (in
special cases) between planetary objects (Fig. 4.36). In addition, it provides computation of greatest
elongations for the inner planets and stationary points for all planets, and, for all Solar system bodies except
the moons, we also compute perihelia and aphelia.
You can export the calculated phenomena into an XLSX or CSV file.
Four columns in the table may be helpful for planning observation of phenomena:
solar elongation angular distance from the Sun
lunar elongation angular distance from the Moon
mag. 1 magnitude of first object
mag. 2 magnitude of second object
4.6.5 The Graphs Tab
This tab provides on several sub-tabs graphs which are helpful for monthly observation planning of deep-sky
objects and analysis of changes between objects or changes of their positions. Clicking in the graph sets the
time at that point, and setting the mouse onto a graph displays values at this point. However, most graphs are
intended for a rapid overview and are plotted using an interpolating spline through sparse samples, so do not
expect highest accuracy.
4.6.5.1 The “Altitude vs. Time” Subtab
On this subtab (the first subtab and default view in the Graphs tab) you can compute the geometrical altitude
of the currently selected object on the currently set date and draw it as a graph (Fig. 4.37).
Optional graphs for the Sun (with lines for civil, nautical and astronomical twilight) and the Moon
(dashed) are also available.
44 Chapter 4. The User Interface
Figure 4.31: Astronomical Calculations (AstroCalc): Analemma on Mars
Figure 4.32: Astronomical Calculations (AstroCalc): Two asteroids nearby to one place
4.6 The Astronomical Calculations Window 45
Figure 4.33: Astronomical Calculations (AstroCalc): Venus when Sun is at the end of civil twilight
(-6°)
Figure 4.34: Astronomical Calculations (AstroCalc): Points of Saturn’s oppositions during a few
decades
46 Chapter 4. The User Interface
Figure 4.35: Astronomical Calculations (AstroCalc): Risings, transits, and settings of selected
celestial object
Figure 4.36: Astronomical Calculations (AstroCalc): Phenomena
Figure 4.37: Astronomical Calculations (AstroCalc): Graphs / Altitude vs. Time
4.6 The Astronomical Calculations Window 47
Figure 4.38: Astronomical Calculations (AstroCalc): Graphs / Azimuth vs. Time
Figure 4.39: Astronomical Calculations (AstroCalc): Graphs / Monthly Elevation
48 Chapter 4. The User Interface
4.6.5.2 The “Azimuth vs. Time” Subtab
On this subtab you can compute the geometrical azimuth of the currently selected object on the currently set
date and draw it as a graph (Fig. 4.38).
4.6.5.3 The “Monthly Elevation” Subtab
This subtab can show a “Monthly Elevation” graph for the current year at the selected time. This tool was
introduced for planning yearly observations (Fig. 4.39).
4.6.5.4 The “Graphs” Subtab
This subtab can show two functions over time for the current month or for up to 30 years and draw graphs
for them in one screen (Fig. 4.40). You can select from
•
Magnitude vs. Time
•
Phase vs. Time
•
Distance vs. Time
•
Elongation vs. Time
•
Angular size vs. Time
•
Phase angle vs. Time
•
Heliocentric distance vs. Time
•
Transit altitude vs. Time
•
Right ascension vs. Time
•
Declination vs. Time
This tool may be very helpful for educational and statistics purposes.
7
For example, the magnitude curve
for Jupiter’s moons shows occasional dips where the moon is in Jupiter’s shadow. However, while for most
graphs a sampling interval of 24 hours should be sufficient (i.e., 1 value per day), for this graph you may
want to reduce the sampling interval to 1 or 2 hours to avoid missing those eclipses by undersampling. Of
course, such high density takes much longer to compute, so you should avoid plotting this curve for many
years, or expect a long delay where the program may seem unresponsive.
4.6.5.5 The “Lunar Elongation” Subtab
This subtab (Fig. 4.41) can show a “Lunar Elongation” graph — the angular distance between the Moon and
the selected object (for example some deep-sky object) for the nearest 30 days. This tool was introduced for
planning monthly observations.
4.6.6 The “What’s Up Tonight” (WUT) Tab
The “What’s Up Tonight” (WUT) tool
8
displays a list of objects that will be visible at night for the current
date and location.
The objects are organized into type categories. Select an object type in the box labeled Select a Category,
and all objects of that type which are above the horizon on the selected night will be displayed in the box
labeled Matching Objects. For example, in the screenshot, the Planets category has been selected, and three
planets which are up in the selected night are displayed (Jupiter, Mars and Mercury).
By default, the WUT will display objects which are above the horizon between sunset and midnight (i.e.
in the evening). You can choose to show objects which are up between midnight and dawn (in the morning),
around midnight, or any time between dusk and dawn (any time tonight) using the combobox near the top
of the window. You can also choose to see only those objects that are brighter than a certain magnitude by
setting a minimum magnitude using the Show objects brighter than magnitude spinbox. You may center an
object from the right list in the sky map just by selecting it.
Note that only DSO from catalogs which you have selected in the DSO panel (section 4.4.3) will be
found.
In version 0.18.3 this tool has been refactored: the tool for searching items from list of Matching Objects
was removed, the filter for magnitudes was moved to the right, and we added a new filter here to limit the
range of acceptable angular sizes of matched objects. In addition to the names we added 5 new sortable
columns: magnitude, rising time, transit time, setting time and angular size of object.
4.6.7 The “Planetary Calculator” (PC) Tab
The “Planetary Calculator” (PC) tool has been added after user requests. It computes the relations between
two Solar system bodies for the current date and location — linear and angular distances, orbital resonances
and orbital velocities.
7
The idea for this tool has been obtained from SkytechX: http://www.skytechx.eu/
8
This tool has been partially ported from the KStars planetarium: https://edu.kde.org/kstars/
4.6 The Astronomical Calculations Window 49
Figure 4.40: Astronomical Calculations (AstroCalc): Graphs
Figure 4.41: Astronomical Calculations (AstroCalc): Graphs / Lunar Elongation
Figure 4.42: Astronomical Calculations (AstroCalc): What’s Up Tonight (WUT)
50 Chapter 4. The User Interface
Figure 4.43: Astronomical Calculations (AstroCalc): Planetary Calculator (PC), Data Tab
Figure 4.44: Astronomical Calculations (AstroCalc): Planetary Calculator (PC), Graphs Tab
Figure 4.45: Astronomical Calculations (AstroCalc): Eclipses / All Solar Eclipses
4.6 The Astronomical Calculations Window 51
The Graphs tab (Fig. 4.44) shows the change in the linear and angular distances between selected
celestial bodies over a range of 600 days (centered on the current date) as graphs.
4.6.8 The Eclipses Tab
The Eclipses tool has four subtabs: “All Solar Eclipses”, “Local Solar Eclipses”, “Lunar Eclipses” and
“Planetary Transits”.
You can export the calculated eclipses and transits into an XLSX or CSV file.
Caution
Predicting eclipses and transits, and in particular local circumstances, over thousands of years in the past and
future is not reliable due to the principal unpredictability of
∆T
, caused by fluctuations of Earth’s rotation.
(See section 18.4.3 for details.)
4.6.8.1 The “All Solar Eclipses” Subtab
This subtab (Fig. 4.45) contains data for all solar eclipses on the Earth in the selected time range. Double
click on a line in the table will set location and time of greatest eclipse. Click on the table row will show
circumstances of selected eclipse in the lower table.
The quantity Gamma is the minimum distance of the lunar shadow cone axis to the center of the Earth,
in units of Earth’s equatorial radius. This distance is positive or negative, depending on whether the axis of
the shadow cone passes north or south of the Earth’s center.
Click the
Export KML. . .
button to create a KML file of the selected eclipse. KML is a file format used to
display geographic data in Earth browsers, such as Marble, Google Earth or Google Maps. The file can be
opened in applications that support KML version 2.2. A description of the lines for solar eclipses is shown
in Fig. 4.46. Different colors are used to draw path of central eclipse. Red = total eclipse, blue = annular
eclipse, and purple = hybrid eclipse. Limits of penumbral or partial eclipse are green.
Northern limit of penumbra (partial eclipse)
Total Solar Eclipse 2027 August 2
Southern limit of penumbra (partial eclipse)
Outline of umbra
plotted every 10 minutes
Point of greatest eclipse
Path of total eclipse
Southern limit
Northern limit
Center line
Eclipse begins at sunrise
Maximum eclipse at sunrise
Eclipse ends at sunrise
Eclipse begins at sunset
Maximum eclipse at sunset
Eclipse ends at sunset
Figure 4.46: Key to solar eclipse map
4.6.8.2 The “Local Solar Eclipses” Subta b
This subtab (Fig. 4.47) contains data for solar eclipses for the current location (on the Earth!) in defined time
range.
Double click on a line in the table will set the time of greatest eclipse.
52 Chapter 4. The User Interface
Figure 4.47: Astronomical Calculations (AstroCalc): Eclipses / Local Solar Eclipses
Figure 4.48: Astronomical Calculations (AstroCalc): Eclipses / Lunar Eclipses
4.6.8.3 The “Lunar Eclipses” Subtab
This subtab (Fig. 4.48) contains data for all lunar eclipses on the Earth in defined time range. Double click
on the table row will set time of greatest eclipse. Click on the table row will show circumstances of selected
eclipse in the lower table.
The quantity gamma is the minimum distance from the center of the Moon to the axis of Earth’s umbral
shadow cone, in units of Earth’s equatorial radius. This distance is positive or negative, depending on whether
the Moon passes north or south of the shadow cone axis.
The visibility conditions are based on the altitude of the Moon at greatest eclipse:
Invisible — the greatest eclipse is invisible at the current location (altitude is negative);
Not obs.
— not observable eclipse. Our rule of thumb is that a partial penumbral eclipse is detectable with
the unaided eye if penumbral magnitude > 0.7;
Bad — bad visibility conditions for current location (altitude range is 0—30°);
Good
— good visibility conditions for current location (altitude range is 30—45°; i.e., “photometric
altitude”);
Perfect — perfect visibility conditions for current location (altitude range is 45—90°).
4.6.8.4 The “Planetary Transits” Subtab
This subtab (Fig. 4.49) contains data for all transits of Mercury and Venus across the Sun as seen from Earth
(see 19.11.3) in the defined time range. If an event is not observable because the Sun/planet is below the
horizon, its time will be shown in brackets and greyed-out. Further columns show the total duration of the
4.6 The Astronomical Calculations Window 53
Figure 4.49: Astronomical Calculations (AstroCalc): Eclipses / Planetary Transits
Figure 4.50: Astronomical Calculations (AstroCalc): Almanac / Specific Time
event, and the observable duration at the current location, which takes rising and setting times into account.
Double click on the table row will set time of mid-transit.
4.6.9 The Almanac Tab
The Almanac tool has one subtab: “Specific Time”. v 25.1
4.6.9.1 The “Specific Time” Subtab
This subtab (Fig. 4.50) contains data for specific time moments in this year (starring and duration seasons)
and at today — time for setting and rising the Sun and Moon, time and duration of twilights, and duration of
the daytime and astronomical night. You can use buttons to quick set these specific time moments. All dates
and times are selectable.
54 Chapter 4. The User Interface
4.7 The Help Window
4.7.1 The Help Tab
Figure 4.51: Help Window
The Help Tab lists all of Stellarium’s keystrokes. Note that some features are only available as keystrokes, so
it’s a good idea to have a browse of the information in this window.
4.7.2 The About Tab
The About Tab (Fig. 4.52) shows version and licensing information, and a list of people who helped to
produce the program. This tab also provides a tool to check for updates of Stellarium.
4.7.3 The Log Tab
The Log Tab (Fig. 4.53) shows messages like the loading confirmations carried out when Stellarium runs. It
is useful to locate the files that Stellarium writes to your computer. The same information is written to the
file log.txt that you will find in your user data directory (see 5.1).
4.7.4 The Config Tab
The Config Tab (Fig. 4.54) shows configuration data of the Stellarium. It is useful to locate the files that
Stellarium writes to your computer. The same information is written to the file
config.ini
that you will
find in your user data directory (see 5.1).
4.7 The Help Window 55
Figure 4.52: Help Window: About
Figure 4.53: Help Window: Logfile
Figure 4.54: Help Window: Config file
56 Chapter 4. The User Interface
4.8 Editing Keyboard Shortcuts
Figure 4.55: Keyboard Shortcuts
You can edit the shortcut keys here. Each available function can be configured with up to two key
combinations. You may want to reconfigure keys for example if you have a non-English keyboard layout and
some keys either do not work at all, or feel unintuitive for you, or if you are familiar with other software and
want to use the same hotkeys for similar functions. Simply select the function and click with the mouse into
the edit field, then press your key of choice. If the key has been taken already, a message will tell you.
This tool is available through the Help Tab of the Help window (see section 4.7.1) and the Tools Tab of
the Configuration window (see section 4.3.5).
4.8.1 Example
If you want to follow the sky view each evening with the Sun at the same depth below the horizon, so
that the twilight is of equal darkness, you may want to assign some actions to intuitive shortcut keys. In
the Keyboard Shortcut editor (Fig. 4.55), find the Date and Time group and assign, e.g., the keys on your
numeric keypad:
Previous evening twilight Ctrl+9
Previous morning twilight Ctrl+7
Next evening twilight Ctrl+3
Next morning twilight Ctrl+1
Today’s evening twilight Ctrl+6
Today’s morning twilight Ctrl+4
II
Advanced Use
5 Files and Directories . . . . . . . . . . . . . . . . . 59
5.1 Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.2 Directory Structure . . . . . . . . . . . . . . . . . . . . . . 60
5.3 The Logfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.4 The Main Configuration File . . . . . . . . . . . . . . . . 61
5.5 Getting Extra Data . . . . . . . . . . . . . . . . . . . . . . . 61
6 Advanced Options . . . . . . . . . . . . . . . . . . 65
6.1 Command Line Options . . . . . . . . . . . . . . . . . 65
6.2 Environment Variables . . . . . . . . . . . . . . . . . . . . 67
6.3 GUI Customizations . . . . . . . . . . . . . . . . . . . . . 68
6.4 Spout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.5 Show effects . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.6 Spherical Mirror Mode for Planetarium Use . . . 70
7 Landscapes . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.1 Stellarium Landscapes . . . . . . . . . . . . . . . . . . . 73
7.2 Creating Panorama Photographs for Stellarium 82
7.3 Panorama Postprocessing . . . . . . . . . . . . . . . . . 87
7.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . 92
7.5 Other recommended software . . . . . . . . . . . . 92
8 Deep-Sky Objects . . . . . . . . . . . . . . . . . . . 95
8.1 Stellarium DSO Catalog . . . . . . . . . . . . . . . . . . 95
8.2 Adding Extra Nebula Images . . . . . . . . . . . . . . 101
9 Sky Cultures . . . . . . . . . . . . . . . . . . . . . . . . 107
9.1 Text description . . . . . . . . . . . . . . . . . . . . . . . . 107
9.2 Technical data: index.json . . . . . . . . . . . . . . . . 110
9.3 Territory description . . . . . . . . . . . . . . . . . . . . . 124
9.4 The Skyculture Converter . . . . . . . . . . . . . . . . . 124
9.5 Publish Your Work . . . . . . . . . . . . . . . . . . . . . . . 125
10 Surveys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.2 Hipslist file and default surveys . . . . . . . . . . . . . 127
10.3 Solar system HiPS survey . . . . . . . . . . . . . . . . . . 128
10.4 Digitized Sky Survey 2 (TOAST Survey) . . . . . . . 128
11 Stellarium’s Skylight Models . . . . . . . . . 129
11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
11.2 The Skylight Models . . . . . . . . . . . . . . . . . . . . . 129
11.3 Light Pollution . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11.4 Tone Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 131
5. Files and Directories
5.1 Directories
Stellarium has many data files containing such things as star catalogue data, nebula images, button icons,
font files and configuration files. When Stellarium looks for a file, it looks in two places. First, it looks in
the user directory
1
for the account which is running Stellarium. If the file is not found there, Stellarium
looks in the installation directory
2
. Thus it is possible for Stellarium to be installed by an administrative user
and yet have a writable configuration file for non-administrative users. Another benefit of this method is on
multi-user systems: Stellarium can be installed by the administrator, and different users can maintain their
own configuration and other files in their personal user accounts.
In addition to the main search path, Stellarium saves some files in other locations, for example screens
shots and recorded scripts.
The locations of the user directory, installation directory, screenshot save directory and script save
directory vary according to the operating system and installation options used. The following sections
describe the locations for various operating systems.
5.1.1 Windows
installation directory
By default this is
C:\Program Files\Stellarium\
, although this can be adjusted
during the installation process.
user directory
This is the Stellarium sub-folder in the Application Data folder for the user account which is
used to run Stellarium. Depending on the version of Windows and its configuration, this could be any
of the following (each of these is tried, if it fails, the next in the list if tried).
% APPDATA %\ Stellarium \
% U SER PROF ILE %\ Ste lla rium \
% HOMEDRIVE %\% HOMEP ATH %\ S tel lar ium \
% HOME %\ Stellarium \
Stellarium ’s in stal lation dir ectory
Thus, on a typical Windows Vista/7/10 system with user “Bob Dobbs”, the user directory will be:
C :\ Users \ Bob Dobbs \ AppData \ Roa ming \ Ste lla rium \
The user data directory is unfortunately hidden by default. To make it accessible in the Windows file
explorer, open an Explorer window and select
Organize... Folder and search options
. Make sure
folders marked as hidden are now displayed. Also, deselect the checkbox to “hide known file name
endings”.
3
1
also called user data directory
2
The installation directory was referred to as the config root directory in previous versions of this guide
3
This is a very confusing default setting and in fact a security risk: Consider you receive an email with some file
60 Chapter 5. Files and Directories
screenshot save directory
Screenshots will be saved to the
Pictures/Stellarium
directory, although
this can be changed in the GUI (see section 4.3.5) or with a command line option (see section 6.1).
5.1.2 macOS
installation directory
This is found inside the application bundle,
Stellarium.app
. See The Anatomy of
macOS App Bundles
4
or Bundle Programming Guide
5
for more information.
user directory
This is the sub-directory
~/Library/Application Support/Stellarium
of the user’s
home directory.
screenshot save directory Screenshots are saved to the user’s Desktop.
5.1.3 Linux
installation directory
This is in the
share/stellarium
sub-directory of the installation prefix, i.e., usu-
ally /usr/share/stellarium.
user directory
This is the
.stellarium
sub-directory of user’s home directory, i.e.,
~/.stellarium/
.
This is a hidden folder, so if you are using a graphical file browser, you may want to change its settings
to “display hidden folders”.
screenshot save directory Screenshots are saved to the user’s home directory.
5.1.4 *BSD/Solaris/OpenIndiana
installation directory
This is in the
share/stellarium
sub-directory of the installation prefix, i.e., usu-
ally /usr/local/share/stellarium/.
user directory
This is the
.stellarium
sub-directory of user’s home directory, i.e.,
~/.stellarium/
.
This is a hidden folder, so if you are using a graphical file browser, you may want to change its settings
to “display hidden folders”.
screenshot save directory Screenshots are saved to the user’s home directory.
5.1.5 Haiku
installation directory This is in the /boot/system/data/stellarium/ sub-directory.
user directory
This is in the user’s home directory, i.e.,
~/config/settings/Stellarium/
or the sub-
directory /boot/home/config/settings/Stellarium/.
screenshot save directory Screenshots are saved to the user’s home directory.
5.1.6 Customized Location
Some users may prefer non-standard locations for their own data, for example when the Windows
C:
drive
(which usually contains user data), or the Linux
/home
partition has become too small to hold tens of
high-resolution landscapes or detailed 3D sceneries. You can move the entire directory elsewhere and use an
environment variable STEL_USERDIR that contains the pathname.
5.2 Directory Structure
Within the installation directory and user directory defined in section 5.1, files are arranged in the following
sub-directories.
landscapes/
contains data files and textures used for Stellarium’s various landscapes. Each landscape has
its own sub-directory. The name of this sub-directory is called the landscape ID, which is used to
specify the default landscape in the main configuration file, or in script commands.
skycultures/
contains constellations, common star names and constellation artwork for Stellarium’s
many sky cultures. Each culture has its own sub-directory in the skycultures directory.
scripts/ contains your own scripts. These can be used to create complex demonstrations (see ch. 17).
nebulae/
contains data and image files for nebula textures. In the future Stellarium may be able to support
multiple sets of nebula images and switch between them at runtime. This feature is not implemented
for version 26.2, although the directory structure is in place – each set of nebula textures has its own
sub-directory in the nebulae directory.
funny.png.exe
attached. Your explorer displays this as
funny.png
. You double-click it, expecting to open some
image browser with a funny image. However, you start some unknown program instead, and running this
.exe
executable
program may turn out to be anything but funny!
4
https://www.maketecheasier.com/anatomy-macos-app-bundles/
5
https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CF
Bundles/Introduction/Introduction.html
5.3 The Logfile 61
stars/
contains Stellarium’s star catalogues. In the future Stellarium may be able to support multiple star
catalogues and switch between them at runtime. This feature is not implemented for version 26.2,
although the directory structure is in place – each star catalogue has its own sub-directory in the stars
directory.
data/ contains miscellaneous data files including fonts, solar system data, city locations, etc.
textures/
contains miscellaneous texture files, such as the graphics for the toolbar buttons, planet texture
maps, etc.
ephem/
(optional) may contain data files for planetary ephemerides DE430, DE431, DE440 and DE441
(see 5.5.3).
If any file exists in both the installation directory and user directory, the version in the user directory will
be used. Thus it is possible to override settings which are part of the main Stellarium installation by copying
the relevant file to the user area and modifying it there.
It is recommended to add new landscapes or sky cultures by creating the relevant files and directories
within the user directory, leaving the installation directory unchanged. In this manner different users on a
multi-user system can customise Stellarium without affecting the other users, and updating Stellarium will
not risk the loss of your own data.
5.3 The Logfile
Stellarium reports various events and confirmations to a logfile,
log.txt
, in the user directory. This has
the same content as you can see on the console on Linux when you start Stellarium on the command line.
Normally you don’t need to bother with its contents, however, if Stellarium behaves unexpectedly, crashes,
or shows other problems, a quick look into this file may help to identify the problem. Also when you report a
problem to the developers in the hope that they (we) can ’fix’ anything, this logfile is an essential ingredient
to your report. The logfile can also be displayed within the program: press
F1
to call the help panel, and
select the Logfile tab.
5.4 The Main Configuration File
The main configuration file is read each time Stellarium starts, and settings such as the observer’s location
and display preferences are taken from it. Ideally this mechanism should be totally transparent to the user
– anything that is configurable should be configured “in” the program GUI. However, at time of writing
Stellarium isn’t quite complete in this respect, despite improvements in each version. Some settings, esp.
color values for some lines, grids, etc. can only be changed by directly editing the configuration file.
6
This
section describes some of the settings a user may wish to modify in this way, and how to do it.
The name of the configuration file is
config.ini
7
. If the configuration file does not exist in the user
directory when Stellarium is started (e.g., the first time the user starts the program), one will be created with
default values for all settings (refer to section 5 Files and Directories for the location of the user directory on
your operating system).
The configuration file is a regular text file, so all you need to edit it is a text editor like Notepad on
Windows, Text Edit on the Mac, or nano/vi/gedit/emacs/leafpad etc. on Linux.
A complete list of configuration file options and values may be found in appendix D.1.
5.5 Getting Extra Data
5.5.1 More Stars
Stellarium is packaged with over 600 thousand stars in the normal program download, but much larger star
catalogues may be downloaded in the Tools tab of the Configuration dialog (
or
F2
).
6
Color values can be edited interactively by the Text User Interface plugin (see 13.5).
7
It is possible to specify a different name for the main configuration file using the
--config-file
command line
option. See section 6.1 Command Line Options for details.
62 Chapter 5. Files and Directories
5.5.2 More Deep-Sky Objects
Stellarium is packaged with over 94 thousand deep-sky objects
8
in the normal program download (the
standard edition of Stellarium DSO catalog
9
, see section 8.1), but an extended edition of DSO catalog with
over one million objects (up to
20.0
m
for galaxies) may be downloaded from Stellarium’s Github website
10
:
Version; Edition Filename MD5 hash Size
3.23; extended catalog-3.23.dat 56dfcdcedc3bfc18ce730984ab039308 28MB
The file can be placed in a folder named nebulae/default inside the user directory (see section 5.2).
5.5.3 Alternative Planet Ephemerides: DE430, DE431, DE440, DE441
By default, Stellarium uses the VSOP87 planetary theory, an analytical solution which is able to deliver
planetary positions for any input date (P. Bretagnon and Francou, 1988). However, its use is recommended
only for the year range
−4000. . . + 8000
. Outside this range, it seems to be usable for a few more millennia
without too great errors, but with degrading accuracy. Likewise for the moon, Stellarium by default uses
ELP 2000-82B (Chapront-Touze, 1982; Chapront-Touzé and Chapront, 1983; Chapront-Touzé and Chapront,
1988b).
Since v0.15.0 you can install extra data files which allow access to the numerical integration runs DE430
and DE431 (Folkner et al., 2014), and meanwhile also DE440 and DE441 (Park et al., 2021), from NASA’s
Jet Propulsion Laboratory (JPL). The data files have to be downloaded separately, and most users will likely
not need them. DE430 and DE440 provide highly accurate data for the years
+1550. . . + 2650
, while DE431
and DE441 covers years
−13000. . . + 17000
, which allows e.g. archaeoastronomical research on Mesolithic
landscapes. (But see Appendix F!) Outside these year ranges, positional computation falls back to VSOP87.
Some current approximations may still lead to numerical data which differ slightly from best possible
ephemerides. Please at least compare with JPL Horizons
11
for dependable results.
To enable use of these data, download the files from JPL
12
:
Ephemeris Filename MD5 hash Size
DE430 linux_p1550p2650.430 707c4262533d52d59abaaaa5e69c5738 97.5 MB
DE431 lnxm13000p17000.431 fad0f432ae18c330f9e14915fbf8960a 2.59 GB
DE440 linux_p1550p2650.440 9dc8a9cefd32b0090002407847e718ba 97.5 MB
DE441 linux_m13000p17000.441 4e3b924463d17b68ec9c4a18240300cd 2.59 GB
The files can be placed in a folder named
ephem
inside either the installation directory or the user
directory (see 5.2). Alternatively, if you have them already stored elsewhere, you may add the path to
config.ini like:
[ astro ]
de430_path = C :/ As trodata / JPL_DE43x / linu x_p15 50p26 50 .430
de431_path = C :/ As trodata / JPL_DE43x / lnxm 13000p17 000 .431
de440_path = C :/ As trodata / JPL_DE44x / linu x_p15 50p26 50 .440
de441_path = C :/ As trodata / JPL_DE44x / linu x_m1300 0p170 00 .441
For fast access avoid storing them on a network drive or USB pendrive!
You activate use of either ephemeris in the Configuration panel (
F2
). If you activate more than one,
preference will be given for DE440 over DE441 if the simulation time allows it. Only if DE44x are not
enabled, DE430 is given preference over DE431 if simulation time allows it. Outside of the valid times,
VSOP87 will always be used.
Acknowledgement
The optional use of DE430/431 has been supported by the ESA Summer of Code in Space 2015 initiative.
8
Over 83 thousand deep-sky objects in version 0.16.0.
9
The first number in the version of Stellarium DSO catalog means version of catalog structure, and the second
number means version of data.
10
https://github.com/Stellarium/stellarium-data/releases/tag/dso-3.23
11
https://ssd.jpl.nasa.gov/horizons.cgi
12
https://ssd.jpl.nasa.gov/ftp/eph/planets/Linux/
(Also download from this directory if you are not
running Linux!)
5.5 Getting Extra Data 63
5.5.4 GPS Position
In the Location panel (see section 4.2) you can receive your location from a GPS device. The exact way to
receive GPS location depends on your operating system.
5.5.4.1 GPSD (Linux, macOS only)
On Linux, Mac-OS X and other Unixoid platforms, Stellarium preferably should not connect directly to a
GPS USB device, serial device, bluetooth device, etc., but use a connection to the gpsd daemon running on
a computer in your network which provides GPS services concurrently for any interested application. In
most cases, this will be a gpsd running on your localhost, receiving data from some GPS device plugged in
via USB. Please follow instructions by the gpsd authors
13
to properly configure this system daemon. A few
hints:
•
On Ubuntu 16.04 and likely other systems, USB hotplug devices are handled by the udev daemon
which detects newly plugged-in devices and creates device files in the
/dev
directory. Unfortunately,
most GPS devices use the Prolific 2303 chipset in their serial-to-USB converter and are identified as
such, without other unique information like serial numbers. This chipset is also used in other Serial-
to-USB converter cables, and to avoid conflicts the according rule has been disabled by the release
managers of Ubuntu. In /lib/udev/60-gpsd.rules, find the commented line and re-activate it.
•
If you have such an USB GPS mouse and USB-to-serial converters for other purposes like for your
telescope control, you must solve the “udev crisis” in some other way to get gpsd running. You may
be able to find some property in your device to uniquely identify this device and write an udev rule to
create the symlink in /dev/gps0 to which gpsd can then connect.
•
You can also connect to another computer which runs gpsd. This could be a little Raspberry Pi
computer which happens to be in your WiFi to allow localisation and time service. To configure this,
you must manually edit config.ini. Find the [gui] section and edit
[ gui ]
# These values are used on non - Windows systems
# sup por tin g GPSD
gp sd_ hostn ame = lo cal host
gpsd_po rt = 2947
Also, gpsd must be started with the -G parameter to enable this.
•
Even your smartphone can be used as GPS data source
14
: Apps like BlueNMEA can provide these
data for gpsd, but you must make sure to configure hostname/IP Address and port number correctly,
for example
sudo gpsd -n -D8 -S 1001 tcp ://1 92 .168. 1. 101:435 2
which means
-n to start without a device connection
-D8 maximum debug level. When it works, use what suits you
-S 1001 provide service on port 1001
tcp
Use this address:port combination to receive data from (IP of your smartphone, port shown on
BlueNMEA screen).
•
In case you really don’t want to use the gpsd, you can use a directly connected device, see below.
This is however not recommended when you have gpsd available.
5.5.4.2 NMEA Device
This mode is primarily for Windows users, but also for Linux and Mac users who don’t want to use gpsd.
Virtually all GPS receivers are able to emit the standardized NMEA-0183 messages which encode time,
position, speed, satellite information and other data. The standard originally required connection settings of
4800 baud, 8 bit, no parity, one stop bit (8N1), however some devices come with faster transfer.
Compatible devices today are connected on a “virtual COM port” via USB. Unfortunately the COM
number seems to depend on the USB plug where you attach the receiver. You can identify the port name
(COM3, COM4, . . . ) in the Windows system configuration (Device Manager) or with the software that came
with your device.
15
13
https://gpsd.gitlab.io/gpsd/index.html
14
Thanks to user Caysho for this hint.
15
On Linux, this may read /dev/ttyUSB0, /dev/gps0 or similar.
64 Chapter 5. Files and Directories
If this is the only serial device, Stellarium should automatically connect to it regardless of configuration
entries. If you have a device with non-standard baudrate or several serial devices on serial ports (e.g., your
telescope?), you must find out which serial port is used by the GPS device and manually edit
config.ini
.
Find the [gui] section and edit
[ gui ]
# These values are used on Windo ws p rim arily .
gp s_i nterf ace = COM3
gps_b audr ate = 4800
From now on, always use the same USB plug configuration to connect GPS and telescope.
16
If GPS lookup fails, see section 6.2.1 to enable more diagnostic messages in the logfile.
Bluetooth GPS
Most smartphones provide GPS and Bluetooth hardware. You can install a virtual COM port in your
Windows Bluetooth settings and use a smartphone app like Share GPS
17
to provide the NMEA strings.
Windows location service
On Windows devices, you can get your location using the Windows location service. The result depends on
available hardware and other settings, e.g. real GPS sensor or network and WiFi detection.
18
5.5.5 Modernized MESA3D libraries (Software OpenGL on Windows)
Stellarium uses hardware-accelerated OpenGL for rendering. On very old Windows systems without
dedicated graphics hardware, or in special circumstances like virtual machines, hardware accelerated
graphics may not be available, and the Mesa3D software implementation of OpenGL is used. This can also
be forced by the command-line option
--mesa-mode
. Rendering the graphics without hardware acceleration
is of course much slower than accelerated graphics, but it’s surely better than nothing.
Qt’s default Mesa library (Mesa 11) provides support for OpenGL 3.0 only. This prevents users of all
versions from applying dithering in Mesa mode. Also the ShowMySky skylight model (see section 11.2.2) is
then not available.
We have replaced this by a version of Mesa 20 compiled by Federico Dossena
19
which appears to be
v 23.4
even a bit faster.
The Mesa3D project
20
meanwhile (2023) provides at least OpenGL 4.5. If you wish to use more “up to
date” precompiled binaries and have Administrator privileges on your Windows system, you can replace
this library using the following steps to install unofficial builds
21
. Note however that after this upgrade, the
program runs with considerably (
≈
35%?) lower framerate. You must decide whether this is really beneficial
in your situation. The libraries don’t provide any additional graphics features that Stellarium makes use of.
•
Download the latest “release-msvc” package as you need from
https://github.com/pal1000/m
esa-dist-win/releases and unpack it somewhere.
•
Copy
(x86|x64)/libglapi.dll,libgallium_wgl.dll,opengl32.dll
to where the executable
stellarium.exe is.
•
Delete the existing opengl32sw.dll
•
Rename the just-copied opengl32.dll to opengl32sw.dll.
Now running Stellarium in Mesa mode (with link from program menu or command line) should report to
provide OpenGL 4.5.
16
Again, for Linux the port number is defined in order of hotplugging by udev. You should develop an udev rule
which adds a unique name and use this. In this case, you may also need to add your user to the
dialout
group (or
whichever group owns your serial port). Better yet, use gpsd (see above).
17
https://play.google.com/store/apps/details?id=com.jillybunch.shareGPS
18
https://support.microsoft.com/en-us/windows/windows-location-service-and-privacy-3a8
eee0a-5b0b-dc07-eede-2a5ca1c49088
19
https://fdossena.com/?p=mesa/index.frag
20
https://www.mesa3d.org/
21
https://github.com/pal1000/mesa-dist-win/
6. Advanced Options
6.1 Command Line Options
Stellarium’s behaviour can be modified by providing parameters to the program when it is called via the
command line. See table for a full list:
Option Option Parameter Description
--help or -h [none]
Print a quick command line help message, and
exit.
--version or -v [none]
Print the program name and version information,
and exit.
--config-file or -c config file name
Specify the configuration file name. The default
value is config.ini.
The parameter can be a full path (which will be
used verbatim) or a partial path.
Partial paths will be searched for inside the reg-
ular search paths unless they start with a “
.
”,
which may be used to explicitly specify a file in
the current directory or similar.
For example, using the option
-c
my_config.ini
would resolve to the file
<user directory>/my_config.ini
whereas
-c ./my_config.ini
can be used to explicitly
point to the file
my_config.ini
in the current
working directory.
--log-file or -l
log file name
Specify the log file name. The default value is
log.txt.
The value of parameter can be a simple filename
or absolute path to the log file.
When a path is specified like
-l
my_log.txt
, the file will be written to
<user
directory>/my_log.txt
. When a path is spec-
ified like
-l /home/user/stellarium.log
/home/user/stellarium.log
66 Chapter 6. Advanced Options
--restore-defaults [none]
Stellarium will start with the default configura-
tion. Note: The old configuration file will be
overwritten.
--user-dir path Specify the user data directory.
--screenshot-dir
path
Specify the directory to which screenshots will
be saved.
--full-screen yes or no
Overrides the full screen setting in the config file.
--home-planet planet Specify observer planet (English name).
--latitude
latitude Specify latitude, e.g. 41.1 or +53d58’16.6"
1
--longitude
longitude Specify longitude, e.g. 16.2 or -1d4’27.48"
1
--altitude
altitude Specify observer altitude in meters.
--list-landscapes [none] Print a list of available landscape IDs and exit.
--landscape
landscape ID
Start using landscape whose ID matches the
passed parameter (dir name of landscape).
--sky-date date The initial date in yyyymmdd format.
--sky-time
time The initial time in hh:mm:ss format.
--startup-script script name
The name of a script to run after the program has
started. [startup.ssc]
--fov angle (degrees) The initial vertical field of view in degrees.
--scale-gui scale factor Scaling the GUI according to scale factor
--gui-css style
name Use name.css to define GUI style
--projection-type ptype The initial projection type: one of
ProjectionPerspective
ProjectionEqualArea
ProjectionStereographic
ProjectionFisheye
ProjectionCylinder
ProjectionCylinderFill
ProjectionMercator ProjectionMiller
ProjectionOrthographic
ProjectionHammer
ProjectionSinusoidal
--spout or -S all or sky Act as Spout sender (See section 6.4).
2,3
--spout-name
name
Use
name
as name of the Spout sender. Default
name: Stellarium.
2
--dump-opengl-details or -d [none]
Dump information about OpenGL support to log-
file. Use this is you have graphics problems and
want to send a bug report.
--angle-mode or -a [none]
Use ANGLE as OpenGL ES2 rendering engine
(autodetect Direct3D version).
2,4
--angle-d3d9 or -9
[none]
Force use Direct3D 9 for ANGLE OpenGL ES2
rendering engine.
2,4
--angle-d3d11
[none]
Force use Direct3D 11 for ANGLE OpenGL ES2
rendering engine.
2,4
--angle-warp
[none]
Force use the Direct3D 11 software rasterizer for
ANGLE OpenGL ES2 rendering engine.
2,4
1
You may have to escape the minute/second characters, like +53d58\’16.6\"
2
On Windows only
3
This function requires running in OpenGL mode.
4
Qt5-based Stellarium versions only
6.2 Environment Variables 67
--mesa-mode or -m [none]
Use MESA as software OpenGL rendering en-
gine.
2
--single-buffer
[none]
Use single-buffering. This reportedly avoids
screen blanking problems with some Intel GPUs.
--opengl-compat or -C [none]
Request OpenGL 3.3 Compatibility Profile.
Might fix graphics problems in some driver con-
figurations.
--low-graphics or -L
[none]
Force low-graphics mode. May be useful on old
GPUs that do support OpenGL 3.3 but perform
too slowly.
--no-audio [none]
Disable sound output (avoids initialisation prob-
lems on Virtual Machines or special builds).
--no-screensaver [none]
Disable screensaver and auto-sleep when in
fullscreen mode (Windows only).
If you want to avoid adding the same switch every time when you start Stellarium from the command line,
you can also set an environment variable STEL_OPTS with your default options.
Calling the respective options on the command line overrides settings from environment variables (apart
from STEL_OPTS).
6.1.1 Examples
•
To start Stellarium using the configuration file
configuration_one.ini
situated in the user direc-
tory (use either of these):
stellarium -- config - file = c onfig urati on_on e . ini
stellarium -c co nfigu ratio n_ one . ini
•
To list the available landscapes, and then start using the landscape with the ID “ocean”
stellarium -- list - landscapes
stellarium -- landsca pe = ocean
Note that console output (like --list-landscapes) may not be possible on some Windows systems.
6.2 Environment Variables
Some command-line options or settings can be set permanently by storing them into environment variables.
How to set them depends on the respective operating system.
Windows
Press the start menu, search for “environment variable”. Use the command to change user
variables. After setting, you can call Stellarium via its menu entry or desktop links.
This may be especially helpful on Windows systems with older graphics cards which may not
fully be compatible with OpenGL. Here we recommend you either use the program links using the
ANGLE-related options, or you can set the environment variable once and forget about the problems.
Linux, macOS
You will usually set such variables at the end of your
~/.bashrc
file. Open this with a text
editor and add, near the end,
export ST EL_OPTS ="- p latfo rm xcb -- single - buffer "
This forces use of the X11 platform plugin which may work better than wayland on older systems.
These environment variables are important:
STEL_OPTS
may contain a default commandline with options in the syntax of the table above. Also some
Qt settings can only be tweaked with this. For example, Windows users of international keyboards
with
Alt Gr
key may want to use
STE L _ O PTS =- pl a tform win d ows : altgr , fonte n g i n e = fr e e type -- single - bu ffer
The
-platform
parameter is part of Qt. Its second argument,
fontengine
, selects a different font
engine (i.e., some fonts may look better with it). The other argument,
- -single-buffer
, is a setting
that influences Stellarium (see table above).
STEL_USERDIR
may contain the path to a user data directory deviating from the default (see section 5.1).
68 Chapter 6. Advanced Options
QT_OPENGL
2
May be one of
desktop
(native OpenGL for your GPU, recommended),
angle
4
or
software
. The last activates pure software rendering using the MESA OpenGL library. Note that
command line options take precedence over this environment variable.
QT_ANGLE_PLATFORM
2,4
May be one of
d3d9
(DirectX 9) or
d3d11
(DirectX 11), or
warp
for
another software-only solution. Note that command line options take precedence over this environment
variable.
6.2.1 Logfile tweaks
Qt based programs can write log files where status messages of varying severity can be written
5
. There
are categories
debug
(usually only of developer interest),
info
(informational),
warning
(something unex-
pected),
critical
(usually connected to some real failure) and
fatal
(program fails (usually exits) here).
The amount of logging messages can be tuned by setting the environment variable
QT_LOGGING_RULES
. For
example, to remove all
debug
messages, set it to
*.debug=false;
. To remove even the
info
messages,
add
*.info=false;
. (Close each rule, also the last, with semicolon!) If you experience operating trouble,
make sure you allow all messages, i.e., set these entries shown here to true (or delete the variable).
Some modules can be individually finetuned with respect to the amount of logging. Most users won’t
v 25.4
ever want to see the ugly details, so debug is deactivated by default for:
stel.GPS GPS related issues.
stel.LocIP IP-based location queries.
stel.Texture Texture handling.
stel.Atmosphere Atmosphere related messages.
stel.Scripting scripting related messages.
stel.Media Multimedia related messages.
stel.HiPS HiPS related messages.
stel.Properties StelProperty related messages.
If you suspect issues with some features on your computer, add those entries as shown above, e.g., to
hunt down issues with a GPS device:
QT _LOGG ING_R ULES =*. debug = false ; stel . GPS . debug = true ;
or if you are developing scripts and videos don’t play, try if this helps:
QT _LOGG ING_R ULES =*. debug = false ; stel . Media . debug = true ;
6.3 GUI Customizations
Some users have difficulties to read Stellarium’s rather dark user interface. Some screens may be too dark, or
environments too bright.
6.3.1 Panel transparency
The GUI panels are semitransparent by design. If this impedes your ability to read them, you can make them
fully opaque with an entry to config.ini.
[ gui ]
fl ag _use_wind ow _transpar en cy = false
6.3.2 Button brightness
If you only want a bit brighter buttons, these can be tweaked separately in config.ini.v 24.4
[ gui ]
pi xmaps _b right ness =1.25
The value is clamped to [1. . . 1.8] to avoid making active and inactive buttons equally bright.
6.4 Spout 69
6.3.3 Text shadow
Some users complain the infotext is badly visible when there are trees or the Milky Way in the background.
v 24.4
This can also be mitigated in config.ini.
[ gui ]
fl ag_in fo_sh adow = true
6.3.4 User interface color s
Others users still find the GUI too bright, and they would prefer a real “dark mode”. To allow this, you can
create and load your own alternative style files.
The appearance of the windows, buttons etc. is governed by a CSS (Cascaded Style Sheet) file. It
certainly requires some knowledge and guessing to edit your own, but there is enough general help on CSS
available online. You can find the CSS files in Stellarium’s Github site
6
.
Copy them into your user directory and rename to e.g.
myOwnGreatStyle.css
. Edit numbers, but do
not change the item names! Then you can either launch Stellarium with the added command line option like
stellarium -- gui - css myOwn Great Style
or you could also use the scripting option (see chapter 17):
core.setGuiStyle("MyOwnGreatStyle ");
To go back to Stellarium’s default, just use
core.setGuiStyle("default ");
If link colors in text panels are now difficult to read, copy
normalHtml.css
from Github to your own
MyOwnGreatStyleHtml.css and modify to your taste.
Note that, as Stellarium evolves, these files also may change from version to version. We cannot give any
guarantees that one customized file will work without adaptation on later or earlier versions of Stellarium.
6.4 Spout
Apart from stand-alone use, Stellarium can be used as multimedia source in larger installations, in museums
or science exhibitions. Spout
7
is a technology which enables use of Stellarium’s output window as texture in
DirectX applications on Windows. Simply start Stellarium with the
--spout=sky
command line option.
(Currently Spout output is limited to the main window without GUI panels, but this may change in future
versions.) Your master application must obviously embed a Spout receiver. The default name of the Spout
sender is
Stellarium
. If you need more than one instance of Stellarium acting as source, you can use
option
--spout-name=StelSpout2
in addition to create another Spout sender without a name conflict. In
such cases, it may be useful to also have separate user data directories and use option --user-dir.
This mode does not work in ANGLE mode and requires reasonably modern graphics hardware with the
WGL_NV_DX_interop
driver extension running in OpenGL mode. Some Nvidia GPUs work without this
extension listed explicitly. On a notebook with Nvidia Optimus technology, make sure to launch Stellarium
and SpoutReceiver (or your target application) on the Nvidia hardware. For permanent setting, use the
Nvidia configuration dialog to configure Stellarium and the target application explicitly to run always on the
Nvidia card.
Note that Spout use disables any multisampling setting (see Appendix D.1.26).
6.5 Show effects
6.5.1 Sky Background
Stellarium is sometimes used for entertainment or artistic music performances. From this community a
request was placed to allow a non-black background. We can do that, but you must revert the color yourself.
5
https://doc.qt.io/qt-6/qloggingcategory.html, https://doc.qt.io/qt-6/debug.html
6
https://github.com/Stellarium/stellarium/blob/stellarium-stable/data/gui/normalStyle.c
ss
and
https://github.com/Stellarium/stellarium/blob/stellarium-stable/data/gui/normalHtml.
css
7
https://spout.zeal.co/
70 Chapter 6. Advanced Options
Setting a background color is not available in the usual GUI to avoid inadvertent changes that later confuse
users. You can play with the sky background in the Text User Interface (see section 13.5.2, feature 5.26). In
config.ini, it is stored in
[ color ]
sk y_backg round_c olor = 0 .000000 ,0.000000 ,0 .000000
6.5.2 Star Trails
One of the oldest and previously simplest techniques from the time of film-based night photography is
v 26.2
the recording of Earth’s rotation by long-time exposure with an untracked camera. This will, for example,
identify the Polar Star as just not quite on the north celestial pole, but else show thousands of circular star
trails. While an exposure time of many hours is possible under dark skies, when the sky is too bright by
remaining twilight or light pollution, the exposure time meanwhile is often limited to minutes, else the
picture is just flooded with unwanted background.
Stellarium can be made to simulate such images by a somewhat “dirty trick”: Usually the image area is
cleared between frames, then the Milky Way, stars, Zodiacal light, grids, planets, atmosphere, landscape
etc., and finally GUI panels are rendered into the scene. By not clearing the image area, we can just add
up everything that is rendered on-screen, like in a long-time exposure. However, just as cars, airplanes,
satellites or people with flashlights can ruin your awesome star trail photo, some elements usually visible in
Stellarium’s sky would also create unwanted views. Image a celestial grid or the Milky Way rotating with the
sky, and twilight stacking all up and flooding the long-time exposure. The trick implemented in this special
mode draws one frame in “normal” mode, and then suppresses those elements and other details which cause
only smeared images like screen labels. A moderately long “exposure” can therefore still successfully show
constellations or star labels.
This is an option probably only used by instructors or presenters and therefore not preconfigured for
beginners. To make use of it, you must assign a keyboard shortcut to the action “Toggle star trails” found in
the “Display Options” key shortcut actions (see 4.8). While the mode is on, tapping
Ctrl
resets the trails. It
can make a nice ending scene in a presentation: show a moderately slow moving sky, and activate it. The
sky will fill with curves, hopefully impressing your audience. You can also utilize it when talking about the
problem of satellite constellations now destroying the sky. (Use realistic view, not icons, for satellites.) Here
your time speed should not be too fast, else satellites will just show up as dot chain.
Note that screenshots have to be made with system means while this mode is running.
6.6 Spherical Mirror Mode for Planetarium Use
IMMERSIVE-THEATRES.COM
With Stellarium it’s very easy to project the sky on a dome and create your own planetarium.
6.6.1 360° Projection
You can use either a very expensive fisheye lens projector – or a standard projector with a spherical mirror.
Not only is spherical mirror projection less expensive, but it produces a higher resolution image on the
dome
8
, and it’s very easy to upgrade the projector.
A planetarium spherical mirror is curved like a security mirror (convex safety mirror) – with the
important difference that its ‘first surface’, i.e., the reflective silver, is not protected by a transparent acrylic or
polycarbonate layer. This allows light to be reflected without being refracted. Spherical mirrors are therefore
very delicate and should never be touched with fingers or wiped with a cloth. A powerful dust blower is all
you need to keep it clean.
There are two types of spherical mirror projection boxes: compact ‘Newtonians’ (spherical mirror with
an additional small mirror)
9
; or full-length boxes (spherical mirror only)
10
. The former take up less space in
the planetarium (but a little less light reaches the dome); whereas the latter produce a slightly brighter image
(but require more space in the planetarium).
8
https://domeclub.com/#PxComp
9
https://www.eplanetarium.com/projector_newtonian.php
10
https://myplanetarium.com/projection-dome-system
6.6 Spherical Mirror Mode for Planetarium Use 71
Although commercial projection boxes are quite expensive (mainly due to the cost of the first-surface
spherical mirror); it’s quite easy to build your own
11
– and you can use a cheap convex safety mirror for
testing before investing in a first-surface mirror.
6.6.2 Projector Specifications
A major challenge with digital planetariums (360° cinemas) is the cross-reflection of light on the dome. This
is why projector contrast ratio and colour saturation are more important than brightness (lumens). Light
‘bouncing’ around the dome causes the planetarium image to ‘wash out’ (lose colour) – so the higher the
projector colour saturation, the better. Similarly, the higher the contrast ratio, the sharper and crisper the
planetarium image will be, especially the night sky.
4K projectors are now very affordable, allowing you to deliver the same high-quality visuals in your
small dome as large planetariums!
6.6.3 Computer Configuration
The best way to operate a planetarium is with a dual display arrangement, i.e., computer screen as the primary
(main) display, and projector as the secondary (extended) display.
This way the Stellarium remote control window, desktop shortcuts, other applications, etc., will only be
visible to you. The audience will only see what you want them to see. To ensure there’s always something
nice on the dome (even with no application open), use a high-resolution image of stars as your desktop
wallpaper.
To function as a planetarium, Stellarium should be configured to open in full screen mode on the
extended display (see below).
6.6.4 System Configuration
To minimise image distortion at the back of the dome, it’s worth carrying out the slightly complex Meshmap-
per configuration
12
. This creates a custom distortion file for your specific system (i.e., your dome diameter,
stand height, spherical mirror dimensions); and the image improvement will be remarkable
13
. This custom
distortion file (‘warp mesh data file’) can then be used with dome applications like Stellarium.
6.6.5 Stellarium Configuration
To enable planetarium spherical mirror projection, the config.ini file needs to include the following:
[ navi gation ]
init _fov = 180
[ proj ection ]
type = Pr ojectio nFish eye
au to _z oom_out_r es ets_direc ti on = true
[ video ]
fullscreen = true
vi ewpor t_effect = sphe ri cMirr or Distort er
sc ree n_num ber = 1
[ s pheri c_mirror ]
di stort er_ma x_fov = 180
dome_ rad ius = 5.0 ( note : regardless of your actual dome radius )
im ag e_dista nc e_div_h ei ght = 2.67
mi rror_ posit ion_x = 0
mi rror_ posit ion_y = 5
mi rror_ posit ion_z = 0
mi rro r_rad ius = 0.37 ( regardless of your actual mirror radius )
Stellarium also has built-in options to help you project the best possible planetarium night sky. In a
planetarium, removing the Stellarium atmosphere results in a much darker (and more beautiful) night sky.
Yet without the atmosphere, the stars stop twinkling and meteors (shooting stars) disappear – which is correct
11
https://docs.worldwidetelescope.org/diy-planetarium-dome/1/dome/#setting-up-the-proje
ctor-and-mirrors
12
https://paulbourke.net/dome/meshmapper
13
https://domeclub.com/images/Meshmapper-1152w.jpg
72 Chapter 6. Advanced Options
for the real sky, but not what you may desire in the planetarium. To maintain twinkling and meteors even
without the atmosphere, manually add the following lines to the config.ini file:
[ stars ]
fl ag_forc ed_tw inkle = true
[ astro ]
fl ag _forced_m et eor_act iv ity = true
Another useful configuration for planetariums is to completely hide the vertical and horizontal toolbars
on the dome:
[ gui ]
fl ag_ show_ gui = false
The following are also recommended (adjust the values to your preference):
[ viewing ]
fl ag_mo on_sc aled = true
moon_scale = 8.00
[ astro ]
meteor_zhr = 3000
[ landscape ]
flag _fog = false
[ stars ]
ab solute_s cale = 6.00
fl ag_st ar_tw inkle = 1.00
fl ag_st ar_spiky = false
re lative_s cale = 0.70
st ar_twin kle_a mount = 0.50
6.6.6 Further notes
This feature is rarely used by the current developers and cannot be tested on standard hardware. See ongoing
discussion on Github
14
and get involved.
14
https://github.com/Stellarium/stellarium/issues/1914 and
https://github.com/Stellarium/stellarium/issues/3535
7. Landscapes
GEORG ZOTTI
Landscapes are one of the key features that make Stellarium popular. Originally just used for decoration,
since version 10.6 they can be configured accurately for research and demonstration in “skyscape astronomy”,
a term which describes the connection of landscape, the sky above, and the observer (D. Brown, 2015).
Configured properly, they can act as reliable proxies of the real landscapes, so that you can take e.g.
measurements of sunrise or stellar alignments (Zotti and Neubauer, 2015), or prepare your next moonrise
photograph, as though you were on-site.
In this chapter you can find relevant information required to accurately configure Stellarium landscapes,
using panoramas created from photographs taken on-site, optionally supported by horizon measurements
with a theodolite.
Creating an accurate panorama requires some experience with photography and image processing.
However, great open-source tools have been developed to help you on the job. If you already know other
tools, you should be able to easily transfer the presented concepts to those other tools.
While you are editing a landscape, you may want to reload it frequently. Turn off caching by editing the
config.ini:
[ landscape ]
ca che _size _mb = 0
7.1 Stellarium Landscapes
As of version 0.15, the available landscape types are:
polygonal
A point list of measured azimuth/altitude pairs, used to define a sharp horizon polygon. The area
below the horizon line is colored in a single color (Section 7.1.2).
spherical
The simple form to configure a photo-based panorama: A single image is used as texture map for
the horizon (Section 7.1.3).
old_style
The original photo panorama. This is the most difficult to configure, but allows highest resolution
by using several texture maps (Section 7.1.4).
fisheye
Another 1-texture approach, utilizing an image made with a fisheye lens. This landscape suffers
from calibration uncertainties and can only be recommended for decoration (Section 7.1.5).
A landscape consists of a
landscape.ini
plus the data files that are referenced from there, like a
coordinate list or the textures. Those reside in a subdirectory of the
landscape
folder inside the Stellarium
program directory, or, for own work, in a subdirectory of the
landscape
folder inside your Stellarium user
data directory (see section 5.1).
74 Chapter 7. Landscapes
Let us assume we want to create a landscape for a place called Rosenburg. The location for the files of
our new custom landscape Rosenburg depends on the operating system (see 5.1). Create a new subdirectory,
and for maximum compatibility, use small letters and no spaces:
Windows C:/Users/YOU/AppData/Roaming/Stellarium/landscapes/rosenburg
Linux ~/.stellarium/landscapes/rosenburg
Mac $HOME/Library/Application Support/Stellarium/landscapes/rosenburg
7.1.1 Location information
This optional section in
landscape.ini
allows automatic loading of site coordinates if this option is
activated in the program GUI (see 4.4.5). For our purposes we should consider especially the coordinates in
the location section mandatory!
[ location ]
planet = Earth
countr y = Austria
name = KGA Rosenburg
lati tude = +48 d38 ’ 3.3"
longitu de = +15 d38 ’2.8 "
alti tude = 266
time zone = Europe / Vienna
li ght_p ollution = 1
at mo sp he ric_extin ct io n_coefficie nt = 0.2
displ ay_ fog = 0
at mo spheric _temper at ure = 10.0
at mospher ic_pres sure = 1013.0
Where:
planet Is the English name of the solar system body for the landscape.
latitude
Is the latitude of site of the landscape in degrees, minutes and seconds. Positive values represent
North of the equator, negative values South of the equator.
longitude
Is the longitude of site of the landscape. Positive values represent East of the Greenwich
Meridian on Earth (or equivalent on other bodies), Negative values represent Western longitude.
altitude Is the altitude of the site of the landscape in meters.
country (optional) Name of the country the location is in.
state (optional) Name of the state the location is in.
timezone (optional) IANA Timezone code
name
(optional) Name of the location. This may contain spaces, but keep it short to have it fully visible in
the selection box.
Since v0.11.0, there are a few more optional parameters that can be loaded if the according switch is active
in the landscape selection panel. If they are missing, the parameters do not change to defaults.
light_pollution
(optional) Light pollution of the site, given on the Bortle Scale (1: none . . . 9: metropoli-
tan; see Appendix B). If negative or absent, no change will be made.
atmospheric_extinction_coefficient
(optional, no change if absent.) Extinction coefficient (mag/air-
mass) for this site.
atmospheric_temperature
(optional, no change if absent.) Surface air temperature (Degrees Celsius).
Used for refraction. Set to -1000 to explicitly declare “no change”.
atmospheric_pressure
(optional, no change if absent.) Surface air pressure (mbar; would be 1013 for
“normal” sea-level conditions). Used for refraction. Set to -2 to declare “no change”, or -1 to compute
from altitude.
display_fog
(optional, -1/0/1, default=-1) You may want to preconfigure setting 0 for a landscape on the
Moon. Set -1 to declare “no change”.
7.1.2 Polygonal landscape
This landscape type has been added to allow the use of measured horizons. Users of Cartes du Ciel
1
will be
happy to hear that the format of the list of measurements is mostly compatible.
1
SkyChart / Cartes du Ciel planetarium: https://www.ap-i.net/skychart/en/start
7.1 Stellarium Landscapes 75
This is the technically simplest of the landscapes, but may be used to describe accurately measured
horizon profiles. The file that encodes horizon altitudes can also be used in all other landscape types. If
present there, it will be used to define object visibility (instead of the opacity of the landscape photo textures)
and, if horizon_line_color is defined, will be plotted.
There are a few little caveats:
•
If you create a polygonal line with vertex azimuths 0, 90, 180, 270 (exactly), the horizon may not
show up at all. Add a tiny nonzero value to the global rotation, like
po ly gonal_a ngle_ro ta tez = 0.0000001
•
Sometimes, there may appear vertical lines from some corners towards the zenith or the mathematical
horizon, e.g. if there is a vertex including azimuth 0 or 180. If this irritates you, just offset this azimuth
minimally (e.g., 180.00001).
•
As technical requirement, the zenith is always assumed to remain free and uncovered. It is not possible
to define a “dome cutout” or similar restricted views out of a window. Such effect can be achieved
with a Spherical Landscape (see section 7.1.3).
The
landscape.ini
file for a polygonal type landscape looks like this (this example is based on the
Geneve landscape which was borrowed from Cartes du Ciel and comes with Stellarium):
[ landscape ]
name = Geneve
type = polygon al
author = Georg Zotti ; Horizon defi nit ion by Patrick Chevalle y
descr ipt ion = Hor izon line of Geneve .
Demon stra tes compati bility with
horizo n descrip tion s from Cartes du Ciel .
po ly gonal _h orizon_ list = hori zon_ Genev e . txt
po ly gonal_a ngle_ro ta tez = 0
groun d_co lor = .15 ,.45 ,.45
Where:
name appears in the landscape tab of the configuration window.
type identifies the method used for this landscape. polygonal in this case.
author lists the author(s) responsible for images and composition.
description
gives a short description visible in the selection panel. The text can be superseded by optional
description.<lang>.utf8 files.
polygonal_horizon_list is the name of the horizon data file for this landscape.
polygonal_horizon_list_mode
(optional) the two first columns in the list are numbers: azimuth and
altitude or zenith distance, in either degrees or radians or gradians(gon). The value must be one of
azDeg_altDeg
,
azDeg_zdDeg
,
azRad_altRad
,
azRad_zdRad
,
azGrad_altGrad
,
azGrad_zdGrad
.
Default: azDeg_altDeg
polygonal_angle_rotatez
(optional, default=0) Angle (degrees) to adjust azimuth. This may be used
to apply a (usually) small offset rotation, e.g. when you have measured the horizon in a grid-based
coordinate system like UTM and have to compensate for the meridian convergence.
ground_color
(optional, default=
0,0,0
, i.e., black) Color for the area below the horizon line. Each R,G,B
component is a float within 0..1.
minimal_brightness
(optional) Some minimum brightness to keep landscape visible. Default=-1, i.e.,
use minimal_brightness from the [landscape] section in the global config.ini.
minimal_altitude
(optional, default=-2) Some sky elements, e.g. stars, are not drawn below this altitude
to increase performance. Under certain circumstances you may want to specify something else here.
(since v0.14.0)
polygonal_horizon_inverted
(optional, default=false; only required in v0.15.0–0.20.2) In rare cases
like horizon lines for high mountain peaks with many negative horizon values this should be set to
true.
No longer used:
horizon_line_color
(optional, default: invisible) used to draw a polygonal horizon line. This is now a
v 24.4
global setting, config.ini:landscape/polygon_color.
76 Chapter 7. Landscapes
7.1.2.1 Artificial Polygonal Panoramas
The online service HeyWhatsThat
2
allows an SRTM-based analysis of the viewshed (the visible topographic
area) for an observing location which also gives names for the mountain peaks visible at a given location. In
summer of 2020 a dedicated landscape download option for Stellarium was added (see upper-right corner),
so that you can install a custom landscape. Its package/directory name is
stellarium-landscape
. If you
create more than one, you must rename the directory. You may also want to extend the scene description in
landscape.ini.
See section 7.3.4 for more options.
7.1.3 Spherical landscape
This method uses a more usual type of panorama – the kind which is produced directly from software such
as autostitch or Hugin
3
. The Moon landscape which comes with Stellarium provides a minimal example of
a landscape.ini file for a spherical type landscape:
[ landscape ]
name = Moon
type = spheric al
maptex = apol lo17 . png
A more elaborate example is found with the Grossmugl landscape:
[ landscape ]
name = Grossmu gl
type = spheric al
author = Guen ther Wuchterl , Kuffner - S ter nwa rte . at ;
Lightscape : Georg Zotti
descr ipt ion = Field near Leeberg , Gr ossmugl ( Ries entumulus ),
Austri a - Primary Obse rving Spot of the Grossmugl
Starlig ht Oasis - http :// starl ighto asis . org
maptex = gros sm ugl_lee be rg_crop 11 .25. png
maptex_top =11.25
maptex_fog = gr os sm ugl_lee be rg _fog_cr op 22 .5. png
ma ptex_fog _top = 22.5
ma ptex_ fog_b ottom = -22.5
mapte x_il lum = grossm ug l_ leeberg _i ll um_crop0 . png
ma ptex_il lum_b ottom = 0
an gle _rota tez = -89.1
mi nimal _b right ness = 0.0075
po ly gonal _h orizon_ list = hori zon_g ro ssmug l . txt
po ly gonal_a ngle_ro ta tez =0
mi nimal _alti tude = -1
Where:
name appears in the landscape tab of the configuration window. This name may be translated.
type identifies the method used for this landscape. spherical in this case.
author lists the author(s) responsible for images and composition.
description
gives a short description visible in the selection panel. The text will be superseded by
optional description.<lang>.utf8 files.
maptex is the name of the image file for this landscape.
maptex_top (optional; default=90) is the altitude angle of the top edge.
maptex_bottom
(optional; default=-90) is the altitude angle of the bottom edge. Usually you will not
require this, or else there will be a hole at your feet, unless you also specify
bottom_cap_color
(optional; default=
-1.0,0.0,0.0
to signal “no color”). If set, this is used to close
any hole in the nadir area (if maptex_bottom higher than -90).
maptex_fog (optional; default: no fog) is the name of the fog image file for this landscape.
2
https://www.heywhatsthat.com/
3
http://hugin.sourceforge.net/
7.1 Stellarium Landscapes 77
maptex_fog_top
(optional; default=90) is the altitude angle of the top edge of the fog texture. Useful to
crop away parts of the image to conserve texture memory.
maptex_fog_bottom (optional; default=-90) is the altitude angle of the bottom edge.
maptex_illum
(optional; default: no illumination layer) is the name of the nocturnal illumination/light
pollution image file for this landscape.
maptex_illum_top
(optional; default=90) is the altitude angle of the top edge, if you have light pollution
only close to the horizon.
maptex_illum_bottom (optional; default=-90) is the altitude angle of the bottom edge.
angle_rotatez
(optional, default=0) Angle (degrees) to adjust azimuth. If 0, the left/right edge is due
east.
tesselate_rows
(optional, default=20) This is the number of rows for the maptex. If straight vertical
edges in your landscape appear broken, try increasing this value, but higher values require more
computing power. Fog and illumination textures will have a similar vertical resolution.
tesselate_cols
(optional, default=40) If straight horizontal edges in your landscape appear broken, try
increasing.
polygonal_horizon_list
(optional) is the name of the (measured) horizon data file for this landscape.
Can be used to define the exact position of the horizon. If missing, the texture can be queried for
horizon transparency (for accurate object rising/setting times)
polygonal_horizon_list_mode (optional) see 7.1.2
polygonal_angle_rotatez (optional, default=0) see 7.1.2
minimal_brightness see 7.1.2
minimal_altitude
(optional, default=-2) Some sky elements, e.g. stars, are not drawn below this altitude
for efficiency. Under certain circumstances (e.g. for space station panoramas where you may have sky
below your feet, or for deep valleys/high mountains, you may want to specify something else here.
To save texture memory, you can trim away the transparent sky and define the angle
maptex_top
. Like-
wise,
fogtex_top
,
fogtex_bottom
,
maptex_illum_top
and
maptex_illum_bottom
. You should then
stretch the texture to a full power of 2 for maximum compatibility, like
4096× 1024
(but note that some
hardware is even limited to 2048 pixels). The easiest method to create perfectly aligned fog and illumination
layers is with an image editor that supports layers like the GIMP or Photoshop. Fog and Light images should
have black background.
7.1.4 High resolution (“Old Style”) landscape
The
old_style
or multiple image method works by having the 360°panorama of the horizon (without
wasting too much texture memory with the sky) split into a number of reasonably small side textures, and a
separate ground texture. This has the advantage over the single-image method that the detail level of the
horizon can be increased without ending up with a single very large image file, so this is usable for either
very high-resolution panoramas or for older hardware with limited capabilities. The ground texture can be a
different resolution than the side textures. Memory usage may be more efficient because there are no unused
texture parts like the corners of the texture file in the fish-eye method. It is even possible to repeat the horizon
several times (for purely decorative purpose). The side textures are mapped onto curved (spherical ring or
cylinder) walls (Fig. 7.1).
On the negative side, it is more difficult to create this type of landscape – merging the ground texture
with the side textures can prove tricky. (Hugin can be used to create also this file, though. And on the
other hand, you can replace this by something else like a site map.) The contents of the
landscape.ini
file for this landscape type is also somewhat more complicated than for other landscape types. Here is the
landscape.ini file which describes our Rosenburg landscape
4
:
[ landscape ]
name = KGA Rosenburg
author = Georg Zotti , VIAS / AST ROSIM
descr ipt ion = KGA Rosenb urg
type = old_sty le
nbsidet ex = 8
tex0 = Horiz -0. png
tex1 = Horiz -1. png
tex2 = Horiz -2. png
4
the groundtex grassground.png mentioned here has been taken from the Guereins landscape.
78 Chapter 7. Landscapes
Figure 7.1: Old_style landscape: eight parts delivering a high-resolution panorama. The bottom
(ground) texture, drawn on a flat plane, is not shown here.
tex3 = Horiz -3. png
tex4 = Horiz -4. png
tex5 = Horiz -5. png
tex6 = Horiz -6. png
tex7 = Horiz -7. png
nbside = 8
side0 = tex0 :0: 0:1:1
side1 = tex1 :0: 0:1:1
side2 = tex2 :0: 0:1:1
side3 = tex3 :0: 0:1:1
side4 = tex4 :0: 0:1:1
side5 = tex5 :0: 0:1:1
side6 = tex6 :0: 0:1:1
side7 = tex7 :0: 0:1:1
groundt ex = grass gro und . png
ground = groundtex :0 :0:1: 1
nb _deco r_repeat = 1
de cor_a lt_angle = 82
de cor_a ngle_ shift = -62
; Rotatez de viates from -90 by the M eridian Co nve rgen ce .
; The original landscape pano is grid - aligned ,
; not north - aligned !
de cor_ang le_ro tatez = -90.525837223
gr ound_ an gle_s hift = -62
gr ound_an gle_rot atez = 44.4 74162777
dr aw_gr ound_ first = 1
fogtex = fog . png
fo g_a lt_an gle = 20
fo g_ang le_shift = -3
fog = fogtex :0:0:1:1
calibrated = true
[ location ]
planet = Earth
7.1 Stellarium Landscapes 79
lati tude = +48 d38 ’ 3.3"
longitu de = +15 d38 ’2.8 "
alti tude = 266
li ght_p ollution = 1
at mo sp he ric_extin ct io n_coefficie nt = 0.2
displ ay_ fog = 0
at mo spheric _temper at ure = 10.0
at mospher ic_pres sure = 1013.0
Where:
name is the name that will appear in the landscape tab of the configuration window for this landscape
type should be old_style for the multiple image method.
author lists the author(s) responsible for images and composition.
description
gives a short description visible in the selection panel. The text will be superseded by
optional description.<lang>.utf8 files.
nbsidetex is the number of side textures for the landscape.
tex0 ... tex<nbsidetex-1>
are the side texture file names. These should exist in the
textures /
landscapes / landscape directory in PNG format.
light0 ... light<nbsidetex-1>
are optional textures. If they exist, they are used as overlays on top
of the respective
tex<...>
files and represent nocturnal illumination, e.g. street lamps, lit windows,
red dots on towers, sky glow by city light pollution, . . . Empty (black) panels can be omitted. They are
rendered exactly over the
tex<...>
files even when the PNG files have different size. If you need
your light pollution higher in the sky, you must use a spherical or fisheye landscape.
nbside is the number of side textures
side0 ...side<nbside-1>
are the descriptions of how the side textures should be arranged in the
program. Each description contains five fields separated by colon characters (
:
). The first field is the
ID of the texture (e.g.
tex0
), the remaining fields are the texture coordinates (
x0:y0:x1:y1
) used to
place the texture in the scene. If you want to use all of the image, this will just be 0:0:1:1.
groundtex
is the name of the ground texture file. (This could also be a diagram e.g. indicating the mountain
peaks!)
fogtex
is the name of the texture file for fog in this landscape. Fog is mapped onto a simple cylinder.
5
Note
that for this landscape, accurate overlay of fog and landscape is only guaranteed if
calibrated=true
and tan_mode=true.
nb_decor_repeat
is the number of times to repeat the side textures in the 360 panorama. (Useful photo
panoramas should have 1 here)
decor_alt_angle
(degrees) is the vertical angular extent of the textures (i.e. how many degrees of the full
altitude range they span).
decor_angle_shift
(degrees) vertical angular offset of the scenery textures, at which height the bottom
line of the side textures is placed.
decor_angle_rotatez
(degrees) angular rotation of the panorama around the vertical axis. This is handy
for rotating the landscape so North is in the correct direction. Note that for historical reasons, a
landscape with this value set to zero degrees has its leftmost edge pointing towards east.
ground_angle_shift
(degrees) vertical angular offset of the ground texture, at which height the ground
texture is placed. Values above -10 are not recommended for non-photographic content (e.g., a map)
due to high distortion.
ground_angle_rotatez
(degrees) angular rotation of the ground texture around the vertical axis. When
the sides are rotated, the ground texture may need to be rotated as well to match up with the
sides. If 0, east is up. if North is up in your image, set this to 90. Note that adjustments of
decor_angle_rotatez require adjustments of this angle in the opposite direction!
fog_alt_angle
(degrees) vertical angular size of the fog cylinder - how fog looks. Accurate vertical size
requires calibrated=true.
fog_angle_shift
(degrees) vertical angular offset of the fog texture - at what height is it drawn. Accurate
vertical placement requires calibrated=true.
draw_ground_first
if
true
or
1
6
the ground is drawn in front of the scenery, i.e. the side textures will
5
In very wide-angle views, the fog cylinder may become visible in the corners.
6
Boolean values true|false preferred since V0.19.3, but 0|1 are still accepted.
80 Chapter 7. Landscapes
overlap over the ground texture if ground_angle_shift > decor_angle_shift.
calibrated
(optional). Only if true,
decor_alt_angle
etc. really work as documented above. The
(buggy) old code was left to work with the landscapes already existing. Note that with “uncalibrated”
landscapes, sunrise computations and similar functionality which requires an accurate horizon line
will not work.
tan_mode
(optional, not used in this file). If true, the panorama image must be in in cylindrical, not
equirectangular projection. Finding
decor_alt_angle
and
decor_angle_shift
may be a bit
more difficult with this, but now (v0.13.0) works also with calibrated. A fog image created as overlay
on the pano will be perfectly placed.
polygonal_horizon_list (optional) see 7.1.3
polygonal_horizon_list_mode (optional) see 7.1.2
polygonal_angle_rotatez (optional, default=0) see 7.1.2
minimal_brightness (optional) see 7.1.2
minimal_altitude (optional) see 7.1.2
7.1.5 Fisheye landscape
The Trees landscape that is provided with Stellarium is an example of the single fish-eye method, and
provides a good illustration. The centre of the image is the spot directly above the observer (the zenith). The
point below the observer (the nadir) becomes a circle that just touches the edges of the image. The remaining
areas of the image (the corners outside the circle) are not used.
The image file (Fig. 7.2) should be saved in PNG format with alpha transparency. Wherever the image is
transparent Stellarium will render the sky.
The
landscape.ini
file for a fish-eye type landscape looks like this (this example is based on the Trees
landscape which comes with Stellarium):
[ landscape ]
name = Trees
type = fisheye
author = Robert Spearman . Light polluti on image : Georg Zotti
descr ipt ion = Trees in G reenlake Park , Seattle
maptex = trees_512 . png
mapte x_il lum = tre es_il lum_5 12 . png
maptex_fog = t rees_ fog_ 512 . png
texturefov = 210
an gle _rota tez = 17
te sselate_ rows = 28
te sselate_ cols = 60
Where:
name appears in the landscape tab of the configuration window.
type identifies the method used for this landscape. fisheye in this case.
author lists the author(s) responsible for images and composition.
description
gives a short description visible in the selection panel. The text will be superseded by
optional description.<lang>.utf8 files.
maptex is the name of the image file for this landscape.
maptex_fog (optional) is the name of the fog image file for this landscape.
maptex_illum
(optional) is the name of the nocturnal illumination/light pollution image file for this
landscape.
texturefov is the field of view that the image covers in degrees.
angle_rotatez (optional) Angle (degrees) to adjust azimuth.
tesselate_rows (optional, default=20) If straight edges in your landscape appear broken, try increasing.
tesselate_cols (optional, default=40) If straight edges in your landscape appear broken, try increasing.
polygonal_horizon_list (optional) see 7.1.3
polygonal_horizon_list_mode (optional) see 7.1.2
polygonal_angle_rotatez (optional, default=0) see 7.1.2
minimal_brightness (optional) see 7.1.2
minimal_altitude (optional) see 7.1.2
7.1 Stellarium Landscapes 81
Figure 7.2: Texture for the Trees Fisheye landscape.
7.1.6 Description
The short
description
entry in
landscape.ini
will be replaced by the contents of an optional file
description.<LANG>.utf8
.
<LANG>
is the ISO 639-1 language code, or its extension which contains
language and country code, like
pt_BR
for Brazilian Portuguese. The long description requires the file
description.en.utf8
, this is
en=english
text with optional HTML tags for sections, tables, etc. You
can also have embedded images in the HTML (Views of sacred landscapes, other informative images, . . . ?),
just make them PNG format please. The length of the description texts is not limited, you have room for a
good description, links to external resources, whatever seems suitable.
If you can provide other languages supported by Stellarium, you can provide translations yourself, else
Stellarium translators may translate the English version for you. (It may take years though.) The file ending
.utf8
indicates that for special characters like ÄÖÜßáé you should use UTF8 encoding. If you write only
English/ASCII, this may not be relevant.
7.1.7 Gazetteer
An optional feature for landscapes is a gazetteer function, i.e., labels for landscape features. The Grossmugl
landscape demonstrates an example and should be self-explanatory. This is again multilingual, so the files
are called gazetteer.<LANG>.utf8.
82 Chapter 7. Landscapes
# demo g a zetteer for Grossmugl la ndscape .
# Can be used to bette r d escribe the landscape ,
# i. e . show labe ls on l a ndscape feat u r es .
# Fie lds must be se parated by v ertical line ,
# la bel m ust not have such a verti c a l line .
# Comm e n ts have this ha sh mark in first colu mn .
# coordinates in degree s from true North .
# line t owards z enit h draws a singl e line str i c tly upw ard .
# la bel is cent e r ed on line endpo i nt .
# Azi m uth | A ltitude | de g rees | azi m uth | label
# | | tow a rds zen ith | shift |
11 3.66 | 5.5 | 4 | -6 | Le eberg
35 | 1.5 | 2.5 | 0 | G r o ssmugl
335 | 2 | 2 | 0 | Ste i n a b r u n n
305 | 2 | 1 | 0 | Ri n g e n d orf
180 | 2 | 2 | 0 | Vienna (30 km )
135 | 2 | 0.5 | 0 | Wind pow er pl ant St r a s shof
7.1.8 Packing and Publishing
You likely have developed your landscape already in your own Stellarium user data directory, but when you
are happy with your work, you may consider sharing it with other users. For easy distribution and installation
via Stellarium’s GUI (see section 4.4.5), you should create a ZIP file. This must contain
landscape.ini
and any textures and auxiliary files described above (
description.en.utf8
,
gazetteer.en.utf8
and
their translations, horizon files, images for the description . . . ) used by your landscape. If you want to release
the landscape for download, consider adding a
README.txt
clarifying license and usage conditions. It does
not matter whether the ZIP file contains a directory name inside the ZIP. If not, the directory name (ID) of
the landscape will be taken from the ZIP file name.
7.2 Creating Panorama Photographs for Stellarium
7.2.1 Panorama Photography
Traditional film-based panorama photography required dedicated cameras with curved film holders and
specialized lenses (Figure 7.3).
Digital photography has brought a revolution also in this field, and it has become quite easy to create
panoramas simply by taking a series of photographs with a regular camera on the same spot and combining
them with dedicated software.
A complete panorama photo visually encloses the observer like the mental image that astronomers
have been using for millennia: the celestial sphere. If we want to document the view, say, in a big hall
like a church, optimal results will be gained with a camera on a tripod with a specialized panorama head
(Figure 7.4) which assures the camera rotates around the entrance pupil
7
of the lens in order to avoid errors
by the parallax shift observed on photographs taken on adjacent but separate positions.
Often however, both the upper half of the observer’s environment (the sky) and the ground the photogra-
pher is standing on, are regarded of lesser importance, and only a series of laterally adjacent photographs is
taken and combined into a cylindrical or spherical ring that shows the landscape horizon, i.e., where ground
and sky meet. If the closest object of interest is farther away that a few metres, requirements on parallax
avoidance are far less critical, and the author has taken lots of landscape panoramas with a camera on the
usual tripod screw, and even more entirely without a tripod. However, any visible errors that are caused by a
shifted camera will require more effort in postprocessing.
When you have no tripod, note that you must not rotate the camera on your outstretched arm! Rather,
the camera’s entrance pupil must be rotated, so you should appear to dance around the camera!
The images should match in brightness and white balance. If you can shoot in RAW, do so to be able to
change white balance later. If the camera can only create JPG, ensure you have set the camera to a suitable
white balance before taking the photos and not to “auto”, because this may find different settings and thus
give colour mismatches. Exposure brightness differences can be largely removed during stitching, but good,
well-exposed original shots always give better results.
7
In many references you will find “Nodal Point” mentioned here. But see these:
https://en.wikipedia.org/wik
i/Cardinal_point_%28optics%29#Nodal_points
,
http://web.archive.org/web/20060513074042/http:
//doug.kerr.home.att.net/pumpkin/Pivot_Point.pdf
,
http://www.janrik.net/PanoPostings/NoPara
llaxPoint/TheoryOfTheNoParallaxPoint.pdf
7.2 Creating Panorama Photographs for Stellarium 83
Figure 7.3: Zenit “Horizon 202” panorama camera with rotating lens for 35mm film. (Source:
Wikipedia, “Horizon202” by BillC - Own Work. Licensed under CC BY-SA 3.0 via Wikimedia Commons -
https:
//commons.wikimedia.org/wiki/File:Horizon202.jpg)
Figure 7.4: Automated panorama head. (Source: Wikipedia
https://commons.wikimedia.org/wiki/Fil
e:Rodeon_vr_head_01.jpg)
84 Chapter 7. Landscapes
As a general recommendation, the images of a panorama should be taken from left to right, else please
accordingly invert some of the instructions given below.
There are several panorama making programs. Often they are included in the software that comes with a
digital camera and allow the creation of simple panoramas. Other software titles are available for purchase.
However, there is one cost-free open-source program that does everything we need for our task, and much
more:
7.2.2 Hugin Panorama Software
Hugin
8
, named after one of the ravens that sits on Odin’s shoulder and tells him about the world, is a
user-friendly catch-all package with graphical user interface that allows creating panoramas with a single
application. Actually, Hugin is a GUI application which calls several specialized sub-programs with fitting
parameters. The instructions are based on Hugin V2014.0 and 2015.0.
Typically digital images come in JPG format with information about camera, lens, and settings stored in
invisible metadata in the EXIF format. When Hugin reads such images, it can automatically derive focal
length, field of view, and exposure differences (exposure time, aperture, color balance) to create panoramas
as easily as possible.
After starting Hugin for the first time, select
Interface Expert
to release several options not visible to
“beginners”. In the Preferences dialog (
Files Preferences
), edit number of CPU to match the number of
cores in your computer and allow parallel processing. E.g., if you have an Intel Core-i7, you usually can set
up to 8 cores (4 cores with hyperthreading; but maybe leave one core for your other tasks while you wait for
a processing job?). If your PC is equipped with a modern programmable graphics card, you can enable its
use in the
Programs
tab with activating “Use GPU for remapping”.
After that, we are ready for creating our panoramas.
7.2.3 Regular creation of panoramas
The graphical user interface (GUI) consists of a main menu, symbols, and 4 tabs. We start on the tab Photos.
•
Add images. . .
Opens a file browser. Select the images which you want to stitch. Usually, lens data
(focal length, horizontal field of view
9
, . . . ) are read from the EXIF data. If those are not available
(e.g. cheap cameras, images scanned from film), you can enter those data on loading or later. The
images are now listed in the file list, and you can edit image parameters by marking one or more, and
then choosing from the context menu which you get from pressing the right mouse button. In case
you have used different lenses (or inadvertently used different focal lengths of a zoom lens), you can
assign separate lenses to the images.
Caveat: If you have resized the images, or produced copied on your RAW converter with non-native
resolution, the horizontal Field of View (FoV) in Hugin may be misidentified. You must edit lens
parameters and fill in the field of view from a full-size image. Else the first round of optimisation will
run into unsolvable trouble.
•
Select one image as position anchor (usually the center image), and one as exposure anchor (this can
be the same image). For our purpose, the anchor image should face south.
•
Next, we must find common feature points. The next field below provides the required settings. It
is recommended to use the CPFind command. To avoid finding control points in (moving) clouds,
select setting
Hugin’s CPFind + Celeste
10
. Then press
Create control points
. This opens a dialog box
in which you can see output of the selected feature point extractor. It should finish with a box telling
you the number of identified points. In rare cases some images cannot be linked to others, you will
have to manually add or edit feature points in those cases.
•
Now it’s time to start optimisations. On the
Geometric Optimimisation
combo, start with the button
Positions, incremental from anchor
, and press
Calculate
. Moments later, a first rough match is
available for inspection.
•
First open the Preview window (press
Ctrl
+
P
or click the blue icon). Assumed your images cover
the full horizon, the window shows an equirectangular area (360 degrees along the horizon and 180
degrees from zenith to nadir). The anchor image should be close to the image center, and the other
images should be already well-aligned to both sides. You can set the exact center point by clicking it
in the image. If the horizon appears badly warped, use the right mouse key and click on the horizon
8
http://hugin.sourceforge.net/
9
contrary to Stellarium, field of view (FoV) in Hugin means the horizontal extent in degrees.
10
If you forget this, you can remove cloud points by calling Celeste in the control point editor later
7.2 Creating Panorama Photographs for Stellarium 85
roughly near −90 or +90 degrees (halfway to the left or right).
•
Open the OpenGL preview window (press
Ctrl
+
Shift
+
P
or click the blue icon with GL inside).
This panel provides several important views:
–
The
Preview
tab is similar to the non-OpenGL preview. You can display an overlay of the
control points, which are colored according to match quality. Also, with button
Identify
activated, you see the overlapping image frames when you move the mouse over the image.
– The
Layout
tab helps finding links between images.
– The
Move/Drag
dialog may help to interactively adjust a panorama.
Sometimes the preview image may however be distorted and unusable.
•
Open the Control Points Table dialog (press
F3
or click the “table” button). Here you see the points
listed which link two images. Clicking a column label sorts by this column. It is recommended that
only neighboring overlapping images should be included here. If you have very large overlap, it is
possible that points are found between two images which are not directly adjacent. In the OpenGL
preview window, you can use the
Preview
or the
Layout
tabs to identify those image pairs. Such
points should be deleted. In the point table, click on columns “Right Img.”, then “Left Img.”, and then
find pairs like 0/2, 1/3, 2/4 etc. Mark those lines, and delete the points.
•
To re-run the optimisation, press the double-arrow icon or the
calculate
button in the Optimise/Geo-
metric area.
7.2.3.1 Preliminary Geometric Optimisation
Now the (usually) longest part begins: Iterative optimisation of the photo matchpoints. If your images were
taken on a panorama tripod head, there should only be very few bad matchpoints, e.g. those found on persons
or clouds
11
which have moved between photos. For handheld photos, the following considerations should be
observed.
The most important line which we want to create in all perfection is the visible horizon, where sky and
earth meet. The foreground, usually grassy or rocky, is of lesser interest, and stitching errors in those areas
may not even be relevant.
Therefore, matchpoints with large errors in the foreground can be safely removed, while, if necessary,
points on the horizon should be added manually. Use the
Control Points
tab, select adjacent images (start
with 0 on the left and 1 on the right side), and delete the worst-fitting matchpoints closest to the camera (near
the bottom of the images). We now start a long phase of re-optimizing and deletion of ill-matching points as
long as those are far from the horizon. When all near matchpoints are deleted, the result should already look
not too bad.
For continued optimisation, the number of parameters to optimize can be extended. To begin, I
recommend
Positions and View (y, p, r, v)
, which may find a new focal length slightly different from the data
in the EXIF tags. Again, delete further foreground points. If after a few rounds you still have bad point
distances, try
Positions and Barrel Distortion (y, p, r, b)
to balance distortion by bad optics, or even go up to
Everything without translation
. Optimisation can only reach perfect results if you did not move between
exposures. Else, find a solution which shows the least error.
In case you took your photos not on a tripod and moved too much, you may even want to play with the
translation options, but errors will be increasingly hard to avoid.
Using Straight Edges as Guides
If the panorama contains straight lines like vertical edges of buildings, these can be used to automatically
get a correctly leveled horizon: Vertical lines are mapped to vertical lines in equirectangular panos! In the
Control Points
tab, select the image with the vertical edge in both subframes, and mark points on the vertical
edge. (switch off auto-estimate!). Likewise, horizontal lines may help, but make sure lines like rooves are
perpendicular to your line of view, else the perspective effect causes an inclination.
Multi-ring Panoramas
If you are trying to create a panorama with several rings (horizon, one or two rings below, and nadir area),
you must try to create/keep control points that best give a result without visible seams. In this case, and esp.
if you have only used a regular tripod or even dared to go for a free-handed panorama, you may observe that
it is best to remove control points in neighboring photos in the lower rings, but keep only the “vertical” links
between images with similar azimuth.
In total, and if the foreground is not important but only grassy or sandy, the rule of thumb is that the
horizon images must be strongly linked with good quality (small errors), while images in the lower rings
should be linked mostly to their respective upper photos, but not necessarily to the images to its sides. The
11
You should have created control points with the Celeste option!
86 Chapter 7. Landscapes
resulting panorama will then show a good horizon line, while stitching artifacts in a grassy or otherwise only
decorative ground will usually be acceptable and can, if needed, be camouflaged in post-processing.
This optimization and editing of control points is likely a longish iterative process, and these are the late
night hours where you will finally wish you had used a panorama head. . .
7.2.3.2 Masking
If you have images with overlapping areas, you can usually not force Hugin to take pixels from the image
which you find best. you can however mask off an area from an image which you don’t want to see in the
output under any circumstances, e.g. a person’s arm or foot in one image. Just open the image in the
Mask
tab and either press
Add new mask
and draw the mask polygon covering the unwanted area, or use the crop
settings to define rectangular areas to use.
7.2.3.3 Exposure disbalance
In the
Photos
tab, select
Photometric parameters
on the right side. The EV column lists the Exposure Value.
If you see disbalance here and in the preview window, you can run a photometric optimization with the
lowest button on the
Photos
tab. Simply select Low dynamic range and press
Calculate
. The preview
should now show a seamless image. If all else fails, you can edit the EV values directly.
Advanced photographers may want to correct exposures in their RAW images before creating JPG or
TIF images to combine with Hugin. This unfortunately may create exposure disbalance because the EXIF
tags may not be adjusted accordingly, so based on different exposure/f-stop combinations Hugin may think
it has to re-balance the values. In these cases, don’t run the photometric optimizer. Some image exposure
values have to be changed manually, and the effect supervised in the preview window. Usually the smooth
blending in the subprogam enblend called by Hugin will hide remaining differences.
7.2.3.4 Stitching
When you are happy with the panorama in the preview window and the match-points promise a good fit, it is
time to finally create the panorama image. Hugin can create a large number of different projections which
all have their application. For Stellarium, we can only use the equirectangular projection. You still have 2
options:
spherical
landscapes (see 7.1.3) require single equirectangular images, the maximum size depends on your
graphics hardware and Qt limitations and is likely not larger than 8192× 4096 pixels.
old_style
landscapes (see 7.1.4) can use several textures for the ring along the horizon, and one image for
the nadir zone. If you need high resolution, you should aim for creating this one.
Sometimes, creating the nadir zone is difficult: this is where usually the view is blocked by the tripod,
and we are not interested in views of tripod or our own feet. For our purpose it is usually enough to fill in
the feet area using the clone stamp, or a monochrome color, or, for
old_style
landscapes, you can instead
insert an oriented site map or wind rose.
There is a button
create optimal size
in Hugin. It may recommend a panorama width around 13.000
pixels for an average camera and photos taken with a wide-angle lens. Increasing this size will most likely
not lead to higher optical resolution! The panorama width which you can most usefully create depends on
the resolution of the source images (which leads to the result given by Hugin) and on your needs. If you need
arc-minute resolution, you would aim for
360× 60 = 21600
pixels, which cannot be loaded into graphics
memory in a single piece, i.e., is too large for Stellarium, and must be configured as
old_style
landscape.
In this case, 10 or 11 tiles of 2048 × 2048 pixels (totalling 20480 or 22528 pixels) is the closest meaningful
setting, i.e., you could create an image of 20480 pixels width and cut this into usable pieces. Usually, a
size of
4096× 2048
or
8192× 4096
pixels (for better computers) is enough, and can be used in a
spherical
landscape.
We have to edit the file after stitching, therefore select creation of an image in the TIFF format. LZW
compression is non-lossy, so use this to keep file size reasonably small.
For regular images, it is enough to create “Exposure corrected, low dynamic range”. If you have a
problem with persons that have moved between your images, you may want to post-process the final result
with import of the distorted sub-images and manually defining the best blending line. For this, find the
“Remapped Images” group and again activate “Exposure corrected, low dynamic range”.
Now, press the
Stitch!
button in the lower right corner. This opens a helper program which supervises
the stitching process. Depending on your computer and size of the image, it will require a few minutes of
processing.
In case stitching fails with a cryptic error message, try to add the option --fine-mask to the enblend
options.
Store a copy of the Hugin project file to always be able to go back to the settings you used to create the
7.3 Panorama Postprocessing 87
last panorama. We will get back to it when we want to make a truly calibrated panorama (see 7.3.3).
7.3 Panorama Postprocessing
The image created has to be further processed to be used in Stellarium. The most obvious change is the
need for a transparent sky, which we can easily create in programs like Adobe Photoshop or the free and
open-source GIMP. I will describe only the free and open-source solution.
After that, we have to bring the image into shape for Stellarium, which may include some trimming.
While we could also slice an image with interactive tools, higher accuracy and repeatable results can be
achieved with command-line programs, which makes the ImageMagick suite the tool of our choice.
7.3.1 The GIMP
The GIMP (GNU Image Manipulation Program) has been developed as free alternative to the leading
commercial product, Adobe Photoshop. While it may look a bit different, basic concepts are similar. Not
everybody can (or wants to) afford Photoshop, therefore let’s use the GIMP.
Like Photoshop, the GIMP is a layer-aware image editor. To understand the concept, it is easiest to
imagine you operate on a growing stack of overhead slides. You can put a new transparent slide (“layer”) on
top of the stack and paint on this without modifying the lower layers.
A few important commands:
Zooming
Ctrl
+
Mouse Wheel
Layer visibility and transparency
Make sure to have layer dialog shown (
Windows Dockable Dialogs
).
A gray bar indicates opacity for the currently active layer. Note the mouse cursor in this opacity
bar (often also called transparency bar): near the top of the bar the upward pointer immediately sets
percentage. A bit lower the pointer looks different and can be used for fine-tuning.
The most obvious post-processing need for our panorama is making the sky transparent. The optimal
tool usually is the “Fuzzy Select”, which is equivalent to the “Magic Wand” tool in Photoshop. Simply
mark the sky, and then delete it. The checkerboard background indicates transparent pixels.
It sometimes helps to put an intensive bright red or blue background layer under the panorama photo to
see the last remaining clouds and other specks. In the layer dialog, create a new layer, bucket-fill with blue
or red, and drag it in the layer dialog below the pano layer. Write-protect this layer, work on the image layer,
and before exporting the image layer with transparent sky to PNG, don’t forget to switch off the background.
We need this layer functionality especially to align the panorama on a calibration grid, see section 7.3.3.
7.3.2 ImageMagick
ImageMagick (IM)
12
can be described as “Swiss Army Knife of image manipulation”. It can do most
operations usually applied to images in a GUI program, but is called from the command line. This allows
also to include IM in your own command scripts
13
. We will use it to do our final cut and resize operations. I
cannot give an exhaustive tutorial about more than a few of IM’s functions, but the commands given here
should be enough for our purpose.
To open a command window (console, a.k.a. DOS window), press the Windows key and enter
cmd
, then
press . (On Linux and Mac, you surely know how to open a console window.)
There are some things you might need to know:
•
The command line is not your enemy, but a way to call expert tools.
•
The Windows command line processor cmd.exe is far from user friendly.
•
There are remedies and alternatives. See notes on clink (7.5.3) for a considerable improvement, and
WSL (7.5.4) for experts.
7.3.2.1 Command-line magick for spherical landscapes
Let’s start with the commands for final dressing of an equirectangular panorama to be used as spherical
landscape which has been created in size
4096× 2048
, but where you have seen that nothing interesting is in
the image above 11.25°. This means we can cut away the sky area and compress the image to
4096× 1024
to
save graphics memory.
14
12
https://www.imagemagick.org/
13
These may typically be .BAT files on Windows, or various shell scripts on Linux or Mac.
14
Most modern graphics cards no longer require the “powers of two” image sizes, but we keep this practice to increase
compatibility.
88 Chapter 7. Landscapes
To understand the numbers in the example, consider that in a panorama image of
4096× 2048
pixels,
1024 pixels represent 90°,
512px = 45
°,
256px = 22.5
°,
128px = 11.25
°. To keep a top line of
11.25
°, we
keep an image height of 1024+ 128 = 1152px, but the crop starts at pixel Y = 1024− 128 = 896.
conver t lan dscape . png - crop 4096 x1152 +0+896
- resize 4096 x1024 ! la ndscape _crop ped . png
Note the exclamation mark in the -resize argument, which is required to stretch the image in a non-
proportional way.
Alternatively, you can operate with IM’s “gravity”, which indicates the corner or edge geometric offsets
are referred to. Given that we want the lower part of the image to exist completely, you only need to compute
the size of the cropped image:
conver t lan dscape . png - gra vity SouthWe st - crop 4096 x1152 +0+0
- resize 4096 x1024 ! la ndscape _crop ped . png
You still need the addition
+0+0
in the -crop option, else the image will be cut into several pieces. In the file
landscape.ini, you then have to set maptex_top=11.25.
7.3.2.2 Command-line magick for old_style landscapes
Let us assume we want to create a high-resolution landscape from a pano image of width 16384 which we
have carefully aligned and calibrated on an oversized grid template that also shows a measured horizon line
(see 7.3.3). Usually it is not necessary to create the full-size image, but only the horizon range, in this high
resolution. Assume this image has been aligned and justified on our grid image and is
HEIGHT
pixels high,
the left border is at pixel
X_LEFT
, and top border (i.e., the point where relevant content like the highest tree is
visible) is on pixel
Y_TOP
. Assume our graphics card is a bit oldish or you aim for maximum compatibility,
so we can load only textures of at most 2048 pixels in size. Given that the horizon area usually only covers a
few degrees, a vertical extent of
2048px
seem a pretty good range for that most interesting zone. The ground
can then be filled with some low-resolution image of grass, soil, or a properly oriented site map, or you can
use Hugin to create a ground image (and using the maximum of
2048× 2048
also here usually is far more
than enough).
In GIMP (or Photoshop, . . . ), we must find the values for
X_LEFT
,
Y_TOP
and
HEIGHT
.
HEIGHT
is being
resized to 2048, strictly, by the exclamation mark in the resize command. We can create our image tiles
now with this singular beast of a command line (write all in 1 line!), which puts our files directly into
STELLARIUM_LANDSCAPEPATH/LANDSCAPE_NAME:
conver t PANO . png - crop 16384 xHEIGH T + X_LEFT + Y_TOP + repage
- resize 16384 x2048 !
- type TrueC olorM atte -depth 8
- crop 2048 x2048 + repage
png : ST ELLARIU M_ LANDSCA PE PATH / L ANDSC APE_NAME / Horiz -% d. png
This creates 8 images. See section 7.1.4 for the
landscape.ini
where these images can be referenced.
Don’t forget to read off top and bottom lines (altitudes in degrees) from your grid, the vertical extent will
form the decor_alt_angle, and the bottom line the decor_angle_shift entries in this file.
Creating a ground image for old_style landscapes
When you want a good ground image for an
old_style
landscape from your panorama and not just fill the
groundtex
with a monochrome texture or a map, you have to create a ground view in Hugin. But you may
have already created a huge pano! This can also be used as source image, and a ground shot can be extracted
with a reversed operation. In principle, all you need to know is the field of view around the nadir. Figure 7.5
shows a simple configuration file.
Say, the side panels extend down to
decor_angle_shift=-44
degrees, which means you must close
the ground with a Nadir
FoV = 2× (90− 44)= 92
. For maximum compatibility, we will again make an image
of width and height both 2048
px
. These values can be found in the
p
line in Figure 7.5. The
i
line describes
the input image, which is our full equirectangular pano of width
w= 16384
and height
h= 8192
. The last
argument of that line is the image file name.
For processing, we do not use the Hugin GUI, but simply the command line. The actual program to call
is nona. If your stitched panorama is a 16-bit TIFF, nona will also make a 16-bit image, but our textures are
limited to 8-bit PNGs. We apply our most useful tool, convert from the ImageMagick suite.
nona -v -m PNG ground . pto -o ground . png
conver t ground . png - depth 8 gr oun d_8b it . png
7.3 Panorama Postprocessing 89
# hugin project file
# h ugin_ ptove rsion 2
p f0 w2048 h2048 v92 E0 R0 n" TIFF_m c : LZW r : CROP "
m g1 i0 f0 m2 p0 .00 784 314
# image lines
# - hugin c ropF act or =1
i w16384 h8192 f4 v360 Ra0 Rb0 Rc0 Rd0 Re0 Eev0 Er1 Eb1 r0
p90 y0 TrX0 TrY0 TrZ0 Tpy0 Tpp0 j0 a0 b0 c0 d0 e0 g0 t0
Va1 Vb0 Vc0 Vd0 Vx0 Vy0 Vm5 n" Eqir ect_P ano36 0 . png "
Figure 7.5: Project file
ground.pto
usable to create the ground image with Hugin or, on the
command line, its nona stitcher. The last line, starting with
i
, has been wrapped, but must be 1 line.
The file ground_8bit.png is then used in the groundtex field on landscape.ini.
7.3.3 Final Calibration
The creation of a calibrated panorama (which can be regarded as dependable proxy for further measurements
taken inside Stellarium) requires reference measurements to match the photos against. We must take
azimuth/altitude measurements with a theodolite or total station, in the optimal case along the full horizon,
and in addition I recommend to take azimuth and altitudes of some distinct features along the horizon which
must also be visible in the photographs: mountain summits, electrical towers, church towers, . . .
I recommend you create grid templates of the sizes you are going to create, e.g. 4096, 8192, 16386 and
20480 pixels wide with some diagram tool. On these, you can then also draw the measured horizon line.
Now, load a panorama on top of this in the GIMP, i.e., copy it into a separate layer over the grid image,
and set it semi-transparent.
Try to align the center of the image (where the geometric anchor has been defined; remember: this
should be the image pointing south!) with the measured horizon line or the distinct features.
The optimal solution consists of a photo panorama which aligns perfectly with the measured line and
features. We now have to iteratively bring deviations to a minimum. The process depends on processor
speed, image size, your training and – most of all – your requirements in accuracy!
In the GIMP, load your grid image with horizon line. Now select
File Open as Layers. . .
, load your
photo panorama, and then set layer transparency in the
Layers
dialog to about 50%.
Select the double-arrow tool to move the panorama via mouse drag and cursor keys over the grid, and
align the outline of the photo horizon’s southern point with the measured line. Now it’s time to estimate the
quality of the panorama.
In Hugin’s
Photos
tab, select the
Positions
view on the right side. Now you see “Yaw”, “Pitch” and
“Roll” values of camera-to-world orientation listed in the photos list. It should now be possible, by changing
the values only for the anchor image and re-optimizing, to come to a panorama with only minimal error. In the
process, start with Optimizing
Positions incremental from anchor
, then go for view and barrel optimization,
and so on. Always try to remove foreground match points which have large error and are irrelevant for the
task to match the horizon. Those are especially cross-matches of horizon and sub-horizon rows of images.
Only vertically and horizontally adjacent images should be required to match. For handheld panoramas, also
links between adjacent images in the non-horizontal rows are usually too erroneous to be useful, just remove
these match points. Use the
Layout
tab in the Fast Panorama Preview to see the relations between images
(Fig. 7.6): Red lines have big errors, green lines are good, thin gray lines indicate possible overlap without
specified match points. After each optimization step, export a new pano image, load as layer in GIMP, and
check again.
90 Chapter 7. Landscapes
Figure 7.6: Hugin’s Fast Panorama Preview can be used to check which images are connected to its
neighbors. Most important are good matches along the horizon, the images in the lower rows are
clearly less important. If captured on a tripod, they should still match.
Basic rules to observe (use obvious inverses).
•
If image aligns well in azimuth but overshoots the grid to the right: Increase yaw accordingly
(0.022°/pixel if image is 16384 pixels wide).
•
If the north end (left and right borders) is higher than the southern contact point: Increase pitch
angle.
•
If north and south points are OK, but the western (right) half is higher than the eastern (left) half:
Increase Roll angle.
The corrections required for pitch and roll may be surprisingly small!
Within a few rounds of adjustments, panorama creation, adding as layer in the image editor, and
comparing to the reference data, you should achieve a match to fit your needs.
In case you have taken photographs in several rings but without a panorama tripod, you may have to first
align only the horizontal images (deselect the lower images to exclude from optimization), and when the
horizon ring is aligned perfectly, deactivate further optimization in Hugin for those photos while “attaching”
(optimizing) the lower photos. In Hugin’s
Photos
tab, select
Optimize Geometric Custom Parameters
.
This opens an extra tab
Optimizer
, where you can fine-tune your needs: Switch off all variables for the
photos in the horizon ring, and make sure the lower photos fit in the preview after optimization.
It may even help to define that the lower rows have been taken with a different Lens, so the field of view
and distortion settings of the horizon row will be used as it had been found during the horizon-only match.
By now you should have enough experience what level of error may be acceptable for you.
7.3.4 Artificial Panoramas
You do not have to visit a site to create a panorama from your own photographs. There is dedicated software
that can process free and proprietary geodata.
A classic for archaeoastronomers is Andrew Smith’s Horizon
15
which can process SRTM 1” data which
are freely available.
A web service similar to HeyWhatsThat (see 7.1.2.1), PeakFinder
16
, creates a polygonal line and
black/white landscape feature renderings and also allows downloading the horizon as installable landscape
15
urlhttp://www.agksmith.net/horizon/
16
https://www.peakfinder.com
7.3 Panorama Postprocessing 91
for Stellarium. A great feature of this service is the excellent gazetteer (peak identification) also visible on
the website.
BRIAN DOYLE has created another online service, Skyliner
17
, computing a panorama in the web browser.
A gazetteer can be created manually. A similar website that can also export Stellarium landscapes is DAVID
HOYLE’s Panorama
18
. He also released his program, which can process SRTM and even Lidar data on
Github
19
.
I have created a website
20
where you can enter geographical coordinates and download a file
pano.kml
which helps with image creation from Google Earth imagery. Store this file for a site, let us call it MYPLACE,
into a new directory GE_MYPLACE inside your landscapes directory.
Store all scenes visible from the respective viewpoint MYPLACE as picture into one common folder
in your
landscapes/GE_MYPLACE
under the viewpoint name, e.g.,
75-30.jpg
, which means 75 degrees
from Nadir, azimuth 30 degrees. Also, double-click the pano entry or the marker in Google Earth to
open a window with the basic content of your
landscape.ini
. Copy and paste from there into a new
file
landscape.ini
and adjust the obvious entries. Complete as required with the entries described in
section 7.1.3.
On loading of the images, Hugin will not be able to detect any EXIF lens data and ask you for the
horizontal field of view. Enter 60 degrees, which is the standard value for Google Earth screenshots
21
.
The viewpoint names translate almost directly to the yaw and pitch angles which you can enter in the
image list in Hugin’s
Photos
tab. For example, switch to the
Positions
display on the right window edge in
the
Photo
tab, mark all images that start with
25-
and assign a pitch angle of
−90+ 25 = −65
. The second
part of the names is directly the azimuth. In this case, don’t run the optimizer, but you can immediately
set an output resolution and stitch (see 7.2.3.4). To get rid of the image decorations (compass etc), apply
masks
22
. Post-processing steps are the same as for photo-panoramas: make sky invisible, crop, etc.
It is also interesting to switch on the 3D buildings layer before creating the images. If temples or other
buildings are accurate, this will give an even closer approximation to what would be visible on-site. Note
however that not every building will be modelled in usable quality, and that usually vegetation is not included
in the 3D buildings layer. Also, if you are too close to buildings, they may be cut away by the near clipping
plane of the rendering.
These images, based on Google Earth imagery and the SRTM topographic model, seem usable as first
rough approximation to a photo-based or surveyed panorama. Note that it is definitely not accurate enough
for representing nearby horizon features or critically important mountain peaks, and please note that Google
has image copyright which at least requires you to acknowledge when displaying these pictures.
7.3.5 Nightscape Layer
Since version 0.13, Stellarium can simulate artificial illumination, like streetlamps, bright windows, or the
skyglow over cities (Zotti and Wuchterl, 2016). One way to create this layer is to make 2 panorama series
during the day and night and process these in the same Hugin project to align those photos, and then stitch
two separate images by selecting either the daylight or the nighttime shots. The night panorama has to be
processed to remove stars, airplanes, etc.
The other way is a simple layer overpainted in the image processing program. As rough recommendation,
use several layers to prepare this feature:
•
Put a semitransparent black layer over your daylight image, this helps you to place your painted
pixels.
•
Paint windows, street lamps, signs, . . . . You may apply a layer style to produce some glow.
•
To draw an impression of more light in the atmosphere (city skyglow), use a gradient with some
brownish color. Generally the color depends on the appropriate mix of city lights (sodium, mercury
vapour, etc.). Note that on the city outskirts a simple vertical gradient will not work, towards the city
the horizon is much brighter. Use a huge but weak brush to make a more spotty sky.
•
Use the existing landscape as template for the layer mask for this gradient sky layer. (You want to
hide skyglow by leaves in the foreground!)
17
https://archaeoastronomyireland.github.io/skyliner/
18
https://www.standingstones.org/viewer.html
19
https://github.com/davidjhoyle/OpenPanorama
20
https://gzotti.github.io/panoCam.html
21
Note that if you work with Google Earth Pro, you can create different FoV!
22
There is a wide overlap in the images to allow generous trimming.
92 Chapter 7. Landscapes
•
If you want to add only a few lights to an
old_style
landscape, you need to provide only the panels
showing those lights. Just load a side panel for reference, place a new layer on top, and paint the
lights on windows, lamps etc. There is no light option for the ground texture. This makes
old_style
landscapes best suited for localized light pollution, not city skyglow.
The resulting image is then declared in the
maptex_illum
line of
landscape.ini
. Try also to balance
the global strength of light pollution with the
light_pollution
key, and a probable minimal brightness
with the minimal_brightness key.
Try to match the visual appearance, not necessarily what photographs may have recorded. E.g., the
Grossmugl sky shows horizon glow mostly towards the city of Vienna, where long-time exposures may
already be saturated.
The possibilities seem limited only by your time and skills!
7.4 Troubleshooting
If something does not work as described and Stellarium does not show your landscape as expected but maybe
just a bright magenta-colored box, don’t panic. Double and triple-check the entries in
landscape.ini
.
Make sure the texture is in PNG format and the file name is correct. Check the logfile for error messages.
If the image is too large, it will be re-scaled on loading, but it is more efficient to keep images as small as
required. Only few systems can use textures larger than
16384× 16384
Pixels. If you need high resolution,
use the old_style type (see section 7.1.4).
7.5 Other recommended software
Here is a short collection of other useful programs for (panorama) image manipulation and other tasks on
Windows.
7.5.1 IrfanView
IrfanView is a free image viewer for Windows with many options. It can show almost any image format,
including several camera RAW formats, in windowed and full-screen mode. It is definitely preferable over
any image viewer built into Windows. Unfortunately however, it has no panorama viewer function!
7.5.2 FSPViewer
FSPViewer
23
by Fulvio Senore is an excellent panorama viewer for equirectanglar images. Images centered
along the horizon can be viewed directly, while settings for images with different minimum and maximum
angles, as well as “hotspots” (similar to hyperlinks) which move to neighboring panoramas, can be configured
in an .FSV text file like figure 7.7.
ImageNa me = H orizo n_Ros enbur g . jpg
Windo wTi tle = Hori zon_R osenb urg
hFov =70
# Formula : HP =100*( h/2 - upper )/( lower - upper ) in Hugin crop , or
# HP =100* zer oRow / img Height
Ho rizon Position =33.8
Figure 7.7: FSP configuration file (example)
7.5.3 Clink and GNUWin32
Clink
24
is a command line enhancement for Windows developed by Martin Ridgers. If you have ever worked
under a Linux bash-like command line, you will easily feel that Windows’ cmd.exe is extremely limited.
Clink provides several useful features, most notably a really usable command-line completion. It is not
essential for our tasks, but a general improvement of usability of the Windows command line which else has
not caused me any trouble.
23
Further details are available on its home page http://www.fsoft.it/FSPViewer/.
24
http://mridgers.github.io/clink/
7.5 Other recommended software 93
Compared to Linux, the command line of Windows can still be a humbling experience. None of the
wonderful helpers taken for granted on Linux are available. Many of the nice tools known and taken for
granted by Linux users (make, sed, awk etc.) have also been made available as standalone commands for
Windows. If you don’t need the inline scripting capabilities in
Makefile
s which you would get from a more
complete Linux installation but just want to call awk or sed inside your .BAT scripts, maybe this is enough.
7.5.4 WSL – Windows Subsystem for Linux
Finally, the 64-bit editions of Windows 10 come with an optional feature that allows you to install a complete
Linux distribution like Ubuntu inside your Windows system. Combined with an X11 server like XMing
25
,
you can even run graphic applications like Stellarium, and all the command-line tools are available.
25
https://sourceforge.net/projects/xming/
8. Deep-Sky Objects
Since version 0.10.0 Stellarium uses the “json” cataloguing system of configuring textures. At the same time
the Simbad online catalogue was added to the search feature, making the catalog somewhat redundant and
used now only as a first search point or if there is no Internet connection.
If the object has a name (not just a catalogue number), you should add one or more records to the file
.../nebulae/default/names.dat
(where
...
is either the installation directory or (preferably) the user
directory). See section 8.1.2 Modifying names.dat for details of the file format.
If you wish to associate a texture (image) with the object, you must add a record to the file
.../nebulae/default/textures.json
See section 8.1.3 for details.
If you wish to associate an outline with the object, you must add the series of lines to the file
.../nebulae/default/outlines.dat. See section 8.1.4 for details.
8.1 Stellarium DSO Catalog
Stellarium’s DSO Catalog contains over 94000 objects
1
(up to
15.5
m
for galaxies) and is available for end
users as collection of files:
catalog.txt Stellarium DSO Catalog in ASCII format for editing data
catalog.dat Stellarium DSO Catalog in zipped binary format for usage within Stellarium
2
names.dat List of proper names of the objects from file catalog.dat
An edited ASCII file can be converted into binary format through enabling an option in the file
config.ini (See 5.4):
[ devel ]
co nvert_d so_ca talog = true
The file
catalog.txt
should be put into the directory
.../nebulae/default/
and you should create
an empty file
catalog.pack
to storing the binary catalog. After converting the data into binary format you
should gzip them by the command
gzip -nc catalog . pack > catalog . dat
Stellarium DSO Catalog contains data and supports the designations for follow catalogs
3
:
NGC New General Catalogue
IC Index Catalogue
M Messier Catalog
1
An extended edition of this catalog with over one million objects may be downloaded and installed manually (see
section 5.5.2).
2
The file name
catalog-VERSION.dat
is used for extended edition of DSO Catalog, where VERSION is version
of catalog.
3
Abell Catalog of Planetary Nebulae was added in v0.18.2 and removed in v0.20.1
96 Chapter 8. Deep-Sky Objects
C Caldwell Catalogue
B Barnard Catalogue (Barnard, 1927)
SH2 Sharpless Catalogue (Sharpless, 1959)
vdB van den Bergh Catalogue of reflection nebulae (van den Bergh, 1966)
RCW
A catalogue of H
α
-emission regions in the southern Milky Way (Rodgers, Campbell, and
Whiteoak, 1960)
LDN Lynds’ Catalogue of Dark Nebulae (Lynds, 1962)
LBN Lynds’ Catalogue of Bright Nebulae (Lynds, 1965)
Cr Collinder Catalogue (Collinder, 1931)
Mel Melotte Catalogue of Deep Sky Objects (Melotte, 1915)
PGC HYPERLEDA. I. Catalog of galaxies
4
UGC The Uppsala General Catalogue of Galaxies
Ced Cederblad Catalog of bright diffuse Galactic nebulae (Cederblad, 1946)
Arp Atlas of peculiar galaxies
5
(Arp, 1966)
VV
The catalogue of interacting galaxies by Vorontsov-Velyaminov (Vorontsov-Velyaminov,
Noskova, and Arkhipova, 2001)
PK Version 2000 of the Catalogue of Galactic Planetary Nebulae (Kohoutek, 2001)
PN G The Strasbourg-ESO Catalogue of Galactic Planetary Nebulae
6
(Acker et al., 1992)
SNR G A catalogue of Galactic supernova remnants (Green, 2025)
Abell A Catalog of Rich Clusters of Galaxies (Abell, Corwin, and Olowin, 1989)
HCG Atlas of compact groups of galaxies (Hickson, 1993)
ESO ESO/Uppsala Survey of the ESO(B) Atlas (Lauberts, 1982)
vdBH Catalogue of southern stars embedded in nebulosity
7
(van den Bergh and Herbst, 1975)
DWB
Catalogue and distances of optically visible H II regions (Dickel, Wendker, and Bieritz,
1969)
Tr Trumpler Catalog
8
St Stock Catalog
Ru Ruprecht Catalog
vdB-Ha van den Bergh-Hagen Catalog (van den Bergh and Hagen, 1975)
Other
deep-sky objects without designations and sky regions — by formal rules objects from this
list are not included in any catalog known to Stellarium
Cross-index data for Stellarium’s DSO Catalog is partially obtained from “Merged catalogue of reflection
nebulae” (Magakian, 2003) and astronomical databases SIMBAD
9
(Wenger et al., 2000) and NED
10
.
Distances for some deep-sky objects obtained from “The Magellanic Cloud Calibration of the Galactic
Planetary Nebula Distance Scale” (Stanghellini, Shaw, and Villaver, 2008), “A 1.4 GHz Arecibo Survey
for Pulsars in Globular Clusters” (Hessels et al., 2007), “Distance measurements of LYNDS galactic dark
nebulae.” (J. Hilton and Lahulla, 1995) and “A Catalog of Parameters for Globular Clusters in the Milky
Way” (Harris, 1996).
Morphological class for many open clusters obtained from “Classification of open star clusters” (Ruprecht,
1966).
Visual magnitudes for Messier objects obtained from “Revised New General Catalogue and Index Catalogue”
by Dr. Wolfgang Steinicke (Version: 2 February 2021 — NI2021)
11
.
4
The PGC and UGC catalogs are partially supported
5
Arp, VV and PK was added in version 0.16.0
6
PN G, SNR G and Abell was added in version 0.16.1
7
vdBH and DWB was added in version 0.19.2
8
Tr, St, Ru and vdB-Ha was added in version 0.20.2
9
SIMBAD Astronomical Database — https://simbad.u-strasbg.fr/simbad/
10
NASA/IPAC Extragalactic Database (NED) — https://ned.ipac.caltech.edu/
11
Discovery and Cataloguing of Nebulae and Star Clusters —
http://www.klima-luft.de/steinicke/index
_e.htm
8.1 Stellarium DSO Catalog 97
8.1.1 Modifying catalog.dat
This section describes the inner structure of the files
catalog.dat
(binary format) and
catalog.txt
(ASCII format). Stellarium can convert ASCII file into the binary format file for faster usage within the
program.
Each line contains one record, each record consisting of the following fields with tab char as delimiter:
Column Type Description
1 integer Deep-Sky Object Identificator
2
float RA (decimal degrees)
3
float Dec (decimal degrees)
4
float B magnitude
5
float V magnitude
6
string Object type (See section 8.1.1.1 for details).
7
string Morphological type of object
8
float Major axis size or radius (arcmin)
9
float Minor axis size (arcmin)
10
integer Orientation angle (degrees)
11
float Redshift
12
float Error of redshift
13
float Parallax (mas)
14
float Error of parallax (mas)
15
float Non-redshift distance (Mpc for galaxies, kpc for other objects)
16
float Error of non-redsift distance (Mpc for galaxies, kpc for other objects)
17
integer NGC number (New General Catalogue)
18
integer IC number (Index Catalogue)
19
integer M number (Messier Catalog)
20
integer C number (Caldwell Catalogue)
21
integer B number (Barnard Catalogue)
22
integer SH2 number (Sharpless Catalogue)
23
integer vdB number (van den Bergh Catalogue of reflection nebulae)
24
integer
RCW number (A catalogue of H
α
-emission regions in the southern Milky Way)
25 integer LDN number (Lynds’ Catalogue of Dark Nebulae)
26
integer LBN number (Lynds’ Catalogue of Bright Nebulae)
27
integer Cr number (Collinder Catalogue)
28
integer Mel number (Melotte Catalogue of Deep Sky Objects)
29
integer PGC number (HYPERLEDA. I. Catalog of galaxies); partial
30
integer UGC number (The Uppsala General Catalogue of Galaxies); partial
31
string Ced identificator (Cederblad Catalog of bright diffuse Galactic nebulae)
32
integer Arp number (Atlas of Peculiar Galaxies)
33
integer VV number (The catalogue of interacting galaxies)
34
string PK identificator (Catalogue of Galactic Planetary Nebulae)
35
string
PN G identificator (The Strasbourg-ESO Catalogue of Galactic Planetary Nebu-
lae)
36
string SNR G identificator (A catalogue of Galactic supernova remnants)
37
string Abell identificator (A Catalog of Rich Clusters of Galaxies)
38
string HCG identificator (Atlas of compact groups of galaxies)
39
string ESO identificator (ESO/Uppsala Survey of the ESO(B) Atlas)
40
string vdBH identificator (Catalogue of southern stars embedded in nebulosity)
41
integer DWB identificator (Catalogue and distances of optically visible H II regions)
42
integer Tr identificator (Trumpler Catalogue)
43
integer St identificator (Stock Catalogue)
44 integer Ru identificator (Ruprecht Catalogue)
45
integer
vdB-Ha identificator (Uniform survey of clusters in the Southern Milky Way —
van den Bergh-Hagen Catalogue)
98 Chapter 8. Deep-Sky Objects
8.1.1.1 Types of Objects
Possible values for type of objects in the file catalog.dat.
Type Description
G Galaxy
GX
Galaxy
AGX
Active Galaxy
RG
Radio Galaxy
IG
Interacting Galaxy
GC
Globular Cluster
OC
Open Cluster
NB
Nebula
PN
Planetary Nebula
DN
Dark Nebula
RN
Reflection Nebula
C+N
Cluster associated with nebulosity
HII
HII Region
SNR
Supernova Remnant
SNC
Supernova Candidate
SNRC
Supernova Remnant Candidate
BN
Bipolar Nebula
EN
Emission Nebula
SA
Stellar Association
SC
Star Cloud
CL
Cluster
IR
Infra-Red Object
QSO
Quasar
Q?
Possible Quasar
ISM
Interstellar Matter
EMO
Emission Object
LIN
LINEAR-type Active Galaxies
BLL
BL Lac Object
BLA
Blazar
MOC
Molecular Cloud
YSO
Young Stellar Object
PN?
Possible Planetary Nebula
PPN
Protoplanetary Nebula
∗
Star
∗∗
Double Star
MUL
Multiple Star
SY∗
Symbiotic Star
EM∗
Emission-line Star
CLG
Cluster of galaxies
empty
Unknown type, catalog errors, Unidentified Southern Objects etc.
8.1.2 Modifying names.dat
Each line in the file
names.dat
contains one record. A record relates an extended object catalog number
(from catalog.dat) with a name. A single catalogue number may have more than one record in this file.
The record structure is as follows:
Offset Length Type Description
0 5 %5s Designator for catalog (prefix)
5
15 %d Identificator for object in the catalog
20 end %s Proper name of the object (translatable) [# references]
If an object has more than one record in the file
names.dat
, the last record in the file will be used for the
nebula label.
8.1 Stellarium DSO Catalog 99
8.1.2.1 Too many names?
Over the years, a large collection of names from many references has been added. DSO names are not
v 25.1
standardized and are generally not used by professional astronomers, but are often used for popularisation
of objects. Some of the collected names may be too fanciful for your taste. If you can identify that those
names that annoy you all come from a single or just a few entries of the reference list, you can exclude those
sources, and thus the names they bring. Note that if a fancy name comes from more than one book, you
would have to exclude all books to ban that name from your display.
To exclude entries, add the following key to config.ini:
[ astro ]
ne bu la_excl ud e_refer en ces = defaul t : ADI , DSC - HT
Here,
default
names the nebula set, and the comma-separated entries are references you want excluded
from nebulae/default/names.dat.
8.1.3 Modifying textures.json
This file is used to describe each nebula image. The file structure follows the JSON format, a detailed
description of which may be found at
www.json.org
. The
textures.json
file which ships with Stellarium
has the following structure:
serverCredits (optional) a structure containing the following key/value pairs:
short a short identifier of a server where the json file is found, e.g. “ESO”
full a longer description of a server, e.g. “ESO Online Digitized Sky Survey Server”
infoURL a URL pointing at a page with information about the server
imageCredits
a structure containing the same parts as a serverCredits structure but referring to the image
data itself
shortName an identifier for the set of images, to be used inside Stellarium
minResolution
minimum resolution, applies to all images in the set, unless otherwise specified at the image
level
maxBrightness
the maximum brightness of an image, applies to all images in the set, unless otherwise
specified at the image level
subTiles
a list of structures describing individual image tiles, or referring to another json file. Each subTile
may contain:
minResolution
maxBrightness
worldCoords
subTiles
imageCredits
imageUrl
textureCoords
shortName (name for the whole set of images, e.g. “Nebulae”)
miniResolution (applies to all images in set)
alphaBlend (applies to all images in set)
subTiles list of images. Each image record has the following properties:
imageCredits (itself a list of key/pairs)
imageUrl (e.g. file name)
worldCoords (a list of four pairs of coordinates representing the corners of the image)
textureCoords (a list of four pairs of corner descriptions. i.e. which is top left of image etc)
minResolution (over-rides file-level setting)
maxBrightness
Items enclosed in Quotation marks are strings for use in the program. Syntax is extremely important.
Look at the file with a text editor to see the format. Items in <> are user provided strings and values to suit
the texture and source.
{
" im a g e C r e d i t s " : { " short " : " <auth or name > " ,
" infoUr l " : " http :// < mysite . org > "
},
" imageUrl " : " <my P hoto .png > ",
" wo r l d C o o rds " : [[[ X0 , Y0 ] , [ X1 , Y1 ], [ X2 , Y2 ] , [ X3 , Y3 ] ]] ,
100 Chapter 8. Deep-Sky Objects
" te x t u r e C o o r d s " : [[[ 0 ,0] ,[1 ,0] ,[1 ,1] ,[0 ,1]]] ,
" mi n R e s o l u t i o n " : 0.2148 81046 3 ,
" ma x B r i g h t n e s s " : <mag >
},
where
worldCoords
Decimal numerical values of the J2000 coordinates (RA and dec both in degrees) of the
corners of the texture. These values are usually given to 4 decimal places.
textureCoords
Where 0,0 is South Left, 1,0 the South Right, 1,1 North Right, 0,1 North Left corners of the
texture.
minResolution UNDOCUMENTED VALUE! Sorry!
maxBrightness total object brightness, magnitude
Calculating of the coordinates of the corners of the images (plate solving) is a time consuming project
and needs to be fine tuned from the screen display. As most images will be two dimensional, display on
a spherical display will limit the size to about 1 degree before distortion becomes evident. Larger images
should be sectioned into a mosaic of smaller textures for a more accurate display.
8.1.4 Modifying outlines.dat
Each line in the file
outlines.dat
contains three “columns” of data for outline elements. The structure for
each line is as follows:
Offset Length Type Description
0 8 %d Right ascension (decimal hours)
10
18 %d Declination (decimal degrees)
20
60 %s Command
Coordinates for each point of outline is represented in the equatorial coordinate system for epoch J2000.0.
The possible values of the third “column” (Command) are:
start
This command marks a start point of the outline. This command should also contain the designation
of the deep-sky object.
vertex This command marks an intermediate point of the outline.
end This command marks an end point of the outline.
Example for outline of M42:
05.5 6401 -05.49880 start M 42
05.5 6759 -05.39201 vertex
05.5 6635 -05.31749 vertex
05.5 7158 -05.21922 vertex
05.5 7601 -05.21716 vertex
05.5 8830 -05.30164 vertex
05.5 9140 -05.34341 vertex
05.5 9028 -05.37076 vertex
05.5 9008 -05.38175 vertex
05.5 9581 -05.37159 vertex
05.5 9943 -05.47123 vertex
05.5 9912 -05.65838 vertex
05.5 9520 -05.73212 vertex
05.5 8490 -05.68102 vertex
05.5 6948 -05.57675 end
The format of the file
outlines.dat
is compatible with the similar file of the SkyChart (Cartes du
Ciel) planetarium.
8.2 Adding Extra Nebula Images 101
8.2 Adding Extra Nebula Images
GLENN NEWELL
Figure 8.1: Screen shot of nebula images displayed in Stellarium
In previous versions of this guide, the technique for preparing Deep Space Object (DSO) images for inclusion
in Stellarium involved plate solving the image to find its center on the sky, and then calculating the corners
of the image in the World Coordinate System (WCS
12
) using the scale of the image, arc-seconds/pixel.
The problem with that approach is that it did not account for any spatial distortion in the image, due
to telescope optics or sensor tilt, etc. This resulted in a labor intensive manual process of trial and error to
adjust the WCS corners of the image until the stars in the image aligned with those displayed in Stellarium.
Fortunately, this problem has been solved for us by astronomers with similar needs, extending FITS
13
file headers to include information on how to map every pixel in an image correctly onto WCS coordinates.
This information can be added to your image when you plate solve it on nova.astrometry.net, or similar
services (local copies of astrometry.net, such as ansvr, or in Pixinsight, etc.). This system of correcting for
distortions in astronomical images was refined for the Spitzer Space Telescope
14
.
It is now possible to utilize this pixel to WCS transformation data included in plate solved images
to prepare images for Stellarium that map perfectly to the Stellarium sky without manual WCS corner
adjustments.
There are Python libraries, namely astropy and a related “channel” astroquery, that can automate some
or all of the needed steps, and there are both manual and fully automated scripts for that purpose available
on Stellarium’s GitHub site. These scripts can be run on Windows, Mac, or Linux platforms, using the
Anaconda Python distribution.
Nowadays, you can quickly plate solve deep space images and add them to the custom texture module
using the Nebula Textures plugin (see section 13.11).
8.2.1 Image requirements for inclusion in Stellarium
The final image must be aligned with the equatorial (J2000.0) coordinate system so that north is directly up
and not inverted side to side or up and down as can happen with photos taken with a diagonal mirror in the
path (In the WCS system, “Parity” must be 1.)
Next you will need to crop and/or re-scale the picture, setting the main feature at the center and making
the cropped size a power of 2, e.g. 64, 128, 256, 512, 1024 or 2048 pixels square (or elongated like
512× 1024
). If this requirement is not met, your textures may not be visible, or graphics performance may be
seriously impacted on some systems. Textures larger than 2048 may only be supported on high-end hardware.
Images must be in PNG format. When cropping, make sure you leave at least six prominent background
stars for plate solving). The next step is to process your photo to make the background black, really black.
12
https://fits.gsfc.nasa.gov/fits_wcs.html
13
The Flexible Image Transport System is the dominating image format used in astronomy.
14
https://www.cs.helsinki.fi/group/goa/viewing/viewtransf/viewTrans.html
102 Chapter 8. Deep-Sky Objects
This will ensure that your background will meld with the Stellarium background and not be noticed as ugly
gray square. Do not use “transparent” pixels available in the PNG format as they will show as white, not
black, in Stellarium.
Images covering more than 10 degrees of sky should be divided into separate images, and images with
pixel scales less than 1 arc-sec per pixel should be re-scaled so as to have a pixel scale of 1 arc-sec per pixel
or larger.
8.2.2 Processing requirements
•
Python 3.7 (Anaconda 64 bit installer
15
) During installation, follow directions, taking defaults to
install for just your user (vs. everyone on your computer)
•
Astropy (included in Anaconda)
•
Astroquery (latest version) To install on Windows, open an “Anaconda Prompt”. On Mac and Linux,
just open a terminal. At the prompt, enter:
pip install --pre --upgrade astroquery
•
For the fully automated process:
– An API Key from your account at https://nova.astrometry.net:
○ Create an account (or log in with google, etc.) at https://nova.astrometry.net
○ On the API tab, copy your API key (shown in green)
○
Using a text editor (e.g., Notepad++ on Windows, BBEdit on macOS), paste that key over
the
X
’s in
Stellarium_Nebulae_Images_Prep.py
’s
ast.api_key = ’XXXXXXXXXXXXXXXX’
•
For the more manual process:
–
Images plate solved at
https://nova. astrometry.net
(or Pixinsight – not yet tested) so
that WCS data is created
–
Graphics software to flip, rotate, scale, etc. and save as
.png
, e.g., Photoshop, GIMP, Pixinsight,
etc.
8.2.2.1 Script and Shortcut placement
Download the Python scripts from Stellarium’s site at Github
16
:
•
WCS_corners.py script
•
Stellarium_Nebulae_Image_Prep.py script
Windows
•
Place the two .py and .bat scripts into %USERPROFILE%\Anaconda3\
•
Place the two Shortcuts on your desktop or an astro tools folder (optional)
•
You can now drag and drop one or more images or
wcs.fits
files onto the shortcuts (or
.bat
scripts) for processing
Mac
•
Place the two
.py
script files in the
anaconda3
directory, which should be inside your home
directory (the directory with your username).
•
Place the two .app files on your desktop or an astro tools folder (optional)
•
You can now drag and drop one or more images or
wcs.fits
files onto the Automator app
icons for processing
Linux
•
Place the two
.py
script files in the
anaconda3
directory, which should be inside your home
directory (the directory with your username).
•
Place the two .desktop files on your desktop or an astro tools folder (optional)
•
You can now drag and drop one or more images or
wcs.fits
files onto the desktop icons for
processing
8.2.3 Manual processing
We present the more manual of the two workflows and script first, WCS_Corners.py, so you understand the
process, before introducing the completely automated image processing pipeline. It is also possible that if
plate solving fails in the fully automated script, you could continue, using this manual process:
Plate Solve
•
Plate solve your image @ nova.astrometry.net (Fig. 8.2)
15
https://www.anaconda.com/distribution/
16
https://github.com/Stellarium/stellarium-data/tree/master/adding-nebula-images
8.2 Adding Extra Nebula Images 103
Figure 8.2: Online plate solving
Figure 8.3: Python processing. If you just leave a space after
python WCS_corners.py
, you can
drag and drop your wcs.fits file into Windows’ Anaconda Prompt window.
104 Chapter 8. Deep-Sky Objects
•
Note pixel scale and orientation
Adjust Parity
•
Download the
wcs.fits
file from the “Results” page and run WCS_Corners.py on it (Fig. 8.3).
•
If Parity is -1, flip your image horizontally (do this before rotate step below)
Rotate
Rotate your image so “up” is exactly “North”. i.e., if the orientation of your image was “261 degrees
East of North” then rotate your image 261 degrees CW.
“Blacken” Sky
Fill in the blank areas of your rotated image with black pixels, and set your “sky” back-
ground to be black.
Crop
Crop your image so that both
x
and
y
dimensions are powers of two pixels, e.g.
512× 512
,
1024× 1024
,
2048× 2048, 1024× 2048, etc.
Save PNG
•
Save your image as .png file
•
Place a copy into the %USERDIR%/nebulae/default directory
Plate Solve final image
•
Plate Solve your flipped, rotated, and cropped image again @ nova.astrometry.net
•
Download the new wcs.fits file.
Calculate WCS corners
•
Run WCS_Corners.py on the final wcs.fits file
•
Edit Stellarium’s
textures.json
with the image file name and the generated world coordinates
Finalize image
Try to minimize the number of stars visible around your nebula in your image. Stellarium
draws its own stars, and a rectangle of excessive stars may look bad. Just blacken them out.
Restart Stellarium
View your image in Stellarium (and adjust
maxBrightness
in
textures.json
if
needed)
Some additional information you should be aware of:
•
Images in Stellarium are NOT tied to an object, just placed on the sky by worldCoords
– So multiple image can overlap. E.g., the bubble nebula has overlapping textures
– Black is rendered transparent
– “Transparent” areas of .png show as white
•
See section 5.1 on Directories for where to put your own copy of the default images + yours, so yours
won’t get overwritten by Stellarium Updates
•
If plate solve fails: adjust gamma/blackpoint so “only” stars are showing (Fig. 8.4)
→
Figure 8.4: Reduce gamma to temporarily help the plate solving algorithm finding stars.
Stellarium keyboard shortcuts you may find useful when adding images:
F3
brings up object search – Tab through search results
G
to remove ground (in case your object is currently behind the landscape)
A
to remove atmosphere (in case it is daytime)
I
to toggle nebulae images on and off – use to test star alignment
M
to toggle Milky Way on and off
/
to zoom into selected object
\
to zoom back out
8.2 Adding Extra Nebula Images 105
Figure 8.5: Automated Python processing with Stellarium_Nebulae_Image_Prep.py
8.2.4 Automated processing
With the recent addition of astrometry.net queries to the Python astroquery library it is now possible to au-
tomate the entire image processing pipeline as well as automatically create full
.json
entries for each image
for inclusion in the
textures.json
file. The python script for this is Stellar ium_Nebulae_Image_Prep.py.
Wrapper scripts Stellarium_Nebulae_Image_Prep.bat and Stellarium_Nebulae_Image_Prep.sh are also
included so you can process multiple images at once. With the desktop links you can even process one or
more .jpg or .tiff files by drag and drop, on Windows, Mac, and Linux systems.
Figure 8.5 is an example run of Stellarium_Nebulae_Image_Prep.py. This converts (rotates, scales,
etc.) the JPEG image as seen in Fig. 8.6, and a
.json
file for inclusion in
textures.json
(Fig. 8.7), along
with two “unstretched” _stars.jpg images used for plate solving, which can be deleted.
→
Figure 8.6: Automatic processing of a DSO image.
Figure 8.7: .json result from processing with Stellarium_Nebulae_Image_Prep.py
106 Chapter 8. Deep-Sky Objects
8.2.5 Troubleshooting
If no images show up in Stellarium, chances are you have introduced one or more errors in the
textures.json
file. You can use Json Lint
17
to check for problems.
Just paste the entire contents of the file in and press “Validate JSON”.
However, the original textures.json file as shipped in v0.19.1 also fails:
•
Missing leading zeros in front of decimal points
•
White space (a tab in this case) before http in infoUrl entries
These minor issues seem however not to irritate Stellarium.
17
An online service available at https://jsonlint.com/
9. Sky Cultures
GEORG ZOTTI, WITH ADDITIONS BY ALEXANDER WOLF AND SUSANNE M. HOFF-
MANN
Stellarium comes with a nice set of sky cultures from all over the world (see section 4.4.6). For ethnographers
or historians of science it may be a worthwhile consideration to illustrate the sky culture of the people they
are studying. It is not very hard to do so, but depending on your data, may require some skills in image
processing.
Version 25.1 introduces a completely new format for skyculture data. If you are interested in the old
v 25.1
format, please refer to the 24.4 edition of the User Guide. In case you have created your own skycultures in
the old format, we have created a format converter described in section 9.4. For new skycultures, a dedicated
plugin assists you (13.9).
If you add a new or extend an existing sky culture, please adhere to this description for an optimal result!
Some features regarding translation and multilinguality have evolved over the years, and not all sky cultures
currently included in Stellarium adhere to the standards described in the following sections. Incomplete
skycultures may be improved, or removed when found too deficient.
A sky culture in Stellarium is the entity that consists of
•
a description of the role these constellations and other celestial features (clouds, polar lights (aurorae),
meteors, comets, .. . ) had or still have for the human culture that used or use these constellations,
including some relevant background on the culture.
•
(optional) a definition of geographic distribution of the skyculture over time (see 9.3) v 26.1
•
a set of names for constellations
•
stick figure definitions connecting stars into those constellations
•
(optional) a list of names for individual stars
•
(optional) artwork supporting the stick figures
•
(optional) a description of boundaries or borders between the constellations
•
(optional) names and stick figure definitions of additional figures of lesser importance, termed
asterisms.
•
A CC-licence that the author of the SC chooses; this is valid for the entire set of files, i.e. all texts and
images provided.
9.1 Text descr iption
A sky culture must contain the file
description.md
, this is a text in Markdown format. Markdown is a
plaintext format which allows the simple declaration of text regions like sections, subsections, lists, images,
or references. The file is automatically broken into pieces, translated and converted to HTML for display or
else processed for speech output. Also some important skyculture components are extracted from here.
108 Chapter 9. Sky Cultures
The first line of the file starts with the only Level 1 header, i.e., a line starting with a single hash (
#
), a
space and then the name of the skyculture. This name is used in the selection list in the Sky Culture GUI
(see 4.4.6).
The other sections typically start with Level 2 or 3 headers (with two or three hash characters) which are
displayed as smaller section and subsection titles (HTML:
h2
or
h3
, respectively). All header lines (except
the first) should be enclosed by empty lines.
The continuous text should be formatted like that, please do not add newlines where they do not signal
the end of a paragraph with an empty line. Use an editor which just auto-wraps long lines to the window
width. These long lines/paragraphs are automatically fed into the translation system. References (see 9.1.2)
should be given like [#42].
You should provide a good description in the interest of future users: some cultural/ethnographical
background of the users of this sky culture, the history or background of sky culture research that provided
this work, tables of names/translations, links to external resources, whatever seems suitable. The length of
the description texts is not limited, but of course if this is your PhD thesis work, there is no need to repeat all
500 pages, you can add a link to the references.
The skyculture description should include the following Level 2 sections. Any other section must be a
subsection (i.e. Level 3 or deeper) of one of these sections. Each of these sections except
Constellations
will have its own entry in the translations files. The
Constellations
section will be split, so that each
constellation’s description will be translated separately.
Introduction – a summary that could ideally be shown on a small screen entirely.
Description – the actual text of the description.
Constellations
– a sequence of Level 5 sections, where the header is the
"english"
name of a constel-
lation (as given in the
index.json
file), and the body gives some information on this constellation.
This text is used for display and speech output when the constellation is selected.v 25.4
References – a list of references, see 9.1.2 for details.
Authors – all authors and acknowledgments go here.
License
– either a license id (see 9.1.3), or a sequence of lines separated by empty lines (i.e. Markdown
paragraphs) describing which part of the culture has which license, in the format "Sky culture item:
License-ID".
Note that the
Constellations
section has the strict format described above. In particular, there’s no
place for an introduction for all the constellations, or closing remarks or a similar deviation from the format
of this section. If this kind of text is desired, it can be placed in a subsection of the Description section.
To allow the correct display of special characters like ÄÖÜßáé you must provide the file in UTF-8
encoding. If you write only English/ASCII, this may not be relevant.
9.1.1 Images
You can also have embedded images in the file (your book cover? Views of sacred landscapes/buildings/art-
work/.. . ?), just provide them in PNG or JPG format please. Use the following syntax, where the last line is
fixed and is required for proper formatting.
My i mage captio n
{: . im g _ a n d _ c a p tion }
Alternatively, you can format an image in HTML if you need specialized extras like right-alignment or
size specifications:
<p >
<img src =" illustrations / my_im a g e . png " w idth =" 150 " align =" ri ght "/ >
My i mage captio n
{: . im g _ a n d _ c a p tion }
</p >
or (note the manual <br/>)
<p c lass =" img_and_capt i o n " >
<img src =" illustrations / my_im a g e . png " w idth =" 150 " align =" ri ght "/ > <br />
My i mage captio n
{: . im g _ a n d _ c a p tion }
</p >
9.1 Text descr iption 109
9.1.2 References
The optional Level 2 section “References” contains a list of information sources. Each line of the section
contains one record of 2 discernible fields: a hyphen followed by a numerical key in brackets, a colon and
then the actual description of the reference. The latter may include hyperlinks, e.g.:
- [# 1]: Kunitzsch , P .; Smart T. (2006) . " A D i c tionary of Moder n star Names : ...
This list is most important for “traditional” sky cultures collected from various sources to provide
traceable references.
Caution!
These reference numbers are not only used in the text, but also in the data description. If you re-arrange
references, you must also fix all affected references in the JSON file (9.2).
9.1.3 License
The level 2 section “License” is mandatory if you want your sky culture to be distributed with Stellarium to
prevent “unexpected” distribution of your content to other software or applications out of our hands.
We recommend to use one of the following possible licenses in this section:
GNU GPL v2.0 (or later)
– this is the most famous “copyleft” license for code and it may be acceptable
also for text and data.
CC0
(No Rights Reserved) – this is a “don’t care” license. Content may be freely distributed without
attribution for all purposes.
CC BY
(Creative Commons Attribution License) – this license lets others distribute, remix, adapt, and build
upon your work, even commercially, as long as they credit you for the original creation. This is the
most accommodating of licenses offered. Recommended for maximum dissemination and use of
licensed materials.
CC BY-SA
(Creative Commons Attribution-ShareAlike License) – this license lets others remix, adapt, and
build upon your work even for commercial purposes, as long as they credit you and license their new
creations under the identical terms. This license is often compared to “copyleft” free and open source
software licenses. All new works based on yours will carry the same license, so any derivatives will
also allow commercial use. This is the license used by Wikipedia, and is recommended for materials
that would benefit from incorporating content from Wikipedia and similarly licensed projects.
CC BY-ND
(Creative Commons Attribution-NoDerivatives License) – this license lets others reuse the
work for any purpose, including commercially; however, it cannot be shared with others in adapted
form, and credit must be provided to you.
CC BY-NC
(Creative Commons Attribution-NonCommercial License) – this license lets others remix, adapt,
and build upon your work non-commercially, and although their new works must also acknowledge
you and be non-commercial, they don’t have to license their derivative works on the same terms.
CC BY-NC-SA
(Creative Commons Attribution-NonCommercial-ShareAlike License) – this license lets
others remix, adapt, and build upon your work non-commercially, as long as they credit you and
license their new creations under the identical terms.
CC BY-NC-ND
(Creative Commons Attribution-NonCommercial-NoDerivatives License) – this license is
the most restrictive of the six main Creative Commons licenses, only allowing others to download
your works and share them with others as long as they credit you, but they can’t change them in any
way or use them commercially.
FAL
For illustrations we also expect usage of the Free Art License
1
(in addition to any other licenses) – it
is a “copyleft” license that grants the right to freely copy, distribute, and transform creative works.
You can specify, e.g., “GPL2, FAL” to indicate that the images are additionally released under Free
Art License.
Creative Commons provides a range of licenses
2
, each of which grants different rights to use the materials
licensed under them. All of these licenses offer more permissions than “all rights reserved”. Some of
Creative Commons are free and some are non-free. For example you can apply only the most permissive of
its licenses (CC0, CC BY and CC BY-SA) to material you create, to meets the Freedom Defined definition
of a “Free Cultural Work”.
3
1
https://artlibre.org/licence/lal/en/
2
Creative Commons License Chooser – https://creativecommons.org/choose/
3
See Creative Commons website to details –
https://creativecommons.org/share-your-work/public-d
omain/freeworks
110 Chapter 9. Sky Cultures
If you have used one of the keys above in your
license
entry, a short (unofficial! Informative only)
description of license conditions will be displayed. You can use other licenses as well, but then please
describe the conditions sufficiently well in this section.
Caution for users!
While Stellarium is provided under the free GPL v2.0 licence which allows for commercial use, some of our
sky cultures have been contributed under CC NC/ND licenses, i.e., are for noncommercial use only. Please
respect their heritage holders and check the CC licence version in the description before you use sky cultures
in public events like TV documentaries, YouTube videos, lectures, planetarium shows or printed matter. If in
doubt, contact the respective authors.
9.1.4 Technical Test
Using correct syntax is required for making display and translation work. If you have checked out Stellarium’s
sources, you can run
util / skyculture s / generate - pot . py -s my_c ult ure
This may emit some warnings about issues that should be fixed (if any remain). It will also generate a
.po
directory in the skycultures directory, but these files aren’t supposed to be committed, you can remove it.
9.2 Technical data: index.json
The file
index.json
contains all “technical data” of the skyculture. JSON is a text-based format in which
strings, numerical values and arrays can be stored in nested dictionaries, i.e. unordered collections of comma-
separated
"tag": value
pairs in braces:
{ "Tag1": "Value1", "number": 123.456 }
. Values
can be strings, numbers, arrays or other dictionaries. Arrays are ordered sequences in
[...]
delimiters. You
must take care to close any open brackets and separate entries by commas.
{
" id " : " mode rn " ,
" regio n ": " World " ,
" cl a s s i f ication ": [ " traditional "] ,
" fallb a c k _ to _ i n t er n a t i on a l _ n am e s " : false ,
" as terisms ": [ ... ] ,
" co n s t e l lations ": [ ... ] ,
" ed g e s_type ": " iau " ,
" ed g e s _ s o u r c e " : " https :// p b arbier . com / co n s t e l l a t i o n s / edg e s _18 . txt " ,
" ed g e s _ e p och ": " B1 875 ",
" edges ": [ ... ] ,
" co m m o n _ n a m e s " : { ... }
}
in which
"id" A unique identifier for program-internal use. It is never displayed to users.
"region" See 9.2.1
"classification" See 9.2.2
"fallback_to_international_names"
if
true
, the IAU-approved star names are loaded after all names
given here, so names will be mixed without a clear separation, and newly-approved star names will
just appear automatically. Also all DSO names from
nebulae/default/names.dat
are loaded.
This is most useful for skycultures which have no names of their own, or where such mix is intended,
like
"personal"
contemporary skycultures (see 9.2.2) which are allowed to auto-adapt to newly
given names.
"common_names" includes names for star, planet and deep-sky objects, see 9.2.7
"constellations" describes constellations, see 9.2.4
"edges..." describes boundaries between constellations, see 9.2.3
"asterisms" describes asterisms, see 9.2.5
Tags not described here may be used in other programs but are ignored by Stellarium.
9.2 Technical data: index.json 111
9.2.1 Region
The “region” tag marks the origin region of the respective sky culture. It allows some form of additional
grouping. The names of regions are largely following the United Nations geoscheme UN M49
4
, but with
some deviations:
Northern Africa – Algeria, Egypt, Libya, Morocco, Sudan, Tunisia, Western Sahara.
Eastern Africa
– British Indian Ocean Territory, Burundi, Comoros, Djibouti, Eritrea, Ethiopia, French
Southern Territories, Kenya, Madagascar, Malawi, Mauritius, Mayotte, Mozambique, Réunion,
Rwanda, Seychelles, Somalia, South Sudan, Uganda, United Republic of Tanzania, Zambia, Zim-
babwe.
Central Africa
– Angola, Cameroon, Central African Republic, Chad, Congo, Democratic Republic of the
Congo, Equatorial Guinea, Gabon, Sao Tome and Principe.
Southern Africa – Botswana, Eswatini, Lesotho, Namibia, South Africa.
Western Africa
– Benin, Burkina Faso, Cabo Verde, Côte d’Ivoire, Gambia, Ghana, Guinea, Guinea-Bissau,
Liberia, Mali, Mauritania, Niger, Nigeria, Saint Helena, Senegal, Sierra Leone, Togo.
Caribbean
– Anguilla, Antigua and Barbuda, Aruba, Bahamas, Barbados, Bonaire, Sint Eustatius and Saba,
British Virgin Islands, Cayman Islands, Cuba, Curaçao, Dominica, Dominican Republic, Grenada,
Guadeloupe, Haiti, Jamaica, Martinique, Montserrat, Puerto Rico, Saint Barthélemy, Saint Kitts and
Nevis, Saint Lucia, Saint Martin (French Part), Saint Vincent and the Grenadines, Sint Maarten (Dutch
part), Trinidad and Tobago, Turks and Caicos Islands, United States Virgin Islands.
Central America – Belize, Costa Rica, El Salvador, Guatemala, Honduras, Mexico, Nicaragua, Panama.
South America
– Argentina, Bolivia (Plurinational State of), Bouvet Island, Brazil, Chile, Colombia,
Ecuador, Falkland Islands (Malvinas), French Guiana, Guyana, Paraguay, Peru, South Georgia and
the South Sandwich Islands, Suriname, Uruguay, Venezuela (Bolivarian Republic of).
Northern America – Bermuda, Canada, Greenland, Saint Pierre and Miquelon, United States of America.
Antarctica – Antarctica.
Northern Asia – Russian Federation (Asian part).
Central Asia – Kazakhstan, Kyrgyzstan, Tajikistan, Turkmenistan, Uzbekistan.
Eastern Asia
– China, Hong Kong Special Administrative Region of China, Macao Special Administrative
Region of China, Democratic People’s Republic of Korea, Japan, Mongolia, Republic of Korea,
Taiwan.
South-eastern Asia
– Brunei Darussalam, Cambodia, Indonesia, Lao People’s Democratic Republic,
Malaysia, Myanmar, Philippines, Singapore, Thailand, Timor-Leste, Viet Nam.
Southern Asia
– Afghanistan, Bangladesh, Bhutan, India, Iran (Islamic Republic of), Maldives, Nepal,
Pakistan, Sri Lanka.
Western Asia
– Armenia, Azerbaijan, Bahrain, Cyprus, Georgia, Iraq, Israel, Jordan, Kuwait, Lebanon,
Oman, Qatar, Saudi Arabia, State of Palestine, Syrian Arab Republic, Türkiye, United Arab Emirates,
Yemen.
Eastern Europe
– Belarus, Bulgaria, Czechia, Hungary, Poland, Republic of Moldova, Romania, Russian
Federation (European part), Slovakia, Ukraine.
Northern Europe
– Åland Islands, Channel Islands, Denmark, Estonia, Faroe Islands, Finland, Iceland,
Ireland, Isle of Man, Latvia, Lithuania, Norway, Svalbard and Jan Mayen Islands, Sweden, United
Kingdom of Great Britain and Northern Ireland.
Southern Europe
– Albania, Andorra, Bosnia and Herzegovina, Croatia, Gibraltar, Greece, Holy See, Italy,
Malta, Montenegro, North Macedonia, Portugal, San Marino, Serbia, Slovenia, Spain.
Western Europe
– Austria, Belgium, France, Germany, Liechtenstein, Luxembourg, Monaco, Netherlands,
Switzerland.
Australasia
– Australia, Christmas Island, Cocos (Keeling) Islands, Heard Island and McDonald Islands,
New Zealand, Norfolk Island.
Melanesia – Fiji, New Caledonia, Papua New Guinea, Solomon Islands, Vanuatu.
Micronesia
– Guam, Kiribati, Marshall Islands, Micronesia (Federated States of), Nauru, Northern Mariana
Islands, Palau, United States Minor Outlying Islands.
Polynesia
– American Samoa, Cook Islands, French Polynesia, Niue, Pitcairn, Samoa, Tokelau, Tonga,
Tuvalu, Wallis and Futuna Islands.
For “modern” sky cultures we use the special region name World to define worldwide applicable data.
4
Standard country or area codes for statistical use (M49) – https://unstats.un.org/unsd/methodology/m4
9/
112 Chapter 9. Sky Cultures
In case you are illustrating a fictional sky culture not actually used on Earth, you can use Other or even
whatever else you like. They will be listed in the “Other” category in the View dialog.
Figure 9.1: Africa: subregions as delineated by United Nations geographic classification scheme:
Eastern Africa, Central Africa, Northern Africa, Southern Africa, Western Africa.
Wikipedia / CC BY-SA 3.0
9.2.2 Classification
The tag “classification” allows describing the origin and intended use of this skyculture:
personal
– this is a personally developed sky culture which is not founded in published historical or
ethnological research. Stellarium may include it when it is “pretty enough” without really approving
its contents.
traditional
– (default value) content represents “common” knowledge by several members of an ethnic
community, and the sky culture has been developed by members of such community. Our “Modern”
sky culture is a key example: rooted in antiquity it has evolved for about 2500 years in what is now
commonly known as “western” world, and modern astronomers use it.
ethnographic – provided by ethnographic researchers based on interviews of indigenous people.
historical – based on historical written sources from a (usually short) period of the past.
single – represents a single source like a historical atlas, or related publications of a single author.
comparative
– special-purpose compositions of e.g. artwork from one and stick figures from another sky
culture, and optionally asterisms as representations of a third. Or comparison of two stick figure sets
in constellations and asterisms. These figures sometimes will appear not to fit together well. This may
be intended, to explain and highlight just those differences! The description text must clearly explain
and identify all sources and how these differences should be interpreted.
9.2 Technical data: index.json 113
Figure 9.2: Asia: subregions as delineated by United Nations geographic classification scheme:
Central Asia, Eastern Asia, South-eastern Asia, Southern Asia, Western Asia,
Northern Asia. Wikipedia / CC BY-SA 3.0
Figure 9.3: Europe: subregions as delineated by United Nations geographic classification scheme:
Eastern Europe, Northern Europe, Southern Europe, Western Europe. Wikipedia / CC
BY-SA 3.0
114 Chapter 9. Sky Cultures
Figure 9.4: Americas: subregions as delineated by United Nations geographic classification scheme:
Caribbean, Central America, Northern America, Southern America. Wikipedia / CC
BY-SA 3.0
Figure 9.5: Oceania: subregions as delineated by United Nations geographic classification scheme:
Australasia, Melanesia, Micronesia, Polynesia. Wikipedia / CC BY-SA 3.0
9.2 Technical data: index.json 115
9.2.3 Constellation boundaries
In the late 18th century, when variable stars started to be catalogued by a code that included the star’s
constellation, a necessity arose to define which sky region belonged to which constellation. Atlases of
this period showed curved boundaries between the constellations. Such boundaries are hard to describe
by coordinates, though. The Uranographia Argentina (Gould, 1879) proposed a different approach. The
boundaries were described by mostly straight segments along great circles of equal right ascension and small
circles of equal declination. The atlas used coordinates for epoch B1875.0. Based on this work, in 1930
the International Astronomical Union (IAU) ratified a partition of the sky into the 88 constellations (now
only using lines along constant right ascension/declination of B1875.0) used by scientists and amateurs ever
since. When looking at these boundaries in J2000.0 coordinates, we can see they are no longer parallel to the
J2000.0 coordinate grid, the deviation caused by precession.
Partitions of the full sky into contiguous regions defined by edges between coordinate vertices defined in
equatorial coordinates at a certain epoch can be described in the following elements of the index.json:
" ed g e s_type ": " iau " ,
" ed g e s _ s o u r c e " : " https :// p b arbier . com / co n s t e l l a t i o n s / edg e s _18 . txt " ,
" ed g e s _ e p och ": " B1 875 ",
" edges ": [
" 001:00 2 M + 2 2:52:00 +34 : 3 0 :00 22:52:0 0 +52:30:00 AND LAC " ,
" 002:00 3 P + 2 2:52:00 +52 : 3 0 :00 23:20:0 0 +52:30:00 AND CAS " ,
" 004:00 5 P + 2 3:20:00 +50 : 0 0 :00 23:35:0 0 +50:00:00 AND CAS " ,
...
]
where
"edges_type" is optional and may contain the following values:
"none"
— (default) designates that this culture doesn’t have constellation boundaries, and any
edges
entry is ignored.
"iau" — use this value for variants of “modern” sky cultures to declare use of IAU boundaries.
"own" — used for cultures which have their own set of constellation boundaries.
"edges_source" is optional and only given for reference. It is not evaluated.
"edges_epoch" describes the coordinate epoch. Allowed values:
"J2000" (default)
"B1875" used for the edge list defining the IAU borders.
"Byyyy.y" (a number with B prepended) Arbitrary epoch as Besselian year.
"Jyyyy.y" (a number with J prepended) Arbitrary epoch as Julian year.
"JDddddddd.ddd" (a number with JD prepended) Arbitrary epoch as Julian Day number.
"ddddddd.ddd" (a pure number) Arbitrary epoch as Julian Day number.
The lines in the array “edges” were taken from the given reference. The first component is ignored. The
next element provides information whether the segment runs along a meridian (
M
, right ascension) or parallel
(
P
, declination) circle in ascending
+
or descending
-
sense. Then it provides
α
1
,
δ
1
,
α
2
,
δ
2
in sexagesimal
numbers (
α
in HH:MM:SS,
δ
in DD:MM:SS format) and the uppercased constellation abbreviations. As
described in the original source file, Serpens has been split into
SER1
and
SER2
, these tags are treated both
as SER.
These edges are used to define isolated boundaries for each constellation (for proper working of the
Select single constellation
option).
9.2.4 Constellations
Constellations are coded as array of dictionaries:
" co n s t e l lations ": [
{
" id " : " CON mode rn Aql ",
" lines ": [ [ 9 80 3 6 , 9 76 4 9, 9727 8 ] , [ 97 6 4 9, 9550 1 , 9 7 80 4 ], [9 94 7 3, 9780 4 ] ,
[95 5 0 1, 9374 7 , 9 3 24 4 ], [9 55 0 1, 9380 5 ] ],
" image ": {
" file ": " il l u s t r a t i o n s / aqu ila . png " ,
" size ": [5 1 2 , 5 12 ] ,
" anchor s " : [
{" pos ": [1 6 3 , 2 32 ] , " hip ": 9 7 6 49 } ,
{" pos ": [3 8 5 , 1 31 ] , " hip ": 9 3 2 44 } ,
{" pos ": [3 9 7 , 3 97 ] , " hip ": 9 3 8 05 }
116 Chapter 9. Sky Cultures
]
} ,
" co m m o n _ n ame ": { " engli sh ": " Aq uila ", " nativ e ": " Aq uila "}
} , ...
] , ...
where
"id"
A unique figure identifier, consisting of
CON
(for constellations), skyculture id, and a short Latin-
character based label still unique within the skyculture. For IAU-based skycultures, these short
labels must be the IAU standard labels. For others, you can invent your own. It is not necessary
to have exactly 3-letter keys, but they should act as mnemonic support, so numerical keys are not
recommended: the short label is displayed when enabling abbreviated screen labels (s. 4.4.6). If you
want to prevent certain abbreviations from being displayed, let them start with a dot. See the effect in
the
Modern (H.A.Rey)
sky culture: with abbreviated labels enabled, only the official abbreviations
are displayed.
"lines"
an array of arrays, each describing a polyline with star numbers. The star numbers are usually the
Hipparcos (HIP) numbers. For very dim stars, the longer numbers from the Gaia DR3 catalog are
acceptable, but they must be written as string. Even Deep-Sky objects (like a naked-eye open cluster)
v 25.2
can be added to a constellation line when written as string starting with "DSO:", like "DSO:M7".
To describe dark constellations formed from dust clouds in the Milky Way or other non-stellar items,
v 25.2
another variant can use coordinate lists and is technically an array of arrays of 2-part arrays of float
numbers, each pair being right ascension
α
(decimal hours) and declination
δ
(decimal degrees) in
equinox J2000.0. See below how Stellarium can help you write these arrays.
Single-star constellations or particular highlights can be described with just one star repeated in a
v 25.1
two-element segment. The respective star will be encircled with a radius of
"single_star_radius" (float, default 0.5).v 25.1
"hull_extension"
(optional) A vector of star IDs (HIP number as integer, Gaia DR3 long integer
v 25.2
number as string, or a Deep-Sky object (like a naked-eye cluster) as string starting with
"DSO:"
, like
"DSO:M44" that are seen as part of the constellation. See below about convex hull.
"hull_radius" (float, defaults to "single_star_radius" or (if that is not defined)0.5).v 25.2
"image" Optional, see 9.2.4.1
"common_name" Dictionary of names.
"native" name in the original language of the skyculture.
"english" translation of the name’s meaning. This is translated to users’ language.
"byname"
an optional explanatory addition to the name. May be helpful to explain mythological
v 25.3
figures. This is translated to users’ language, but is not included in search functions.
"pronounce"
(optional, but recommended) a Latin-character based transliteration/pronunciation
aid, e.g. Pinyin for Chinese. This may also be translated to user language.
"transliteration"
(optional) a scientific Latin-character based transliteration where applicable.
This is not translatable or adaptable to user language conventions, but may include extended
diacritics. An example is Wylie for Tibetan, which is not meant to help in pronunciation.
"IPA" (optional) International Phonetic Alphabet, a standardardized phonetic spelling.
"context"
(optional) Short english explanation that helps to disambiguate terminology. Not dis-
played in the program.
"translators_comments"
(optional) English explanations that help in translation on Transifex.
Not displayed in the program.
These names are used in the sky culture name style settings (s. 4.4.6). If your sky culture is a variant
of the
Modern
sky culture, please use the canonical Latin as
"native"
name and the
"english"
names from the default Modern skyculture, they have all been translated already. Also star names
should provide both
"native"
and
"english"
entries, even if both are identical, to allow transla-
tion/transliteration to languages with other script systems or spelling variants.
If your sky culture is not a variant of the generally known
Modern
(western) sky culture, please
make sure to provide an
"english"
translation (where possible) in addition to the name given in the
"native"
language, or a
"byname"
which may help better understanding a figure. Else translators
will not be able to translate the name, and users will be less interested to learn about the culture. Also
make very sure to use the same spelling consistently in
index.json
and
description.md
, and
explain the context of stars (how these stars are used, or what they mean to the respective members of
the culture), especially where only an untranslatable proper name is given.
9.2 Technical data: index.json 117
"label_offset"
optional. An array of
[deltaRA, deltaDE]
(decimal degrees) used as offset that shifts
the auto-computed label positions.
"label_positions"
optional. An array of sub-arrays of
[RA, DE]
tuples (decimal hours, decimal
degrees) used as label positions. By default, the label position is computed from the star positions
used in the
"lines"
. With this entry you can set specialized positions, or also use more than one
label per constellation.
"visibility"
(optional) special cases for rule-based visibility, e.g. seasonally changing aspects of figures.
Currently only a
"months"
rule has been defined. Its “payload” is an array of two integers, start and
end of visibility in months, e.g:
" visi bility ": { " months ": [ 6 , 3 ]} ,
This specifies that the afflicted constellation is visible only from June to March, wrapping over the
12-month cycle. A second entry of the same constellation (with possibly different lines, artwork, or
even name) that would be visible from April to May, would be specified as:
" visi bility ": { " months ": [ 4 , 5 ]} ,
Drawing dark constellations
The outlines of figures like the “Emu in the Sky” cannot be described with connect-the-dot star patterns, as
v 25.2
they are formed from the absence of luminous patterns. We need to describe them using coordinate lists. To
make the process less tedious, we can extend setting Markers (see 3.6). For this to work, add the following
key to config.ini:
[ devel ]
ma rkers _t o_log file = true
After program restart, setting a marker also writes a numbered line into the logfile, containing marker number
and the array of coordinates (
[RA, dec]
). In the text editor you are using to edit
index.json
, the arrays
can be collated into the format required to code coordinate lists for dark constellations.
Constellation area (convex hull)
The constellation area, or convex hull of a constellation, is an area of the sky described by a convex polygon
v 25.2
which surrounds all stars that are part of the lines that form the constellation “stick figure”, plus those
objects which are listed in
"hull_extension"
. While the IAU has defined 88 constellation areas in 1930,
constellations of other cultures are not as clearly defined. These areas can help analyzing historical records.
Note that a point may lie in zero, one or more than one constellation area(s) when it overlaps two or even
more adjacent figures.
Technically, the stars are projected perspectively onto a tangential plane to the celestial sphere at the
balance point of all involved stars. Then a simple package wrapping algorithm (Sedgewick, 1990, ch.25)
can be applied to find the convex hull. Straight lines in the projection are great circle arcs. Note that this
limits constellation size to less than 180 degrees in the sky, outlying stars will currently be discarded. (Please
report an error if this affects you, so we might find a better solution.)
This functionality is an advanced topic mostly used by sky culture researchers (e.g. S. M. Hoffmann,
2017, pages 94–98) who are also not afraid of calling scripting functions (see ch. 17), and is therefore hidden
from beginning users. To make use of it, edit your config.ini and add a key:
[ gui ]
sk yc ulture_ enable_ hu lls = true
The constellation areas of a skyculture can be queried by a scripting function:
ConstellationMgr.outputHullAreas(<filename_start>);
The argument
<filename_start>
is optional and defaults to
"hullAreas"
. The created CSV file
<filename_start>_skycultureName.csv
in your Stellarium user data directory lists hull areas for
all constellations of the current skyculture.
You can list stars which belong to a thusly defined constellation with a scripting function:
ConstellationMgr.starsInHullOf("Taurus", false, 12.0, <start>);
118 Chapter 9. Sky Cultures
This creates a file
hullStars_Modern_Taurus-12.00.csv
in your Stellarium user data directory which
contains all stars within the convex hull of Taurus in the current (here: “Modern”) sky culture. The arguments
to the function are:
constellation string; name or abbreviation.
hipOnly
Boolean, optional, defaults to
true
; if you are only interested in brighter stars contained in the
Hipparcos catalog, set it true.
maxMag
float, optional, default: 25.0. Dimmest stellar magnitude to use. The default value just makes sure
all stars that are contained in the catalogs are listed, the result will only have few entries dimmer than
mag 18.
<start> string, optional, default hullStars; the start of the filename can be changed here.
9.2.4.1 Constellation Artwork
Constellation artwork is optional, but may give your sky culture the final touch, if it requires artwork at all.
E.g., H. A. Rey’s variant of the
Modern
sky culture deliberately does not contain artwork other than his new
set of stick figures.
Each constellation artwork is linked to 3 stars in its constellation. This is programmed in the
"image"
dictionary. It contains entries
"file"
is the file name of your texture. All constellation artwork files should reside in a subdirectory
illustrations
. For best efficiency it should be sized in a power of two, like
512× 512
,
1024× 2048
etc. Avoid dimensions larger than 2048, they are not supported on all systems. Use as little border in
your textures as possible instead. You can distort images to better exploit the pixels, the texture will
be stretched back. The background of the artwork image must be absolutely black.
"size"
Image size (width, height) in pixels. This size specified here, and not the real image size, is relevant
for the
"anchors"
entry. This may be important on very memory limited systems where you decide
to downscale all textures.
"anchors" An array of three similar dicts with
"pos" pixel addresses [x, y] given from upper left corner (find those in any image editor)
"hip"
The star index as Hipparcos (HIP) number, given as integer. This may technically also be a
Gaia DR3 number when given as string.
In case the artwork is only available in a certain projection (e.g., an all-sky map), or is otherwise heavily
distorted so that the match is not satisfactory, you may have to re-project the image somehow. For aligning,
you should switch Stellarium to Stereographic projection for optimal results.
You don’t have to shutdown and restart Stellarium during creation/matching, you can just press
Ctrl
+
Alt
+
I
to reload.
9.2.5 Asterisms and help rays
Sometimes auxiliary figures were created for easier orientation. Some part of a constellation may have
been redefined into a figure in its own right, or parts from different constellations were merged into one big
figure — e.g. “Big Dipper” as part of Ursa Major, or the “Summer Triangle” consisting of 3 stars from the
constellations Cygnus, Lyra and Aquila. After the codification of the official 88 constellations by the IAU,
those additional figures have generally been called asterisms.
5
Other simple figures might be used as navigation and orientation helpers: the help rays. As example
to help in orientation in the sky the additional lines between constellations Ursa Major, Ursa Minor and
Cassiopeia might be useful. The asterisms and help rays are listed in
"asterisms"
which is similar to the
"constellations" dict, but has no "figures" entry:
" as terisms ": [
{
" id " : " AST mode rn HeG ",
" co m m o n _ n ame ": { " engli sh ": " Heav e nly G " , " references ": [30 ,32 ] } ,
" lines ": [ [ 2 14 2 1 , 2 46 0 8, 3685 0 , 3 7 82 6 , 3 7 27 9 , 3 23 4 9 , 2 44 3 6, 2533 6 , 2 7 98 9 ] ]
} , ...
]
"id"
A unique asterism identifier, consisting of
AST
(for asterism), skyculture id, and a short Latin-character
based label still unique within the skyculture. It is not necessary to have exactly 3-letter keys, but they
should act as mnemonic support, so numerical keys are not recommended: the short label is displayed
5
In a more generalized context when describing the sky of other cultures, the distinction may be less strict, and the
term “asterism” may even be used for the “primary figures” observed by those cultures.
9.2 Technical data: index.json 119
when activating abbbreviated labels (s. 4.4.6). If you want to prevent certain abbreviations from being
displayed at all, let them start with a dot.
"common_name"
Another dict with entries
"native"
(as used in the source),
"english"
(the trans-
latable english name),
"pronounce"
,
"transliteration"
,
"IPA"
,
"byname"
,
"context"
and
"translators_comments"
as defined for constellations, and an optional array
"references"
which lists from which sources (from 9.1.2) this asterism was taken.
Collecting sources and giving such references is always a good idea. If you feel ther are more in the
collection than you like, read 9.2.9.1 about suppressing excessive entries.
"label_offset"
optional. An array of
[deltaRA, deltaDE]
(decimal degrees) used as offset that shifts
the auto-computed label positions.
"label_positions"
optional. An array of sub-arrays of
[RA, DE]
tuples (decimal hours, decimal
degrees) used as label positions. By default, the label position is computed from the star positions
used in the
"lines"
. With this entry you can set specialized positions, or also use more than one
label per asterism.
"is_ray_helper"
(optional, default=
false
). Set to
true
to declare this asterism as “ray helper” which is
shown in a different color and without label.
"lines"
an array of arrays, each describing a polygon with integer star numbers. The star numbers are
usually the Hipparcos (HIP) numbers. For the very dim stars of telescopic asterisms, the longer
numbers from the Gaia DR3 catalog are acceptable, but they must be written as string. Another variant
can use coordinate lists and is technically an array of arrays of 2-part arrays of float numbers, each
pair being right ascension
α
(decimal hours) and declination
δ
(decimal degrees) in equinox J2000.0.
Single-star asterisms can be described with a two-element array that repeats the first entry (star or
v 25.1
coordinate pair) – the respective star/coordinate will be encircled with a radius of
"single_star_radius"
(float, default 0.5) radius of a circle (degrees) marking single-star segments in
v 25.1
"lines".
9.2.6 Culture Relevant Coordinate Systems: Zodiac and Lunar Systems
Ancient high cultures in and around Asia took special note of the zone where the planets move: along the
v 25.2
path of the Moon, a system of 27 or 28 lunar stations or lunar mansions were formed, and later the Sun’s
annual path was split into 12 equal-size parts of 30 degrees along the ecliptic.
The best-known system in modern times is that of the tropical zodiac of
12× 30
degrees along the ecliptic,
counted from the equinox point (First point of Aries
à
). The 12 sections, or zodiacal signs, were named
after the constellations which resided there at the time the system was codified. Precessional movement
since antiquity moved the stars eastwards along the ecliptic by about one full sign, so that meanwhile
there is usually a mismatch between the constellation the sun is in and the sign which you find listed in
bad newspapers’ horoscope pages. Astronomically, the zodiacal sign is just an old-fashioned way to write
ecliptical coordinates of date.
In India, the partitions were defined so that the star Spica rests at the 180° mark, so that the Indian or
sidereal zodiac moves along the ecliptic with precession.
" zodia c ": {
" name ": { " pr o n o unce ": "R¯aśi" , " english " : " Indi an Zod iac "} ,
" contex t " : " ind ian zod iac sign " ,
" pa r t itions ": [ 1 2 , 3 , 2 , 5 ] ,
" exten t ": 9 ,
" link ": { " star ": 6 5 4 74 , " of fset ": 180} ,
" names ": [ { " sym bol ": "\ u2648 " , " native " : " ... " , " engli s h ": " Ram "} ,
{ " symbol " : " \u26 49 " , " native " : " ... " , " engli sh ": " Bull "} ,
...
{ " symbol " : " \u26 53 " , " native " : " ... " , " engli sh ": " Fi shes "} ]} ,
where
"name" cultural name as described in 9.2.7.
"context"
(optional, recommended) context data for all English names in zodiac (enhancement of local-
ization support).
"comment" (optional) commentary for zodiac, it will be used as extra commentary for translators also.
"partitions"
regular division of the centerline. The first element commonly is 12 (30-degree sign). The
other elements (up to 3) are used to describe the tick marks in decreasing order. The example means,
the 30 degrees are further divided in 3 sections (large 10-degree ticks), these are split in 2 5-degree
sections with 5 sections (1-degrees) each.
120 Chapter 9. Sky Cultures
"extent"
The zone of interest is closed off by parallel lines this many degrees north and south of the
centerline. A zodiac of 9 degrees encloses extreme positions of all major planets.
"link"
(optional) The Indian sidereal zodiac is described to be defined with the longitude of a certain star.
Usually and in this sample, Spica (
α
Vir, HIP 65474) is declared to lie at 180°. If missing, the zodiac
starts from à.
"names"
Sequence of names. In addition to the elements listed in 9.2.7,
"symbol"
provides a Unicode
symbol (as shown here, these are the common zodiacal signs) or 1-2 letter string (for practical reasons,
a number seems generally useful). The number of entries must be equal to (or larger than) the first
element of "partitions". Excessive entries are ignored.
More important for Indians however, and still relevant today, is the traditional system of lunar stations, the
nakshatras. the ecliptic is split into 27 equal-sized partitions, which are then further split into 4 equal parts.
" lu n a r _ s y s t e m " : {
" name ": { " native " : " ... ", ... , " engl i sh ": " Naksha t r a s " } ,
" contex t " : " ind ian lu nar ma nsion ",
" pa r t itions ": [ 2 7 , 4 ],
" exten t ": 5 ,
" link ": { " star ": 6 5 4 74 , " of fset ": 180} ,
" names ": [ { " sym bol ": "1 " , " nat ive ": " ... " , ... , " eng lish ": " Ph y s ician to the
↪ Gods "} ,
{ " symbol " : " 2" , " na tive ": " ... ", ... , " engli s h ": " Bea rer "} ,
{ " symbol " : " 3" , " na tive ": " ... ", ... , " engli s h ": " Plei a d es "} ,
...
where
"name" cultural name as described in 9.2.7.
"context"
(optional, recommended) context data for all English names in lunar mansions (enhancement
of localization support).
"comment"
(optional) commentary for lunar system, it will be used as extra commentary for translators
also.
"partitions" regular division of the centerline. 27 stations which are further divided in 4 equal parts.
"extent"
The zone of interest. With an obliquity of the Lunar orbit of about 5 degrees, a 5-degree zone
seems appropriate.
"link"
(optional) The Indian system is again described to be defined with the longitude of Spica (
α
Vir,
HIP 65474) to lie at 180°. If missing, the count starts from à.
"names"
Sequence of names. In addition to the elements listed in 9.2.7,
"symbol"
provides a Unicode
symbol or 1-2 letter string (for practical reasons, a sequential number seems generally useful). The
number of entries must be equal to (or larger than) the first element of
"partitions"
. Excessive
entries are ignored.
In the Arabian peninsula, a similar system of 28 lunar stations is in use until today, but the actual asterism
appears to be more important than the regularity of the ecliptic partition. The first station is centered around
al-Thurayya (the Pleiades star cluster). In some skycultures the “band” of stations around the ecliptic is
shown irregular, with boxes trying to frame the associated asterisms:
" lu n a r _ s y s t e m " : {
" name ": {" en glish ": " Lun ar Stati o ns " , " na tive ": " ... " , " pron o u n ce ": " Man a zil
↪ alQamar " , " IPA ": " manazilulqamar "} ,
" pa r t itions ": [ 2 8 , 3 , 2 ] ,
" exten t ": [ 1 0. 0 , -1 0 .0 , 1 0 .0 , - 1 0 .0 , 1 0 .0 , - 1 5 .0 , 1 0 .0 , - 1 5 .0 , 1 5 .0 , ... ] ,
" contex t " : " arab i an lun ar stat i o ns " ,
" link ": { " star ": 1 7 7 02 , " of fset ": 6.42 8 5 71 4 28 5 71 4 2 9, " comme n t ": " ce nter of
↪ f irst s tation is Lucida P l eiadum "} ,
" names ": [ { " sym bol ": " 1" , " eng lish ": "Al - Th urayya ", " nativ e ": " ... " , ... } ,
{ " symbol " : "2 " , " eng l ish ": " Al - Da baran " , " nati ve ": " ... ", ... } ,
...
where
"partitions"
regular division of the centerline. 28 stations which are further divided into 3 equal parts
that are further halved.
"extent"
As array of latitude coordinates, they provide alternating north and south latitudes for all stations.
v 25.3
The number of entries must be twice the number of partitions.
In China, the 28 lunar mansions are defined in a different way. 28 defining stars mark the begin (western
9.2 Technical data: index.json 121
edge) of each mansion, and great circles are drawn from the celestial poles through these stars. In Stellarium,
the defining stars are marked with a little circle. The mansions are quite different in width.
" lu n a r _ s y s t e m " : {
" name ": { " native " : " ... ", " p ronounce ": "Xiù", " engli s h ": " Lunar M a nsion " } ,
" contex t " : " chin e se lunar man s ion " ,
" de f i n i n g_stars ": [ 6 54 7 4 , 6 94 2 7, ... ],
" coordsys " : " equatorial ",
" exten t ": 9 0 ,
" names ": [ { " sym bol ": "1 " , " nat ive ": " ... " , " prono u n c e ": "Jiˇao" , " en g lish ":
↪ " Horn "} ,
{ " symbol " : " 2" , " na tive ": " ... ", " pronounc e " : "Kàng" , " en g lish ":
↪ " Neck "} ,
...
where
"name" cultural name as described in 9.2.7.
"context"
(optional, recommended) context data for all English names in lunar mansions (enhancement
of localization support).
"comment"
(optional) commentary for lunar system, it will be used as extra commentary for translators
also.
"defining_stars" List of HIP numbers of the 28 defining stars.
"coordsys" may be "equatorial" or "ecliptical" (default).
"extent" The zone of interest. The Chinese mansions extend from pole to pole.
"names"
Sequence of names. In addition to the elements listed in 9.2.7,
"symbol"
provides a Unicode
symbol or 1-2 letter string (for practical reasons, a number seems generally useful). The number of
entries must be equal to (or larger than) the number of elements of
"defining_stars"
. Excessive
entries are ignored.
9.2.7 Names of Stars, Planets and Nonstellar Objects
Many cultures have defined their own names for stars, planets and even a few deep-sky objects bright enough
to be seen with the unaided eye. The
"common_names"
dict in a skyculture file
index.json
contains entries
of arrays tagged with HIP catalog numbers or other names.
Names for stars, constellations, asterisms, planets and DSOs can be specified with a plethora of options:
v 25.2
"native" name in the original language of the skyculture.
"english" translation of the name’s meaning. This is translated to users’ language.
"pronounce"
(optional, but recommended) a Latin-character based transliteration/pronunciation aid, re-
quired when
"native"
is written in non-Latin-based glyphs (e.g., Chinese, Arab, Hindu, Tibetan,
. . . ), e.g. Pinyin for Chinese. This is usually written with simple characters found on typewriters and
may also be translated to user language to adopt different customs.
"transliteration"
(optional) a scientific Latin-character based transliteration where applicable. Not
translatable to user language, but may use extended diacritics. The scheme may not be helpful as
pronunciation aid. For example, Wylie for Tibetan.
"IPA" (optional) International Phonetic Alphabet, a standardardized phonetic spelling.
"byname"
an optional explanatory addition to the name for constellations and stars only. May be helpful
v 25.3
to explain mythological figures. This is translated to users’ language, but is not included in search
functions.
"context"
(optional) Short english explanation that helps to disambiguate terminology. Not displayed in
the program.
"translators_comments" (optional): comments to be shown to translators on Transifex.
"references" (optional): array of integers, referring to the references list in description.md.
As example, we show a part of the Samoan skyculture:
" co m m o n _ n a m e s " : {
" HIP 32349 ": [ { " englis h " : " Glid i ng Star ", " nati ve ": "F¯et¯usolonu
‘
u"}] ,
" HIP 68702 ": [ { " englis h " : " Mea " , " nati ve ": " Mea "}] ,
" HIP 71683 ": [ { " englis h " : " Filo ", " nati ve ": " Filo "}] ,
" M45 ": [ {" engl ish ": " Face of Li
‘
i", " native ": "Mat¯ali
‘
i"}] ,
" NGC205 5 " : [ {" eng lish ": " Pale Cl oud ", " nati ve ": " Aotea " } ] ,
" NGC29 2 ": [ { " englis h ": " Fly ing Cloud ", " nati ve ": " Aolele " } ] ,
" NGC609 3 " : [ {" eng lish ": " Pae "} ],
" NGC612 1 " : [ {" eng lish ": " Suga "}] ,
122 Chapter 9. Sky Cultures
" NAME Earth " : [ {" eng l ish ": " Eart h " , " na tive ": " Lalolag i " } ] ,
" NAME Jup iter ": [{ " engl ish ": " Un dying Mys tery " , " native ": "Tupual¯egase"} ] ,
" NAME Mars ": [ { " englis h " : " Redd i sh Face / S urface " , " na tive ": " Matamemea " } ],
" NAME Mer cury ": [{ " engl ish ": " Br o w nish " , " native " : " Ta ' elo " }] ,
" NAME Moon ": [ { " englis h " : " Moon ", " nati ve ": "M¯asina"} ],
" NAME Sa turn ": [{" en glish ": " Garla n d Star ", " nativ e ": "F¯et¯u
‘
¯asoa"} ],
" NAME Sun ": [ { " engli sh ": " Sun " , " na tive " : "L¯a"} ] ,
" NAME Venus " : [ {" eng l ish ": " Mo rning Star / F o r bidden Radia n ce " , " nativ e ":
↪ " Tapu ' itea "} ]
}
9.2.7.1 No translation in Modern Skyculture?
The star names that have been collected over the years in our default Modern skyculture come from an
extensive collection of sources. Some names from Latin and Arab sources have a well-known meaning. In
contrast to what we recommend for non-modern skycultures, we still keep the original name as translation in
the
"english"
string, as such names are used internationally, without thinking about the translated meaning.
Translated names may show slight, language dependent, spelling variations, or transliterations to other glyph
systems, though. At best, the "byname" can transport a translation of the meaning to user language.
9.2.7.2 Star names
The Keys for stars generally start with
"HIP "
. The associated array contains again dicts providing
"native"
(original) and
"english"
(translatable) spellings of the star names, and
"references"
(optional but highly
recommended) which indicates in which sources (see 9.1.2) these star names or particular spellings occur.
The
"english"
name will be translated. An additional
"native"
entry can be given, which is the culture-
native version of the spelling (also in language-specific glyphs when available in UTF8 and the current font)
and will never be translated but can be shown on screen if so configured.
" c o mmo n_n ame s ": {
" HIP 6 7 7 " : [{ " nat i ve " : " Alpher atz " , " eng l ish " : " Al phe r atz " , " re f er e nce s ": [1
↪ , 2 , 5 ,6 ,1 1 ,12 ,3 7] } ,
{" n ative " : " Si r rah " , "e n glis h ": " Sirr a h " , " r e fer e nce s " : [ 23 ,3 7] }] ,
" HIP 7 4 6 " : [{ " nat i ve " : " C aph " , " en g lish " : " Caph " , " r efe ren c es " : [1
↪ , 2 , 6 ,1 1 ,12 ,2 3 ,37 ]} ,
{" n ative " : " Al S a nam al Nakah " , " en g lish ": "Al Sanam al Nakah " , " re f ere n ce s ": [37 ]} ] ,
... }
When there is more than one name for a star, the first in the list is used as screen label.
9.2.7.3 Planet Names
The "common_names" array can also contain dicts of native names of the planets. For these, the JSON key
is formed from
"NAME "
, a space and the English name of the planet. The value array provides the dict
entries ("native", "english", . . . ) listed above.
Currently, if more than one
"english"
strings are given, the first is used as screen label. This may
change as the features further evolve.
In some cultures, Venus and even Mercury may have different names, depending on evening or morning
v 25.2
visibility. We can add a tag
"visible"
which may be either
"morning"
or
"evening"
to select the name.
If the base name should be the screen label, you must repeat it as first entry of the object’s
"NAME "
name
array. If the elongation-dependent name should be screen label, place the names with
"visible"
first, then
repeat the standard name to be shown in the Info text. See the examples for Venus as Morning Star and
Evening Star in the modern skyculture.
In earlier versions it was recommended to combine the native name with an English translation. In the
new format here we should keep them separate, and the actual screen label can be combined from available
components on the fly (see 4.4.6).v 25.2
9.2.8 Deep-Sky Objects Names
"common_names"
can also contain native names for deep-sky objects (DSO). The content of the dicts is
similar to the format for planet names above. Known tags are
"english" English meaning
"native" (optional) Native name. May be in native glyphs when supported in UTF8.
"pronounce" (optional) Native name in European glyphs, if needed. For Chinese, expect Pinyin here.
"transliteration"
(optional) Scientific transliteration of the native name in European glyphs, if needed.
"IPA" (optional) International Phonetic Alphabet.
"context"
(optional) Short english explanation that helps to disambiguate terminology. Not displayed in
the program.
9.2 Technical data: index.json 123
"translators_comments"
(optional) English explanations that help in translation. Not displayed in the
program.
"references" (optional) the sources for these names where applicable
9.2.9 User Settings for the Skycultures
The large number of label combinations requires storing them in a user accessible way. In essence, we are
v 25.2
using a 6-bit scheme with name elements that either show up or are omitted.
Native to show the native name in native glyphs.
Pronounce to show a Latin-character based transliteration usable as pronunciation aid.
Translit to show a scientific transliteration that is not necessarily aimed at pronunciation.
Translated to show the meaning of the name translated to user language.
IPA to show the name in International Phonetic Alphabet.
Modern to show the contemporary scientific object name.
The names for the active parts are joined with commas (the sequence of entries is irrelevant and does not
influence displayed order), and the resulting strings stored in config.ini in two dedicated sections like:
[ SC InfoLabe l S t y l e ]
arabic _ a r a bia n _ p e nins u l a = Native , P ronounce , Mode rn
bo o rong = Native , Translate d
ch i nese = Native , Pronounce , Translated , Mod ern
mo dern = Native , Mod ern
russian_siber i a n = Native , Pronounce , Translit , Translat ed , IPA , Modern
[ SCScreenLabe l S t y l e ]
arabic _ a r a bia n _ p e nins u l a = Pronounce , Translated , Moder n
aztec = Native , Translated
ch i nese = Pronounce , Transla ted , Mod ern
mo dern = Native , Mod ern
russian_siber i a n = Pronounce , Transla ted , Mod ern
9.2.9.1 Not enough, or too many names?
Over the years, we have collected a quite extensive list of star names from many references. Until recently,
the scientific community was not interested in standardizing names. With the introduction of Exoplanet
naming contests, the International Astronomical Union started to also be concerned with the names of the
brighter stars, and a proper Working Group on Star Names has formed.
Stellarium comes with a list of standardized names in
skycultures/common_star_names.fab
. These
are always used when a skyculture shows
"fallback_to_international_names"
(see 9.2). If you always
want to see these names, regardless of whether they are used or not in the respective skyculture, add the
following to your config.ini:
[ viewing ]
fl ag _s ky cu lt ur e_ al wa ys _fallback_to_internatio na l_ na me s = true
Activating this flag for non-modern skycultures may feel weird, though, as it mixes these names into the
other-cultural namespace.
Excluding excessive names
In contrast, some of the collected names may be too fanciful for your taste. If you can identify that those
v 25.2
names that irritate you all come from a single or just a few entries of the reference list, you can exclude those
sources, and thus the names they bring into the program. Note that if a fancy name comes from more than
one book, you would have to exclude all books to ban that name from your display.
In a similar way, some of the collected asterisms (secondary figures), especially in the default Modern sky
culture, may be too much for you. There are overlapping entries like the “Winter Hexagon” vs. “Heavenly
G”, or parts of constellations like Orion’s shield and cudgel are marked as asterism. Some users may find
that this clutters their screens too much. If you cannot identify a reference which introduces the unwanted
asterism (for some entries we cannot specify a source, unfortunately), you can also exclude them by their
unique abbreviation, which is the last part of their "id" entries.
To exclude entries from being displayed for a particular skyculture, add an entry like this to
config.ini
:
[ S CExclud eRefere nces ]
modern = 11 ,36 , OrB , OrS , OSh ,OrC ,HeG ,Sal , TPT
124 Chapter 9. Sky Cultures
Here,
modern
names the skyculture, and the comma-separated entries are references listed in the file
description.md or asterism abbreviations you want to be ignored.
9.3 Terr itory description
Most traditional skycultures are regional. The map interface in the View dialog should indicate where on
v 26.1
Earth a skyculture is located. Stellarium makes use of a file in the GeoJSON format,
territory.geojson
,
to encode where and when this culture is located. In case a cultural group can be traced over a longer time
and the culture has moved or spread, the time slider below the map will show the changes in the geographic
regions.
GeoJSON is a flexible and simple JSON-based format to encode a collection of geographic features
(points, lines and polygons) with geographic coordinates (pairs of longitude/latitude in decimal degrees,
WGS84). Additional properties can be given in a
"properties"
dictionary. Stellarium only uses polygonal
features, and stores
"beginDate"
and
"endDate"
data (calendar years) for each polygon. If the end date
should be “now”, this is indicated by a special value 9146.
An example (Norse (Edda) SC):
{
" type ": " FeatureCollec t i o n " ,
" features " : [
{
" type ": " Feature " ,
" pr o p erties ": {
" be ginTime ": 80 0 ,
" endTim e " : 1 40 0
} ,
" geometry " : {
" co o r d i n a tes ": [
[
[ -2 2 . 74 6 44 2 92 1 5 26 3 24 , 6 4 .1 3 2 94 9 59 3 28 3 9 7 ] ,
[ -2 2 . 43 7 76 2 17 9 2 97 2 45 , 6 4 .0 3 1 76 5 02 1 70 1 2 9 ] ,
...
[ -2 2 . 81 8 12 7 60 2 7 43 7 8, 64.0 8 8 85 2 23 3 0 67 7 7 ]
]
] ,
" type ": " Polygon "
}
} ,
...
]
}
9.4 The Skyculture Converter
Many sky cultures have been created and maintained outside of Stellarium. They follow the old format,
which is no longer supported since Stellarium version 25.1. To ease the transition we have developed a
converter tool. It is a console application that takes a path to the old-format sky culture directory, and a path
where to put the converted sky culture.
The converter is installed together with the program, but there is no menu entry for it. On Windows,
press the Windows key and type cmd to startup the command console.
Let us assume you have created a skyculture following the format used until version 24.4 and described
in previous editions of this Guide, and that this skyculture
mine
resides in the default user data directory on
Windows (see 5.1 for other platforms). First we rename the skyculture to indicate that it is old and outdated.
Then we must call the converter in its absolute path name, with names of old (source) and new (target)
directories as program arguments.
Example command to run it:
cd c :\ Users \< ME >\ AppDa ta \ Roam ing \ s kyc ul tur es
move mine mine . old
"c :\ Program Files \ s tel lar ium \ skyculture - conve rte r " mine . old mine
While the converter tries hard to convert the description text from HTML to Markdown adding some
sections from other parts of the sky culture, the conversion result may not be perfect. Formerly the description
9.5 Publish Your Work 125
was completely free in structure, while now there are some structural requirements on it, so the text may
need some editing to conform.
If you have gettext translation files (the ones whose names are in the form
locale-name.po
) for the
names of stars, constellations etc., you can pass the path to the directory that contains them as an optional
third positional argument to the converter.
Additionally, there are some options that you can use to control the conversion:
--footnotes-to-references
Convert footnotes in a particular form to references. Such footnotes are
expected to be in the form of
<p id =" footnote -9 " > This is a foo tnote </p>
while the references to them are expected to be in the form of
<sup ><a href = "# footnote -9 " > [9] </ a></ sup >
--untrans-names-are-native
Put the names that in
star_names.fab
or in
dso_names.fab
are de-
noted without an underscore into the
"native"
section of the name, rather than
"english"
. For
example, with this option
32349|("F¯et¯usolonu
‘
u")
would be used for the
"native"
name, while
32349|_("Gliding Star") would be used for the "english" tag.
--native-locale LOCALE
In addition to files
star_names.fab
or
dso_names.fab
, some sky cultures
have localized versions of them, like e.g.
star_names.zh_CN.fab
, that were never actually used
but do contain useful information. If you pass the locale (
zh_CN
in this example) as the
LOCALE
parameter, these names will be read and put into the
"native"
section of the corresponding JSON
entry. Note that the order of stars/DSOs in the normal and localized files must be the same, otherwise
there’s no way to match the names.
--translated-md
To check the look of the translated description texts you can use this option. The output
directory will contain files named like
description.es_419.DO_NOT_COMMIT.md
, in addition to
description.md
, with the
DO_NOT_COMMIT
part reminding you that they are not a part of the sky
culture.
After the run, read the notes and warnings, and adjust your text accordingly. Make especially sure to prepare
and adjust your old
description.en.utf8
for successful conversion. For example, it must start with an
HTML header of level
<h1>
(the only such header in this file!) which is expected to match the skyculture
name given in the old info.ini. If in doubt, the latter will be used in the new files.
Generally, clean HTML should be converted successfully. Given the wide variety of writing styles, not
every conversion may however work flawlessly, and you may have to adjust the result, also in light of the
new features. To protect any changes you may have added after conversion, running the converter again
needs a new target directory.
9.5 Publish Your Work
If you are willing to let other users enjoy the result of your hard work (and we certainly hope you do!),
when you are done, please write a note in the Forum or at GitHub. We will decide about acceptability and
classification, or may ask for better descriptions for the benefit of our users.
Please put the imagery and text under some compatible open-source license (see 9.1.3). Else the sky
culture cannot be hosted by us. While we cannot be held responsible for legal problems, it seems that CC BY
4.0 International
6
or CC BY-SA 4.0 International
7
licenses are best suited. See notes in section 9.1.3 above.
6
https://creativecommons.org/licenses/by/4.0/
7
https://creativecommons.org/licenses/by-sa/4.0/
10. Surveys
GUILLAUME CHÉREAU
10.1 Introduction
A sky survey is a map of the sky stored as a hierarchical set of a potentially large number of smaller images
(called tiles). The advantage compared to a regular texture is that we need to render only the visible tiles of
a potentially gigantic image at the lowest resolution needed. This is particularly interesting for rendering
online images that can be stored on a server, while the client only has to download the parts he currently uses.
Since version 0.18.0, Stellarium added some preliminary support for loading and rendering online
surveys in the Hierarchical Progressive Surveys (HiPS) format, developed by the International Virtual
Observatory Alliance. A full description of the format can be found on the IVOA website
1
.
10.2 Hipslist file and default surveys
Hipslist files are text files used to describe catalogs of HiPS surveys. The full specification is part of the
HiPS format, and looks like that:
# Exa m ple of a h i pslist file .
# Date : 2018 -03 -19
obs _ t i tle = call i s to
hips_service_ u r l = https :// data . stellarium . org / survey s / cal l i sto
hips_relea s e _ d a t e = 2018 -03 -18 T14 :01 Z
hips_s t a t u s = pub lic mi rror clonableOnce
...
Stellarium by default tries to load HiPS from two sources:
•
http://alasky.u-strasbg.fr/MocServer/query?*/P/*&get=record (deep sky)
•
https://data.stellarium.org/surveys/hipslist (planets)
This can be changed with the
sources
entries in the
[hips]
section of the configuration file (see also
section D.1.30). You can add your own private HiPS surveys by either running your own (even machine-local)
webserver, or just placing your files into any directory and adding a file:// URL:
[ hips ]
so u rces /1/ url = http :// ala sky .u - s t rasbg .fr / M o c S erver / query ?*/ P /*& get = reco rd
so u rces /2/ url = ht tps :// data . stellariu m . org / survey s / hip s list
so u rces /3/ url = http :// localhos t / Stella r i u m / hips / hipslist
so u rces /4/ url = file :/// D:/ S t ellarium / h ips / hi pslist
so u rces / size = 4
1
https://www.ivoa.net/documents/HiPS/20170519/REC-HIPS-1.0-20170519.pdf
128 Chapter 10. Surveys
10.3 Solar system HiPS survey
Though not specified in the HiPS standard, Stellarium recognises HiPS surveys representing planet textures,
as opposed to sky surveys. If the
obs_frame
property of a survey is set to the name of a planet or other solar
system body, Stellarium will render it in place of the default texture used for the body.
10.4 Digitized Sky Survey 2 (TOAST Survey)
GEORG ZOTTI, ALEXANDER WOLF
The older way to provide a tessellated all-sky survey uses the TOAST encoding
2
. Stellarium provides access
to the Digitized Sky Survey 2, a combination of high-resolution scans of red- and blue-sensitive photographic
plates taken in 1983–2006 at Palomar Observatory and the Anglo-Australian Observatory.
3
To enable access to the DSS layer, see section 4.3.3 and enable the DSS button. Then just press that
DSS button in the lower button bar, wait a moment, zoom in and enjoy!
10.4.1 Local Installation
This display normally requires access to the Internet. However, in some situations like frequent and extensive
use in fixed observatories, or use in the field when Internet connection is not possible, you can download all
image tiles to your local harddisk for local use. Please be considerate, don’t waste bandwidth, and do this
only if you really need it.
The images are stored in subdirectories that increase in size and number of files (see Table 10.1).
Zooming in loads the next level if available.
Level No of files Filespace (kB)
Level No of files Filespace (kB) Level No of files Filespace (kB)
0 1 32 4 256 7.172 8 65.536 1.661.808
1 4 124
5 1.024 27.920 9 262.144 6.119.092
2 16 472
6 4.096 109.628 10 1.048.576 20.250.216
3 64 1.820
7 16.384 429.800 11 4.194.305 83.583.724
Table 10.1: Number of files and storage requirements for local DSS TOAST installation
For partial downloads, you can limit the maximally used level (e.g. 9 or 10). The difference from level
10 to 11 is really hardly noticeable, yet level 11 contains almost 75% of all data. On a small system like
Raspberry Pi 3, you may run into troubles with too little texture memory when level is more than 7.
Another issue: the level 11 subdirectory holds over 4 million files. Windows Explorer is not optimized
to open and display this number of files and will take a long time to open. Just unpack this archive, but don’t
access the folder with Explorer.
If all that does not discourage you, you can download the archives at
https://dss.stellarium.org
/offline/.
Then add a few entries to the
[astro]
section in Stellarium’s
config.ini
. On Windows, if you have
a harddisk
T:
with path
T:\StelDSS
that contains the unpacked image subdirectories 0, 1, 2, . . . , 10, the
section may look like
[ astro ]
to as t_sur ve y_direc tory = StelDSS
to ast_s urvey _host = T :/
to ast_sur vey_l evels = 10
On Linux, with the files stored in
/usr/local/share/Stellarium/StelDSS
, the same section could look
like
[ astro ]
to as t_sur ve y_direc tory = usr / local / share / S tel lar ium / Stel DSS
to ast_s urvey _host = /
to ast_sur vey_l evels = 10
2
Please see http://montage.ipac.caltech.edu/docs/WWT/ for details
3
The original data are available at https://archive.stsci.edu/cgi-bin/dss_form.
11. Stellarium’s Skylight Models
GEORG ZOTTI
11.1 Introduction
Stellarium’s main aim is a realistic simulation of the night sky. This is more than just the creation of a star
map. Especially a realistic simulation of twilight and the visibility of stars, deep-sky objects or the Zodiacal
light is a challenge. Since early in its history Stellarium has used models from the computer graphics
literature to achieve its goals. For most users, the models seem to work well, but more advanced users may
want to tweak some of the values.
11.2 The Skylight Models
11.2.1 Legacy Mode: The Preetham Skylight Model
A well-known fast computer graphics model for daylight has been presented by Preetham, Shirley, and Smits
(1999). Its brightness distribution is based on an all-weather model for sky luminance distribution by Perez,
Seals, and Michalsky (1993) and models chromaticity distribution with similarly-shaped functions. It works
reasonably well for average conditions, and a “turbidity” parameter
T
allows a simple modelling of visibility
conditions. In terms of the atmospheric extinction coefficient k (see 19.13.1), we can define
T = 25(k − 0.16)+ 1 (11.1)
In Stellarium, a value of
T = 5
has been used for many years, and the chromaticity parameters have been
slightly changed for a more pleasing color distribution at this value for
T
. Recently, we have made the many
parameters of the Preetham model accessible for users to fine-tune. Not many users will even want to do this,
and therefore you must enable this manually by editing config.ini:
[ Skylight ]
enable_gui = true
Only with this setting, a button will be available in the View settings, Sky tab (section 4.4.1.2).
All settings described here will immediately be stored in config.ini.
One setting allows to compute T from k with the above relation 11.1.
Please note that the parameters are far from intuitive, therefore we added two sets of reset functions. One
sets the values to those in the original paper, the other re-establishes Stellarium’s sky colors from version
0.21.3 and earlier, which however seem only suitable for T = 5.
130 Chapter 11. Stellarium’s Skylight Models
A sky brightness model better suited for astronomical simulation, including twilight and brightness
contributions of the Moon and airglow, was presented by B. E. Schaefer (1989-93 and 1993). By default,
Stellarium uses this model in combination with chromaticity from the Preetham model. For experiments,
you can however revert from the Schaefer brightness model to the Preetham model. The parameters of the
Schaefer model are currently not accessible for further experiments.
Some more parameters fine-tune some aspects of rendering of the Solar disk and the solar glare. It makes
a slight difference whether the Sun’s disk is plotted before or after the glare, and whether the solar sphere is
rendered after the atmosphere.
11.2.2 Advanced Mode: The ShowMySky Skylight Model
A much more advanced skylight model has been presented by Bruneton and Neyret (2008). An implementa-
tion of this has been developed by Ruslan Kabatsayev just in time for inclusion in version 1.0. Switching
between the models is described in section 4.4.1.2.
It requires graphics hardware which uses OpenGL 3.3 or better and consists of two components.
Atmospheric data (a description of gas composition) is processed by an auxiliary program, CalcMySky,
which creates a lot of textures and shaders. For final display, a software component (the ShowMySky library)
is used that processes these data in real-time to compute the final sky colors. This model and its default
atmosphere data especially can deliver stunning reality of twilight colors in a dry atmosphere, and also
provides special modes for the “circular twilight” during a Total Solar Eclipse.
To choose a dataset
press near the Path to data entry field, and in the dialog that opens, choose the
directory with the dataset. Stellarium comes with a default dataset that’s automatically chosen after a
fresh installation. Power users can use CalcMySky
1
to generate other atmospheres. Creating a new
dataset requires some understanding of the physics of light scattering.
Eclipse simulation quality
option lets you configure the balance between realism of skylight simulation
during a solar eclipse. The values of this option can be:
0
This is the fastest and crudest mode. The atmosphere is simply dimmed to account for the lower
amount of direct sunlight.
1
This is the first mode that actually tries to simulate an eclipse. It uses precomputed textures, and
may look blocky in some cases like e.g. very low Sun (and Moon).
2
This mode is much slower than the previous one (2.5 FPS on an NVIDIA GeForce GTX 750Ti).
In this mode part of the calculation is done on the fly for the current eclipse phase to improve
correctness of the simulation, unlike the previous mode where a texture was used that contains
data only for totality, other phases being approximated from this.
3
This is the slowest mode (1.1 FPS on NVIDIA GeForce GTX 750Ti), but computation is done on
the fly for the whole simulation, which yields best quality.
To achieve higher frame rates on slow systems, the configuration parameter in config.ini:
[ landscape ]
at mo sp here_reso lu ti on_reduct io n = 4
allows reducing the resolution of the skylight texture. Preferred values are:
1 full resolution (default)
2 half resolution
4 quarter resolution
The configuration switch in config.ini:
[ landscape ]
fl ag _a tm osphere_d yn am ic_resoluti on = true
allows to use the reduced resolution only while moving the view, when panning, zooming, dimming
or in time-lapse mode. With the real-time display, on the other hand, the full resolution is retained.
Possible values are:
false static resolution (default)
true dynamic resolution
1
https://github.com/10110111/CalcMySky
11.3 Light Pollution 131
Note:
In dynamic resolution mode, a motion analyzer selects either full or reduced resolution. The change
in resolution could be particularly visible in close proximity to the Sun. Especially at full resolution,
frames will be skipped depending on the speed of movement.
A more detailed description of how to create a custom atmosphere will be given in a future version of this
User Guide.
11.2.3 Intermediate Mode: The Lightweight Skylight Model
This model combines a realistic view of the sky as in ShowMySky with light weight of the Preetham model,
v 26.2
at the cost of being fixed to simulating a sea level sky (just as Preetham), lacking the realism of eclipse
simulation (also as Preetham), and having no parameters to tweak.
The Lightweight model is based on a set of meshes generated from a render of ShowMySky, so its look
is just as realistic (at sea level and without any eclipse) as that of ShowMySky, except for the solar aureole,
which is a bit simplified.
This model is intended to eventually become the default skylight model when it’s proven to be stable
enough to replace the Preetham model on all platforms, including the weakest ones.
11.3 Light Pollution
In urban and suburban areas the night sky is lit by ground sources of light. This light is scattered by the
atmosphere, and the sky appears brighter. This reduces visibility of astronomical objects.
Stellarium simulates this effect. The main physical quantity that describes light pollution is zenith
luminance, measured in candelas per square meter (
cdm
2
). It can be measured using a device called sky
quality meter (SQM).
For astronomical observations often another unit of sky brightness is useful: magnitudes per square
arcsecond (magarcsec
2
). It is related to cdm
2
as
L = 10.8× 10
4−0.4M
, (11.2)
where
L
is the value in
cdm
2
, and
M
is the value in
magarcsec
2
. Some SQMs give readings in
magarcsec
2
.
Stellarium supports input in both units.
Another way to characterize light pollution is by defining the naked-eye limiting magnitude (NELM).
Unlike luminance, which, although based on human vision, is well-standardized (in particular, the candela is
part of the SI), NELM is subjective and variable: it is based on human vision, depends on weather conditions,
and is not standardized. In Stellarium the calculations follow B. E. Schaefer (1990). In particular, equation
(18)
is used, assuming observer’s acuity
F
s
= 1
(as suggested in the text as “typical observer”), and absorption
term k
v
= 0.3 (as suggested for “typical weather”).
A related subjective characterization of light pollution is the Bortle Dark Sky Scale, which assigns an
integral number from 1 to 9 to the sky based on its brightness. This scale is described in detail in Appendix B.
Stellarium calculates both Bortle class and NELM for user convenience. They aren’t used in the actual
calculations for visualization.
11.4 Tone Mapping
Tone mapping is the process which attempts to compress the brightness values found in nature into the
range of brightness values which can be achieved on a display device so that an image of a natural scene
looks reasonably natural and realistic. The process has been described by Tumblin and Rushmeier (1993),
Larson, Rushmeier, and Piatko (1997) and Devlin et al. (2002). For low-light conditions like night and the
transitional phase, twilight, special considerations have to be taken, first described by Jensen et al. (2000).
Stellarium’s transformation from skylight model to display colors is based on these papers.
Parameters to tweak the tone mapping can be reached in the view settings dialog after pressing
.
Display max luminance
maximal brightness of the used screen. This used to be
100cdm
2
applicable
for CRT monitors, but more modern screens can achieve much higher luminances of
250cdm
2
or
more, to be found in the spec sheets. Adjust this value to influence the displayed brightness along the
horizon.
Display adaptation luminance
describes the view environment where the screen is set up. For an average
office environment,
50cdm
2
seems a usable default. In an outdoor setting, much higher values are
possible.
132 Chapter 11. Stellarium’s Skylight Models
Display Gamma
describes the exponent of a nonlinear correlation between input values and output lumi-
nance of the screen. Higher values push the average image brightness.
Use extra Gamma term The original implementation of tone mapping included a gamma term which did
not exactly follow the description from Larson, Rushmeier, and Piatko (1997), but looks better (more
colorful) than the implementation without the gamma term. You can now play with it to find your
preferred setting. This flag is only used with the Preetham skylight model.
Use sRGB
The final step of color creation is a transformation from CIE Yxy to some display RGB color
space. Nowadays most monitors can display the sRGB color space, therefore this flag is usually
enabled. Disabling this flag will lead to using the Adobe RGB (1998) color space. The colors may
look a bit better on monitors which are set to display Adobe RGB, but washed-out on sRGB monitors.
III
Extending Stellarium
12 Plugins: An Introduction . . . . . . . . . . . . . 135
12.1 Enabling plugins . . . . . . . . . . . . . . . . . . . . . . . . 135
12.2 Data for plugins . . . . . . . . . . . . . . . . . . . . . . . . 135
13 Interface Extensions . . . . . . . . . . . . . . . . 137
13.1 Angle Measure Plugin . . . . . . . . . . . . . . . . . . . 137
13.2 Equation of Time Plugin . . . . . . . . . . . . . . . . . . 139
13.3 Pointer Coordinates Plugin . . . . . . . . . . . . . . . 140
13.4 Time Navigator Plugin . . . . . . . . . . . . . . . . . . . 141
13.5 Text User Interface Plugin . . . . . . . . . . . . . . . . . 142
13.6 Remote Control Plugin . . . . . . . . . . . . . . . . . . . 145
13.7 Remote Sync Plugin . . . . . . . . . . . . . . . . . . . . . 148
13.8 OnlineQueries Plugin . . . . . . . . . . . . . . . . . . . . 151
13.9 Sky Culture Maker Plugin . . . . . . . . . . . . . . . . . 152
13.10 Solar System Editor Plugin . . . . . . . . . . . . . . . . 159
13.11 Nebula Textures Plugin . . . . . . . . . . . . . . . . . . . 162
13.12 Calendars Plugin . . . . . . . . . . . . . . . . . . . . . . . 164
14 Object Catalog Plugins . . . . . . . . . . . . . 171
14.1 Bright Novae Plugin . . . . . . . . . . . . . . . . . . . . . 171
14.2 Historical Supernovae Plugin . . . . . . . . . . . . . . 173
14.3 Exoplanets Plugin . . . . . . . . . . . . . . . . . . . . . . . 176
14.4 Pulsars Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . 188
14.5 Quasars Plugin . . . . . . . . . . . . . . . . . . . . . . . . . 190
14.6 Meteor Showers Plugin . . . . . . . . . . . . . . . . . . . 191
14.7 Navigational Stars Plugin . . . . . . . . . . . . . . . . . 194
14.8 Satellites Plugin . . . . . . . . . . . . . . . . . . . . . . . . 197
14.9 ArchaeoLines Plugin . . . . . . . . . . . . . . . . . . . . 202
15 Scenery3d – 3D Landscapes . . . . . . . . 207
15.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
15.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
15.3 Hardware Requirements & Performance . . . . . 208
15.4 Model Configuration . . . . . . . . . . . . . . . . . . . . 208
15.5 Predefined views . . . . . . . . . . . . . . . . . . . . . . . 215
15.6 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
15.7 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
16 Stellarium at the Telescope . . . . . . . . . 219
16.1 Oculars Plugin . . . . . . . . . . . . . . . . . . . . . . . . . 219
16.2 TelescopeControl Plugin . . . . . . . . . . . . . . . . . 232
16.3 Observability Plugin . . . . . . . . . . . . . . . . . . . . . 240
16.4 Mosaic Camera Plugin . . . . . . . . . . . . . . . . . . 241
17 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
17.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
17.2 The Script Console . . . . . . . . . . . . . . . . . . . . . . 246
17.3 Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
17.4 Minimal Scripts . . . . . . . . . . . . . . . . . . . . . . . . . 246
17.5
Critical Scripting Differences introduced with ver-
sion 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
17.6 Example: Retrograde motion of Mars . . . . . . . 247
17.7 More Examples . . . . . . . . . . . . . . . . . . . . . . . . 251
12. Plugins: An Introduction
Starting with version 0.10.3, Stellarium’s packages have included a steadily growing number of optional
extensions called plug-ins which are presented in the following chapters. All these plug-ins are “built-in” in
the standard Stellarium distribution and don’t need to be downloaded separately.
12.1 Enabling plugins
To enable a plugin:
1. Open the Configuration dialog (press
F2
or use the left tool bar button
)
2. Select the Plugins tab
3. Select the plugin you want to enable from the list
4. Check the Load at startup option
5. Restart Stellarium
If the plugin has configuration options, the configuration button will be enabled when the plugin has been
loaded and clicking it will open the plugin’s configuration dialog. When you only just activated loading of a
plugin, you must restart Stellarium to access the plugin’s configuration dialog. The plugin’s configuration
dialog is also available by right-clicking on the respective plugin’s main button in the bottom button bar.
12.2 Data for plugins
Some plugins contain files with different data, e.g., catalogs. JSON is a typical format for those files, and
you can edit its contents manually. Of course, each plugin has a specific format of data for its own catalogs,
and you should read the documentation for the plugin before editing its catalog.
You can read some common instructions for editing catalogs of plugins below. In this example we use
file name catalog.json for identification of the catalog for a typical plugin.
You can modify the
catalog.json
files manually using a text editor. If you are using Windows, it
is strongly recommended to use an advanced text editor such as Notepad++
1
to avoid problems with
end-of-line characters. (It will also color the JSON code and make it easier to read.)
Warning: Before editing your
catalog.json
file, make a backup copy. Leaving out the smallest detail
(such as a comma or forgetting to close a curly bracket) may prevent Stellarium from starting.
As stated in section 5, the path to the directory
2
which contains catalog.json file is something like:
Windows C:\Users\UserName\AppData\Roaming\Stellarium\modules\PluginName
macOS HomeDirectory/Library/Application Support/Stellarium/modules/PluginName
Linux and UNIX-like OS ~/.stellarium/modules/PluginName
1
https://notepad-plus-plus.org/
2
This is a hidden folder, so in order to find it you may need to change your computer’s settings to display hidden
files and folders.
13. Interface Extensions
Most users will soon be familiar with the usual user interface. A few plugins are available which extend the
regular user interface with a few small additions which are presented first. However, some applications and
installations of Stellarium require completely different user interfaces. Mostly, these serve to avoid showing
the user interface panels to an audience, be that in your astronomy club presentations, a domed planetarium
or in a museum installation.
13.1 Angle Measure Plugin
goes misty eyed
I recall measuring the size of the Cassini Division when I was a student. It was not the high
academic glamor one might expect. . . It was cloudy. . . It was rainy. . . The observatory lab had
some old scopes set up at one end, pointing at a photograph of Saturn at the other end of the lab.
We measured. We calculated. We wished we were in Hawaii. A picture is worth a thousand
words.
Figure 13.1: Interface of Angle Measure plugin
The Angle Measure plugin is a small tool which is used to measure the angular distance between two points
138 Chapter 13. Interface Extensions
on the sky.
1.
Enable the tool by clicking the tool-bar button , or by pressing
Ctrl
+
A
. A message will appear
at the bottom of the screen to tell you that the tool is active.
2. Drag a line from the first point to the second point using the left mouse button.
3. To measure to a different endpoint, click the right mouse button.
4.
To deactivate the angle measure tool, press the tool-bar button again, or press
Ctrl
+
A
on the
keyboard.
In the configuration dialog, you can configure if you want to have distances given on the rotating sphere, or
in horizontal (alt-azimuthal) coordinates. You can also link one point to the resting horizon, the other to the
sky and observe how angles change. You can choose where to display the measurement.
When option “Allow snap to selected object” is activated the process of measurement is changed:
•
The left mouse button is not used for angle measurement, so you can pan the screen and left-click to
select an object as usual.
•
To draw the angle dimension line, you can drag with the right mouse button.
•
A right click moves the end of the angle line that is closest to the mouse pointer.
•
If an object is selected, right-clicking will snap the end of the protractor line (closest to the mouse
pointer) to the selected object.
•
Double-click the right mouse button to capture the end of the line. Another double click with the right
mouse button removes the angle measuring line.
•
Which end of the protractor line is chosen depends on the position of the mouse pointer in relation to
the two ends of the line. The end of the line that is closer to the mouse pointer is moved and defined
as the new end point. The end of the line farther from the mouse pointer is not moved and is defined
as the new starting point.
13.2 Equation of Time Plugin 139
13.2 Equation of Time Plugin
-20 -15 -10 -5 0 5 10 15 20
-25
-20
-15
-10
-5
0
5
10
15
20
25
Ari
Tau
Gem
Cnc
Leo
Vir
Lib
Sco
Sgr
Cap
Aqr
Psc
-20 -15 -10 -5 0 5 10 15 20
-25
-20
-15
-10
-5
0
5
10
15
20
25
Ari
Tau
Gem
Cnc
Leo
Vir
Lib
Sco
Sgr
Cap
Aqr
Psc
Figure 13.2: Figure-8 plots for Equation of Time, for years 1000 (left) and 2000 (right). These
plots, often found on sundials, link solar declination (vertical axis) and its deviation at mean noon
from the meridian, in minutes. Labeled dots indicate when the sun entered the respective Zodiacal
sign (30°section of the ecliptic). Figures by Georg Zotti.
The Equation of Time plugin shows the solution of the equation of time. This describes the discrepancy
between two kinds of solar time:
Apparent solar time directly tracks the motion of the sun. Most sundials show this time.
Mean solar time tracks a fictitious “mean” sun with noons 24 hours apart.
There is no universally accepted definition of the sign of the equation of time. Some publications show
it as positive when a sundial is ahead of a clock; others when the clock is ahead of the sundial. In the
English-speaking world, the former usage is the more common, but is not always followed. Anyone who
makes use of a published table or graph should first check its sign usage.
If enabled (see section 12.1), click on the Equation of Time button on the bottom toolbar to display
the value for the equation of time on top of the screen.
13.2.1 Section
[
EquationOfTime
]
in config.ini file
You can edit
config.ini
file by yourself for changes of the settings for the Equation of Time plugin – just
make it carefully!
ID Type Description
enable_at_startup bool Display solution of the equation of time at startup of Stellarium
flag_use_ms_format
bool
Set format for the displayed solution – minutes and seconds or
decimal minutes
flag_use_inverted_value
bool Change sign of the equation of time
flag_show_button
bool Show the tool’s button on the bottom toolbar
text_color
R,G,B Font color for the displayed solution of the equation of time
font_size
int Font size for the displayed solution of the equation of time
140 Chapter 13. Interface Extensions
13.3 Pointer Coordinates Plugin
Figure 13.3: Interface of Pointer Coordinates plugin
The Pointer Coordinates plugin shows the coordinates of the mouse pointer. If enabled, click on the plugin
button on the bottom toolbar to display the coordinates of the mouse pointer.
13.3.1 Section
[
PointerCoordinates
]
in config.ini file
You can edit
config.ini
file by yourself for changes of the settings for the Pointer Coordinates plugin –
just make it carefully!
ID Type Description
enable_at_startup bool
Enable displaying mouse pointer coordinates at program
startup
flag_show_button
bool Show the plugin’s tool button on the bottom toolbar
text_color
R,G,B Color for coordinates text of the mouse pointer
font_size
int Font size for the displayed mouse pointer coordinates
current_displaying_place
string
Specifies the place of displaying coordinates of the
mouse pointer. Possible values:
TopRight
,
TopCenter
,
RightBottomCorner, Custom. Default value: TopRight.
custom_coordinates
int,int
Specifies the screen coordinates of the custom place for
displaying coordinates of the mouse pointer
current_coordinate_system
string
Specifies the coordinate system. Possible values:
RaDecJ2000
,
RaDec
,
HourAngle
,
Ecliptic
,
AltAzi
,
Galactic. Default value: RaDecJ2000.
flag_show_constellation
bool
Add the 3-letter IAU abbreviation for the constellation of
the mouse pointer location (Roman, 1987).
flag_show_crossed_lines
bool Show crossed lines under mouse cursor.
13.4 Time Navigator Plugin 141
13.4 Time Navigator Plugin
Figure 13.4: Interface of Time Navigator plugin: Time Steps tab (left), Specific Time tab (center),
and Planetary Events (right)
The Time Navigator plugin brings a convenient GUI to many different astronomical time steps and allows
addition or subtraction of one (1) unit of any of these periods interactively. If enabled (see section 12.1),
click on the plugin button on the bottom toolbar to open the plugin window.
The first tab
Time Steps
shows step buttons for different definitions of days, months and years, and even
longer cycles such as the Saros. The second tab
Specific Time
shows buttons to jump to the previous, current
or next event of the selected object, e.g. its meridian transit, as well as buttons for specific twilight moments.
The third tab
Planetary Events
shows step buttons for some interesting planetary events, such as opposi-
tions for outer planets and greatest elongations for inner planets. For the Moon, the four phases (new, first
quarter, full, last quarter) and times for apogee and perigee are shown, as well as times for Earth aphelion
and perihelion. Clicking any of these buttons sets the time to that of the event.
142 Chapter 13. Interface Extensions
13.5 Text User Interface Plugin
This plugin re-implements the “TUI” of the pre-0.10 versions of Stellarium, an unobtrusive menu used
primarily by planetarium system operators to change settings, run scripts and so on.
13.5.1 Using the Text User Interface
1. Activate the text menu using the
Alt
+
T
key.
1
2. Navigate the menu using the cursors keys.
3.
To edit a value, press the right cursor until the value you wish to change it highlighted with > and <
marks, e.g. >3.142<. Then press the cursor keys and to change the value. You may also type
in a new value with the other keys on the keyboard.
13.5.2 TUI Commands
1 Location (menu group)
1.1
Latitude Set the latitude of the observer in degrees
1.2
Longitude Set the longitude of the observer in degrees
1.3
Altitude Set the altitude of the observer in meters
1.4
Solar System Body Select the solar system body on which the observer is
2 Set Time (menu group)
2.1
Current date/time
Set the time and date for which Stellarium will generate the
view
2.2
Set Time Zone (disabled in 0.15)
2.3
Days keys (disabled in 0.15)
2.4
Startup date/time preset
Select the time which Stellarium starts with (if the “Sky Time
At Start-up” setting is “Preset Time”
2.5
Startup date and time
The setting “system” sets Stellarium’s time to the computer
clock when Stellarium runs. The setting “preset” selects a
time set in menu item “2.4 - Startup date/time preset”
2.6
Date Display Format
Change how Stellarium formats date values. “system_default”
takes the format from the computer settings, or it is possible
to select “yyyymmdd”, “ddmmyyyy” or “mmddyyyy” modes
2.7 Time Display Format
Change how Stellarium formats time values. “system_default”
takes the format from the computer settings, or it is possible
to select “24h” or “12h” clock modes
3 General (menu group)
3.1
Sky Culture
Select the sky culture to use (changes constellation lines,
names, artwork)
3.2
Sky Language Change the language used to describe objects in the sky
3.3
App Language Change the application language (used in GUIs)
4 Stars (menu group)
4.1
Show stars Turn on/off star rendering
4.2
Relative Scale
Change the relative brightness of the stars. Larger values
make bright stars much larger.
4.3
Absolute Scale
Change the absolute brightness of the stars. Large values
show more stars. Leave at 1 for realistic views.
4.4
Twinkle
Sets how strong the star twinkling effect is - zero is off, the
higher the value the more the stars will twinkle.
4.5
Mag limit Sets a custom magnitude cutoff for stars
4.6
Use mag limit Activates this magnitude limit
4.7
Spiky stars Use pointed star figures
4.8
Labels and Markers configures the amount of labels
1
This used to be hard-coded to
M
before version 0.15, but
Alt
+
T
is better to remember as it runs parallel with
Ctrl
+
T
for switching the GUI panels, and frees up
M
for the Milky Way. The
Alt
+
T
keybinding is hard-coded,
i.e., cannot be reconfigured by the user, and should not be used for another function.
13.5 Text User Interface Plugin 143
4.9 Show additional star names
4.10
Use designations for screen la-
bels
5 Colors (menu group) change color/brightness of the. . .
5.1
Constellation lines constellation lines
5.2
Constellation labels labels used to name stars
5.3
Art brightness constellation art
5.4
Constellation boundaries constellation boundary lines
5.5
Cardinal points cardinal points markers
5.6
Planet labels labels for planets
5.7
Planet orbits orbital guide lines for planets
5.8
Planet trails planet trails lines
5.9
Meridian Line meridian line
5.10
Azimuthal Grid lines and labels for the azimuthal grid
5.11
Equatorial Grid lines and labels for the equatorial grid
5.12
Equatorial J2000 Grid lines and labels for the equatorial J2000.0 grid
5.13
Equator Line equator line
5.14
Ecliptic Line ecliptic line
5.15
Ecliptic Line (J2000) J2000 ecliptic line
5.16
Nebula names labels for nebulae
5.17
Nebula hints circles used to mark positions of unspecified nebulae
5.18
Galaxy hints ellipses used to mark positions of galaxies
5.19
Bright nebula hints squares used to mark positions of bright nebulae
5.20
Dark nebula hints squares used to mark positions of dark nebulae
5.21
Clusters hints symbols used to mark positions of clusters
5.22
Horizon line horizon line
5.23
Galactic grid galactic grid
5.24
Galactic equator line galactic equator line
5.25
Opposition/conjunction longi-
tude line
opposition/conjunction line
5.26
Sky background
sky background. Note that anything but black is only useful
for artistic works.
6 Effects (menu group)
6.1
Light Pollution
Changes the intensity of the light pollution (see Appendix B
Bortle Scale index)
6.2
Landscape
Select the landscape which Stellarium draws when ground
drawing is enabled. Press to activate.
6.3
Setting Landscape Sets Location
If “Yes” then changing the landscape will move the observer
location to the location for that landscape (if one is known).
Setting this to “No” means the observer location is not modi-
fied when the landscape is changed.
6.4
Auto zoom out returns to initial
. . . view
Changes the behavior when zooming out from a selected
object. When set to “Off”, selected object will stay in center.
When set to “On”, view will return to startup view.
6.5
Zoom Duration Sets the time for zoom operations to take (in seconds)
6.6
Milky Way intensity Changes the brightness of the Milky Way
6.6
Milky Way saturation Changes the saturation of the Milky Way
6.7
Zodiacal light intensity Changes the brightness of the Zodiacal light
7 Scripts (menu group)
7.1
Run local script
Run a script from the scripts sub-directory of the User Di-
rectory or Installation Directory (see section 5 (Files and
Directories))
7.1
Stop running script Stop execution of a currently running script
8 Administration (menu group)
8.1
Load default configuration Reset all settings according to the main configuration file
144 Chapter 13. Interface Extensions
8.2 Save current configuration Save the current settings to the main configuration file
8.3
Shutdown Emits a command configured in
13.5.3 Section
[
tui
]
in config.ini file
The section in
config.ini
for this plugin is named only
[tui]
for historical reasons. As always, be careful
when editing!
ID Type Description
tui_font_color R,G,B Font color for TUI text
tui_font_size
int Font size for the TUI
flag_show_gravity_ui
bool
Bend menu text around the screen center. May be useful in
planetarium setups, and should then be used together with
“Disc viewport” in the configuration menu (see 4.3.5).
flag_show_tui_datetime
bool Show date and time in lower center.
flag_show_tui_short_obj_info
bool
Show some object info in lower right, or (in planetarium setups
with “Disc viewport” active,) wrapped along the outer circle
border.
admin_shutdown_cmd
string
executable command to shutdown your system. Best used on
Linux or Mac systems. E.g. shutdown -h now
13.6 Remote Control Plugin 145
13.6 Remote Control Plugin
The Remote Control plugin enables the user to control Stellarium through an external web interface using
a standard web browser like Firefox or Chrome, instead of using the main GUI. This works on the same
computer Stellarium runs as well as over the network. Even more, multiple “remote controls” can access
the same Stellarium instance at the same time, without getting in the way of each other. Apart from system
configuration options, most of the functionality the main interface provides is available through it (Zotti,
Schaukowitsch, and Wimmer, 2017).
The plugin may be most useful for presentation scenarios, hiding the GUI from the audience and allowing
the presenter to change settings on a separate monitor without showing distracting dialog windows. It also
allows to start and stop scripts remotely.
Because the web interface can be customized (or completely replaced) with some knowledge of HTML,
CSS and JavaScript, another possibility is a kiosk mode, where untrusted users can execute a variety of
predefined actions (like starting recorded tours) without having access to all Stellarium settings. The web
API can also be accessed directly (without using a browser and the HTML interface), allowing control of
Stellarium with external programs and scripts using HTTP calls like with the tools wget and curl.
This plugin allows also interfacing other programs with Stellarium.
13.6.1 Using the plugin
Figure 13.5: The default remote control web interface
After enabling the plugin, you can set it up through the configuration dialog. You can configure it to start
the web server automatically whenever Stellarium starts or manually start/stop the server using the “Server
enabled” checkbox or the button
in the toolbar.
The plugin starts an HTTP server on the specified port. The default port is 8090, so you should
reach the remote control after enabling it by starting a web browser on the same computer and entering
http://localhost:8090
in the address bar. When trying to access the remote control from another
computer, you need the IP address or the hostname of the server on which Stellarium runs. On a small tablet,
you may want to use http://myserver:8090/tablet7in.html instead.
The plugin shows the locally detected address, but depending on your network or if you need external
access you might need to use a different one — contact your network administrator if you need help with
that.
13.6.1.1 Password
The access to the remote control may optionally be restricted with a simple password.
146 Chapter 13. Interface Extensions
Warning: currently no network encryption is used, meaning that an attacker having access to your
network can easily find out the password by waiting for a user entering it. Access from the Internet to the
plugin should generally be restricted, except if countermeasures such as VPN usage are taken! If you are in
a home network using NAT (network access translation), this should be enough for basic security except if
port forwarding or a DMZ is configured.
13.6.1.2 CORS
The Web API also supports Cross-Origin Resource Sharing (CORS). By enabling CORS, compatible websites
and web apps can be used to control your Stellarium server.
Enable CORS by checking the “Enable CORS for the following origin” option in the configuration
dialog. Then, enter the URL of the website you’d like to use to control Stellarium – e.g.
https://telesc
opius.com. Specify “*” to let any website take control. Do this at your own risk.
13.6.2 Remote Control Web Interface
If you are familiar with the main Stellarium interface, you should easily find your way around the web
interface. The remote control automatically uses the same language as set in the main program. Tabs at the
top allow access to different settings and controls.
Main
Contains the time controls and most of the buttons of the main bottom toolbar. An additional control
allows moving the view like when dragging the mouse or using the arrow keys in Stellarium, and a
slider enables the changing of the field of view. There are also buttons to quickly execute time jumps
using the commonly used astronomical time intervals.
Selection
Allows searching and selecting objects like in section 4.5. SIMBAD search is also supported.
Quick select buttons are available for the primary solar system objects. It also displays the information
text for current selection.
Sky Settings related to the sky display as shown in the “View” dialog as shown in subsection 4.4.1.
DSO The deep-sky object catalog, filter and display settings like in subsection 4.4.4.
Landscape Changing and configuring the background landscape, see subsection 4.4.5
Actions and scripts
Lists all registered actions, and allows starting and stopping of scripts (chapter 17).
If there is no button for the action you want in another tab, you can find all actions which can be
configured as a keyboard shortcut (section 4.3) here.
Location
Allows changing the location, like in section 4.2. Custom location saving is currently not
supported.
Projection Switch the projection method used, like subsection 4.4.4.
13.6.3 Remote Control API
Apart from retrieving quick object info in your browser with e.g.
http://localh ost:8090/api/obj
ects/info?format=json&name=Sun
, you can access a running instance of Stellarium with various
programming languages. A few examples:
13.6.3.1 Commandline
It is possible to send commands via command line, e.g.:
curl -d "x =1& y =0.3 " http :// lo c a l host :8 090/ api / main / m ove
wget -- post - data " id = show . ssc " http :// st ella :809 0/ api / script s / run - O / dev / nu ll
curl -d " id= my Script . ssc " h ttp :// localh o s t :80 90/ api / scrip t s / run
curl -d " id= Lan d s c a p e M g r . fogDisplayed & value = f alse " \
http :// localhos t :809 0/ api / st e l p r o p e rty / set
This allows triggering automatic show setups for museums etc. via some centralized schedulers like cron.
To get a complete pretty-printed list of properties and actions, use:
curl -G -d " pro pId = -2& actio n Id = -2" http :// localho s t :809 0/ api / main / sta tus | \
py thon -m js on . tool
13.6.3.2 Node.js
If you want to use node.js to build your own interface app, you may find the following example helpful.
2
It
sets the view direction in one of 3 coordinate systems, depending on the argument:
" j2000 " : "[x , y ,z ]" ,
" jNow " : " [ x ,y ,z ] ",
" altAz " : "[x , y ,z ]"
2
Thanks to user FogoVoar
13.6 Remote Control Plugin 147
The vector
[x, y, z]
should be a normalized vector (unit length), derived from either J2000.0 or current
equatorial coordinates
(α, δ )
, or from alt-azimuthal coordinates
(Az, alt)
which are however always counted
from south (
[1, 0, 0]
) towards east (
[0, 1, 0]
), with the azimuth
Az
′
counted from South towards East,
Az
′
=
180− Az.
x = cos(
δ)∗ cos(α)
y = cos(
δ)∗ sin(α)
z = sin(
δ)
x = cos(alt)∗ cos(Az
′
)
y = cos(alt)∗ sin(Az
′
)
z = sin(alt)
const url = ’ http ://192 . 1 6 8 . xxx .xxx :8090 / api / main / view ? j200 0 =[0.5 ,0.3 ,0.2] ’;
fetch (url , {
me thod : ’ POST ’ ,
he a ders : {
’ Content - Type ’: ’ a p p l i c a t i o n / json ’
}
})
. then ( respo n s e = > {
res p onse . text (). then ( text = > c o nsole . log (’ Raw respons e : ’, text ));
re turn res p onse . json ();
})
13.6.3.3 Python
An example for time control:
im port req u ests
STELLARIUM_URL = ’ http ://1 9 2 . 1 6 8.1. 1 0 0 : 8 090 / api /main ’
def set_time ( julian_d ay , timerat e ):
url = f"{ STELLARIUM_URL }/ time "
data = " time ="+ str ( julian_d a y )+ " & t i merate =" +str ( t i merate )
print (f " Reque s t URL : { url }" )
print (f " Reque s t Data : { data }" )
try :
res p onse = r equests . post ( url , data = data )
print (f " Respons e S tatu s Code : { respons e . status_ c o d e } " )
print (f " Respons e C ontent : { respo n se . text }")
res p onse . ra i s e _ for_stat u s ()
if re sponse . text . str ip () == " ok" :
re turn {" status " : " succe ss " , " mes sage ": " Time set s u c c e s s f u l l y " }
else :
re turn {" status " : " error ", " messag e " : r esponse . text }
ex cept req u ests . exceptions . Re q u e s t E x ception as e:
print (f " Err or set t ing time : { e } ")
re turn {" status " : " error ", " messag e " : str (e )}
13.6.4 Developer information
If you are a developer and would like to add functionality to the Remote Control API, customize the web
interface or access the API through another program, further information can be found in the plugin’s
developer documentation
3
.
13.6.5 Acknowledgements
This plugin was created by Florian Schaukowitsch in the 2015 campaign of the ESA Summer of Code in
Space
4
programme.
If you are using this plugin in your scientific publications, please cite Zotti, Schaukowitsch, and Wimmer
(2017).
3
https://stellarium.org/doc/head/remoteControlDoc.html
4
https://socis.esa.int/
148 Chapter 13. Interface Extensions
13.7 Remote Sync Plugin
The Remote Sync plugin enables setups which connect several instances of Stellarium running on a network.
This may be useful in installations where one presenter wants to allow a larger audience to follow the actions
on several dim screens (e.g., when you need to avoid a projector’s bright light in a public observatory).
The actions performed on a “master” instance, which acts as a server, are automatically replicated on all
connected clients. These clients may run on the same device the server runs, or may access the server over a
network.
The plugin is still quite experimental, but is provided for testing and developing purposes. You can
configure it through the standard plugin settings dialog (Figure 13.6). One Stellarium instance can either
run in the server mode or connect to an existing server as a client. A custom TCP protocol is used for the
connection. The port used by the server is configurable, and the clients must know the IP address or host
name and the port of the server.
Figure 13.6: RemoteSync settings window
Alternatively, you may start the plugin through command line arguments. This is useful for automated
setups or when multiple instances are running on the same computer. To start the instance as a server, use
the
--syncMode=server
argument with the optional
--syncPort
parameter to specify the port to listen
on. To start a client instance, use
--syncMode=client
and use
--syncHost
and
--syncPort
to specify
the server to connect to.
In the settings window, you can also specify what should happen when the client loses the connection to
its server, and what to do when the server quits normally. You can choose between
Do nothing:
connection is lost and will not be re-established. Stellarium client keeps running in whatever
state it was, waiting for keyboard/mouse interaction.
Try reconnecting:
Assume Stellarium is switched off on the server but may come back online again, or
assume some temporary network problem. Stellarium client just keeps running in whatever state it
13.7 Remote Sync Plugin 149
was, but tries to reconnect.
Quit:
Assume the server always runs until switched off at the end of operating hours. This is intended for
pure client screens without keyboards. When the server is shut down, assume this is the end of the
day, and exit Stellarium. An enclosing run script can then shutdown the client computer before power
is switched off with some main switch.
By default, the following things are synchronized:
•
simulation time
•
viewer location
•
the selected object
•
view direction
•
current field of view
•
all StelProperty-based settings except for GUI-related properties. This includes almost all settings
visible in the configuration dialogs such as projection type, sky and view options, landscape settings,
line colors, etc.
Because there is currently no full time synchronization implemented, for the best results all client computers
should make sure their system clocks are set as close as possible to the server computer’s clock (preferably a
few milliseconds difference at most). This can be done for example by using an NTP server.
5
If all your
Stellarium instances run on the same device, this is of course not necessary.
Figure 13.7: RemoteSync client settings window
It is also possible to exclude some state from being synchronized. On each client, the client configuration
GUI (Figure 13.7) allows to disable specific settings from being synchronized on this client.
The lower part of this dialog allows you to fine-tune which named StelProperties (which hold parts
of the internal program state) should be excluded from synchronization. The configuration dialog lists all
available properties which usually have easy to understand names on the left side. Highlight one or more
properties which you don’t want synchronized and press the arrow button to move them to the list of excluded
properties.
For historic reasons there are two kinds of Properties: Actions (Boolean switches, for which also hotkeys
can be assigned) and (genuine) StelProperties. The latter have names indicating which module they belong
to and may have other data types (numbers, colors, . . . ). Note that the actions frequently are just alias names
of Boolean StelProperties, so in order to inhibit a certain property from being synchronized, you must find
5
Instructions on how to use the public NTP server pool for the most common operating systems can be found at
https://www.pool.ntp.org/en/use.html.
150 Chapter 13. Interface Extensions
both entries.
Properties of plugins will only be visible when the respective plugin has been enabled. When a plugin
has been disabled, its properties may vanish from the stored list of non-synchronized properties.
Each client can have different settings. This could allow installations with several screens where on one
screen you show the constellation figures, another screen shows the distribution of deep-sky objects in the
same frame, and a third screen may show a close-up view of the currently centered object. Or just show
several sky cultures, or show the sky at different locations, . . . .
The names of all available StelProperties from which you might want to select a few to exclude from
synchronisation can also be found with a little scripting (see chapter 17). Open the script console
F12
and
enter the following call:
core.output(core.getPropertyList());
Run the script and inspect the output tab. It may take a little guesswork to select the right names, but the
general structure of property names like
<Module>.<Property>
should help you to find your way around.
13.7.1 Developer notes
Usually the synchronisation fails if you attempt to use different versions of Stellarium. You can override this
behaviour with an entry in the respective section of config.ini:
[ Re m o teSync ]
allowVe r s i o n M isma t c h = true
13.7.2 Finetuning
This plugin makes use of the QLoggingCategory infrastructure. By default it is very verbose and prints each
transmitted property to the logfile. To reduce verbosity when it works, configure an environment variable
with these entries (Note the closing semicolon!):
QT_LOGGING_RU L E S = " stel . plugin . remo t e S y n c . debu g = true ;
stel . plugi n . re m o t eSync . client . debug = fal se ;
stel . plugi n . re m o t eSync . protocol . debug = false ;"
The final parts may be debug|info|warning|critical = true|false. Default: true.
Author and Acknowledgements
This plugin was created mostly by Florian Schaukowitsch in the 2015-16 campaigns of the ESA Summer of
Code in Space
6
programme.
6
https://socis.esa.int/
13.8 OnlineQueries Plugin 151
13.8 OnlineQueries Plugin
Stellarium includes and provides lots of information about many kinds of objects. However, there are
scientific websites which provide even more specialized information about particular objects. This plugin
(Zotti, S. M. Hoffmann, et al., 2023) allows online access to several websites on a variety of special topics.
To retrieve information, select the first tab and press the respective button labeled with the information source.
The result is displayed in a browser view
7
.
Wikipedia
The free online encyclopedia provides information about many bright stars, the planets, moons
and many asteroids, as well as many deep-sky objects. The lookup is based on the English proper
name.
AAVSO
The International Variable Star Index
8
of the American Association of Variable Star Observers
(AAVSO) provides data about variable stars.
GCVS
The General Catalogue of Variable Stars
9
of the Sternberg Astronomical Institute and the Institute
of Astronomy of the Russian Academy of Sciences in Moscow.
ASE
The All Skies Encyclopaedia
10
of the IAU Working Group on Star Names (WGSN) which collates and
collects the data on cultural names of stars and constellations in order to preserve their heritage and
distribute the knowledge about them beyond their culture of origin.
In addition, you can configure up to three further websites. These must provide some public website
which takes a query for a Hipparcos star number or object name.
Regardless of the current program language, the result is always presented in English or the language of
the respective website.
13.8.1 Section
[
OnlineQueries
]
in config.ini file
You can edit the
config.ini
file to change settings of the OnlineQueries plugin. The only strings you
should need to touch are the
customN_...
entries (
N ∈ {1, 2, 3}
). The placeholder
%1
will be filled by either
the Hipparcos number (if the respective
customN_use_hip
is
true
) or by the first English name used in
Stellarium. The
customN_use_hip
should be
true
to use a star’s Hipparcos number, or
false
to use the
English name as key.
ID Type Default
aavso_hip_url string (don’t override)
aavso_oid_url
string (don’t override)
ase_url
string (don’t override)
gcvs_url
string (don’t override)
wikipedia_url
string (don’t override)
custom1_url string
custom2_url string
custom3_url string
custom1_use_hip boolean true
custom2_use_hip
boolean true
custom3_use_hip
boolean true
disable_webview boolean false
7
For technical reasons, on some platforms the result is displayed in the system’s default web browser. On some
other platforms, e.g. Windows/WSL with Ubuntu or some ARM computers, the web view fails to work properly. On
these platforms you should manually edit config.ini and set the disable_webview entry in the config file.
8
https://www.aavso.org/vsx/
9
http://www.sai.msu.su/gcvs/
10
https://ase.exopla.net/index.php/All_Skies_Encyclopaedia
152 Chapter 13. Interface Extensions
13.9 Sky Culture Maker Plugin
LUCA-PHILIPP GRUMBACH, SUSANNE M. HOFFMANN
13.9.1 Introduction
To ease the creation of sky cultures (Chapter 9) and avoid mistakes caused by the shortcomings of manual
coding, Stellarium in 2025 started developing a “Sky Culture Maker” (SCM) plugin. It provides the technical
means of visually creating a new sky culture, allowing the user to interact with the usual Stellarium star
map while drawing constellation stick figures and attaching artwork in a wizard-like editor. The SCM
also prompts the user to supply copyright and category information, geographical schema, and all other
requirements for a well-defined sky culture.
With the many new sky culture features released in 2025 (a new data format, display options for historical
frames of reference, and audio output of sky culture information) the requirements on both the data files and
the accompanying description have grown a lot. The SCM is intended to handle these details for the user and
provide an intuitive UI.
However, beware that the plugin is still in development. It was originally set up as a student project
in a software development course, but tests with students from the humanities and researchers in cultural
astronomy showed that it is already useful for users who are comfortable editing source code. Future versions
will continue to improve the SCM.
13.9.2 Getting Started
Figure 13.8: SCM plugin: start dialog
The SCM plugin is disabled by default. In order to use it, you will need to activate it first according to
section 12.1. Once activated, a toolbar button will appear. This button is also an indicator of whether
the SCM is currently open: pressing it toggles the icon to a glowing version and opens the start dialog shown
in Figure 13.8.
The Create button opens the main dialog where you can build a new sky culture. If the Sky Culture
Converter was enabled at build time, a Convert button also appears (see section 13.9.3 for details). The Edit
button may be present already, but it is disabled because the SCM currently does not support editing existing
sky cultures. This feature is planned for a future release.
Saving partial results: Since editing an existing sky culture is not yet supported, the following workaround
is needed to save partial work and resume later. Ensure all metadata is complete so the SCM allows you to
export. When resuming, create a new temporary sky culture, continue your work there, and then manually
merge the two exported JSON files by copying the relevant entries.
13.9.3 Converting an Existing Sky Culture
The SCM includes a UI for the Sky Culture Converter (section 9.4) that transforms legacy sky cultures using
the old .fab format into the new JSON-based format (Chapter 9).
Build-time requirement
The converter is not built by default. To enable it, pass
-DSCM_SHOULD_ENABLE_CONVERTER=ON
to CMake
when configuring the build. The converter requires Qt 6 or later and it is automatically disabled for Qt 5
builds and Windows ARM64 targets. It also depends on Tidy HTML, GNU gettext, and zlib. CMake will
download the converter library automatically via CPM.
Using the converter
When the converter has been built, a Convert button appears in the SCM start dialog alongside the Create
button (Figure 13.9).
1. Press Convert in the start dialog.
13.9 Sky Culture Maker Plugin 153
(a) Start dialog with Convert button (b) Converter file chooser
Figure 13.9: SCM plugin: converter workflow dialogs
2.
A file chooser opens (Figure 13.9, panel b). Select an archive that contains the old sky culture files.
Supported formats:
.zip
,
.rar
,
.tar
,
.7z
. Selecting a plain directory is not supported by the
converter. Note that only plain
.tar
archives are supported. Compressed variants such as
.tar.gz
or .tar.bz2 are not.
3.
The converter processes the archive and writes the resulting files directly into Stellarium’s
skycultures
directory. If the application does not have write permission there, a dialog prompts you to choose an
alternative output folder.
Note: Sky culture identifiers are case-sensitive. For example,
chinese_chenzhuo
and
chinese_Chenzhuo
are treated as different cultures.
13.9.4 Creating a New Sky Culture
After pressing Create in the start dialog, you will be greeted by the Overview tab of the main dialog
(Figure 13.10, panel a). This dialog is different from most dialogs in Stellarium, as it is an independent
window that can be moved outside the Stellarium application, including onto a second monitor for more
workspace. To resize it on Windows, you must drag the tiny square handle in the bottom-right corner.
Note: Because the dialog is an independent window, it may open behind the Stellarium main window and
therefore not be immediately visible. If nothing seems to have happened after pressing Create, the dialog
has most likely opened in the background or on another monitor. Try clicking once on the Stellarium main
window to bring the SCM dialog to the front. If that does not work, try minimizing the Stellarium main
window. The same behaviour applies to the Constellation Editor described in section 13.9.5. In the first text
input, you may enter a name for your new sky culture. This field is mandatory. Below the name field is the
constellation list, which is empty until you create constellations (see section 13.9.5). Before doing that, it is
worth browsing the remaining tabs.
Description tab
The Description tab (Figure 13.10 b) collects textual information about the sky culture. It contains dropdown
menus as well as mandatory (marked with an asterisk) and optional text fields. Scroll through all fields and
supply as much information as possible. Your inputs are used to generate the sky culture description file
(
description.md
), which Stellarium will use to display certain information to users. For details on the
expected content and structure of this file, see section 9.1.
Common Names tab
The Common Names tab (Figure 13.10 c) manages culture-specific names for stars, planets, and deep-sky
objects.
The table at the top lists the common name entries you have already created. The input fields below are
used to enter new names. In order to automatically fill in the type, identifier, and English name, select an
object in Stellarium and press Copy Data From Selected Object. The mandatory fields are marked with an
asterisk, just like in the Description tab.
Note that in some cultures, planets carry different names depending on the time of day. The Visible
dropdown lets you choose whether a name is always visible, or only during morning or evening. For
non-planetary objects the value is fixed at Always visible.
For the full specification of common names for stars, planets and deep-sky objects, see sections 9.2.7,
9.2.7.3, and 9.2.8.
Workflow for managing entries:
•
Add: Fill in the fields and press Save As New Entry. The fields are cleared afterwards.
•
Edit: Select a row in the table; the fields are populated with the current values. Make your changes
and press Update Selected Entry.
154 Chapter 13. Interface Extensions
(a) Overview tab (b) Description tab
(c) Common Names tab (d) Location tab
Figure 13.10: SCM plugin: main dialog tabs for creating a sky culture
(a) Drawing tab (b) Information tab (c) Artwork tab
Figure 13.11: SCM plugin: Constellation Editor tabs and drawing workflow
13.9 Sky Culture Maker Plugin 155
•
Remove: Select a row and press Remove Selected Entry. This action is irreversible!
Location tab
The Location tab (Figure 13.10, panel d) specifies where and when the sky culture was or is practiced.
The upper part of the tab shows a world map, which allows you to digitize the geographic territory of
the culture by drawing polygons. Simply click on the map to register corners and extend the polygon.
•
At least one polygon is required before exporting the sky culture. You can later edit or refine the
GeoJSON format in your GIS applications.
•
Hold
and drag with the left mouse button to move the map while drawing.
•
Press
Ctrl
+
Z
to undo the last click.
•
Press
Esc
to discard the entire current polygon.
•
Double-right-click to finish the polygon. A dialog then asks for the start and end year during which
the culture was or is practiced. The special value 9146 indicates that the culture is still practiced.
•
A short help summary for all map interactions is available by clicking the ? button in the bottom-right
corner of the map.
Instruction for creating geo-polygons: The polygons are meant to indicate the origin of the astronomical
culture that is represented in Stellarium. We regard this information as educational in terms of understanding
the reasons for the selection of specific images, because the specific fauna and flora, and the geological
features of the area influence cultural habits (astronomy is used for forecasting seasonal weather, encounters
with migrating birds, fish, and other animals that might be depicted in the constellations). For that reason,
the polygons of historical indigenous settlements or the extent of empires are more important than modern
borders of states or enclosures. For instance, in a modern state (like the USA) there might be reserves for
indigenous nations (e.g. the Navajo), but for our purpose these legal boundaries are less important than the
original area where their sky cultures had been developed in pre-Columbian America.
Note the Time Slider! You have the option to simulate the movement of a culture over time. For instance,
the Indian Vedic culture developed in the Indus Valley first, then spread to the Ganges Plateau and then to
the entire Indian subcontinent (and with Hinduism even beyond). So, we defined three time steps for the
Indian Vedic culture with different geographical extents. This may help in understanding both where any
specific culture is practiced today and where it stems from.
Note that the time slider does not affect the display in the Stellarium main simulation, i.e. the display of the
sky. It is only meant to illustrate the evolution of cultures.
The polygon data is then saved to a
territory.geojson
file. For details on its format see section 9.3.
For information on geoscheme regions, see section 9.2.1.
13.9.5 Creating a New Constellation
Head back to the Overview tab and press Add Constellation to open the Constellation Editor (Figure 13.11,
panel a). This editor consists of three tabs.
Drawing tab
The Drawing tab lets you draw constellation lines directly on the Stellarium sky map (see also section 9.2.4
for the underlying data format).
1. Press the Pen button to activate drawing mode.
2. Hover over a star and a snapping indicator will show you which star is currently targeted.
3. Right-click on the star to set it as the start of a line segment.
4.
Move the mouse to the next star; right-click again to complete the segment and immediately begin the
next one from that point.
5. To stop drawing, double-right-click or simply press the Pen button again.
Using this workflow you can build complex stick figures (see Figure 13.12 a). Mistakes can be undone with
the Undo button (one segment at a time) or erased with the Eraser tool: press Eraser, then hold the right
mouse button and drag through any line segment to remove it.
Information tab
The Information tab (Figure 13.11 b) records metadata about the constellation. The English name and the
unique identifier are mandatory; all other fields are optional but recommended. A possible identifier is
generated automatically from the English name, but you may change it manually as well.
Artwork tab
The Artwork tab (Figure 13.11 c) lets you attach an illustration to the constellation. For background on
artwork and its role in sky cultures, see section 9.2.4.1.
156 Chapter 13. Interface Extensions
Press Upload Image and select an image file. Three blue anchor points appear on the image. To align
the artwork with the sky:
1. Select an anchor point in the tab.
2. Select a star in Stellarium (for example, one that appears in the constellation).
3. Press Bind Star to associate that star with the anchor point.
4. Drag the anchor point to the position in the image that the star represents.
5. Repeat for the remaining anchor points.
An example result is shown in Figure 13.12. If the image is not visible on the sky map, try repositioning the
anchor points. The SCM does not draw images that become too distorted.
(a) (b)
Figure 13.12: Example constellation drawing (a) in progress and (b) with artwork aligned
Dark constellations
The Overview tab also offers Add Dark Constellation. The dark constellation editor works just like the
regular editor, except that lines are not snapped to stars. You may click anywhere in the sky to place a vertex
using its sky coordinates directly. See section 9.2.4 for details on dark constellations.
Managing constellations
When you save a constellation, it is added to the list in the Overview tab (Figure 13.13). Select a constellation
in the list to Edit or Remove it.
Figure 13.13: SCM plugin: Overview tab with two example constellations
13.9.6 Exporting the Sky Culture
When the sky culture is ready, select a license from the dropdown menu in the Overview tab. For guidance
on which license to choose, see section 9.1.3. Then press Export Sky Culture. If any mandatory fields are
incomplete, an error message identifies what is missing. Otherwise the Export Dialog (Figure 13.14) opens.
Read through the checklist items and confirm you have followed them. The checkbox Merge constellation
lines into polylines on export (checked by default) merges consecutive line segments that share an endpoint:
13.9 Sky Culture Maker Plugin 157
Figure 13.14: SCM plugin: Export dialog
for example,
[1,2]
and
[2,3]
become
[1,2,3]
in the JSON output, producing a cleaner file. It is
recommended to leave this option enabled.
Choose Export to export while keeping the SCM open, or Export and Exit to export and close the plugin.
The export creates a folder containing:
•
index.json — see section 9.2
•
description.md — see section 9.1
•
territory.geojson — see section 9.3
•
illustrations/ — sub-folder with any uploaded artwork images
13.9.7 Closing the Plugin
Press the X icon in a dialog’s title bar or Cancel wherever available. This opens the dialog shown in
Figure 13.15, offering three choices:
Figure 13.15: SCM plugin: Close dialog
Hide editor
Hides all SCM windows but preserves all data. Reopening the SCM via the toolbar button
restores the previous state.
Close without saving Shuts down the SCM plugin and discards all unsaved data.
Don’t close Returns to the SCM without any changes.
Section
[
SkyCultureMaker
]
in config.ini
The following settings can be adjusted manually in the
config.ini
file under the
[SkyCultureMaker]
group. Colors are given as comma-separated R,G,B values in the range 0–1.
Key Type Default
fixedLineColor float R,G,B 1.0,0.5,0.5
fixedLineAlpha float 1.0
floatingLineColor
float R,G,B 1.0,0.7,0.7
floatingLineAlpha float 0.5
maxSnapRadiusInPixels
int 25
mergeLinesOnExport
bool true
Key descriptions:
158 Chapter 13. Interface Extensions
fixedLineColor / fixedLineAlpha
Color and opacity of constellation line segments that have been commit-
ted (drawn with right-click).
floatingLineColor / floatingLineAlpha
Color and opacity of the preview line segment following the cursor
while drawing.
maxSnapRadiusInPixels
Maximum distance in screen pixels within which the cursor snaps to the nearest
star or DSO.
mergeLinesOnExport
Whether consecutive line segments sharing an endpoint are merged into polylines
on export (mirrors the checkbox in the export dialog).
13.9.8 Further Development
The plugin is still in active development. In its current state it provides the fundamental features but is not
yet fully functional (beta). If you test the wizard, please report missing features or bugs via the Stellarium
issue tracker.
13.9.9 Acknowledgments
Fabian Hofer, Vincent Gerlach, Luca-Philipp Grumbach, Richard Hofmann, and Mher Mnatsakanyan
developed this plugin in 2025 at the University of Jena, under the supervision of Jan Heinrich Merker and
with Susanne M. Hoffmann as product owner.
If you use this plugin in scientific publications, please cite this User Guide and Zotti, Kabatsayev, et al.
(submitted).
13.10 Solar System Editor Plugin 159
13.10 Solar System Editor Plugin
Stellarium stores its data (orbital elements and other details) about solar system objects (planets, their moons,
minor bodies) in two files. File
data/ssystem_major.ini
in the installation directory contains data for the
planets and their moons, and should never be touched by users. File
data/ssystem_minor.ini
contains
data for minor bodies, i.e., planetoids and comets. The file will be taken from the user data directory if it also
exists there, which means that users can add minor planets or comets as they become observable by editing
this file.
The orbits of minor bodies (minor planets and comets) are specified with orbital elements for Kepler
orbits (after JOHANNES KEPLER (1572–1630) who found the true shape of the orbit of a small body around
a large one being a conic section, i.e., circle, ellipse, parabola or hyperbola). These elements describe the
instantaneous shape and orientation of the object’s orbit around the Sun at a particular time called the epoch.
We compute positions from these osculating elements of minor body orbits, but the result is only valid for a
moderately short timespan around the epoch, because the major planets can exert noticeable gravitational
perturbations on the objects when they come close, and so these orbital elements, which are mere snapshots
in time, need to be updated on a regular basis. Stellarium does not perform numerical integration that could
work out the orbital changes automatically, and so the element file needs to be modified to compute positions
further away from the orbit’s epoch. See Appendix D.2 for more details, and see e.g. Meeus (2007) for a
discussion of a few interesting examples of orbital development. When you go out hunting for asteroids and
comets, this plugin is for you.
This plugin provides access to the Minor Planet Center (MPC
11
) server where the latest Solar System
information can be found. When this plugin is loaded (see section 12.1) and you open the configuration
dialog, the first tab allows to import, export or reset your
ssystem_minor.ini
, and also to load extra
data for minor bodies in Stellarium’s
.ini
format. For example, the installation directory contains a file
ssystem_1000comets.ini
which contains data for over 1000 historical comets. Currently it is not possible
to select only a few from that, so try loading this only on a reasonably fast computer, and think about deleting
comets again (or resetting the file) when you don’t require them.
Figure 13.16: Interface of Solar System Editor plugin: Configuration file tab
The second tab lists all currently loaded minor bodies (see figure 13.17). It is recommended to remove
old entries of yesteryear’s comets if you don’t need them any longer. Just select one or more objects and
press
Remove
. If you have a very weak computer, you may want to reduce the number of minor bodies to
11
https://www.minorplanetcenter.net
160 Chapter 13. Interface Extensions
just a handful to improve performance.
Figure 13.17: Interface of Solar System Editor plugin: Solar System tab
On this tab, you also find the option to connect to the MPC and download current orbital elements, or
load a text file in the format provided by MPC (see figures 13.18 and 13.19).
Once MPC data has been downloaded, the user can select objects for updating the user’s
ssystem_minor.ini
.
13.10 Solar System Editor Plugin 161
Figure 13.18: Interface of Solar System Editor plugin: Import data dialog
Figure 13.19: Interface of Solar System Editor plugin: Import data dialog — view after downloading
and parsing the MPC data.
162 Chapter 13. Interface Extensions
13.11 Nebula Textures Plugin
The Nebula Textures plugin allows users to customize deep-sky object (DSO) textures, precisely rendering
them in Stellarium like default textures. Astronomy amateurs can use it to create a collection of their own
astrophotography, visual-like sketches, paintings, and even more in Stellarium. It also serves as a simple
client for Astrometry.net, enabling blind-solving and precise positioning of astronomical images. The
plugin’s full functionality includes online plate-solving and positioning of astronomical images, as well as
the management and rendering of custom textures.
13.11.1 Online Solving and Texture Management
Instructions for integrating astrophotography images via online plate solving.
1.
Prepare an Image: Prepare a processed rectangular bitmap file of a deep-sky object, in a format
that supports both Astrometry analysis and rendering, such as PNG, JPG, TIF, or GIF. You should
adjust the image background brightness to suit Stellarium by referencing the nebulae images in the
Stellarium
nebulae/default
directory. Typical astrophotography images with TAN projections are
fine, but avoid images with high field distortion. If the image’s FOV is too large, it is recommended
to manually split it into multiple sub-images beforehand. Ensure that the image is not flipped
horizontally or vertically!!! It’s recommended to use a descriptive ID or nickname as the filename.
While Nova Astrometry does not strictly limit image size, keeping it below 20 MP ensures efficient
plate solving.
2.
Open Image: By default, the plugin opens the “Solve and Add” page. Click the
Open File
button to
select an image file or paste the file path into the “Image Filepath” text box.
3.
Enter API Key: Paste your Astrometry API key into the corresponding text box (password mode by
default). If you don’t have one, click
Astrometry API key
to obtain it after registering or logging in.
Check
2 Remember me
to store the key for future use.
4.
Upload and Solve: Click
Online Solve
to begin uploading and solving the image. Ensure system
proxies are disabled to avoid errors. The solving process may take seconds to minutes, depending on
the Astrometry.net server. If you need to stop the solving process, click the
Cancel
button.
5.
View Solving Results: After successful solving, the image’s center and corners’ J2000 equatorial
coordinates (in decimal degrees) will be displayed.
6. Optional Testing:
•
Click
Goto Center
to locate the texture’s center.
•
Use
Test this texture
to preview the texture. If it overlaps with default textures, you should
check
Disable default textures
to avoid visual conflicts. The
Test this texture
button will toggle
between “Test this texture” and “Stop test” to start and stop the rendering process. Remember
to click
Stop Test
afterward to restore the rendering of the default nebula textures!
•
When testing is active, modifying the coordinate spinboxes (including using the mouse wheel)
will immediately update and redraw the texture in real-time, enabling an interactive experience
for fine-tuning alignment.
•
For images solved via Astrometry.net, if manual coordinate adjustments deviate too much,
Reset
will appear. Click it to reset the coordinates back to the original astrometric solution.
•
The dropdown menu is used to adjust texture brightness, with three options: Bright, Normal,
and Dark. The default Normal setting is suitable for most cases.
•
You can repeatedly press the
s
key in the main view to toggle star visibility and verify whether
the image is aligned accurately.
7.
Add Texture to Storage: Click
Add the Texture to Custom Storage
to permanently save the texture.
The original image will be copied to Stellarium’s plugin folder in the user directory. After adding a
texture, you should restart Stellarium to fully integrate the texture into the module.
8.
Display Settings: After restarting Stellarium, switch to the
Custom Textures
page of the plugin to
manage your custom textures. Options include
Show Custom Textures
(showing/hiding textures),
Avoid Area Conflict
(avoiding overlaps with default textures), and
Reload
(reloading custom tex-
tures).
9. Locate a Texture: Double-clicking a texture item in the list will center the view on that texture.
10.
Remove a Texture: To remove a texture, switch to the
Custom Textures
page, select it in the list
view and click
Remove selected item in Custom Textures
. The configuration file will update, and the
corresponding image file in the plugin folder will be deleted. However, Stellarium may continue
rendering the texture until it is restarted.
13.11 Nebula Textures Plugin 163
13.11.2 Manual Texture Addition)
Instructions for adding manual textures (e.g., sketches, paintings). The process is similar to the one above,
but performing online solving is not required:
•
Open the image file. Stars in non-astrophotographic images may not align precisely with the software’s
stars, so it is recommended to use the texture without stars (de-star it).
•
Input the J2000 equatorial coordinates (in decimal degrees) for the image corners, aligning with the
bitmap display.
•
If needed, use an astrophotography image with a similar field of view (FOV) to obtain approximate
corner coordinates via online solving first. Alternatively, enable Digitized Sky Survey layers in
Stellarium (Disable constellation lines, illustrations, grids, and other unrelated elements to approximate
a realistic effect), adjust the field of view and rotation to match the texture, and capture a screenshot
for solving. After obtaining the solved coordinates, replace the image path with the texture path.
•
Then, debug and render the texture, adjusting coordinates until the texture stars align accurately with
Stellarium stars. Finally, add the texture to the custom storage.
13.11.3 Notes
1.
All uploaded images are automatically assigned a CC BY-NC-ND 3.0 license by Astrometry.net and
are not publicly visible by default. Avoid excessive uploads to prevent server congestion or issues
with your API key.
2.
After adding a texture, you must restart Stellarium to fully integrate the texture into the module. The
same applies when deleting a texture.
3.
To back up your texture library or share it with others, copy the plugin folder from your user config
directory. You can find the exact plugin storage path in the “About” section of the plugin GUI. For
Windows systems, this path is usually something like:
%APPDATA%\Stellarium\modules\NebulaTextures
You can then share this folder with others, and they can place it in the same directory on their system
to use the custom textures.
164 Chapter 13. Interface Extensions
13.12 Calendars Plugin
GEORG ZOTTI
13.12.1 Introduction
The calendar dates in the main program behave like most other astronomical software titles:
•
Dates are given in the Gregorian calendar for all dates beginning with October 15, 1582.
•
All earlier dates are given in the Julian Calendar in its finalized form by AUGUSTUS. Historically,
only dates beginning with March 1st, 4 A.D. coincide with historically recorded dates: the Roman
priesthood messed up the 4-year count introduced by JULIUS CAESAR and counted leap years every
third year. AUGUSTUS decreed to omit leap days from 12 B.C. to 4 A.D. to move the seasons to
where JULIUS CAESAR had placed them.
•
Given the errors in the Julian calendar, simulation in early prehistory will provide non-intuitive
calendar dates for the seasons’ beginnings.
•
Astronomical counting of years includes a year zero and negative years. Historical calendars don’t
have a year zero. 1 A.D. is preceded by 1 B.C. Therefore a negative year in Stellarium may look
uncommon to historians who may think Stellarium is one year off.
Since earliest times people all over the world have observed the sky and used its phenomena to structure
their lives, agree on future events (“we shall meet here again and exchange goods at the third Full Moon
from now”), record and measure time. Over millennia, various systematic calendars evolved. A classic
and often-cited presentation of calendars from the pre-computer era is still the monumental work by Ginzel
(1906; 1908; 1911). The next challenge was then to describe the systematic of these algorithmically and
make them available for computer programs. Reingold and Dershowitz (2018) have presented a modern
masterpiece of this kind and are our preferred source of algorithms. This plugin will evolve over the next
time to bring a good sample of calendars into Stellarium.
In the configuration panel you can select which calendars you want to display in the lower right corner
of the screen, and you can also directly interact with some of them.
The calendars displayed in this plugin come with their own logic. Historically, when a calendar was
introduced, dates which precede its starting point (era) were of little interest to its users, therefore if a date
bears negative years (or negative units of its largest component) those dates may not be useful.
Note that in some calendars the day did not begin at midnight, but for example at sunrise, sunset, or
dawn. This cannot be reflected in this plugin. Dates should be correct at noon, and may be one day off
dependent on these aspects.
12
13.12.2 The Calendars
13.12.2.1 Lunisolar European calendars
Julian
JULIUS CAESAR introduced this calendar, advised by the Egyptian astronomer SOSIGENES. Every
4th year is a leap year of 366 instead of 365 days, yielding a mean length of the year of 365.25 days.
In contrast to the default calendar display of Stellarium, this implementation utilizes historical year
counting, i.e., has no year zero. Years are marked A.D. or B.C., respectively. The omission of year
zero makes negative leap years break the simple 4-year count. Now they are 1 B.C., 5 B.C., 9 B.C.
etc. However, note that before 8 A.D. leap years are just counted proleptic, but the Romans did not
keep the leap years commanded by JULIUS CAESAR until AUGUSTUS put things back in order. This
means, displayed dates before 8 A.D. may be off by up to 3 days from historical accounts written by
contemporaries.
Gregorian
This implementation acts like Stellarium with respect to year counting and counts signed
negative and positive years, with a year zero between them. It shows dates in a Proleptic Gregorian
calendar for dates before October 15, 1582. Given its improved rules for leap years which provide a
mean length of the year of 365.2425 days, it keeps the seasons’ beginnings closer to the commonly
known dates, at least for many more centuries in the past than the Julian calendar commonly used by
historians.
Revised Julian Calendar
(also named Milankovi
´
c Calendar) In 1923, the Serbian scientist MILUTIN
MILANKOVI
´
C (1879–1958) proposed a calendar which should overcome the then 13-day calendar
12
At the current point of implementation I cannot exclude further errors! The plugin reproduces the given sample
dates, but we cannot give any guarantee about the accuracy of historical dates. If you are more familiar with any of the
non-European calendars, you are invited to identify errors or at least additions to this documentation, e.g. variants to the
schemes used.
13.12 Calendars Plugin 165
gap between the Eastern European Orthodox churches who still adhered to the Julian calendar and the
rest of the world which followed the Gregorian calendar. It amends the 4-year Julian leap year cycle
by omitting century years except for those where division by 900 leaves a remainder of 200 or 600.
Therefore the mean length of the year is 365.242
¯
2 days, 24 seconds less than the Gregorian and within
2 seconds of the correct length of the mean tropical year. For a synchronisation with the Gregorian,
October 1-13 1923 were omitted. Between March 1600 and February 2800 the calendar dates are
identical to those in the Gregorian calendar. The calendar was adopted by several but not all Eastern
Orthodox churches, although date of Easter is still computed according to the Julian calendar
13
.
In historical context giving dates in the Revised Julian calendar for years before the dates of religious
festivals were defined in the calendar makes no sense. Its idea was to have a continuous calendar as it
was in use at the concile of Nicaea in A.D.325. Therefore dates before A.D.325 are displayed like in
the traditional Julian calendar.
ISO Week
The International Standards Organization describes weeks in the Gregorian calendar from
Monday (Day 1) to Sunday (Day 7). Week 1 of each year contains the first Thursday of the year.
Years may have a week 53, where the last days already belong to the next Gregorian year.
Icelandic calendar
Since 1700, this counts weeks in summer and winter seasons, 12 months of 30 days
with a few extra days and the occasional leap week after the third month of summer. Year numbers
concur with the Gregorian, but start with summer in late April.
Roman calendar
This presents the Roman way of writing calendar dates in the Julian calendar and provides
dates ab urbe condita (A.U.C.).
Byzantine Calendar
has month names and days identical to the Julian. However, years are counted as
v 26.2
annus mundi (AM), starting from Creation of the World on September 1, 5509 B.C. (Julian). A
question about Year Zero or negative years is pointless. This calendar was used in Russia before
introducing the Julian calendar in 1700. Before that, from around 7th century to 1492 (unrelated to
Columbus), start of the year was observed on March 1.
Olympic calendar
Another way to write the years in the Julian calendar uses the Greek Olympiads, a
4-year cycle starting in 776 B.C.E. The Olympic games of antiquity were held in year 1 of each cycle.
13.12.2.2 Near Eastern Solar calendars
Several calendars with 12 months of 30 days plus 5 (6 for leap years in some calendars) epagomenae days,
with different calendar eras.
Egyptian
A 365 day year without leap days. Following the tradition of PTOLEMY, we use the era of
Nabonassar.
Armenian also has no leap days.
Zoroastrian
also has no leap days. This uses different names for each day of the month and for each
epagomenae day. Month names are from Ginzel (1906, §69) with transliteration adapted to Reingold
and Dershowitz (2018).
Coptic
uses Month names derived from the Egyptian calendar, but observes leap years every 4th year. Its
era martyrum is also called Diocletian era.
Ethiopic
like the Coptic calendar, just with different year numbers, counted from the ethiopic era of mercy.
Persian
a Solar calendar adopted in 1925, but based on the earlier Jal
¯
al
¯
ı calendar of the 11th century A.D.
Years begin at the Vernal equinox (nowruz) and follow a complicated leap year cycle of 2820 years.
Days begin at midnight (zone time). An identical calendar with different month names was adopted
in Afghanistan in 1957.
Stellarium provides both versions: the algorithmic version and the astronomically specified one. They
occasionally deviate from each other by 1 day.
Bahá’í
is a Solar calendar with years beginning on the day of Vernal equinox. In the algorithmic version
v 1.2
used in the West, March 21 in the Gregorian calendar was used, but the astronomical version used
since 2015 uses Tehran as reference location. Days begin at sunset. The calendar uses a 7-day
week but is else based on cycles of the number 19: 19 named months of 19 named days plus 4-5
additional days after month 18. In addition, years are structured in named 19-years (V
¯
a
h
.
id, “unity”)
and numbered 19
2
= 361-years (Kull-i-shay) cycles.
13.12.2.3 Near Eastern calendar s
Several more calendars have been worked out in algorithmic forms:
Islamic
is a strict Lunar calendar without observance of seasons. Days begin at sunset, but we cannot
currently show this. The date should be correct at Noon. The week begins on Sunday. Note that this
13
More details can be found on https://en.wikipedia.org/wiki/Revised_Julian_calendar
166 Chapter 13. Interface Extensions
algorithmic solution may deviate from the dates given by religious authorities on basis of observation.
Hebrew
is a Lunisolar calendar with strict Lunar months, but adherence to the seasons. It has 12 or 13
months, and 353-355 or 383-385 days per year. The algorithmic form was introduced in the mid-4th
century A.D.
13.12.2.4 Asian calendars
Old Hindu Solar
used before about 1100 A.D. The implementation follows the (First)
¯
Arya Siddh
¯
anta of
¯
Aryabha
t
.
a (499 C.E.), as amended by Lalla (circa 720–790 C.E.). The year is split into 12 months
(saura) of equal length. Days begin with sunrise, simplified as 6 am. Years are counted as elapsed
years (starting at 0) from the Kali Yuga (Iron Age) epoch (Feb. 18., 3102 B.C. jul.).
Old Hindu Lunisolar
used before about 1100 A.D. This implementation shows the south-Indian method
with months starting at New Moon (am
¯
anta scheme). (In the north, the p
¯
ur
n
.
im
¯
anta scheme describes
months starting with Full Moon. There are also some local differences.) It also shows the K.Y. day
count (ahargan
.
a), i.e., days elapsed since the K.Y. epoch.
New Hindu Solar and Lunisolar
This is the Hindu calendar from the S
¯
urya-Siddh
¯
anta (ca. 1000 A.D.). It
is based on epicyclical motions of the Sun and Moon around the Earth. While still an approximation,
this provides more accurate models of the motions at cost of much more complicated computation.
The Solar month begins when the Sun enters a sign on the Sidereal Zodiac. Months are therefore 29
to 32 days long. Solar days begin at sunrise, and the zodiacal position of the sun at sunrise in Ujjain,
India, decides on the date. Years given for the Solar calendar are counted from the Saka era (A.D. 78).
The lunar month name is determined by the (first) zodiacal sign entered by the sun during the month.
When no sign is entered, the month is “leap” (adhika) and named after the following month. When a
Solar month passes without a New Moon, a lunar month can also be skipped (kshaya). The Lunisolar
year has 12 or 13 months, of which up to 2 can be leap and one skipped!
A lunar day varies in length from 21.5 to 26.2 hours, and therefore may occasionally have to be
repeated (here the second day is the leap day or adhika), or skipped.
Years are given in the Vikrama era which began in 58 B.C. Both months schemes share the same 12
names.
Also this calendar is shown in the am
¯
anta scheme, i.e., months start at New Moon. There are again
several local variants, and of course a longitude difference to the reference location may also lead to
deviations.
In addition to the New Hindu Lunisolar date, the Hindu panchang is shown, a 5-part description of
the day consisting of
Tithi (lunar day)
Weekday
Naks
.
atra the part of the ecliptic the Moon is in at time of sunrise (in Ujjain).
Yoga a cycle of 27 names resulting from the “addition” of Solar and Lunar longitudes.
14
Karan
.
a
a count of 60 lunar half-days resulting in 11 names. The kara
n
.
a at time of sunrise (in Ujjain)
governs the karan
.
a for the day
15
.
Hindu Astronomical Solar and Lunisolar
These are similar to the New Hindu calendars, but with even
more accurate positional computations from the S
¯
urya-Siddh
¯
anta for Solar and Lunar positions.
Tibetan calendar
is actually only one of several calendars used in Tibet. We show the date in the official
Phuglugs (or Phug-pa, Phukluk) version of the K
¯
alacakra calendar, derived from the K
¯
alacakra
Tantra which was translated from Sanskrit to Tibetan in the 11th century, and has been sanctioned by
the Dalai Lama. It is similar to the Hindu Lunisolar calendar, but has also regional variants where
astronomical events are computed in local time. In Tibet, the actual calendar is issued only annually
(after empirical corrections) by the Tibetan School for Astro and Medicine and may diverge from the
calendar shown here.
Months are 29 or 30 days long and numbered 1 to 12. Leap months precede their “regular” counterparts
but else have the same name.
Years are counted from the date of ascension of the first Yarlung king, NYATRI TSENPO, in 128 B.C.
(We write “A.T.” for Anno Tibetorum.) However, it is more common to designate years in a cycle of
60 years, with 5 elements which label two consecutive years which are further named “male” and
“female”, and a parallel cycle of 12 animal totems. This cycle has been synchronized with the similar
14
For technical reasons this is currently shown for midnight UTC. It is currently unclear if yoga should be given for
the time of sunrise or for the current moment.
15
Again, this is unconfirmed. If you know better, please tell us!
13.12 Calendars Plugin 167
Chinese 60-years cycle.
Balinese Pawukon
is a 10-part sequence of day names with cycle lengths of 2 to 10, which can also be
written as numbers or symbols. Some numbers repeat in simple cycles, while others follow more
complicated rules. A full cycle takes 210 days. Due to space reasons this needs two lines on the
display. Formatting may improve in later versions.
13.12.2.5 Chinese calendars
v 1.2
The Chinese calendar (and related Japanese, Korean and Vietnamese) is a Lunisolar calendar based on
astronomical events. Days begin at midnight. Lunar months begin on the day of New Moon. The position of
the Sun along the Zodiac is given by Major (zh
¯
ongqì) and Minor (jiéqì) Solar Terms.
Chinese
The version here is the 1645 version. Earlier dates may be wrong. The calendar’s location for
astronomical computations is Beijing.
Japanese
The same principles of the Chinese calendar have been followed since 1844, but with Tokyo as
reference location. The years given are in the kigen count (years from 660 BCE).
Korean
Korea adopted the Gregorian calendar in 1896, but the older Chinese-based calendar is still used
for traditional purposes. The reference location for computing Solar longitudes and lunar phases is
Seoul City Hall. Years are counted in the Danki system starting in 2333 BCE.
Vietnamese
From 1813-1967 the Chinese calendar was used directly. The currently used traditional calendar
parallels the Chinese, but with Saigon as reference location. Years are not counted, only named. It
also seems that Solar terms are not used.
13.12.2.6 Mesoamerican calendars
Maya Long Count
is a 5-part sequence of numbers, conventionally written with dot separators. Just like
most modern people write numbers in the decimal system (base 10), and the Mesopotamians developed
a scheme with base 60 still used today for angular and temporal minutes and seconds, the Maya used
base 20 as their unit. However, this count uses a mixed-base system. The lowest (rightmost) number
(kin) runs from 0 to 19, the second-lowest (uinal) from 0 to 17, the others from 0 to 19 again. It is
assumed these lowest places of
18× 20 = 360
days have been used to approximate the solar year, so
that the third number from the right (tun) increases about once per year. The higher places are called
katun and baktun. Most scientists agree that the zero point of the long count corresponds to Monday,
September 6, 3114 B.C. (Julian), but in many sources dates in the proleptic Gregorian calendar are
listed, where this date is given as August 11, -3113. This plugin finally allows the use of both systems,
and of Long Count dates directly.
In December of 2012 some people were afraid that the switchover from baktun 12 to 13 (something
which occurs about every 400 years) would cause Armageddon, just as other people prefer to be afraid
of turns of centuries or millennia of the Christian year count.
Maya Haab
is a calendar of 18 “months” of 20 days each (counted 1 to 20), plus 5 days (Uayeb) at the
end, providing “years” of 365 days. Years are not counted, but you can use buttons in the calendar
interface to move forth and back to the previous or next, respectively, day with the same Haab name.
Maya Tzolkin
is described as ritual calendar consisting of two cycles with 13 day numbers (1 to 13) and
20 names. Each day both counters are advanced. Date names repeat after 260 days. Usually Haab and
Tzolkin calendars were both used to define a unique date which repeats only after a calendar round of
52 Haab years, corresponding to 73 Tzolkin cycles.
Aztec Xihuitl
is similar to the Maya Haab, consisting of 18 “months” of 20 days, plus 5 nemontemi
(worthless days). Days are counted from 1 to 20. The Aztecs may have used intercalation, but details
have been lost. The correlation in use here is based on the recorded Aztec date of the fall of their
empire to HERNÁN CORTÉS in 1521 and should provide correct dates in the early 16th century.
Aztec Tonalpohualli
is similar in structure to the Mayan Tzolkin. Also an Aztec date is usually given by
both systems.
13.12.2.7 French Revolution calendar
The French Revolution of 1789 brought also a calendar reform. After a few years with different year count
only, a new calendar was introduced effective on November 24, 1793 (4. Frimaire, II). This was based on an
astronomical determination of the autumnal equinox at Paris, which marked the start of the years.
The calendar has 12 months of
3× 10
days (décades), plus 5 (in leap years: 6) extra days at the end of
the year. These 10-day “weeks” made it pretty unpopular. The months were given names that alluded to the
climate or vegetation.
In 1795, an arithmetic version was proposed which got rid of the difficult astronomical computation
with a leap year scheme similar to the Gregorian. However, this version of the calendar never came into use.
Stellarium also shows this calendar, which may be off from the original by 1 day.
168 Chapter 13. Interface Extensions
With the end of Gregorian year 1805, the calendar was abolished, but re-introduced for a few days in
May 1871.
13.12.3 Scripting
Advanced users who have the book at hand may find it useful that almost all functions from Reingold
and Dershowitz (2018) are available as scripting functions (as far as the implementation of the described
calendars has come). Whenever a location is needed, the current location is used, or you can use a location
from the location database by giving its name like “Vienna, Austria” or “Madrid, Western Europe”. This
should also work for user-specified locations. Take care to use a “real” name for the timezone, or specify an
UTC based zone exactly like “UTC+03:15”, else timezone will be read as zero. Full documentation for this
can be found at https://stellarium.org/doc/head/group__calendars.html.
13.12.4 Configuration Options
The configuration dialog allows the selection of the calendars which are of interest to you, and also provides
direct interaction with the calendars. The Mayan and Aztec calendars allow moving to the previous or next
date of that respective name.
Section
[
Calendars
]
in config.ini file
Apart from changing settings using the plugin configuration dialog, you can also edit the
config.ini
file to
change settings for the Calendars plugin – just make it carefully!
ID Type Default ID Type Default
show bool true
flag_text_color_override bool false text_color R,G,B 0.5,0.5,0.7
show_julian bool true show_gregorian bool true
show_revised_julian bool false show_iso bool true
show_icelandic bool false
show_roman bool false show_olympic bool false
show_egyptian bool false
show_armenian bool false show_zoroastrian bool false
show_coptic bool false show_ethiopic bool false
show_persian_astronomical bool false show_persian_arithmetic bool false
show_bahai_astronomical bool false show_bahai_arithmetic bool false
show_islamic bool true show_hebrew bool true
show_old_hindu_solar bool false show_old_hindu_lunar bool false
show_new_hindu_solar bool true show_new_hindu_lunar bool true
show_astro_hindu_solar bool false show_astro_hindu_lunar bool false
show_tibetan
bool false show_balinese_pawukon bool false
show_chinese bool false show_japanese bool false
show_korean bool false show_vietnamese bool false
show_maya_long_count bool true
show_maya_haab bool false show_maya_tzolkin bool false
show_aztec_tonalpohualli bool false show_aztec_xihuitl bool false
show_french_astronomical bool false show_french_arithmetic bool false
13.12.5 Further development
The plugin is still in development. More calendars will be added in later versions, and formatting and setting
options may be improved. Members of non-European cultures who are actually using the output and can
judge its correctness are invited to report errors or suggest better formatting for their respective calendars.
For example, our source book (Reingold and Dershowitz, 2018) describes one solution for the “New
Hindu” calendars, but notes several variants, which are in fact also location dependent. We cannot show
every variant here, but hope to have the version described in the book correct. If you know what you are
doing: we are accepting improvements and extensions in form of working code plus documentation where
this variant is used. Not just a few example dates, but an algorithmic solution.
13.12 Calendars Plugin 169
13.12.6 Acknowledgments
If you are using this plugin in scientific publications, please cite Zotti, S. Hoffmann, et al. (2021).
14. Object Catalog Plugins
Several plugins provide users with some more object classes.
14.1 Bright Novae Plugin
Figure 14.1: Nova Cygni 1975 (also known as V1500 Cyg)
The Bright Novae plugin provides visualization of some bright novae in the Milky Way galaxy. If enabled
(see section 12.1), bright novae from the past will be presented in the sky at the correct times. For example,
set date and time to 30 August 1975, look at the constellation Cygnus to see Nova Cygni 1975
1
(Fig. 14.1).
14.1.1 Section
[
Novae
]
in config.ini file
You can edit
config.ini
file by yourself for changes of the settings for the Bright Novae plugin – just make
it carefully!
ID Type Description
last_update string Date and time of last update
update_frequency_days
int Frequency of updates, in days
updates_enable
bool Enable updates of bright novae catalog from Internet
url
string URL of bright novae catalog
14.1.2 Format of bright novae catalog
To add a new nova, open a new line after line 5 and paste the following, note commas and brackets, they are
important:
1
https://en.wikipedia.org/wiki/V1500_Cygni
172 Chapter 14. Object Catalog Plugins
" Nova desig nat ion ":
{
" name ": " name of nova " ,
" type ": " type of nova " ,
" m axMa gnit ude ": value of maxim al visual magnitude ,
" m inMa gnit ude ": value of minim al visual magnitude ,
" peakJD ": JD for maximal visual magnitude ,
" m2 ": Time to decline by 2 mag from maximum ( in days),
" m3 ": Time to decline by 3 mag from maximum ( in days),
" m6 ": Time to decline by 6 mag from maximum ( in days),
" m9 ": Time to decline by 9 mag from maximum ( in days),
" distance " : value of d istance between nova and
Earth ( in thousands of Light Years ),
" RA ": " Right ascensi on ( J2000 )" ,
" Dec ": " Declination ( J2000 )"
},
For example, the record for Nova Cygni 1975 (V1500 Cyg) looks like:
" V1500 Cyg ":
{
" name ": " Nova Cygni 1975 " ,
" type ": " NA " ,
" m axMa gnit ude ": 1.69 ,
" m inMa gnit ude ": 21 ,
" peakJD ": 2442655 ,
" m2 ": 2 ,
" m3 ": 4 ,
" m6 ": 32 ,
" m9 ": 263
" distance " : 6.36 ,
" RA ": " 21 h11m36 .6 s ",
" Dec ": " 48 d09m02 s "
},
14.1.3 Light curves
This plugin uses a very simple model for calculation of light curves for novae stars. This model is based on
time for decay by
N
magnitudes from the maximum value, where
N
is 2, 3, 6 and 9. If a nova has no values
for decay of magnitude then this plugin will use generalized values for it.
14.2 Historical Supernovae Plugin 173
14.2 Historical Supernovae Plugin
Figure 14.2: Supernova 1604 (also known as Kepler’s Supernova, Kepler’s Nova or Kepler’s
Star)
Similar to the Historical Novae plugin (section 14.1), the Historical Supernovae plugin provides visualization
of bright historical supernovae (Fig. 14.2) from the table below. If enabled (see section 12.1), bright
supernovae from the past will be presented in the sky at the correct times. For example, set date and time to
29 April 1006, and look at the constellation Lupus to see SN 1006A.
14.2.1 List of supernovae in default ca talog
Supernova Date of max. brightness Max. apparent mag. Type Name
SN 185A
2
7 December -6.0 Ia
SN 386A 24 April 1.5 II
SN 1006A
3
29 April -7.5 I
SN 1054A
4
3 July -6.0 II
SN 1181A
5
4 August -2.0 II
SN 1572A
6
5 November -4.0 I Tycho’s Supernova
SN 1604A
7
8 October -2.0 I Kepler’s Supernova
SN 1680A
8
15 August 6.0 IIb Cassiopeia A
2
https://en.wikipedia.org/wiki/SN_185
3
https://en.wikipedia.org/wiki/SN_1006
4
https://en.wikipedia.org/wiki/SN_1054
5
https://en.wikipedia.org/wiki/SN_1181
6
https://en.wikipedia.org/wiki/SN_1572
7
https://en.wikipedia.org/wiki/SN_1604
8
https://en.wikipedia.org/wiki/Cassiopeia_A
174 Chapter 14. Object Catalog Plugins
SN 1885A
9
17 August 5.8 IPec S Andromedae
SN 1895B 5 July 8.0 I
SN 1919A 14 March 11.0 I
SN 1920A 17 December 11.7 II
SN 1921C 11 December 11.0 I
SN 1937C 21 August 8.5 Ia
SN 1937D 15 September 11.87 Ia
SN 1960F 21 April 11.6 Ia
SN 1960R 19 December 12.0 I
SN 1961H 8 May 11.8 Ia
SN 1962M 26 November 11.5 II
SN 1965I 19 Juni 11.8 Ia
SN 1966J 2 December 11.3 I
SN 1968L 12 July 11.9 IIP
SN 1970G 30 July 11.4 IIL
SN 1971I 29 May 11.9 Ia
SN 1972E
10
8 May 8.4 Ia
SN 1974G 27 April 11.8 Ia
SN 1979C 15 April 11.6 IIL
SN 1980K 31 October 11.6 IIL
SN 1981B 9 March 12.0 Ia
SN 1983N 17 July 11.4 Ib
SN 1986G 12 May 11.44 Ia Pec
SN 1987A
11
24 February 2.9 IIPec
SN 1989B 6 February 11.9 Ia
SN 1991T 26 April 11.6 IaPec
SN 1993J
12
30 March 10.8 IIb
SN 1994ae 12 January 12.0 Ia
SN 1994D 31 March 11.8 Ia
SN 1998bu 21 May 11.9 Ia
SN 2004dj 31 July 11.3 IIP
SN 2004et 2 October 11.57 II
SN 2011fe
13
13 September 10.06 Ia
SN 2012cg 6 Juni 11.954 Ia
SN 2012fr 16 November 11.95 Ia
SN 2013aa 13 February 11.9 Ia
SN 2014j 30 January 10.5 Ia
SN 2017cbv 22 March 11.5 Ia
14.2.2 Light curves
In this plugin a simple model of light curves for different supernovae has been implemented (Figure 14.3).
While Type I supernovae show a peak and slow but steady decay, Type II supernovae show a longer “plateau”
in the decay curve.
In both images for light curves the maximum brightness is marked as day 0.
9
https://en.wikipedia.org/wiki/S_Andromedae
10
https://en.wikipedia.org/wiki/SN1972e
11
https://en.wikipedia.org/wiki/SN_1987A
12
https://en.wikipedia.org/wiki/SN_1993J
13
https://en.wikipedia.org/wiki/SN_2011fe
14.2 Historical Supernovae Plugin 175
Figure 14.3: Light Curves of Supernovae Types I (left) and II (right)
14.2.3 Section
[
Super novae
]
in config.ini file
You can edit
config.ini
file by yourself for changes of the settings for the Historical Supernovae plugin –
just make it carefully!
ID Type Description
last_update
string Date and time of last update
update_frequency_days
int Frequency of updates, in days
updates_enable
bool Enable updates of bright novae catalog from Internet
url
string URL of bright novae catalog
14.2.4 Format of historical supernovae catalog
To add a new nova, open a new line after line 5 and paste the following, note commas and brackets, they are
important:
" Supernova designatio n ":
{
" type ": " type of supernova " ,
" m axMa gnit ude ": value of maxim al visual magnitude ,
" peakJD ": JD for maximal visual magnitude ,
" alpha ": " Right asc ens ion ( J2000 )" ,
" delta ": " Dec lin atio n ( J2000 )" ,
" distance " : value of d istance between su pernova and
Earth ( in thousands of Light Years ),
" note ": " notes for s upernova "
},
For example, the record for SN 1604A (Kepler’s Supernova) looks like:
" 1604 A":
{
" type ": " I" ,
" m axMa gnit ude ": -2,
" peakJD ": 2307190 ,
" alpha ": " 17 h30m36 .00 s" ,
" delta ": " -21 d29m00 .0 s" ,
" distance " : 14 ,
" note ": " Kepler ’s Su pernova "
},
176 Chapter 14. Object Catalog Plugins
14.3 Exoplanets Plugin
Figure 14.4: Planetary system τ Ceti
This plugin plots the position of stars with exoplanets. Exoplanets data is derived from “The Extrasolar
Planets Encyclopaedia”
14
. List of potential habitable exoplanets and data about them were taken from “The
Habitable Exoplanets Catalog”
15
by the Planetary Habitability Laboratory
16
. If enabled (see section 12.1),
just click on the Exoplanet button on the bottom toolbar to display markers for the stars with known
exoplanets. You can then either click on such a marked star or find the stars with exoplanets by their
designation (e.g., 24 Sex) in the
F3
dialog (see 4.5).
A large number of exoplanets was discovered by the Kepler space observatory mission (2009–18) which
in its primary mission observed a small field in the Cyg/Lib/Dra area. Accordingly you will find a huge
concentration of exoplanets there. This should give us a hint about how many more must be out there. Its
extended mission added many more exoplanet systems along the ecliptic.
The second tab in the plugin’s dialog shows a scatter plot relating two selectable properties. In some
cases a logarithmic axis is more useful, but if the original values can be negative only the positive data are
shown in log plots. Additional entry fields allow filtering the data range.
14.3.1 Potential habitable exoplanets
This plugin can display potential habitable exoplanets (orange marker) and some information about those
planets.
Planetary Class
Planet classification from host star spectral type (F, G, K, M; see section 19.2.4), habitable
zone (hot, warm, cold) and size (miniterran, subterran, terran, superterran, jovian, neptunian) (Earth =
G-Warm Terran).
Equilibrium Temperature
The planetary equilibrium temperature
17
is a theoretical temperature (in °C)
that the planet would be at when considered simply as if it were a black body being heated only by its
parent star (assuming a 0.3 bond albedo). As example the planetary equilibrium temperature of Earth
is -18.15°C (255 K).
Earth Similarity Index (ESI)
Similarity to Earth
18
on a scale from 0 to 1, with 1 being the most Earth-like.
ESI depends on the planet’s radius, density, escape velocity, and surface temperature.
14
http://exoplanet.eu/
15
https://phl.upr.edu/projects/habitable-exoplanets-catalog
16
https://phl.upr.edu/home
17
https://en.wikipedia.org/wiki/Planetary_equilibrium_temperature
18
https://phl.upr.edu/projects/earth-similarity-index-esi
14.3 Exoplanets Plugin 177
14.3.2 Proper names
In December 2015
19
and in December 2019
20
, the International Astronomical Union (IAU) has officially
approved names for several exoplanets after a public vote.
Veritate * (14 And) – From the latin Veritas, truth. The ablative form means where there is truth
21
.
Spe * (14 And b) – From the latin Spes, hope. The ablative form means where there is hope.
Musica (18 Del) – Musica is Latin for music.
Arion
(18 Del b) – Arion was a genius of poetry and music in ancient Greece. According to legend, his life
was saved at sea by dolphins after attracting their attention by the playing of his kithara.
Fafnir (42 Dra) – Fafnir was a Norse mythological dwarf who turned into a dragon.
Orbitar
(42 Dra b) – Orbitar is a contrived word paying homage to the space launch and orbital operations
of NASA.
Chalawan (47 UMa) – Chalawan is a mythological crocodile king from a Thai folktale.
Taphao Thong
(47 UMa b) – Taphao Thong is one of two sisters associated with the Thai folk tale of
Chalawan.
Taphao Kaew
(47 UMa c) – Taphao Kae is one of two sisters associated with the Thai folk tale of Chalawan.
Helvetios
(51 Peg) – Helvetios is Celtic for the Helvetian and refers to the Celtic tribe that lived in
Switzerland during antiquity.
Dimidium
(51 Peg b) – Dimidium is Latin for half, referring to the planet’s mass of at least half the mass of
Jupiter.
Copernicus
(55 Cnc) – Nicolaus Copernicus or Mikolaj Kopernik (1473-1543) was a Polish astronomer
who proposed the heliocentric model of the solar system in his book “De revolutionibus orbium
coelestium”.
Galileo
(55 Cnc b) – Galileo Galilei (1564-1642) was an Italian astronomer and physicist often called the
father of observational astronomy and the father of modern physics. Using a telescope, he discovered
the four largest satellites of Jupiter, and the reported the first telescopic observations of the phases of
Venus, among other discoveries.
Brahe
(55 Cnc c) – Tycho Brahe (1546-1601) was a Danish astronomer and nobleman who recorded
accurate astronomical observations of the stars and planets. These observations were critical to
Kepler’s formulation of his three laws of planetary motion.
Lipperhey
* (55 Cnc d) – Hans Lipperhey (1570-1619) was a German-Dutch lens grinder and spectacle
maker who is often attributed with the invention of the refracting telescope in 1608
22
.
Janssen
(55 Cnc e) – Zacharias Janssen (1580s-1630s) was a Dutch spectacle maker who is often attributed
with invention of the microscope, and more controversially with the invention of the telescope.
Harriot
(55 Cnc f) – Thomas Harriot (ca. 1560-1621) was an English astronomer, mathematician, ethno-
grapher, and translator, who is attributed with the first drawing of the Moon through telescopic
observations.
Amateru
* (
ε
Tau b) – Amateru is a common Japanese appellation for shrines when they enshrine Amaterasu,
the Shinto goddess of the Sun, born from the left eye of the god Izanagi
23
.
Hypatia
(
ι
Dra b) – Hypatia was a famous Greek astronomer, mathematician, and philosopher. She was
head of the Neo-Platonic school at Alexandria in the early
5
th
century, until murdered by a Christian
mob in 415.
Ran
* (
ε
Eri) – Ran is the Norse goddess of the sea, who stirs up the waves and captures sailors with her net.
AEgir * (ε Eri b) – Ægir is Ran’s husband, the personified god of the ocean. Ægir and Ran both represent
the Jotuns who reign in the outer Universe; together they had nine daughters
24
.
Tadmor
* (
γ
Cep b) – Ancient Semitic name and modern Arabic name for the city of Palmyra, a UNESCO
World Heritage Site.
Dagon (
α PsA b) – Dagon was a Semitic deity, often represented as half-man, half-fish.
Tonatiuh (HD 104985) – Tonatiuh was the Aztec god of the Sun.
19
https://www.iau.org/news/pressreleases/detail/iau1514/
20
https://www.iau.org/news/pressreleases/detail/iau1912/
21
The original name proposed, Veritas, is that of an asteroid important for the study of the solar system.
22
The original spelling of Lippershey was corrected to Lipperhey on 15.01.2016. The commonly seen spelling
Lippershey (with an s) results in fact from a typographical error dating back from 1831, thus should be avoided.
23
The name originally proposed, Amaterasu, is already used for an asteroid.
24
Note the typographical difference between Ægir and Aegir, the Norwegian transliteration. The same name, with the
spelling Aegir, has been attributed to one of Saturn’s satellites, discovered in 2004.
178 Chapter 14. Object Catalog Plugins
Meztli (HD 104985 b) – Meztli was the Aztec goddess of the Moon.
Ogma
* (HD 149026) – Ogma was a deity of eloquence, writing, and great physical strength in the Celtic
mythologies of Ireland and Scotland, and may be related to the Gallo-Roman deity Ogmios
25
.
Smertrios (HD 149026 b) – Smertrios was a Gallic deity of war.
Intercrus
(HD 81688) – Intercrus means between the legs in Latin style, referring to the star’s position in
the constellation Ursa Major.
Arkas (HD 81688 b) – Arkas was the son of Callisto (Ursa Major) in Greek mythology.
Cervantes
(
µ
Ara) – Miguel de Cervantes Saavedra (1547-1616) was a famous Spanish writer and author
of “El Ingenioso Hidalgo Don Quixote de la Mancha”.
Quijote
(
µ
Ara b) – Lead fictional character from Cervantes’s “El Ingenioso Hidalgo Don Quixote de la
Mancha”.
Dulcinea
(
µ
Ara c) — Fictional character and love interest of Don Quijote (or Quixote) in Cervantes’s “El
Ingenioso Hidalgo Don Quixote de la Mancha”.
Rocinante
(
µ
Ara d) – Fictional horse of Don Quijote in Cervantes’s “El Ingenioso Hidalgo Don Quixote
de la Mancha”.
Sancho
(
µ
Ara e) – Fictional squire of Don Quijote in Cervantes’s “El Ingenioso Hidalgo Don Quixote de
la Mancha”.
Thestias
* (
β
Gem b) – Thestias is the patronym of Leda and her sister Althaea, the daughters of Thestius.
Leda was a Greek queen, mother of Pollux and of his twin Castor, and of Helen and Clytemnestra
26
.
Lich
(PSR B1257+12) – Lich is a fictional undead creature known for controlling other undead creatures
with magic.
Draugr (PSR B1257+12 b) – Draugr refers to undead creatures in Norse mythology.
Poltergeist
(PSR B1257+12 c) – Poltergeist is a name for supernatural beings that create physical distur-
bances, from German for noisy ghost.
Phobetor
(PSR B1257+12 d) – Phobetor is a Greek mythological deity of nightmares, the son of Nyx, the
primordial deity of night.
Titawin
(
υ
And) – Titawin (also known as Medina of Tetouan) is a settlement in northern Morocco
and UNESCO World Heritage Site. Historically it was an important point of contact between two
civilizations (Spanish and Arab) and two continents (Europe and Africa) after the 8
th
century.
Saffar
(
υ
And b) – Saffar is named for Abu al-Qasim Ahmed Ibn-Abd Allah Ibn-Omar al Ghafiqi Ibn-
al-Saffar, who taught arithmetic, geometry, and astronomy in
11
th
century Cordova in Andalusia
(modern Spain), and wrote an influential treatise on the uses of the astrolabe.
Samh
(
υ
And c) – Samh is named for Abu al-Qasim ’Asbagh ibn Muhammad ibn al-Samh al-Mahri (or Ibn
al-Samh), a noted 11
th
century astronomer and mathematician in the school of al Majriti in Cordova
(Andalusia, now modern Spain).
Majriti
(
υ
And d) – Majriti is named for Abu al-Qasim al-Qurtubi al-Majriti, a notable mathematician,
astronomer, scholar, and teacher in 10
th
century and early 11
th
century Andalusia (modern Spain).
Libertas
* (
ξ
Aql) – Libertas is Latin for liberty. Liberty refers to social and political freedoms, and a
reminder that there are people deprived of liberty in the world even today. The constellation Aquila
represents an eagle – a popular symbol of liberty.
Fortitudo
* (
ξ
Aql b) – Fortitudo is Latin for fortitude. Fortitude means emotional and mental strength in
the face of adversity, as embodied by the eagle (represented by the constellation Aquila).
Illyrian
(HD 82886) – Historians largely believe that the Albanians are descendants of the Illyrians, a term
Albanians proudly call themselves.
Arber (HD 82886 b) – Arber is the term for the inhabitants of Albania during the middle ages.
Hoggar
(HD 28678) – Hoggar is the name of the main mountain range in the Sahara Desert in southern
Algeria.
Tassili
(HD 28678 b) – Tassili is a UNESCO World Heritage Site situated in the Sahara Desert and is
renowned for its prehistoric cave art and scenic geological formations.
Arcalís
(HD 131496) – Arcalis is a famous peak in the north of Andorra, where the Sun passes through a
hole in the mountain twice a year at fixed dates. It was used as a primitive solar calendar and reference
point for shepherds and early inhabitants of Andorra.
Madriu
(HD 131496 b) – Madriu (Mare del riu in Catalan, Mother of the River in English) is the name of a
25
Ogmios is a name already attributed to an asteroid.
26
The original proposed name Leda is already attributed to an asteroid and to one of Jupiter’s satellites. The name
Althaea is also attributed to an asteroid.
14.3 Exoplanets Plugin 179
glacial valley and of the river that runs through it in the southeast of Andorra. It is the main part of
the Madriu-Perafita-Claror UNESCO World Heritage Site.
Nosaxa
(HD 48265) – Nosaxa means spring in the Moqoit language. The word comes from a combination
of nosahuec, which means renew, and ñaaxa, which means year.
Naqaya
(HD 48265 b) – Naqaya means brother-family-relative in the Moqoit language and leads us to call
all humans, indigenous or non-indigenous, brother.
Malmok
(WASP-39) – Malmok is an indigenous name given to a beach in Aruba with a narrow sandy
stretch that interrupts the limestone and rocky terrace along the coast. Its shallow clear Caribbean
waters make it a popular snorkelling spot.
Bocaprins
(WASP-39 b) – Boca Prins is a secluded beach with white dunes and iconic scenery situated in
Arikok National Park along the northeast coast of Aruba. It is named after Plantation Prins where
coconuts are cultivated.
Bubup (HD 38283) – Bubup is the Boonwurrung word for child.
Yanyan (HD 38283 b) – YanYan is the Boonwurrung word for boy.
Franz
(HAT-P-14) – Franz is a character in the movie “Sissi” embodying an emperor of Austria in the
19
th
century. The role is played by the actor Karlheinz Böhm.
Sissi
(HAT-P-14 b) – Sissi is a character in the movie “Sissi”, who is married with Franz. The role is played
by the actress Romy Schneider.
Mahsati
(HD 152581) – Mahsati Ganjavi (1089–1159) is one of the brightest shining stars of Azerbaijani
poetry. She was said to have associated with both Omar Khayyam and Nizami and was well educated
and talented and played numerous musical instruments.
Ganja
(HD 152581 b) – Ganja is an ancient city of Azerbaijan, and is the birth place of many prominent
people such as the poets Mahsati and Nizami. It is the ancient capital of Azerbaijan, the first capital
of the Azerbaijan Democratic Republic and the city with the spirit of wisdom and freedom.
Timir
(HD 148427) – Timir means darkness in Bengali language, alluding to the star being far away in the
darkness of space.
Tondra
(HD 148427 b) – Tondra means nap in Bengali language, alluding to the symbolic notion that the
planet was asleep until discovered.
Nervia (HD 49674) – Nervia, adapted from Nervii, was a prominent Belgian Celtic tribe.
Eburonia (HD 49674 b) – Eburonia, adapted from Eburones, was a prominent Belgian Celtic tribe.
Gakyid
(HD 73534) – Gakyid means happiness. Gross National Happiness is the development philosophy
conceived and followed in Bhutan and is one of Bhutan’s contributions to the world.
Drukyul
(HD 73534 b) – Drukyul (land of the thunder dragon) is the native name for Bhutan, the country
that came up with the philosophy of Gross National Happiness.
Tapecue
(HD 63765) – Tapecue means eternal path in Guarani and represents the Milky Way through
which the first inhabitants of the Earth arrived and could return.
Yvaga
(HD 63765 b) – Yvaga means paradise for the Guarani and the Milky Way was known as the road to
Yvaga or paradise.
Bosona
(HD 206610) – Bosona is the name given to the territory of Bosnia in the
10
th
century. Later, the
name was transformed to Bosnia originating from the name of the Bosna river.
Naron
(HD 206610 b) – Naron is one of the names given to the Neretva river in Herzegovina (and partly in
Croatia) in antiquity originating with the Celts who called it Nera Etwa which means the Flowing
Divinity.
Tupi
(HD 23079) – Tupi is the name of the most populous Indigenous People living on the eastern coast of
South America, before the Portuguese arrived in the 16
th
century.
Guarani
(HD 23079 b) – Guarani is the name of the most populous Indigenous people living in South
Brazil and parts of Argentina, Paraguay and Uruguay.
Gumala
(HD 179949) – Gumala is a Malay word, which means a magic bezoar stone found in snakes,
dragons, etc.
Mastika
(HD 179949 b) – Mastika is a Malay word, which means a gem, precious stone, jewel or the
prettiest, the most beautiful.
Tangra (WASP-21) – Tangra is the supreme celestial god that early Bulgars worshiped.
Bendida
(WASP-21 b) – Bendida is the Great Mother Goddess of the Thracians. She was especially revered
as a goddess of marriage and living nature.
Mouhoun
(HD 30856) – Mouhoun, also called Volta Noire, is the largest river in Burkina Faso and plays
an important role in the lives of the people in the areas it passes through.
Nakanbé
(HD 30856 b) – The Nakanbé, also called Volta Blanche, is the second largest river in Burkina
180 Chapter 14. Object Catalog Plugins
Faso. Its source is in the heart of the Sahara Burkinabe and ends in Ghana.
Nikawiy (HD 136418) – Nikawiy is the word for mother in the Indigenous Cree language of Canada.
Awasis (HD 136418 b) – Awasis is the word for child in the Indigenous Cree language of Canada.
Pincoya
(HD 164604) – Pincoya is a female water spirit from southern Chilean mythology who is said to
bring drowned sailors to the Caleuche so that they can live in the afterlife.
Caleuche
(HD 164604 b) – Caleuche is a large ghost ship from southern Chilean mythology which sails the
seas around the island of Chiloé at night.
Lionrock
(HD 212771) – Lion Rock is a lion-shaped peak overlooking Hong Kong and is a cultural symbol
with deep respect from the local community.
Victoriapeak
(HD 212771 b) – Victoria Peak overlooks the bustling Victoria Harbour and is regarded as an
ambassadorial gateway for foreign visitors wishing to experience Hong Kong first hand.
Xihe
(HD 173416) – Xiheis the goddess of the sun in the Chinese mythology and also represents the earliest
astronomers and developers of calendars in ancient China.
Wangshu
(HD 173416 b) – Wangshu is the goddess who drives for the Moon and also represents the Moon
in Chinese mythology.
Formosa
(HD 100655) – Formosa is the historical name of Taiwan used in the
17
th
century, meaning
beautiful in Latin.
Sazum
(HD 100655 b) – Sazum is the traditional name of Yuchi, a Township in Nantou county, in which
the famous Sun-Moon Lake lies. Sazum means water in the language of the Thao people who are a
tribe of Taiwanese aborigines who lived in the region for hundreds of years.
Macondo
(HD 93083) – Macondo is the mythical village of the novel “One Hundred Years of Solitude”
(“Cien años de soledad”) the classic novel by Gabriel García Marquez. Macondo is a fictional place
where magic and reality are mixed.
Melquíades
(HD 93083 b) – Melquíades is a fictional character that walks around Macondo, like a planet
orbiting a star, connecting it with the external world by introducing new knowledge using his inventions
as well as his stories.
Poerava
(HD 221287) – Poerava is the word in the Cook Islands Maori language for a large mystical black
pearl of utter beauty and perfection.
Pipitea
(HD 221287 b) – Pipitea is a small, white and gold pearl found in Penrhyn lagoon in the northern
group of the Cook Islands.
Dìwö
(WASP-17) – Dìwö in Bribri language means the sun (bigger than the sun we know) and that never
turns off.
Ditsö (WASP-17 b) – Ditsö is the name that the god Sibö gave to the first Bribri people.
Stribor
(HD 75898) – Stribor is God of winds in Slavic mythology, as well as a literature character in the
book Pri
ˇ
ce iz davnine (Croatian Tales of Long Ago) by the Croatian author Ivana Brli
´
c-Mažurani
´
c.
Veles (HD 75898 b) – Veles is a major Slavic god of earth, waters and the underworld.
Felixvarela
(BD-17 63) – Felix Varela (1788–1853) was the first to teach science in Cuba at the San Carlos
and San Ambrosio Seminary. He opened the way to education for all, and began the experimental
teaching of physics in Cuba.
Finlay
(BD-17 63 b) – Carlos Juan Finlay (1833–1915) was an epidemiologist recognized as a pioneer in
the research of yellow fever, determining that it was transmitted through mosquitoes.
Alasia
(HD 168746) – Alasia is the first historically recorded name of Cyprus, dating back to mid-fifteenth
century BC.
Onasilos
(HD 168746 b) – Onasilos is the oldest historically recorded doctor in Cyprus, inscribed on the
fifth century BC Idalion Tablet. Also known as the Onasilou Plate, it is considered as the oldest legal
contract found in the world.
Absolutno
(XO-5) – Absolutno is a fictional miraculous substance in the sci-fi novel “Továrna na absolutno”
(“The Factory for the Absolute”) by influential Czech writer Karel
ˇ
Capek.
Makropulos
(XO-5 b) – Makropulos is the name from Karel
ˇ
Capek’s play V
ˇ
ec Makropulos (The Makropu-
los Affair), dealing with problems of immortality and consequences of an artificial prolongation of
life.
Muspelheim
(HAT-P-29) – Muspelheim is the Norse mythological realm of fire. The first gods used the
sparks of Muspelheim to form the sun, moon, planets, and stars.
Surt
(HAT-P-29 b) – Surt is the ruler of Muspelheim and the fire giants there in Norse mythology. At
Ragnarok, the end of the world, he will lead the attack on our world and destroy it in flames.
Márohu
(WASP-6) – Márohu the god of drought is the protector of the Sun and is engraved at a higher
position on the stalagmite than Boinayel in the El Puente cave, where the Sun makes its way down
14.3 Exoplanets Plugin 181
every 21 December.
Boinayel
(WASP-6 b) – Boinayel the god of rain that fertilizes the soil is engraved on the stalagmite at a
lower position than Márohu in the El Puente cave.
Nenque
(HD 6434) – Nenque means the Sun in the language spoken by the Indigenous Waorani tribes of
the Amazon regions of Ecuador
Eyeke
(HD 6434 b) – Eyeke means near in the language spoken by the Indigenous Waorani tribes of the
Amazon regions of Ecuador. This word is suggested for the exoplanet owing to the proximity of the
planet to the host star.
Citalá (HD 52265) – Citalá means River of stars in the native Nahuat language.
Cayahuanca
(HD 52265 b) – Cayahuanca means The rock looking at the stars in the native Nahuat language.
Koit (XO-4) – Koit is Estonian for the time when the Sun rises in the morning (dawn).
Hämarik (XO-4 b) – Hämarik is Estonian for the time when the Sun goes down in the evening (twilight).
Buna (HD 16175) – Buna is the commonly used word for coffee in Ethiopia.
Abol
(HD 16175 b) – Abol is the first of three rounds of coffee in the Ethiopian traditional coffee ceremony.
Horna (HAT-P-38) – Horna is hell or the underworld from Finnic mythology.
Hiisi (HAT-P-38 b) – Hiisi represents sacred localities and later evil spirits from Finnic mythology.
Bélénos (HD 8574) – Bélénos was the god of light, of the Sun, and of health in Gaulish mythology.
Bélisama
(HD 8574 b) – Bélisama was the goddess of fire, notably of the hearth and of metallurgy and
glasswork, in Gaulish mythology.
Itonda (HD 208487) – Itonda, in the Myene tongue, corresponds to all that is beautiful.
Mintome
(HD 208487 b) – Mintome, in the Fang tongue, is a mythical land where a brotherhood of brave
men live.
Mago
(HD 32518) – Mago is a National Park in Ethiopia noted for its giraffes. The star also happens to be
in the constellation of Camelopardis (the giraffe).
Neri (HD 32518 b) – The Neri river in Ethiopia runs through parts of the Mago National park.
Sika (HD 181720) – Sika means gold in the Ewe language and gold is one of Ghana’s principal exports.
Toge (HD 181720 b) – Toge means earring in the Ewe language.
Lerna (HAT-P-42) – Lerna was the name of a lake in the eastern Peloponnese, where the Lernaean Hydra,
an immortal mythical nine-headed beast lived. The star lies in the constellation of Hydra.
Iolaus
(HAT-P-42 b) – Iolaus was the nephew of Heracles from Greek mythology, moving around lake Lerna
in helping Heracles to exterminate the Lernaean Hydra. Similarly this exoplanet in the constellation
of Hydra moves around its parent star.
Tojil (WASP-22) – Tojil is the name of one of the Mayan deities related to rain, storms, and fire.
Koyopa’
(WASP-22 b) – Koyopa’ is the word associated with lightning in K’iche’ (Quiché) Mayan language.
Citadelle
(HD 1502) – The Citadelle is a large mountaintop fortress in Nord, Haiti built after Haiti’s
independence, and was designated a UNESCO World Heritage site along with the nearby Sans-Souci
Palace.
Indépendance
(HD 1502 b) – Indépendance is named after the Haitian Declaration of Independence on 1
January 1804, when Haiti became the first independent black republic.
Hunahpú
(HD 98219) – Hunahpú was one of the twin gods who became the Sun in K’iche’ (Quiché)
Mayan mythology as recounted in the Popol Vuh.
Ixbalanqué
(HD 98219 b) – Ixbalanqué was one of the twin gods who became the Moon in K’iche’ (Quiché)
Mayan mythology as recounted in the Popol Vuh.
Hunor
(HAT-P-2) – Hunor was a legendary ancestor of the Huns and the Hungarian nation, and brother of
Magor.
Magor
(HAT-P-2 b) – Magor was a legendary ancestor of the Magyar people and the Hungarian nation, and
brother of Hunor.
Funi (HD 109246) – Funi is an old Icelandic word meaning fire or blaze.
Fold (HD 109246 b) – Fold is an old Icelandic word meaning earth or soil.
Bibh
¯
a
(HD 86081) – Bibh
¯
a is the Bengali pronunciation of the Sanskrit word Vibha, which means a bright
beam of light.
Santamasa
(HD 86081 b) – Santamasa in Sanskrit means clouded, which alludes to the exoplanet’s
atmosphere.
Dofida (HD 117618) – Dofida means our star in Nias language.
Noifasui
(HD 117618 b) – Noifasui means revolve around in Nias language, derived from the word ifasui,
meaning to revolve around, and no, indicating that the action occurred in the past and continued to the
present time.
182 Chapter 14. Object Catalog Plugins
Kaveh
(HD 175541) – Kaveh is one of the heroes of Shahnameh, the epic poem composed by Persian poet
Ferdowsi between 977 and 1010 CE. Kaveh is a blacksmith who symbolises justice.
Kavian
(HD 175541 b) – Kaveh carries a banner called Derafsh Kaviani (Derafsh: banner, Kaviani: relating
to Kaveh).
Uruk
(HD 231701) – Uruk was an ancient city of the Sumer and Babylonian civilizations in Mesopotamia
situated along an ancient channel of the Euphrates river in modern-day Iraq.
Babylonia
(HD 231701 b) – Babylonia was a key kingdom in ancient Mesopotamia from the
18
th
to
6
th
centuries BC whose name-giving capital city was built on the Euphrates river.
Tuiren
(HAT-P-36) – Tuiren was the aunt of the hunterwarrior Fionn mac Cumhaill of Irish legend, who
was turned into a hound by the jealous fairy Uchtdealbh.
Bran
(HAT-P-36 b) – Tuiren’s son Bran was a hound and cousin of the hunterwarrior Fionn mac Cumhaill
of Irish legend.
Tevel
(HAT-P-9) – Tevel means Universe or everything and begins with the letter Taf, the last letter in the
Hebrew alphabet.
Alef (HAT-P-9 b) – Alef is the first letter in the Hebrew alphabet and also means bull.
Flegetonte
(HD 102195) – Flegetonte is the underworld river of fire from Greek Mythology in the Italian
narrative poem on the afterlife “Divina Commedia” (“Divine Commedy”) by Dante Alighieri, chosen
as an allusion to the star’s fiery nature.
Lete
(HD 102195 b) – Lete is the oblivion river made of fog from Greek Mythology in the Italian narrative
poem on the afterlife “Divina Commedia” (“Divine Commedy”) by Dante Alighieri, chosen as an
allusion to the planet’s gaseous nature.
Nyamien (WASP-15) – Nyamien refers to the supreme creator deity of Akan mythology.
Asye (WASP-15 b) – Asye refers to the Earth goddess of Akan mythology.
Kamui
(HD 145457) – Kamui is a word in the Ainu language denoting a supernatural entity possessing
spiritual energy.
Chura (HD 145457 b) – Chura is a word in the Ryukyuan/Okinawan language meaning natural beauty.
Petra
(WASP-80) – Petra is a historical and archaeological city in southern Jordan and a UNESCO World
Heritage site.
Wadirum
(WASP-80 b) – Wadi Rum (Valley of the Moon) is located at the far south of Jordan, it is the
largest valley in Jordan, set on the high plateau at the western edge of the Arabian Desert.
Kalausi
(HD 83443) – The word Kalausi means a very strong whirling column of wind in the Dholuo
language of Kenya.
Buru
(HD 83443 b) – Buru means dust in the Dholuo language of Kenya and is typically associated with
wind storms.
Liesma
(HD 118203) – Liesma means flame, and it is the name of a character from the Latvian poem
Staburags un Liesma.
Staburags
(HD 118203 b) – Staburags is the name of a character from the Latvian poem Staburags un
Liesma, and denotes a rock with symbolic meaning in literature and history.
Phoenicia
(HD 192263) – Phoenicia was an ancient thalassocratic civilisation of the Mediterranean that
originated from the area of modern-day Lebanon.
Beirut
(HD 192263 b) – Beirut is one of the oldest continuously inhabited cities in the world and was a
Phoenician port. Beirut is now the capital and largest city of Lebanon.
Pipoltr
(TrES-3) – In the local dialect of Triesenberg, Pipoltr is a bright and visible butterfly, alluding to the
properties of a star.
Umbäässa
(TrES-3 b) – In the local dialect of southern Liechtenstein, Umbäässa is a small and barely
visible ant, alluding to the properties of a planet with respect to its star.
Taika (HAT-P-40) – Taika means peace in the Lithuanian language.
Vytis (HAT-P-40 b) – Vytis is the symbol of the Lithuanian coat of arms.
Lucilinburhuc
(HD 45350) – The Lucilinburhuc fortress was built in 963 by the founder of Luxembourg,
Count Siegfried.
Peitruss
(HD 45350 b) – Peitruss is derived from the name of the Luxembourg river Pétrusse, with the
river’s bend around Lucilinburhuc fortress alluding to the orbit of the planet around its star.
Rapeto (HD 153950) – Rapeto is a giant creature from Malagasy tales.
Trimobe (HD 153950 b) – Trimobe is a rich ogre from Malagasy tales.
Intan
(HD 20868) – Intan means diamond in the Malay language (Bahasa Melayu), alluding to the shining
of a star.
Baiduri
(HD 20868 b) – Baiduri means opal in Malay language (Bahasa Melayu), alluding to the mysterious
14.3 Exoplanets Plugin 183
beauty of the planet.
Sansuna
(HAT-P-34) – Sansuna is the name of the mythological giant from traditional Maltese folk tales
that carried the stones of the Gozo megalithic temples on her head.
˙
Ggantija
(HAT-P-34 b) –
˙
Ggantija means giantess: the megalithic temple complex on the island of Gozo,
which alludes to the grandeur of this gas giant exoplanet.
Diya
(WASP-72) – Diya is an oil lamp that is brought by Indian ancestors to Mauritius in the 1820’s, and is
used for lighting during special occasions, including the light festival of Diwali.
Cuptor
(WASP-72 b) – Cuptor is a thermally insulated chamber used for baking or drying substances, that
has long disappeared in Mauritius and has been replaced by more sophisticated ovens.
Axólotl
(HD 224693) – Axólotl means water animal in the native Nahuatl language, which is a unique and
culturally significant endemic amphibious species from the basin of Mexico.
Xólotl
(HD 224693 b) – Xólotl means animal in the native Nahuatl language and was an Aztec deity
associated with the evening star (Venus).
Tislit
(WASP-161) – Tislit is the name of a lake in the Atlas mountains of Morocco. It means the bride in
the Amazigh language and it is associated with a heartbroken beautiful girl in an ancient local legend.
Isli
(WASP-161 b) – Isli is the name of a lake in the Atlas mountains of Morocco. It means the groom in the
Amazigh language and it is associated with a heartbroken handsome boy in an ancient local legend.
Emiw
(HD 7199) – Emiw represents love in the local Makhuwa language of the northern region of
Mozambique.
Hairu
(HD 7199 b) – Hairu represents unity in the local Makhuwa language of the northern region of
Mozambique.
Ayeyarwady (HD 18742) – Ayeyarwady is the largest and most important river in Myanmar.
Bagan (HD 18742 b) – Bagan is one of Myanmar’s ancient cities that lies beside the Ayeyarwardy river.
Sagarmatha
(HD 100777) – Sagarmatha is the Nepali name for the highest peak in the world (also known
as Mount Everest) and symbol of national pride of Nepal.
Laligurans
(HD 100777 b) – Laligurans are the Nepali variation of the rhododendron flower and is the
national flower of Nepal.
Sterrennacht
(HAT-P-6) – The Sterrennacht (Starry Night) is a world-famous painting by Dutch grand
master Van Gogh that was painted in France in 1889 and now belongs to the permanent collection of
New York’s Museum of Modern Art.
Nachtwacht
(HAT-P-6 b) – The Nachtwacht (Night Watch) is a world-famous painting by Dutch grand
master Rembrandt that was completed in 1642 and now belongs to the collection of the Rijksmuseum
in Amsterdam.
Karaka
(HD 137388) – Karaka is the word in the M
¯
aori language for a plant endemic to New Zealand that
produces a bright orange, fleshy fruit.
Kerer
¯
u
(HD 137388 b) – Kerer
¯
u is the word in the M
¯
aori language for a large bush pigeon native to New
Zealand.
Cocibolca
(HD 4208) – Cocibolca is the Nahualt name for the largest lake in Central America in Nicaragua.
Xolotlan
(HD 4208 b) – Xolotlan is the name of the second largest lake of Nicaragua and its name is from
the Nahualt language of the indigenous tribe that settled in Nicaragua, which symbolises a native god
and a refuge for animals.
Amadioha
(HD 43197) – Amadioha is the god of thunder in Igbo mythology. As well as representing
justice, Amadioha is also a god of love, peace and unity.
Equiano
(HD 43197 b) – Equiano was a writer and abolitionist from Ihiala, Nigeria who fought injustice
and the elimination of the slave trade.
Násti (HD 68988) – Násti means star in the Northern Sami language of Norway.
Albmi (HD 68988 b) – Albmi means sky in the Northern Sami language of Norway.
Shama
(HAT-P-23) – Shama is an Urdu literary term meaning a small lamp or flame, symbolic of the light
of the star.
Perwana
(HAT-P-23 b) – Perwana means moth in Urdu, alluding to the eternal love of an object circling the
source of light (the lamp).
Moriah (HD 99109) – Moriah is an ancient name for the mountain within the Old City of Jerusalem.
Jebus
(HD 99109 b) – Jebus was the ancient name of Jerusalem in
2
nd
millennium BC when populated by
the Canaanite tribe of Jebusites.
Montuno
(WASP-79) – Montuno is the traditional costume the man wears in the “El Punto”, a Panamanian
dance in which a man and woman dance to the sound of drums.
Pollera
(WASP-79 b) – Pollera is the traditional costume the woman wears in the El Punto, a Panamanian
184 Chapter 14. Object Catalog Plugins
dance in which a man and woman dance to the sound of drums.
Tupã
(HD 108147) – Tupã is one of four principle gods of the Guarani Cosmogony in popular Paraguayan
folklore that helped the supreme god Ñamandu to create the Universe.
Tumearandu
(HD 108147 b) – Tume Arandu is a son of Rupavê and Sypavê, the original man and woman
of the Universe, who is known as the Father of Wisdom in popular Paraguayan folklore.
Inquill
(HD 156411) – Inquil was one half of the couple involved in the tragic love story Way to the Sun by
famous Peruvian writer Abraham Valdelomar.
Sumajmajta
(HD 156411 b) – Sumaj Majta was one half of the couple involved in a tragic love story Way
to the Sun by famous Peruvian writer Abraham Valdelomar.
Amansinaya
(WASP-34) – Aman Sinaya is one of the two trinity deities of the Philippine’s Tagalog
mythology, and is the primordial deity of the ocean and protector of fisherman.
Haik
(WASP-34 b) – Haik is the successor of the primordial Aman Sinaya as the God of the Sea of the
Philippine’s Tagalog mythology.
Uklun (HD 102117) – Uklun means us or we in the Pitkern language of the people of Pitcairn Islands.
Leklsullun
(HD 102117 b) – Lekl Sullun means child or children in the Pitkern language of the people of
Pitcairn Islands.
Solaris
(BD+14 4559) – Solaris is the title of a 1961 science fiction novel about an ocean-covered exoplanet
by Polish writer Stanislaw Lem.
Pirx
(BD+14 4559 b) – Pirx is a fictional character from books by Polish science-fiction writer Stanislaw
Lem.
Lusitânia
(HD 45652) – Lusitânia is the ancient name of the western region of the Iberic Peninsula where
the Lusitanian people lived and where most of modern-day Portugal is situated.
Viriato
(HD 45652 b) – Viriato was a legendary leader of the Lusitanian people, a herdsman and hunter
who led the resistance against Roman invaders during 2
nd
century B.C.
Koeia
(HIP 12961) – Koeia was the word for star in the language of the Taíno Indigenous People of the
Caribbean.
Aumatex
(HIP 12961 b) – Aumatex was the God of Wind in the mythology of the Taíno Indigenous People
of the Caribbean.
Moldoveanu
(XO-1) – Moldoveanu is the highest peak in Romania of the F
˘
ag
˘
ara
s
,
mountain range with an
altitude of 2544 metres.
Negoiu
(XO-1 b) – Negoiu is the second highest peak in Romania of the F
˘
ag
˘
ara
s
,
mountain range with an
altitude of 2535 metres.
Dombay
(HAT-P-3) – Dombay is a resort region in the North Caucasus mountains that is enclosed by
mountain forests and rich wildlife, including bears (as this star lies in the constellation Ursa Major,
the great bear).
Teberda
(HAT-P-3 b) – Teberda is a mountain river in Dombay region with a rapid water flow, symbolising
the planet’s rapid motion around its host star.
Belel (HD 181342) – Belel is a rare source of water in the north of Senegal.
Dopere
(HD 181342 b) – Dopere is an expansive historical area in the north of Senegal where Belel was
located.
Morava (WASP-60) – Morava is the longest river system in Serbia.
Vlasina (WASP-60 b) – Vlasina is one of the most significant tributaries of the South Morava river.
Parumleo
(WASP-32) – Parumleo is a Latin term for little lion, symbolising Singapore’s struggle for
independence.
Viculus
(WASP-32 b) – Viculus is a Latin term for little village, embodying the spirit of the Singaporean
people.
Chaso
ˇ
n (HAT-P-5) – Chaso
ˇ
n is an ancient Slovak term for Sun.
Král’omoc (HAT-P-5 b) – Král’omoc is an ancient Slovak term for the planet Jupiter.
Irena
(WASP-38) – Irena is a leading character in the novel “Under the Free Sun: a Story of the Ancient
Grandfathers” by Slovene writer Fran Saleški Finžgar. Irena is a woman of the court.
Iztok
(WASP-38 b) – Iztok is a leading character in the novel “Under the Free Sun: a Story of the Ancient
Grandfathers” by Slovene writer Fran Saleški Finžgar. Iztok is a freedom fighter for the Slavic people.
Naledi
(WASP-62) – Naledi means star in the Sesotho, SeTswana and SePedi languages and is typically
given as a name to girls in the hope that they will bring light, joy and peace to their communities.
Krotoa
(WASP-62 b) – Krotoa is considered the Mother of Africa and member of the indigenous Khoi
people, who was a community builder and educator during colonial times.
Baekdu
(8 Umi) – Baekdu is the highest mountain on the Korean peninsula, situated in North Korea, and
14.3 Exoplanets Plugin 185
symbolises the national spirit of Korea.
Halla
(8 Umi b) – Halla is the highest mountain in South Korea and is regarded as a sacred place in the
region.
Rosalíadecastro
(HD 149143) – Rosalía de Castro was a significant figure of Galician culture and prominent
Spanish writer, whose pioneeting work often referenced the night and celestial objects.
Riosar
(HD 149143 b) – Rio Sar is the name of a river that was present in much of the literary work of the
pioneering Spanish author Rosalía de Castro.
S
¯
amaya (HD 205739) – S
¯
amaya means peace in the Sinhalese language.
Samagiya (HD 205739 b) – Samagiya means togetherness and unity in the Sinhalese language.
Aniara
(HD 102956) – Aniara is the name of a spaceship in the epic poem Aniara by Swedish author Harry
Martinson.
Isagel
(HD 102956 b) – Isagel is the name of the spaceship pilot in the epic science fiction poem Aniara
written by Swedish author Harry Martinson.
Mönch (HD 130322) – Mönch is one of the prominent peaks of the Bernese Alps in Switzerland.
Eiger
(HD 130322 b) – Eiger is one of the prominent peaks of the Bernese Alps, in the Jungfrau-Aletsch
protected area.
Ebla
(HD 218566) – Ebla was one of the earliest kingdoms in Syria, and served as a prominent region in
the 2
nd
and 3
rd
millennia B.C.
Ugarit
(HD 218566 b) – Ugarit was a city where its scribes devised the Ugaritic alphabet around 1400 B.C.
The alphabet was made up of thirty letters and was inscribed on clay tablets.
Mpingo
(WASP-71) – Mpingo is a famous tree that grows in southern Tanzania and produces ebony wood
used for musical instruments and curios.
Tanzanite
(WASP-71 b) – Tanzanite is the name of a precious stone mined in Tanzania and is treasured
worldwide.
Chaophraya (WASP-50) – Chao Phraya is the great river of Thailand.
Maeping (WASP-50 b) – Mae Ping is one of the tributaries of Thailand’s great river Chao Phraya.
Atakoraka (WASP-64) – Atakoraka means the chain of the Atacora: the largest mountain range in Togo.
Agouto
(WASP-64 b) – Agouto (Mount Agou) is the highest mountain in Togo and a treasured region of
the Atakoraka.
Dingolay
(HD 96063) – Dingolay means to dance, twist and turn in elaborate movements, symbolising the
culture and language of the ancestors of the people of Trinidad and Tobago.
Ramajay
(HD 96063 b) – Ramajay means to sing and make music in a steelpan style, representing the love
of culture and languages of the ancestors of the people of Trinidad and Tobago.
Chechia
(HD 192699) – Chechia is a flat-surfaced, traditional red wool hat worn by men and women,
symbolising the country’s rich traditions and is considered as the national headdress for in Tunisia.
Khomsa
(HD 192699 b) – Khomsa is a palm-shaped amulet that is popular in Tunisia, used in jewelry and
decorations. It depicts an open right hand and is often found in modern designs.
Anadolu
(WASP-52) – Anadolu is the primary homeland of Turkey and refers to the motherland in Turkish
culture.
Göktürk
(WASP-52 b) – Göktürk refers to the historical origin of the Turkish people, as it was the first
established state in Turkey in
5
th
century AD. It is also the name of a Turkish satellite and is the
combination of two words, of which “Gök” means sky.
Berehinya
(HAT-P-15) – Berehinya was a Slavic deity of waters and riverbanks but in more recent times
her status has been promoted to that of a national goddess — “hearth mother, protectress of the earth”.
Tryzub
(HAT-P-15 b) – Tryzub is the most recognised ancient symbol of Ukraine, that was minted on the
coins of Prince Volodymyr the Great and today remains one of the country’s state symbols (a small
coat).
Sharjah
(HIP 79431) – Sharjah is the cultural capital of United Arab Emirates, and considered the city of
knowledge due to its many educational centers, institutes, museums, libraries and heritage centers.
Barajeel
(HIP 79431 b) – A barajeel is a wind tower used to direct the flow of the wind so that air can be
recirculated as a form of air conditioning.
Gloas (WASP-13) – In Manx Gaelic, Gloas means to shine (like a star).
Cruinlagh (WASP-13 b) – In Manx Gaelic, Cruinlagh means to orbit (like a planet around its star).
Nushagak
(HD 17156) – Nushagak is a regional river near Dilingham, Alaska, which is famous for its wild
salmon that sustain local Indigenous communities.
Mulchatna
(HD 17156 b) – The Mulchatna River is a tributary of the Nushagak River in southwestern
Alaska, USA.
186 Chapter 14. Object Catalog Plugins
Ceibo (HD 63454) – Ceibo is the name of the native tree of Uruguay that gives rise to the national flower.
Ibirapitá
(HD 63454 b) – Ibirapitá is the name of a native tree that is characteristic of the country of
Uruguay, and is also known as Artigas’ tree, after the national hero.
Natasha (HD 85390) – Natasha means thank you in many languages of Zambia.
Madalitso (HD 85390 b) – Madalitso means blessings in the native language of Nyanja in Zambia.
All names with asterix mark (*) are modified based on the original proposals, to be consistent with the
IAU rules.
14.3.3 Section
[
Exoplanets
]
in config.ini file
You can edit config.ini file to change the settings for the Exoplanets plugin – just make it carefully!
ID Type Description
last_update string Date and time of last update
update_frequency_hours
int Frequency of updates, in hours
updates_enable
bool Enable updates of exoplanets catalog from Internet
url
string URL of exoplanets catalog
flag_show_exoplanets_button
bool Enable showing button of exoplanets on bottom bar
distribution_enabled
bool Enable distribution mode of display
timeline_enabled
bool Enable timeline mode of display
habitable_enabled
bool Enable habitable mode of display
enable_at_startup
bool Enable displaying exoplanets at startup of the plugin
exoplanet_marker_color
R,G,B Color for marker of star with planetary system
habitable_exoplanet_marker_color
R,G,B
Color for marker of star with planetary system with
potential habitable exoplanets
temperature_scale
string
Temperature scale for equilibrium temperature of exo-
planets. Possible values: Kelvin, Celsius, Fahrenheit.
Default value: Celsius.
14.3.4 Format of exoplanets catalog
To add a new exoplanet system, open a new line after line 5 and paste the following, note commas and
brackets, they are important:
" Star de sig na t io n ":
{
" exo pla net s ":
[
{
" mass ": mass of ex opl ane t ( M jup ) ,
" radius " : radius of exop lane t ( R jup ),
" period " : period of exop lane t ( days ),
" semiA xis " : semi - major axis ( AU) ,
" ecc en tri ci ty " : orbit ’s eccentrici ty ,
" inc lin at ion ": orbit ’s i nc lin at ion ( d egree ) ,
" ang le Di st a nc e ": angle distan ce from star ( arc sec ond s ),
" dis cov ere d ": exopl ane t d isc ove red year ,
" de te cti on Me th od ": " e xop lane t d ete c tio n metho d ",
" pclass " : " p lane tar y class " ,
" EqTemp " : e qui lib ri um t em per atu re ( K),
" con se rva ti ve " : cons erv at ive or opt imi sti c
hab ita bi lit y of the exoplanet ,
" ESI ": Earth Simi la rit y Index (*100) ,
" pl an et Pr op er Na me " : " pr oper name of pla net " ,
" pla net Nam e ": " des ig nat ion of planet "
},
{
" mass ": mass of ex opl ane t ( M jup ) ,
" radius " : radius of exop lane t ( R jup ),
" period " : period of exop lane t ( days ),
" semiA xis " : semi - major axis ( AU) ,
14.3 Exoplanets Plugin 187
" ecc en tri ci ty " : orbit ’s eccentrici ty ,
" inc lin at ion ": orbit ’s i nc lin at ion ( d egree ) ,
" ang le Di st a nc e ": angle distan ce from star ( arc sec ond s ),
" dis cov ere d ": exopl ane t d isc ove red year ,
" de te cti on Me th od ": " e xop lane t d ete c tio n metho d ",
" pclass " : " p lane tar y class " ,
" EqTemp " : e qui lib ri um t em per atu re ( K),
" con se rva ti ve " : cons erv at ive or opt imi sti c h ab ita bi li t y of the
exoplanet ,
" ESI ": Earth Simi la rit y Index (*100) ,
" pl an et Pr op er Na me " : " pr oper name of pla net " ,
" pla net Nam e ": " des ig nat ion of planet "
}
],
" dista nce " : value of distan c e to star ( pc ),
" stype ": " sp ectr al type of star " ,
" smass ": value of mass of star (M sun ),
" smetal " : value of metal li cit y of star ,
" Vmag ": value of v isual ma gni tude of star ,
" sradius ": value of radi u s of star (R sun ),
" eff ec ti ve T em p ": value of eff ecti ve t em per atu re of star (K ),
" st arP ro pe rN am e ": " proper name of the star " ,
" hasHP ": boole an ( has pot enti al h abi tabl e pl anets ) ,
" RA ": " Right asc ens ion ( J2000 ) ",
" DE ": " Decli na tio n ( J2000 ) "
},
For example, the record for 24 Sex looks like:
" 24 Sex ":
{
" exo pla net s ":
[
{
" mass ": 1.99 ,
" period " : 452.8 ,
" semiA xis " : 1.333 ,
" ecc en tri ci ty " : 0.09 ,
" ang le Di st a nc e ": 0.017821 ,
" dis cov ere d ": 2010 ,
" pla net Nam e ": "b "
},
{
" mass ": 0.86 ,
" period " : 883.0 ,
" semiA xis " : 2.08 ,
" ecc en tri ci ty " : 0.29 ,
" ang le Di st a nc e ": 0.027807 ,
" dis cov ere d ": 2010 ,
" pla net Nam e ": "c "
}
],
" dista nce " : 74.8 ,
" stype ": " G5 ",
" smass ": 1.54 ,
" smetal " : -0.03 ,
" Vmag ": 7.38 ,
" sradius ": 4.9 ,
" eff ec ti ve T em p ": 5098 ,
" RA ": "10 h2 3m28s " ,
" DE ": " -00 d54 m08s "
},
188 Chapter 14. Object Catalog Plugins
14.4 Pulsars Plugin
Figure 14.5: PSR J0332+5434
This plugin plots the position of various pulsars, with object information about each one. Pulsar data is
derived from “The Australia Telescope National Facility Pulsar Catalogue” (Manchester et al., 2005).
If enabled (see section 12.1), use the button to activate display of pulsars. The GUI allows a few
configuration options. You can also find a pulsar (
F3
) by its designation (e.g., PSR J0437-4715).
14.4.1 Section
[
Pulsars
]
in config.ini file
ID Type Description
last_update string Date and time of last update
update_frequency_days
int Frequency of updates [days]
updates_enable
bool Enable updates of pulsars catalog from Internet
url
string URL of pulsars catalog
enable_at_startup
bool Enable displaying of pulsars at startup of Stellarium
distribution_enabled
bool Enable distribution mode for the pulsars
flag_show_pulsars_button
bool Enable displaying pulsars button on toolbar
marker_color
R,G,B Color for marker of the pulsars
glitch_color
R,G,B Color for marker of the pulsars with glitches
use_separate_colors
bool Use separate colors for different types of the pulsars
14.4 Pulsars Plugin 189
14.4.2 Format of pulsars catalog
To add a new pulsar, open a new line after line 5 and paste the following, note commas and brackets, they are
important:
" Pulsar de sig nati on ":
{
" RA ": " Right ascensi on ( J2000 )" ,
" DE ": " Declinatio n ( J2000 )" ,
" notes ": " type of pulsar " ,
" distance " : value of d istance based on elec tron density
model ( kpc ) ,
" period ": value of ba ryc entr ic period of the pulsar ( s),
" parallax " : value of annual parallax ( mas ),
" bperiod " : value of binary period of pulsar ( days ) ,
" p der ivat ive ": value of time deri vat ive of barcyce ntri c
period ,
" dmeasure " : value of dispersion measure ( pc /( cm * cm *cm )) ,
" frequency " : value of b ary cent ric rotation fre quency ( Hz ),
" pfre quency ": value of time deri vat ive of barycentric
rota tion fr equency (1/( s *s ))
" e ccen tric ity ": value of eccentricity ,
" w50 ": value of profile width at 50% of peak ( ms ),
" s400 ": value of time averag ed flux d ensity at
400 MHz ( mJy ) ,
" s600 ": value of time averag ed flux d ensity at
600 MHz ( mJy ) ,
" s1400 ": value of time averag ed flux d ensity at
1400 MHz ( mJy )
},
For example, the record for PSR J0014+4746 looks like:
" PSR J0014 +4746 ":
{
" distance " : 1.82 ,
" dmeasure " : 30.85 ,
" frequency " : 0.805997 239145 ,
" pfre quency ": -3.6669 E -16 ,
" w50 ": 88.7 ,
" s400 ": 14 ,
" s600 ": 9 ,
" s1400 ": 3 ,
" RA ": " 00 h14m17 .75 s",
" DE ": " 47 d46m33 .4 s "
},
190 Chapter 14. Object Catalog Plugins
14.5 Quasars Plugin
The Quasars plugin provides visualization of some quasars brighter than 16 visual magnitude. The catalogue
of quasars has been compiled from “A catalogue of quasars and active nuclei: 13th edition” (Véron-Cetty
and Véron, 2010).
Figure 14.6: 3C 249.1, also known as LEDA 2821945 or 4C 77.09
If enabled (see section 12.1), use the button to activate display of quasars. The GUI allows a few
configuration options. You can also find a quasar (
F3
) by its designation (e.g., 3C 273).
14.5.1 Section
[
Quasars
]
in config.ini file
ID Type Description
last_update string Date and time of last update
update_frequency_days
int Frequency of updates, in days
updates_enable
bool Enable updates of quasars catalog from Internet
url
string URL of quasars catalog
enable_at_startup
bool Enable displaying of quasars at startup of Stellarium
distribution_enabled
bool Enable distribution mode for the quasars
flag_show_quasars_button
bool Enable displaying quasars button on toolbar
marker_color
R,G,B Color for marker of the quasars
14.5.2 Format of quasars catalog
To add a new quasar, open a new line after line 5 and create a new section. For example, the record for 3C
249.1 looks like (note commas and brackets – they are important!):
"3C 249.1 ": // Quasar de sign atio n
{
" RA ": " 11 h04m13 .8 s ", // Right ascension ( J2000 )
" DE ": " +76 d58m58s " , // Declina tio n ( J2000 )
" Amag ": -25.1 , // value of absol ute magnitude
" Vmag ": 15.72 , // value of visual ma gni tude
"z": 0.313 , // value of Z ( redshift )
" bV ": -0.02 // value of B -V colour
},
14.6 Meteor Showers Plugin 191
14.6 Meteor Showers Plugin
Figure 14.7: The 1833 Leonids replayed with the Meteor Showers plugin.
In contrast and extension of the random shooting stars feature of Stellarium (see section 19.6), this plugin
provides data for real meteor showers and a marker for each active and inactive radiant, showing real
information about its activity. If enabled (see section 12.1), just click on the Meteor Showers button on
the bottom toolbar to display markers for the radiants.
14.6.1 Terms
Meteor shower
A meteor shower is a celestial event in which a number of meteors are observed to radiate, or originate, from
one point in the night sky. These meteors are caused by streams of cosmic debris called meteoroids entering
Earth’s atmosphere at extremely high speeds on parallel trajectories. Most meteors are smaller than a grain of
sand, so almost all of them disintegrate and never hit the Earth’s surface. Intense or unusual meteor showers
are known as meteor outbursts and meteor storms, which may produce greater than 1,000 meteors an hour.
Radiant
The radiant or apparent radiant of a meteor shower is the point in the sky from which (to a planetary
observer) meteors appear to originate. The Perseids, for example, are meteors which appear to come from a
point within the constellation of Perseus.
An observer might see such a meteor anywhere in the sky but the direction of motion, when traced back,
will point to the radiant. A meteor that does not point back to the known radiant for a given shower is known
as a sporadic and is not considered part of that shower.
Many showers have a radiant point that changes position during the interval when it appears. For
example, the radiant point for the Delta Aurigids drifts by more than a degree per night.
Zenithal Hourly Rate (ZHR)
The Zenithal Hourly Rate (ZHR) of a meteor shower is the number of meteors a single observer would see in
one hour under a clear, dark sky (limiting apparent magnitude of 6.5) if the radiant of the shower were at the
zenith. The rate that can effectively be seen is nearly always lower and decreases the closer the radiant is to
the horizon.
Population index
The population index indicates the magnitude distribution of the meteor showers. Values below 2.5 correspond
to distributions where bright meteors are more frequent than average, while values above 3.0 mean that the
share of faint meteors is larger than usual.
192 Chapter 14. Object Catalog Plugins
Solar longitude
The solar longitude (equinox J2000) gives the position of the Earth on its orbit. It is a more appropriate
information on a meteor shower than the date.
14.6.2 Section
[
MeteorShowers
]
in config.ini file
You can edit
config.ini
file by yourself for changes of the settings for the Meteor Showers plugin – just
make it carefully!
ID Type Description
last_update string Date and time of last update
update_frequency_hours
int Frequency of updates, in hours
updates_enable
bool Enable updates of the meteor showers catalog from Internet
url
string URL of the meteor showers catalog
flag_show_ms_button
bool Enable showing button of the meteor showers on bottom bar
flag_show_radiants
bool Enable displaying markers for the radiants of the meteor showers
flag_active_radiants
bool
Flag for displaying markers for the radiants of the active meteor
showers only
enable_at_startup
bool Enable displaying meteor showers at startup plugin
show_radiants_labels
bool
Flag for displaying labels near markers of the radiants of the meteor
showers
font_size
int
Font size for label of markers of the radiants of the meteor showers
colorARG R,G,B Color for marker of active meteor showers with generic data
colorARR
R,G,B Color for marker of active meteor showers with real data
colorIR
R,G,B Color for marker of inactive meteor showers
14.6.3 Format of Meteor Showers catalog
To add a new meteor shower, you just need to:
1. Copy the code of some valid meteor shower;
2. Paste it in the line 6 (right after the “showers”: {) of the MeteorShowers.json document;
3. Replace the information according with your needs.
Note commas and brackets, they are very important!
" Three - le tter code " :
{
" des ign at ion ": " Name " ,
" IAUNo ": " IAU shower number " ,
" activ ity " :
[{
" year ": " ge neric " ,
" zhr ": Maxim um ZHR ( -1 if v aria ble ) ,
" varia ble " : " Minimum - maxi mum ( if va riab le ) ",
" start ": Solar long itu de at start ,
" finish " : Solar lon git ude at finish ,
" peak ": Solar l ongi tud e at peak ,
" distt ype " : Type of d is tri bu tio n f unct ion
(0= Gauss , 1= Lor entz ) ,
" b1 ": Slope of dist rib ut ion functi on
before peak ,
" b2 ": Slope of dist rib ut ion functi on
after peak
}] ,
" speed ": Ge oce ntr ic speed ( km /s) ,
" rad ia ntA lp ha " : Right A sce nsio n ( J2000 ) ( de gree ) ,
" rad ia ntD el ta " : Decli na tio n ( J2000 ) ( deg ree ) ,
" dri ftA lph a ": Radiant drift in Right Ascension ,
" dri ftD elt a ": Radiant drift in Decli nation ,
" colors " :
[{
" color ": " white " ,
" inte nsi ty " : 70
14.6 Meteor Showers Plugin 193
},
{
" color ": " bl ueG ree n ",
" inte nsi ty " : 30
}] ,
" pare ntO bj " : " Pa rent object " ,
" pidx ": popul ati on index
},
For example, below is a record for the Northern Taurids:
" NTA ":
{
" de s i g n a t ion ": " Nort h e rn Tauri d s " ,
" IAUNo ": " 17" ,
" activity " :
[{
" year ": " generi c " ,
" zhr ": 5 ,
" start ": 206 ,
" finis h ": 258 ,
" peak ": 230
}] ,
" speed ": 29 ,
" ra d i a n t A l p h a " : 58 ,
" ra d i a n t D e l t a " : 22 ,
" dr i f tAlpha ": 1.03 ,
" dr i f tDelta ": 0.26 ,
" color s ":
[{
" color ": " yellow " ,
" in tensity ": 80
},
{
" color ": " white " ,
" in tensity ": 20
}] ,
" pa rentObj ": " Come t 2 P /Enc ke " ,
" pidx ": 2.3
},
14.6.4 Notes
•
This plugin uses two models (P. Jenniskens, 1994) and (Peter Jenniskens et al., 1998) to calculate
ZHR, assuming that the activity profile of meteor shower follows a double exponential shape.
•
To predict the local hourly rate, altitude of radiant and limiting magnitude of the sky are taken into
account. Moonlight can also reduce the hourly rate, but is not taken into account.
•
Most of the numerical data for past meteor outbursts (Leonids, etc.) come from (P. Jenniskens, 2006).
There is a wide range of reported values for the maximum ZHR for the 1833 and 1966 Leonids
(P. Brown, 1999). We decided to use a maximum number of 150,000 to demonstrate meteor outbursts
with very high rate.
14.6.5 Further Information
You can get more info about meteor showers here:
•
Wikipedia about Meteor showers: https://en.wikipedia.org/wiki/Meteor_Showers
•
International Meteor Organization: https://www.imo.net/
•
IAU Meteor Data Center: https://www.ta3.sk/IAUC22DB/MDC2007/
Acknowledgements
This plugin was initially created as project of ESA Summer of Code in Space 2013
27
.
27
http://sophia.estec.esa.int/socis2013/?q=about
194 Chapter 14. Object Catalog Plugins
14.7 Navigational Stars Plugin
Figure 14.8: Navigational stars on the screen
This plugin marks navigational stars from a selected set (Figure 14.9):
Anglo-American
— the 57 “selected stars” that are listed in The Nautical Almanac
28
jointly published by
Her Majesty’s Nautical Almanac Office and the US Naval Observatory since 1958; consequently,
these stars are also used in navigational aids such as the 2102-D Star Finder
29
and Identifier.
French
— the 81 stars that are listed in the Ephémérides Nautiques published by the French Bureau des
Longitudes.
Russian — the 160 stars that are listed in the Russian Nautical Almanac.
German
— the 80 stars that are listed in the German Nautical Almanac (The original German title is
Nautisches Jahrbuch) published by the Federal Maritime and Hydrographic Agency of Germany.
If enabled (see section 12.1), just click on the Sextant button on the bottom toolbar to display markers
for the navigational stars. This can help you in training your skills in astronomical navigation before you
cruise the ocean in the traditional way, with your sextant and chronometer.
In the second tab (“Today”, see Figure 14.10) in the plugin’s dialog (right-click the button) you can see
times of sunrise and sunset, twilights, moonrise and moonset.
Civil Twilight
occurs when the zenith angle of the center of the Sun is less than
96
° (
6
° below the horizon)
and the available skylight is still typically sufficient for most civilian outdoor activities. The apparent
horizon is still clearly visible against the glowing sky and only the brightest stars are beginning to
show.
Nautical Twilight
occurs when the zenith angle of the center of the Sun is less than
102
° (
12
° below the
horizon) and the available skylight is no longer sufficient for detailed outdoor activities. However, the
outline of the apparent horizon, as well as most large topographical features, are still distinguishable
and the key stars used for navigational purposes have all typically become visible.
Astronomical Twilight
occurs when the zenith angle of the center of the Sun is less than
108
° (
18
° below
the horizon) and the available skylight is effectively imperceptible compared to moonlight and starlight.
Beyond this angle there is no longer any discernible atmospheric scattering of sunlight, so the time
after astronomical twilight is basically night.
28
The Nautical Almanac website – https://aa.usno.navy.mil/publications/docs/na.php
29
Rude Starfinder 2102-D description and usage instruction –
https://oceannavigation.blogspot.com/200
8/12/rude-starfinder-2102-d.html
14.7 Navigational Stars Plugin 195
Figure 14.9: Settings of the Navigational stars plugin
Figure 14.10: Today tab in the Navigational stars plugin
196 Chapter 14. Object Catalog Plugins
14.7.1 Section
[
NavigationalStars
]
in config.ini file
You can edit
config.ini
file by yourself for changes of the settings for the Navigational Stars plugin – just
make it carefully!
ID Type Description
navstars_color R,G,B Color of markers of navigational stars
enable_at_startup
bool Set to true to display navigational stars at startup of planetarium
use_utc_time
bool Set to true to use UTC time when navigational stars are displayed
extra_decimals
bool Set to true to show extra decimals in info
upper_limb
bool Set to true to use upper limb for Sun and Moon
tabulated_display
bool Set to true to show information as a tabulated list
limit_info_to_nav_stars
bool
Set to true to show extra information only for marked Navigation
Stars
highlight_when_visible
bool Set to true to highlight only visible stars
current_ns_set
string
Current set of navigational stars. Possible values: AngloAmerican,
French, Russian and German.
14.8 Satellites Plugin 197
14.8 Satellites Plugin
The Satellites plugin displays the positions of artificial satellites in Earth’s orbit based on a catalog of orbital
data. It allows automatic updates from online sources and manages a list of update file URLs.
To calculate satellite positions, the plugin uses an implementation of the SGP4/SDP4 algorithms (J.L.
Canales’ gsat library), using as its input data in NORAD’s two-line element set (TLE
30
) format. Lists with
TLEs for hundreds of satellites are available online and are regularly updated. The plugin downloads the lists
prepared by
https://celestrak.org
to keep itself up-to-date, but the users can specify other sources
online or load updates from local files.
Figure 14.11: Configuration of the Satellites plugin
If the plugin has been enabled (see section 12.1), just click on the Satellite button on the bottom toolbar
to display markers for the satellites, or use right click to call the GUI.
You can search for artificial satellites using the regular search dialog (
F3
). Note that at any given time,
most Satellites will be below the horizon.
Satellites can be either shown as white dots of appropriate brightness similar to moving stars (just like
they appear to the naked eye), or as satellite-shaped markers (icons). Especially this latter view shows
the huge number of satellites in orbit, most of which are invisible to the unaided eye. Satellites which are
v 25.4
reported to transit the penumbra (twilight) zone are rendered with a subdued color.
You can display circles representing the Earth’s shadow (penumbra and umbra, defined just like for Lunar
eclipses, see section 19.11.2), at the altitude of the currently selected satellite, or at a fixed (configurable)
altitude from Earth’s surface.
31
14.8.1 Satellite Properties
Name
Each satellite has a name. It’s displayed as a label of the satellite hint and in the list of satellites.
Names are not unique though, so they are used only for presentation purposes.
Catalog number
In the Satellite Catalog satellites are uniquely identified by their NORAD number, which
is encoded in TLEs.
I.D. (The International Designator)
In the Satellite Catalog satellites are also uniquely identified by their
International Designator also known as COSPAR ID, which is encoded in TLEs.
Standard magnitude
The standard magnitude may be an estimate based on the mean cross-sectional area
derived from its dimensions, or it may be a mean value derived from visual observations (see section
14.8.4).
RCS
The Radar Cross Section is a median value derived from the last several years of values in the Satellite
Situation Report. The units of the RCS are square meters (see section 14.8.4).
Perigee
The perigee is the nearest point respectively of a satellite’s direct orbit around the Earth. The unit
of perigee is kilometers.
30
TLE: https://en.wikipedia.org/wiki/Two-line_element_set
31
The height of the selected satellite is computed above the WGS84 ellipsoid, while the fixed (configurable) altitude
from Earth’s surface is computed over the sphere. You may note these circles will deviate slightly from each other when
displayed altitudes are equal.
198 Chapter 14. Object Catalog Plugins
Figure 14.12: Configuration of the Satellites plugin: satellite properties
Apogee
The apogee is the farthest point respectively of a satellite’s direct orbit around the Earth. The unit
of apogee is kilometers.
Period
The orbital period is simply how long an orbiting satellite takes to complete one orbit. The unit of
period is minutes.
Displayed
In the Satellite Catalog tab this property controls whether the selected satellite should be
displayed on the sky.
Orbit
In the Satellite Catalog tab this property controls whether the orbit of the selected satellite should be
displayed in the sky.
Do not update
In the Satellite Catalog tab this property marks satellites for which TLE should not be
updated.
Description The user-defined notes for the selected satellite.
Groups
A satellite can belong to one or more groups such as “amateur”, “geostationary” or “navigation”.
They have no other function but to help the user organize the satellite collection. Group names are
arbitrary strings defined in the Satellite Catalog for each satellite and are more similar to the concept
of tags than a hierarchical grouping. A satellite may also not belong to any group at all.
By convention, group names are in lowercase. The GUI translates some of the groups used in the
default catalog.
The group names also can be used as an additional filters for the satellites (see UI elements on the left
side).
TLE set
The raw TLE data of selected satellite. A two-line element set (TLE) is a data format encoding
a list of orbital elements of an Earth-orbiting object for a given point in time, the epoch. Using a
suitable prediction model, the state (position and velocity) at any point in the past or future can be
estimated to some accuracy.
Epoch of the TLE Human-readable epoch of current TLE set.
On the left side of this tab you may see tools for filtering the satellites. The upper part shows a drop-down
list with many predefined filters. Some filters are connected to user defined groups to quickly get a list of
satellites in some group, such as all satellites from group “navigation”. Some filters are connected to orbital
properties of satellites, e.g., selecting the filter “[LEO]” will show all low-orbital satellites.
You can display a list of satellites by specific selection of their properties, when the filter “[custom filter]”
has been selected (Fig. 14.13). The settings of this filter are available through the button
, which is located
at the right of the drop-down list.
You can edit communication data for individual satellites by pressing (Fig. 14.14), where “Descrip-
tion” and “Frequency” are required fields and field “Modulation” is optional. Some individual satellites and
their groups already have the communication data filled in the default catalog.
Abbreviations of some types of modulation:
14.8 Satellites Plugin 199
Figure 14.13: Configuration of the Satellites plugin: satellites custom filter
Figure 14.14: Configuration of the Satellites plugin: satellite communication data
APT Automatic Picture Transmission
LRPT Low Resolution Picture Transmission
HRPT High Resolution Picture Transmission
AHRPT Advanced High Resolution Picture Transmission
AX.25 Amateur Radio adaptation of X.25 packet protocol
CW Continuous Wave, Morse Code
AM Amplitude Modulation
FM Frequency Modulation
DUV Data Under Voice
FSK Frequency Shift Keying
GFSK Gaussian Frequency Shift Keying
GMSK Gaussian Minimum Shift Keying
AFSK Audio Frequency Shift Keying
ASK Amplitude-shift Keying
PSK Phase-shift Keying
BPSK Binary Phase-shift Keying
QPSK Quadrature Phase-shift Keying
OQPSK Offset Quadrature Phase-shift Keying
DPSK Differential Phase-shift Keying
BOC Binary Offset Carrier
MBOC Multiplexed Binary Offset Carrier
200 Chapter 14. Object Catalog Plugins
14.8.2 Satellite Catalog
The satellite catalog is stored on disk in JSON
32
format, in a file named
satellites.json
. A default copy
is embedded in the plug-in at compile time. A working copy is kept in the user data directory.
To add a new satellite, open a new line after line 5 and paste the following. Note the structure of commas
and brackets, they are important:
" NORAD num ber ":
{
" name ": " name of the sat e l l ite "
" de s c r i p t ion ": " description goes here ",
" comms ": [
{
" de s c r i p t ion ": " down l i nk 1 " ,
" fr equency ": 437.49 ,
" mo d u lation ": " AFSK 1200 bps "
},
{
" de s c r i p t ion ": " down l i nk 2 " ,
" fr equency ": 145 .825
}
],
" group s ": [ " gro up1 ", " group2 "] ,
" stdMa g ": 2.0 ,
" tle1 ": "1 123 45 U 9 0005 D 09 0 8 0.85236265 .000 0 0 0 14 00000 -0 20602 -4 0 5632 " ,
" tle2 ": "2 123 45 98. 2 700 5 3.2702 0 011918 71.17 76 289.070 5 14 . 3 1 8 1 8920 653 " ,
" visibl e " : true
},
Explanation of the fields:
NORAD number
required parameter, surrounded by double quotes (
"
), followed by a colon (
:
). It is used
internally to identify the satellite. You should replace the text
"NORAD number"
with the first number
on both lines of the TLE set (in this case, "12345"). It must match the number of the satellite in the
source you are adding from if you want the TLE to be automatically updated.
The remaining parameters should be listed between two curly brackets, and the closing curly bracket must be
followed by a comma to separate it from the next satellite in the list:
name
required parameter. It will be displayed on the screen and used when searching for the satellite with
the Find window. Use the description field for a more readable name if you like.
description
optional parameter, double quoted. Appears when you click on the satellite. The description
field can accept HTML tags such as <br/> (new line), <b>bold</b>, etc.
comms optional parameter, square bracketed list of curly bracketed communications information.
groups
optional parameter, comma separated list of double quoted group names contained in square brackets.
Used for grouping satellites in the drop down box on the config (see above)
tle1 required, line 1 of the TLE, must be contained in double quotes and begin with "1 "
tle2 required, line 2 of the TLE, must be contained in double quotes and begin with "2 "
visible
required parameter, set to true if you want to see it, this can be toggled from the configuration
window once the satellite is loaded.
stdMag optional parameter, containing standard magnitude of satellite.
rcs
optional parameter, containing the satellite’s Radar Cross Section. The units of the RCS are square
meters.
You can edit the tags for a satellite, modify the description and comms data, and even add new satellites.
14.8.3 Configuration
The plug-in’s configuration data is stored in Stellarium’s main configuration file.
14.8.4 The approximated visual magnitude
To calculate an approximated visual magnitude of satellites we use the radar cross section (RCS) data and
standard magnitudes from Mike McCants’ database (with permissions)
33
; the radar cross section (RCS) data
from CelesTrack database
34
; the standard magnitudes from database of the MMT-9 observatory (belongs to
32
https://www.json.org/
33
Mike McCants’ Satellite Tracking Web Pages — https://mmccants.org
34
Satellite Catalog (SATCAT) — https://celestrak.org/satcat/search.php
14.8 Satellites Plugin 201
Figure 14.15: Configuration of the Satellites plugin: sources for TLE data
Kazan Federal University) (Beskin et al., 2017; Karpov et al., 2016).
We use a spherical shape of satellite to calculate an approximated visual magnitude from RCS values.
For modelling Starlink visual magnitudes we use Anthony Mallama’s formula
35
(Mallama, 2020) and Mike
McCants’ formula
36
for other satellites.
14.8.5 Sources for TLE data
TLE sets have to be accessed online. Occasionally the source path changes, and configurations set up with
previous versions may no longer be available. Use the bottom right button in the Sources tab (Figure 14.15)
to restore the installation defaults.
Celestrak
37
used as default update source, it also has TLE lists beyond those included by default in Satellite
plug-in
TLE.info
38
Space Track
39
the definitive source, requires sign-up, operated by United States Department of Defense
35
http://www.satobs.org/seesat/Aug-2020/0079.html
36
https://mmccants.org/tles/mccdesc.html
37
https://celestrak.org/NORAD/elements/
38
https://www.tle.info/joomla/index.php
39
https://www.space-track.org/
202 Chapter 14. Object Catalog Plugins
14.9 ArchaeoLines Plugin
GEORG ZOTTI
Figure 14.16: Declination Lines provided by the ArchaeoLines plugin
14.9.1 Introduction
In the archaeoastronomical literature, several astronomically derived orientation schemes are prevalent.
Often prehistorical and historical buildings are described as having been built with a main axis pointing to a
sunrise on summer or winter solstice. There can hardly be a better tool than Scenery3D (see chapter 15) to
investigate a 3D model of such a building, and this plugin has been introduced in version 0.13.3 as a further
tool in the archaeoastronomer’s toolbox (Zotti, 2016b).
When activated (see section 12.1), you can find a a tool bar button (in the shape of a trilithon with
the sun shining through it). Press this, or
Ctrl
+
U
, to display the currently selected set of characteristical
diurnal arcs.
14.9.2 Characteristic Declinations
The ArchaeoLines plugin displays any combination of declination arcs
δ
most relevant to archaeo- or
ethnoastronomical studies. Of course, principles used in this context are derived from natural observations,
and many of these declinations are still important in everyday astronomy.
•
Declinations of equinoxes (i.e., the equator,
δ = 0) and the solstices (δ = ±ε)
•
Declinations of the crossquarter days (days between solstices and equinoxes,
δ(λ = ±45
○
))
•
Declinations of the Major Lunar Standstills (
δ = ±(ε + i))
•
Declinations of the Minor Lunar Standstills (
δ = ±(ε − i))
•
Declination of the Zenith passage (
δ = ϕ)
•
Declination of the Nadir passage (
δ = −ϕ)
•
Declination
δ of the currently selected object
•
Current declination
δ
À
of the sun
•
Current declination
δ
Á
of the moon
•
Current declination
δ
P
of a naked-eye planet
The principal relation between declinations
δ
, geographic latitude
ϕ
, and the rising azimuth
A
is
computed from
cosA = −
sin
δ
cosϕ
. (14.1)
This formula does not take into account local horizon elevation nor atmospheric refraction nor lunar
parallax correction. The effect applied to characteristic declinations is shown graphically for the present time
14.9 ArchaeoLines Plugin 203
0 10 20 30 40 50 60 70 80 90 100 110 120 130 140 150 160 170 180
0
5
10
15
20
25
30
35
40
45
50
55
60
65
70
75
0
5
10
15
20
25
30
35
40
45
50
55
60
65
70
75
Solstices, Equinoxes
Solar Crossquarters
Major Standstills
Minor Standstills
Zenith Passage
Nadir Passage
Rising Azimuths, Year 2000
Figure 14.17: Rising azimuths of a few important events for sun and moon, and zenith and nadir
passages depending on geographic latitudes (vertical axis).
(J2000.0) in figure 14.17. For example, in a latitude of 30°, an object which goes through the zenith rises
at azimuth 55°. Lunar major standstill risings occur at azimuths 56.7° and 123.5°, lunar minor standstill
risings at azimuths 69° and 111°. The summer solstice sun rises at 62.6°, the winter solstice sun at 117.3°.
An object which goes through the nadir rises at 125°.
The blue lines seem to vanish at
ϕ = 45
°: while there are still objects going through the zenith in higher
latitudes, they are circumpolar and do not cross the horizon.
For the lunar events, there are two lines each drawn by the plugin, for maximum and minimum distance
of the moon. The lunar extreme declinations are computed taking horizon parallax effects into account.
For technical reasons however, the derived declinations are then used to draw small circles of constant
declinations on the sphere, without taking the change of lunar horizontal parallax into account. Note that
therefore the observed declination of the moon at the major standstill can exceed the indicated limits if it is
high in the sky. The main purpose of this plugin is however to show an indication of the intersection of the
standstill lines with the horizon.
It may be very instructive to let the time run quite fast and observe the declination line of “current moon”
swinging between its north and south limits each month. These limits grow and shrink between the Major
and Minor Standstills in the course of 18.6 years.
The sun likewise swings between the solstices. Over centuries, the solstice declinations very slightly
move as well due to the slightly changing obliquity of the ecliptic.
14.9.3 Geographical Targets
Some religions, e.g., Islam or Bahai, adhere to a practice of observing a prayer direction towards a particular
location. Azimuth lines for two locations can be shown, these lines indicate the great circle direction towards
the locations which can be edited in the configuration window. Default locations are Mecca (Kaaba) and
Jerusalem. The azimuth
q
towards a location
T = (λ
T
,
ϕ
T
)
can be computed for an observer at
O = (λ
O
,
ϕ
O
)
based on spherical trigonometry on a spherical Earth (Abdali, 1997) as
q = arctan
sin(
λ
T
−
λ
O
)
cosϕ
O
tan
ϕ
T
− sin
ϕ
O
cos(
λ
T
−
λ
O
)
(14.2)
204 Chapter 14. Object Catalog Plugins
You can set geographical coordinates and a name label directly, or select locations from Stellarium’s location
list by pressing the
Pick...
button. You can search for locations in the list. When you click on a location, its
data are taken as target.
14.9.4 Custom Lines
In addition, lines can be shown which indicate arbitrary azimuths (great circles through the zenith), altitudes,
and declinations. Note that these azimuths are always counted from north, regardless of the azimuth setting
described in section 4.3.5. These lines can be marked with a custom label.
When some celestial object is selected, you can take over its current respective data and name by pressing
the button, however the lines are not linked to the selected objects, and changing angle values or time
will make labels invalid.
14.9.5 Configuration Options
The configuration dialog allows the selection of the lines which are of interest to you. In addition, you can
select the color of the lines by clicking on the color swatches.
Section
[
ArchaeoLines
]
in config.ini file
ID Type Default
enable_at_startup bool false
line_thickness
int 1
color_equinox float R,G,B 1.00,1.00,0.50
color_solstices float R,G,B 1.00,1.00,0.25
color_crossquarters float R,G,B 1.00,0.75,0.25
color_major_standstill float R,G,B 0.25,1.00,0.25
color_minor_standstill float R,G,B 0.20,0.75,0.20
color_zenith_passage float R,G,B 1.00,0.75,0.75
color_nadir_passage float R,G,B 1.00,0.75,0.75
color_selected_object float R,G,B 1.00,1.00,1.00
color_current_sun float R,G,B 1.00,1.00,0.75
color_current_moon float R,G,B 0.50,1.00,0.50
color_current_planet float R,G,B 0.25,0.80,1.00
color_geographic_location_1 float R,G,B 0.25,1.00,0.25
color_geographic_location_2 float R,G,B 0.25,0.25,1.00
color_custom_azimuth_1 float R,G,B 0.25,1.00,0.25
color_custom_azimuth_2 float R,G,B 0.25,0.50,0.75
color_custom_altitude_1 float R,G,B 0.25,1.00,0.25
color_custom_altitude_2 float R,G,B 0.25,0.50,0.75
color_custom_declination_1 float R,G,B 0.45,1.00,0.15
color_custom_declination_2 float R,G,B 0.45,0.50,0.65
show_equinox bool true
show_solstices
bool true
show_crossquarters
bool true
show_major_standstills
bool true
show_minor_standstills
bool true
show_zenith_passage
bool true
show_nadir_passage
bool true
show_selected_object
bool true
show_current_sun
bool true
show_current_moon
bool true
show_current_planet
string none
show_geographic_location_1 bool false
14.9 ArchaeoLines Plugin 205
show_geographic_location_2 bool false
geographic_location_1_longitude
double 39.826175
geographic_location_1_latitude
double 21.4276
geographic_location_1_label
string Mecca (Qibla)
geographic_location_2_longitude
double 35.235774
geographic_location_2_latitude
double 31.778087
geographic_location_2_label
string Jerusalem
show_custom_azimuth_1 bool false
show_custom_azimuth_2
bool false
custom_azimuth_1_angle
double 0.0
custom_azimuth_2_angle
double 0.0
custom_azimuth_1_label
string custAzi1
custom_azimuth_2_label
string custAzi2
show_custom_altitude_1
bool false
show_custom_altitude_2
bool false
custom_altitude_1_angle
double 0.0
custom_altitude_2_angle
double 0.0
custom_altitude_1_label
string custAlt1
custom_altitude_2_label
string custAlt2
show_custom_declination_1 bool false
show_custom_declination_2
bool false
custom_declination_1_angle
double 0.0
custom_declination_1_label
string custDec1
custom_declination_2_angle
double 0.0
custom_declination_2_label
string custDec2
14.9.6 Acknowledgements
If you are using this plugin in scientific publications, please cite Zotti (2016b).
15. Scenery3d – 3D Landscapes
GEORG ZOTTI AND FLORIAN SCHAUKOWITSCH
15.1 Introduction
Have you ever wished to be able to walk through Stonehenge or other ancient building structures described
as being constructed with astronomical orientation in mind, and experience such orientation in a 3D virtual
environment that also provides a good sky simulation?
The Stellarium Scenery3d plugin allows you to see architectural 3D models embedded in a landscape
combined with the excellent representation of the sky provided by Stellarium. You can walk around, check
for (or demonstrate) possible astronomical alignments of ancient architecture, see sundials and other shadow
casters in action, etc.
15.2 Usage
You activate the plugin with the circular enclosure button at screen bottom or by pressing
Ctrl
+
W
.
A right-click on that button (or
Ctrl
+
+
W
) opens the settings dialog. Once loaded and displaying,
you can walk around pressing
Ctrl
on PC or
Option
on Mac plus cursor keys. Change eye height with
Ctrl
+
Page
/
Ctrl
+
Page
keys on PC or
Option
+
Page
/
Option
+
Page
keys on Mac. Adding
key increases speed by 10, adding
Alt
on PC or
Command
on Mac multiplies by 5 (pressing both keys
multiplies by 50!). If you release
Ctrl
/
Option
before the cursor key, animation will continue. (Press
Ctrl
/
Option
+any cursor key to stop moving.)
Further key bindings exist which can be configured using the Stellarium default key-binding interface.
Some options are also available in the Scenery3d dialog. For example, coordinate display can be enabled
with
Ctrl
+
R
+
T
. If your models are georeferenced in a true geographical coordinate grid, e.g. UTM or
Gauss-Krueger, you will especially like this, and this makes the plugin usable for scientific purposes. Display
shows grid name, Easting, Northing, Altitude of ground, and eye height above ground.
Other features include a virtual “torchlight”, which can be enabled with
Ctrl
+
R
+
L
to give additional
local illumination around the viewer to help to see in the dark. Interesting points of view can be saved and
restored later by the user, including a description of the view. Scene authors can also distribute predefined
viewpoints in their scene.
The plugin also simulates the shadows of the scene’s objects cast by the Sun, Moon and even Venus (only
1 shadow caster used at a time, you will never see shadows cast by Venus in moonlight), so you could use it
for examining sundials, or analyze and simulate light-and-shadow interactions in archaeological structures.
Sometimes, light patches cast through small holes are important, e.g., in churches with meridiana
v 23.2
“sundial/calendar” lines. If these patches appear too dim, you can increase the power of the directional light
using the
Directional light enhancement
switch. (Use value 1.0 to revert to normal.)
208 Chapter 15. Scenery3d – 3D Landscapes
15.3 Hardware Requirements & Performance
In order to work with the non-linear projection models in Stellarium, this plugin uses a trick to create the
foreground renderings: it renders the scene into the six planes of a so-called cubemap, which is then correctly
reprojected onto the sides of a cube, depending on the current projection settings. Your graphics card must
be able to do this, i.e. it must support the OpenGL extension called
EXT_framebuffer_object
. Typical
modern 3D cards (by Nvidia or ATI/AMD) support this extension. In case your graphics hardware does not
support it, the plugin will still work, but you are limited to perspective projection.
You can influence rendering quality, but also speed, using the plugin’s GUI, which provides some options
such as enabling the use of shadows, bumpmapping (provides more realistic surface lighting) or configuring
the sizes of the textures used for the cubemap or shadowmaps. Larger values there improve the quality, but
require faster hardware and more video memory for smooth results.
Because the “cubemap trick” requires quite a large amount of performance (in essence, the scene has to
be rendered 6 times), there are some options available that try to reduce this burden. The first option is to
change the type of the “cubemap”. The most compatible setting is 6 textures, which seems to work best on
older integrated Intel GPUs. The recommended default is the second setting, Cubemap, which uses a more
modern OpenGL feature and generally works a bit faster than 6 textures on more modern graphics cards.
Finally, the Geometry shader option tries to render all 6 cube faces at once. This requires a more recent GPU
+ drivers (at least OpenGL 3.2 must be supported), the setting is disabled otherwise. Depending on your
hardware and the scene’s complexity, this method may give a speedup or may be slower, you must find this
out yourself.
Another option prevents re-rendering of the cubemap if nothing relevant has changed. You can define
the interval (in Stellarium’s simulation time) in which nothing is updated in the GUI. You can still rotate the
camera without causing a re-draw, giving a subjective performance that is close to Stellarium’s performance
without Scenery3d. When moving, the cubemap will be updated. You can enable another option that only
causes 1 or 2 sides of the cubemap to be updated while you move, giving a speedup but causing some parts of
the image to be outdated and discontinuous. The cubemap will be completed again when you stop moving.
Shadow rendering may also cause quite a performance impact. The Simple shadows option can speed
this up a lot, at the cost of shadow quality especially in larger scenes. Another performance/quality factor is
shadow filtering. The sharpest (and fastest) possible shadows are achieved with filtering Off, but depending
on shadowmap resolution and scene size the shadows may look quite “blocky”. Hardware shadow filtering
is usually very fast, but may not improve appearance a lot. Therefore, there are additional filter options
available, the High filter option is relatively expensive. Finally, the PCSS option allows to approximate the
increase of solar and lunar shadow penumbras relative to the distance from their shadow casters, i.e. shadows
are sharp near contact points, and more blurred further away. This again requires quite a bit of performance,
and only works if the shadow filter option is set to Low or High (without Hardware).
The configuration GUI shows tooltips for most of its settings, which can explain what a setting does. All
settings are saved automatically, and restored when you reopen Stellarium.
15.3.1 Performance notes
This plugin clearly runs better with proper 3D graphics cards. On reasonably good hardware (tested on a
notebook PC with Nvidia M960), models with over 10.000.000 triangles are working nicely with shadows
and bumpmaps, although your mileage may vary. On very small hardware like single-board computers
with native OpenGL ES2, models may be limited to 64k vertices (points). If display is too slow, switch to
perspective projection: all other projections require almost sixfold effort! Or try the “lazy” cubemap mode
and lazy updates of tiles, where the scene is only rendered in specific timesteps or when movement happens.
15.4 Model Configuration
The model format supported in Scenery3d is Wavefront .OBJ, which is pretty common for 3D models. You
can use several modeling programs to build your models. Software such as Blender, Maya, 3D Studio Max
etc. can export OBJ.
15.4.1 Exporting OBJ from Sketchup
A simple to use and cost-free modeling program is Sketchup, commonly used to create the 3D buildings
seen in Google Earth. It can be used to create georeferenced models. OBJ is not a native export format for
the standard version of Sketchup. If you are not willing to afford Sketchup Pro, you have to find another
way to export a textured OBJ model.
15.4 Model Configuration 209
Geometry Yes
Lights Yes
Clay No
Photomatched Yes
DefaultUVs No
Instanced No
Table 15.1: Kerkythea Export Settings
One good exporter is available in the Kerkythea renderer project
1
. You need SU2KT 3.17 or better, and
KT2OBJ 1.1.0 or better. Deselect any selection, then export your model to the Kerkythea XML format with
settings shown in 15.1. (Or, with selection enabled, make sure settings are No-Yes-Yes-No-Yes-No-No.)
You do not have to launch Kerkythea unless you want to create nice renderings of your model. Then, use the
KT2OBJ converter to create an OBJ. You can delete the XML after the conversion. Note that some texture
coordinates may not be exported correctly. The setting
Photomatched:Yes
seems now to have corrected
this issue, esp. with distorted/manually shifted textures.
Another free OBJ exporter has been made available by TIG:
OBJexporter.rb
2
. This is the only OBJ
exporter tested so far capable of handling large TIN landscapes (
> 450.000
triangles). As of version 2.6 it
seems to be the best OBJ exporter available for Sketchup.
This exporter swaps Y/Z coordinates, but you can add a key to the config file to correct swapped axes,
see below. Other exporters may also provide coordinates in any order of X, Y, Z – all those can be properly
configured.
Another quirk has to be fixed manually though: in the material description file (MTL), TIG’s exporter
writes both
d
and
Tr
lines with the same value. Actually,
Tr = 1.0− d
according to OBJ/MTL documentation,
so you should edit away one line, or else the later line overwrites the value given earlier. Moreover, given that
Tr=1 should actually specify fully transparent objects, such a line will make your object entirely invisible!
Another (almost) working alternative: ObjExporter.rb by author Honing. Here, export with settings
0xxx00
. This will not create a
TX...
folder but dump all textures in the same directory as the OBJ and
MTL files. Unfortunately, currently some material assignments seem to be bad.
15.4.2 Notes on OBJ file format limitations
The OBJ format supported is only a subset of the full OBJ format: Only (optionally textured) triangle meshes
are supported, i.e., only lines containing statements:
mtllib
,
usemtl
,
v
,
vn
,
vt
,
f
(with three elements
only!), g. Negative vertex numbers (i.e., a specification of relative positions) are not supported.
A further recommendation for correct illumination is that all vertices should have vertex normals.
Sketchup models exported with the Kerkythea or TIG plugins should have correct normals. If your model
does not provide them, default normals can be reconstructed from the triangle edges, resulting in a faceted
look.
If possible, the model should also be triangulated, but the current loader may also work with non-triangle
geometry. The correct use of objects (
o
) and groups (
g
) will improve performance: it is best if you pre-
combine all objects that use the same material into a single one. The loader will try to optimize it anyways if
this is not the case, but can do this only partly (to combine 2 objects with the same material into 1, it requires
them to follow