Transforming Stellarium landscapes from standard equirectangular-spherical into multi-image format ("old style")

In earlier versions, before the equirectangular-spherical format became standard, Stellarium was only able to load landscapes in multi-image format, which consisted of one image for the ground and several side panels for the horizon. Because of its ease in production and handling, the spherical format has become the de-facto norm for stellarium landscapes. However, many computers with their graphics subsystems cannot process the large files of high-resolution spherical landscapes in OpenGL at once and display just a black screen instead.

In such a situation the conversion of the spherical landscape into the multi-image format is the only way to go on. With the multi-image format, 16k resolutions for the horizon line are also no problem.

Again, GIMP and Hugin are to be used, i.e. the very same software that is required for creating panoramas anyway.

Preparation

First create your landscape in the equirectangular-spherical(!) format to the final touch, as if you were about to publish your landscape in this format, i.e. including the removal of all artifacts, scaling the resolution to integer powers of 2, height correction, possibly brightness correction, thorough removal of the sky and also determination of the azimuth correction angle angle_rotatez. Save the finished spherical landscape as usual in PNG format.

Producing the side panels

Now open this PNG file in GIMP. Specify how many side panels you want the horizontal 360° circle to be divided into (4 images are recommended). Now copy these side panels from the loaded image. To do this, use the Rectangular Select tool and make sure that the dimensions of the rectangle shown in the tool dialog are integer powers of 2 (e.g. 2048, 4096) and both coordinates of its upper left corner are suitable multiples of integer powers of 2 (e.g. 0, 2048, 3072) while its vertical extent has to be symmetrical to the horizon line. Save each produced rectangular side panel in PNG format to an individual file name.

Producing the ground image

In contrast to the side panels, the ground image must be in a rectilinear (= gnomonic) projection - this is not noted in any instructions that have been found on the web so far. The rectilinear projection of the ground image can be imagined as a projection onto a horizontal tangential plane on an imaginary sphere around the observer's eyes with eye level (e.g. 1.6 m) as the radius. As a result of this projection, parts of the image from an angular distance of about 30° from the vertical axis show an increasing distortion reaching extreme extents when approaching 90° (i.e. in the immediate area of ​​the mathematical horizon). One shouldn't be bothered by the distortion of the image of the base; it is exactly suitable for Stellarium to display the nadir range correctly. With the rectilinear projection, however, in principle only a field of view of less than 180°x180° can be imaged; when taking the limit towards 180°, with a given pixel resolution, even the entire half-plane or hemisphere lying below the observer collapses to a single point. In the case of rectilinear images that can be used in practice, however, the field of view must remain well below that, otherwise the final quality of the landscape in the Stellarium use will visibly suffer.

In order to obtain a ground image that is of adequate quality comparable to that of the side panels and that can be easily and correctly aligned, the Stellarium screenshot method described many times in the instructions should NOT be used, because the resolution of a screenshot affects the viewport of the screen used is limited, the nadir cannot be placed exactly in the center of the image with absolute certainty and the fitting into the already existing side image set is characterized by "try & error". Rather, a tool should be used that is predestined for working with panoramas and their various projections: Hugin!

Start a new project in Hugin and upload the PNG file of the finished spherical landscape as the only image. Set the type of lens, typically "Lens 0", to "equirectangular" and the HFOV (Horizontal Field Of View) of the lens to 360° ("Photos" tab, right-click on the entry of the loaded image, "Edit image variables...", select the "Lens" tab in the dialog menu, set "degrees of view" to 360° if necessary. All other entries must be set to 0, only "Red / Blue Multiplier" must be set to 1. In the "Fast Panorama preview" the loaded PNG image now fills the entire 360°x180° viewport.

Now click on the "Move / Drag" tab in the "Fast Panorama preview", set the pitch value to 90° and press "Apply". The nadir now moves exactly to the center of the viewport.

The required base image can now be output via the "Stitch" tab. To do this, "Rectilinear" must be selected as the projection. The size of the square field of view is measured according to the fact that the nadir dome should be minimally overlapped (by 0.1°) from the side panels (in order to avoid tiny holes due to a lack of overlap). The formula for the required field of view angle results in

FOV = 180.2° - 360°/number of side panels

The resolution of the ground image to be produced must finally be set to an integer power of 2 (e.g. 4096x4096).

Once all parameters have been set, click on the "Stitch!" Button to produce the ground image. Load this image into GIMP and export it in PNG format. Incidentally, only the content of the largest disk, which is completely contained in the base area image, is actually used by Stellarium.

If you actually use 4 side panels, ground image and side panels are practically of the same quality, providing a seamless quality experience in full screen mode. In this case, the multi-image format is similar to the cubic 6-surface projection with the difference that the top surface is missing (sky!) and the side panels must be in equirectangular (or cylindrical) instead of rectilinear projection.

Building the file package for your multiple image panorama and integrating it with Stellarium

Regardless of the format, every Stellarium landscape has its own subfolder in the <config_root>/landscapes directory ( e.g. <config_root>=/usr/share/stellarium or similar) or $ HOME/.stellarium/landscapes. Create such a subfolder for your multi-image 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 use them for your panorama project edit accordingly:

• <landscape-name>/description.de.utf8 - Description of the landscape that can be invoked from within Stellarium
• <landscape-name>/description.en.utf8 in German and in English, possibly
• <landscape-name>/description.XX.YY in other languages (XX = country code, YY = encoding format)
• <landscape-name>/landscape.ini - Config file, including the exact geo-coordinates of the location
• <landscape-name>/readme.txt - Description and installation instructions as human readable English text file
• <landscape-name>/<landscape-name>GT.png - Image file for the ground image (GT = number, e.g. 0, or your own extension)
• <landscape-name>/<landscape-name>S1.png - Image files for the side panels
• ···   Number the side panels:
• <landscape-name>/<landscape-name>Sn.png   S1 to Sn, 1 to n, 0 to n-1 or the like.

Make sure to name and save the side panels in the correct order from left to right. All image files must be in PNG format. The text files are to be created exactly as in the equirectangular-spherical case, with one exception:

landscape.ini
must contain information in the [landscape] section about the fact that the landscape is in multi-image format and how it is to be composed from the associated image files. This is done using the following assignment blocks:

type = old_style(instead of "spherical")

nbsidetex = numerical valueNumber of different side panel textures (i.e. image files)
tex0 = <landscape-name>S1.pngAssignment of file names to internal texture IDs
tex1 = ···
···

nbside = numerical valueNumber of different side panel faces (i.e. geometrical faces)
side0 = tex0:x0:y0:x1:y1Assignment of the texture IDs (and thus the image files) to the side panels
side1 = tex1:x0:y0:x1:y1with selection of a rectangular section between the bottom left
···corner x0:y0 and the top right corner x1:y1 in relative coordinates
 x0:y0:x1:y1 = 0:0:1:1 for picking the entire texture image

groundtex = <landscape-name>GT.pngTexture / image file for the ground area

calibrated = true"false" for landscapes developed under versions < 0.10.6 only
tan_mode = falsefor side panels in equirectangular instead of cylindrical projection
nb_decor_repeat = 1Repetition rate for the side panel images,
always = 1 in the case of real photo panoramas

decor_alt_angle = angleVertical extent angle of the side panels,
 = 360°/number of side panels (when they are square)
decor_angle_shift = angleAltitude angle of the side panels' lower edge,
 = -180°/number of side panels (when they are square)
decor_angle_rotatez = angleThe calculated azimuth correction angle angle_rotatez (see above)
ground_angle_shift = angleAltitude angle of the upper edge of the nadir dome,
 = 0,1° - 180°/number of side panels (when they are square)
 = FOV/2 - 90° (see above for the FOV of the ground image)
ground_angle_rotatez = angle= 180° - angle_rotatez (add 360° if the result is negative)

A list of all valid keywords with their meaning and their value assignment syntax can be found 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!