Stellarium User Guide 0.18.0 1

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 353 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Stellarium 0.18.0 User Guide
Georg Zotti, Alexander Wolf (editors)
2017
Copyright c
2014-2017 Georg Zotti.
Copyright c
2011-2017 Alexander Wolf.
Copyright c
2006-2013 Matthew Gates.
Copyright c
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 0.18.0-1, March 25, 2018
Contents
IBasic Use
1Introduction ................................................ 3
1.1 Historical notes 3
2Getting 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 OSX .......................................................... 8
2.3.3 Linux .......................................................... 8
2.4 Running Stellarium 9
2.4.1 Windows ...................................................... 9
2.4.2 OSX .......................................................... 9
2.4.3 Linux .......................................................... 9
2.5 Troubleshooting 9
3A 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
4The User Interface ........................................ 19
4.1 Setting the Date and Time 19
4.2 Setting Your Location 20
4.3 The Configuration Window 21
4.3.1 TheMainTab ................................................. 21
4.3.2 TheInformationTab ............................................ 21
4.3.3 TheNavigationTab ............................................ 21
4.3.4 TheToolsTab .................................................. 21
4.3.5 TheScriptsTab ................................................ 25
4.3.6 ThePluginsTab ................................................ 26
4.4 The View Settings Window 26
4.4.1 TheSkyTab ................................................... 26
4.4.2 The Deep-Sky Objects (DSO) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.4.3 TheMarkingsTab .............................................. 27
4.4.4 TheLandscapeTab ............................................ 29
4.4.5 TheStarloreTab ............................................... 30
4.4.6 TheSurveysTab ............................................... 31
4.5 The Object Search Window 32
4.6 The Astronomical Calculations Window 34
4.6.1 ThePositionsTab............................................... 34
4.6.2 TheEphemerisTab ............................................. 34
4.6.3 ThePhenomenaTab ........................................... 37
4.6.4 The“Altitudevs.Time”Tab ...................................... 37
4.6.5 TheGraphsTab ............................................... 38
4.6.6 The “What’s Up Tonight” (WUT) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.6.7 The “Planetary Calculator” (PC) Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.7 Help Window 40
4.7.1 Editing Keyboard Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
II Advanced Use
5Files and Directories ...................................... 45
5.1 Directories 45
5.1.1 Windows ..................................................... 45
5.1.2 MacOSX .................................................... 46
5.1.3 Linux ......................................................... 46
5.2 Directory Structure 46
5.3 The Logfile 47
5.4 The Main Configuration File 47
5.5 Getting Extra Data 48
5.5.1 MoreStars .................................................... 48
5.5.2 MoreDeep-SkyObjects ........................................ 48
5.5.3 Alternative Planet Ephemerides: DE430, DE431 . . . . . . . . . . . . . . . . . . . . 48
5.5.4 GPSPosition .................................................. 49
6Command Line Options .................................. 51
6.1 Examples 53
6.2 Special Options 53
6.2.1 Spout ........................................................ 53
7Landscapes ............................................... 55
7.1 Stellarium Landscapes 55
7.1.1 Locationinformation ........................................... 56
7.1.2 Polygonallandscape .......................................... 57
7.1.3 Sphericallandscape ........................................... 58
7.1.4 High resolution (“Old Style”) landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.1.5 Fisheyelandscape............................................. 63
7.1.6 Description ................................................... 64
7.1.7 Gazetteer .................................................... 65
7.1.8 PackingandPublishing ......................................... 65
7.2 Creating Panorama Photographs for Stellarium 66
7.2.1 PanoramaPhotography ........................................ 66
7.2.2 HuginPanoramaSoftware ...................................... 67
7.2.3 Regular creation of panoramas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.3 Panorama Postprocessing 71
7.3.1 TheGIMP ..................................................... 71
7.3.2 ImageMagick ................................................. 72
7.3.3 FinalCalibration ............................................... 74
7.3.4 ArticialPanoramas............................................ 76
7.3.5 NightscapeLayer.............................................. 76
7.4 Other recommended software 77
7.4.1 IrfanView ..................................................... 77
7.4.2 FSPViewer .................................................... 77
7.4.3 Clink ......................................................... 77
7.4.4 Cygwin ...................................................... 78
7.4.5 GNUWin32.................................................... 78
8Deep-Sky Objects ........................................ 79
8.1 Stellarium DSO Catalog 79
8.1.1 Modifyingcatalog.dat ......................................... 80
8.1.2 Modifyingnames.dat .......................................... 82
8.1.3 Modifyingtextures.json ......................................... 82
8.1.4 Modifyingoutlines.dat.......................................... 84
8.2 Adding Extra Nebulae Images 84
8.2.1 Preparing a photo for inclusion to the textures.json le............. 84
8.2.2 PlateSolving .................................................. 86
8.2.3 Processing into a textures.json insert ............................ 86
9Adding Sky Cultures ...................................... 89
9.1 Basic Information 89
9.2 Skyculture Description Files 90
9.3 Constellation Names 90
9.4 Star Names 90
9.5 Planet Names 91
9.6 Deep-Sky Objects Names 91
9.7 Stick Figures 91
9.8 Constellation Boundaries 92
9.9 Constellation Artwork 92
9.10 Seasonal Rules 92
9.11 References 93
9.12 Asterisms and help rays 93
9.13 Publish Your Work 93
10 Surveys .................................................... 95
10.1 Introduction 95
10.2 Hipslist file and default surveys 95
10.3 Solar system HiPS survey 96
III Extending Stellarium
11 Plugins: An Introduction .................................. 99
11.1 Enabling plugins 99
11.2 Data for plugins 99
12 Interface Extensions ..................................... 101
12.1 Angle Measure Plugin 101
12.2 Compass Marks Plugin 102
12.3 Equation of Time Plugin 103
12.3.1 Section EquationOfTimeincong.inifile........................ 103
12.4 Field of View Plugin 104
12.4.1 Section FOVincong.inifile .................................. 104
12.5 Pointer Coordinates Plugin 105
12.5.1 Section PointerCoordinatesin config.ini file . . . . . . . . . . . . . . . . . . . . . 105
12.6 Text User Interface Plugin 106
12.6.1 Using the Text User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
12.6.2 TUICommands ............................................... 106
12.6.3 Section tuiincong.inifile.................................... 108
12.7 Remote Control Plugin 109
12.7.1 Usingtheplugin .............................................. 109
12.7.2 Remote Control Web Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
12.7.3 Remote Control Commandline API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
12.7.4 Developerinformation ........................................ 110
12.8 Remote Sync Plugin 111
12.9 Solar System Editor Plugin 114
13 Object Catalog Plugins ................................. 117
13.1 Bright Novae Plugin 117
13.1.1 Section Novaeincong.inifile ................................ 117
13.1.2 Format of bright novae catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
13.1.3 Lightcurves.................................................. 118
13.2 Historical Supernovae Plugin 119
13.2.1 List of supernovae in default catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
13.2.2 Lightcurves.................................................. 121
13.2.3 Section Supernovaeincong.inifile ........................... 121
13.2.4 Format of historical supernovae catalog . . . . . . . . . . . . . . . . . . . . . . . . . 122
13.3 Exoplanets Plugin 123
13.3.1 Potential habitable exoplanets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
13.3.2 Propernames ................................................ 124
13.3.3 Section Exoplanetsincong.inifile ............................ 126
13.3.4 Format of exoplanets catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
13.4 Pulsars Plugin 129
13.4.1 Section Pulsarsincong.inifile ................................ 129
13.4.2 Formatofpulsarscatalog...................................... 130
13.5 Quasars Plugin 131
13.5.1 Section Quasarsincong.inifile .............................. 131
13.5.2 Format of quasars catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
13.6 Meteor Showers Plugin 133
13.6.1 Terms ....................................................... 133
13.6.2 Section MeteorShowersincong.inifile ........................ 134
13.6.3 Format of Meteor Showers catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
13.6.4 FurtherInformation ........................................... 136
13.7 Navigational Stars Plugin 137
13.7.1 Section NavigationalStarsincong.inifile ...................... 137
13.8 Satellites Plugin 138
13.8.1 SatelliteProperties ............................................ 138
13.8.2 IridiumFlaresprediction ....................................... 139
13.8.3 SatelliteCatalog ............................................. 139
13.8.4 Conguration ................................................ 140
13.8.5 SourcesforTLEdata........................................... 140
13.9 ArchaeoLines Plugin 141
13.9.1 Introduction ................................................. 141
13.9.2 Characteristic Declinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
13.9.3 AzimuthLines ................................................ 143
13.9.4 Arbitrary Declination Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
13.9.5 CongurationOptions......................................... 143
14 Scenery3d – 3D Landscapes ........................... 145
14.1 Introduction 145
14.2 Usage 145
14.3 Hardware Requirements & Performance 146
14.3.1 Performancenotes ........................................... 147
14.4 Model Configuration 147
14.4.1 Exporting OBJ from Sketchup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
14.4.2 Notes on OBJ file format limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
14.4.3 Configuring OBJ for Scenery3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
14.4.4 ConcatenatingOBJles ....................................... 153
14.4.5 Beyond 3D: Temporally evolving Models . . . . . . . . . . . . . . . . . . . . . . . . . 153
14.4.6 Working with non-georeferenced OBJ files . . . . . . . . . . . . . . . . . . . . . . . 153
14.4.7 Rotating OBJs with recognized survey points . . . . . . . . . . . . . . . . . . . . . 154
14.5 Predefined views 154
14.6 Example 155
15 Stellarium at the Telescope ............................. 159
15.1 Oculars Plugin 159
15.1.1 UsingtheOcularplugin........................................ 160
15.1.2 Conguration ................................................ 164
15.1.3 Scaling the eyepiece view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
15.2 TelescopeControl Plugin 172
15.2.1 Abilities and limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
15.2.2 Usingthisplug-in.............................................. 172
15.2.3 Main window (’Telescopes’) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
15.2.4 Telescope configuration window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
15.2.5 Supporteddevices ........................................... 175
15.3 RTS2 176
15.4 INDI 177
15.5 StellariumScope 178
15.6 Other telescope servers and Stellarium 178
15.7 Observability Plugin 180
16 Scripting .................................................. 183
16.1 Introduction 183
16.2 Script Console 184
16.3 Includes 184
16.4 Minimal Scripts 184
16.5 Example: Retrograde motion of Mars 184
16.5.1 Scriptheader ................................................ 184
16.5.2 Abodyofscript .............................................. 185
16.6 More Examples 187
IV Practical Astronomy
17 Astronomical Concepts ................................. 191
17.1 The Celestial Sphere 191
17.2 Coordinate Systems 192
17.2.1 Altitude/Azimuth Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
17.2.2 Right Ascension/Declination Coordinates . . . . . . . . . . . . . . . . . . . . . . . . 193
17.2.3 EclipticalCoordinates ......................................... 195
17.2.4 GalacticCoordinates ......................................... 196
17.3 Distance 196
17.4 Time 196
17.4.1 SiderealTime ................................................ 197
17.4.2 JulianDayNumber ........................................... 197
17.4.3 DeltaT ...................................................... 198
17.5 Angles 201
17.5.1 Notation .................................................... 201
17.5.2 HandyAngles ................................................ 201
17.6 The Magnitude Scale 202
17.7 Luminosity 202
17.8 Precession 203
17.9 Parallax 205
17.9.1 Geocentric and Topocentric Observations . . . . . . . . . . . . . . . . . . . . . . . 205
17.9.2 StellarParallax ............................................... 205
17.10 Proper Motion 206
18 Astronomical Phenomena .............................. 207
18.1 The Sun 207
18.2 Stars 207
18.2.1 MultipleStarSystems .......................................... 208
18.2.2 Constellations ................................................ 208
18.2.3 StarNames .................................................. 209
18.2.4 Spectral Type & Luminosity Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
18.2.5 VariableStars ................................................ 211
18.3 Our Moon 213
18.3.1 PhasesoftheMoon........................................... 213
18.4 The Major Planets 214
18.4.1 TerrestrialPlanets ............................................. 214
18.4.2 JovianPlanets................................................ 214
18.5 The Minor Bodies 215
18.5.1 Asteroids .................................................... 215
18.5.2 Comets ..................................................... 215
18.6 Meteoroids 216
18.7 Zodiacal Light and Gegenschein 216
18.8 The Milky Way 216
18.9 Nebulae 217
18.9.1 TheMessierObjects ........................................... 217
18.10 Galaxies 217
18.11 Eclipses 218
18.11.1SolarEclipses................................................. 218
18.11.2LunarEclipses ................................................ 218
18.12 Observing Hints 218
18.13 Atmospheric effects 219
18.13.1AtmosphericExtinction ........................................ 219
18.13.2AtmosphericRefraction ....................................... 219
18.13.3LightPollution ................................................ 222
19 A Little Sky Guide ........................................ 223
19.1 Dubhe and Merak, The Pointers 223
19.2 M31, Messier 31, The Andromeda Galaxy 223
19.3 The Garnet Star, µCephei 224
19.4 4 and 5 Lyrae, εLyrae 224
19.5 M13, Hercules Cluster 224
19.6 M45, The Pleiades, The Seven Sisters 224
19.7 Algol, The Demon Star, βPersei 225
19.8 Sirius, αCanis Majoris 225
19.9 M44, The Beehive, Praesepe 225
19.10 27 Cephei, δCephei 225
19.11 M42, The Great Orion Nebula 225
19.12 La Superba, Y Canum Venaticorum, HIP 62223 226
19.13 52 and 53 Bootis, ν1and ν2Bootis 226
19.14 PZ Cas, HIP 117078 226
19.15 VV Cephei, HIP 108317 226
19.16 AH Scorpii, HIP 84071 226
19.17 Albireo, βCygni 227
19.18 31 and 32 Cygni, o1and o2Cygni 227
19.19 The Coathanger, Brocchi’s Cluster, Cr 399 227
19.20 Kemble’s Cascade 228
19.21 The Double Cluster, χand hPersei, NGC 884 and NGC 869 228
19.22 Large Magellanic Cloud, PGC 17223 228
19.23 Tarantula Nebula, C 103, NGC 2070 228
19.24 Small Magellanic Cloud, NGC 292, PGC 3085 229
19.25 ωCentauri cluster, C 80, NGC 5139 229
19.26 47 Tucanae, C 106, NGC 104 230
19.27 The Coalsack Nebula, C 99 230
19.28 Mira, oCeti, 68 Cet 230
19.29 αPersei Cluster, Cr 39, Mel 20 230
19.30 M7, The Ptolemy Cluster 231
19.31 M24, The Sagittarius Star Cloud 231
19.32 IC 4665, The Summer Beehive Cluster 232
19.33 The E Nebula, Barnard 142 and 143 232
20 Exercises ................................................. 233
20.1 Find M31 in Binoculars 233
20.1.1 Simulation ................................................... 233
20.1.2 ForReal ..................................................... 233
20.2 Handy Angles 233
20.3 Find a Lunar Eclipse 234
20.4 Find a Solar Eclipse 234
20.5 Find a retrograde motion of Mars 234
20.6 Analemma 234
20.7 Transit of Venus 235
20.8 Transit of Mercury 235
20.9 Triple shadows on Jupiter 235
20.10 Jupiter without satellites 235
20.11 Mutual occultations of planets 235
20.12 The proper motion of stars 236
VAppendices
ADefault Hotkeys .......................................... 239
A.1 Mouse actions with combination of the keyboard keys 239
A.2 Display Options 239
A.3 Miscellaneous 240
A.4 Movement and Selection 241
A.5 Date and Time 241
A.6 Scripts 242
A.7 Windows 242
A.8 Plugins 242
A.8.1 AngleMeasure............................................... 242
A.8.2 ArchaeoLines ................................................ 242
A.8.3 CompassMarks .............................................. 242
A.8.4 EquationofTime ............................................. 242
A.8.5 Exoplanets................................................... 243
A.8.6 FieldofView ................................................. 243
A.8.7 MeteorShowers .............................................. 243
A.8.8 Oculars ..................................................... 243
A.8.9 Pulsars ...................................................... 243
A.8.10 Quasars ..................................................... 244
A.8.11 Satellites..................................................... 244
A.8.12 Scenery3d: 3D landscapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
A.8.13 SolarSystemEditor ............................................ 244
A.8.14 TelescopeControl ............................................ 244
BThe Bortle Scale of Light Pollution ...................... 247
B.1 Excellent dark sky site 247
B.2 Typical truly dark site 247
B.3 Rural sky 248
B.4 Rural/suburban transition 248
B.5 Suburban sky 249
B.6 Bright suburban sky 249
B.7 Suburban/urban transition 249
B.8 City sky 249
B.9 Inner-city sky 249
CStar Catalogues ......................................... 251
C.1 Stellarium’s Sky Model 251
C.1.1 Zones ....................................................... 251
C.2 Star Catalogue File Format 251
C.2.1 GeneralDescription .......................................... 251
C.2.2 FileSections.................................................. 252
C.2.3 RecordTypes ................................................ 253
C.3 Variable Stars 255
C.3.1 Variable Star Catalog File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
C.3.2 GCVSVariabilityTypes ........................................ 256
C.4 Double Stars 268
C.4.1 Double Star Catalog File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
C.5 Cross-Identification Data 269
C.5.1 Cross-Identification Catalog File Format . . . . . . . . . . . . . . . . . . . . . . . . . 269
DConfiguration Files ....................................... 271
D.1 Program Configuration 271
D.1.1 astro...................................................... 271
D.1.2 astrocalc.................................................. 274
D.1.3 color...................................................... 275
D.1.4 custom_selected_info....................................... 278
D.1.5 custom_time_correction..................................... 278
D.1.6 devel..................................................... 278
D.1.7 dso_catalog_filters.......................................... 279
D.1.8 dso_type_filters............................................. 279
D.1.9 gui....................................................... 280
D.1.10 init_location............................................... 282
D.1.11 landscape................................................. 282
D.1.12 localization................................................ 283
D.1.13 main...................................................... 283
D.1.14 navigation................................................. 283
D.1.15 plugins_load_at_startup..................................... 284
D.1.16 projection................................................. 285
D.1.17 proxy..................................................... 285
D.1.18 scripts..................................................... 286
D.1.19 search.................................................... 286
D.1.20 spheric_mirror.............................................. 286
D.1.21 stars...................................................... 287
D.1.22 tui........................................................ 287
D.1.23 video..................................................... 288
D.1.24 viewing................................................... 288
D.1.25 DialogPositions............................................. 289
D.1.26 DialogSizes................................................ 289
D.1.27 hips....................................................... 290
D.2 Solar System Configuration Files 291
D.2.1 Filessystem_major.ini .......................................... 291
D.2.2 Filessystem_minor.ini .......................................... 295
EPlanetary nomenclature ................................ 299
E.1 Format of nomenclature data file 300
E.2 How names are approved by the IAU 300
E.3 IAU rules and conventions 301
E.4 Naming conventions 302
E.5 Descriptor terms (feature types) 303
FAccuracy ................................................ 305
F.1 Date Range 305
F.2 Stellar Proper Motion 305
F.3 Planetary Positions 306
F.4 Minor Bodies 306
F.5 Precession and Nutation 307
F.6 Planet Axes 307
F.7 Eclipses 307
F.8 The Calendar 307
GGNU Free Documentation License ..................... 309
G.1 PREAMBLE 309
G.2 APPLICABILITY AND DEFINITIONS 309
G.3 VERBATIM COPYING 311
G.4 COPYING IN QUANTITY 311
G.5 MODIFICATIONS 311
G.6 COMBINING DOCUMENTS 313
G.7 COLLECTIONS OF DOCUMENTS 313
G.8 AGGREGATION WITH INDEPENDENT WORKS 313
G.9 TRANSLATION 314
G.10 TERMINATION 314
G.11 FUTURE REVISIONS OF THIS LICENSE 314
G.12 RELICENSING 314
HAcknowledgements ..................................... 317
H.1 Contributors 317
H.2 How you can help 317
H.3 Technical Articles 318
H.4 Included Source Code 319
H.5 Data 319
H.6 Image Credits 321
H.6.1 Full credits for “earthmap” texture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
H.6.2 License for the JPL planets images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
H.6.3 DSS ......................................................... 325
Bibliography ............................................. 327
Index ..................................................... 335
I
1Introduction .................................3
1.1 Historical notes
2Getting Started .............................. 7
2.1 System Requirements
2.2 Downloading
2.3 Installation
2.4 Running Stellarium
2.5 Troubleshooting
3A First Tour ..................................11
3.1 Time Travel
3.2 Moving Around the Sky
3.3 The Main Tool Bar
3.4 Taking Screenshots
4The 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 Window
4.5 The Object Search Window
4.6 The Astronomical Calculations Window
4.7 Help Window
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 still under 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 website1.
If you have questions and/or comments about this guide, or about Stellarium itself, visit the
Stellarium site at Github2or our Google Groups forum3.
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:
1http://stellarium.org
2https://github.com/Stellarium/stellarium
3https://groups.google.com/forum/#!forum/stellarium
4Chapter 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, user guide, general development
Georg Zotti
astronomical computations, Scenery 3D and ArchaeoLines plugins, general develop-
ment, 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
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. Major new features are contributed mostly by Georg Zotti and his team focussing 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 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 users 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 Qt library as main GUI and general purpose library
2009-09 plugin system, enabling a lot of new development
2010-07 Stellarium ported on Maemo mobile device
2010-11 artificial satellites plugin
2014-06 high quality satellites and Saturn rings shadows, normal mapping for moon craters
2014-07
v0.13.0: adapt to OpenGL evolutions in the Qt framework, now requires more modern
4https://groups.google.com/d/topic/fr.sci.astronomie.amateur/OT7K8yogRlI/
discussion
1.1 Historical notes 5
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
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).
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) will not contain notes about using earlier
versions than 0.13 or using very outdated hardware. New features are marked with a version
number like 0.15.2 in the margin. 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
1
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 (It may run on Vista, but unsupported. A special version
for XP is still available); Mac OS X 10.10.0 and later
3D graphics capabilities which support OpenGL 3.0 and GLSL 1.3 (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 and GLSL ES 1.0 (e.g., ARM SBCs like Raspberry Pi 2/3). On Windows,
some older cards may be supported via ANGLE when they support DirectX10.
512 MB RAM
250 MB free on disk
2.1.2 Recommended
Linux/Unix; Windows 7 and later; Mac OS X 10.10.0 and later
3D graphics card which supports OpenGL 3.3 and above and GLSL1.3 and later
1 GB RAM or more
1.5 GB free on disk (About 3GB extra required for the optional DE430/DE431 files).
A dark room for realistic rendering — details like the Milky Way, Zodiacal Light or star
twinkling can’t be seen in a bright room.
1
As of autumn 2017, you need to enable the experimental OpenGL driver and compile the drm and
Mesa 17 libraries from sources. See 2.3.3
8Chapter 2. Getting Started
2.2 Downloading
Download the correct package for your operating system directly from the main page,
http://stellarium.org
. An archive of all available versions is available at
https://sourceforge.
net/projects/stellarium/files/.
2.3 Installation
2.3.1 Windows
1. Double click on the installer file you downloaded:
stellarium-0.18.0-win64.exe for 64-bit Windows 7 and later.
stellarium-0.18.0-win32.exe for 32-bit Windows 7 and later.
stellarium-0.18.0-classic-win32.exe for Windows XP and later.
2. Follow the on-screen instructions.
2.3.2 OS X
1.
Locate the
Stellarium-0.18.0.dmg
file in Finder and double click on it or open it using
the Disk Utility application. Now, a new disk appears on your desktop and Stellarium is in it.
2.
Open the new disk and please take a moment to read the
ReadMe
file. Then drag
Stellarium
to the Applications folder.
3.
Note: You should copy Stellarium to the Applications folder before running it — some users
have reported problems running it directly from the disk image (.dmg).
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 we provide a package repository with the latest stable releases. Open a terminal
and type:
sudo add - apt - repository ppa : ste llarium / stellarium - releases
sudo apt - get upd at e
sudo apt - get insta ll s tella rium
Raspberry Pi 2/3
These tiny ARM-based computers are very popular for small and energy-efficient applications like
controlling push-to Dobsonians. A new open-source OpenGL driver stack has been made available
recently, but as of October 2017 the default Raspbian operating system comes with an outdated
version. Stellarium requires Mesa 17 or later. To set up a Raspberry Pi 2 or 3 with Raspbian
Stretch for use with Stellarium, activate the OpenGL driver in
raspi-config
and follow instructions
from the VC4 wiki.
2
The
libdrm
upgrade is required and does not harm, but you can also install
Mesa 17 in addition to the stock Mesa 13 following another set of instructions.3
For Ubuntu 16.04 LTS, follow instructions4.
Note that as of October 2017 (Mesa 17.4) the 3D planets do not work.
2https://github.com/anholt/mesa/wiki/VC4-complete-Raspbian-upgrade
. You only need
to follow the instructions on first boot, libdrm and Mesa.
3https://github.com/anholt/mesa/wiki/Building-Mesa-for-VC4
. Note that you may
need to add a symbolic link to the VC4 library. With all paths from these instructions,
ln -s ~/prefix/dri/vc4_dri.so ~/prefix/vc4_dri.so should do the trick.
4https://ubuntu-mate.community/t/tutorial-activate-opengl-driver-for-ubuntu-mate-16-04/
7094
2.4 Running Stellarium 9
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.
Stellarium (MESA mode)
Uses software rendering via MESA library. This should work on any
PC without dedicated graphics card.
On startup, a diagnostic check is performed to test whether the graphics hardware is capable of
running. If all is fine, you will see nothing of it. Else you may see an error panel informing you
that your computer is not capable of running Stellarium (“No OpenGL 2 found”), or a warning
that there is only OpenGL 2.1 support. The latter means you will be able to see some graphics,
but depending on the type of issue you will have some bad graphics. For example, on an Intel
GMA4500 there is only a minor issue in Night Mode, while on other systems we had reports of
missing planets or even crashes as soon as a planet comes into view. If you see this, try running in
Direct3D 9 or MESA mode, or upgrade your system. The warning, once ignored, will not show
again.
When you have found a mode that works on your system, you can delete the other links.
2.4.2 OS X
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.
If you don’t succeed in running Stellarium, please see the online forum
5
. 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.
5https://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
1See 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, 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.7.1 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
JDecrease the rate at which time passes
KMake time pass as normal
LIncrease the rate at which time passes
8Return 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
and slide the mouse along the
direction of daily motion to go forward, or to the other direction to go backward. 0.15.1
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
. With a little luck 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 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
Table 3.2: Moving Around the Sky
As well as travelling through time, Stellarium lets to 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.
It’s also possible 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.
14 Chapter 3. A First Tour
The forward-slash
/
and backslash
\
keys auto-zoom in an 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.
3.3 The Main Tool Bar
Figure 3.2: Night scene with constellation artwork and moon.
Stellarium can do a whole lot more than just draw the stars. Figure 3.2 shows some of
Stellarium’s visual effects including constellation line and boundary drawing, constellation art,
planet hints, and atmospheric halo around the bright Moon. The controls in the main tool bar
provide a mechanism for turning on and off the visual effects.
When the mouse if 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.3 describes the operations of buttons on the main tool bar and the side tool bar, and
gives their default keyboard shortcuts.
3.3 The Main Tool Bar 15
Feature Button Key Description
Constellations C
Draw constellations as “stick fig-
ures”
Constellation Names VDraw 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
coordinate system (RA/Dec)
Azimuth Grid Z
Draw grid lines for the horizontal
coordinate 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
coordinate system at standard epoch
J2000.0 (RA/Dec) 1
Ecliptic Grid
Draw grid lines for the ecliptic co-
ordinate system of date (Long/Lat)
1
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 Atmosphere A
Toggle atmospheric effects. Most
notably 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 IToggle “nebula images”. 1
Digitized Sky Survey Ctrl +Alt +DToggle “Digitized Sky Survey”.1
16 Chapter 3. A First Tour
Coordinate System Ctrl +M
Toggle between horizontal (Alt/Azi)
& equatorial (RA/Dec) coordinate
systems.
Goto
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
easier on the dark-adapted eye.
Full Screen Mode F11 Toggle full screen mode.
Bookmarks Alt +BToggle bookmarks window. 1
Flip view (horizontal) Ctrl +Shift +H
Flip the image in the horizontal
plane. 1
Flip view (vertical) Ctrl +Shift +V
Flip the image in the vertical plane.
1
Quit Stellarium Ctrl +QClose 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 +FShow the object search window
View Window F4 Show the view window
Time Window F5 Show the time window
Location Window F6 Show the observer location window
(map)
AstroCalc Window F10
Show the astronomical calculations
window
Table 3.3: Stellarium’s standard menu buttons. Those marked
1
must be enabled first, see section 4.3.4.
3.4 Taking Screenshots 17
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).
Stellarium creates screenshots in a directory depending on your operating system, see section
5.1 Files and Directories.
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.10.15
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
1
Unfortunately, on Windows 7 and later, with some NVidia and AMD GPUs in OpenGL mode, these
tooltips often do not work.
20 Chapter 4. The User Interface
window (open with the button or
F5
) to set the simulation time. The values for year, month,
day, hour, minutes and seconds may be modified by typing new values, by clicking the up and down
arrows above and below the values, and by using the mouse wheel.
The other tab in this window allows you to see or set Julian Day and/or Modified Julian Day
numbers (see 17.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.0.13.1
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:
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.3 The Configuration Window 21
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. See section 5.5.4 for configuration
0.16
details. Sometimes you have to try several times to get a valid 3D fix including altitude.
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.
4.3 The Configuration Window
The configuration window contains general program settings, and many other settings which do not
concern specific display options. Press the tool button or F2 to open.
4.3.1 The Main Tab
The Main tab in the configuration window provides controls for changing separately the program
and sky culture languages.
The next setting group allows to enable using DE430/DE431 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.
4.3.2 The Information Tab
The Information tab 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 colours depending on the type and level of the stored
data
Additional settings for the information display
4.3.3 The Navigation Tab
The Navigation tab (Fig. 4.5) allows for enabling/disabling of keyboard shortcuts for panning and
zooming the main view, and also how to specify what simulation time should be used when the
program starts:
System date and time
Stellarium will start with the simulation time equal to the operating system
clock.
System date at
Stellarium will start with the same date as the operating system clock, but the
time will be fixed at the specified value. This is a useful setting for those people who use
Stellarium during the day to plan observing sessions for the upcoming evening.
Other some fixed time can be chosen which will be used every time Stellarium starts.
The lowest field allows selection of the correction model for the time correction
T
(see sec-
tion 17.4.3). Default is “Espenak and Meeus (2006)”. Please use other values only if you know
what you are doing.
4.3.4 The Tools Tab
The Tools tab (Fig. 4.6) contains miscellaneous utility features, and also allows to hide or show
additional buttons in the lower button bar. If your screen is too narrow to show all buttons, you may
have to choose your optimal setup.
22 Chapter 4. The User Interface
Figure 4.3: Configuration Window: Main Tab
Figure 4.4: Configuration Window: Information Tab
4.3 The Configuration Window 23
Figure 4.5: Configuration Window: Navigation Tab
Figure 4.6: Configuration Window: Tools Tab
24 Chapter 4. The User Interface
Figure 4.7: Configuration Window: Scripts Tab
Figure 4.8: Configuration Window: Plugins Tab
4.3 The Configuration Window 25
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.
Select single constellation
When active, clicking on a star that is member in the constellation
lines will make the constellation stand out. You can select several constellations, but clicking
onto a star which is not member of a constellation line will display all constellations.
Show nebula background button
You can disable display of DSO photographs with this button.
Show bookmarks button You can enable display of Bookmarks dialog with this button.
Show ICRS grid button
You can toggle display of equatorial J2000 coordinate grid with this
button.
Show ecliptic grid button You can toggle display of ecliptic coordinate grid with this button.
Auto-enabling for the atmosphere
When changing planet during location change, atmosphere
will be switched as required.
Include nutation
Compute the slight wobble of earth’s axis. This feature is active only about 500
years around J2000.0.
Azimuth from South Some users may be used to counting azimuth from south.
Use buttons background Applies a gray background under the buttons on the bottom bar.
Auto zoom out returns to initial direction of view
When enabled, this option changes the be-
haviour of the zoom out key
\
so that it resets the initial direction of view in addition to
the field of view.
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.
Show 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.
Show DSS button You can toggle display of Digitized Sky Survey with this button.
Show galactic grid button You can toggle display of galactic coordinate grid with this button.
Show constellation boundaries button
You can toggle display of constellation boundaries with
this button.
Use decimal degrees You can toggle usage of decimal degree format for coordinates.
Topocentric coordinates
If you require planetocentric coordinates, you may switch this off. Usu-
ally it should be enabled. (See 17.9.1)
Auto select landscapes
When changing the planet in the location panel, a fitting landscape
panorama will be shown when available.
Indication for mount mode
You can activate the short display of a message when switching type
of used mount.
In addition, you can set the directory where screenshots will be stored, and you can download more
star catalogs on this tab.
4.3.5 The Scripts Tab
The Scripts tab (Fig. 4.7) allows the selection of pre-assembled scripts bundled with Stellarium that
can be run (See chapter 16 for an introduction to the scripting capabilities and language). This list
can be expanded by 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
26 Chapter 4. The User Interface
Figure 4.9: View Settings Window: Sky Tab
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.6 The Plugins Tab
Plugins (see chapter 11 for an introduction) can be enabled here (Fig. 4.8) 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.9) contains settings for changing the general appearance of
the main sky view. Some hightlights:
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.
4.4 The View Settings Window 27
Twinkle
controls how much the stars twinkle when atmosphere is enabled (scintillation, see
section 18.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.
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 brightned by terrestrial light pollution
reflected in the atmophere. Stellarium simulates light pollution and is calibrated to the Bortle
Dark Sky Scale where 1 means a good dark sky, and 9 is a very badly light-polluted sky. See
Appendix B for more information.
Solar System objects
this group of options lets you turn on and off various features related to
the planets. Simulation of light speed will give more precise positions for planetary bodies
which move rapidly against backround stars (e.g. the moons of Jupiter). The Scale Moon
option will increase the apparent size of the moon in the sky, which can be nice for wide
field of view shots.
Labels and markers
you can independantly change the amount of labels displayed for planets,
stars and nebulae. 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.
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 visiable at some times of day. Meteor showers are not currently simulated.
Atmosphere settings
An auxiliary dialog contains detail settings for the atmosphere. Here you can set atmospheric
pressure and temperature which influence refraction (see section 18.13.2), and the opacity factor
kv
for extinction, magnitude loss per airmass (see section 18.13.1).
4.4.2 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 catalogue of over
90,000 extended objects containing the combined data from many catalogues, with 200 images.
The DSO tab (Fig. 4.10) 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.3 The Markings Tab
The Markings tab of the View window (Fig. 4.11) controls the following features:
Celestial sphere
this group of options makes it possible to plot various grids and lines in the main
view.
Projection
Selecting items in this list changes the projection method which Stellarium uses to
draw the sky (Snyder, 1987). Options are:
Perspective
Perspective projection maps the horizon and other great circles like equator,
ecliptic, hour lines, etc. into straight lines. The maximum field of view is 150
. The
mathematical name for this projection method is gnomonic projection.
28 Chapter 4. The User Interface
Figure 4.10: View Settings Window: DSO Tab
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 centre of the field of view (like the distortions seen with very wide angle
camera lenses). This is more pronounced as the user zooms out. The maximum field
of view in this mode is 180.
Orthographic
Orthographic projection is related to perspective projection, but the point of
perspective is set to an infinite distance. The maximum field of view is 180.
Equal Area
The full name of this projection method is Lambert azimuthal equal-area
projection. It preserves the area but not the angle. The maximum field of view is 360
.
Hammer-Aitoff
The Hammer projection is an equal-area map projection, described by
ERNST VON HAMMER (1858–1925) in 1892 and directly inspired by the Aitoff
projection. The maximum field of view in this mode is 360.
Sinusoidal
The sinusoidal projection is a pseudocylindrical equal-area map projection,
sometimes called the Sanson–Flamsteed or the Mercator equal-area projection. Merid-
ians are mapped to sine curves.
Mercator
Mercator projection is a cylindrical projection developed by GERARDUS MER-
CATOR (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.
4.4 The View Settings Window 29
Figure 4.11: View Settings Window: Markings Tab
4.4.4 The Landscape Tab
The Landscape tab of the View window (Fig. 4.12) 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:
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.
Use associated planet and position
When enabled, selecting a new landscape will automatically
update the observer location.
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.
Minimal brightness
Use some minimal brightness setting. Moonless night on very dark locations
may appear too dark on your screen. You may want to configure some minimal brightness
here.
from landscape, if given
Landscape authors may decide to provide such a minimal brightness
value in the landscape.ini file.
30 Chapter 4. The User Interface
Figure 4.12: View Settings Window: Landscape Tab
Show landscape labels
Landscapes can be configured with a gazetteer of interesting points, e.g.,
mountain peaks, which can be labeled with this option.
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.
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
2
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
v0.15.2
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.11.
4.4.5 The Starlore Tab
The Starlore tab of the View window (Fig. 4.13) controls what 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 skyculture as default
Activate this option to load this skyculture when Stellarium starts.
Show labels
Activate display of constellation labels, like or
V
. You can further select
whether you want to display abbreviated, original or translated names.
2http://stellarium.sourceforge.net/wiki/index.php/Landscapes
4.4 The View Settings Window 31
Figure 4.13: View Settings Window: Starlore Tab
Show lines with thickness. . .
Activate display of stick figures, like or
C
, and you can
configure constellation line thickness here.
Show asterism lines. . .
Activate display of asterism stick figures (like the shortcut
Alt +A
), and
you can configure asterism line thickness here. v0.16.0
Show 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 here. v0.17.0
Show boundaries
Activate display of constellation boundaries, like
B
. Currently, boundaries
have been defined only for “Western” skycultures.
Use native names for planets
If provided, show the planet names as used in this skyculture (also
shows modern planet name for reference).
Show art in brightness. . .
Activate display of constellation art (if available), like or
R
.
You can also select the brightness here.
Show asterism labels Activate display of asterism labels, like Alt +V. v0.16.0
4.4.6 The Surveys Tab v0.18.0
The Surveys tab (Fig. 4.14) 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.27 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
32 Chapter 4. The User Interface
Figure 4.14: View Settings Window: Surveys Tab
to a given type (Deep Sky or Solar System).
You can toggle the visibility of a survey by checking the box on the left of the survey name
in the list. (Note that as of v0.18.0, only a single deep sky survey can be rendered at a time, so it
makes no sense to select more than one in the list!) Once a survey is visible you should be able to
see its loading status in the loading bar area of the sky view.
Deep sky surveys will be rendered aligned with the sky view, while solar system surveys
automatically map on the proper body.
4.5 The Object Search Window
The Object 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 key, the selection
will change to the next item in the list. Hitting the key will go to the currently highlighted
object and close the search dialog.
For example, suppose we want to locate Saturn’s moon Mimas. Type the first letter of the name,
m, to see a list of objects whose name contains m: Haumea, Miranda, Umbriel, . . .
You may want at this point to have Stellarium rather propose object names with start with the
string you enter. Do that in the Options tab of this panel. Now repeat searching (delete, and re-enter
4.5 The Object Search Window 33
Figure 4.15: The Search Window: Objects
Figure 4.16: The Search Window: Positions
Figure 4.17: The Search Window: Lists
34 Chapter 4. The User Interface
Figure 4.18: The Search Window: Options
mto start over). Now the list is shorter and contains only objects which start with m:Maia, Mars,
. . . The first item in this list, Maia, is highlighted. Pressing now would go to Maia, but we
want Mimas. We can either press a few times to highlight Mimas and then hit , or we can
continue to type the name until it is the first/only object in the list.
The Position tab (Fig. 4.16) provides a convenient way to enter a set of coordinates.
The List Search tab (Fig. 4.18) 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 go to that object.
The Options tab (Fig. 4.18) provides a few settings to fine-tune your search experience. When
the name of an object to find is typed in the object window and you are connected to the internet and
“Extend search” is ticked, Stellarium will search the SIMBAD on-line data bases for its coordinates.
You can then click the button or press return. 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.
4.6 The Astronomical Calculations Window
This window provides advanced functionality, some of which is still in an experimental phase.
v0.15.0
You can call it by pressing
F10
or the button on the left menu bar. The Astronomical
Calculations window shows six tabs with different functionality.
4.6.1 The Positions Tab
This tab shows J2000.0 or horizontal positions, magnitudes and additional parameters (e.g. surface
v0.16.0
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 (Figure 4.19). You may also export the list of positions into a CSV file.
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 circles
(Figure 4.20).
4.6 The Astronomical Calculations Window 35
Figure 4.19: Astronomical Calculations (AstroCalc): Celestial positions
Figure 4.20: Astronomical Calculations (AstroCalc): Plot trace of planet
When you click on a date, an orange circle indicates this date and/or magnitude. Double-
clicking sets the respective date and brings the object to focus. Dates and/or magnitudes will show
near position markers when Show dates and/or Show magnitudes checkboxes are active.
You can export the calculated ephemeris into a 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 (Figures 4.21
and 4.22), or observe the visibility of Mercury, Venus or a comet in the twilight sky.
36 Chapter 4. The User Interface
Figure 4.21: Astronomical Calculations (AstroCalc): Analemma on the Earth
Figure 4.22: Astronomical Calculations (AstroCalc): Analemma on Mars
4.6 The Astronomical Calculations Window 37
4.6.3 The Phenomena Tab
This tab allows you to compute phenomena like conjunctions, oppositions, occultations and eclipses
(in special cases) between planetary objects (Figure 4.23). You can export the calculated phenomena
into a CSV file.
Figure 4.23: Astronomical Calculations (AstroCalc): Phenomena
4.6.4 The “Altitude vs. Time” Tab
On this tab you can compute the geometrical altitude of the currently selected object and date and
draw it as a graph (Figure 4.24).
Figure 4.24: Astronomical Calculations (AstroCalc): Altitude vs. Time
38 Chapter 4. The User Interface
4.6.5 The Graphs Tab
Figure 4.25: Astronomical Calculations (AstroCalc): Graphs
This tab can show two functions over time for the current year and draw graphs for them in one
v0.16.0
screen (Figure 4.25). You can select from
Magnitude vs. Time
Phase vs. Time
Distance vs. Time
Elongation vs. Time
Angular size vs. Time
Phase angle vs. Time
This tool may be very helpful for educational and statistics purposes.3
4.6.6 The “What’s Up Tonight” (WUT) Tab
The “What’s Up Tonight” (WUT) tool
4
displays a list of objects that will be visible at night for the
v0.16.0
current date and location.
The objects are organized into type categories. Select an object type in the box labeled Select
a Category, and all objects of that type which are above the horizon on the selected night will be
displayed in the box labeled Matching Objects. For example, in the screenshot, the Planets category
has been selected, and three planets which are up in the selected night are displayed (Jupiter, Mars
and Mercury).
By default, the WUT will display objects which are above the horizon between sunset and
midnight (i.e. in the evening). You can choose to show objects which are up between midnight and
dawn (in the morning), around midnight, or any time between dusk and dawn (any time tonight)
using the combobox near the top of the window. You can also choose to see only those objects
that are brighter than a certain magnitude by setting a minimum magnitude using the Show objects
brighter than magnitude spinbox. You may center an object from the right list in the sky map just
by selecting it.
Note that only DSO from catalogs which you have selected in the DSO panel (section 4.4.2)
will be found.
3The idea for this tool has been obtained from SkytechX:http://www.skytechx.eu/
4This tool has been partially ported from the KStars planetarium: https://edu.kde.org/kstars/
4.6 The Astronomical Calculations Window 39
Figure 4.26: Astronomical Calculations (AstroCalc): What’s Up Tonight (WUT)
4.6.7 The “Planetary Calculator” (PC) Tab
The “Planetary Calculator” (PC) tool has been added after user requests. It computes the relations
v0.17.0
between two Solar system bodies for the current date and location — linear and angular distances,
orbital resonances and orbital velocities.
Figure 4.27: Astronomical Calculations (AstroCalc): Planetary Calculator (PC)
40 Chapter 4. The User Interface
4.7 Help Window
Figure 4.28: Help Window
The Help window 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.1 Editing 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.
The About Tab (Fig. 4.29) shows version and licensing information, and a list of people who
helped to produce the program.
The Log Tab (Fig. 4.30) 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 directory (see 5.1).
4.7 Help Window 41
Figure 4.29: Help Window: About
Figure 4.30: Help Window: Logfile
II 5Files and Directories ...................... 45
5.1 Directories
5.2 Directory Structure
5.3 The Logfile
5.4 The Main Configuration File
5.5 Getting Extra Data
6Command Line Options ...................51
6.1 Examples
6.2 Special Options
7Landscapes ............................... 55
7.1 Stellarium Landscapes
7.2 Creating Panorama Photographs for Stellarium
7.3 Panorama Postprocessing
7.4 Other recommended software
8Deep-Sky Objects ........................ 79
8.1 Stellarium DSO Catalog
8.2 Adding Extra Nebulae Images
9Adding Sky Cultures ...................... 89
9.1 Basic Information
9.2 Skyculture Description Files
9.3 Constellation Names
9.4 Star Names
9.5 Planet Names
9.6 Deep-Sky Objects Names
9.7 Stick Figures
9.8 Constellation Boundaries
9.9 Constellation Artwork
9.10 Seasonal Rules
9.11 References
9.12 Asterisms and help rays
9.13 Publish Your Work
10 Surveys ..................................... 95
10.1 Introduction
10.2 Hipslist file and default surveys
10.3 Solar system HiPS survey
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 for the account which is running Stellarium. If the file is not
found there, Stellarium looks in the installation directory
1
. 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 \
% USER PROFILE %\ Stellarium \
% HOMEDRIVE %\% HOMEPATH %\ Stellari um \
% HOME %\ St ella rium \
Stellarium ’s instal lat ion directory
1The installation directory was referred to as the config root directory in previous versions of this guide
46 Chapter 5. Files and Directories
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”.2
screenshot save directory
Screenshots will be saved to the
Pictures/Stellarium
directory,
although this can be changed in the GUI (see section 4.3.4) or with a command line option
(see section 6).
5.1.2 Mac OS X
installation directory
This is found inside the application bundle,
Stellarium.app
. See Inside
Application Bundles3for more information.
user directory This is the sub-directory Library/Preferences/Stellarium/ (or
~/Library/Application Support/Stellarium
on newest versions of Mac OS X) 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.2 Directory Structure
Within the installation directory and user directory defined in section 5.1, files are arranged in the
following sub-directories.
landscapes/
contains data files and textures used for Stellarium’s various landscapes. Each
landscape has its own sub-directory. The name of this sub-directory is called the landscape
ID, which is used to specify the default landscape in the main configuration file, or in script
commands.
skycultures/
contains constellations, common star names and constellation artwork for Stel-
larium’s many sky cultures. Each culture has its own sub-directory in the skycultures
directory.
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 0.18.0, although the directory structure is in place - each set
of nebula textures has its own sub-directory in the nebulae directory.
2
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!
3http://www.mactipsandtricks.com/articles/Wiley_HT_appBundles.lasso
5.3 The Logfile 47
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 0.18.0, 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 and DE431 (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 lines, grids, etc. can only be changed by directly
editing the configuration file.
4
This section describes some of the settings a user may wish to
modify in this way, and how to do it.
If the configuration file does not exist in the user directory when Stellarium is started (e.g., the
first time the user starts the program), one will be created with default values for all settings (refer
to section 5 Files and Directories for the location of the user directory on your operating system).
The name of the configuration file is config.ini5.
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 Configu-
ration File.
4Color values can be edited interactively by the Text User Interface plugin (see 12.6).
5
It is possible to specify a different name for the main configuration file using the
--config-file
command line option. See section 6 Command Line Options for details.
48 Chapter 5. Files and Directories
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 90 thousand deep-sky objects6in the normal program downloadv0.16.1
(the standard edition of Stellarium DSO catalog, see section 8.1), but an extended DSO catalog
with over one million objects (up to
19.0m
) may be downloaded from Stellarium’s SourceForge
website7:
Version Filename MD5 hash Size
3.3; extended edition catalog.dat b703354655d7d7f109f2ed97100b8de5 28.6 MB
The file can be placed in a folder named
nebulae/default
inside either the installation
directory (replacing of standard catalog) or the user directory (see section 5.2).
5.5.3 Alternative Planet Ephemerides: DE430, DE431
By default, Stellarium uses the VSOP87 planetary theory, an analytical solution which is able to
v0.15.0
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 from NASAs Jet Propulsion Laboratory (JPL) (Folkner et al., 2014). The data
files have to be downloaded separately, and most users will likely not need them. DE430 provides
highly accurate data for the years
+1550... +2650
, while DE431 covers years
13000... +17000
,
which allows e.g. archaeoastronomical research on Mesolithic landscapes. Outside these year
ranges, positional computation falls back to VSOP87.
The integration of this feature is still somewhat experimental, and some other current approxi-
mations will lead to numerical data which differ slightly from best possible ephemerides. Please at
least compare with JPL Horizons8for dependable results.
To enable use of these data, download the files from JPL9:
Ephemeris Filename MD5 hash Size
DE430 linux_p1550p2650.430 707c4262533d52d59abaaaa5e69c5738 97.5 MB
DE431 lnxm13000p17000.431 fad0f432ae18c330f9e14915fbf8960a 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:
6Over 83 thousand deep-sky objects in version 0.16.0.
7https://sourceforge.net/projects/stellarium/files/Extra-data-files/DSO/3.3/
8https://ssd.jpl.nasa.gov/horizons.cgi
9ftp://ssd.jpl.nasa.gov/pub/eph/planets/Linux/
. (Also download from this directory if you
are not running Linux!)
5.5 Getting Extra Data 49
[ astro ]
de430_ path = C :/ Astrodata / JPL_DE43x / lin ux_p155 0p26 50 .430
de431_ path = C :/ Astrodata / JPL_DE43x / lnx m13 000p170 00 .431
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 both,
preference will be given for DE430 if the 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
0.16
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 preferrably should not connect
directly to a GPS USB device, serial device, bluetooth device, etc., but uses 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
10
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.
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
gpsd_hostname = " localhost "
gpsd_port = 2947
Also, gpsd must be started with the -G parameter to enable this.
10http://catb.org/gpsd/index.html
50 Chapter 5. Files and Directories
Even your smartphone can be used as GPS data source
11
: Apps like
BlueNMEA
can provide
these data for
gpsd
, but you must make sure to configure hostname/IP Address and port
number correctly, for example
sudo gpsd -n - D8 -S 1001 tcp ://1 92.1 6 8.1. 101:4 352
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.12
If this is the only serial device, Stellarium should automatically connect to it regardless of
configuration entries. You cannot change the USB plug after you first have received a location
fix. 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_interface = "COM3"
gps_ bau drate = 4800
From now on, always use the same USB plug configuration to connect GPS and telescope.
13
If
GPS lookup fails, 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
BlueNMEA
to provide the NMEA
strings.
11Thanks to user Caysho for this hint.
12On Linux, this may read /dev/ttyUSB0,/dev/gps0 or similar.
13
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).
6. 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 say the file
my_config.ini
in
the current working directory.
--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.
52 Chapter 6. Command Line Options
--screenshot-dir path
Specify the directory to which screenshots
will be saved.
--full-screen yes or no
Over-rides the full screen setting in the config
file.
--home-planet planet Specify observer planet (English name).
--longitude longitude Specify latitude, e.g. +53d58’16.65"
--latitude latitude Specify longitude, e.g. -1d4’27.48"
--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 The initial field of view in degrees.
--projection-type ptype
The initial projection type (e.g.
perspective).
--spout or -S all or sky Act as Spout sender (See section 6.2.1).12
--spout-name name
Use
name
as name of the Spout sender. De-
fault name: Stellarium.1
--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).1
--angle-d3d9 or -9 [none]
Force use Direct3D 9 for ANGLE OpenGL
ES2 rendering engine.1
--angle-d3d11 [none]
Force use Direct3D 11 for ANGLE OpenGL
ES2 rendering engine.1
--angle-warp [none]
Force use the Direct3D 11 software rasterizer
for ANGLE OpenGL ES2 rendering engine.
1
--mesa-mode or -m [none]
Use MESA as software OpenGL rendering
engine.1
--safe-mode or -s [none] Synonymous to --mesa-mode.1
--compat33 or -C [none]
Request OpenGL 3.3 Compatibility Profile.
May help for certain driver configurations.
Mac?
1On Windows only
2This function requires running in OpenGL mode.
6.1 Examples 53
--fix-text or -t [none]
Alternative way of creating the Info text, re-
quired on some systems.3
If you want to avoid adding the same switch every time when you start Stellarium from the
0.15
command line, you can also set an environment variable STEL_OPTS with your default options.
6.1 Examples
To start Stellarium using the configuration file,
configuration_one.ini
situated in the
user directory (use either of these):
stel lari um -- config - file = conf igu rat ion _on e . ini
st ella riu m - c con figu rat ion_ one . ini
To list the available landscapes, and then start using the landscape with the ID “ocean”
stellarium --list-landscapes
stel lari um -- landsca pe = ocean
Note that console output (like --list-landscapes) on Windows is not possible.
6.2 Special Options
6.2.1 Spout 0.15.1
Apart from stand-alone use, Stellarium can be used as multimedia source in larger installations,
in museums or science exhibitions.
Spout4
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 on the NVidia hardware. For permanent setting, use the NVidia configuration
dialog to configure Stellarium explicitly to run always on the NVidia card.
3E.g., Raspberry Pi 2/3 with Raspbian Jessie and VC4 drivers from Mesa 11 (2016).
4http://spout.zeal.co/
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 demonstra-
tion in “skyscape astronomy”, a term which describes the connection of landscape and the sky
above (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.
7.1 Stellarium Landscapes
As of version 0.15, the available landscape types are:
polygonal
A point list of measured azimuth/altitude pairs, used to define a sharp horizon polygon.
The area below the horizon line is colored in a single color (Section 7.1.2).
spherical
The simple form to configure a photo-based panorama: A single image is used as texture
map for the horizon (Section 7.1.3).
old_style
The original photo panorama. This is the most difficult to configure, but allows highest
resolution by using several texture maps (Section 7.1.4).
fisheye
Another 1-texture approach, utilizing an image made with a fisheye lens. This 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,
56 Chapter 7. Landscapes
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 ssume 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/Preferences/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.4). For our purposes we should consider especially the
coordinates in the location section mandatory!
[location]
planet = Earth
country = Austria
name = KGA Rosenburg
latitud e = +48 d38 3.3 "
long itud e ␣= ␣ +15 d38 2.8 "
altitude = 266
light_pollution = 1
at m ospher i c_exti n ction_ c oeffic i ent = 0.2
display_fog = 0
atmospheric_temperature = 10.0
at mosp heri c _pre ssur e = 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.
name
(optional) Name of the location. This may contain spaces, but keep it short to have it fully
visible in the selection box.
Since v0.11.0, there are a few more optional parameters that can be loaded if the according switch
is active in the landscape selection panel. If they are missing, the parameters do not change to
defaults.
light_pollution (optional) Light pollution of the site, given on the Bortle Scale (1: none . . . 9:
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".
7.1 Stellarium Landscapes 57
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 only recently (since 0.13) to allow the use of measured horizons.
Users of
Cartes du Ciel1
will be happy to hear that the format of the list of measurements is
compatible.
This is the technically simplest of the landscapes, but may be used to describe accurately
measured horizon lines. 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 is a small caveat: 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).
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 .
Demonstrates compatibility with
horizon desc ription s from Cartes du Ciel .
po ly gon al_ ho riz on_l is t = ho riz on_ Gen eve . txt
polygonal_angle_rotatez = 0
grou nd_ color = .15 ,.45 ,.45
horizon_line_color = .75,.45,.45
Where:
name appears in the landscape tab of the configuration window.
type identifies the method used for this landscape. polygonal in this case.
author lists the author(s) responsible for images and composition.
description
gives a short description visible in the selection panel. The text can be superseded
by optional description.<lang>.utf8 files.
polygonal_horizon_list is the name of the horizon data file for this landscape.
polygonal_horizon_list_mode
(optional) the two first columns in the list are numbers: az-
imuth 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.
1SkyChart / Cartes du Ciel planetarium: http://www.ap-i.net/skychart/en/start
58 Chapter 7. Landscapes
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.
horizon_line_color
(optional, default: invisible) used to draw a polygonal 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) In rare cases like horizon lines for high
mountain peaks with many negative horizon values this should be set to true. (since v0.15.0)
7.1.3 Spherical landscape
This method uses a more usual type of panorama – the kind which is produced directly from
software such as
autostitch
or
Hugin2
. 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 = apol lo17 . png
A more elaborate example is found with the Grossmugl landscape:
[landscape]
name = Grossmugl
type = spherical
aut hor = G uent her Wu ch te rl , K uf fner - S ter nwa rte . at ;
Lights cape : Georg Zotti
descripti on = Field near Leeberg , Grossmugl ( Riesentumulus ),
Austria - Primary Observing Spot of the Grossmugl
Star ligh t Oasis - http :// star lig hto asi s . org
maptex = gross mugl_ l eebe r g_cr o p11 .25. png
maptex_top=11.25
maptex_fog = grossmugl_leeberg_fog_crop22.5.png
maptex_f og_ top = 22.5
maptex_fo g_bo ttom = -22.5
maptex_illum = grossmugl_leeberg_illum_crop0.png
maptex_illum_bottom = 0
angle_rotatez=-89.1
minimal_brightness = 0.0075
po ly gon al_ ho riz on_l is t = ho riz on_g ros smug l . txt
polygonal_angle_rotatez=0
horizon_line_color = .75,.45,.45
minimal_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.
2http://hugin.sourceforge.net/
7.1 Stellarium Landscapes 59
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. ;-)
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.
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
horizon_line_color 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. (since v0.14.0)
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_top
. You
should then stretch the texture to a full power of 2, 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
60 Chapter 7. Landscapes
Figure 7.1: Old_style landscape: eight parts delivering a high-resolution panorama. The
bottom (ground) texture, drawn on a flat plane, is not shown here.
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 landscape3:
[landscape]
name = KGA Rosenburg
author = Georg Zotti , VIAS / ASTROSIM
descripti on = KGA Rosenburg
type = old_style
nbsidetex = 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
3the groundtex grassground.png mentioned here has been taken from the Guereins landscape.
7.1 Stellarium Landscapes 61
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
grou ndte x = gra ssg round . png
ground = groundtex :0:0:1:1
nb_decor_repeat = 1
decor_alt_angle = 82
decor_angle_shift = -62
; Rotatez deviates from -90 by the Meridian Conver gence .
; The original landscape pano is grid - aligned , not north - aligned !
de cor_ angl e_ro tatez = -90.525837223
ground_angle_shift = -62
gr ound _ang l e_ro tate z = 44.4 741 62777
draw_ground_first = 1
fogtex = fog . png
fog_alt_angle = 20
fog_angle_shift = -3
fog = fogtex :0:0:1:1
calibrated = true
[location]
planet = Earth
latitud e = +48 d38 3.3 "
long itud e ␣= ␣ +15 d38 2.8 "
altitude = 266
light_pollution = 1
at m ospher i c_exti n ction_ c oeffic i ent = 0.2
display_fog = 0
atmospheric_temperature = 10.0
at mosp heri c _pre ssur e = 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. v0.13.1
nbside is the number of side textures
62 Chapter 7. Landscapes
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.
4
Note that for this landscape, accurate overlay of fog and landscape is only
guaranteed if calibrated=true and tan_mode=true.
nb_decor_repeat
is the number of times to repeat the side textures in the 360 panorama. (Useful
photo panoramas should have 1here)
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.
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.
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 1 the ground is drawn in front of the scenery, i.e. the side textures will
overlap over the ground texture.
calibrated
(optional). Only if true,
decor_alt_angle
etc. really work as documented above.
v0.10.6
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.
decor_angle_rotatez
angular rotation of the scenery around the vertical axis. This is handy for
rotating the landscape so North is in the correct direction. If 0, the left edge of
tex0
is due
east.
ground_angle_shift
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
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
4In very wide-angle views, the fog cylinder may become visible in the corners.
7.1 Stellarium Landscapes 63
decor_angle_rotatez require adjustments of this angle in the opposite direction!
fog_alt_angle vertical angular size of the fog cylinder.
fog_angle_shift vertical angular offset of the fog cylinder.
draw_ground_first
if 1, the ground is drawn before the sides, i.e. the side textures may overlap
the ground texture if ground_angle_shift >decor_angle_shift.
polygonal_horizon_list (optional) see 7.1.2
polygonal_horizon_list_mode (optional) see 7.1.2
polygonal_angle_rotatez (optional, default=0) see 7.1.2
horizon_line_color see 7.1.2
minimal_brightness see 7.1.2
minimal_altitude 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. Whereever
the image is transparent Stellarium will render the sky.
The
landscape.ini
file for a fish-eye type landscape looks like this (this example is based on
the Trees landscape which comes with Stellarium):
[landscape]
name = Trees
type = fisheye
author = Robert Spearman . Light pollution image : Georg Zotti
descripti on = Trees in Greenlake Park , Seattle
maptex = trees_5 12 . png
ma pte x_ill um = t ree s_i llu m_5 12 . png
ma ptex _fo g = tree s_f og_ 512 . png
texturefov = 210
angle_rotatez = 17
tesselat e_r ows = 28
tesselat e_c ols = 60
Where:
name appears in the landscape tab of the configuration window.
type identifies the method used for this landscape. fisheye in this case.
author lists the author(s) responsible for images and composition.
description
gives a short description visible in the selection panel. The text will be superseded
by optional description.<lang>.utf8 files.
maptex is the name of the image file for this landscape.
maptex_fog (optional) is the name of the fog image file for this landscape.
maptex_illum
(optional) is the name of the nocturnal illumination/light pollution image file for
this landscape.
texturefov is the field of view that the image covers in degrees.
angle_rotatez (optional) Angle (degrees) to adjust azimuth.
tesselate_rows
(optional, default=20) If straight edges in your landscape appear broken, try
increasing.
64 Chapter 7. Landscapes
Figure 7.2: Texture for the Trees Fisheye landscape.
tesselate_cols
(optional, default=40) If straight edges in your landscape appear broken, try
increasing.
polygonal_horizon_list (optional) see 7.1.2
polygonal_horizon_list_mode (optional) see 7.1.2
polygonal_angle_rotatez (optional, default=0) see 7.1.2
horizon_line_color see 7.1.2
minimal_brightness see 7.1.2
minimal_altitude 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
7.1 Stellarium Landscapes 65
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 0.14
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 gaz ett eer for Gros smu gl land sca pe .
# Can be used to bette r des cri be the landscape ,
# i.e. show label s on la ndscape f eatu res .
# Fields must be s epar ate d by vertica l line ,
# lab el must not have s uch a ver tic al line .
# Comm ent s have this hash mark in firs t col umn .
# coo rdina tes in de gree s from true No rth .
# line to war ds zenith draw s a s ingle line st ric tly upwa rd .
# l abel is c ente red on line endpoin t .
# Az imu th | Al tit ude | degrees | azimuth | label
# | | towar ds z enith | shift |
11 3.66 | 5.5 | 4 | -6 | Leeberg
35 | 1.5 | 2.5 | 0 | Gro ssmu gl
335 | 2 | 2 | 0 | S tein abru nn
305 | 2 | 1 | 0 | R ing endo rf
18 0 | 2 | 2 | 0 | V ie nn a (3 0 km )
135 | 2 | 0.5 | 0 | Wind power plant Stra ssh of
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.4), 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.
66 Chapter 7. Landscapes
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)
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
5
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
5
In many references you will find “Nodal Point” mentioned here. But see these:
http://en.
wikipedia.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 Photographs for Stellarium 67
Figure 7.4: Automated panorama head. (Source: Wikipedia
https://commons.wikimedia.org/
wiki/File:Rodeon_vr_head_01.jpg)
camera!
The images should match in brightness and white balance. If you can shoot in RAW, do so to
be able to change white balance later. If the camera can only create JPG, ensure you have set the
camera to a suitable white balance before taking the photos and not to “auto”, because this may
find different settings and thus give colour mismatches. Exposure brightness differences can be
largely removed during stitching, but good, well-exposed original shots always give better results.
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
Hugin6
, 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 automati-
cally 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
6http://hugin.sourceforge.net/
68 Chapter 7. Landscapes
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, field of view, . . . ) 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 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 7
. Then press
Create control points
.
This opens a dialog box in which you can see output of the selected feature point extractor.
It should finish with a box telling you the number of identified points. In rare cases some
images cannot be linked to others, you will have to manually add or edit feature points in
those cases.
Now it’s time to start optimisations. On the
Geometric Optimimisation
combo, start with
the button
Positions, incremental from anchor
, and press
Calculate
. Moments later, a first
rough match is available for inspection.
First open the Preview window (press
Ctrl +P
or click the blue icon). Assumed your
images cover the full horizon, the window shows an equirectangular area (360 degrees along
the horizon and 180 degrees from zenith to nadir). The anchor image should be close to the
image center, and the other images should be already well-aligned to both sides. You can set
the exact center point by clicking it in the image. If the horizon appears badly warped, use
the right mouse key and click on the horizon 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.
7If you forget this, you can remove cloud points by calling Celeste in the control point editor later
7.2 Creating Panorama Photographs for Stellarium 69
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
8
which have moved between photos. For handheld photos, the
following considerations should be observed.
The most important line which we want to create in all perfection is the visible horizon, where
sky and earth meet. The foreground, usually grassy or rocky, is of lesser interest, and stitching
errors in those areas may not even be relevant.
Therefore, matchpoints with large errors in the foreground can be safely removed, while, if
necessary, points on the horizon should be added manually. Use the
Control Points
tab, select
adjacent images (start with 0 on the left and 1 on the right side), and delete the worst-fitting
matchpoints closest to the camera (near the bottom of the images). We now start a long phase of
re-optimizing and deletion of ill-matching points as long as those are far from the horizon. When
all near matchpoints are deleted, the result should already look not too bad.
For continued optimisation, the number of parameters to optimize can be extended. To begin, I
recommend
Positions and View (y, p, r, v)
, which may find a new focal length slightly different from
the data in the EXIF tags. Again, delete further foreground points. If after a few rounds you
still have bad point distances, try
Positions and Barrel Distortion (y, p, r, b)
to balance distortion by bad
optics, or even go up to
Everything without translation
. Optimisation can only reach perfect results if
you did not move between exposures. Else, find a solution which shows the least error.
In case you took your photos not on a tripod and moved too much, you may even want to play
with the translation options, but errors will be increasingly hard to avoid.
Using Straight Edges as Guides
If the panorama contains straight lines like vertical edges of buildings, these can be used to
automatically get a correctly levelled 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
8You should have created control points with the Celeste option!
70 Chapter 7. Landscapes
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 postprocessing.
This optimisation 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
optimisation 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
conbinations
Hugin
may think it has to re-balance the values. In these cases, don’t run the
photometric optimiser. Some image exposure values have to be changed manually, and the effect
supervised in the preview window. Usually the smooth blending in the subprogam
enblend
called
by Hugin will hide remaining differences.
Stitching
When you are happy with the panorama in the preview window and the matchpoints 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 arcminute resolution, you would aim for
360 ×60 =21600
7.3 Panorama Postprocessing 71
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.
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 postprocessing 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
72 Chapter 7. Landscapes
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
)
9
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
10
. 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.4.3) for a considerable improve-
ment, and Cygwin (7.4.4) for experts.
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.11
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.
co nve rt l an dsc ape . png - crop 4096 x 11 52 +0 +896
- res ize 4096 x 1024 ! l and sc ape _c rop pe d . 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
- res ize 4096 x 1024 ! l and sc ape _c rop pe d . 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.
9http://www.imagemagick.org/
10These may typically be .BAT files on Windows, or various shell scripts on Linux or Mac.
11
Most modern graphics cards no longer require the “powers of two” image sizes, but we keep this practice
to increase compatibility.
7.3 Panorama Postprocessing 73
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
- res ize 1 63 84 x204 8 !
- type Tr ueC ol or Mat te - d epth 8
- crop 2 04 8 x 2048 + r epa ge
png : S TELL AR IUM _L AND SCAP EP ATH / L AND SCA PE_ NAM E / Horiz -% d. png
This creates 8 images. See section 7.1.4 for the
landscape.ini
where these images can be
referenced. Don’t forget to read off top and bottom lines (altitudes in degrees) from your grid,
the vertical extent will form the
decor_alt_angle
, and the bottom line the
decor_angle_shift
entries in this file.
Creating a ground image for old_style landscapes
When you want a good ground image for an
old_style
landscape from your panorama and not
just fill the
groundtex
with a monochrome texture or a map, you have to create a ground view in
Hugin
. But you may have already created a huge pano! This can also be used as source image, and
a ground shot can be extracted with a reversed operation. In principle, all you need to know is the
field of view around the nadir. Figure 7.5 shows a simple configuration file.
# hugin project file
#hugin_ptoversion 2
p f0 w2048 h 2048 v92 E0 R0 n " TIFF_m ␣ c: LZW ␣ r: CROP "
m g1 i0 f0 m2 p0 .00784314
# image lines
# - hug in cr opF ac tor =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" Eq irect_P ano360 . 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.
74 Chapter 7. Landscapes
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 grou nd . pto -o gro un d . png
con vert groun d . png - depth 8 gro und _8bi t . 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.
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 Optimising
Positions incremental from anchor
,
then go for view and barrel optimisation, 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 subhorizon 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 optimisation step, export a new pano image, load as layer in
GIMP, and check again.
7.3 Panorama Postprocessing 75
Figure 7.6:
Hugin
s Fast Panorama Preview can be used to check which images are
connected to its neighbours. Most important are good matches along the horizon, the
images in the lower rows are clearly less important. If captured on a tripod, they should
still match.
Basic rules to observe (use obvious inverses).
If image aligns well in azimuth but overshoots the grid to the right: Increase yaw 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
optimisation), and when the horizon ring is aligned perfectly, deactivate further optimisation in
Hugin
for those photos while “attaching” (optimising) the lower photos. In
Hugin
s
Photos
tab,
select
Optimise Geometric Custom Parameters
. This opens an extra tab
Optimiser
, 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 optimisation.
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.
76 Chapter 7. Landscapes
7.3.4 Artificial Panoramas
I have created a website
12
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
screenshots13.
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
14
. Postprocessing steps are the same as for
photo-panoramas: make sky invisible, crop, etc.
It is also interesting to switch on the 3D buildings layer before creating the images. If temples
or other buildings are accurate, this will give an even closer approximation to what would be visible
on-site. Note however that not every building will be modelled in usable quality, and that usually
vegetation is not included in the 3D buildings layer. Also, if you are too close to buildings, they
may be cut away by the near clipping plane of the rendering.
These images, based on
Google Earth
imagery and the SRTM topographic model, seem usable
as first rough approximation to a photo-based or surveyed panorama. Note that it is definitely not
accurate enough for representing nearby horizon features or critically important mountain peaks,
and please note that Google has image copyright which at least requires you to acknowledge when
displaying these pictures.
7.3.5 Nightscape Layer
Since version 0.13, Stellarium can simulate artificial illumination, like streetlamps, bright windows,
or the skyglow over cities (Zotti and Wuchterl, 2016). One way to create this layer is to make 2
panorama series during the day and night and process these in the same
Hugin
project to align
those photos, and then stitch two separate images by selecting either the daylight or the nighttime
shots. The night panorama has to be processed to remove stars, airplanes, etc.
The other way is a simple layer overpainted in the image processing program. As rough
recommendation, use several layers to prepare this feature:
Put a semitransparent black layer over your daylight image, this helps you to place your
painted pixels.
Paint windows, street lamps, signs, . . . . You may apply a layer style to produce some glow.
To draw an impression of more light in the atmosphere (city skyglow), use a gradient with
some brownish color. Generally the color depends on the appropriate mix of city lights
(sodium, mercury vapour, etc.). Note that on the city outskirts a simple vertical gradient will
12http://homepage.univie.ac.at/Georg.Zotti/php/panoCam.php
13Note that if you work with Google Earth Pro, you can create different FoV!
14There is a wide overlap in the images to allow generous trimming.
7.4 Other recommended software 77
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 Other recommended software
Here is a short collection of other useful programs for (panorama) image manipulation and other
tasks on Windows.
7.4.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
preferrable over any image viewer built into Windows. Unfortunately however, it has no panorama
viewer function!
7.4.2 FSPViewer
FSPViewer15
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.
Imag eNam e = H ori zon _Ro senb urg . jpg
WindowTit le = Hor izon _Rosenb urg
hFov =70
# Formula : HP =100*( h /2 - upper )/( lower - upper ) in Hugin crop , or
# HP =100* zeroRow / imgHeight
HorizonPosition=33.8
Figure 7.7: FSP configuration file (example)
7.4.3 Clink
Clink16
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
15Further details are available on its home page http://www.fsoft.it/FSPViewer/.
16http://mridgers.github.io/clink/
78 Chapter 7. Landscapes
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.
7.4.4 Cygwin
Compared to Linux, the command line of Windows can be a humbling experience. None of the
wonderful helpers taken for granted on Linux are available.
Cygwin17
provides a command line
console with
bash
shell and all the niceties like
make
,
awk
,
sed
, etc. which seem essential for
routine work. If you are used to Linux tools, use inline scripts in your
Makefile
s and need more
than Clink can offer, you should install Cygwin.
7.4.5 GNUWin32
Alternative to
Cygwin
, several of those nice tools (
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
Cygwin
but just want to call
awk
or
sed
inside your
.BAT
scripts, maybe
this is enough.
17https://cygwin.com/index.html
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 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 of the file format.
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 of the file format.
8.1 Stellarium DSO Catalog
Stellarium’s DSO Catalog contains over 90000 objects
1
(up to
15.5m
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
names.dat List of proper names of the objects from file catalog.dat
ASCII file can be converted into binary format through enabling an option in the file
config.ini
(See 5.4):
[ devel ]
convert_dso_catalog = true
The file
catalog.txt
should be put into the directory
.../nebulae/default/
and you
should create an empty file
catalog.pack
to storing the binary catalog. After converting the data
into binary format you should gzip them by the command
1
An extended edition of this catalog with over one million objects may be downloaded and installed
manually (see section 5.5.2).
80 Chapter 8. Deep-Sky Objects
gzip -nc catalog . pack > catalog . dat
Stellarium DSO Catalog contains data and supports the designations for follow catalogues:
NGC New General Catalogue
IC Index Catalogue
MMessier Catalog
CCaldwell Catalogue
BBarnard 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 galaxies2
UGC The Uppsala General Catalogue of Galaxies
Ced Cederblad Catalog of bright diffuse Galactic nebulae (Cederblad, 1946)
Arp Atlas of peculiar galaxies (Arp, 1966)V0.16.0
VV
The catalogue of interacting galaxies by Vorontsov-Velyaminov (Vorontsov-Velyaminov,
Noskova, and Arkhipova, 2001)V0.16.0
PK Version 2000 of the Catalogue of Galactic Planetary Nebulae (Kohoutek, 2001)
V0.16.0
PN G The Strasbourg-ESO Catalogue of Galactic Planetary Nebulae (Acker et al., 1992)
V0.16.1
SNR G A catalogue of Galactic supernova remnants (Green, 2014)
V0.16.1
ACO A Catalog of Rich Clusters of Galaxies (Abell, Corwin, and Olowin, 1989)
V0.16.1
Cross-index data for Stellarium’s DSO Catalog is partially obtained from “Merged catalogue of
reflection nebulae” (Magakian, 2003) and astronomical databases SIMBAD
3
(Wenger et al., 2000)
and NED4.
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)
2The PGC and UGC catalogues are partially supported
3SIMBAD Astronomical Database — http://simbad.u-strasbg.fr/simbad/
4NASA/IPAC Extragalactic Database (NED) — https://ned.ipac.caltech.edu/
8.1 Stellarium DSO Catalog 81
9 float Minor axis size (arcmin)
10 integer Orientation angle (degrees)
11 float Redshift
12 float Error of redshift
13 float Parallax (mas)
14 float Error of parallax (mas)
15 float Non-redshift distance (Mpc for galaxies, kpc for other objects)
16 float Error of non-redsift distance (Mpc for galaxies, kpc for other objects)
17 integer NGC number (New General Catalogue)
18 integer IC number (Index Catalogue)
19 integer M number (Messier Catalog)
20 integer C number (Caldwell Catalogue)
21 integer B number (Barnard Catalogue)
22 integer SH2 number (Sharpless Catalogue)
23 integer VdB number (van den Bergh Catalogue of reflection nebulae)
24 integer
RCW number (A catalogue of H
α
-emission regions in the southern
Milky Way)
25 integer LDN number (Lynds’ Catalogue of Dark Nebulae)
26 integer LBN number (Lynds’ Catalogue of Bright Nebulae)
27 integer Cr number (Collinder Catalogue)
28 integer Mel number (Melotte Catalogue of Deep Sky Objects)
29 integer PGC number (HYPERLEDA. I. Catalog of galaxies); partial
30 integer UGC number (The Uppsala General Catalogue of Galaxies); partial
31 string
Ced identificator (Cederblad Catalog of bright diffuse Galactic nebulae)
32 integer Arp number (Atlas of Peculiar Galaxies)
33 integer VV number (The catalogue of interacting galaxies)
34 string PK identificator (Catalogue of Galactic Planetary Nebulae)
35 string
PN G identificator (The Strasbourg-ESO Catalogue of Galactic Planetary
Nebulae)
36 string SNR G identificator (A catalogue of Galactic supernova remnants)
37 string ACO identificator (A Catalog of Rich Clusters of Galaxies)
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
82 Chapter 8. Deep-Sky Objects
SNR Supernova Remnant
SNC Supernova Candidate
SNRC Supernova Remnant Candidate
BN Bipolar Nebula
EN Emission Nebula
SA Stellar Association
SC Star Cloud
CL Cluster
IR Infra-Red Object
QSO Quasar
Q? Possible Quasar
ISM Interstellar Matter
EMO Emission Object
LIN LINEAR-type Active Galaxies
BLL BL Lac Object
BLA Blazar
MOC Molecular Cloud
YSO Young Stellar Object
PN? Possible Planetary Nebula
PPN Protoplanetary Nebula
Star
∗∗ Double Star
MUL Multiple Star
SYSymbiotic Star
EMEmission-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 catalogue
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 catalogue (prefix)
5 15 %d Identificator for object in the catalog
20 60 %s Proper name of the object (translatable)
If an object has more than one record in the file
names.dat
, the last record in the file will be used
for the nebula label.
8.1.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 Digitised Sky Survey Server”
infoURL a URL pointing at a page with information about the server
8.1 Stellarium DSO Catalog 83
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 indiviual 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.
{
" i m ag eC r ed it s " : { " s ho rt " : " < au th or ␣ n ame > " ,
" in foUr l " : " htt p :// < mysit e .org > "
},
" i ma ge U rl " : " < m yP ho to . png > " ,
" w o rl dC oo r ds " : [[ [ X0 , Y0 ] , [ X1 , Y 1 ], [ X2 , Y 2 ], [ X3 , Y3 ] ]] ,
" tex ture Coor ds " : [[[ 0 ,0] ,[1 ,0] ,[1 ,1] ,[0 ,1]]] ,
" Min Resol utio n " : 0. 214 881 046 3 ,
" max Brigh tnes s " : < mag >
},
where
worldCoords
Decimal numerical values of the J2000 coordinates (RA and dec both in degrees) of
the corners of the texture. These values are usually given to 4 decimal places.
textureCoords
Where 0,0 is South Left, 1,0 the South Right, 1,1 North Right, 0,1 North Left
corners of the texture.
MinResolution UNDOCUMENTED VALUE! Sorry!
maxBrightness total object brightness, magnitude
Calculating of the coords 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.
84 Chapter 8. Deep-Sky Objects
8.1.4 Modifying outlines.dat
Each line in the file
outlines.dat
contains three “columns” of data for outline elements. The
V0.16.1
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 Nebulae Images
BARRY GERDES
8.2.1 Preparing a photo for inclusion to the textures.json file
The first step is to take a photo of the object you wish to display in Stellarium. When you have
the picture you will need to align it with the equatorial 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. Next you will need to crop the picture, setting the main feature at the centre
and making the cropped size a factor of
2n
eg. 64, 128, 256, 512, 1024 or 2048 pixels square
(or elongated like 512x1024). If this requirement is not met, your textures may not be visible, or
graphics performance may be seriously impacted. Textures larger than 2048 may only be supported
on high-end hardware. Images must be in PNG format. When cropping, make sure you leave at
least six prominent background stars.
8.2 Adding Extra Nebulae Images 85
Figure 8.1: Screen shot of nebula images displayed in Stellarium
Figure 8.2:
Stellarium Textures Generator
: A program to convert Equatorial coordinates
into decimal form and write a textures.json insert
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 gray
square. Suitable programs to do all this are The GIMP5or Photoshop if you can afford it.
When you have your image prepared you will need to plate solve it using at least 6 known GSC
stars that can be identified. That is why the cropping with plenty of stars was necessary. When
the plate is solved you will need to find the J2000 coordinates of the corners and convert them to
decimal values to form the world coordinates in the textures.json file.
The program
Stellarium Textures Generator
by Peter Vasey (Fig. 8.2) can convert the corner
coordinates of a texture found in your plate solving program into decimal values and write an insert
5free in keeping with the Stellarium spirit; available from http://www.gimp.org
86 Chapter 8. Deep-Sky Objects
Figure 8.3:
ReadDSS
: A program to write a
textures.json
insert with epoch manipula-
tion.
for the textures.json file.6
There is another program,
ReadDSS
(Fig. 8.3), written by Barry Gerdes in Qb64(gl), that will
perform the same task but allows manipulation of the epochs.7
8.2.2 Plate Solving
Suitable programs that can accept your picture and calculate its corner coordinates are hard to
find. I have only found one that suits our purpose and it is another expensive planetarium program,
TheSky X Pro
. However the older versions
TheSky 5
and
6 Pro
will also do the job if suitably
configured, although I could not solve the test program with
TheSky 6
that uses the same procedure
as TheSky 5.
These programs have a link feature that can match your photo to the selected area of the screen
and superimpose it on the display with a box around your photo provided it can match at least 6
stars from the GSC that is included with the program. When this is fitted you can read the corner
coordinates of your texture in the Status bar by selecting them with a mouse.
TheSky X
can read
these coordinates in J2000 values and uses textures in the FITS format, but the earlier programs
only read the coordinates of the current program date. To read the J2000 coordinates it is necessary
to re-start the program with the date set to 1-1-2000.
To add the picture to
TheSky 5
you need first make a mono 8 bit version of the photo and place
it on the clipboard. Run
TheSky
and centre on the object centre. Look in the
Tools
menu for the
image link and select setup . Tick show image frame to put a frame around the image.
Paste the clipboard image on the display and use the zoom and position controls to get it as
close to the size and position as possible by visually matching stars. Go to the menu again and click
on
link wizard
. If you have been successful the window will show the number of stars matched
and the option to
accept
or
continue
. Accept and you will now see all the matched stars have
overlaid the picture. You can now read off the corner coordinates from the status bar starting at the
bottom (south) left and continuing counterclockwise to the top (north) left.
8.2.3 Processing into a textures.json insert
Place your image in the
*.png
format in the
.../nebulae/default/
folder. Ensure that the name
matches the textures.json entry.
Once you have the corner coordinates of your photo you can add them to the decimal converter
program and it will write an insert
nebula.json
as a text file that you can paste directly into the
6
It is available as a freebee from
http://www.madpc.co.uk/~peterv/astroplover/equipnbits/
Stellariumtextures.zip.
7http://barry.sarcasmogerdes.com/stellarium/uploads/writejsoninsert.zip
8.2 Adding Extra Nebulae Images 87
textures.json file that is in the .../nebulae/default/ folder.
Save the
textures.json
file with the new insert and run Stellarium. Find the object in the
F3
Object selection window and slew to it. Your image should be there and with a bit of luck
it will nicely overlay the stars in Stellarium. However this only rarely happens, so a little bit of
tweaking of the JSON
worldcoords
will be needed to get a perfect match. Select equatorial mode
( or
Ctrl +M
). This will show the area with north up. Select each corner in sequence and
make small changes to the coordinates. Restart Stellarium each time and check if you have moved
into the right direction. Continue with each corner until all the stars match. With a little bit of
practice this will be done in about 10 minutes.