How to build Stellarium landscapes from photographs of your own (4/4)
Integration of the created panorama in Stellarium
Creating folder and file structure
Each Stellarium landscape has its own subfolder in the directory <config_root>/landscapes (e.g. <config_root> = /usr/share/stellarium or similar) or $HOME/.stellarium/landscapes. Create such a subfolder for your panorama, which should be named after your panorama landscape, and create the following files there, which you can also use as templates from other landscape folders in order to then use them accordingly for your panorama project edit:
- <landscape-name>/description.de.utf8 - Description of the landscape that can be called up in the menus within Stellarium,
- <landscape-name>/description.en.utf8 in German and in English
- <landscape-name>/description.XX.YY possibly in other languages (XX = country code, YY = encoding format)
- <landscape-name>/landscape.ini - Config file, including the exact site geo-coordinates
- <landscape-name>/readme.txt - Description and installation instructions as readable text file in English
- <landscape-name>/<landscape-name>.png - the actual image file of the landscape
Copy the panorama image file you have created and exported in PNG format to the last-mentioned path and file name. Apart from this file, all other files are readable text files that can be created and edited with all common text editors:
is a text file that is free in form and content, but should at least contain standard installation instructions in English. In addition, all information about the landscape can be accommodated here that would go beyond the scope of another place (e.g. in the description files). The readme files contained in the packages that can be downloaded from this website or the example on the Stellarium website may serve as a blueprint.
is a config text file comprising the sections [landscape] and [location] and expects assignments of the type keyword = value. Here, among other things, the geographical coordinates and the elevation of the location, the azimuthal alignment of the landscape, its standard name and the file name of the panorama image file (without path) are specified. The "Type" parameter must be set to "spherical", as this setting corresponds exactly to the "Equirectangular" type of the panorama image file created with Hugin. A list of all valid keywords with their meaning and their value assignment syntax can be looked up in the official Stellarium user manual. Comments are also possible; they always start with a semicolon. Without a correctly completed landscape.ini file, Stellarium cannot recognize and integrate your new landscape!
description.XX.YY (XX = language country code, YY = HTML encoding format)
are HTML text files containing the landscape information that can be displayed in the Stellarium landscape window, structured and formatted using common HTML tags such as <h2>, <p> and <br> (the display of this information in the landscape window is automatically supplemented by location geo-data generated from the corresponding entries in the landscape.ini). The name of the landscape in language XX must be enclosed in <h2> tags at the beginning of the file and then will also appear in the landscape selection menu instead of the standard name if the program language has been set to XX in the settings window, i.e. a landscape called "København" (DK) can appear in other languages with the names "Kopenhagen" (DE), "Copenhagen" (EN) and "Köpenhamn" (SE). The information in the description files should be restricted to such an extent that reading them does not require a great deal of scrolling in the landscape window.
Azimuthal alignment of the panorama
One of the final essential tasks is the exact azimuthal alignment of the panorama. Responsible for this is the parameter angle_rotatez in the [landscape] section of the config file landscape.ini, which an appropriate angle value must be assigned to.
If the left and right edges of the panorama point precisely to the east and the center of the panorama points precisely to the west, then angle_rotatez = 0°, otherwise angle_rotatez describes the clockwise rotation angle of the left edge of the panorama compared to the east direction.
Using the already known real azimuth values of the landmarks and their pixel coordinates in the panorama image file, the correct value for angle_rotatez can now be calculated (and the elevation angle deviations can be checked again on this occasion). Again, the relevant data is logged in a table:
This example table refers to a panorama image file with a resolution of 4096x2048.
For each landmark, an individual value for angle_rotatez is calculated using one of the following two equivalent formulas (the values in the fields highlighted in red must come from the current panorama image file and must not be adopted from earlier panorama versions):
angle_rotatez = Real azimuth − 90° −
|X coordinate of landmark + 0.5|
|Total pano width in pixels|
angle_rotatez = Real azimuth + 90° − Panoramic proto-azimuth (yaw)
If the result is ≥360°, then 360° must be subtracted; if, on the other hand, a negative value results, then 360° must be added.
The values for angle_rotatez obtained in this way should ideally only scatter by ±0.2°. Now calculate the arithmetic mean of the angle_rotatez values of all landmarks and enter the result in the config file landscape.ini (in the example in the table, "angle_rotatez = 278.3836"). Your landscape is now aligned with the exact direction of the compass.
If you take this opportunity to check the elevation angle deviations of your landmarks, these deviations should also only be ±0.2°. This is the accuracy that can be expected when creating Stellarium landscapes using the method described.
Tip: You can create the folder and file structure described here at an early stage. As soon as you have the first development versions of your panorama in the Stellarium-compatible target format, you can use this structure as a test environment by copying the panorama version to be tested into the folder you have set up and calling up Stellarium with your panorama version.
Light pollution and the Bortle scale
The parameter for light pollution is already known from the work step "Optimization with regard to brightness and color saturation", which should be set to the value 2 for optimal adjustment of the landscape brightness. Viewing the created landscape on a moonless night with this setting gives a good indication of how much the brightness of the landscape image file must be reduced in order to provide a reasonably realistic nocturnal appearance.
Since light pollution is a location property, this parameter can be set in the config file landscape.ini in the section [location] can be set to a default value suitable for the conditions at the location of the created landscape by assigning a value to the keyword light_pollution, which can be activated in the Stellarium mode in the sky and display options window [F4] by switching on "light pollution data from location database".
I always set light_pollution = 2 for the landscapes I created. In order to set this parameter correctly, anyone who wants a realistic simulation of light pollution should become familiar with the underlying Bortle light pollution scale. John E. Bortle published its principles in February 2001 in an article in the specialist journal "Sky & Telescope"; its online version is available in a version from July 18, 2006. Stellarium uses this concept, and the user manual also explains the definitions of each Bortle scale level.
The data required for this is available on the lightpollution.it website of the "Istituto di Scienza e Tecnologia dell'Inquinamento Luminoso" (ISTIL) located in Thiene (VI), Italy, can be viewed in mapped form. The color coding used in the ISTIL maps can be directly converted into values of the Bortle scale according to the following scheme, demonstrated on a map section of Western and Central Europe:
One recognizes, for example, that in Germany - apart from the open North Sea and Baltic Sea - only the northeast German lowlands with a foothill extending west of Uelzen into the Lüneburg Heath have good visibility conditions with a value of 3 on the Bortle scale. Find out the Bortle value at the location of your created Stellarium landscape - the maps are also available in high resolution in TIFF format.
Publishing your Stellarium landscape
If you own all rights to the image material used, then you can publish your Stellarium landscape on the Internet and make it known to the worldwide Stellarium community. In order to make your landscape available to other Stellarium users, you need your own web space to which you can upload the file tree of your landscape that has been packed into a ZIP archive; you should also create a "thumbnail" of your landscape in the format 200x114 from a Stellarium screenshot, which gives a first visual impression of your landscape.
Packing the ZIP archive
Log in as root / administrator, switch to the file tree of your Stellarium landscape and make the root / administrator the owner of folders and files so that no information that indicates user and group names from your user administration is transferred to the ZIP archive must also be packed. Check all files again for correctness and completeness. Now switch to the folder above your landscape and execute the following command:
zip -9 <landscape-name> .zip <landscape-name> / * (Windows wildcard *. *)
Now you can transfer the completed ZIP archive to your working folder and upload it to your web space. Also create an HTML file that links to the ZIP archive with a download note.
Creating a thumbnail
Now create a Stellarium screenshot with your landscape in action for the thumbnail image. Invoke Stellarium, load your landscape, switch the Stellarium clock to pause mode and make the appropriate settings such as date, time, direction of view, with / without graticule / constellation figures, etc.
When everything is finished, switch from Stellarium full screen to window mode [F11] and invoke GIMP on your desktop. Initiate the screenshot in GIMP with [File / Create / Screenshot ...] and select the option "Take a screenshot of the entire screen" in the appearing pop-up window. Deselect the option "Include mouse pointer" (so that the mouse pointer does not appear in the screenshot) and enter 10 seconds for "Delay". When you are ready, press the snap button, reset the Stellarium window to full screen mode within the delay, bring the mouse pointer into the middle and wait until the delay has elapsed. Close Stellarium, go back to GIMP and save the produced screenshot.
For the thumbnail picture you have to copy a rectangle with an aspect ratio of 7:4 from the screenshot. To do this, select the Rectangle Select Tool, activate the "Fixed Aspect Ratio" option and enter "7:4" in the input field. Your selection rectangle now always has the desired aspect ratio of 7:4. Select a representative section, copy it with [Edit / Copy], create a new image from it with [Edit / Paste as / New Image], scale it to 200x114 pixels with [Image / Scale Image ...] and export it in PNG format named <landscape-name>_thumb.png - your thumbnail image is ready, which you can now also upload to your webspace.