Customising Landscapes

From Stellarium Wiki
Revision as of 14:50, 3 December 2013 by Gzotti (Talk | contribs)
Jump to: navigation, search
Information is actual for version 0.13.0

It is possible to create your own landscapes for Stellarium. There are four types of landscape:

  • Polygonal Method Using a text file with azimuths/altitudes.
  • Single Fish-eye Method Using a fish-eye panorama image.
  • Single Spherical Method Using a spherical panorama image.
  • Multiple Image Method (also called “old style” landscapes) Using a series of images split from a 360° “strip” panorama image + a ground image.

Each landscape has it's own sub-directory in <user directory>/landscapes or <installation directory>/landscapes. The name of the sub-directory is called the landscape ID. The sub-directory must contain a file called landscape.ini which describes the landscape type, texture filenames and other data. Texture files for a landscape should by put in the same directory as the landscape.ini file, although if they are not found there they will be searched for in the .../textures directory, allowing shared files for common textures such as the generic fog texture.

For example, the Moon landscape that is provided with Stellarium has the following files:

.../landscapes/moon/landscape.ini
.../landscapes/moon/apollo17.png

The landscape.ini file must contain a section called [landscape], which contains the details necessary to render the landscape (which vary, depending on the type of the landscape).

There is also an optional [location] section which is used to tell Stellarium where the landscape is in the solar system. If the [location] section exists, Stellarium can automatically adjust the location and observing conditions of the observer to match the landscape.

Contents

Polygonal Line Method

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
description = Horizon line of Geneve. Demonstrates compatibility with horizon descriptions from  Cartes du Ciel.
polygonal_horizon_list = horizon_Geneve.txt
polygonal_angle_rotatez = 0
ground_color = .15,.45,.45
horizon_line_color =  .75,.45,.45

Where:

  • name is what 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 will be superseded by optional description.<lang>.utf8 files.
  • polygonal_horizon_list is the name of the horizon data file for this landscape.
  • polygonal_horizon_list_mode (optional) the two first columns in the list are numbers: azimuth and altitude or zenith distance, in either degrees or radians or gradians(gon). The value must be one of azDeg_altDeg|azDeg_zdDeg|azRad_altRad|azRad_zdRad|azGrad_altGrad|azGrad_zdGrad. Default: azDeg_altDeg
  • polygonal_angle_rotatez (optional, default=0) Angle (degrees) to adjust azimuth. This may be used to apply a (usually) small offset rotation, e.g. when you have measured the horizon in a grid-based coordinate system like UTM and have to compensate for the meridian convergence.
  • ground_color (optional, default="0,0,0", i.e., black) Color for the area below the horizon line. Each R,G,B component is a float within 0..1.
  • 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, default=-1, i.e. use preset landscape/minimal_brightness from global config.ini) Some minimum brightness to keep landscape visible.

Single Fish-eye Method

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 should be saved in PNG format with alpha transparency. Wherever the image is transparent is where 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
description = Trees in Greenlake Park, Seattle
maptex = trees_512.png
maptex_illum = trees_illum_512.png
maptex_fog = trees_fog_512.png
texturefov = 210
angle_rotatez = 17
tesselate_rows = 28
tesselate_cols = 60

Where:

  • name is what appears in the landscape tab of the configuration window.
  • type identifies the method used for this landscape. “fisheye” in this case.
  • author lists the author(s) responsible for images and composition.
  • description gives a short description visible in the selection panel. The text will be superseded by optional description.<lang>.utf8 files.
  • maptex is the name of the image file for this landscape.
  • maptex_fog (optional) is the name of the fog image file for this landscape.
  • maptex_illum (optional) is the name of the nocturnal illumination/light pollution image file for this landscape.
  • texturefov is the field of view that the image covers in degrees.
  • angle_rotatez (optional) Angle (degrees) to adjust azimuth.
  • tesselate_rows (optional, default=20) If straight edges in your landscape appear broken, try increasing.
  • tesselate_cols (optional, default=40) If straight edges in your landscape appear broken, try increasing.
  • polygonal_horizon_list (optional) is the name of the (measured) horizon data file for this landscape.
  • polygonal_horizon_list_mode (optional) the two first columns in the list are numbers: azimuth and altitude or zenith distance, in either degrees or radians or gradians(gon). The value must be one of azDeg_altDeg|azDeg_zdDeg|azRad_altRad|azRad_zdRad|azGrad_altGrad|azGrad_zdGrad. Default: azDeg_altDeg
  • polygonal_angle_rotatez (optional, default=0) Angle (degrees) to adjust azimuth. This may be used to apply a (usually) small offset rotation, e.g. when you have measured the horizon in a grid-based coordinate system like UTM and have to compensate for the meridian convergence.
  • horizon_line_color (optional, default: invisible) used to draw a polygonal horizon line.
  • minimal_brightness (optional, default=-1, i.e. use preset landscape/minimal_brightness from global config.ini) Some minimum brightness to keep landscape visible.

Single Panorama Method

This method uses a more usual type of panorama - the kind which is produced directly from software such as autostitch or Hugin (http://hugin.sourceforge.net/). The panorama file should be copied into the <config root>/landscapes/<landscape_id> directory, and a landscape.ini file created. The Moon landscape which comes with Stellarium provides a minimal example of the contents of a landscape.ini file for a spherical type landscape:

[landscape]
name = Moon
type = spherical
maptex = apollo17.png

A more elaborate example is found with the Grossmugl landscape:

[landscape]
name = Grossmugl
type = spherical
author = Guenther Wuchterl, Kuffner-Sternwarte.at; Lightscape: Georg Zotti
description = Field near Leeberg, Grossmugl (Riesentumulus), Austria - Primary Observing Spot of the Grossmugl Starlight Oasis - http://starlightoasis.org
maptex = grossmugl_leeberg_crop11.25.png
maptex_top=11.25 
maptex_fog = grossmugl_leeberg_fog_crop22.5.png
maptex_fog_top = 22.5
maptex_fog_bottom = -22.5
maptex_illum = grossmugl_leeberg_illum_crop0.png
maptex_illum_bottom = 0
angle_rotatez=-89.1
minimal_brightness = 0.0075
polygonal_horizon_list = horizon_grossmugl.txt
polygonal_angle_rotatez=0
horizon_line_color =  .75,.45,.45

Where:

  • name is what appears in the landscape tab of the configuration window.
  • type identifies the method used for this landscape. “spherical” in this case.
  • author lists the author(s) responsible for images and composition.
  • description gives a short description visible in the selection panel. The text will be superseded by optional description.<lang>.utf8 files.
  • maptex is the name of the image file for this landscape.
  • maptex_top (optional; default=90) is the altitude angle of the top edge.
  • maptex_bottom (optional; default=-90) is the altitude angle of the bottom edge. Usually you will not require this, or else there will be a hole at your feet. ;-)
  • 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 illumination/light pollution image file for this landscape.
  • maptex_illum_top (optional; default=90) is the altitude angle of the top edge, if you have light pollution only close to the horizon.
  • maptex_illum_bottom (optional; default=-90) is the altitude angle of the bottom edge.
  • angle_rotatez (optional, default=0) Angle (degrees) to adjust azimuth. If 0, the left/right edge is due east.
  • tesselate_rows (optional, default=20) If straight edges in your landscape appear broken, try increasing. This is the number of rows for the maptex. Fog and illumination textures will have a similar vertical angle.
  • tesselate_cols (optional, default=40) If straight 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 query horizon transparency (for accurate object rising/setting times)
  • polygonal_horizon_list_mode (optional) the two first columns in the list are numbers: azimuth and altitude or zenith distance, in either degrees or radians or gradians(gon). The value must be one of azDeg_altDeg|azDeg_zdDeg|azRad_altRad|azRad_zdRad|azGrad_altGrad|azGrad_zdGrad. Default: azDeg_altDeg
  • polygonal_angle_rotatez (optional, default=0) Angle (degrees) to adjust azimuth. This may be used to apply a (usually) small offset rotation, e.g. when you have measured the horizon in a grid-based coordinate system like UTM and have to compensate for the meridian convergence.
  • horizon_line_color (optional, default: invisible) used to draw a polygonal horizon line.
  • minimal_brightness (optional, default=-1, i.e. use preset landscape/minimal_brightness from global config.ini) Some minimum brightness to keep landscape visible.

Multiple Image Method

The multiple image method works by having a 360 panorama of the horizon (without wasting too much texture memory with the sky) split into a number of smaller “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 further without ending up with a single very large image file, so this is usable for either very high-resolution panoramas or for older hardware. The ground texture can be a lower resolution than the panorama images. Memory usage may be more efficient because there are no unused texture parts like the corners of the texture file in the fish-eye method. It is even possible to repeat the horizon several times (for purely decorative purpose). The side textures are indeed mapped onto curved (cylinder) walls, not flat sides as shown here.

faq_landscape.png

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. 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 the Guereins landscape:

[landscape]
name = Guereins
type = old_style
author = Fabien Chéreau
description = Guéreins is a small french village...
nbsidetex = 8
tex0 = guereins4.png
tex1 = guereins5.png
tex2 = guereins6.png
tex3 = guereins7.png
tex4 = guereins8.png
tex5 = guereins1.png
tex6 = guereins2.png
tex7 = guereins3.png
nbside = 8
side0 = tex0:0:0.005:1:1
side1 = tex1:0:0.005:1:1
side2 = tex2:0:0.005:1:1
side3 = tex3:0:0.005:1:1
side4 = tex4:0:0.005:1:1
side5 = tex5:0:0.005:1:1
side6 = tex6:0:0.005:1:1
side7 = tex7:0:0.005:1:1
groundtex = guereinsb.png
fogtex = fog.png
nb_decor_repeat = 1
decor_alt_angle = 40
decor_angle_shift = -22
decor_angle_rotatez = 0
ground_angle_shift = -22
ground_angle_rotatez = 45
fog_alt_angle = 20
fog_angle_shift = -3
draw_ground_first = 1

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 directory in PNG format.
  • nbside is the number of side textures
  • side0 ... side<nbside-1> are the descriptions of how the side textures should be arranged in the program. Each description contains five fields separated by colon characters (:). The first field is the ID of the texture (e.g. tex0), the remaining fields are the texture coordinates (x0:y0:x1:y1) used to place the texture in the scene. If you want to use all of the image, this will just be 0:0:1:1.
  • groundtex is the name of the ground texture file. (This could also be a diagram e.g. indicating the mountain peaks!)
  • ground [NO LONGER USED] is the description of the projection of the ground texture in the scene.
  • fogtex is the name of the texture file for fog in this landscape. Note that for this landscape, accurate overlay of fog and landscape is only done if calibrated=true and tan_mode=true.
  • fog [NO LONGER USED] is the description of the projection of the fog texture in the scene.
  • nb_decor_repeat is the number of times to repeat the side textures in the 360 panorama.
  • decor_alt_angle (degrees) is the vertical angular size of the textures (i.e. how high they go into the sky).
  • decor_angle_shift (degrees) vertical angular offset of the scenery textures, at which height are the side textures placed.
  • decor_angle_rotatez (degrees) angular rotation of the scenery around the vertical axis. This is handy for rotating the landscape so North is in the correct direction.
  • 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 me 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, not used in this file). New since 0.10.6: Only if true, decor_alt_angle etc. really work as documented above. The (buggy) old code was left to work with the landscapes already existing.
  • tan_mode (optional, not used in this file). If true, the panorama image is 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) works also with calibrated. A fog image created with 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 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.
  • fog_alt_angle vertical angular size of the fog texture - how fog looks.
  • fog_angle_shift vertical angular offset of the fog texture - at what height is it drawn.
  • 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) is the name of the (measured) horizon data file for this landscape. Can be used to query horizon transparency (for accurate object rising/setting times)
  • polygonal_horizon_list_mode (optional) the two first columns in the list are numbers: azimuth and altitude or zenith distance, in either degrees or radians or gradians(gon). The value must be one of azDeg_altDeg|azDeg_zdDeg|azRad_altRad|azRad_zdRad|azGrad_altGrad|azGrad_zdGrad. Default: azDeg_altDeg
  • polygonal_angle_rotatez (optional, default=0) Angle (degrees) to adjust azimuth. This may be used to apply a (usually) small offset rotation, e.g. when you have measured the horizon in a grid-based coordinate system like UTM and have to compensate for the meridian convergence.
  • horizon_line_color (optional, default: invisible) used to draw a polygonal horizon line.
  • minimal_brightness (optional, default=-1, i.e. use preset landscape/minimal_brightness from global config.ini) Some minimum brightness to keep landscape visible.


A step-by-step account of the creation of a custom landscape has been contributed by Barry Gerdes. See Appendix Creating a Personalised Landscape for Stellarium.

landscape.ini [location] section

An example location section:

[location]
planet = Earth
latitude = +48d10'9.707"
longitude = +11d36'32.508"
altitude = 83
light_pollution=3
atmospheric_extinction_coefficient=0.2
atmospheric_temperature=10
atmospheric_pressure=-1

Where:

  • planet Is the English name of the solar system body for the landscape.
  • latitude Is the latitude of site of the landscape in degrees, minutes and seconds. Positive values represent North of the equator, negative values South of the equator.
  • longitude Is the longitude of site of the landscape. Positive values represent East of the Greenwich Meridian on Earth (or equivalent on other bodies), Negative values represent Western longitude.
  • altitude Is the altitude of the site of the landscape in meters.
  • country (optional) Name of the country the location is in
  • state (optional) Name of the state the location is in
  • name (optional) Name of the location

Since 0.11, 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). If negative or absent, no change will be made.
  • atmospheric_extinction_coefficient (optional, no change if absent.) Extinction coefficient (mag/airmass) for this site.
  • atmospheric_temperature (optional, no change if absent.) Surface air temperature (Degrees Celsius). Used for refraction. . Set to -1000 to explicitly declare "no change".
  • atmospheric_pressure (optional, no change if absent.) Surface air pressure (mbar; would be 1013 for "normal" sea-level conditions). Used for refraction. Set to -2 to declare "no change", or -1 to compute from altitude.
  • display_fog (optional, -1/0/1, default=-1) You may want to preconfigure setting 0 for a landscape on the Moon. Set -1 to declare "no change".

« Advanced Use Contents Adding Nebulae Images »

Personal tools
Namespaces
Variants
Actions
in this wiki
other languages
Toolbox