Stellarium 25.1 User Guide
Georg Zotti, Alexander Wolf (editors)
2025
Copyright © 2014-2025 Georg Zotti.
Copyright © 2011-2025 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 25.1-1, March 23, 2025
Contents
I
Basic Use
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Historical notes 3
1.2 Ver sion Numbers 5
1.3 Acknowledgements 6
1.4 Scientific use 6
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.4 Running Stellarium 9
2.4.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.2 macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.4.3 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5 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 17
3.5 Observing Lists (Bookmarks) 17
3.6 Custom Markers 18
3.7 Copy Information 18
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.3 The Configuration Window 22
4.3.1 The Main Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.3.2 The Information Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.3.3 The Extras Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.3.4 The Time Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.3.5 The Tools Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.3.6 The Scripts Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.3.7 The Plugins Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.4 The View Settings Window 28
4.4.1 The Sky Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.4.2 The Solar System Objects (SSO) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4.3 The Deep-Sky Objects (DSO) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4.4 The Markings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4.5 The Landscape Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4.6 The Sky Culture Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.4.7 The Surveys Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.5 The Search Window 38
4.5.1 The Object tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.5.2 The SIMBAD tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.5.3 The Position tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.5.4 The Lists tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.5.5 The Options tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.6 The Astronomical Calculations Window 41
4.6.1 The Positions Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.6.2 The Ephemeris Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.6.3 The “Risings, Transits, and Settings” (RTS) Tab . . . . . . . . . . . . . . . . . . . . . . . 44
4.6.4 The Phenomena Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.6.5 The Graphs Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.6.6 The “What’s Up Tonight” (WUT) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.6.7 The “Planetary Calculator” (PC) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.6.8 The Eclipses Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.6.9 The Almanac Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.7 The Help Window 55
4.7.1 The Help Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.7.2 The About Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.7.3 The Log Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.7.4 The Config Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.8 Editing Keyboard Shortcuts 57
4.8.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
II
Advanced Use
5 Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.1 Directories 61
5.1.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.1.2 macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.1.3 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.1.4 Customized Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.2 Directory Structure 62
5.3 The Logfile 63
5.4 The Main Configuration File 63
5.5 Getting Extra Data 64
5.5.1 More Stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.5.2 More Deep-Sky Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.5.3 Alternative Planet Ephemerides: DE430, DE431, DE440, DE441 . . . . . . . . 64
5.5.4 GPS Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.5.5 Modernized MESA3D libraries (Software OpenGL on Windows) . . . . . . . 67
6 Advanced Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.1 Command Line Options 69
6.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
6.2 Environment Variables 72
6.2.1 Logfile tweaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
6.3 GUI Customizations 72
6.3.1 Panel transparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.3.2 Button brightness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.3.3 Text shadow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.3.4 User interface colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.4 Spout 74
6.5 Spherical Mirror Mode for Planetarium Use 74
7 Landscapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.1 Stellarium Landscapes 77
7.1.1 Location information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.1.2 Polygonal landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
7.1.3 Spherical landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.1.4 High resolution (“Old Style”) landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
7.1.5 Fisheye landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
7.1.6 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.1.7 Gazetteer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.1.8 Packing and Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
7.2 Creating Panorama Photographs for Stellar ium 88
7.2.1 Panorama Photography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
7.2.2 Hugin Panorama Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.2.3 Regular creation of panoramas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.3 Panorama Postprocessing 93
7.3.1 The GIMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.3.2 ImageMagick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.3.3 Final Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
7.3.4 Artificial Panoramas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.3.5 Nightscape Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.4 Troubleshooting 99
7.5 Other recommended software 100
7.5.1 IrfanView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
7.5.2 FSPViewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
7.5.3 Clink and GNUWin32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
7.5.4 WSL – Windows Subsystem for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8 Deep-Sky Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
8.1 Stellarium DSO Catalog 101
8.1.1 Modifying catalog.dat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
8.1.2 Modifying names.dat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.1.3 Modifying textures.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.1.4 Modifying outlines.dat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.2 Adding Extra Nebula Images 107
8.2.1 Image requirements for inclusion in Stellarium . . . . . . . . . . . . . . . . . . . . . 108
8.2.2 Processing requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
8.2.3 Manual processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
8.2.4 Automated processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
8.2.5 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9 Adding Sky Cultures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.1 Text description 116
9.1.1 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.1.2 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.2 Technical data: index.json 118
9.2.1 Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.2.2 Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9.2.3 Constellation boundaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.2.4 Constellations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
9.2.5 Asterisms and help rays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9.2.6 Names of Stars, Planets and Nonstellar Objects . . . . . . . . . . . . . . . . . . . 126
9.2.7 Deep-Sky Objects Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
9.3 The Skyculture Converter 128
9.4 Publish Your Work 129
10 Surveys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
10.1 Introduction 131
10.2 Hipslist file and default surveys 131
10.3 Solar system HiPS survey 132
10.4 Digitized Sky Survey 2 (TOAST Survey) 132
10.4.1 Local Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
11 Stellarium’s Skylight Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
11.1 Introduction 135
11.2 The Skylight Models 135
11.2.1 Legacy Mode: The Preetham Skylight Model . . . . . . . . . . . . . . . . . . . . . 135
11.2.2 Advanced Mode: The ShowMySky Skylight Model . . . . . . . . . . . . . . . . . 136
11.3 Light Pollution 137
11.4 Tone Mapping 138
III
Extending Stellarium
12 Plugins: An Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
12.1 Enabling plugins 141
12.2 Data for plugins 141
13 Interface Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
13.1 Angle Measure Plugin 143
13.2 Equation of Time Plugin 145
13.2.1 Section
EquationOfTime
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . 145
13.3 Pointer Coordinates Plugin 146
13.3.1 Section
PointerCoordinates
in config.ini file . . . . . . . . . . . . . . . . . . . . . 146
13.4 Text User Interface Plugin 147
13.4.1 Using the Text User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
13.4.2 TUI Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
13.4.3 Section
tui
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
13.5 Remote Control Plugin 150
13.5.1 Using the plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
13.5.2 Remote Control Web Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
13.5.3 Remote Control API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
13.5.4 Developer information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
13.5.5 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
13.6 Remote Sync Plugin 154
13.6.1 Developer notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
13.6.2 Finetuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
13.7 OnlineQueries Plugin 157
13.7.1 Section
OnlineQueries
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . 157
13.8 Solar System Editor Plugin 158
13.9 Calendars Plugin 161
13.9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
13.9.2 The Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
13.9.3 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
13.9.4 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
13.9.5 Further development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
13.9.6 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
14 Object Catalog Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
14.1 Bright Novae Plugin 169
14.1.1 Section
Novae
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
14.1.2 Format of bright novae catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
14.1.3 Light curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
14.2 Historical Supernovae Plugin 171
14.2.1 List of supernovae in default catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
14.2.2 Light curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
14.2.3 Section
Supernovae
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
14.2.4 Format of historical supernovae catalog . . . . . . . . . . . . . . . . . . . . . . . . . 174
14.3 Exoplanets Plugin 175
14.3.1 Potential habitable exoplanets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
14.3.2 Proper names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
14.3.3 Section
Exoplanets
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
14.3.4 Format of exoplanets catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
14.4 Pulsars Plugin 190
14.4.1 Section
Pulsars
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
14.4.2 Format of pulsars catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
14.5 Quasars Plugin 192
14.5.1 Section
Quasars
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
14.5.2 Format of quasars catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
14.6 Meteor Showers Plugin 194
14.6.1 Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
14.6.2 Section
MeteorShowers
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . . . 195
14.6.3 Format of Meteor Showers catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
14.6.4 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
14.6.5 Further Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
14.7 Navigational Stars Plugin 198
14.7.1 Section
NavigationalStars
in config.ini file . . . . . . . . . . . . . . . . . . . . . . . 200
14.8 Satellites Plugin 201
14.8.1 Satellite Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
14.8.2 Satellite Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
14.8.3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
14.8.4 The approximated visual magnitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
14.8.5 Sources for TLE data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
14.9 ArchaeoLines Plugin 207
14.9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
14.9.2 Characteristic Declinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
14.9.3 Geographical Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
14.9.4 Custom Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
14.9.5 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
14.9.6 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
15 Scenery3d – 3D Landscapes . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
15.1 Introduction 211
15.2 Usage 211
15.3 Hardware Requirements & Performance 212
15.3.1 Performance notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
15.4 Model Configuration 213
15.4.1 Exporting OBJ from Sketchup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
15.4.2 Notes on OBJ file format limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
15.4.3 Configuring OBJ for Scenery3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
15.4.4 Concatenating OBJ files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
15.4.5 Beyond 3D: Temporally evolving Models . . . . . . . . . . . . . . . . . . . . . . . . . 219
15.4.6 Working with non-georeferenced OBJ files . . . . . . . . . . . . . . . . . . . . . . . 220
15.4.7 Rotating OBJs with recognized survey points . . . . . . . . . . . . . . . . . . . . . 221
15.5 Predefined views 221
15.6 Example 221
15.7 Limitations 222
16 Stellarium at the Telescope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
16.1 Oculars Plugin 225
16.1.1 Using the Ocular plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
16.1.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
16.1.3 Scaling the eyepiece view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
16.2 TelescopeControl Plugin 239
16.2.1 Abilities and limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
16.2.2 Using this plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
16.2.3 Main window (’Telescopes’) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
16.2.4 Telescope configuration window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
16.2.5 Supported devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
16.2.6 RTS2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
16.2.7 INDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
16.2.8 ASCOM 7 (Windows only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
16.2.9 StellariumScope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
16.2.10 Other telescope servers and Stellarium . . . . . . . . . . . . . . . . . . . . . . . . . . 246
16.3 Observability Plugin 249
17 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
17.1 Introduction 251
17.2 The Script Console 252
17.2.1 The Tabs in the Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
17.2.2 The Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
17.2.3 German Keyboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
17.3 Includes 252
17.4 Minimal Scripts 253
17.5 Critical Scripting Differences introduced with version 1.0 253
17.5.1 Pause/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
17.5.2 The Vec3f problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
17.6 Example: Retrograde motion of Mars 255
17.6.1 Script header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
17.6.2 A body of script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
17.7 More Examples 258
IV
Practical Astronomy
18 Astronomical Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
18.1 The Celestial Sphere 261
18.2 Coordinate Systems 262
18.2.1 Altitude/Azimuth Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
18.2.2 Right Ascension/Declination Coordinates . . . . . . . . . . . . . . . . . . . . . . . . 263
18.2.3 Fixed Equatorial Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
18.2.4 Ecliptical Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
18.2.5 Galactic Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
18.2.6 Planet Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
18.3 Distance 267
18.4 Time 268
18.4.1 Sidereal Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
18.4.2 Julian Day Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
18.4.3 Delta T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
18.5 Angles 273
18.5.1 Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
18.5.2 Handy Angles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
18.6 The Magnitude Scale 274
18.7 Luminosity 275
18.8 Precession 275
18.9 Parallax 277
18.9.1 Geocentric and Topocentric Observations . . . . . . . . . . . . . . . . . . . . . . . 277
18.9.2 Stellar Parallax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
18.10 Aberration of Light 278
18.11 Proper Motion 279
18.11.1 Binary Stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
19 Astronomical Phenomena . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
19.1 The Sun 281
19.1.1 Twilight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
19.2 Stars 282
19.2.1 Multiple Star Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
19.2.2 Constellations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
19.2.3 Star Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
19.2.4 Spectral Type & Luminosity Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
19.2.5 Variable Stars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
19.3 Our Moon 289
19.3.1 Phases of the Moon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
19.3.2 The Lunar Magnitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
19.4 The Major Planets 290
19.4.1 Terrestrial Planets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
19.4.2 Jovian Planets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
19.4.3 Apparent Magnitudes of the Planets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
19.5 The Minor Bodies 291
19.5.1 Asteroids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
19.5.2 Comets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
19.6 Meteoroids 292
19.7 Zodiacal Light and Gegenschein 293
19.8 The Milky Way 293
19.9 Nebulae 293
19.9.1 The Messier Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
19.9.2 The Caldwell catalogue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
19.10 Galaxies 294
19.11 Eclipses and Transits 295
19.11.1 Solar Eclipses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
19.11.2 Lunar Eclipses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
19.11.3 Transits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
19.11.4 Contact Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
19.12 Observing Hints 296
19.13 Atmospheric effects 298
19.13.1 Atmospheric Extinction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
19.13.2 Atmospheric Refraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
19.13.3 Light Pollution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
20 A Little Sky Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
20.1 Dubhe and Merak, The Pointers 303
20.2 M31, Messier 31, The Andromeda Galaxy 303
20.3 The Garnet Star,
µ Cephei 304
20.4 4 and 5 Lyrae,
ε Lyrae 304
20.5 M13, Hercules Cluster 304
20.6 M45, The Pleiades, The Seven Sisters 304
20.7 C41, The Hyades 305
20.8 Algol, The Demon Star, β Persei 305
20.9 Sirius, α Canis Majoris 305
20.10 M44, The Beehive, Praesepe 305
20.11 27 Cephei,
δ Cephei 305
20.12 Betelgeuse, α Orionis, 58 Orionis 306
20.13 M42, The Great Orion Nebula 306
20.14 La Superba, Y Canum Venaticorum, HIP 62223 306
20.15 52 and 53 Bootis, ν
1
and
ν
2
Bootis 307
20.16 Almach,
γ Andromedae 307
20.17 Algieba,
γ Leonis, 41 Leonis 307
20.18 Castor, α Geminorum 307
20.19 PZ Cas, HIP 117078 308
20.20 VV Cephei, HIP 108317 308
20.21 AH Scorpii, HIP 84071 308
20.22 Albireo,
β Cygni 308
20.23 31 and 32 Cygni, o
1
and o
2
Cygni 308
20.24 The Coathanger, Brocchi’s Cluster, Cr 399 309
20.25 Kemble’s Cascade 309
20.26 The Double Cluster, χ and h Persei, NGC 884 and NGC 869 309
20.27 Large Magellanic Cloud, PGC 17223 310
20.28 Tarantula Nebula, C 103, NGC 2070 310
20.29 Small Magellanic Cloud, NGC 292, PGC 3085 311
20.30
ω Centauri cluster, C 80, NGC 5139 311
20.31 47 Tucanae, C 106, NGC 104 311
20.32 The Coalsack Nebula, C 99 311
20.33 Mira, o Ceti, 68 Cet 312
20.34
α Persei Cluster, Cr 39, Mel 20 312
20.35 M7, The Ptolemy Cluster 313
20.36 M22, NGC 6656, The Great Sagittarius Cluster 313
20.37 M24, The Sagittarius Star Cloud 313
20.38 IC 4665, The Summer Beehive Cluster 313
20.39 The E Nebula, Barnard 142 and 143 313
21 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
21.1 Find M31 in Binoculars 315
21.1.1 Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
21.1.2 For Real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
21.2 Handy Angles 315
21.3 Find a Lunar Eclipse 316
21.4 Find a Solar Eclipse 316
21.5 Find a retrograde motion of Mars 316
21.6 Analemma 316
21.7 Transit of Venus 317
21.8 Transit of Mercury 317
21.9 Tr iple shadows on Jupiter 317
21.10 Jupiter without satellites 317
21.11 Mutual occultations of planets 317
21.12 The proper motion of stars 318
V
Appendices
A Default Hotkeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
A.1 Mouse actions with combina tion of the keyboard keys 321
A.2 Display Options 322
A.3 Miscellaneous 323
A.4 Movement and Selection 323
A.5 Date and Time 324
A.6 Scripts 324
A.7 Windows 325
A.8 Plugins 325
A.8.1 Angle Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
A.8.2 ArchaeoLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
A.8.3 Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
A.8.4 Equation of Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
A.8.5 Exoplanets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
A.8.6 Meteor Showers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
A.8.7 Oculars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
A.8.8 Pulsars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
A.8.9 Quasars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
A.8.10 Satellites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
A.8.11 Scenery3d: 3D landscapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
A.8.12 Solar System Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
A.8.13 Telescope Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
A.8.14 Text User Interface (TUI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
A.9 Special local keys 328
B The Bortle Scale of Light Pollution . . . . . . . . . . . . . . . . . . . . . . 329
B.1 Excellent dark sky site 329
B.2 Typical truly dark site 329
B.3 Rural sky 330
B.4 Rural/suburban transition 330
B.5 Suburban sky 331
B.6 Bright suburban sky 331
B.7 Suburban/urban transition 331
B.8 City sky 331
B.9 Inner-city sky 331
C Star Catalogues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
C.1 Stellarium’s Sky Model 333
C.1.1 Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
C.2 Star Catalogue File Format 333
C.2.1 General Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
C.2.2 File Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
C.2.3 Record Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
C.3 Variable Stars 339
C.3.1 Variable Star Catalog File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
C.3.2 GCVS Variability Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
C.4 Double Stars 351
C.4.1 Double Star Catalog File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
C.4.2 Designations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
C.5 Cross-Identification Data 364
C.5.1 Cross-Identification Catalog File Format . . . . . . . . . . . . . . . . . . . . . . . . . 364
C.6 Binary Star System Orbital Parameters 365
C.6.1 Binary Star System Orbital Parameters Catalog File Format . . . . . . . . . 365
D Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
D.1 Program Configuration 367
D.1.1
astro
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
D.1.2
astrocalc
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
D.1.3
audio
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
D.1.4
color
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
D.1.5
custom_selected_info
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
D.1.6
custom_time_correction
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
D.1.7
devel
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
D.1.8
dso_catalog_filters
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
D.1.9
dso_type_filters
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
D.1.10
fov
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
D.1.11
gui
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
D.1.12
init_location
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
D.1.13
landscape
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
D.1.14
localization
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
D.1.15
main
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
D.1.16
navigation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
D.1.17
plugins_load_at_startup
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
D.1.18
projection
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
D.1.19
proxy
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
D.1.20
scripts
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
D.1.21
search
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
D.1.22
spheric_mirror
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
D.1.23
stars
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
D.1.24
tui
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
D.1.25
video
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
D.1.26
viewing
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
D.1.27
DialogPositions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
D.1.28
DialogSizes
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
D.1.29
hips
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
D.2 Solar System Configuration Files 392
D.2.1 File ssystem_major.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
D.2.2 File ssystem_minor.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
D.2.3 JPL Horizons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
E Planetary nomenclature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
E.1 Format of nomenclature data file 404
E.2 Planetary Coordinate Systems 404
E.3 How names are approved by the IAU 405
E.4 IAU rules and conventions 407
E.5 Naming conventions 408
E.6 Descriptor terms (feature types) 409
E.6.1 Chart of landform types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
F Accuracy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
F.1 Date Range 415
F.2 Stellar Astrometry 416
F.3 Planetary Positions 416
F.4 Minor Bodies 416
F.5 Precession and Nutation 417
F.6 Planet Axes 417
F.7 Eclipses 417
F.8 The Calendar 418
F.9 Comparison to Reference Data 419
G GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . 425
G.1 PREAMBLE 425
G.2 APPLICABILITY AND DEFINITIONS 425
G.3 VERBATIM COPYING 427
G.4 COPYING IN QUANTITY 427
G.5 MODIFICATIONS 428
G.6 COMBINING DOCUMENTS 429
G.7 COLLECTIONS OF DOCUMENTS 430
G.8 AGGREGATION WITH INDEPENDENT WORKS 430
G.9 TRANSLATION 430
G.10 TERMINATION 431
G.11 FUTURE REVISIONS OF THIS LICENSE 431
G.12 RELICENSING 431
H Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
H.1 Contributors to this User Guide 433
H.2 Developers 434
H.2.1 Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
H.2.2 Former Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
H.2.3 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
H.3 How you can help 435
H.4 Technical Articles 436
H.5 Included Source Code 437
H.6 Data 437
H.7 Graphics 439
H.7.1 Full credits for “earthmap” texture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
H.7.2 License for the JPL planets images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
H.7.3 DSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
Foreword for Stellarium 25.1
Almost twenty-five years have elapsed since Fabien Chéreau typed the first lines of code of a
desktop planetarium which should be based on modern algorithms from computer graphics to
provide a trustworthy simulation of the night sky, utilizing OpenGL real-time graphics technology
which best runs on dedicated graphics hardware. The beautiful program that evolved since then
has been downloaded millions of times to run on desktop computers and notebooks all around
the planet, on various operating systems and in dozens of languages. The first team of developers
also developed ways to control Goto telescopes which became a popular feature. In the years to
come this was occasionally extended by further external contributors to provide support for INDI
and RTS2 on Linux and ASCOM on Windows, but keeping the systems working by occasionally
upgrading the protocols was left to the maintainers who may be limited in their access to instruments
or just have not even enough time to go observing themselves.
Only in late 2022 we were confident enough in the accuracy of our implementations of planetary
algorithms and various coordinate refinements that we have finally dropped the zero version number
and released version 1.0, and started using the year number as basis for later versions. On this
occasion we also moved forward to upgrading the foundational Qt GUI framework from Qt5 to
Qt6 to be prepared for upgrades in the next years. To keep compatibility with older PCs, we
kept providing builds based on the aging Qt5 framework. However it turned out that the new Qt6
framework and the widely used telescope control framework ASCOM 6 apparently don’t play
nicely together. We saw several reports about crashes coming in, but were not able to really solve
the issue, requiring us to finally disable support on Qt6-based builds. The builds on the older Qt5
framework seemed to always work nicely.
With only three core developers working part-time at best and otherwise busy in other projects
or daytime jobs, we cannot do giant leaps, but the program has evolved nicely in other areas like
the AstroCalc dialog that becomes richer in every version.
While many improvements had involved refinements for planetary positions and modelling of
observing conditions, other users were more interested in star positions over millennia. The star
catalog we have used since 2006, which was based on the then best positional measurements made
by ESA’s Hipparcos satellite, was discovered to have a systematic error that caused slightly wrong
coordinates millennia from the present. Also, binary stars could be observed to fly apart, because
their motions around each other were not modelled.
Just a few weeks before release 24.4 a new developer, Henry Leung, showed up and offered
a new star catalog for Stellarium. We needed a few weeks to test, check for inconsistencies and
finding how to best link this to our existing infrastructure, but days after 24.4 was out, we fully
embraced this new catalog, now a combination of ESA’s latest and best astrometry satellite Gaia’s
DR3 catalog with – still – the Hipparcos data, required for the brightest stars which were too
bright for Gaia to measure. Computers have become more powerful since 2006, and so this new
catalog comes with new features: While previously we just showed numerical data for parallax,
now you can observe the stars’ actual parallaxes as you move around the Sun! If needed in
demonstrations, you can exaggerate the effect. Proper motions are now modelled accurately, and
even stars’ distances change, so you can observe the brightness change of close stars like Barnard’s
as they pass our Solar system. And, what some may like best, binary stars with known orbits move
around each other while doing all this. So, fasten your seat belts and observe, for example, the
fast spatial motion of 61 Cygni, affected by annual parallax and aberration, and observe the two
components dancing around each other over centuries! Add a HiPS survey displayed behind the
stars, and see when the actual plates were taken so that the fast running stars fall in place. Observe
the combination of motions and you will get a higher appreciation for how difficult finding stellar
distances from positional measurements actually must have been for the pioneers in the field in the
19th century. Each star is now identified by its catalog number in Gaia DR3 as an added benefit.
If you need to run an older version of Stellarium and have downloaded the higher-level star
catalogs, these will still be available for running these older versions, but you will want to download
the new star catalogs as soon as possible.
We had actually planned for a different large development to begin in early 2025. Fabien’s
newer projects, Stellarium-web and Stellarium-mobile, are utilizing a more modern data format for
their skyculture descriptions: JSON. Also in our core team, we were convinced that the file formats
used so far are not flexible enough to model the many aspects of the rich astronomical heritage
of cultures found all over the world, and we had already collected ideas for years. In a scientific
symposium in Jena in late 2023 that was also supported by Stellarium’s donation fund we were able
to work out a few definitions and requirements of how Stellarium can help scientists collecting,
displaying and communicating all this. Starting with this version 25.1, we are therefore using a
completely new file format for the sky cultures which should be compatible with all programs
of the Stellarium family. Ruslan, who also optimizes the OpenGL rendering in countless little
improvements, did a great job converting all existing data, especially the translation into dozens
of existing languages, so that hopefully no vocabulary that was already translated was lost. See
chapter 9 for details about the new features as we use them now, and expect more features to come
in this area as we continue to work during this year.
Coming back to ASCOM, while testing with version 7 we could not trigger the bad crash that
was reported before, therefore we hope that re-enabling ASCOM in this release will work for our
users with actual instruments. Your feedback is important to find this out, and if you are familiar
with programming, we can need support in this part of the program.
We want to thank all sponsors and backers of the project as meanwhile we have collected
substantial funds to support development also in work hours. We like working on this project, but
also must pay the bills, so please keep up your kind support!
Work on other things has started, but they are scheduled for completion only in upcoming
versions. So, Stellarium is going strong as we approach the 25th anniversary of this project!
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 2025
I
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Historical notes
1.2 Ver sion Number s
1.3 Acknowledgements
1.4 Scientific use
1.5 About this User Guide
2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 System Requirements
2.2 Downloading
2.3 Installation
2.4 Running Stellarium
2.5 Troubleshooting
3 A First Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1 Time Travel
3.2 Moving Around the Sky
3.3 The Main Tool Bar
3.4 Taking Screenshots
3.5 Observing Lists (Bookmarks)
3.6 Custom Markers
3.7 Copy Information
4 The User Interface . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.1 Setting the Date and Time
4.2 Setting Your Location
4.3 The Configuration Window
4.4 The View Settings W indow
4.5 The Search Window
4.6 The Astronomical Calculations Window
4.7 The Help Window
4.8 Editing Keyboard Shortcuts
Basic Use
1. Introduction
Stellarium is a software project that allows people to use their home computer as a virtual plan-
etarium. 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 ob-
servational 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 OSX port
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 the French newsgroup
fr.sci.astronomie.amateur
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
4
https://groups.google.com/d/topic/fr.sci.astronomie.amateur/OT7K8yogRlI/disc
ussion
1.2 Version Numbers 5
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
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.
5
On Windows it has 4 components, where the last one is always 0.
6 Chapter 1. Introduction
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.
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
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
8 Chapter 2. Getting Started
• 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.
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-25.1-win64.exe for 64-bit Windows 7 and later.
• stellarium-25.1-win32.exe for 32-bit Windows 7 and later.
2. Follow the on-screen instructions.
Unattended Install/Uninstall
The installation program allows for unattended installation (e.g., for lab setups) following official
documentation
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 :\ Pr ogram Files [ ( x86 )]\ Stellarium \ u n i n s 000 . exe " / V E R Y S I L E N T / S UPPRESS M S G BO 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 - repos itory ppa : stellarium / stellarium - releases
sudo apt - get update
sudo apt - get install stellarium
3
HiDPI screens may work, but show occasional platform-dependent issues.
4
https://documentation.help/Inno-Setup/topic_setupcmdline.htm
2.4 Running Stellarium 9
You can also download and run universal binary packages for linux systems: flat
5
or snap
6
.
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.
2.4 Running Stellarium
2.4.1 Windows
The Stellarium installer creates a whole list of items in the Start Menu under the Programs/Stel-
larium 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.
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-m
ate-16-04/7094
9
Stellarium series 0.* and Qt5-based builds only
10 Chapter 2. Getting Started
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.5 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
1
See section 4.2 if you want to switch this off.
12 Chapter 3. A First Tour
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 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 Mac OS X. 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
3.2 Moving Around the Sky 13
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!).
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
14 Chapter 3. A First Tour
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
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.
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
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
Figure 3.2: Night scene with constellation artwork and moon.
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
B
Draw boundaries of the constella-
tions
1
Equatorial Grid
E
Draw grid lines for the equatorial co-
ordinate system of date (RA/Dec)
Azimuth Grid
Z
Draw grid lines for the horizontal co-
ordinate system (Alt/Azi)
Galactic Grid
Draw grid lines for the galactic coor-
dinate system (Long/Lat)
1
Equatorial J2000 Grid
Draw grid lines for the equatorial co-
ordinate system at standard epoch
J2000.0 (RA/Dec)
1
Ecliptic Grid
Draw grid lines for the ecliptic coor-
dinate system of date (Long/Lat)
1
16 Chapter 3. A First Tour
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
+
Q
Toggle degree marks along the hori-
zon.
Toggle Atmosphere
A
Toggle atmospheric effects. Most no-
tably makes the stars visible in the
daytime.
Deep-Sky Objects
D
Toggle marking the positions of
Deep-Sky Objects.
Planet Hints
P
Toggle indicators to show the posi-
tion of planets.
Nebula images
I
Toggle “nebula images”.
1
Digitized Sky Survey
Toggle “Digitized Sky Survey”
(TOAST).
1
Hierarchical Progressive
Surveys
Ctrl
+
Alt
+
D
Toggle “Hierarchical Progressive
Surveys”.
1
Coordinate System
Ctrl
+
M
Toggle between horizontal (Alt/Azi)
& equatorial (RA/Dec) coordinate
systems.
Center
Center the view on the selected ob-
ject
Night Mode
Ctrl
+
N
Toggle “night mode”, which applies
a red-only filter to the view to be eas-
ier on the dark-adapted eye.
Full Screen Mode
F11
Toggle full screen mode.
Bookmarks
Alt
+
B
Toggle bookmarks window.
1
Flip view (horizontal)
Ctrl
+
+
H
Flip the image in the horizontal
plane.
1
Flip view (vertical)
Ctrl
+
+
V
Flip the image in the vertical plane.
1
Quit Stellarium
Ctrl
+
Q
Close Stellarium.
Help Window
F1
Show the help window, with key
bindings and other useful informa-
tion
Configuration Window
F2
Show the configuration window
Search Window
F3
or
Ctrl
+
F
Show the object search window
3.4 Taking Screenshots 17
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
1
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
.
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).
18 Chapter 3. A First Tour
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.
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,
1
Unfortunately, on Windows 7 and later, with some Nvidia and AMD GPUs in OpenGL mode, these
tooltips sometimes do not work.
20 Chapter 4. The User Interface
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).
4.2 Setting Your Location
Figure 4.2: Location window
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
4.2 Setting Your Location 21
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
v 23.2
in the 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
22 Chapter 4. The User Interface
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
Figure 4.3: Configuration Window: Main Tab
The Main tab in the configuration window (Fig. 4.3) provides controls for changing separately
the program and sky culture languages.
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.
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
v 24.4
settings changes will be stored 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.
2
https://unstats.un.org/unsd/methodology/m49/
4.3 The Configuration Window 23
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
about a selected object.
• Ticking or unticking the relevant boxes will control this.
•
The information displays in various colors depending on the type and level of the stored data
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.
24 Chapter 4. The User Interface
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.
tabular output for coordinates and time uses a more eye-friendly layout.
Azimuth from South Some users may be used to counting azimuth from south.
Use decimal degrees You can toggle usage of decimal degree format for coordinates.
Designations for celestial coordinate systems Use symbols like
α,δ instead of textual labels.
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.
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.
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
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.
4.3 The Configuration Window 25
Figure 4.6: Configuration Window: Time Tab
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 sec-
tion 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.
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 behav-
ior 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
26 Chapter 4. The User Interface
Figure 4.7: Configuration Window: Tools Tab
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 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
4.3 The Configuration Window 27
of your CPU seems to be busy. You can try to distribute the computation of solar system bodies to
v 24.3
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 Scripts Tab
The Scripts tab (Fig. 4.8) 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
28 Chapter 4. The User Interface
Figure 4.8: Configuration Window: Scripts Tab
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.7 The Plugins Tab
Plugins (see chapter 12 for an introduction) can be enabled here (Fig. 4.9) 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.10) contains settings for changing the general appearance
of the main sky view and projections. Some highlights of sky field:
4.4 The View Settings Window 29
Figure 4.9: Configuration Window: Plugins Tab
Figure 4.10: View Settings Window: Sky Tab
30 Chapter 4. The User Interface
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 (
cd/m
2
,
mcd/m
2
,
µcd/m
2
) as well as astronomical,
mag/arcsec
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). 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 customize the on-screen labels we added 3 additional options
3
— 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.
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
3
These options are only used if the star does not have Bayer/Flamsted designations.
4.4 The View Settings Window 31
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 per-
spective 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
◦
.
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 OSBORN 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.
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 sec-
tion 11.2.2). It relies on a precomputed dataset that can be chosen in the user interface after
the ShowMySky model is enabled.
32 Chapter 4. The User Interface
4.4.2 The Solar System Objects (SSO) Tab
The Solar System Objects tab of the View window (Fig. 4.11) contains settings for changing the
general appearance of the view of Solar system objects. Some highlights:
Figure 4.11: 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.
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,
v 24.3
. . .), down to 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.8 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
4.4 The View Settings Window 33
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 items along the terminator (the border
v 1.2
between light and dark on the surface). You can also mark craters and lunar maria (the dark
v 23.3
“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 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 avail-
able from the literature. Data by Müller (1893) provide visual magnitudes. The other models
provide instrumental (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.12) 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.13) 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.14) 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.
34 Chapter 4. The User Interface
Figure 4.12: View Settings Window: DSO Tab
Figure 4.13: View Settings Window: Markings Tab
Figure 4.14: View Settings Window: Landscape Tab
4.4 The View Settings Window 35
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 config-
ured 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 bright-
ness value in the landscape.ini file.
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
4
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
If you want to explore humankind’s cultural history, you could also switch to the viewpoint of other
ancient or contemporary people. Constellations are defined as patterns in the sky 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 are 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.2 for details.
The Sky Culture tab of the View window (Fig. 4.16) controls which culture’s constellations
and bright star names will be used in the main display. Some cultures have constellation art (e.g.,
Western and 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.
Constellations name style
You can select whether you want to display abbreviated, original or
translated names.
4
https://stellarium.org/landscapes.html
36 Chapter 4. The User Interface
Figure 4.15: 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)
Figure 4.16: View Settings Window: Sky Culture Tab
Use native names for planets
If provided, show the planet names as used in this sky culture (also
shows modern planet name for reference).
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 boundaries
Activate display of constellation boundaries, like
B
. Currently,
boundaries have been defined only for “Modern” sky cultures.
Art in brightness. . .
Activate display of constellation art (if available), like or
R
. You can
also select the brightness here.
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
4.4 The View Settings Window 37
configure asterism line thickness as well.
Ray helpers
Activate display of special navigational lines which connect stars often from different
constellations (like the shortcut
Alt
+
R
), and you can configure thickness of those lines as
well.
Select single constellation/Isolated See section 4.4.6 for details.
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.16). 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
Figure 4.17: View Settings Window: Surveys Tab
The Surveys tab (Fig. 4.17) 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.
On the left side of the window we see the list of available surveys from the configured sources
(See section D.1.29 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).
38 Chapter 4. The User Interface
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
. . .
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.19:
4.5 The Search Window 39
Figure 4.18: The Search Window: Object
Figure 4.19: The Search Window: Object (Recent Searches)
Figure 4.20: The Search Window: SIMBAD
40 Chapter 4. The User Interface
Figure 4.21: The Search Window: Position
Figure 4.22: The Search Window: Lists
Figure 4.23: The Search Window: Options
4.6 The Astronomical Calculations Window 41
Mimas (SI)
Mago
Maia
Mars
. . .
4.5.2 The SIMBAD tab
The SIMBAD tab (Fig. 4.20) 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.21) provides a convenient way to enter a set of coordinates.
4.5.4 The Lists tab
The Lists tab (Fig. 4.22) 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.23) 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.
Most tabs allow exporting computed data to XLSX (Excel) files in addition to CSV files, and
graphs can be exported as PNG files.
42 Chapter 4. The User Interface
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.24). You may also export the list of positions into an
XLSX or CSV file.
Figure 4.24: 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.25) 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.25: 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.26).
4.6 The Astronomical Calculations Window 43
Figure 4.26: Astronomical Calculations (AstroCalc): Plot trace of planet
Figure 4.27: Astronomical Calculations (AstroCalc): Extra options for ephemeris
Figure 4.28: Astronomical Calculations (AstroCalc): Analemma on the Earth
44 Chapter 4. The User Interface
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 in the Extra options window (Fig. 4.27). 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.28
and 4.29), 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.30).
Note: The ephemeris is computed with the current settings for atmosphere, topocentric correc-
tion 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.
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.31).
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.32). 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.
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.33).
Optional graphs for the Sun (with lines for civil, nautical and astronomical twilight) and the
Moon (dashed) are also available.
4.6 The Astronomical Calculations Window 45
Figure 4.29: Astronomical Calculations (AstroCalc): Analemma on Mars
Figure 4.30: Astronomical Calculations (AstroCalc): Two asteroids nearby to one place
Figure 4.31: Astronomical Calculations (AstroCalc): Risings, transits, and settings of
selected celestial object
46 Chapter 4. The User Interface
Figure 4.32: Astronomical Calculations (AstroCalc): Phenomena
Figure 4.33: Astronomical Calculations (AstroCalc): Graphs / Altitude vs. Time
Figure 4.34: Astronomical Calculations (AstroCalc): Graphs / Azimuth vs. Time
4.6 The Astronomical Calculations Window 47
The “Azimuth vs. Time” Subta b
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.34).
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.35).
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.36). 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.
5
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.
The “Lunar Elongation” Subtab
This subtab (Fig. 4.37) 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
6
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
5
The idea for this tool has been obtained from SkytechX: http://www.skytechx.eu/
6
This tool has been partially ported from the KStars planetarium: https://edu.kde.org/kstars/
48 Chapter 4. The User Interface
Figure 4.35: Astronomical Calculations (AstroCalc): Graphs / Monthly Elevation
Figure 4.36: Astronomical Calculations (AstroCalc): Graphs
Figure 4.37: Astronomical Calculations (AstroCalc): Graphs / Lunar Elongation
4.6 The Astronomical Calculations Window 49
Figure 4.38: Astronomical Calculations (AstroCalc): What’s Up Tonight (WUT)
Figure 4.39: Astronomical Calculations (AstroCalc): Planetary Calculator (PC), Data Tab
Figure 4.40: Astronomical Calculations (AstroCalc): Planetary Calculator (PC), Graphs
Tab
50 Chapter 4. The User Interface
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.
The Graphs tab (Fig. 4.40) 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.)
The “All Solar Eclipses” Subtab
Figure 4.41: Astronomical Calculations (AstroCalc): Eclipses / All Solar Eclipses
This subtab (Fig. 4.41) 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.
4.6 The Astronomical Calculations Window 51
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.42. 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.42: Key to solar eclipse map
The “Local Solar Eclipses” Subtab
This subtab (Fig. 4.43) 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.
The “Lunar Eclipses” Subtab
This subtab (Fig. 4.44) 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:
52 Chapter 4. The User Interface
Figure 4.43: Astronomical Calculations (AstroCalc): Eclipses / Local Solar Eclipses
Figure 4.44: Astronomical Calculations (AstroCalc): Eclipses / Lunar Eclipses
4.6 The Astronomical Calculations Window 53
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
◦
).
The “Planetary Transits” Subtab
This subtab (Fig. 4.45) 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 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.
Figure 4.45: Astronomical Calculations (AstroCalc): Eclipses / Planetary Transits
4.6.9 The Almanac Tab
The Almanac tool has one subtab: “Specific Time”. v 25.1
The “Specific Time” Subta b
This subtab (Fig. 4.46) 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
Figure 4.46: Astronomical Calculations (AstroCalc): Almanac / Specific Time
4.7 The Help Window 55
4.7 The Help Window
4.7.1 The Help Tab
Figure 4.47: 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.48) 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.49) 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.50) 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).
56 Chapter 4. The User Interface
Figure 4.48: Help Window: About
Figure 4.49: Help Window: Logfile
Figure 4.50: Help Window: Config file
4.8 Editing Keyboard Shortcuts 57
4.8 Editing Keyboard Shortcuts
Figure 4.51: 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.51), 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
5 Files and Directories . . . . . . . . . . . . . . . . . . . . . . . 61
5.1 Directories
5.2 Directory Structure
5.3 The Logfile
5.4 The Main Configuration File
5.5 Getting Extra Data
6 Advanced Options . . . . . . . . . . . . . . . . . . . . . . . 69
6.1 Command Line Options
6.2 Environment Variables
6.3 GUI Customizations
6.4 Spout
6.5 Spherical Mirror Mode for Planetarium Use
7 Landscapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.1 Stellarium Landscapes
7.2 Creating Panorama Photographs for Stellarium
7.3 Panorama Postprocessing
7.4 Troubleshooting
7.5 Other recommended software
8 Deep-Sky Objects . . . . . . . . . . . . . . . . . . . . . . . 101
8.1 Stellarium DSO Catalog
8.2 Adding Extra Nebula Images
9 Adding Sky Cultures . . . . . . . . . . . . . . . . . . . . . 115
9.1 Text description
9.2 Technical data: index.json
9.3 The Skyculture Converter
9.4 Publish Your Work
10 Surveys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
10.1 Introduction
10.2 Hipslist file and default surveys
10.3 Solar system HiPS survey
10.4 Digitized Sky Survey 2 (TOAST Survey)
11 Stellarium’s Skylight Models . . . . . . . . . . . . . 135
11.1 Introduction
11.2 The Skylight Models
11.3 Light Pollution
11.4 Tone Mapping
Advanced Use
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 \
% USERPROFILE %\ Stellarium \
% HOMEDRIVE %\% HOMEPATH %\ Stellarium \
% HOME %\ Stel larium \
1
also called user data directory
2
The installation directory was referred to as the config root directory in previous versions of this guide
62 Chapter 5. Files and Directories
Stellarium ’s install ation directory
Thus, on a typical Windows Vista/7/10 system with user “Bob Dobbs”, the user directory
will be:
C :\ Users \ Bob Dobbs \ AppData \ Roaming \ Stellarium \
The user data directory is unfortunately hidden by default. To make it accessible in the Win-
dows 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
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., usually /usr/share/stellarium or /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.4 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.
3
This is a very confusing default setting and in fact a security risk: Consider you receive an email
with some file
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/Con
ceptual/CFBundles/Introduction/Introduction.html
5.3 The Logfile 63
skycultures/
contains constellations, common star names and constellation artwork for Stel-
larium’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 25.1, although the directory structure is in place – each set of
nebula textures has its own sub-directory in the nebulae directory.
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 25.1, 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
6
Color values can be edited interactively by the Text User Interface plugin (see 13.4).
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.
64 Chapter 5. Files and Directories
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
).
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.20; extended catalog-3.20.dat 8b25343a5983ef5841cbc0b60e96f4dc 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
:
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.20
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 65
Ephemeris Filename MD5 hash Size
DE430 linux_p1550p2650.430 707c4262533d52d59abaaaa5e69c5738 97.5 MB
DE431 lnxm13000p17000.431 fad0f432ae18 c330f9e14915fbf8960a 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 :/ Astrodata / JPL_DE43x / lin u x _p1550p2650 .430
de431_path = C :/ Astrodata / JPL_DE43x / lnx m 13000p17000 .431
de440_path = C :/ Astrodata / JPL_DE44x / lin u x _p1550p2650 .440
de441_path = C :/ Astrodata / JPL_DE44x / linux _ m 1 3000p17000 .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.
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.
GPSD (Linux, Mac OS X 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
di-
rectory. 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.
13
https://gpsd.gitlab.io/gpsd/index.html
66 Chapter 5. Files and Directories
•
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
# supporting GPSD
gps d_hostnam e = localhost
gp sd_port = 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 ://192.168.1.101:4352
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.
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
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 Windows primarily .
gps _interfac e = COM3
gps _baudrat e = 4800
14
Thanks to user Caysho for this hint.
15
On Linux, this may read /dev/ttyUSB0, /dev/gps0 or similar.
5.5 Getting Extra Data 67
From now on, always use the same USB plug configuration to connect GPS and telescope.
16
If GPS lookup fails, run Stellarium with the
–verbose
option and see the logfile for diagnostic
messages.
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
v 23.4
to be 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/pal
1000/mesa-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-pri
vacy-3a8eee0a-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 informa-
tion, and exit.
--config-file or -c config file name
Specify the configuration file name. The de-
fault 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
regular 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.
70 Chapter 6. Advanced Options
--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 file-
name 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 specified like
-l /home/user/stellarium.log
/home/user/stellarium.log
--restore-defaults [none]
Stellarium will start with the default configu-
ration. 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
1
You may have to escape the minute/second characters, like +53d58\’16.6\"
6.1 Command Line Options 71
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. De-
fault name: Stellarium.
2
--verbose
Even more diagnostic output in logfile (esp.
multimedia handling)
--dump-opengl-details or -d
[none]
Dump information about OpenGL support to
logfile. Use this is you have graphics prob-
lems and want to send a bug report.
--angle-mode or -a [none]
Use ANGLE as OpenGL ES2 rendering en-
gine (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 raster-
izer for ANGLE OpenGL ES2 rendering en-
gine.
2,4
--mesa-mode or -m
[none]
Use MESA as software OpenGL rendering
engine.
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
configurations.
--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
problems on Virtual Machines or special
builds).
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.
2
On Windows only
3
This function requires running in OpenGL mode.
4
Qt5-based Stellarium versions only
72 Chapter 6. Advanced Options
6.1.1 Examples
•
To start Stellarium using the configuration file
configuration_one.ini
situated in the
user directory (use either of these):
stellarium -- config - file = configuration_one . ini
stellarium -c configur a t i on_one . ini
• To list the available landscapes, and then start using the landscape with the ID “ocean”
stellarium -- list - landscapes
stellarium -- landscape = ocean
Note that console output (like
--list-landscapes
) may not be possible on some Windows
systems.
6.2 Environment Variables
Some command-line options can be set permanently by storing them into environment variables.
How to set them depends on the respective operating system. Calling the respective options on the
command line still overrides an environment variable (apart from STEL_OPTS).
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.
STEL_OPTS may contain a default commandline with options in the syntax of the table above.
STEL_USERDIR
may contain the path to a user data directory deviating from the default (see
section 5.1).
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
The amount of logging messages in Qt-based programs can be tuned by setting an environment vari-
able
QT_LOGGING_RULES
. For example, to remove all “Debug” messages, set it to
*.debug=false
.
To remove even the “Info” messages, add
;*.info=false
. (Combine several rules with semicola.)
If you experience operating trouble, make sure you allow all messages, i.e., set these entries shown
here to true (or delete the variable).
More information can be found online
5
.
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.
5
https://doc.qt.io/qt-6/qloggingcategory.html, https://doc.qt.io/qt-6/debug.html
6.3 GUI Customizations 73
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 ]
flag_use_window_transpar e n c y = 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 ]
pixmaps _ b r ightness =1.25
The value is clamped to [1. . . 1.8] to avoid making active and inactive buttons equally bright.
6.3.3 Text shadow
Some users complain the infotext is badly visible when there are trees or the Milky Way in the
background. This can also be mitigated in config.ini. v 24.4
[ gui ]
flag_ i nfo_shadow = true
6.3.4 User interface colors
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 m yOwnGreatSty l e
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
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
https://github.com/Stellarium/stellarium/blob/stellarium-stable/data/gui/nor
malStyle.css
and
https://github.com/Stellarium/stellarium/blob/stellarium-stable/
data/gui/normalHtml.css
74 Chapter 6. Advanced Options
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 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.25).
6.5 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.
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).
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.
7
https://spout.zeal.co/
8
https://domeclub.com/#PxComp
9
https://www.eplanetarium.com/projector_newtonian.php
10
https://myplanetarium.com/projection-dome-system
11
https://docs.worldwidetelescope.org/diy-planetarium-dome/1/dome/#setting-up-t
he-projector-and-mirrors
6.5 Spherical Mirror Mode for Planetarium Use 75
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!
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).
System Configuration
To minimise image distortion at the back of the dome, it’s worth carrying out the slightly complex
Meshmapper 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.
Stellarium Configuration
To enable planetarium spherical mirror projection, the
config.ini
file needs to include the
following:
[ navigation ]
init_fov = 180
[ projection ]
type = P rojectionFisheye
auto_zoom_out_rese t s _ d i r ec tion = true
[ video ]
fullscreen = true
view p ort_effect = sp h e r i c M i r r o r D i s t o rter
scr een_numbe r = 1
[ s pheric_mir ror ]
distor t e r_max_fov = 180
dome_radi us = 5.0 ( note : regardless of your actual dome radius )
image_distance_div_height = 2.67
mirror _ p osition_x = 0
mirror _ p osition_y = 5
mirror _ p osition_z = 0
mir ror_radiu s = 0.37 ( regardless of your actual mirror radius )
12
https://paulbourke.net/dome/meshmapper
13
https://domeclub.com/images/Meshmapper-1152w.jpg
76 Chapter 6. Advanced Options
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 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 ]
flag_fo r c e d _ t winkle = true
[ astro ]
flag_forced_meteor_activity = true
Another useful configuration for planetariums is to completely hide the vertical and horizontal
toolbars on the dome:
[ gui ]
fla g_show_gu i = false
The following are also recommended (adjust the values to your preference):
[ viewing ]
flag_ m oon_scaled = true
moon_scale = 8.00
[ astro ]
meteor_zhr = 3000
[ landscape ]
flag_fog = false
[ stars ]
abso lute_scale = 6.00
flag_s t a r_twinkle = 1.00
flag _ star_spiky = false
rela tive_scale = 0.70
star_tw i n k l e _ amount = 0.50
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 process-
ing. 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 ]
cac he_size_m b = 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).
78 Chapter 7. Landscapes
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 land-
scape 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).
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
country = Austria
name = KGA Rosenburg
latitude = +48 d38 ’3.3"
lo ngitude = +15 d38 ’2.8 "
altitude = 266
timezone = Europe / Vienna
ligh t _pollution = 1
atmospheric_e x t i n c tion_coefficient = 0.2
display_f og = 0
atmospheric_temperature = 10.0
atmospheri c _ p r e s s u re = 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 Green-
wich 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
7.1 Stellarium Landscapes 79
defaults.
light_pollution
(optional) Light pollution of the site, given on the Bortle Scale (1: none . .. 9:
metropolitan; see Appendix B). If negative or absent, no change will be made.
atmospheric_extinction_coefficient
(optional, no change if absent.) Extinction coefficient
(mag/airmass) 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.
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
polygonal_angle_rotatez = 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 = polygonal
author = Georg Zotti ; Horizon definition by Patrick Chevalley
descripti on = Horizon line of Geneve .
Dem onstrate s com patibilit y with
horizon descri ptions from Cartes du Ciel .
polygonal_horizon_list = h orizon_Gene v e . txt
polygonal_angle_rotatez = 0
gro und_colo r = .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.
1
SkyChart / Cartes du Ciel planetarium: https://www.ap-i.net/skychart/en/start
80 Chapter 7. Landscapes
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 global setting, config.ini:landscape/polygon_color.v 24.4
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.
A data download option provides users inclined to do some programming with the necessary
data to create a polygonal landscape for Stellarium. From this, BRIAN DOYLE has created another
online service, horiZONE
3
, which does just this work for you.
1.
When your viewshed analysis has been created in HeyWhatsThat, enter the “all panoramas”
tab, and on the map click the marker associated with the panorama. Select “make public”.
2.
Then, take the landscape key given to you by HeyWhatsThat
4
, add a few lines of description
and other details that will become visible and used in Stellarium, and you receive a ZIP file
ready for installation in Stellarium (see section 4.4.5).
A similar web service, PeakFinder
5
, meanwhile also allows downloading the horizon polygon
as installable landscape for Stellarium. A great feature of this service is the excellent gazetteer
(peak identification) also visible on the website.
2
https://www.heywhatsthat.com/
3
https://briandoylegit.github.io/horiZONE/
4
in the line https://www.heywhatsthat.com/?view=N15ABXY
5
https://www.peakfinder.com
7.1 Stellarium Landscapes 81
7.1.3 Spherical landsca pe
This method uses a more usual type of panorama – the kind which is produced directly from
software such as autostitch or Hugin
6
. 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 = spherical
maptex = apollo17 . png
A more elaborate example is found with the Grossmugl landscape:
[ landscape ]
name = Grossmugl
type = spherical
author = Guenther Wuchterl , Kuffner - Sternwarte . at ;
Lightscape : Georg Zotti
descripti on = Field near Leeberg , Grossmugl ( Ri esentumul us ) ,
Austria - Primary Observing Spot of the Grossmugl
St arlight Oasis - http :// star l ightoasis . org
maptex = gr o s s m u g l _ l e e b e r g _ c r o p 1 1 .25. png
maptex_top =11.25
maptex_fog = grossmugl_leeberg_fo g _ c r o p 2 2 .5. png
mapt ex_fog_top = 22.5
maptex _ f og_bottom = -22.5
map tex_illu m = grossmug l _ l e e b e r g_ illum_crop0 .png
maptex_ i l l u m _ bottom = 0
ang le_rotate z = -89.1
minimal _ b r ightness = 0.0075
polygonal_horizon_list = h o r i zon_grossmugl . txt
polygonal_angle_rotatez =0
minim a l_altitude = -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.
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.
6
http://hugin.sourceforge.net/
82 Chapter 7. Landscapes
maptex_illum
(optional; default: no illumination layer) is the name of the nocturnal illumina-
tion/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.
Likewise,
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
7
:
[ landscape ]
name = KGA Rosenburg
7
the groundtex grassground.png mentioned here has been taken from the Guereins landscape.
7.1 Stellarium Landscapes 83
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.
author = Georg Zotti , VIAS / ASTROSIM
descripti on = KGA Rosenburg
type = old_style
nb sidetex = 8
tex0 = Horiz -0. png
tex1 = Horiz -1. png
tex2 = Horiz -2. png
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
gr oundtex = grassground .png
ground = groundtex :0:0:1:1
nb_d e cor_repeat = 1
deco r _alt_angle = 82
decor_ a n gle_shift = -62
; Rotatez deviates from -90 by the Meridian Convergen ce .
; The original landscape pano is grid - aligned ,
84 Chapter 7. Landscapes
; not north - aligned !
decor_a n g l e _ r otatez = -90.525837223
ground_ a n g le_shift = -62
ground_ang l e _ r o t a t ez = 44.47 4162777
draw_g r o und_first = 1
fogtex = fog . png
fog _alt_angl e = 20
fog_ a ngle_shift = -3
fog = fogtex :0:0:1:1
calibrated = true
[ location ]
planet = Earth
latitude = +48 d38 ’3.3"
lo ngitude = +15 d38 ’2.8 "
altitude = 266
ligh t _pollution = 1
atmospheric_e x t i n c tion_coefficient = 0.2
display_f og = 0
atmospheric_temperature = 10.0
atmospheri c _ p r e s s u re = 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.
8
Note that for this landscape, accurate overlay of fog and landscape is only
guaranteed if calibrated=true and tan_mode=true.
8
In very wide-angle views, the fog cylinder may become visible in the corners.
7.1 Stellarium Landscapes 85
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
9
the ground is drawn in front of the scenery, i.e. the side textures
will 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):
9
Boolean values true|false preferred since V0.19.3, but 0|1 are still accepted.
86 Chapter 7. Landscapes
Figure 7.2: Texture for the Trees Fisheye landscape.
[ landscape ]
name = Trees
type = fisheye
author = Robert Spearman . Light pollution image : Georg Zotti
descripti on = Trees in Greenlak e Park , Seattle
maptex = trees_512 . png
map tex_illu m = trees_i l lum_512 .png
maptex_fog = tre es_fog_51 2 . png
texturefov = 210
ang le_rotate z = 17
tess elate_rows = 28
tess elate_cols = 60
Where:
name appears in the landscape tab of the configuration window.
7.1 Stellarium Landscapes 87
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.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.
# demo g a z e t t e e r for Grossmugl lan d s c a p e .
# Can be used to b etter describe the landsca pe ,
# i .e . show lab els on landscape feat u r e s .
# Fields must be separated by vertical line ,
# labe l must not have such a ve r t i c a l line .
# C o m ments have t his hash mark in first colum n .
# c o o r di n a t es in deg r e es from true Nor th .
# line t o wards z enith draws a singl e line strictly upward .
# labe l is c e n tered on line e n d point .
# A zimuth | Altitude | de grees | az imuth | label
# | | t owards zenith | shi ft |
11 3.66 | 5.5 | 4 | -6 | Leeb e r g
35 | 1.5 | 2.5 | 0 | Grossmugl
335 | 2 | 2 | 0 | Steinab r u n n
305 | 2 | 1 | 0 | Ringendorf
88 Chapter 7. Landscapes
180 | 2 | 2 | 0 | Vie nna (30 km )
135 | 2 | 0.5 | 0 | Wind power plant S t r a s s h o f
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 as-
tronomers 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
10
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 photographer 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
10
In many references you will find “Nodal Point” mentioned here. But see these:
https://en.w
ikipedia.org/wiki/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/NoParallaxPoint/TheoryOfTheNoParallaxPoint.pdf
7.2 Creating Panorama Photogra phs for Stellarium 89
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/File:Rodeon_vr_head_01.jpg)
90 Chapter 7. Landscapes
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.
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
11
, 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
12
, . . .) 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
13
. Then press
Create control points
.
11
http://hugin.sourceforge.net/
12
contrary to Stellarium, field of view (FoV) in Hugin means the horizontal extent in degrees.
13
If you forget this, you can remove cloud points by calling Celeste in the control point editor later
7.2 Creating Panorama Photogra phs for Stellarium 91
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 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/Geometric area.
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
14
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.
14
You should have created control points with the Celeste option!
92 Chapter 7. Landscapes
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 automat-
ically 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 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. . .
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.
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
7.3 Panorama Postprocessing 93
supervised in the preview window. Usually the smooth blending in the subprogam enblend called
by Hugin will hide remaining differences.
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 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.
94 Chapter 7. Landscapes
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)
15
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
16
. 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 improve-
ment, and WSL (7.5.4) for experts.
15
https://www.imagemagick.org/
16
These may typically be .BAT files on Windows, or various shell scripts on Linux or Mac.
7.3 Panorama Postprocessing 95
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.
17
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.
convert landscape . png - crop 4096 x1152 +0+896
- resize 4096 x1024 ! landscape _ c r opped . 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:
convert landscape . png - gravity SouthWest - crop 4096 x1152 +0+0
- resize 4096 x1024 ! landscape _ c r opped . 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.
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:
convert PANO . png - crop 16384 xHEIGHT + X_LEFT + Y_TOP + repage
- resize 16384 x2048 !
- type Tru eColorMatte - depth 8
- crop 2048 x2048 + repage
png : STELLARIUM_LANDSCAPEPATH / LAN DSCAPE_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,
17
Most modern graphics cards no longer require the “powers of two” image sizes, but we keep this practice
to increase compatibility.
96 Chapter 7. Landscapes
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.
# hugin project file
# h u gin_ptoversio n 2
p f0 w2048 h2048 v92 E0 R0 n" TIFF_m c : LZW r : CROP "
m g1 i0 f0 m2 p0 .00784314
# image lines
# - hugin cropFactor =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" Eqirect_Pano3 6 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.
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
convert ground . png - depth 8 groun d_8bit . png
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.
7.3 Panorama Postprocessing 97
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.
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.
98 Chapter 7. Landscapes
Basic rules to observe (use obvious inverses).
•
If image aligns well in azimuth but overshoots the grid to the right: Increase yaw accord-
ingly (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
I have created a website
18
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
19
.
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). To get rid of
the image decorations (compass etc), apply masks
20
. 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
18
https://homepage.univie.ac.at/Georg.Zotti/php/panoCam.php
19
Note that if you work with Google Earth Pro, you can create different FoV!
20
There is a wide overlap in the images to allow generous trimming.
7.4 Troubleshooting 99
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!)
•
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).
100 Chapter 7. Landscapes
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
21
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.
Im ageName = Horizon_ R o senburg . jpg
WindowTit le = Horizon_Rose n b u rg
hFov =70
# Formula : HP =100*( h /2 - upper )/( lower - upper ) in Hugin crop , or
# HP =100* zeroRow / imgHeight
Hori z onPosition =33.8
Figure 7.7: FSP configuration file (example)
7.5.3 Clink and GNUWin32
Clink
22
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.
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
23
, you can even run graphic applications like Stellarium, and all the
command-line tools are available.
21
Further details are available on its home page http://www.fsoft.it/FSPViewer/.
22
http://mridgers.github.io/clink/
23
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
.../nebulae/default/names.dat
file (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
.../nebulae/default/textures.json file. 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
.../nebulae/default/outlines.dat file. 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 ]
convert _ d s o _ c atalog = true
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.
102 Chapter 8. Deep-Sky Objects
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
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, 2014)
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)
3
Abell Catalog of Planetary Nebulae was added in v0.18.2 and removed in v0.20.1
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/
8.1 Stellarium DSO Catalog 103
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
.
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 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)
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/steinic
ke/index_e.htm
104 Chapter 8. Deep-Sky Objects
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
Nebulae)
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)
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
8.1 Stellarium DSO Catalog 105
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.
Too many names?
Over the years, a large collection of names from many references has been added. DSO names
v 25.1
are not 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 ]
nebula_exclude_references = default : ADI , DSC - HT
Here,
default
names the nebula set, and the comma-separated entries are references you want
excluded from nebulae/default/names.dat.
106 Chapter 8. Deep-Sky Objects
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.
{
" ima g e C r e d it s " : { " short " : " < a uthor name >" ,
" infoU r l " : " http :// < mys ite . org >"
},
" imageUrl " : " < myPho t o .png > " ,
" world C o o r d s " : [[[ X0 , Y0 ] , [ X1 , Y1 ], [ X2 , Y2 ] , [ X3 , Y3 ] ]] ,
" te x t u r e Co or ds " : [[[ 0 ,0] ,[1 ,0] ,[1 ,1] ,[0 ,1]]] ,
" mi n R e s o lu ti on " : 0.21 4 8810463 ,
" ma x B r i g ht ne ss " : <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.
8.2 Adding Extra Nebula Images 107
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.56401 -05.49880 start M 42
05.56759 -05.39201 vertex
05.56635 -05.31749 vertex
05.57158 -05.21922 vertex
05.57601 -05.21716 vertex
05.58830 -05.30164 vertex
05.59140 -05.34341 vertex
05.59028 -05.37076 vertex
05.59008 -05.38175 vertex
05.59581 -05.37159 vertex
05.59943 -05.47123 vertex
05.59912 -05.65838 vertex
05.59520 -05.73212 vertex
05.58490 -05.68102 vertex
05.56948 -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
GLENN NEWELL
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
108 Chapter 8. Deep-Sky Objects
Figure 8.1: Screen shot of nebula images displayed in Stellarium
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.
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
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
8.2 Adding Extra Nebula Images 109
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. 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 astroqu ery
• 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, Text Wrangler on Mac
OS), 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.astromet ry.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.
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
15
https://www.anaconda.com/distribution/
16
https://github.com/Stellarium/stellarium-data/tree/master/adding-nebula-image
s
110 Chapter 8. Deep-Sky Objects
•
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:
Figure 8.2: Online plate solving
Plate Solve
• Plate solve your image @ nova.astrometry.net (Fig. 8.2)
• 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”
background 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
8.2 Adding Extra Nebula Images 111
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.
• 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)
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
112 Chapter 8. Deep-Sky Objects
→
Figure 8.4: Reduce gamma to temporarily help the plate solving algorithm finding stars.
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 automate 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
Stellarium_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.
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
17
An online service available at https://jsonlint.com/
8.2 Adding Extra Nebula Images 113
→
Figure 8.6: Automatic processing of a DSO image.
Figure 8.7: .json result from processing with Stellarium_Nebulae_Image_Prep.py
• White space (a tab in this case) before http in infoUrl entries
These minor issues seem however not to irritate Stellarium.
9. Adding Sky Cultures
GEORG ZOTTI, WITH ADDITIONS BY ALEXANDER WOLF AND SUSANNE
M. HOFFMANN
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
v 25.1
the old format, please refer to the 24.4 edition of the User Guide. In case you have created your
own skycultures, we have created a format converter described in section 9.3.
If you add a new 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.
• 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.
116 Chapter 9. Adding Sky Cultures
9.1 Text description
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. Also some important skyculture components are extracted from here.
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).
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.1) should be given like [#42].
You can also have embedded images in the file (your book cover? Views of sacred land-
scapes/buildings/artwork/. .. ?), just provide them in PNG or JPG format please.
You should provide a good description in the interest of future users: some cultural/ethnograph-
ical background of the users of this sky culture, history 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.
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 will
have its own entry in the translations files.
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 names a constellation, and
the contents gives some information on it.
References – a list of references, see 9.1.1 for details.
Authors – all authors and acknowledgments go here.
License
– either a license id (see 9.1.2), 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".
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 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 t i o n a r y of Mo d ern 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 Text description 117
9.1.2 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 li-
cense 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
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
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-domain/freeworks
118 Chapter 9. Adding Sky Cultures
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.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 collec-
tions 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 " : " mo dern " ,
" regi on " : " W orld " ,
" cl a s s i fi cation " : [ " tradit i o n a l "] ,
" f a llba c k _to_ i n tern a t iona l _ name s ": false ,
" asterisms " : [ ... ] ,
" co n s t e ll ations " : [ ... ] ,
" edges_type " : " iau " ,
" edg e s _ s o u rc e ": " ht tps :// pb a r b i er . com / constel l a t i on s / e d ges_18 . txt " ,
" edges _ e p o c h ": " B1 875 " ,
" edges " : [ ... ] ,
" com m o n _ n a me 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.6
"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.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 following the United Nations geoscheme UN M49
4
:
4
Standard country or area codes for statistical use (M49) –
https://unstats.un.org/unsd/method
ology/m49/
9.2 Technical data: index.json 119
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, Zimbabwe.
Central Africa
– Angola, Cameroon, Central African Republic, Chad, Congo, Democratic Repub-
lic 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.
Southern 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 Ad-
ministrative 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 Repub-
lic, 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
120 Chapter 9. Adding Sky Cultures
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.
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.
9.2 Technical data: index.json 121
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
122 Chapter 9. Adding 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 123
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.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 proposed a different
approach. The boundaries were described by straight segments along great circles of equal right
ascension and small circles of equal declination. The atlas used coordinates for epoch B1875.0.
In 1930 the International Astronomical Union (IAU) ratified this partition of the sky into the 88
constellations 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:
" edges_type " : " iau " ,
" edg e s _ s o u rc e ": " ht tps :// pb a r b i er . com / constel l a t i on s / e d ges_18 . txt " ,
" edges _ e p o c h ": " B1 875 " ,
" edges " : [
" 001:0 0 2 M+ 22 : 5 2 : 00 +34:30:00 2 2 : 5 2 :00 +52:30:00 AND LAC " ,
" 002:0 0 3 P+ 22 : 5 2 : 00 +52:30:00 2 3 : 2 0 :00 +52:30:00 AND CAS " ,
" 004:0 0 5 P+ 23 : 2 0 : 00 +50:00:00 2 3 : 3 5 :00 +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 bound-
aries.
"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
124 Chapter 9. Adding Sky Cultures
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 ll ations " : [
{
" id " : " CON mo dern Aql " ,
" lines " : [ [ 9 80 3 6 , 9 76 4 9 , 97 27 8 ] , [ 97 6 4 9 , 955 0 1 , 978 0 4 ] , [99 4 73 , 97 8 04] ,
[9 5 5 01 , 9 3 7 47 , 9 3 2 44 ] , [ 955 0 1 , 93 80 5 ]] ,
" image " : {
" file ": " il l u s t r at io n s / aquila . png " ,
" size ": [5 1 2 , 5 12 ] ,
" ancho r s ": [
{" pos ": [1 6 3 , 2 32 ] , " hip " : 97 6 49 } ,
{" pos ": [3 8 5 , 1 31 ] , " hip " : 93 2 44 } ,
{" pos ": [3 9 7 , 3 97 ] , " hip " : 93 8 05 }
]
} ,
" commo n _ n a m e ": {" english ": " Aq u ila " , " n ative " : " Aqui l a " }
} , ...
] , ...
where
"id"
A unique figure identifier, consisting of
CON
(for constellations), skyculture id, and a short
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 setting Constellation name style to “short”
(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: In
Abbreviated
mode,
only the official abbreviations are displayed.
"lines"
an array of arrays, each describing a polygon 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.
Single-star constellations or particular highlights can be described with just one star re-
v 25.1
peated in a two-element segment, the respective star will be encircled with a radius of
"single_star_radius".
To describe dark constellations formed from dust clouds in the Milky Way or other non-
v 25.2
stellar items, 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_radius"
(float, default 0.5) radius of a circle (degrees) marking single-star seg-
v 25.1
ments in "lines".
"image" Optional, see 9.2.4
"common_name" Dictionary of names. Required entries: "english". Optional: "native"
These names are used in the Constellation name style settings (s. 4.4.6): In
Native
mode, the
native element is shown. Only with setting
Translated
, the text translated from the english
element is shown. If your sky culture is a variant of the
Modern
sky culture, please use the
canonical Latin names, they have all been translated already.
If your sky culture is not a variant of the generally known
Modern
(western) sky culture,
9.2 Technical data: index.json 125
please provide an English translation in addition to the name given in the native language.
Else translators will not be able to translate the name.
"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:
" visibility " : {" months ": [6 , 3 ] },
This specifies that the afflicted constellation is visible only from June to March. 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:
" visibility " : {" months ": [4 , 5 ] },
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 sub-
directory
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 was
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 are generally 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,
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.
126 Chapter 9. Adding Sky Cultures
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:
" asterisms " : [
{
" id " : " AST mo dern HeG " ,
" commo n _ n a m e ": {" english ": " Heave n l y G" , " re f e r e n c e s ": [30 ,3 2] } ,
" lines " : [ [ 2 14 2 1 , 2 46 0 8 , 36 85 0 , 3 7 82 6 , 3 7 27 9 , 3 234 9 , 2 443 6 , 2 533 6 , 2 798 9 ]]
} , ...
]
"id"
A unique asterism identifier, consisting of
AST
(for asterism), skyculture id, and a short 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 when setting Constellation name style to “short” (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
"english"
(the translatable english name), and an
optional array
"references"
which lists from which sources (from 9.1.1) this asterism was
taken. Collecting sources and giving such references is always a good idea. This entry may
be used in later versions of Stellarium.
"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
v 25.1
(star or coordinate pair) – the respective star/coordinate will be encircled with a radius of
"single_star_radius".
"single_star_radius"
(float, default 0.5) radius of a circle (degrees) marking single-star seg-
v 25.1
ments in "lines".
9.2.6 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.
As example, we show a part of the Samoan skyculture:
" com m o n _ n a me s ": {
" HIP 32 349 " : [{ " en glish " : " G liding Star " , " n ative " : "F¯et¯usolonu
‘
u"}] ,
" HIP 68 702 " : [{ " en glish " : " Mea " , " nativ e ": " Mea " } ] ,
" HIP 71 683 " : [{ " en glish " : " Filo " , " n ative " : " Filo " } ] ,
" M45 ": [{" english " : " Face of Li
‘
i", " na tive " : "Mat¯ali
‘
i"}] ,
" NGC20 5 5 ": [{" english " : " Pale Cloud " , " native " : " Aot ea " } ] ,
" NGC2 92 " : [ {" english ": " Fly ing Cloud " , " na tive " : " Aolel e "}] ,
" NGC60 9 3 ": [{" english " : " Pae "} ] ,
" NGC61 2 1 ": [{" english " : " Suga " } ] ,
" NAME Ear th " : [ { " engl i s h " : " Earth " , " nativ e " : " Lalo l a g i "}] ,
" NAME Jupiter ": [{" e nglish " : " Undying Mystery " , " native ": "Tupual¯egase"} ] ,
" NAME Mars " : [{ " en glish " : " R eddish Face / S u r face " , " n a tive " : " M a tamemea " }] ,
" NAME Mercury ": [{" e nglish " : " Brownish " , " n ative " : "Ta ' elo " }] ,
" NAME Moon " : [{ " en glish " : " Moon " , " n ative " : "M¯asina"}] ,
" NAME Satur n " : [ {" english " : " Garland Star " , " native ": "F¯et¯u
‘
¯asoa"}] ,
" NAME Sun ": [{" e nglish " : " Sun " , " nativ e " : "L¯a" } ] ,
" NAME Ven us " : [ { " engl i s h " : " Mo r n ing Star / F o r b i d d e n Radiance " , " native ":
֒→ "Tapu ' itea " }]
9.2 Technical data: index.json 127
}
Star names
The Keys for stars generally start with
"HIP "
. The associated array contains again dicts providing
english spellings of the star names and
"references"
(optional but highly recommended) which
indicates in which sources (see 9.1.1) these star names or particular spellings occur. Currently this
has only documentary value for skyculture authors and researchers, but may become useful in later
versions of Stellarium. 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.
" com m o n _ n a me s ": {
" HIP 677 " : [ {" english ": " Alpheratz " , " r e f e r e nc e s ": [1 ,2 ,5 , 6 ,11 ,1 2 ,3 7 ]} ,
{" english " : " Sirra h " , " references " : [ 2 3 , 3 7]} ] ,
" HIP 746 " : [ {" english ": " Caph " , " references " : [ 1 ,2 , 6 ,11 ,1 2 ,2 3 ,3 7 ] } ,
{" english " : " Al Sanam al Nakah " , " r e f e r e n c e s ": [37 ] } ] ,
... }
When there is more than one name for a star, the first in the list is used as screen label.
Planet Names
The
"common_names"
dict can also contain 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 vector provides
dicts which include
"english" (the translated name),
"native" (optional) native spelling, may be in native glyphs when supported by UTF8,
"pronounce"
(optional) Native name in European glyphs, if needed. For Chinese, expect Pinyin
here.
"translators_comments" (optional) comments to be shown to translators on Transifex,
"references" (optional) the sources for these names where applicable.
Currently, if two
"english"
strings are given, the first is used as screen label. This may change
as the features further evolve.
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. However, for languages with non-European glyphs please
v 25.2
add a widely used transliteration as pronounciation aid in the "pronounce" tag.
9.2.7 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.
"translators_comments"
(optional) English explanations that help in translation. Not displayed
in the program.
"references" (optional) the sources for these names where applicable
128 Chapter 9. Adding Sky Cultures
9.3 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.
Example command to run it:
cd c :\ Users \<ME >\ AppData \ Roaming \ skycultu res
move mine mine . old
"c :\ Program Files \ stel lariu m \ skyculture - c onverter " 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 may not be ideal. Formerly the
description was completely free in structure, while now there are some 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 foot-
notes are expected to be in the form of
<p id =" footnote -9 " > This is a footnote </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 denoted 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 op-
tion. The output directory will contain, in addition to
description.md
, files named like
description.es_419.DO_NOT_COMMIT.md
, with the “DO NOT COMMIT” part remind-
ing 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
9.4 Publish Your Work 129
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.4 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.2). 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.2 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 on-
line 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:
# E xample of a hi p s l ist file .
# Date : 2018 -03 -19
obs_ti t l e = c a l listo
hips_s e r v ice_url = https :// d ata . stellarium . org / s u rveys / ca l l i sto
hips_ r e l ea se_dat e = 2018 -03 -18 T14 :01 Z
hips_status = pub l ic m i rror c l on a bl e On c e
...
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)
1
https://www.ivoa.net/documents/HiPS/20170519/REC-HIPS-1.0-20170519.pdf
132 Chapter 10. Surveys
This can be changed with the
sources
entries in the
[hips]
section of the configuration file (see
also section D.1.29). You can add your own private HiPS surveys by running a local webserver and
adding:
[ hips ]
so u r ces /1/ url = http :// alasky .u - st r a sbg . fr / M o c S e rver / query ?*/ P /*& get = recor d
so u r ces /2/ url = https :// data . stellarium . org / su r veys / hi p s l ist
so u r ces /3/ url = http :// loca l h o s t / Stellarium / hips / hi p s l i s t
so u r ces / size = 3
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.
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.stellari
um.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
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.
10.4 Digitized Sky Survey 2 (TOAST Survey) 133
[ astro ]
toast_survey_directory = StelDSS
toast_ s u rvey_host =T :/
toast_s u r v e y _ levels =10
On Linux, with the files stored in
/usr/local/share/Stellarium/StelDSS
, the same section
could look like
[ astro ]
toast_survey_directory = usr / local / share / Stellarium / StelDSS
toast_ s u rvey_host =/
toast_s u r v e y _ levels =10
Level No of files Filespace (kB)
0 1 32
1 4 124
2 16 472
3 64 1.820
4 256 7.172
5 1.024 27.920
6 4.096 109.628
7 16.384 429.800
8 65.536 1.661.808
9 262.144 6.119.092
10 1.048.576 20.250.216
11 4.194.305 83.583.724
Table 10.1: Number of files and storage requirements for local DSS TOAST installation
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
136 Chapter 11. Stellarium’s Skylight Models
Only with this setting, a button will be available in the View settings, Sky tab (sec-
tion 4.4.1).
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.
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
implementation 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.
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, Cal-
cMySky, 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 automat-
ically 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:
1
https://github.com/10110111/CalcMySky
11.3 Light Pollution 137
[ landscape ]
atmosphere_resol u t i o n _ reduction = 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 ]
flag_atmosphe r e _ d y namic_resolution = 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
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.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 (
cd/m
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 (mag/arcsec
2
). It is related to cd/m
2
as
L = 10.8 ×10
4−0.4M
, (11.2)
where
L
is the value in
cd/m
2
, and
M
is the value in
mag/arcsec
2
. Some SQMs give readings in
mag/arcsec
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.
138 Chapter 11. Stellarium’s Skylight Models
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
100cd/m
2
applicable for CRT monitors, but more modern screens can achieve much higher luminances
of
250cd/m
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,
50cd/m
2
seems a usable default. In an outdoor setting, much
higher values are possible.
Display Gamma
describes the exponent of a nonlinear correlation between input values and
output luminance 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
12 Plugins: An Introduction . . . . . . . . . . . . . . . . . 141
13 Interface Extensions . . . . . . . . . . . . . . . . . . . . . 143
14 Object Catalog Plugins . . . . . . . . . . . . . . . . . 169
15 Scenery3d – 3D Landscapes . . . . . . . . . . . . 211
16 Stellarium at the Telescope . . . . . . . . . . . . . 225
17 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Extending Stellarium
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: Angle Measure, Compass Marks, Oculars, Telescope Control,
Text User Interface, Satellites, Solar System Editor, Historical Novae and Supernovae, Quasars,
Pulsars, Exoplanets, Observability analysis, ArchaeoLines, Scenery3D, RemoteControl, Navigation
Stars and RemoteSync. 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.
142 Chapter 12. Plugins: An Introduction
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
Mac OS X 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.
The Angle Measure plugin is a small tool which is used to measure the angular distance between
two points 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:
144 Chapter 13. Interface Extensions
Figure 13.1: Interface of Angle Measure plugin
•
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 145
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 Stel-
larium
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
146 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 pro-
gram 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 Text User Interface Plugin 147
13.4 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.
A full list of the commands for the TUI plugin is given in section 13.4.2.
13.4.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.4.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 com-
puter 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. “sys-
tem_default” takes the format from the computer set-
tings, or it is possible to select “yyyymmdd”, “ddm-
myyyy” or “mmddyyyy” modes
2.7
Time Display Format
Change how Stellarium formats time values. “sys-
tem_default” takes the format from the computer set-
tings, 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)
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.
148 Chapter 13. Interface Extensions
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
4.9
Show additional star names
4.10
Use designations for screen
labels
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 Ap-
pendix B Bortle Scale index)
13.4 Text User Interface Plugin 149
6.2 Landscape
Select the landscape which Stellarium draws when
ground drawing is enabled. Press to activate.
6.3
Setting Landscape Sets Loca-
tion
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 modified when the landscape is changed.
6.4
Auto zoom out returns to ini-
tial . . . 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
Directory 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
8.2 Save current configuration Save the current settings to the main configuration file
8.3
Shutdown Emits a command configured in
13.4.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 plane-
tarium 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
150 Chapter 13. Interface Extensions
13.5 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.5.1 Using the plugin
Figure 13.4: 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.
13.5 Remote Control Plugin 151
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.
Password
The access to the remote control may optionally be restricted with a simple password.
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.
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 config-
uration dialog. Then, enter the URL of the website you’d like to use to control Stellarium – e.g.
https://telescopius.com
. Specify “*” to let any website take control. Do this at your own
risk.
13.5.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 (chap-
ter 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.5.3 Remote Control API
Apart from retrieving quick object info in your browser with e.g.
http://localhost:8090/api
/objects/info?format=json&name=Sun
, you can access a running instance of Stellarium with
various programming languages. A few examples:
Commandline
It is possible to send commands via command line, e.g.:
curl -d "x =1& y =0.3 " http :// localhost :8090/ api / main / move
wget -- post - data " id = show . ssc " http :// stella :809 0 / api / s c ripts / run -O / dev / null
152 Chapter 13. Interface Extensions
curl -d " id = myS c r i p t . ssc " http :// l o c a l h o s t :809 0/ api / scripts / run
curl -d " id = Landscap e M g r . fog D i s p l a y ed & val ue = false " \
http :// l o c a l h o s t :809 0/ api / s t e l pr o pe r ty / 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 " pr o pId = -2& actionI d = -2 " http :// localhost :8090/ api / m ain / st atus | \
py thon -m json . tool
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] "
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.168 . xxx . xxx :809 0/ api / main / view ? j 2000 =[0.5 ,0.3 ,0 .2] ’;
fetch ( url , {
me thod : ’ POST ’ ,
he a d ers : {
’ Content - Type ’: ’ application / json ’
}
})
. then ( response = > {
res p o n s e . text (). then ( text = > console . log ( ’Raw r e sponse : ’ , text ));
re turn r e s p onse . json ();
})
Python
An example for time control:
im port r e q u ests
STELLAR I U M _ UR L = ’ http : //192 . 1 68.1. 1 0 0:809 0 / api / main ’
def set_time ( julian_ day , timerate ):
url = f"{ S TELLARIUM _ U R L }/ time "
data = " time =" + str ( ju l i a n _ d a y )+ " & ti m e r a te = "+ str ( timerate )
print (f " Re q uest URL : { url }")
print (f " Re q uest Data : { data } " )
try :
res p o n s e = r e q u ests . post (url , data = d ata )
print (f " Res p o n s e Sta t us Code : { r e sponse . st at u s _ co d e }" )
print (f " Res p o n s e Conte n t : { re s ponse . text } ")
res p o n s e . rai s e _ fo r_statu s ()
if respons e . text . str ip () == " ok " :
re turn { " stat us " : " su ccess " , " m e s sage " : " Time set s u cc e s sfully " }
else :
re turn { " stat us " : " e rror " , " message ": re s ponse . text }
ex cept r e q u ests . exceptions . Re questEx c e p ti on as e :
print (f " Error settin g time : {e} " )
re turn { " stat us " : " e rror " , " message ": str ( e )}
2
Thanks to user FogoVoar
13.5 Remote Control Plugin 153
13.5.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.5.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/
154 Chapter 13. Interface Extensions
13.6 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.5). 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.5: 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
13.6 Remote Sync Plugin 155
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 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.6: RemoteSync client settings window
It is also possible to exclude some state from being synchronized. On each client, the client
configuration GUI (Figure 13.6) allows to disable specific settings from being synchronized on this
client.
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.
156 Chapter 13. Interface Extensions
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 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.6.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:
[ RemoteSync ]
allo w V e rsionM i s match = true
13.6.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_LOG G I N G_RULES =" stel . plugi n . remoteSync . d ebug = true ;
stel . plug i n . remoteSync . c lient . debug = f alse ;
stel . plug i n . remoteSync . p r o t o col . debug = fa lse ; "
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.7 OnlineQueries Plugin 157
13.7 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.
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.7.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)
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/
158 Chapter 13. Interface Extensions
13.8 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 direc-
tory 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
10
) 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.
The second tab lists all currently loaded minor bodies (see figure 13.8). 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 just a handful to improve performance.
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.9 and 13.10).
Once MPC data has been downloaded, the user can select objects for updating the user’s
ssystem_minor.ini.
10
https://www.minorplanetcenter.net
13.8 Solar System Editor Plugin 159
Figure 13.7: Interface of Solar System Editor plugin: Configuration file tab
Figure 13.8: Interface of Solar System Editor plugin: Solar System tab
160 Chapter 13. Interface Extensions
Figure 13.9: Interface of Solar System Editor plugin: Import data dialog
Figure 13.10: Interface of Solar System Editor plugin: Import data dialog — view after
downloading and parsing the MPC data.
13.9 Calendars Plugin 161
13.9 Calendars Plugin
GEORG ZOTTI
13.9.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.
11
13.9.2 The Calendars
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
11
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.
162 Chapter 13. Interface Extensions
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 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
12
.
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.).
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.
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.
12
More details can be found on https://en.wikipedia.org/wiki/Revised_Julian_calendar
13.9 Calendars Plugin 163
Ethiopic
is Parallel to 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
v 1.2
version 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
¯
ah
.
id, “unity”) and numbered 19
2
= 361-years (Kull-i-shay) cycles.
Near Eastern calendars
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 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.
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 Side-
real 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
164 Chapter 13. Interface Extensions
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.
13
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
14
.
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 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.
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 tradi-
13
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.
14
Again, this is unconfirmed. If you know better, please tell us!
13.9 Calendars Plugin 165
tional 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.
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.
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 compu-
tation 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.
With the end of Gregorian year 1805, the calendar was abolished, but re-introduced for a few
days in May 1871.
166 Chapter 13. Interface Extensions
13.9.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.9.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.9.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
13.9 Calendars Plugin 167
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.9.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!
1
https://en.wikipedia.org/wiki/V1500_Cygni
170 Chapter 14. Object Catalog Plugins
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:
" Nova desig nation " :
{
" name " : " name of nova " ,
" type " : " type of nova " ,
" maxMagni tude ": value of maximal visual magnitude ,
" minMagni tude ": value of minimal 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 distance between nova and
Earth (in thousands of Light Years ),
" RA ": " Right ascension ( J2000 ) " ,
" Dec " : " Declina tion ( J2000 ) "
},
For example, the record for Nova Cygni 1975 (V1500 Cyg) looks like:
" V1500 Cyg " :
{
" name " : " Nova Cygni 1975 " ,
" type " : " NA " ,
" maxMagni tude ": 1.69 ,
" minMagni tude ": 21 ,
" peakJD ": 2442655 ,
" m2 ": 2,
" m3 ": 4,
" m6 ": 32 ,
" m9 ": 263
" distance ": 6.36 ,
" RA ": " 21 h11m36 .6 s " ,
" Dec " : " 48 d09m02s "
},
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 171
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 catalog
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
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
172 Chapter 14. Object Catalog Plugins
SN 1680A
8
15 August 6.0 IIb Cassiopeia A
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
8
https://en.wikipedia.org/wiki/Cassiopeia_A
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 173
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.
Figure 14.3: Light Curves of Supernovae Types I (left) and II (right)
In both images for light curves the maximum brightness is marked as day 0.
14.2.3 Section
Supernovae
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
174 Chapter 14. Object Catalog Plugins
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 ",
" maxMagni tude ": value of maximal visual magnitude ,
" peakJD ": JD for maximal visual magnitude ,
" alpha " : " Right ascension ( J2000 ) " ,
" delta " : " Declination ( J2000 ) " ,
" distance ": value of distance between supernova and
Earth (in thousands of Light Years ),
" note " : " notes for supernova "
},
For example, the record for SN 1604A (Kepler’s Supernova) looks like:
" 1604 A " :
{
" type " : "I" ,
" maxMagni tude ": -2,
" peakJD ": 2307190 ,
" alpha " : " 17 h30m36 .00 s" ,
" delta " : " -21 d29m00 .0 s" ,
" distance ": 14 ,
" note " : " Kepler ’s Supe rnova "
},
14.3 Exoplanets Plugin 175
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
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
176 Chapter 14. Object Catalog Plugins
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.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
18
https://phl.upr.edu/projects/earth-similarity-index-esi
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.
14.3 Exoplanets Plugin 177
the telescope.
Harriot
(55 Cnc f) – Thomas Harriot (ca. 1560-1621) was an English astronomer, mathematician,
ethnographer, 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.
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
disturbances, from German for noisy ghost.
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.
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.
178 Chapter 14. Object Catalog Plugins
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 mathe-
matician, 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 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
14.3 Exoplanets Plugin 179
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 Azerbai-
jan, 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 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.
180 Chapter 14. Object Catalog Plugins
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
Makropulos Affair), dealing with problems of immortality and consequences of an artificial
prolongation of life.
14.3 Exoplanets Plugin 181
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 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
182 Chapter 14. Object Catalog Plugins
nearby Sans-Souci Palace.
Indépendance
(HD 1502 b) – Indépendance is named after the Haitian Declaration of Indepen-
dence 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.
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.
14.3 Exoplanets Plugin 183
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 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 sub-
stances, 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
184 Chapter 14. Object Catalog Plugins
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 repre-
senting 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 dance in which a man and woman dance to the sound of drums.
14.3 Exoplanets Plugin 185
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.
186 Chapter 14. Object Catalog Plugins
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 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, sym-
bolising 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
14.3 Exoplanets Plugin 187
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 south-
western Alaska, USA.
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 by yourself for changes of 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 Inter-
net
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
188 Chapter 14. Object Catalog Plugins
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 plu-
gin
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 exoplanets. 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 des ignat ion ":
{
" ex oplan ets " :
[
{
" mass " : mass of exo planet ( M jup ) ,
" radius ": radius of ex op lanet ( R jup ),
" period ": period of ex op lanet ( days ),
" semiAx is ": semi - major axis ( AU ),
" eccen tri city " : orbit ’s eccentricity ,
" incli natio n ": orbit ’s i nclin ation ( degree ) ,
" angleDistan ce ": angle distance from star
( ar cseco nds ) ,
" di scove red " : exoplan et di scove red year ,
" det ect ion Met hod ": " exop lanet d etection method " ,
" pclass ": " plane tary class " ,
" EqTemp ": e quilibri um tempe ratur e (K),
" conse rva tive " : conserva tive or opti misti c
ha bitab ili ty of the exoplanet ,
" ESI " : Earth Sim ilarity Index (*100) ,
" pla net ProperN ame ": " proper name of planet " ,
" pl anetN ame " : " de signatio n of planet "
},
{
" mass " : mass of exo planet ( M jup ) ,
" radius ": radius of ex op lanet ( R jup ),
" period ": period of ex op lanet ( days ),
" semiAx is ": semi - major axis ( AU ),
" eccen tri city " : orbit ’s eccentricity ,
" incli natio n ": orbit ’s i nclin ation ( degree ) ,
" angleDistan ce ": angle distance from star
( ar cseco nds ) ,
" di scove red " : exoplan et di scove red year ,
" det ect ion Met hod ": " exop lanet d etection method " ,
" pclass ": " plane tary class " ,
" EqTemp ": e quilibri um tempe ratur e (K),
" conse rva tive " : conserva tive or opti misti c
ha bitab ili ty of the exoplanet ,
" ESI " : Earth Sim ilarity Index (*100) ,
14.3 Exoplanets Plugin 189
" pla net ProperN ame ": " proper name of planet " ,
" pl anetN ame " : " de signatio n of planet "
}
],
" distan ce ": value of distance to star ( pc ),
" stype ": " spectral type of star " ,
" smass ": value of mass of star ( M sun ) ,
" smetal ": value of metal licit y of star ,
" Vmag " : value of visual magni tude of star ,
" sradius ": value of radius of star (R sun ),
" effectiveTe mp ": value of effec ti ve tempe ratur e
of star ( K ) ,
" sta rPr ope rNa me ": " proper name of the star " ,
" hasHP ": boolean ( has potentia l hab itable planets ),
" RA " : " Right ascension ( J2000 )" ,
" DE " : " De clinatio n ( J2000 ) "
},
For example, the record for 24 Sex looks like:
" 24 Sex ":
{
" ex oplan ets " :
[
{
" mass " : 1.99 ,
" period ": 452.8 ,
" semiAx is ": 1.333 ,
" eccen tri city " : 0.09 ,
" angleDistan ce ": 0.017821 ,
" di scove red " : 2010 ,
" pl anetN ame " : "b"
},
{
" mass " : 0.86 ,
" period ": 883.0 ,
" semiAx is ": 2.08 ,
" eccen tri city " : 0.29 ,
" angleDistan ce ": 0.027807 ,
" di scove red " : 2010 ,
" pl anetN ame " : "c"
}
],
" distan ce ": 74.8 ,
" stype ": " G5 " ,
" smass ": 1.54 ,
" smetal ": -0.03 ,
" Vmag " : 7.38 ,
" sradius ": 4.9 ,
" effectiveTe mp ": 5098 ,
" RA " : " 10 h 23m28s " ,
" DE " : " -00 d54m08s "
},
190 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 191
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 d esignation " :
{
" RA ": " Right ascension ( J2000 ) " ,
" DE ": " Declination ( J2000 ) " ,
" notes " : " type of pulsar " ,
" distance ": value of distance based on electron density
model ( kpc ),
" period ": value of barycentric period of the pulsar (s),
" parallax ": value of annual parallax ( mas ) ,
" bperiod ": value of binary period of pulsar ( days ) ,
" pderivative " : value of time derivative of b arcycent ric
period ,
" dmeasure ": value of dispersio n measure ( pc /( cm * cm * cm )) ,
" frequency ": value of barycentric rotation frequency (Hz ),
" pfrequency " : value of time derivative of barycentric
rotation frequency (1/( s*s ))
" eccentri city ": value of eccentricity ,
" w50 " : value of profile width at 50% of peak ( ms ) ,
" s400 " : value of time averaged flux density at
400 MHz ( mJy ),
" s600 " : value of time averaged flux density at
600 MHz ( mJy ),
" s1400 " : value of time averaged flux density 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.805997239145 ,
" pfrequency " : -3.6669E -16 ,
" w50 " : 88.7 ,
" s400 " : 14 ,
" s600 " : 9,
" s1400 " : 3,
" RA ": " 00 h14m17 .75 s " ,
" DE ": " 47 d46m33 .4 s "
},
192 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 Quasars Plugin 193
14.5.2 Format of quasars catalog
To add a new quasar, open a new line after line 5 and paste the following, note commas and brackets,
they are important:
" Quasar d esignation " :
{
" RA ": " Right ascension ( J2000 ) " ,
" DE ": " Declination ( J2000 ) " ,
" Amag " : value of absolute magnitude ,
" Vmag " : value of visual magnitude ,
"z": value of Z ( redshift ),
" bV ": value of B -V colour
},
For example, the record for 3C 249.1 looks like:
"3C 249.1 ":
{
" RA ": " 11 h04m13 .8 s " ,
" DE ": " +76 d58m58s ",
" Amag " : -25.1 ,
" Vmag " : 15.72 ,
"z": 0.313 ,
" bV ": -0.02
},
194 Chapter 14. Object Catalog Plugins
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
14.6 Meteor Showers Plugin 195
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.
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 - letter code " :
{
" desig natio n " : " Name " ,
" IAUNo ": " IAU shower number " ,
" activi ty ":
[
{
196 Chapter 14. Object Catalog Plugins
" year " : " generic " ,
" zhr " : Maximum ZHR ( -1 if var ia ble ) ,
" variab le ": " Minimum - maximum ( if v ar ia ble ) " ,
" start ": Solar longit ude at start ,
" finish ": Solar longitud e at finish ,
" peak " : Solar long itude at peak ,
" distty pe ": Type of d ist ribut ion function
(0= Gauss , 1= Lorentz ) ,
" b1 " : Slope of di str ibuti on function
before peak ,
" b2 " : Slope of di str ibuti on function
after peak
}
],
" speed ": Geoc entri c speed ( km /s ) ,
" radia ntA lpha " : Right As cension ( J2000 ) ( degree ),
" radia ntD elta " : Decli natio n ( J2000 ) ( degree ),
" dr iftAl pha " : Radi ant drift in Right Ascension ,
" dr iftDe lta " : Radi ant drift in Declination ,
" colors ":
[
{
" color ": " white " ,
" in tensity " : 70
},
{
" color ": " blu eGreen " ,
" in tensity " : 30
}
],
" pa rentObj " : " Parent object " ,
" pidx " : po pulation index
},
For example, below is a record for Northern Taurids:
" NTA " :
{
" desig natio n " : " Northern Taurids " ,
" IAUNo ": " 17 " ,
" activi ty ":
[
{
" year " : " generic " ,
" zhr " : 5 ,
" start ": 206 ,
" finish ": 258 ,
" peak " : 230
}
],
" speed ": 29 ,
" radia ntA lpha " : 58 ,
" radia ntD elta " : 22 ,
" dr iftAl pha " : 1.03 ,
" dr iftDe lta " : 0.26 ,
" colors ":
14.6 Meteor Showers Plugin 197
[
{
" color ": " yellow " ,
" in tensity " : 80
},
{
" color ": " white " ,
" in tensity " : 20
}
],
" pa rentObj " : " Comet 2 P / Encke " ,
" 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
198 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
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/2008/12/rude-starfinder-2102-d.html
14.7 Navigational Stars Plugin 199
Figure 14.9: Settings of the Navigational stars plugin
Figure 14.10: Today tab in the Navigational stars plugin
200 Chapter 14. Object Catalog Plugins
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.
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 plane-
tarium
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 Navi-
gation Stars
highlight_when_visible
bool Set to true to highlight only visible stars
current_ns_set string
Current set of navigational stars. Possible values: An-
gloAmerican, French, Russian and German.
14.8 Satellites Plugin 201
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.
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.
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.
202 Chapter 14. Object Catalog Plugins
Figure 14.12: Configuration of the Satellites plugin: satellite properties
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.
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
14.8 Satellites Plugin 203
Figure 14.13: Configuration of the Satellites plugin: satellites custom filter
Figure 14.14: Configuration of the Satellites plugin: satellite communication data
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
“Description” 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:
APT Automatic Picture Transmission
204 Chapter 14. Object Catalog Plugins
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
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 number ":
{
" name ": " name of the satellite "
" descr i p t i o n ": " description goes here " ,
" comms " : [
{
" desc r i p t i o n ": " downl i n k 1" ,
" frequency " : 437.49 ,
" modulation " : " AFSK 1 200 bps "
},
{
" desc r i p t i o n ": " downl i n k 2" ,
" frequency " : 145.82 5
}
],
" grou ps " : [ " gro up1 " , " g roup2 " ] ,
" stdM ag " : 2.0 ,
" tle1 ": "1 1 2345 U 90005 D 09080. 8 5 2 3 62 65 .0 0 0 0 0 0 1 4 00000 -0 20602 -4 0 5632 " ,
" tle2 ": "2 1 2345 98.270 0 53.2702 0011918 71.1776 289.0705 14.31818920 653 " ,
" visib l e ": tru e
},
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
32
https://www.json.org/
14.8 Satellites Plugin 205
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 configura-
tion 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 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
33
Mike McCants’ Satellite Tracking Web Pages — https://mmccants.org
34
Satellite Catalog (SATCAT) — https://celestrak.org/satcat/search.php
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
14.9 ArchaeoLines Plugin 207
14.9 ArchaeoLines Plug in
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
208 Chapter 14. Object Catalog Plugins
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).
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 (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.
14.9 ArchaeoLines Plugin 209
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)
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
210 Chapter 14. Object Catalog Plugins
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
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 de-
scribed 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
plus cursor keys. Change eye height with
Ctrl
+
Page
/
Ctrl
+
Page
keys. Adding key increases speed by 10, adding
Alt
multiplies by 5
(pressing both keys multiplies by 50!). If you release
Ctrl
before the cursor key, animation will
continue. (Press
Ctrl
+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
212 Chapter 15. Scenery3d – 3D Landscapes
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 merid-
v 23.2
iana “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.)
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 perfor-
mance/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
15.4 Model Configuration 213
Geometry Yes
Lights Yes
Clay No
Photomatched Yes
DefaultUVs No
Instanced No
Table 15.1: Kerkythea Export Settings
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.
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.
1
Available at http://www.kerkythea.net/cms/
2
Available from http://forums.sketchucation.com/viewtopic.php?f=323&t=33448
214 Chapter 15. Scenery3d – 3D Landscapes
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 directly after each other in the OBJ). A
simple guide to use Blender
3
for this task follows:
1.
File Import Wavefront .obj
- you may need to change the forward/up axes for correct
orientation, try “-Y forward” and “Z up”
2. Select an object which has a shared material
3. Press
+
L
and select ’By Material’
4. Select ’Join’ in the left (main) tool window
5. Repeat for other objects that have shared materials
6.
Export the .obj, making sure to select the same forward/up axes as in the import, also make
sure “Write Normals”, “Write Materials” and “Include UVs” are checked
For transparent objects (with a
d
or
Tr
value, alpha testing does NOT need this), this recommenda-
tion does NOT hold: for optimal results, each separate transparent object should be exported as a
separate “OBJ object”. This is because they need to be sorted during rendering to achieve correct
transparency. If the objects are combined already, you can separate them using Blender:
1. Import .obj (see above)
2. Select the combined transparent object
3. Enter “Edit” mode with
and make sure everything is selected (press
A
if not)
4.
Press
P
and select “By loose parts”, this should separate the object into its unconnected
regions
5. Export .obj (see above), also check “Objects as OBJ Objects”
The MTL file specified by
mtllib
contains the material parameters. The minimum that should
be specified is either
map_Kd
or a
Kd
line specifying color values used for the respective faces.
3
https://www.blender.org
15.4 Model Configuration 215
Parameter Default Range Meaning
Ka set to Kd values 0. . .1 each R/G/B Ambient color
Kd 0.8 0.8 0.8 0...1 each R/G/B Diffuse color
Ke 0.0 0.0 0.0 0...1 each R/G/B Emissive color
Ks 0.0 0.0 0.0 0...1 each R/G/B Specular color
Ns 8.0 0. . .∞ shinyness
d or Tr 1.0 0...1 opacity
bAlphatest 0 0 or 1 perform alpha test
bBackface 0 0 or 1 render backface
map_Kd (none) filename texture map to be mixed with Ka, Kd
map_Ke (none) filename texture map to be mixed with Ke
map_bump (none) filename normal map for surface roughness
illum 2 integer illumination mode in the standard MTL format.
vis_fadeIn (none) double see 15.4.5
vis_fadeOut (none) double see 15.4.5
Table 15.2: MTL parameters evaluated
But there are other options in MTL files, and the supported parameters and defaults are listed in
Table 15.2.
If no ambient color is specified, the diffuse color values are taken for the ambient color. An
optional emissive term
Ke
can be added, which is modulated to only be visible during nighttime.
This also requires the landscape’s self-illumination layer to be enabled. It allows to model self-
illuminating objects such as street lights, windows etc. It can optionally also be modulated by the
emissive texture map_Ke.
If a value for
Ks
is specified, specularity is evaluated using the Phong reflection model
4
with
Ns
as the exponential shininess constant. Larger shininess means smaller specular highlights (more
metal-like appearance). Specularity is not modulated by the texture maps. Unfortunately, some 3D
editors export unusable default value combinations for
Ks
and
Ns
. Blender may create lines with
Ks
=1/1/1 and
Ns
=0. This creates a look of “partial overexposed snow fields”. While the values are
allowed in the specification, in most cases the result looks ugly. Make sure to set
Ns
to 1 or higher,
or disable those two lines.
If a value for
d
or
Tr
exists, alpha blending is enabled for this material. This simulates
transparency effects. Transparency can be further controlled using the alpha channel of the
map_Kd
texture.
A simpler and usually more performant way to achieve simple “cutout” transparency effects is
alpha-testing, by setting
bAlphatest
to 1. This simply discards all pixels of the model where the
alpha value of the
map_Kd
is below the
transparency_threshold
value from
scenery3d.ini
,
making “holes” in the model. This also produces better shadows for such objects. If required, alpha
testing can be combined with “real” blending-based transparency.
Sometimes, exported objects only have a single side (“paper wall”), and are only visible from
one side when looked at in Scenery3d. This is caused by an optimization called back-face culling
5
,
which skips drawing the back sides of objects because they are usually not visible anyway. If
possible, avoid such “thin” geometry, this will also produce better shadows on the object. As a
workaround, you can also set bBackface to 1 to disable back-face culling for this material.
The optional
map_bump
enables the use of a tangent-space normal maps
6
, which provides a
dramatic improvement in surface detail under illumination.
4
https://en.wikipedia.org/wiki/Phong_reflection_model
5
https://en.wikipedia.org/wiki/Back-face_culling
6
https://en.wikipedia.org/wiki/Normal_mapping
216 Chapter 15. Scenery3d – 3D Landscapes
15.4.3 Configuring OBJ for Scenery3d
The walkaround in your scene can use a ground level (piece of terrain) on which the observer can
walk. The observer eye will always stay “eye height” above ground. Currently, there is no collision
detection with walls implemented, so you can easily walk through walls, or jump on high towers, if
their platform or roof is exported in the ground layer. If your model has no explicit ground layer,
walk will be on the highest surface of the scenery layer. If you use the special name
NULL
as ground
layer, walk will be above zero_ground_height level.
Technically, if your model has cavities or doors, you should export your model twice. Once,
just the ground plane, i.e. where you will walk. Of course, for a temple or other building, this
includes its socket above soil, and any steps, but pillars should not be included. This plane is
required to compute eye position above ground. Note that it is not possible to walk in several floors
of a building, or in a multi-plane staircase. You may have to export several “ground” planes and
configure several scenery directories for those rare cases. For optimal performance, the ground
model should consist of as few triangles as you can tolerate.
The second export includes all visible model parts, and will be used for rendering. Of course,
this requires the ground plane again, but also all building elements, walls, roofs, etc.
If you have not done so by yourself, it is recommended to separate ground and buildings into
Sketchup layers (or similar concepts in whichever editor you are using) in order to easily switch the
model to the right state prior to exporting.
Filename recommendations:
<Temple>.skp
Name of a Sketchup Model file. (The
<>
brackets signal “use your
own name here!”) The SKP file is not used by Scenery3d, but you
may want to leave it in the folder for later improvements.
<Temple>.obj Model in OBJ format.
<Temple>_ground.obj Ground layer, if different from Model file.
OBJ export may also create folders
TX_<Temple>
and
TX_<Temple>_ground
. You can delete the
TX_<Temple>_ground folder, <Temple>_ground.obj is just used to compute vertical height.
Put the OBJ, MTL and TX directories into a subdirectory of your user directory (see sec-
tion 5.1), e.g.
<USERDATA>/Stellarium/scenery3d/<Temple>
, and add a text file into it called
scenery3d.ini (This name is mandatory!) with content described as follows.
[model]
name=<Temple>
Unique ID within all models in scenery3d directory. Recom-
mendation: use directory name.
landscape=<landscapename> Name of an available Stellarium landscape.
This is required if the landscape file includes geographical coordinates and your model does not:
First, the location coordinates of the
landscape.ini
file are used, then location coordinates given
here. The landscape also provides the background image of your scenery. If you want a zero-height
(mathematical) horizon, use the provided landscape called Zero Horizon.
scenery=<Temple>.obj The complete model, including visible ground.
ground=<Temple>_ground.obj
Optional: separate ground plane. (NULL for zero altitude.)
description=<Description> A basic scene description (including HTML tags)
The
scenery3d.ini
may contain a simple scene description, but it is recommended to use the
localizable description format: in the scene’s directory (which contains
scenery3d.ini
) create
files in the format
description.<lang>.utf8
which can contain arbitrary UTF-8–encoded
HTML content. <lang> stands for the ISO 639 language code.
author=<Your Name yourname@yourplace.com>
copyright=<Copyright Info>
15.4 Model Configuration 217
obj_order=XYZ
Use this if you have used an exporter which swaps Y/Z
coordinates. Defaults to
XYZ
, other options:
XZY
,
YZX
,
YXZ
,
ZXY, ZYX
camNearZ=0.3
This defines the distance of the camera near plane, default
0.3. Everything closer than this value to the camera can not
be displayed. Must be larger than zero. It may seem tempting
to set this very small, but this will lead to accuracy issues.
Recommendation is not to go under 0.1
camFarZ=10000 Defines the maximal viewing distance, default 10000.
shadowDistance=<val>
The maximal distance shadows are displayed. If left out, the
value from
camFarZ
is used here. If this is set to a smaller
value, this may increase the quality of the shadows that are
still visible.
shadowSplitWeight=0..1
Decimal value for further shadow tweaking. If you require
better shadows up close, try setting this to higher values. The
default is calculated using a heuristic that incorporates scene
size.
[general]
The general section defines some further import/rendering options.
transparency_threshold=0.5
Defines the alpha threshold for alpha-testing, as described
in section 15.4.2. Default 0.5
scenery_generate_normals=0
Boolean, if true normals are recalculated by the plugin,
instead of imported. Default false
ground_generate_normals=0
Boolean, same as above, for ground model. Default
false
.
[location]
Optional section to specify geographic longitude
λ
, latitude
ϕ
, and altitude. The section is
required if
coord/convergence_angle={from_grid|from_utm}
, else location is inherited from
landscape.
planet = Earth
latitude = +48d31’30.4"
Required if
coord/convergence_angle=from_{grid|utm}
longitude = +16d12’25.5" "–"
altitude =from_model|<int>
altitude (for astronomical computations) can be computed
from the model: if
from_model
, it is computed as
(z
min
+
z
max
)/2+ orig_H
, i.e. from the model bounding box centre
height.
display_fog = 0
atmospheric_extinction_coefficient = 0.2
atmospheric_temperature = 10.0
atmospheric_pressure = -1
light_pollution = 1
[coord]
Entries in the
[coord]
section are again optional, default to zero when not specified, but are
required if you want to display meaningful eye coordinates in your survey (world) coordinate
system, like UTM or Gauss-Krüger.
218 Chapter 15. Scenery3d – 3D Landscapes
grid_name=<string>
Name of grid coordinates, e.g.
"UTM 33 U
(WGS 84)"
,
"Gauss-Krüger M34"
or
"Relative to
<Center>"
This name is only displayed, there is no
evaluation of its contents.
orig_E=<double> | (Easting) East-West-distance to zone central meridian
orig_N=<double> | (Northing) North distance from Equator
orig_H=<double> | (Height) Altitude above Mean Sea Level of model origin
These entries describe the offset, in metres, of the model coordinates relative to coordinates in a
geographic grid, like Gauss-Krüger or UTM. If you have your model vertices specified in grid
coordinates, do not specify orig_... data, but please definitely add start_... data, below.
Note that using grid coordinates without offset for the vertices is usually a bad idea for real-
world applications like surveyed sites in UTM coordinates. Coordinate values are often very large
numbers (ranging into millions of meters from equator and many thousands from the zone meridian).
If you want to assign millimetre values to model vertices, you will hit numerical problems with the
usual single-precision floating point arithmetic. Therefore we can specify this offset which is only
necessary for coordinate display.
Typically, digital elevation models and building structures built on those are survey-grid aligned,
so true geographical north for a place with geographical longitude
λ
and latitude
ϕ
will in general
not coincide with grid north, the difference is known as meridian convergence
7
and, on a spherical
globe, amounts to:
γ(λ ,ϕ) = arctan(tan(λ −λ
0
)sin
ϕ) (15.1)
This amount can be given in
convergence_angle
(degrees), so that your model will be rotated
clockwise by this amount around the vertical axis to be aligned with True North
8
.
conver g e nce_angle = from_grid | from_utm | < double >
gri d_meridia n =< double >|+ < int >d < int > ’< float >"
grid_meridian
is the central meridian
λ
0
of the grid zone, e.g. for Gauss-Krüger, and is only
required to compute convergence angle if
convergence_angle=from_grid
. If your model coordi-
nates is based on UTM, you can use
coord/convergence_angle=from_utm
for a more accurate
computation.
zero_gr o u n d_height =< double >
height of terrain outside
<Temple>_ground.OBJ
, or if
ground=NULL
. Allows smooth approach
from outside. This value is relative to the model origin, or typically close to zero, i.e., use a Z
value in model coordinates, not world coordinates! (If you want the terrain height surrounding your
model to be orig_H, use 0, not the correct mean height above sea level!) Defaults to minimum of
height of ground level (or model, resp.) bounding box.
start_E=<double>
start_N=<double>
start_H=<double> only meaningful if ground==NULL, else H is derived from ground
start_Eye=<double> default: 1.65m
start_az_alt_fov=<az_deg>,<alt_deg>,<fov_deg>
initial view direction and field of view.
7
https://en.wikipedia.org/wiki/Transverse_Mercator_projection
8
Note that Sketchup’s georeferencing dictionary provides a NorthAngle entry, which is
360 −
convergence_angle.
15.4 Model Configuration 219
start_...
defines the view position to be set after loading the scenery. Defaults to center of
model boundingbox.
It is advisable to use the grid coordinates of the location of the panoramic photo (landscape) as
start_...
coordinates, or the correct coordinates and some carefully selected
start_az_alt_fov
in case you want to highlight a certain view corridor (temple axis, . . . ).
In some setups like digital full-dome planetaria it is advisable to disable the use of the
v 23.2
start_az_alt_fov
. You can do that in the Scenery3D configuration dialog or by the entry
ignore_start_az_alt_fov in config.ini.
15.4.4 Concatenating OBJ files
Some automated workflows may involve tiled landscape areas, e.g. to overcome texture limitations
or triangle count limits in simpler tools like Sketchup. In this case you can create separate meshes
in the same coordinate system, but you need to concatenate them. One powerful program to
assemble your parts is again Blender.
In Blender, import the OBJ files
File Import Wavefront .obj
. If your OBJ coordinates have
Z as vertical axis (common for terrestrial models), use “Z up”, “-Y Forward” as import settings for
the coordinate axes. The model will appear south-up.
Blender may not show anything except the default cube because of aggressive camera far plane
clipping. Press
N
and in the
View
set at least the far clipping plane as required to see the full
extent of your terrain model. Then press
View View All
(or
Home
).
The landscape may look white now. Switch on textured view if required (
Alt
+
Z
). If the
scene looks almost black now, reconfigure the light to be sunlight: Select the lamp in the outliner
graph, press the lamp icon and in the
Lamp
select “Sun”. Now the scene should be in full color,
and the Y axis should point towards grid-south.
After importing the first model, you may consider locking it in place to avoid errors. Select the
model in the outliner, select the cube button below, then open
Transform Locks
and lock all. The
other model parts may have to be transformed, and numerical transformation can be added in the
Transform
settings in this menu.
If you have created a VRML (WRL) of some structures in ArcScene, export that without
shifting to center, and import the WRL file in Blender with default orientation “Y up”, “Z forward”.
Models from other sources may still be different.
In the end, all parts should fit neatly together. Blender is a very powerful program, you can
enhance your model as you wish.
When the model configuration is complete, select all relevant parts which you want to have
visible in Stellarium (click on the lines in the outline view containing the object names to light
them up gray, then Rightclick-Select, so that the triangle (mesh) icon has a colored background
circle) and press
Ctrl
+
J
to optionally join them, then export to a single OBJ
File Export
Wavefront .obj
. In the export options, apply “Selection Only”, and “-Y Forward” and “Z Up”
9
.
Verify the new model loads correctly, e.g. in Meshlab
10
!
15.4.5 Beyond 3D: Temporally evolving Models
Stellarium working as “time machine” can display the sky for any calendar date in its range of
valid dates. Also landscapes and human-built structures evolve. Temples are being rebuilt, changed,
re-dedicated or repurposed, new windows are cut, old windows closed. To show landscape and
buildings in the right shape for the time in question, we can make material transparent, so that parts
of the model are not displayed. To allow for archaeological uncertainties in dating construction and
9
https://blender.stackexchange.com/questions/3352/merging-multiple-obj-files
10
https://www.meshlab.net/
220 Chapter 15. Scenery3d – 3D Landscapes
destruction, we can gradually fade in and fade out the model parts in question (Zotti, Schaukowitsch,
and Wimmer, 2018).
To enable this magic, you must combine all your models into one (see section 15.4.4), export as
one OBJ/MTL as usual, and manually edit the MTL file. It is wise to give the material for the parts
in question a reasonable name that you can later identify in the MTL file. Then you simply add
one or both of the new keywords
vis_fadeIn
or
vis_fadeOut
to the material description, with 2
arguments which are the Julian days of begin and end of a phase transition. For sharp transitions,
just use the same JD dates.
# Some structure has been put up around -3100/ -3000
vis_fadeIn 588783.5 625308.5
# Fade away between 500 AD /700 AD
vis_fadeO ut 1903682.5 1976732. 5
15.4.6 Working with non-georeferenced OBJ files
There exists modeling software which produces nice models, but without concept of georeference.
One spectacular example is AutoDesk PhotoFly, a cloud application which delivers 3D models
from a bunch of photos uploaded via its program interface. This “technological preview” is in
version 2 and free of cost as of mid-2011.
The problem with these models is that you cannot assign surveyed coordinates to points in
the model, so either you can georeference the models in other applications, or you must find the
correct transformation matrix. Importing the OBJ in Sketchup may take a long time for detailed
photo-generated models, and the texturing may suffer, so you can cut the model down to the
minimum necessary e.g. in Meshlab, and import just a stub required to georeference the model in
Sketchup.
Now, how would you find the proper orientation? The easiest chance would be with a structure
visible in the photo layer of Google Earth. So, start a new model and immediately
add location
from the Google Earth interface. Then you can import the OBJ with TIG’s importer plugin. If
the imported model looks perfect, you may just place the model into the Sketchup landscape and
export a complete landscape just like above. If not, or if you had to cut/simplify the OBJ to be
able to import it, you can rotate/scale the OBJ (it must be grouped!). If you see a shadow in the
photos, you may want to set the date/time of the original photos in the scene and verify that the
shadows created by Sketchup illuminating the model match those in the model’s photo texture.
When you are satisfied with placement/orientation, you create a
scenery3d.ini
like above with
the command
Plugins ASTROSIM/Stellarium scenery3d helpers Create scenery3d.ini
.
Then, you select the OBJ group, open the
Windows Ruby Console
and readout data by calling
Plugins ASTROSIM/Stellarium scenery3d helpers Export transformation of selected group
.
On the Ruby console, you will find a line of numbers (the
4×4
transformation matrix) which
you copy/paste (all in one line!) into the [model] section in scenery3d.ini.
obj2 grid_trafo = < a11 > , <a12 > ,<a13 >,< a14 >, < a21 > , <a22 > ,< a23 > , < a24 > ,
<a31 >, < a32 > , <a33 >,< a34 >,< a41 > , < a42 > ,<a43 >,< a44 >
You edit the
scenery3d.ini
to use your full (unmodified) PhotoFly model and, if you don’t have a
panorama, take
Zero Horizon
landscape as (no-)background. It depends on the model if you want
to be able to step on it, or to declare
ground=NULL
for a constant-height ground. Run Stellarum
once and adjust the start_N, start_E and zero_ground_height.
15.5 Predefined views 221
15.4.7 Rotating OBJs with recognized survey points
If you have survey points measured in a survey grid plus an image-based model with those points
visible, you can use Meshlab to find the model vertex coordinates in the photo model, and some
other program like CoordTrans in the JavaGraticule3D suite to find either the matrix values to
enter in
scenery3d.ini
or even rotate the OBJ points. However, this involves more math than can
be described here; if you came that far, you likely know the required steps. Here it really helps if
you know how to operate automatic text processors like AWK.
15.5 Predefined views
You can also configure and distribute some predefined views with optional date of interest with your
model in a
viewpoints.ini
file. The viewpoints can be loaded and stored with the viewpoint
dialog which you can call with the button. See the provided “Sterngarten” scene for an example.
These entries are not editable by the user through the interface. The user can always save his own
views, they will be saved into the file
userviews.ini
in the user’s Stellarium user directory, and
are editable.
[ Stor e d V i e w s ]
size =< int > Def i nes how many ent r ies are in th is file .
Pr efix eac h e ntry with its index !
1/ label =< string > The name of t his entry
1/ description = < string > A description of this entry ( can include HT ML )
1/ po s i t i on = <x ,y ,z ,h > The x ,y , z grid coor d i n a t e s
( like ori g_ * or s tart_ * in scenery3d . ini )
+ the current eye heig h t h
1/ vi e w _ f ov = < az_deg , alt_deg , fov_deg > The view direction + FOV
( like s t a rt_az_a l t _ f ov in scenery3d . ini )
; an examp l e for a second entry ( note the 2 at the beginning of ea ch line !)
2/ label = Sign s
2/ description = Two sig ns that desc r i b e the Sterngart e n
2/ po s i t i on = 593155.24 2 1 ,5 3 3 3 3 4 8 . 6 30 4 ,3 2 5 . 72 9 5 80 9 03 8 ,0.8805
2/ vi e w _ f ov = 84. 3 1 5399 , -8.187 0 7 8 , 8 3 . 000000
2/ JD = 2 4 5 1 5 4 5 . 5 [ optional ]
15.6 Example
Let us add a quick example here. A recent paper (Pollard, 2017) claims that the Uffington White
Horse, a geoglyph carved into a hillsite in England during the Bronze Age, may depict the mythical
“Sun Horse”, a common conception of that period.
Unfortunately, as of 2017, the official UK Lidar repository does not include the Uffington
area, so a detailed GIS-based model is not available. We could use EUdem25 data with aerial
imagery, or for a quick look, we just use Sketchup. Yet another unfortunate development: Trimble
declared that after the 5-year transition period from Google to Trimble is over in May 2017, terrain
modelling will be limited to Sketchup Pro. But note that a fresh installation comes with a 30-day
Pro trial time, this should be enough for this example.
First, locate the site in Google Earth at
λ = −1.56718,ϕ = 51.582843
. (Or just search for
“Uffington”.) Try to identify which parts of the landscape may be visible from your site, so you
can estimate which parts of terrain should be included in the model. Open Sketchup, select the
meter-based “Landscape Architecture” template, add
View Toolbars. . .
: Locations. Click on the
“Add Location” button of that toolbar. Enter “Uffington” into the location search dialog. This brings
you close to our site of interest. Clip a part of terrain to import it to Sketchup. Optionally, add more
terrain.
If installed, TIG’s OBJ exporter is available from the
File
menu, or you can use Sketchup Pro’s
built-in OBJ export. Export
UffingtonHorse.obj
to a subdirectory
scenery3d/Uffington
in
222 Chapter 15. Scenery3d – 3D Landscapes
your Stellarium user data directory. The geolocation is stored in an “AttributeDictionary”. To read
this, press
Window Ruby Console
to open the Ruby Console. Then write a few lines of Ruby to
get access to the Georeference dictionary and other data:
model = Sketchup . active_model
at trdicts = model . attribute_dictionaries
at trdicts . each {| d|
puts " AttributeDictionary : %s" % d. name
d. each_pair { |k , v | puts " %s =% s" % [k , v] }
}
model . shadow_ info . each {| k , v | puts " #{ k } #{ v} " }
utm = model . point_to_utm Geom :: Point3d . new (0 ,0 ,0)
puts ( " grid_name = UTM %i %s (% s)" %
[ utm . zone_number , utm . zone_letter , model . get_datum ])
Note the
ModelTranslation
values. Those are inches (of all units!) in the UTM reference
frame and define the model coordinate origin in world coordinates. (Actually, it uses the negative
values.) Multiplication by 2.54 gives cm, and by 0.0254, meters in the UTM coordinate system. We
will use the negatives of these values as
orig_E
,
orig_N
,
orig_H
. Additionally, we have found
information about meridian convergence correction (Sketchup’s
NorthAngle
), UTM zone number
etc. All this goes into our configuration file. Create this file
scenery3d.ini
with the content seen
in fig. 15.1
15.7 Limitations
Models with up to 14 million triangles have been used successfully on a mid-range notebook PC
from 2016. However, take some restrictions into account:
•
The model is rendered in Cartesian coordinates. Earth’s surface is curved. If your model
extends by tens of kilometres, the visible horizon formed by faraway mountains may appear
too high. You can display a landscape polygon defined in the currently displayed Landscape
on top of your 3D scene by activating
Draw horizon polyline in foreground
in the plugin’s
settings dialog.
•
The OBJ format is static. Simulation of interaction with 3D objects is not possible with this
plugin.
Authors and Acknowledgements
Scenery3d was conceived by Georg Zotti for the ASTROSIM
11
project. A first prototype was
implemented in 2010/2011 by Simon Parzer and Peter Neubauer as student work supervised
by Michael Wimmer (TU Wien). Models for accuracy tests (Sterngarten, Testscene), and later
improvements in integration, user interaction,
.ini
option handling, OBJ/MTL loader bugfixes
and georeference testing by Georg Zotti.
Andrei Borza in 2011/12 further improved rendering quality (shadow mapping, normal map-
ping) and speed (Zotti, 2015; Zotti and Neubauer, 2012a; Zotti and Neubauer, 2012b).
In 2014–17, Florian Schaukowitsch adapted the code to work with Qt 5 and the Stellarium 0.13
codebase, replaced the renderer with a more efficient, fully shader-based system, implemented
various performance, quality and usability enhancements, and did some code cleanup. Both
Andrei and Florian were again supervised by Michael Wimmer (Zotti, 2016a; Zotti, 2016b; Zotti,
Schaukowitsch, and Wimmer, 2018).
11
https://astrosim.univie.ac.at
15.7 Limitations 223
[ model ]
name = UffingtonHo r se
; Either a fitting landscape or just ’Zero Horizon ’:
la ndscape = Zero Horizon
scenery = Uf f ingtonHors e . obj
; activate the next line if you have a separate ground layer
; ground = UffingtonHorse_ground . obj
; If model Y - axis points up , activate the next line
; obj_order = XZY
author = Georg Zotti
co pyright =( c ) 2017 Georg Zotti
descripti on = Uffington Horse may represent the Sun Horse . \
See Joshua Pollard in An tiquity 91 356(2017): 406 -20.
[ location ]
name = UffingtonHo r se
country = UK
planetName = Earth
; Set the following to a fitting landscap e
lan dscapeKe y = Zero Horizon
lo ngitude = -1.56718254089355
latitude =51.582 8 4 32749823
altitude =137
[ coord ]
gr id_name =UTM 30 U ( WGS 84)
gridType = UTM
orig_E = 5 99273.02119578
orig_N = 5 715615.15079106
orig_H = 1 36.295297626736
conver g e nce_angle =1.1228436 3 7 71988
; Height used outside the terrain , to not " fall off " the rim .
zero_gr o u n d_height =137
; You may want to reset these coordinates .
; Observer is set to those on loading the scenery .
start_E = 5 9 9273.02119578
start_N = 5 7 1 5615.15079106
start _ az_alt_fov =50 ,10 ,83
Figure 15.1: scenery3d.ini for the Uffington example.
224 Chapter 15. Scenery3d – 3D Landscapes
This work has been originally created during the ASTROSIM project supported 2008-2012
by the Austrian Science Fund (FWF) under grant number P 21208-G19. Further development has
partially been supported by the Ludwig Boltzmann Institute for Archaeological Prospection and
Virtual Archaeology in Vienna, Austria
12
.
If you are using this plugin in scientific work, please cite: (Zotti, 2016a; Zotti, 2016b; Zotti,
2019; Zotti, Frischer, et al., 2019; Zotti, S. Hoffmann, et al., 2021; Zotti, Schaukowitsch, and
Wimmer, 2018).
12
https://archpro.lbg.ac.at
16. Stellarium at the Telescope
Stellarium is great for indoor use on the desktop, but it is also very useful outdoors under the real
sky, and several plugins enhance its usability particularly for observers.
Two plugins are bundled with Stellarium which are designed to be used at the telescope:
Oculars (section 16.1), which provides field of view hints for telescopes, oculars and sensors, and
TelescopeControl (section 16.2), which allows you to send GOTO commands to most motorized
telescope mounts. Other GOTO telescopes are supported by external programs which you must
install separately: RTS2 (section 16.2.6), INDI (section 16.2.7) or ASCOM (section 16.2.8). This
can also help DIY hardware tinkerers who like to build their own control systems (section 16.2.10).
In addition, the Observability plugin (section 16.3) can be used for planning the best times to
observe your favorite objects.
16.1 Oculars Plugin
TIMOTHY REAVES, WITH ADDITIONS BY ALEXANDER WOLF
This plugin serves several purposes:
•
to see what the sky looks like through a particular combination of eyepiece, lens (Barlow or
Shapley types) and telescope. This plugin helps to get an idea of what you should see when
looking through a physical telescope, and understand why one eyepiece may be better suited
to observe a particular target than another. This can also be very useful for deciding what
telescope is best suited to a style of viewing. And with the support for binoculars, you also
have the ability to understand just about any type of optics-enhanced visual observing.
•
to show what a particular combination of camera and telescope (or photographic lens) would
be able to photograph of the sky.
•
lastly, with the help of the Telrad sight, understand where object in the sky are in relation to
each other. This can be helpful for star-hopping with a non-GOTO telescope.
None of these activities can take the place of hands-on experience, but they are a good way to
supplement your visual astronomy interests.
226 Chapter 16. Stellarium at the Telescope
Figure 16.1: The on-screen menu (top right) and popup menu (lower right) of the Oculars
plugin.
16.1.1 Using the Ocular plugin
The plugin is controlled through a popup menu or through an on-screen control panel (see top
right corner on screens in fig. 16.17). By default, the hot key to display the popup is
Alt
+
O
(
Option
+
O
for Mac users). This can be changed in the
Editing Keyboard Shortcuts
window
(see section 4.8). The menu will popup where your cursor is located.
The options available in the popup menu depend on what you are currently doing. In the default
menu, you can choose to configure the plugin, activate a CCD, or activate the Telrad finder (see
fig. 16.1). The menu is navigated by either the arrow keys on your keyboard or by your mouse. The
and arrow keys move the selection up or down the menu, and the and arrow keys
display or hide sub-menus. activates an option.
Telrad Finder
The Telrad view can be used without defining any of the items below. As a reflex sight is non-
magnifying, this feature can only be enabled when no eyepiece is selected. You still may want to
zoom in a bit to better see which stars are in the circles (fig. 16.2). The three circles that appear in
the center of the screen are
0.5
◦
,
2.0
◦
, and
4.0
◦
in diameter. They stay centered in the screen, so
move the “telescope” (click-drag the background) to center the circles on the object of interest.
While the Telrad finder is active, you can not activate a CCD with the popup menu, but only
with the on-screen menu.
Figure 16.2: The left image is the default 60
◦
, and the right one is 40
◦
.
16.1 Oculars Plugin 227
CCD Sensors
Figure 16.3: View of M37 through a CCD sensor of the Oculars plugin.
Figure 16.4: View of M37 through a CCD sensor of the Oculars plugin (without on-screen
control panel).
This is a great way to get an idea of what a particular camera will be able to capture when attached
to a particular telescope or lens. For using camera lenses, you must describe them as telescope with
the appropriate values for the lens. When active, this feature will display a red bounding box of the
area that will be captured, as well as zoom in to give a better view of the surroundings. You can
manually zoom in or out from there.
The default CCD view will appear similar to fig. 16.3 or, when you are working without the
on-screen control panel, the information area in the upper right hand corner also shows angular size
captured by the CCD (see fig. 16.4).
When a CCD view is displayed, the popup menu changes as seen in fig. 16.5. You can select
what telescope to use, as well as progress to the previous or next CCD, or go to a specific CCD.
You can also rotate the CCD to better frame your subject, or to see if the CCD can be rotated in
such a way as to catch your area of interest (see fig. 16.6). Once rotated, the CCD frame on screen
displays the new orientation (see fig. 16.7).
228 Chapter 16. Stellarium at the Telescope
Figure 16.5: The CCD sensor popup menu of the Oculars plugin.
Figure 16.6: Setting rotation of CCD sensor in the popup menu.
Figure 16.7: A rotated CCD sensor frame of the Oculars plugin.
16.1 Oculars Plugin 229
Oculars
• Define some eyepieces and telescope (see section 16.1.2).
• Select an object to view (i.e. a star, planet, etc.)
•
Click the toolbar button for toggling the Ocular view, or press
Ctrl
+
O
(
+
O
for
Mac users).
• Swap between eye pieces and telescopes to see how the view changes.
This is really the area of interest to most telescopic observers. It is a great way to compare
different eyepiece/telescope combinations, to see how they change the view of the sky. And it is
easy to do so with binoculars too. To show this, let us use the M37 cluster as target. Through a pair
of Celestron 15x70 binoculars, it would look like in fig. 16.8.
Figure 16.8: The M37 cluster through a Celestron 15x70 binocular.
A very pretty sight. Now, what would it look like through a Celestron 80 mm EDF finder ’scope,
with an Explore Scientific 14 mm 100
◦
eyepiece? See fig. 16.9!
Figure 16.9: The M37 cluster through a Celestron 80 mm EDF with Explore Scientific
14 mm eyepiece.
Not bad at all. But we like to see more! So we move the eyepiece to a C1400. See fig. 16.10 for the
resulting view.
230 Chapter 16. Stellarium at the Telescope
Figure 16.10: The M37 cluster through a Celestron C1400 with Tele Vue Nagler 31 mm
eyepiece.
Very nice indeed! So for this target, the C1400 is going to be the best bet. However, if my
target was the Pleiades, the C1400 with that eyepiece would not be good — the 80EDF would do
much better!
When an eyepiece is active, the popup menu again changes. With a non-binocular eyepiece
selected, you also have the ability to select a particular eyepiece or telescope. When a binocular is
active, you can not select a telescope, as it is not relevant. Changing the eyepiece to a non-binocular
will again allow the telescope to be selected. Also notice that when your mouse cursor is very near
the right hand border of the screen, the popup menu’s sub-menus display to the left, not the right.
Star Scales
As you know from section 4.4.1, the number and relative size of stars of various magnitudes can be
adjusted to your personal preferences in the view settings window to approximate the appearance
of the stars as seen by the naked eye. Some observers prefer to have a simulated ocular view with
very small, or more, stars, quite different from what Stellarium usually shows. The Oculars plugin
therefore keeps two additional sets of scaling values for ocular views and CCD views, which are
activated automatically when you switch to ocular or CCD view, and which are stored immediately
and permanently in the plugin’s ocular.ini file.
1
16.1.2 Configuration
All configuration is done through the user interface in the application. To open the configuration
dialog hit the
Alt
+
O
key, or click the
configure
button on the plugin setup dialog (available in
the
Plugins
tab of Stellarium’s Configuration window (opened by pressing
F2
or the button in
the left toolbar)), or the rightmost button of the on-screen panel (if displayed in the top right corner
of screen). There are six tabs in the configuration dialog: General, Eyepieces, Lenses, Sensors,
Telescopes, and About. The first five are the ones we are interested in here.
1
The appearance of stars may depend on various other factors: telescope type, ocular type, quality of
optics, seeing, .. . Such details with all combinations cannot meaningfully be stored, though. These values
should allow a rapid toggle on any single night.
16.1 Oculars Plugin 231
General
The first option allows you to define the general behavior of the plugin. The options are grouped by
areas of usage: Interface, Ocular view, Sensor view and Telrad view (see figure 16.11).
Figure 16.11: General tab of the Oculars plugin configuration dialog.
Interface: this group of options allows to change behavior of the plugin in general.
On-screen control panel:
show an additional GUI panel in the top-right corner of the
screen to allow switching features of the plugin (in addition to the popup window).
Restore FOV to initial values and
Restore direction to initial values
options allow restoration field of view and direction of
view, resp., to the initial values at program start at the end of the plugin usage (e.g.,
when disabling the view through CCD frame).
Show resolution criteria
compute and show Rayleigh criterion, Dawes’, Abbe’s and Spar-
row’s limits for combination of telescope, lens and eyepiece. In addition, this option
will show visual resolution for selected “setup”. This option may be very helpful for
double star observers.
Show oculars button on toolbar
option allows to toggle visibility the plugin button on
main toolbar.
Arrow button scale
allows to change the size of the arrow buttons in the ocular GUI panel.
Line Color Select color for ocular and sensor outlines and their labels.
Text Color
Select color for screen messages which are shown only when the on-screen
control panel is not shown.
Ocular view
is a group of options that allows to change the plugin’s behavior in visual observation
mode.
Enable only if an object is selected
– uncheck this option if you want to use the visual
observation mode when no object is selected.
Auto-limit stellar magnitude
sets the magnitude limitation for stars based on telescope
diameter. When disabled, the main program’s setting applies (see section 4.4.1). Note
that two manual limits for ocular view and main program are handled, and switching
between ocular and main view also switches those values.
Hide grids and lines when enabled
allows to hide grids and lines when you observe the
sky through the eyepiece and re-enables their visibility when leaving visual observation
mode.
232 Chapter 16. Stellarium at the Telescope
Scale image circle
option allows you to define whether or not to scale the images based on
apparent FOV. When deactivated, the image circle will fill your screen. In general,
we recommend you not select this, unless you have a need to, because it can really
reduce the image size on the screen. It can however be very useful in comparing
two eyepieces. If you set this option, the on-screen image will be scaled based on
the eyepieces and telescopes you define. See section 16.1.3 for information on what
scaling means, and why you might want to use it.
Use semi-transparent mask
uncheck this option if you want to see visible field of view as
in real telescope. You may define level of transparency for mask.
Hide grids and lines when enabled
allows to hide grids and lines when you observe the
sky through the eyepiece and re-enables their visibility when leaving visual observation
mode.
Show FOV outline
option enables drawing the border of the eyepiece’s FOV and it may be
helpful in combination with a semi-transparent mask.
Show compass rose
option enables drawing cardinal directions in the equatorial coordinate
system.
Align crosshair
option enables alignment of the cross-hair according to the equatorial
coordinate system.
Sensor view
is group of options allows to change behavior of the plugin for photographic observa-
tions mode.
Enable autozoom when switching CCD
Use degrees and minutes for FOV of CCD
– for many cases the use of decimal degrees
for the value of the field of view is not comfortable, and this option allows to use the
more human readable format for FOV.
Use horizontal coordinates instead of equatorial (J2000.0) coordinates
in the top left
frame corner.
Show max exposure time for moving objects
For solar system objects, the top right edge
can indicate the maximum exposure time so that the object moves less than a pixel
against the stars.
Enable automatic switch of mount type
allows to store the CCD frame orientation when
the type of telescope mount is changed.
Show sensor crop overlay
toggles drawing a crop box within the CCD frame. In addition,
a pixel grid can be drawn within the crop overlay especially for astrophotographers.
Show focuser overlay
allows drawing a circle which represents the telescope’s focuser.
We added sizes of 3 common modern focusers to allow users to check the visible
aberrations in the FOV of the telescope.
Telrad view
is a group of options which allows to change behavior of the plugin for Telrad mode.
Enable autozoom when switching Telrad
option allows you to define whether or not to
zoom the field of view to twice the size of the Telrad circles.
FOV:
If you don’t use the original Telrad but a similar device, you may define up to 4
circles to show its specific FOV in the sky.
Eyepieces
This is the tab used to enter your own eyepieces (see figures 16.12 and 16.13). By default, a few
sample ones have been added; feel free to delete those once you’ve entered your own.
The fields on this tab are:
Name
– a free-text description of the eye piece. You could modify this to match your personal
descriptions of eyepieces.
aFOV – apparent field of view in degrees.
16.1 Oculars Plugin 233
Figure 16.12: Eyepieces tab of Oculars plugin configuration dialog.
Figure 16.13: Eyepieces tab of Oculars plugin configuration dialog (settings for binocular).
234 Chapter 16. Stellarium at the Telescope
Focal Length – eyepiece focal length in mm.
Field Stop
– the field stop of the eyepiece in
mm
. This is used to calculate the true field of view of
an eyepiece. If you do not know what it is just leave it the default zero. Not all manufacturers
provide this value; Tele Vue is one that does.
Binoculars
– selecting this checkbox tells the system that this eyepiece is binoculars or finders;
this means that this eyepiece can be used without defining a telescope.
Has permanent cross-hairs
– selecting this checkbox tells the system that this eyepiece or binoc-
ular (finder) has also simple cross-hairs
2
.
When Binoculars are described, the relevant fields change to
tFOV
– true field of view in degrees. The true field of view can be given as meters at 1000 m.
The approximate conversion of this to degrees is to divide by 17.5. Thus, 87 m at 1000 m
= (87/17.5)
◦
≈ 5
◦
.
Magnification factor – the magnification of the binocular.
Diameter – the diameter of the binocular objective in mm.
For binoculars, we’re computed a few important factors in additional to the exit pupil
3
(these
factors are visible in an on-screen control panel):
Relative Brightness.
This is the square of the diameter of the exit pupil. For example, for a 10x50
binocular, the exit pupil is 5
mm
and relative brightness is
(50/10)
2
= 5
2
= 25
. However,
the calculation for a 20x100 binocular, through which a great deal more can be seen, gives
exactly the same relative brightness:
(100/20)
2
= 5
2
= 25
, so this is an inadequate rating
to use for astronomical binoculars. Relative brightness is a number used to compare the
brightness of binoculars of similar magnification. The larger the relative brightness number,
the brighter the image.
Twilight Factor
(Twilight Index or Twilight Performance Factor). This was used by Carl
Zeiss International as an indication of the distance at which comparable detail would be
seen in different binoculars. It’s calculated by finding the square root of the product of the
magnification and aperture. For the two binoculars above, the calculations are:
p
(10∗50) =
p
(500) = 22.36
p
(20∗100) =
p
(2000) = 44.72
In this instance, the larger binocular has an index that is double that of the smaller binocular.
Twilight factor is a number used to compare the effectiveness of binoculars used in low light.
The larger the twilight factor, the more detail you can see in low light.
Bishop Index
(or Visibility Factor). This is due to Roy Bishop (Bishop, 2002) and is evaluated
simply by multiplying the magnification by the aperture in
mm
. For our two binocular above,
we obtain:
10∗50 = 500
20∗100 = 2000
The larger binocular has a visibility factor four times greater than the smaller one.
Adler Index
(or Astro Index). This is due to Alan Adler (Adler, 2002) and is evaluated as the
product of the magnification and the square root of the aperture in
mm
. For our two binocular
above, we obtain:
10∗
√
50 = 10 ∗7.1 = 71
20∗
√
100 = 20 ∗10 = 200
2
The Oculars plugin supports eyepieces with reticle patterns – both special eyepieces are available in the
default list of eyepieces, and the option Has permanent cross-hairs is not related to those eyepieces.
3
The exit pupil diameter is calculated by dividing the aperture by the magnification.
16.1 Oculars Plugin 235
This gives the larger binocular an Astro Index of 2.8x the smaller one. At the moment this is
the best index to comparison of astronomical binoculars (of course for the simplest indexes,
because others have tried to expand on these by including the effect of coatings, baffles, and
other aspects of individual quality).
Lenses
This is the tab used to enter your own focal extender or reducer lenses (see figure 16.14). By default,
a few sample ones have been added; feel free to delete them once you’ve entered your own.
Figure 16.14: Lenses tab of Oculars plugin configuration dialog.
The fields on this tab are:
Name
– a free-text description of the lens. You could modify this to match your personal descrip-
tions of lenses.
Multiplier
– a factor larger than 1 expands the focal length, and lenses with this type are named
Barlow lens; a factor less than 1 reduces the focal length, and lenses with this type are named
Shapley lens or focus reducer.
Sensors
This tab allows you to define sensors for any camera you may have (see figure 16.15). When defined
and selected, this will draw a red bounding rectangle in the center of the eye piece view, showing
what the CCD will capture. Because of the way floating point numbers are stored, sometimes you
may see one of your defined values change (for example from 2.2 to 2.19999) but this should not
affect what you see.
Figure 16.15: Sensors tab of Oculars plugin configuration dialog.
The fields on this tab are:
Name – A free-text description of the sensor.
Resolution x – the width of the sensor in pixels.
236 Chapter 16. Stellarium at the Telescope
Resolution y – the height of the sensor in pixels.
Chip width – the width of the sensor in mm.
Chip height – the height of the sensor in mm.
Rotation Angle – the rotation angle of the sensor, in degrees.
Binning x – the binning factor for the width of the sensor.
Binning y – the binning factor for the height of the sensor.
Off-Axis guider
– selecting this checkbox tells the system that this sensor has support an off-axis
guider also.
Prism/CCD distance
– distance between center of prism/CCD of Off-Axis Guider and optical
axis of telescope in mm.
Prism/CCD width – the width of the prism/CCD of Off-Axis Guider in mm.
Prism/CCD height – the height of the prism/CCD of Off-Axis Guider in mm.
Position Angle – the position angle of the prism/CCD of Off-Axis Guider, in degrees.
The resolution is easy to find: these are simply the image dimensions of a (non-binned) frame. The
chip size and pixel size may be more difficult, but the manual, or searching the Internet, should turn
up these values. For a “full-frame” DSLR, this should be close to 36x24
mm
, while APS-C should
be around 22.5x15mm. Some cameras may have unsquare pixels.
Telescopes
This is the tab used to enter your own telescopes and photographic objectives (see fig. 16.16). The
fields on this tab are:
Figure 16.16: Telescopes tab of Oculars plugin configuration dialog.
Name – A free-text description of the telescope.
Focal Length – telescope focal length f in mm.
Diameter
– telescope diameter (aperture
) in
mm
. If you add a photographic objective that
does not provide this information but provides a largest f stop like “100
mm
f/2.8”, you can
estimate from = f /s, where s = 2.8 and thus = 100/2.8 = 35.7mm in this example.
Horizontal flip – if the view through this telescope should flip horizontally.
Vertical flip – if the view through this telescope should flip vertically.
Equatorial Mount – select it if this telescope has an equatorial mount.
16.1.3 Scaling the eyepiece view
I (TR) would like to thank Al Nagler over at Tele Vue
4
for helping to set me straight on the topic of
eyepieces. They are a lot more complicated than you might think!
By default, the view drawn on your computer screen when the plugin is active fills the screen.
That is, there is a circle drawn to represent the view through the eyepiece, and this circle will fill
the screen. For general use, this is what most people would want. There will be times that it’s not.
4
https://www.televue.com/
16.1 Oculars Plugin 237
If you are going to be observing any deep space object, it can be very important to choose the
best eyepiece for that object. You will typically want an eyepiece that will magnify the object as
much as possible, while showing all of the object in the eyepiece view. Getting this can be tricky,
especially if you do not like changing eyepieces at the telescope. Or maybe you want to understand
why one type of telescope may be better than another type for observing what you are interested in.
This is where you will want to scale the image on screen based on your eyepiece.
Different eyepieces generally have a different apparent field of view (aFOV). An easy way
to think about this is: the larger the aFOV, the bigger the picture you see in the eyepiece. Older
types of eyepiece (some types still built and in wide use today have been constructed in the 19th
century) generally have their aFOV in the
50
◦
range. Today, there are massive eyepieces available
with
82
◦
, and recently even
100
◦
aFOV! These eyepieces are huge, as they require a lot of very
special glass to achieve their incredible fields of view. An eyepiece of the same focal length with a
100
◦
aFOV will produce an image through the eyepiece that is twice as wide as one produced by a
50
◦
eyepiece.
Different telescopes, with an eyepiece of a given aFOV, will also produce a different true field
of view. This is the actual size of the piece of sky that you see through the eyepiece. Getting these
two “just right” can be very important. It’s easy to assume that you want the biggest telescope
you can get, with the eyepiece that gives you the highest magnification. This is never true in
reality. Depending on where you live, and especially what you like to look at, a 100-120
mm
quality
refractor with a wide aFOV eyepiece may very well be better than a large SCT with the same
eyepiece. This is something I learned the hard way.
So how does scaling the eyepiece view help? The plugin will find the eyepiece you have with
the largest aFOV. This aFOV becomes
100%
of the computer screen diameter. Then, any other
eyepiece will have its aFOV compared, and the view on screen will be scaled down accordingly.
These
100
◦
aFOV eyepieces makes the math here easy. If you have one, then when that eyepiece
is used, the circle that represents the view through the eyepiece will take up
100%
of the screen
diameter. Next, if you select an eyepiece with an
82
◦
aFOV, its view will be scaled to
82%
of the
screen, and a 62
◦
aFOV eyepiece will be scaled to 62% of the screen.
Example in action
This is easier to understand in action, so let us look at an example that uses three eyepieces all with
the same 17
mm
focal length, so they all produce the same level of magnification (well, one has
an 17.3
mm
focal length, but its magnification is nearly identical) and see how the view changes.
These example all use a Celestron C8 8" SCT telescope, and the target is the Great Orion Nebula.
We can see from the images in fig. 16.17 that the target is all three images is the same size.
The
100
◦
image fills the screen, the
82
◦
is smaller, and the
62
◦
is smallest yet, filling
62%
of the
computer screen. Note that in each image, the field of view that you see changes. The larger the
aFOV, the more you can see of the sky. So in this example, if you had an 8" telescope, you would
want to use the 17mm 100
◦
Ethos eyepiece to see as much of the nebula as possible.
238 Chapter 16. Stellarium at the Telescope
Figure 16.17: Comparing apparent fields of view of (top) a 17
mm
Tele Vue Ethos eyepiece
with an aFOV of
100
◦
. Magnification is
119.5×
. (center) a 17
mm
Tele Vue Nagler
eyepiece with an aFOV of
82
◦
. Magnification is
119.5×
. (bottom) a 17.3
mm
Tele Vue
Delos eyepiece with an aFOV of 62
◦
. Magnification is 117.5×.
16.2 TelescopeControl Plugin 239
16.2 TelescopeControl Plugin
This plugin provides a simple control mechanism for motorized telescope mounts. The user selects
an object (i.e. by clicking on something – a planet, a star etc.) and presses the telescope go-to key,
and the telescope will be guided to the object.
Multiple telescopes may be controlled simultaneously.
WARNING
Stellarium cannot prevent your telescope from being pointed at the Sun. It is up to you to ensure
proper filtering and safety measures are applied!
Never point your telescope at the Sun without a proper solar filter installed. The powerful light
amplified by the telescope WILL cause irreversible damage to your eyes and/or your equipment.
Even if you don’t do it deliberately, a slew during daylight hours may cause your telescope to
point at the sun on its way to the given destination, so it is strongly recommended to avoid using
the telescope control feature before sunset without appropriate protection.
16.2.1 Abilities and limitations
This plug-in allows Stellarium to send ’slew’ (’go to’) commands to the device and to receive its
current position. There are some scopes which additionally support ’sync’ commands to be received
in order to update the internal pointing model of the mount. Some scopes also have the ability
to abort a previous slew command. However, users should always be aware of the possibility for
mount collisions and similar situations. You should always make sure that a slew does not cause
parts of the telescope to collide with the environment or mount itself.
Currently this plug-in does not allow satellite tracking unless the controlled telescope is an
RTS2 system (see section 16.2.6), and is not very suitable for lunar or planetary observations. Many
mounts can be set to a ’lunar’ tracking speed, you may prefer this.
Some users are running Stellarium on little, low-power “Telescope computers” connected to
their powerful indoor PCs via RemoteDesktop or similar setups. Keep in mind that Stellarium
is a graphics-heavy program that may challenge the outdoor computer’s graphics subsystem or
network. See framerate intent settings on page 27 for optimizing your screen refresh rates. Better,
run Stellarium on your indoor system and use INDI or ASCOM network protocols.
16.2.2 Using this plug-in
Here are two general ways to control a device with this plug-in, depending on the situation:
DIRECT CONNECTION
A device supported by the plug-in is connected with a cable to the
computer running Stellarium
INDIRECT CONNECTION
local
A device is connected to the same computer but it is driven by a stand-alone telescope
server program or a third-party application that can ’talk’ to Stellarium;
remote
A device is connected to a remote computer and the software that drives it can
’talk’ to Stellarium over the network; this software can be either one of Stellarium’s
stand-alone telescope servers, or a third party application.
Most older telescopes use cables that connect to a serial port (RS-232), the newer ones use USB
(Universal Serial Bus). On Linux and Max OS X, both cases are handled identically by the plug-in.
On Windows, a USB connection may require a ’virtual serial port’ software, if it is not supplied
with the cable or the telescope. Such a software creates a virtual (’fake’) COM port that corresponds
to the real USB port so it can be used by the plug-in. On all three platforms, if the computer
has no ’classic’ serial ports and the telescope can connect only to a serial port, a serial-to-USB
(RS-232-to-USB) adapter may be necessary.
240 Chapter 16. Stellarium at the Telescope
Telescope set-up (setting geographical coordinates, performing alignment, etc.) should be done
before connecting the telescope to Stellarium.
16.2.3 Main window (’Telescopes’)
The plug-in’s main window can be opened:
•
By pressing the
configure
button for the plug-in in the
Plugins
tab of Stellarium’s Configu-
ration window (opened by pressing
F2
or the
button in the left toolbar).
•
By pressing the
Configure telescopes...
button in the
Slew to
window (opened by pressing
Ctrl
+
0
or the respective button on the bottom toolbar).
The
Telescopes
tab displays a list of the telescope connections that have been set up:
•
The number (#) column shows the number used to control this telescope. For example, for
slewing telescope #2, the shortcut is
Ctrl
+
2
.
•
The Status column indicates if this connection is currently active or not. Unfortunately, there
are some cases in which ’Connected’ is displayed when no working connection exists.
• The Type field indicates what kind of connection this is:
virtual means a virtual telescope (test mode).
local, Stellarium means a DIRECT connection to the telescope (see above).
local, external
means an INDIRECT connection to a program running on the same com-
puter.
local, ASCOM
means an INDIRECT connection to a ASCOM driver running on the same
computer.
remote, unknown means an INDIRECT connection over a network to a remote machine.
remote, RTS2 means an INDIRECT connection over a network to an RTS2 server.
remote, INDI means an INDIRECT connection over a network to an INDI server.
To set up a new telescope connection, press the
Add
button. To modify the configuration of an
existing connection, select it in the list and press the
Configure
button. In both cases, a telescope
connection configuration window will open.
16.2.4 Telescope configuration window
Connection type
The topmost field represents the choice between the types of connections (see section 16.2.2):
Telescope controlled by:
Stellarium, directly through a serial port is the DIRECT case
External software or a remote computer is an INDIRECT case
RTS2 Telescope is another INDIRECT case
INDI is another INDIRECT case
ASCOM is another INDIRECT case
Nothing, just simulate one (a moving reticle) is a virtual telescope (no connection)
Telescope properties
Name is the label that will be displayed on the screen next to the telescope reticle.
Connection delay
If the movement of the telescope reticle on the screen is uneven, you can try
increasing or decreasing this value.
Coordinate system
Some Celestron telescopes have had their firmware updated and now interpret
the coordinates they receive as coordinates that use the equinox of the date (EOD, also
known as JNow), making necessary this setting. With ASCOM telescopes it’s also possible
to use this setting to override the default device preference.
Start/connect at startup
Check this option if you want Stellarium to attempt to connect to the
16.2 TelescopeControl Plugin 241
telescope immediately after it starts. Otherwise, to start the telescope, you need to open the
main window, select that telescope and press the
Start/Connect
button.
Device settings
This section is active only for DIRECT connections (see above).
Serial port
sets the serial port used by the telescope. There is a pop-up box that suggests some
default values:
• On Windows, serial ports COM1 to COM10
•
On Linux, serial ports
/dev/ttyS0
to
/dev/ttyS3
and USB ports
/dev/ttyUSB0
to
/dev/ttyUSB3. Make sure you have read/write access to the tty device. Depending
on your flavour of Linux, this may e.g. require some group membership.
•
On Mac OS X, the list is empty as it names its ports in a peculiar way. If you are using
a USB cable, the default serial port of your telescope most probably is not in the list of
suggestions. To list all valid serial port names in Mac OS X, open a terminal and type:
ls / dev /*
This will list all devices, the full name of your serial port should be somewhere in the
list (for example, /dev/cu.usbserial-FTDFZVMK).
Device model : see 16.2.5 Supported devices.
Connection settings
Both fields here refer to INDIRECT connections, which implies communication over a network
(TCP/IP).
Host
can be either a host name or an IPv4 address such as ’127.0.0.1’. The default value of
’localhost’ means ’this computer’.
Modifying the default host name value makes sense only if you are attempting a remote
connection over a network. In this case, it should be the name or IP address of the computer
that runs a program that runs the telescope.
Port
refers to the TCP port used for communication. The default value depends on the telescope
number and ranges between 10001 and 10009.
RTS2 settings
(see also 16.2.6) You will need access to an RTS2 HTTPD server through HTTP/JSON calls. Please
see RTS2 documentation (man rts2-httpd) for details. You will as well need username and password
for HTTPD. Please be aware that in order to move the telescope, your user must have the telescope
in the list of allowed devices in the database. Please see
man rts2-user
for details on how to
manipulate RTS2 users.
URL
points to RTS2 HTTPD. Can include anything a URL can have - port (:8889) and prefix path
for RTS2 access.
Username username used for login to RTS2 HTTPD.
Password password for login to RTS2 HTTPD.
INDI settings
(see also 16.2.7) You will need access to an INDI server through a TCP/IP connection. Please see
INDI documentation for details. You will need to select the correct INDI device to manage it.
ASCOM settings
You can choose an ASCOM telescope driver installed in your system using the ASCOM chooser.
Additionally you can choose how Stellarium is determining the coordinate system used to commu-
nicate with the ASCOM mount. For more information, please see 16.2.8.
242 Chapter 16. Stellarium at the Telescope
User Interface Settings: Field of view indicators
A series of circles representing different fields of view can be added around the telescope marker.
This is a relic from the times before the Oculars plug-in (see 16.1) existed.
Activate the ’Use field of view indicators’ option, then enter a list of values separated with
commas in the field below. The values are interpreted as degrees of arc.
These marks can be used in combination with a virtual telescope to display a moving reticle
with the Telrad circles.
’Slew telescope to’ window
The
Slew telescope to
window can be opened by pressing
Ctrl
+
0
or the respective button in
the bottom toolbar.
It contains two fields for entering celestial coordinates, selectors for the preferred format
(Hours-Minutes-Seconds, Degrees-Minutes-Seconds, or Decimal degrees), a drop-down list and
two buttons.
The drop-down list contains the names of the currently connected devices. If no devices are
connected, it will remain empty, and the
Slew
button will be disabled.
Pressing the
Slew
button slews the selected device to the selected set of coordinates. See the
section about keyboard commands below for other ways of controlling the device.
Pressing the
Configure telescopes. . .
button opens the main window of the plug-in.
TIP: Inside the ’Slew’ window, underlined letters indicate that pressing
Alt
+
underlined letter
can be used instead of clicking. For example, pressing
Alt
+
S
is equivalent to clicking the
Slew
button, pressing
Alt
+
E
switches to decimal degree format, etc.
Sending commands
Once a telescope is successfully started/connected, Stellarium displays a telescope reticle labelled
with the telescope’s name on its current position in the sky. The reticle is an object like every other
in Stellarium - it can be selected with the mouse, it can be tracked and it appears as an object in the
’Search’ window.
To point a device to an object: Select an object (e.g. a star) and press the number of the device
while holding down the
Ctrl
key. (For example,
Ctrl
+
1
for telescope #1.) This will move the
telescope to the selected object. Note that most telescopes can only execute a single command
to move to that object’s position, but if the telescope is an RTS2 telescope, you can even track a
satellite (if the mount then is fast enough to support it).
5
To point a device to the center of the view: Press the number of the device while holding down
the Alt key. (For example,
Alt
+
1
for telescope #1.) This will slew the device to the point in
the center of the current view. (If you move the view after issuing the command, the target won’t
change unless you issue another command.)
To point a device to a given set of coordinates: Use the
Slew to
window (press
Ctrl
+
0
).
16.2.5 Supported devices
Directly connected telescopes
All devices listed in the ’Device model’ list are convenience definitions using one of the two built-in
interfaces: the Meade LX200 (the Meade Autostar controller) interface and the Celestron NexStar
interface.
The device list contains the following:
Celestron NexStar (compatible) Any device using the NexStar interface.
5
Actually, the TLE orbital elements of the selected satellite are transmitted to RTS2, which does then
compute the satellite position itself.
16.2 TelescopeControl Plugin 243
Losmandy G-11
A computerized telescope mount made by Losmandy (Meade LX-200/Autostar
interface).
Meade Autostar compatible Any device using the LX-200/Autostar interface.
Meade ETX-70 (#494 Autostar, #506 CCS)
The Meade ETX-70 telescope with the #494 Au-
tostar controller and the #506 Connector Cable Set. According to the tester, it is a bit slow,
so its default setting of ’Connection delay’ is 1.5 seconds instead of 0.5 seconds.
Meade LX200 (compatible) Any device using the LX-200/Autostar interface.
Sky-Watcher SynScan AZ mount
The Sky-Watcher SynScan AZ GoTo mount is used in a num-
ber of telescopes.
Sky-Watcher SynScan (version 3 or later)
SynScan is also the name of the hand controller used
in other Sky-Watcher GoTo mounts, and it seems that any mount that uses a SynScan
controller version 3.0 or greater is supported by the plug-in, as it uses the NexStar protocol.
Wildcard Innovations Argo Navis (Meade mode)
Argo Navis is a ’Digital Telescope Computer’
by Wildcard Innovations. It is an advanced digital setting circle that turns an ordinary
telescope (for example, a dobsonian) into a ’Push To” telescope (a telescope that uses a
computer to find targets and human power to move the telescope itself). Just don’t forget to
set it to Meade compatibility mode and set the baud rate to 9600B1.
RTS2 telescopes
Setting up a robotic telescope and dome control system with RTS2 is beyond the scope of this
handbook, but see section 16.2.6 for a few notes to be able to connect and command the telescope
with Stellarium. Please refer to the RTS2 Web pages
6
for further details.
Please be aware that some RTS2 usernames might have only read-only access. If this is case for
your username, the telescope marker will be painted red (or
color_telescope_readonly
from
Stellarium’s settings file).
INDI telescopes
Setting up a robotic telescope and dome control system with INDI is beyond the scope of this
handbook, but see section 16.2.7 for a few notes to be able to connect and command the telescope
with Stellarium. Please refer to the INDI web pages
7
for further details.
ASCOM telescopes
ASCOM specific settings can be configured when a ASCOM telescope was selected. Please see
section 16.2.8 for further information about configuration possibilities.
Virtual telescope
If you want to test this plug-in without an actual device connected to the computer, choose “Nothing,
just simulate one (a moving reticle)” in the
Telescope controlled by:
field. It will show a telescope
reticle that will react in the same way as the reticle of a real telescope controlled by the plug-in.
See the section above about field of view indicators for a possible practical application (emulating
’Telrad’ circles).
16.2.6 RTS2
RTS2, the Remote Telescope System 2, is a complete robotic observatory control system for Linux
by Petr Kubánek, who kindly provided the plugin code to make RTS2 interoperate with Stellarium.
We cannot give a full manual or any further support for RTS2 here, please refer to its website
8
for
6
https://rts2.org/
7
https://indilib.org
8
https://rts2.org
244 Chapter 16. Stellarium at the Telescope
complete instructions about dome control, cameras, filter wheels, weather sensors, etc. A few notes
may be useful for beginners, though.
RTS2’s central piece is a daemon. Start the system:
sudo service rts2 start
RTS2’s main control screen is text-based, rts2-mon. For a quick check, switch on the system using
F9
. Telescope
T0
is a dummy telescope which you can select and operate with commands like
move 120 35
(this moves to RA=120
◦
=8h, DEC=35
◦
, but only when this position is above your
horizon).
Stellarium’s Telescope plugin can communicate with RTS2 using the RTS2 web interface. You
must run rts2-httpd for this, which may require the right permissions to write the lock files in
/var/run
. This program requires that a database has been created as described in the file
RUN
in
RTS2’s source directory and on the RTS2 website
9
. Also, you must create a ’user’ for RTS2. This
is not a regular Linux account, but an entry in the RTS2 database. Create a user with rts2-user -a
<user>. You should use a password different from your regular Linux password, as this will be
transmitted in plain text between the computer running Stellarium and the RTS2 control computer,
and may also be written into Stellarium’s logfile. Then you can enable device control for the
respective user. If you want to send slew commands from Stellarium, make sure to allow access to
telescope
T0
. If not, Stellarium will be able to show the telescope marker, but you will not be able
to control the telescope. To enable control for existing users in the default stars database,
psql stars
update users set all o wed_devices = ’* ’;
In case you cannot properly connect to the RTS2 telescope or cannot send slew commands,
check Stellarium’s logfile log.txt for some diagnostic messages.
RTS2 is the only type of telescope supported by Stellarium which can autonomously track
satellites. Tracking accuracy fully depends on Stellarium’s TLE satellite elements being up-to-date
(see section 14.8) and the accuracy of your RTS2 installation.
16.2.7 INDI
INDI, the Instrument Neutral Distributed Interface, is a distributed control system (DCS) protocol
to enable control, data acquisition and exchange among hardware devices and software front ends,
emphasizing astronomical instrumentation
10
.
INDI client (v1.6.0) has been incorporated into Stellarium’s Telescope Control plugin by
Alessandro Siniscalchi to allow Stellarium to communicate with INDI hardware drivers via INDI
server. INDI server is a hub that sits between drivers and clients. It reroutes traffic for control
and data across distributed networks. Each device or client in the network is a node and may
communicate with other nodes whenever desired. The server supports broadcasting, chaining, and
marshalling of data.
Stellarium only supports INDI mounts (no other INDI devices), and you will need to select the
correct INDI device to manage it at the stage of configuration of telescope. For this purpose the
plug-in has a tool to getting the list of connected devices from the INDI server (when the server is
working!). Please define hostname and port
11
in the “INDI Settings” block, press
Refresh devices
and select the required device in the list “Devices”.
List of telescope types supported by INDI
12
:
9
https://rts2.org/faq.html
10
https://en.wikipedia.org/wiki/Instrument_Neutral_Distributed_Interface
11
The Internet Assigned Numbers Authority (IANA) has assigned to INDI the Transmission Control
Protocol and User Datagram Protocol (TCP/UDP) port 7624.
12
https://indilib.org/devices/telescopes/all.html
16.2 TelescopeControl Plugin 245
• Meade Autostar
• Meade LX200 (Classic/GPS/16)
• Celestron NexStar
• Celestron NexStar Evolution
• Orion Synscan Telescope
• EQ-6 MCU Update
• HEQ-5 MCU Update
• LittleFoot Vpower
• LittleFoot Elegance Photo
• Astro-Electronic FS-2
• EQMod
• Pulsar2
• SkySensor2000PC
• Takahashi Temma
• 10 Micron
• Losmandy Gemini
• Astrophysics
• Skywatcher Virtuoso (Alt/Az)
• IOptron IEQPro/CEM60
• IOptron ZEQ25/SmartEQ
• IOptron GotoNova Upgrade Kit 8400
16.2.8 ASCOM 7 (Windows only)
ASCOM is probably the most widely used way how to communicate with telescopes, mounts and
other astronomy equipment on Microsoft Windows operating systems. The ASCOM platform aims
to decouple device dependent specifics by introducing a common standard for communication
between device drivers and applications. Almost every telescope mount comes with an ASCOM
driver and most of the astronomy software and tools can communicate with ASCOM compatible
devices.
The ASCOM telescope support has been added to Stellarium’s Telescope Control plugin by
Gion Kunz in version 0.19.3.
13
Note that in order for Stellarium to communicate with your ASCOM compatible mount, you
will need to have the ASCOM platform installed on your Windows machine (version 7 or higher
14
).
Also, the ASCOM driver of your telescope mount needs to be installed before you can start using
the telescope in Stellarium.
Important: Most modern ASCOM drivers are written to run in 32bit and 64bit mode (any) and
therefore are compatible with the 64bit and 32bit version of Stellarium. However, if you happen
to have a 32bit or 64bit only driver for your telescope mount, you will also need to install the
respective Stellarium version.
In order to use your ASCOM telescope you need to select the correct device in the ASCOM
chooser by clicking the button
Choose ASCOM telescope
. The selected device is shown below
that button.
By default, Stellarium is trying to ask the ASCOM driver in order to determine if JNow or
13
Unfortunately ASCOM version 6 seems to be incompatible with Qt6. After numerous error reports
we had to disable ASCOM support on Qt6-based builds of version 24.3-24.4. However, preliminary tests
showed that ASCOM 7 may work again, so this way of connection is back. Without proper instruments, the
maintainers depend on your feedback, though. If you depend on ASCOM support, please update to ASCOM
version 7, or use a Qt5-based build of the same version.
14
https://ascom-standards.org/Downloads/Index.htm
246 Chapter 16. Stellarium at the Telescope
J2000 coordinates should be used for communicating with the mount. If you’d like to override this
behavior and tell the ASCOM telescope to communicate in the coordinate system configured in
the section Telescope properties, you can switch the radio button
Let ASCOM device decide
to
Use Stellarium settings
in the ASCOM settings of the Configure Telescope dialog.
16.2.9 StellariumScope
StellariumScope is a free add-on that enables you to control your ASCOM enabled telescope with
Stellarium.
Note that Stellarium supports ASCOM telescopes natively since version 0.19.3. There’s no
need to use StellariumScope in order to use your ASCOM telescopes with Stellarium anymore. We
are encouraging our users to use the native ASCOM option unless they need particular features of
StellariumScope.
The original StellariumScope program was designed and implemented by Scott of ByteArts
but is no longer available. It is now maintained by and available for download from Welsh Dragon
Computing
15
.
Features
• Provides an interface between Stellarium and ASCOM telescope drivers.
•
Provides the ability to both “Sync” and “Slew” the telescope. It’s also possible to issue a
stop/cancel command from Stellarium.
•
You can easily host Stellarium on one computer linked to another control computer that hosts
the telescope driver.
•
The installation program will automatically install the documentation, but the link to the
documentation is provided by the developer
16
so you can read it before installation.
Use this application (like all software that controls your mount) with supervision of your
mount’s movements.
16.2.10 Other telescope servers and Stellarium
Other developers have also been busy creating hard- and software often involving Arduino or
Raspberry Pi boards which can control GOTO or PUSHTO (manually driven but position-aware,
usually Dobsonian) telescopes and are ultimately controlled from Stellarium. Those are not related
nor authored by the Stellarium team, so while we welcome such development (esp. open-sourced)
in general, we cannot provide documentation nor any support.
A few examples:
iTelescope http://simonbox.info/index.php/astronomy/93-raspberry -pi-itelesc
ope
node-telescope-server https://www.npmjs.com/package/node-telescope-server
OnStep https://groups.io/g/onstep
One anonymous user sent a troubleshooting solution when connecting Stellarium to the Cele-
stron NexRemote software:
One tricky Window XP issue I fixed was that my older laptop would transiently lose
connection with Stellarium although the status would still be “Connected” and all
looked normal. [. . . ]
15
http://welshdragoncomputing.ca/x/index.php/home/stellariumscope/about-stellar
iumscope
16
StellariumScope User’s Guide —
http://welshdragoncomputing.ca/x/st/misc/stellari
umscope_user_guide.2016.03.05.pdf
16.2 TelescopeControl Plugin 247
I boosted the NexRemote.exe process in Windows XP to High under Set Priority under
the Windows Task Manager via
Ctrl
+
Alt
+
Del
.
All slews now proceed normally. Problem went away.
17
Stellarium Telescope Protocol
In the early days of Stellarium, telescope control required standalone server programs. These were
later integrated in the plugin. However, there are situations where external control servers are still
useful, e.g. when they are running on some tiny telescope computer while the user sits in the warm
control room in front of the powerful PC running Stellarium. For you DIYers out there, figure 16.18
shows the original protocol.
17
https://sourceforge.net/p/stellarium/discussion/278769/thread/16e4c054/?limi
t=25#8ffa
248 Chapter 16. Stellarium at the Telescope
/*
Author and Copyright of this file and of the stellarium telescope library:
Johannes Gajdosik, 2006
*/
Stellarium Telescope Protocol version 1.0
The Stellarium Telescope Protocol works on top of TCP/IP.
The client is the stellarium program (or any similar program),
the server is called "telescope server" and controls the telescope.
Depending on the implementation the server may handle one or many
simultaneous clients. The reference server implementation accepts
an unlimited number of simultaneous clients.
The protocol is message based: both server and client may
spontaneousely send messages as often as they want.
When the server looses control of the telescope he should
actively close the connection to all clients.
The first two bytes of any message describes the total
length of that message in bytes (including the first 2 bytes).
The next 2 bytes of any message describe the type of this message.
The byte order for all kind of integers is always
"least significiant byte first".
-----------------------
server->client:
MessageCurrentPosition (type = 0):
LENGTH (2 bytes,integer): length of the message
TYPE (2 bytes,integer): 0
TIME (8 bytes,integer): current time on the server computer in microseconds
since 1970.01.01 UT. Currently unused.
RA (4 bytes,unsigned integer): right ascension of the telescope (J2000)
a value of 0x100000000 = 0x0 means 24h=0h,
a value of 0x80000000 means 12h
DEC (4 bytes,signed integer): declination of the telescope (J2000)
a value of -0x40000000 means -90degrees,
a value of 0x0 means 0degrees,
a value of 0x40000000 means 90degrees
STATUS (4 bytes,signed integer): status of the telescope, currently unused.
status=0 means ok, status<0 means some error
---------------------
client->server:
MessageGoto (type =0)
LENGTH (2 bytes,integer): length of the message
TYPE (2 bytes,integer): 0
TIME (8 bytes,integer): current time on the client computer in microseconds
since 1970.01.01 UT. Currently unused.
RA (4 bytes,unsigned integer): right ascension of the telescope (J2000)
a value of 0x100000000 = 0x0 means 24h=0h,
a value of 0x80000000 means 12h
DEC (4 bytes,signed integer): declination of the telescope (J2000)
a value of -0x40000000 means -90degrees,
a value of 0x0 means 0degrees,
a value of 0x40000000 means 90degrees
Figure 16.18: The Stellarium Telescope Protocol, version 1.0
16.3 Observability Plugin 249
16.3 Observability Plugin
This Plugin is activated with the button . It analyzes the observability of the selected object
(or the screen center, if no object is selected). The plugin can show the best epoch of the year (i.e.,
largest angular separation from the Sun), the date range when the source is above the horizon at
dark night, and the dates of Acronychal and Cosmical rise/set. Ephemerides of the Solar-System
objects and parallax effects are taken into account.
Explanation of some parameters
Sun altitude at twilight
Any celestial object will be considered visible when the Sun is below this
altitude. The altitude at astronomical twilight ranges usually between -12 and -18 degrees.
This parameter is only used for the estimate of the range of observable epochs (see below).
Horizon altitude
Minimum observable altitude (due to mountains, buildings, or just a limited
telescope mount).
Acronychal/Cosmical/Heliacal rise/set
The days of Cosmical rise/set of an object are estimated
as the days when the object rises (or sets) together with the rise/set of the Sun. The exact
dates of these ephemeris depend on the Observer’s location. On the contrary, the Acronycal
rise (or set) happens when the star rises/sets with the setting/rising of the Sun (i.e., opposite
to the Sun). On the one hand, it is obvious that the source is hardly observable (or not
observable at all) in the dates between Cosmical set and Cosmical rise. On the other hand,
the dates around the Acronychal set and rise are those when the altitude of the celestial
object uses to be high when the Sun is well below the horizon (hence the object can be
well observed). The date of Heliacal rise is the first day of the year when a star becomes
visible. It happens when the star is close to the eastern horizon roughly before the end of the
astronomical night (i.e., at the astronomical twilight). In the following nights, the star will
be visible during longer periods of time, until it reaches its Heliacal set (i.e., the last night
of the year when the star is still visible). At the Heliacal set, the star sets roughly after the
beginning of the astronomical night.
Largest Sun separation
Happens when the angular separation between the Sun and the celestial
object are maximum. In most cases, this is equivalent to say that the Equatorial longitudes of
the Sun and the object differ by 180 degrees, so the Sun is in opposition to the object. When
an object is at its maximum possible angular separation from the Sun (no matter if it is a
planet or a star), it culminates roughly at midnight, and on the darkest possible area of the
Sky at that declination. Hence, that is the ’best’ night to observe a particular object.
Nights with source above horizon
The program computes the range of dates when the celestial
object is above the horizon at least during one moment of the night. By ’night’, the program
considers the time span when the Sun altitude is below that of the twilight (which can be set
by the user; see above). When the objects are fixed on the sky (or are exterior planets), the
range of observable epochs for the current year can have two possible forms: either a range
from one date to another (e.g., 20 Jan to 15 Sep) or in two steps (from 1 Jan to a given date
and from another date to 31 Dec). In the first case, the first date (20 Jan in our example) shall
be close to the so-called ’Heliacal rise of a star’ and the second date (15 Sep in our example)
shall be close to the ’Heliacal set’. In the second case (e.g., a range in the form 1 Jan to 20
May and 21 Sep to 31 Dec), the first date (20 May in our example) would be close to the
Heliacal set and the second one (21 Sep in our example) to the Heliacal rise. More exact
equations to estimate the Heliacal rise/set of stars and planets (which will not depend on the
mere input of a twilight Sun elevation by the user) will be implemented in future versions of
this plugin.
Full Moon
When the Moon is selected, the program can compute the exact closest dates of the
250 Chapter 16. Stellarium at the Telescope
Moon’s opposition to the Sun.
Note on Terminology
The (sparse) literature on terminology about computing these Heliacal, Acronychal or Cosmic
events seems to disagree on which end of the night is to be computed. While all agree about Heliacal
rises taking place in the morning, Acronychal and Cosmic are sometimes applied in reverse order
from those described here. In case you use these data, make sure you keep this definition as well.
Author
This plugin has been contributed by Ivan Marti-Vidal (Onsala Space Observatory)
18
with some
advice by Alexander Wolf and Georg Zotti.
18
mailto:i.martividal@gmail.com
17. Scripting
A. WOLF, G. ZOTTI, WITH ADDITIONS BY WOLFGANG LAUN
17.1 Introduction
The scripting facility is Stellarium’s version of a Presentation, a feature that may be used to run an
astronomical or other show for instruction or entertainment from within the Stellarium program.
The use of scripts was recognized as a perfect way of arranging a presentation of a sequence of
astronomical events from the earliest versions of Stellarium.
The original Stratoscript was quite limited in what it could do, and so a new Stellarium Scripting
System has been developed.
Since version 0.10.1, Stellarium has included a scripting feature based on the Qt5 Scripting
Engine
1
. This made it possible to write small programs within Stellarium to produce automatic
presentations, set up custom configurations, and to automate repetitive tasks. By version 0.14.0 the
new scripting engine had reached a level where it had all required features for usage, and support
of scripts for the old Stratoscript engine has been discontinued.
The programming language ECMAScript
2
(also known as JavaScript) gives users access to
all basic ECMAScript language features such as flow control, variables, string manipulation and
so on. Its integration with Qt’s QtScript module and the way Stellarium’s main components
(“StelModule”s) have been designed to work means that all module functions which are labeled as
“slots” can be called from JavaScript.
Interaction with Stellarium-specific features is done via a collection of objects which represent
components of Stellarium itself. The various modules of Stellarium, and also activated plugins, can
be called in scripts to calculate, move the scene, switch on and off display of objects, etc. You can
write text output into text files with the
output()
command. You can call all public slots which
are documented in the scripting API documentation
3
.
1
https://doc.qt.io/qt-5/qtscript-index.html
2
https://en.wikipedia.org/wiki/ECMAScript
3
https://www.stellarium.org/doc/25.0/scripting.html
252 Chapter 17. Scripting
With the adaptation to Qt6 in versions 1.0 and later we had to switch to yet another scripting
engine in 2022. Qt6 comes with QJSEngine
4
, another JavaScript engine which behaves mostly
similar to the older QtScript. However, small differences exist, so that care must be taken if scripts
should be developed for both series of Stellarium. Some older scripts will not work on versions 1.0
and later or at least require some adaptations described in section 17.5.
17.2 The Script Console
It is possible to load, edit, run and save scripts using the script console window. To toggle the script
console, press
F12
.
17.2.1 The Tabs in the Console
The three tabs “Script”, “Log” and “Output” each provide a text field. In the “Script” text field you
can edit a script, which can be loaded from and saved to a file, and executed. The “Log” text field
receives all errors and other messages resulting from the script’s execution; the “Output” text field
will show the results of core.output() function calls.
The fourth tab, “Settings”, provides some configuration options.
17.2.2 The Menu Bar
The menu bar contains buttons for loading and saving a script. A file dialog is shown for selecting
the file. The “clear” button lets you clear the contents of the text field in the currently selected
tab. The drop-down menu “Execute:” offers a selection of menu entries, mainly intended to let
you restore the sky to a clean state. The entry “selected text as script” executes selected text
in the “Script” text field, allowing to test scripts during development. Entries “remove screen
text”, “remove screen images” and “remove screen markers” remove labels, images and markers,
respectively, that may have been left over on the screen from previous script actions. Each of
the “clear map” entries results in a call to
core.clear()
, using one of the arguments “natural”,
“starchart”, “deepspace”, “galactic” or “supergalactic”. These calls reset Stellarium’s state, resulting
in a basic state of the display and providing a clean starting point for another run of your script.
The button SSC runs the Stellarium Script Preprocessor with the script in the text field as
input and produces an output by recursively inserting all included scripts into the text. This output
replaces the contents of the Script text field. Store the original script if you need it!
17.2.3 German Keyboards
There is a glitch in the keyboard module of the underlying system that is responsible for keyboard
handling. It affects users of Windows and Linux systems with a German, and probably also other
international keyboards: The key combinations
AltGr
+
8
and
AltGr
+
9
cannot be used for
typing
[
and
]
. You need to work around by copy-pasting these two characters. You can also try to
use a command line argument like -platform windows:altgr.
17.3 Includes
Stellarium provides a mechanism for splitting scripts into different files. Typical functions or lists
of variables or celestial objects can be stored in separate
.inc
files and used within other scripts
through the include() command:
include("common_objects . inc");
4
https://doc.qt.io/qt-6/qtjavascript.html
17.4 Minimal Scripts 253
17.4 Minimal Scripts
This script prints “Hello Universe” in the Script Console log window and into log.txt:
core.debug("Hello Universe ");
This script prints “Hello Universe” in the Script Console output window and into the file
output.txt
which you will also find in the user data directory. The absolute path to the file will also be given in
log.txt.
core.output("Hello Universe ");
The file
output.txt
will be rewritten on each run of Stellarium. In case you need to save a copy
of the current output file to another file, call
core.saveOutputAs(" myImportantData .txt ");
core.resetOutput();
This script uses the LabelMgr module to display “Hello Universe” in red, fontsize 20, on the screen
for 3 seconds.
var label=LabelMgr.labelScreen("Hello Universe ", 200, 200,
true, 20, "# ff0000 ");
core.wait(3);
LabelMgr.deleteLabel(label);
17.5 Critical Scripting Differences introduced with version 1.0
Qt5’s QtScript module which has been used in versions 0.10 to 0.22 was more flexible and easier
to fine-tune than Qt6’s QJSEngine, which is used in the Qt6-based 1.* series of the program, i.e.,
versions 1.0 (22.3) and later. Still, most scripts that have been developed for Stellarium versions
0.10 to 0.22 still run without or with just minor modifications as described in this section.
17.5.1 Pause/Resume
The Qt6-based builds (version 1.0 and later) do not offer a way to pause and resume a script as was
available in the Qt5-based builds (0.10 to 0.22).
17.5.2 The Vec3f problem
One of the most important little helper classes in the main program are three-dimensional vectors.
Vec3f
describe those with single-precision floating point data, and
Vec3d
are those with double-
precision floating point data.
As late as in version 0.19 we added
Vec3f
and later
Vec3d
data types to the Javascript
environment. These allowed addressing variables of C++ classes
Vec3f
or
Vec3d
with named
sub-fields
r
,
g
,
b
(if used to describe colors), or
x
,
y
,
z
(same data but contextually understood as
3D data). These functions may have pleased the JavaScript connoisseur when running scripts with
Qt5-based builds of Stellarium (series 0.*, and now usually found on 32-bit and older systems), but
we recommend to abstain from their use in new scripts.
Qt6’s scripting module cannot be extended that easily. The
Vec3d
and
Vec3f
data types are not
directly scriptable, but we can deal with method arguments of these types when they are mentioned
in the API documentation (see 17.1). To access internals of these classes, we must use wrapper
classes which bear different names:
V3d can be used where Vec3d must be accessed.
V3f can be used where Vec3f must be accessed.
254 Chapter 17. Scripting
Input Result with Qt5 Result with Qt6
x var f1=new V3d(.1,.2,.3);
core.output(f1); [0.1, 0.2, 0.3] V3d(0x249a1cf37c0) [some address]
core.output(+f1.toString()); [0.1, 0.2, 0.3] V3d(0x249a1cf37c0) [some address]
x core.output(f1.toHex()); #19334c #19334c
x core.output(f1.toVec3d()); [0.1, 0.2, 0.3] [0.1, 0.2, 0.3]
x var f2=new V3d(f1.x(), 2*f1.y(), 3*f1.z());
core.output(f2); [0.1, 0.4, 0.9] V3d(0x249a1cf3a60) [some address]
x core.output(f2.toVec3d()); [0.1, 0.4, 0.8999999999999999] [0.1, 0.4, 0.9]
x var crimson=new Color("Crimson");
x core.output(crimson.toHex()); #dc143c #dc143c
core.output(crimson.toVec3f()); [r:0.8627451062202454, g:0.0784313753247261, b:0.23529411852359772] [0.862745, 0.0784314, 0.235294]
core.output(crimson.r); 0.8627451062202454 error
core.output(crimson.r()); error 0.8627451062202454
x core.output(crimson.getR()); 0.8627451062202454 0.8627451062202454
x core.output(crimson.getG()); 0.0784313753247261 0.0784313753247261
x core.output(crimson.getB()); 0.23529411852359772 0.23529411852359772
crimson.g=0.444; (works) (error)
crimson.setG(0.444); (error) (works)
x crimson=new Color(crimson.getR(), 0.444, crimson.getB()); (reassign crimson; recommended for Qt5 and Qt6)
x core.output(crimson.toRGBString()); [r:0.862745, g:0.444, b:0.235294] [r:0.862745, g:0.444, b:0.235294]
x var eq=new Color(GridLinesMgr.getColorEquatorJ2000Grid());
x core.output(eq.toHex()); #00aaff #00aaff
core.output(eq.toVec3f()); [r:0, g:0.6666669845581055, b:1] [0, 0.666667, 1]
core.output(eq.toVec3d()); (n.a.) [0, 0.666667, 1]
core.output(eq.toString()); [0, 0.666667, 1] Color(0x24a11712910) [some address]
x core.output(eq.toRGBString()); [r:0, g:0.666667, b:1] [r:0, g:0.666667, b:1]
x var c=new Color(core.vec3f(.3, .4, .5));
core.output(c.toString()); [0.3, 0.4, 0.5] Color(0x249a1e078b0) [some address]
core.output(c.toVec3f()); [r:0.30000001192092896, g:0.4000000059604645, b:0.5] [0.3, 0.4, 0.5]
x var d=c; // assign to other
core.output(d.toVec3f()); [r:0.30000001192092896, g:0.4000000059604645, b:0.5] [0.3, 0.4, 0.5]
x var c2=new Color(.3, .4, .5);
core.output(c2.toString()); [0.3, 0.4, 0.5] Color(0x24a11712a60) [some address]
core.output(c2.toVec3f()); [r:0.30000001192092896, g:0.4000000059604645, b:0.5] [0.3, 0.4, 0.5]
x var d2=c2; // assign to other
core.output(d2.toVec3f()); [r:0.30000001192092896, g:0.4000000059604645, b:0.5] [0.3, 0.4, 0.5]
Table 17.1: Use of V3d, V3f and Color wrapper classes. Only use the calls marked with x in scripts targeted at all versions of Stellarium.
17.6 Example: Retrograde motion of Mars 255
Figure 17.1: Retrograde motion of Mars in 2005. (Credit & Copyright: Tunc Tezel — APOD:
2006 April 22 – Z is for Mars.)
Color can be used where a Vec3f must be accessed which represents a color value.
They behave slightly different when run using Qt5 or Qt6, as shown in Table 17.1. If you aim
for maximum compatibility between versions, only use the calls which provide equal results in both
series. This current state is far from optimal or even pretty, but a pragmatic solution that works. We
invite advanced developers to find a better solution that works with both Qt5 and Qt6.
17.6 Example: Retrograde motion of Mars
A good way begin writing of scripts: set yourself a specific goal and try to achieve it with the help
of few simple steps. Any complex script can be split into simple parts or tasks, which may solve
any newbie problems in scripting.
Let me explain it with examples.
Imagine that you have set a goal to make a demonstration of a very beautiful, but longish
phenomenon — the retrograde motion of the planet Mars (Fig. 17.1).
17.6.1 Script header
Any “complex” script should contain a few lines in the first part of the file, which contains important
data for humans — the name of the script and its description — and some rules for Stellarium.
You can even assign default shortcuts in the script header, but make sure you assign a key not used
elsewhere! The shortcuts are read during startup from all scripts in the
scripts
sub-directories of
both program and user data directories (see section 5.2). The description may cover several lines
(until the end of the commented header) and should therefore be the last entry of the header.
//
// Name : Retrograde motion of Mars
256 Chapter 17. Scripting
// Author : John Doe
// License : Public Domain
// Version : 1.0
// Shortcut: Ctrl +M
// Description : A demo of retrograde motion of Mars .
//
17.6.2 A body of script
At the first stage of writing of the script for a demo of retrograde motion of Mars we should set
some limits for our demo. For example we want to see motion of Mars every day during 250 days
since October
1
st
, 2009. Choosing a value of field of view and of the coordinates of the center of
the screen should be done at the this stage also.
Let’s add few lines of code into the script after the header and run it:
core.setDate("2009 -10 -01 T10 :00:00 ");
core.moveToRaDec("08 h44m41s", "+18 d09m13s ",1);
StelMovementMgr.zoomTo(40, 1);
for (i=0; i<250; i++)
{
core.setDate("+ 1 days ");
core.wait(0.2);
}
Note: The
wait(delay_seconds)
instruction inside the loop is important: when you are just
setting the time in rapid succession, there is no guarantee that the view is updated, or a textual result
has been updated when writing ephemerides, before executing the next time update! The
wait()
ensures the program can update the main simulation loop and put the planets where they should be
at that set time. The minimum delay required may depend on your computer’s speed.
OK, Stellarium is doing something, but what exactly is it doing? The ground and atmosphere is
enabled and any motion of Mars is invisible. Let’s add an another few lines into the script (hiding
the landscape and atmosphere) after setting date and time:
LandscapeMgr.setFlagLandscape(false);
LandscapeMgr.setFlagAtmosphere(false);
The whole sky is moving now — let’s lock it! Add this line after previous lines:
StelMovementMgr.setFlagLockEquPos(true);
It looks better now, but what about cardinal points, elements of GUI and some “glitch of
movement”? Let’s change the script:
core.setDate("2009 -10 -01 T10 :00:00 ");
LandscapeMgr.setFlagCardinalsPoints(false);
LandscapeMgr.setFlagLandscape(false);
LandscapeMgr.setFlagAtmosphere(false);
core.setGuiVisible(false);
core.moveToRaDec("08 h44m41s", "+18 d09m13s ",1);
StelMovementMgr.setFlagLockEquPos(true);
StelMovementMgr.zoomTo(40, 1);
core.wait(2);
for (i=0; i<250; i++)
{
17.6 Example: Retrograde motion of Mars 257
core.setDate("+ 1 days ");
core.wait(0.2);
}
core.setGuiVisible(true);
It’s better, but let’s draw the “path” of Mars! Add those line before the loop:
core.selectObjectByName("Mars ", false);
SolarSystem.setFlagIsolatedTrails(true);
SolarSystem.setFlagTrails(true);
Hmm. . . let’s add a few strings with info for users (insert those lines after the header):
var color = "# ff9900 ";
var info = LabelMgr.labelScreen("A motion of Mars ", 20, 20,
false, 24, color);
var apx = LabelMgr.labelScreen("Setup best viewing angle , FOV
and date / time .", 20, 50, false, 18, color);
LabelMgr.setLabelShow(info, true);
LabelMgr.setLabelShow(apx, true);
core.wait(2);
LabelMgr.setLabelShow(apx, false);
Let’s add some improvements to display info for users — change in the loop:
var label = LabelMgr.labelObject(" Normal motion , West to
East ", "Mars ", true, 16, color, "SE");
for (i=0; i<250; i++)
{
core.setDate("+ 1 days ");
if ((i % 10) == 0)
{
var strDate = "Day " + i;
LabelMgr.setLabelShow(apx, false);
var apx = LabelMgr.labelScreen(strDate, 20,
50, false, 16, color);
LabelMgr.setLabelShow(apx, true);
}
if (i == 75)
{
LabelMgr.deleteLabel(label);
label = LabelMgr.labelObject(" Retrograde or
opposite motion begins ", " Mars ",
true, 16, color, "SE");
core.wait(2);
LabelMgr.deleteLabel(label);
label = LabelMgr.labelObject(" Retrograde
motion ", " Mars ", true, 16, color,
"SE");
}
if (i == 160)
{
LabelMgr.deleteLabel(label);
258 Chapter 17. Scripting
label = LabelMgr.labelObject(" Normal motion
returns ", "Mars ", true, 16, color,
"SE");
core.wait(2);
LabelMgr.deleteLabel(label);
label = LabelMgr.labelObject(" Normal motion ",
"Mars ", true, 16, color, "SE");
}
core.wait(0.2);
}
17.7 More Examples
The best source of examples is the
scripts
sub-directory of the main Stellarium source tree. This
directory contains a sub-directory called
tests
which are not installed with Stellarium, but are
nonetheless useful sources of example code for various scripting features.
18. Astronomical Concepts
BARRY GERDES, WITH ADDITIONS BY GEORG ZOTTI
This section includes some general notes on astronomy in an effort to outline some concepts that
are helpful to understand features of Stellarium. Material here is only an overview, and the reader is
encouraged to get hold of a couple of good books on the subject. A good place to start is a compact
guide and ephemeris such as the National Audubon Society Field Guide to the Night Sky
1
. Also
recommended is a more complete textbook such as Universe
2
. There are also some nice resources
on the net, such as the Wikibooks Astronomy book
3
.
18.1 The Celestial Sphere
The Celestial Sphere is a concept which helps us think about the positions of objects in the
sky. Looking up at the sky, you might imagine that it is a huge dome or top half of a sphere (a
hemisphere), and the stars are points of light on that sphere. Visualizing the sky in such a manner,
it appears that the sphere moves, taking all the stars with it — it seems to rotate. Watching the
movement of the stars we can see that they seem to rotate around a static point about once a day
(the diurnal motion). Stellarium is the perfect tool to demonstrate this!
1.
Open the location dialog (
F6
). Set the location to be somewhere in mid-northern latitudes.
(Just click on the map to select a location, or fine-tune with the settings.) The United
Kingdom is an ideal location for this demonstration.
2.
Turn off atmospheric rendering
A
and ensure cardinal points are turned on (
Q
). This will
keep the sky dark so the Sun doesn’t prevent us from seeing the motion of the stars when it
is above the horizon.
3. Pan round to point north, and make sure the field of view is about 90
◦
.
4. Pan up so the ‘N’ cardinal point on the horizon is at the bottom of the screen.
1
https://www.amazon.com/National-Audubon-Society-Field-Series/dp/0679408525
2
https://www.amazon.com/Universe-Definitive-Visual-Martin-Rees/dp/0756636701
3
https://en.wikibooks.org/wiki/Subject:Astronomy
262 Chapter 18. Astronomical Concepts
5.
Now increase the time rate. Press
K
,
L
,
L
,
L
,
L
– this should set the time rate so
the stars can be seen to rotate around a point in the sky about once every ten seconds. If
you watch Stellarium’s clock you’ll see this is the time it takes for one day to pass at this
accelerated rate.
The point which the stars appear to move around is one of the Celestial Poles.
The apparent movement of the stars is due to the rotation of the Earth. Our location as the
observer on the surface of the Earth affects how we perceive the motion of the stars. To an observer
standing at Earth’s North Pole, the stars all seem to rotate around the zenith (the point directly
upward). As the observer moves south towards the equator, the location of the celestial pole moves
down towards the horizon. At the Earth’s equator, the North Celestial Pole appears to be on the
northern horizon.
Similarly, observers in the southern hemisphere see the Southern Celestial Pole at the zenith
when they are at the South Pole, and it moves to the horizon as the observer travels towards the
equator.
1.
Leave time moving on nice and fast, and open the configuration window. Go to the location
tab and click on the map right at the top – i.e., set your location to the North Pole. See how
the stars rotate parallel to the horizon, around a point right at the top of the screen. With the
field of view set to
90
◦
and the horizon at the bottom of the screen, the top of the screen is
the zenith.
2.
Now click on the map again, this time a little further south. You should see the positions of
the stars jump, and the center of rotation has moved a little further down the screen.
3.
Click on the map even further towards and equator. You should see the centre of rotation
having moved down again.
To help with the visualization of the celestial sphere, turn on the equatorial grid by clicking the
button on the main toolbar or pressing the
E
key. Now you can see grid lines drawn on the sky.
These lines are like lines of longitude and latitude on the Earth, but drawn for the celestial sphere.
The Celestial Equator is the line around the celestial sphere that is half way between the
celestial poles – just as the Earth’s equator is the line half way between the Earth’s poles.
18.2 Coordinate Systems
18.2.1 Altitude/Azimuth Coordinates
The Horizontal Coordinate System (also called Altitude/Azimuth coordinate system) can be used
to describe a direction of view (the azimuth angle) and an angular height in the sky (the altitude
angle). The azimuth angle is measured clockwise round from due north
4
. Hence North itself is 0
◦
,
East
90
◦
, Southwest is
225
◦
and so on. The altitude angle is measured up from the mathematical
horizon, which is just halfway between “straight up” and “straight down”, without regard to the
landscape. Looking directly up (at the zenith) would be
90
◦
, half way between the zenith and the
horizon is 45
◦
and so on. The point opposite the zenith is called the nadir.
The Altitude/Azimuth coordinate system is attractive in that it is intuitive – most people are
familiar with azimuth angles from bearings in the context of navigation, and the altitude angle is
something most people can visualise pretty easily.
However, the altitude/azimuth coordinate system is not suitable for describing the general
position of stars and other objects in the sky – the altitude and azimuth values for a celestial object
change with time and the location of the observer.
4
In some textbooks azimuth is counted from south. There is no global authority to decide upon this issue,
just be aware of this when you compare numbers with other sources.
18.2 Coordinate Systems 263
Figure 18.1: Altitude/Azimuth (Horizontal) Coordinate System
Stellarium can draw grid lines for altitude/azimuth coordinates. Use the button on the main
toolbar to activate this grid, or press the
Z
key.
In addition, the cardinal points can be highlighted using the
button or
Q
key.
There are a few great circles with special names which Stellarium can draw (see section 4.4.4).
Meridian
This is a great circle which runs through the North Pole towards the zenith and further
to the South Pole and nadir.
(Mathematical) Horizon This is the line exactly 90
◦
away from the zenith.
First Vertical
This is the vertical circle perpendicular to the horizon and which runs from the East
point through the zenith, down the West point and to the nadir.
18.2.2 Right Ascension/Declination Coordinates
Like the Altitude/Azimuth system, the Right Ascension/Declination (RA/Dec) Coordinate System
(or Equatorial Coordinate System) uses two angles to describe positions in the sky. These angles
are measured from standard points on the celestial sphere. Right ascension
α
and declination
δ
are
264 Chapter 18. Astronomical Concepts
Figure 18.2: Equatorial Coordinates
to the celestial sphere what longitude and latitude are to terrestrial map makers.
The Northern Celestial Pole has a declination of
δ = 90
◦
, the celestial equator has a declination
of δ = 0
◦
, and the Southern Celestial Pole has a declination of δ = −90
◦
.
Right ascension is measured as an angle round from the vernal equinox, a point in the sky also
known as the First Point of Aries
à
, in the same way that longitude is measured around the Earth
from Greenwich. Figure 18.2 illustrates RA/Dec coordinates. The angle
α
is usually expressed as
time with minute and seconds, with 15
◦
equaling one hour.
Unlike Altitude/Azimuth coordinates, RA/Dec coordinates of a star do not change when the
observer changes latitude, and do not change noticeably over the course of the day due to the
rotation of the Earth. RA/Dec coordinates are generally used nowadays in star catalogs such as the
Hipparcos catalog.
However, the story is complicated a little by precession (section 18.8) and parallax (sec-
tion 18.9). Precession causes a slow drift of the coordinates almost parallel to the ecliptic, and
therefore star catalogs always have to specify their equinox of validity.
18.2 Coordinate Systems 265
Current catalogs and atlases use coordinates for the standard epoch J2000.0. The currently best
defined coordinate system, the International Celestial Reference Frame (ICRF), is one particular
version described in detail in the astronomical literature (Urban and Seidelmann, 2013). Other
catalogs with data referring to “J2000.0” may have to be slightly adjusted (usually in sub-arcsecond
rotations) to match the ICRF coordinate system (short ICRS).
Stars close to the celestial poles are permanently visible above the horizon and thus called
circumpolar. Those stars have observable upper and lower culminations when they pass the
meridian arc spanning from the celestial pole over the zenith to the opposite point on the horizon,
or from the celestial pole to the horizon below, respectively.
Those circumpolar stars which show their upper culmination between pole and zenith also have
limits in azimuth which they can reach in their daily course, the points of greatest digression. At
these points they move vertically upwards (in the east) or downwards (in the west), respectively.
Stellarium can draw grid lines for equatorial coordinates. Use the button on the main
toolbar to activate this grid, or press the
E
key to draw the equatorial grid for the simulation time.
The Markings dialog (4.4.4) allows you to set also the grid for J2000.0 standard coordinates.
There are again a few great circles with special names which Stellarium can draw in addition,
both for simulation time and for J2000.0 (see section 4.4.4).
Celestial Equator
the line directly above the Earth’s (or more generally, the observer’s planet’s)
equator.
Colures
These are lines similar to meridian and first vertical in the azimuthal system. The
Equinoctial Colure runs from the North Celestial Pole NCP through the First Point of Aries
à
, South Celestial Pole SCP and First Point of Libra
æ
, while the Solstitial Colure runs
from the NCP through First Point of Cancer ã, SCP and First Point of Capricorn é.
In case you are observing from another celestial object, the equatorial coordinates use a system
similar to the one referring to the Earth-based coordinates, but parallel to the planet’s rotational
axis.
18.2.3 Fixed Equatorial Coordinates
The celestial sphere with its stars and other objects located in equatorial coordinates seems to rotate
around the celestial polar axis. When observing with a telescope, it proved useful to mount the
instrument on an axis which is aimed to be parallel to the earth’s axis, i.e., points to the celestial
pole. In this case, after setting the objects’s declination, it is enough to move the telescope around
this polar axis to track its course over time and keep the object in the field of view. We can describe
the Fixed Equatorial Coordinate System as an intermediate coordinate system which uses the
same equator and declination as the equatorial system, but does not rotate as time goes by. The
longitudinal coordinate is counted in hours from the meridian towards the west and is aptly named
Hour Angle. A star which has passed the meridian will reach hour angle of 1 hour one sidereal hour
later.
Stellarium can display the fixed equatorial coordinates in the Markings dialog (4.4.4).
18.2.4 Ecliptical Coordinates
The Earth’s orbit around the Sun, i.e., the ecliptic, defines the “equatorial line” of this coordinate
system, which is traditionally used when computing the coordinates for planets because of their
close proximity to this line. Mirroring Earth’s motion, the Sun is seen to move along the ecliptic.
The zero point of ecliptical longitude
λ
is the same as for equatorial coordinates (
à
), and
the ecliptical latitude
β
is counted positive towards the Northern Ecliptical Pole NEP in the
constellation of Draco.
Moon and Sun (and to a much lesser extent, the other planets) pull on the equatorial bulge and
try to put Earth’s axis normal to its orbital plane. Earth acts like a spinning top and evades this pull
266 Chapter 18. Astronomical Concepts
in a sideways motion, so that Earth’s axis seems to describe a small circle over a period of almost
26.000 years (see section 18.8).
In addition, ecliptic obliquity against the equatorial coordinates, which mirrors the Earth’s axial
tilt, slowly changes.
Therefore, also for ecliptical coordinates it is required to specify which date (epoch) the
coordinates refer to. Stellarium can draw grids for two epochs. Use the
,
key to draw the ecliptic
for the simulation time. The Markings dialog (4.4.4) allows you to add date marks to the ecliptic
line and also show a line for epoch J2000.0 and grids for the ecliptical coordinates for current epoch
v 23.1
and epoch J2000.0. You can assign your own shortcut keys (section 4.8) if you frequently operate
with these coordinates.
Since version 0.14.0 Stellarium can very accurately show the motions between the coordinate
systems (Vondrák, Capitaine, and Wallace, 2011; Vondrák, Capitaine, and Wallace, 2012), and it is
quite interesting to follow these motions for several millennia. To support such demonstrations,
Stellarium can also draw the precession circles between celestial and ecliptical poles (activate
them in the Markings dialog (4.4.4). However, these circles are simply plotted centered on the
instantaneous ecliptic pole by the instantaneous value of obliquity. If you observe long enough, you
will see that these circles vary in size, reflecting the changes in ecliptic obliquity. The real track of
where Earth’s axis is pointing forms an open helical loop.
The inner planets are best observed when their apparent distance from the Sun, or elongation,
reaches a maximum. Unfortunately there are two definitions for elongation, though:
ψ angular distance on the sphere. This is today the most widely used definition.
∆λ
À
difference between solar and the object’s ecliptical longitude. The advantage of using this
definition is that we can easily read opposition (
∆λ
À
= 180
◦
) and conjunction (
∆λ
À
= 0
◦
).
We can also see whether we have eastern elongation (
∆λ
À
> 0
) where the planet is visible in
the evening sky, or western elongation (
∆λ
À
< 0
) where the planet is visible in the morning
sky. For the inner planets Mercury and Venus we further discern superior conjunction,
when the planet is “above”, or behind, the Sun, and inferior conjunction, when the planet is
“below”, or closer than, the Sun.
Many of the minor bodies are best observed around the times of their opposition. Stellarium
can display a great circle in the ecliptical coordinates which runs through the ecliptic poles and
through the Sun, thereby allowing to estimate opposition and conjunction. Activate display of
this Opposition/Conjunction Line in the Markings dialog (Labeled “O./C. longitude”; 4.4.4). The
Markings dialog also provides the possibility to visualize the antisolar point, which lies opposite of
the Sun, on the intersection of the ecliptic and the O/C line.
Another interesting aspect of planets is their quadrature from the Sun. Here their angular
distance is 90
◦
. You can activate display of the quadrature circle in the Markings dialog (4.4.4).
It is interesting to note that star catalogs before TYCHO BRAHE’s (1546–1601), most notably
the one in PTOLEMY’s Almagest, used ecliptical coordinates. The reason is simple: it was known
since HIPPARCHUS that stellar coordinates slowly move along the ecliptic through precession, and
the correction to coordinates of a date of interest was a simple addition of a linear correction to the
ecliptical longitude in the catalog. Changes of ecliptic obliquity were discovered much later.
18.2.5 Galactic Coordinates
The Milky Way appears to run along a great circle over the sky, mirroring the fact that the Sun
is a star in it. Coordinates for non-stellar objects which belong to the Milky Way like pulsars
or planetary nebulae are often mapped in Galactic Coordinates, where galactic longitude
l
and
galactic latitude
b
are usually given in decimal degrees. Here, the zero point of galactic longitudes
lies in the Galactic Center.
Stellarium can also draw a galactic grid and the galactic equator by activating the respective
18.3 Distance 267
options in the Markings dialog (see section 4.4.4). You can assign a keyboard shortcut if you
frequently use these coordinates (see 4.8).
18.2.6 Planet Coordinates
The larger objects in the Solar system are described as spheroids, sometimes flattened into slightly
ellipsoid shape.
Just like the Prime Meridian on Earth has been defined to run through Greenwich Observatory,
each such object in the Solar system for which any kind of rotation has been detected has a prime
meridian defined by the IAU Working Group on Cartographic Coordinates and Rotational Elements
(WGCCRE). On a rocky planet this is usually defined by some surface feature like a crater. For
the Moon, it has traditionally been the center of the Lunar disk. For the gas giant planets with
ever-changing atmospheric features, there are even several systems of rotation. Most notably on
Jupiter, System I describes the rotation of its equatorial area, while System II describes the mean
atmospheric rotation north of the south component of the north equatorial belt, and south of the
north component of the south equatorial belt. Official sources prefer to list the rotation of the
magnetic fields (System III) for these planets. The most interesting feature on Jupiter for most
observers is the Great Red Spot (GRS), a huge storm that has been observed since the 19th, if not
even since the 17th century.
Astronomical almanacs and observing guides often list transit times when the GRS crosses the
center of Jupiter’s visible disk. Stellarium aims to show it at the right place. The storm moves in
longitude, and to adjust for this you can configure its System II longitude in the settings, see 4.4.2.
Like many planet moons, also Earth’s Moon shows one side towards its planet. However,
given its elliptical orbit and disturbations by Earth, Sun and other planets, the Moon seems to
nod slightly in east-west and north-south directions. This motion is called Libration. Stellarium
gives geocentric libration in longitude
L
and latitude
B
, which are the coordinates of the apparent
center of the Lunar disk. Another way to express this shift is the total angle of libration and the
direction into which the Moon’s mean center has been shifted. This angle is given counterclockwise
from the direction of the North pole on the Lunar disk. The larger this shift is, the better you can
observe the opposite side, which is therefore marked in brackets. If libration is larger than 3/5/7
degrees, Stellarium shows 1, 2 or 3 exclamation marks to draw your attention further to this lunar
rim. However, you also need light on this edge.
Another interesting point for which Stellarium gives coordinates is the sub-solar point
(L
s
,B
s
)
.
The Selenographic colongitude of the Sun
c
0
= 450
◦
−L
s
is given for the Moon. This helps
estimating the terminator (Meeus, 1998):
• The morning terminator is at 360
◦
−c
0
.
• The evening terminator is at 180
◦
−c
0
.
• When c
0
= 0
◦
, the Sun rises at selenographic longitude L = 0
◦
, near First Quarter.
• When c
0
= 90
◦
, the Sun rises at selenographic longitude L = 270
◦
, near Full Moon.
• When c
0
= 180
◦
, the Sun rises at selenographic longitude L = 180
◦
, near Last Quarter.
• When c
0
= 270
◦
, the Sun rises at selenographic longitude L = 90
◦
, near New Moon.
c
0
is used to compute the Sun’s altitude
h
over a surface point, e.g. a crater on the Moon at
position (η,θ ), which is displayed when you select a surface feature.
sinh = sinB
s
sin
θ + cosB
s
cosθ sin(c
0
+ η) (18.1)
18.3 Distance
As DOUGLAS ADAMS (1952–2001) pointed out in The Hitchhiker’s Guide to the Galaxy (Adams,
1981),
268 Chapter 18. Astronomical Concepts
Space [. . . ] is big. Really big. You just won’t believe how vastly, hugely, mind-
bogglingly big it is. I mean, you may think it’s a long way down the road to the
chemist, but that’s just peanuts to space.[p.76]
Astronomers use a variety of units for distance that make sense in the context of the mind-boggling
vastness of space.
Astronomical Unit (AU)
This is the mean Earth-Sun distance. Roughly 150 million kilometers
(
1.49598×10
8
km
). The AU is used mainly when discussing the solar system – for example
the distance of various planets from the Sun.
Light year (LY)
A light year is not, as some people believe, a measure of time. It is the distance
that light travels in a year. The speed of light being approximately 300,000 kilometers per
second means a light year is a very large distance indeed, working out at about 9.5 trillion
kilometers (
9.46073×10
12
km
). Light years are most frequently used when describing the
distance of stars and galaxies or the sizes of large-scale objects like galaxies, nebulae etc.
Parsec (pc)
A parsec is defined as the distance of an object that has an annual parallax of 1 second
of arc. This equates to 3.26156 light years (
3.08568 ×10
13
km
). Parsecs (and derivatives:
kiloparsec
kpc
, megaparsec
Mpc
) are most frequently used when describing the distance of
stars or the sizes of large-scale objects like galaxies, nebulae etc.
18.4 Time
Figure 18.3: Sidereal day
The length of a day is defined as the amount of time that it takes for the Sun to travel from
the highest point in the sky at mid-day to the next high-point on the next day. In astronomy this is
called a solar day. The apparent motion of the Sun is caused by the rotation of the Earth. However,
18.4 Time 269
in this time, the Earth not only spins, it also moves slightly round its orbit. Thus in one solar day
the Earth does not spin exactly
360
◦
on its axis. Another way to measure day length is to consider
how long it takes for the Earth to rotate exactly 360
◦
. This is known as one sidereal day.
Figure 18.3 illustrates the motion of the Earth as seen looking down on the Earth orbiting the
Sun. The red triangle on the Earth represents the location of an observer. The figure shows the
Earth at four times:
1. The Sun is directly overhead - it is mid-day.
2.
Twelve hours have passed since 1. The Earth has rotated round and the observer is on the
opposite side of the Earth from the Sun. It is mid-night. The Earth has also moved round in
its orbit a little.
3. The Earth has rotated exactly 360
◦
. Exactly one sidereal day has passed since 1.
4.
It is mid-day again – exactly one solar day since 1. Note that the Earth has rotated more than
360
◦
since 1.
It should be noted that in figure 18.3 the sizes of the Sun and Earth and not to scale. More
importantly, the distance the Earth moves around its orbit is much exaggerated. The Earth takes a
year to travel round the Sun –
365
1
4
solar days. The length of a sidereal day is about 23 hours, 56
minutes and 4 seconds.
18.4.1 Sidereal Time
It takes exactly one sidereal day for the celestial sphere to make one revolution in the sky. As-
tronomers find sidereal time useful when observing. This is the Right Ascension which is currently
passing the meridian line, or, equivalent, the Hour Angle of the First Point of Aries
à
. When
visiting observatories, look out for doctored alarm clocks that have been set to run faster and show
sidereal time!
18.4.2 Julian Day Number
In the 19th century, astronomer JOHN HERSCHEL (1792–1871) introduced the use of Julian Day
numbers (invented around the time of the Gregorian calendar reform). This is a simple continuous
day count starting on January 1, -4712 (4713 BC). There are no years, months etc., and the integral
day number switches at noon, so during a single night of observation (in Europe) the date never
changes.
The fractional part of the number is just the fraction of day that has elapsed since last noon.
Given that a day has 86400 seconds, we should give a JD with 5 decimal places to capture the
nearest second.
This causes a problem for modern computers: even a “double precision float” can keep
only about 13 decimal places. More than 2.4 million days have passed, so that e.g. Jan-
uary 1, 2000, 12:00UT is 2451545.0, which is an accurately storable number with 7 decimal
places, but 12:34:56UT is computed as 2451545.02426. A more accurate result would yield
2451545.024259259259... So, for a field where sub-second accuracy became crucial like spacecraft
operations, the Modified Julian Day (MJD) has been introduced. It is simply
MJD = JD −2400000.5. (18.2)
This means, days start at midnight, and the (constant, in our era) decimal places of the “big numbers”
at the begin of the number have been traded in for more decimal places at the end.
Don’t put your expectations too high when you see MJD displayed (section 4.1): Stellarium
uses a double-precision floating point number for JD for internal timekeeping, and Stellarium’s
display of MJD is simply computed from it. So you cannot set temporal increments smaller than a
second, and it hardly would make sense to expect more accuracy from the simulation algorithms.
270 Chapter 18. Astronomical Concepts
18.4.3 Delta T
Until around 1900, the Earth’s rotation was regarded as perfect standard of time. There were
86400 seconds per mean solar day, and the accuracy of reproducing time with mechanical clocks
only in this time started to become as good as the Earth’s rotation itself.
Astronomers who computed solar eclipses reported in texts from antiquity wondered about a
required time shift which they originally attributed to a yet-unknown “secular acceleration of the
lunar motion”. However, it turned out that indeed the gravitational effect of the Moon which causes
the tides also has effects on Earth’s rotation: the tides slowly break Earth’s rotational speed. The
energy is also transferred to the Moon, and the acceleration leads to the Moon slowly moving away
from the Earth
5
.
This led to the introduction of a time named Ephemeris Time (ET) with progresses in the speed
of the second in the year 1900, to be used for positional computation in our solar system, in addition
to Greenwich Mean Time (GMT), from which all zone times and “civil” clock times were derived.
The introduction of atomic clocks in the middle of the 20th century led to a redefinition of the
(temporal) second, which has been de-coupled from Earth’s rotation. This time, the International
Atomic Time TAI
6
, is the basis for Terrestrial Time TT which can be considered as constantly
progressing at constant speed
7
, and is used for computation of the planetary positions.
Still, people living on Earth prefer to have the mean solar noon governing the run of day and
night. Therefore all forms of civil time are linked to Coordinated Universal Time UTC. Seconds
in UTC and TAI are of equal length. The slow and irregular divergence between TAI and UTC is
observed by a few standardization institutes. When necessary, a leap second can be introduced to
the UTC to bring the Earth’s rotation back in sync so that the Mean Sun again culminates at noon.
The difference
∆T = T T −UT
(or “Delta T”) describes the temporal offset which amounts
already to more than a minute in the 21st century. There have been many attempts to properly
model
∆T
, and Stellarium offers several models you can choose from in the configuration dialog
(see section 4.3.4). “Espenak and Meeus (2006, 2014)”, is a widely accepted standard. The default,
“Modified Espenak and Meeus (2006, 2014, 2023)”, is created to make
∆T
closely in line with
observed and predicted values between the years 2015-2050. But if you are a researcher and want
to experiment with alternative models, you will hopefully like this feature. you can even specify
your own data for
a
,
b
,
c
,
y
and the secular term for lunar acceleration
n
(actually
˙n = dn/dt
in
units of arcseconds/century
2
) if you can model ∆T according to the formula
∆T = a +b ·u + c ·u
2
where (18.3)
u =
year−y
100
(18.4)
List of ∆T models in Stellarium
The following list describes sources and a few details about the models for
∆T
implemented in
Stellarium.
Without correction. Correction is disabled. Use only if you know what you are doing!
Schoch (1931).
This historical formula was obtained by Schoch (1931) and was also used in “A
New Test of Einstein’s Theory of Relativity by Ancient Solar Eclipses” (Henriksson, 2009).
See for more in Peters (2010). ˙n = −29.68
′′
/cy
2
.
5
No need to worry, the Moon recedes from the Earth only a few centimeters per year as measured with
the laser reflectors left by the Apollo astronauts in the 1970s. In a very far future, however, there will only be
annular solar eclipses as a consequence!
6
From the French name temps atomique international
7
We don’t discuss relativity here. The advanced reader is referred to the presentation in the Wikipedia,
https://en.wikipedia.org/wiki/Delta_T.
18.4 Time 271
Clemence (1948).
This empirical equation was published in “On the system of astronomical
constants” (Clemence, 1948). Valid range of usage: between years 1681 and 1900.
˙n =
−22.44
′′
/cy
2
.
IAU (1952).
This formula is based on a study of post-1650 observations of the Sun, the Moon and
the planets (Spencer Jones, 1939) and reproduced in Astronomical Formulae for Calculators
(Meeus, 1988). It was also adopted in the PC program SunTracker Pro. Valid range of usage:
between years 1681 and 1936. ˙n = −22.44
′′
/cy
2
.
Astronomical Ephemeris (1960).
This is a slightly modified version of the IAU 1952 (Spencer
Jones, 1939) formula which was adopted in the “Astronomical Ephemeris” (Wilkins, 1961)
and in the Canon of Solar Eclipses -2003 to +2526 (Mucke and Meeus, 1983). Valid range
of usage: between years -500 and 2000. ˙n = −22.44
′′
/cy
2
.
Tuckerman (1962, 1964) & Goldstine (1973).
The famous tables (Tuckerman, 1962; Tuckerman,
1964) list the positions of the Sun, the Moon and the planets at 5- and 10-day intervals from
601 BCE to 1649 CE. The same relation was also implicitly adopted in the syzygy tables of
Goldstine (1973). Valid range of usage: between years -600 and 1649.
Muller & Stephenson (1975).
This equation was published in “The accelerations of the earth and
moon from early astronomical observations” (Muller and F. R. Stephenson, 1975). Valid
range of usage: between years -1375 and 1975. ˙n = −37.5
′′
/cy
2
.
Stephenson (1978).
This equation was published in “Pre-Telescopic Astronomical Observations”
(F. R. Stephenson, 1978). ˙n = −30.0
′′
/cy
2
.
Schmadel & Zech (1979).
This 12th-order polynomial equation (outdated and superseded by
Schmadel and Zech (1988)) was published in “Polynomial approximations for the correction
delta T E.T.-U.T. in the period 1800-1975” (Schmadel and Zech, 1979) as fit through data
published by Brouwer (1952). Valid range of usage: between years 1800 and 1975, with
meaningless values outside this range. ˙n = −23.8946
′′
/cy
2
.
Morrison & Stephenson (1982).
This algorithm Morrison and F. R. Stephenson, 1982 was adopted
in Planetary Programs and Tables from –4000 to +2800 (Pierre Bretagnon and Simon, 1986)
and in the PC planetarium program RedShift. Valid range of usage: between years -4000
and 2800. ˙n = −26.0
′′
/cy
2
.
Stephenson & Morrison (1984).
This formula was published in “Long-term changes in the rota-
tion of the earth - 700 B.C. to A.D. 1980” (F. R. Stephenson and Morrison, 1984). Valid
range of usage: between years -391 and 1600. ˙n = −26.0
′′
/cy
2
.
Stephenson & Houlden (1986).
This algorithm (Houlden and F. Stephenson, 1986) is used in the
PC planetarium program Guide 7. Valid range of usage: between years -600 and 1600.
˙n = −26.0
′′
/cy
2
.
Espenak (1987, 1989).
This algorithm was given in Fifty Year Canon of Solar Eclipses: 1986 –
2035 (Espenak, 1987) and in Fifty Year Canon of Lunar Eclipses: 1986 – 2035 (Espenak,
1989). Valid range of usage: between years 1950 and 2100.
Borkowski (1988).
This formula was obtained by Borkowski (1988) from an analysis of 31 solar
eclipse records dating between 2137 BCE and 1715 CE. Valid range of usage: between years
-2136 and 1715. ˙n = −23.895
′′
/cy
2
.
Schmadel & Zech (1988).
This 12th-order polynomial equation was published in “Empirical
Transformations from U.T. to E.T. for the Period 1800-1988” (Schmadel and Zech, 1988) as
data fit through values given by F. R. Stephenson and Morrison (1984). Valid range of usage:
between years 1800 and 1988, with a mean error of less than one second, max. error 1.9s,
and meaningless values outside this range. ˙n = −26.0
′′
/cy
2
.
Chapront-Touze & Chapront (1991).
This formula was adopted by M. Chapront-Touze & J.
Chapront in the shortened version of the ELP 2000-85 lunar theory in their Lunar Tables and
Programs from 4000 B.C. to A.D. 8000 (Chapront-Touzé and Chapront, 1991). The relations
272 Chapter 18. Astronomical Concepts
are based on those of F. R. Stephenson and Morrison (1984), but slightly modified to make
them compatible with the tidal acceleration parameter of
˙n = −23.8946
′′
/cy
2
adopted in the
ELP 2000-85 lunar theory (Chapront-Touzé and Chapront, 1988a).
Stephenson & Morrison (1995).
This equation was published in “Long-Term Fluctuations in the
Earth’s Rotation: 700 BC to AD 1990” (F. R. Stephenson and Morrison, 1995). Valid range
of usage: between years -700 and 1600. ˙n = −26.0
′′
/cy
2
.
Stephenson (1997).
F. R. Stephenson published this formula in his book Historical Eclipses and
Earth’s Rotation (F. Richard Stephenson, 1997). Valid range of usage: between years -500
and 1600. ˙n = −26.0
′′
/cy
2
.
Meeus (1998) (with Chapront, Chapront-Touze & Francou (1997)).
From Astronomical Algo-
rithms (Meeus, 1998), and widely used. Table for 1620..2000, and includes a variant of
Chapront, Chapront-Touze & Francou (1997) for dates outside 1620..2000. Valid range of
usage: between years -400 and 2150. ˙n = −25.7376
′′
/cy
2
.
JPL HORIZONS.
The JPL Solar System Dynamics Group of the NASA Jet Propulsion Labora-
tory use this formula in their interactive website JPL HORIZONS
8
. Valid range of usage:
between years -2999 and 1620, with zero values outside this range. ˙n = −25.7376
′′
/cy
2
.
Meeus & Simons (2000).
This polynome was published in “Polynomial approximations to Delta
T, 1620-2000 AD” (Meeus and Simons, 2000). Valid range of usage: between years 1620
and 2000, with zero values outside this range. ˙n = −25.7376
′′
/cy
2
.
Montenbruck & Pfleger (2000).
The fourth edition of Astronomy on the Personal Computer
(Montenbruck and Pfleger, 2000) provides simple 3rd-order polynomial data fits for the
recent past. Valid range of usage: between years 1825 and 2005, with a typical 1-second
accuracy and zero values outside this range.
Reingold & Dershowitz (2002, 2007, 2018). E. M. Reingold & N. Dershowitz present this poly-
nomial data fit in Calendrical Calculations: The Ultimate Edition (Reingold and Dershowitz,
2018) and in their Calendrical Calculations (Reingold and Dershowitz, 2007), Calendri-
cal Tabulations 1900-2200 (Reingold and Dershowitz, 2002). It is based on Astronomical
Algorithms (Meeus, 1991).
Morrison & Stephenson (2004, 2005).
This important solution was published in “Historical val-
ues of the Earth’s clock error
∆
T and the calculation of eclipses” (Morrison and F. R.
Stephenson, 2004) with addendum (Morrison and F. R. Stephenson, 2005). Valid range of
usage: between years -1000 and 2000. ˙n = −26.0
′′
/cy
2
.
Stephenson, Morrison & Hohenkerk (2016, 2021).
This important new solution was published
in “Measurement of the Earth’s rotation: 720 BC to AD 2015” (F. R. Stephenson, Morrison,
and Hohenkerk, 2016). The solution combines a spline fit to observations (used between
the given limits) with a parabolic fit (used as fallback outside the range, but without smooth
transitions at the limits, i.e., values for 2016 and later deviate notably from current estimates,
and should not be used for dates after 2015). The solution was updated in “Addendum
2020 to ‘Measurement of the Earth’s rotation: 720 BC to AD 2015’” (Morrison, F. R.
Stephenson, et al., 2021). Recommended range of usage: between years -720.0 and 2019.0
˙n = −25.82
′′
/cy
2
.
Espenak & Meeus (2006, 2014).
This solution by F. Espenak and J. Meeus, based on Morrison
and F. R. Stephenson (2004) and a polynomial fit through tabulated values for 1600-2000, is
used for the NASA Eclipse Web Site
9
, in their Five Millennium Canon of Solar Eclipses: -
1900 to +3000 (Espenak and Meeus, 2006) and Thousand Year Canon of Solar Eclipses 1501
to 2500 (Espenak, 2014). This formula is also used in the solar, lunar and planetary ephemeris
program SOLEX. Valid range of usage: between years -1999 and 3000. ˙n = −25.858
′′
/cy
2
.
8
https://ssd.jpl.nasa.gov/?horizons
9
https://eclipse.gsfc.nasa.gov/eclipse.html
18.5 Angles 273
Modified Espenak & Meeus (2006, 2014, 2023).
This solution
10
is a modification from Espenak
& Meeus (2006, 2014). Values for 2015-2033 are interpolated from observations and
predictions by IERS Rapid Service/Prediction Center. A simple formula is used to connect
with F. Espenak’s predicted value at year 2050. Valid range of usage: between years -1999
and 3000. ˙n = −25.858
′′
/cy
2
.
Reijs (2006).
From the Length of Day (LOD; as determined by Morrison and F. R. Stephenson
(2004)), Victor Reijs derived a
∆T
formula by using