Advanced Use

(Difference between revisions)
Jump to: navigation, search
(39 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{ActualVersion|0.12.4}}
 
==Files and Directories==
 
==Files and 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''. Thus it is possible for Stellarium to be installed as 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.
+
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''<ref>The installation directory was referred to as the config root directory in previous versions of this guide</ref>. Thus it is possible for Stellarium to be installed as 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.
 
In addition to the main search path, Stellarium saves some files in other locations, for example screens shots and recorded scripts.
Line 18: Line 19:
  
 
  C:\Documents and Settings\Bob Dobbs\Application Data\Stellarium\
 
  C:\Documents and Settings\Bob Dobbs\Application Data\Stellarium\
 +
 +
Thus, on a typical Windows Vista and Windows 7 systems with user “Bob Dobbs”, the user directory will be:
 +
 +
C:\Users\Bob Dobbs\AppData\Roaming\Stellarium\
  
 
Stellarium version 0.9.0 did use the <code>%APPDATA%\Stellarium</code> folder. Thus if a <code>config.ini</code> file exists in the <code>%USERPROFILE%\Stellarium\</code> directory, that will be used in preference to the <code>%APPDATA%\Stellarium\</code> directory. This is to prevent users of version 0.9.0 from losing their settings when they upgrade.
 
Stellarium version 0.9.0 did use the <code>%APPDATA%\Stellarium</code> folder. Thus if a <code>config.ini</code> file exists in the <code>%USERPROFILE%\Stellarium\</code> directory, that will be used in preference to the <code>%APPDATA%\Stellarium\</code> directory. This is to prevent users of version 0.9.0 from losing their settings when they upgrade.
  
* '''screenshot save directory''' Screenshots will be saved to the Desktop, although this can be changed with a command line option (see section [sec:commandlineoptions]).
+
* '''screenshot save directory''' Screenshots will be saved to the Desktop, although this can be changed with a command line option (see section [[Advanced_Use#Command_Line_Options|Command Line Options]]<ref>Windows Vista users who do not run Stellarium with administrator priviliges should adjust the shortcut in the start menu to specify a different directory for screenshots as the Desktop directory is not writable for normal progams. The next release of Stellarium will include a GUI option to specify the screenshot directory.</ref>).
  
 
===Mac OS X===
 
===Mac OS X===
 
* '''installation directory''' This is found inside the application bundle, <code>Stellarium.app</code>. See the [http://www.mactipsandtricks.com/articles/Wiley_HT_appBundles.lasso Inside Application Bundles] for more information.
 
* '''installation directory''' This is found inside the application bundle, <code>Stellarium.app</code>. See the [http://www.mactipsandtricks.com/articles/Wiley_HT_appBundles.lasso Inside Application Bundles] for more information.
* '''user directory''' This is the <code>Library/Preferences/Stellarium/</code> sub-directory of the users home directory.
+
* '''user directory''' This is the <code>Library/Preferences/Stellarium/</code> (or <code>~/Library/Application Support/Stellarium</code> on newest versions of Mac OS X) sub-directory of the users home directory.
 
* '''screenshot save directory''' Screenshots are saved to the users Desktop.
 
* '''screenshot save directory''' Screenshots are saved to the users Desktop.
  
Line 34: Line 39:
  
 
===Directory Structure===
 
===Directory Structure===
Within the ''installation directory'' and ''user directory'' (defined in section [sec:filesanddirectories]), files are arranged in the following sub-directories.
+
Within the ''installation directory'' and ''user directory'' (defined in section [[Advanced_Use#Files_and_Directories|Files and Directories]]), files are arranged in the following sub-directories.
 
* '''landscapes/''' contains data files and textures used for Stellarium's various landscapes. Each landscape has it's 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.
 
* '''landscapes/''' contains data files and textures used for Stellarium's various landscapes. Each landscape has it's 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.
 
* '''skycultures/''' contains constellations, common star names and constellation artwork for Stellarium's many sky cultures. Each culture has it's own sub-directory in the skycultures directory.
 
* '''skycultures/''' contains constellations, common star names and constellation artwork for Stellarium's many sky cultures. Each culture has it's own sub-directory in the skycultures directory.
Line 49: Line 54:
 
The main configuration file is read each time Stellarium starts up, 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 version 0.10.0. Some settings can only be changed by directly editing the configuration file. This section describes some of the settings a user may wish to modify in this way, and how to do it.
 
The main configuration file is read each time Stellarium starts up, 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 version 0.10.0. Some settings can only be changed by directly editing the configuration file. 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 [sec:filesanddirectories] for the location of the user directory on your operating system). The name of the configuration file is <code>config.ini</code>.
+
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 [[Advanced_Use#Files_and_Directories|Files and Directories]] for the location of the user directory on your operating system). The name of the configuration file is <code>config.ini</code><ref>It is possible to specify a different name for the main configuration file using the <code>--config-file</code> command line option. See section [[Advanced_Use#Command_Line_ Options|Command Line Options]] for details.</ref>.
  
 
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'' etc. on Linux.
 
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'' etc. on Linux.
  
The following sub-sections contain details on how to make commonly used modifications to the configuration file. A complete list of configuration file values may be found in appendix [sec:configfileref].
+
The following sub-sections contain details on how to make commonly used modifications to the configuration file. A complete list of configuration file values may be found in appendix [[Configuration file]].
  
 
==Command Line Options==
 
==Command Line Options==
 
Stellarium's behaviour can be modified by providing parameters to the program when it is run, via the command line. See table [tab:Command-line-options] for a full list.
 
Stellarium's behaviour can be modified by providing parameters to the program when it is run, via the command line. See table [tab:Command-line-options] for a full list.
{|
+
{| class="guidetable"
 
  |''Option''
 
  |''Option''
 
  |''Option Parameter''
 
  |''Option Parameter''
Line 153: Line 158:
  
 
==Scripting==
 
==Scripting==
In version 0.10.2 of Stellarium includes the beginnings of a new scripting engine. The new scripting engine is still in development - there are missing features and probably a lot of bugs.  
+
Since version 0.10.2 of Stellarium includes the beginnings of a new scripting engine. The new scripting engine is still in development - there are missing features and probably a lot of bugs.  
  
 
===Running Scripts===
 
===Running Scripts===
Line 173: Line 178:
 
Stellarium can simulate light pollution, which is controlled from the light pollution section of the ''Sky'' tab of the ''View'' window. Light pollution levels are set using an numerical value between 1 and 9 which corresponds to the ''Bortle Dark Sky Scale''.
 
Stellarium can simulate light pollution, which is controlled from the light pollution section of the ''Sky'' tab of the ''View'' window. Light pollution levels are set using an numerical value between 1 and 9 which corresponds to the ''Bortle Dark Sky Scale''.
  
{|
+
{| class="guidetable"
 
  |Level
 
  |Level
 
  |Title
 
  |Title
Line 236: Line 241:
  
 
==Customising Landscapes==
 
==Customising Landscapes==
It is possible to create your own landscapes for Stellarium. There are three types of landscape:
+
{{ChapterLink|name=Customising Landscapes|type=section}}
* '''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&deg; “strip” panorama image + a ground image.
+
 
+
Each landscape has it's own sub-directory in <code><user directory>/landscapes</code> or <code><installation directory>/landscapes</code>. The name of the sub-directory is called the ''landscape ID''. The sub-directory must contain a file called <code>landscape.ini</code> which describes the landscape type, texture filenames and other data. Texture files for a landscape should by put in the same directory as the <code>landscape.ini</code> file, although if they are not found there they will be searched for in the <code>.../textures</code> directory, allowing shared files for common textures such as the 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 <code>landscsape.ini</code> file must contain a section called <code>[landscape]</code>, which contains the details necessary to render the landscape (which vary, depending on the type of the landscape).
+
 
+
There is also an optional <code>[location]</code> section which is used to tell Stellarium where the landscape is in the solar system. If the <code>[location]</code> section exists, Stellarium can automatically adjust the location of the observer to match the landscape.
+
 
+
===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 rounded corners) 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 <code>landscape.ini</code> file for a fish-eye type landscape looks like this (this example if for the Trees landscape which comes with Stellarium):
+
[landscape]
+
name = Trees
+
type = fisheye
+
maptex = trees_512.png
+
texturefov = 210
+
 
+
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.
+
* '''maptex''' is the name of the image file for this landscape.
+
* '''texturefov''' is the field of view that the image covers in degrees.
+
 
+
===Single Panorama Method===
+
This method uses a more usual type of panorama - the kind which is produced directly from software such as ''autostitich''. The panorama file should be copied into the <code><config root>/landscapes/<landscape_id></code> directory, and a <code>landscape.ini</code> file created. The ''Moon'' landscape which comes with Stellarium provides a good example of the contents of a landscape.ini file for a spherical type landscape:
+
[landscape]
+
name = Moon
+
type = spherical
+
maptex = apollo17.png
+
 
+
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.
+
* '''maptex''' is the name of the image file for this landscape.
+
 
+
Note that the name of the section, in this case <code>[moon]</code> must be the landscape ID (i.e. the same as the name of the directory where the <code>landscape.ini</code> file exists).
+
 
+
===Multiple Image Method===
+
The multiple image method works by having a 360 panorama of the horizon 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. 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.
+
 
+
http://www.stellarium.org/wikiimg/UserManual/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 <code>landscape.ini</code> file for this landscape type is also somewhat more complicated than for other landscape types. Here is the <code>landscape.ini</code> file which describes the Guereins landscape:
+
[landscape]
+
name = Guereins
+
type = old_style
+
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
+
ground = groundtex:0:0:1:1
+
fogtex = fog.png
+
fog = fogtex:0:0:1:1
+
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.
+
* '''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 <code>.../textures/landscapes</code> 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 coordinates used to place the texture in the scene.
+
* '''groundtex''' is the name of the ground texture file.
+
* '''ground''' 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.
+
* '''fog''' 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''' is the vertical angular size of the textures (i.e. how high they go into the sky).
+
* '''decor_angle_shift''' vertical angular offset of the scenery textures, at which height are the side textures 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.
+
* '''ground_angle_shift''' vertical angular offset of the ground texture, at which height the ground texture is placed.
+
* '''ground_angle_rotatez''' 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''' 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 in front of the scenery, i.e. the side textures will overlap over the ground texture.
+
 
+
Note that the name of the section, in this case [guereins] must be the landscape ID (i.e. the same as the name of the directory where the <code>landscape.ini</code> file exists).
+
 
+
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
+
 
+
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.
+
  
 
==Adding Nebulae Images==
 
==Adding Nebulae Images==
Extended objects are those which are external to the solar system, and are not point-sources like stars. Extended objects include galaxies, planetary nebulae and star clusters. These objects may or may not have images associated with them. Stellarium comes with a catalogue of about 13,000 extended objects, with images of over 100.
+
{{ChapterLink|name=Adding Nebulae Images|type=section}}
 
+
To add a new extended object, add an entry in the <code>.../nebulae/default/ngc2000.dat</code> file with the details of the object (where ... is either the installation directory or the user directory). See section [[ Modifying ngc2000.dat]] for details of the file format.
+
 
+
If the object has a name (not just a catalogue number), you should add one or more records to the <code>.../nebulae/default/ngc2000names.dat</code> file. See section [sec:ngc2000names.dat] for details of the file format.
+
 
+
If you wish to associate a texture (image) with the object, you must also add a record to the <code>.../nebulae/default/textures.json</code> file. See section [sec:nebula_textures.fab] for details of the file format.
+
 
+
Nebula images should have dimensions which are integer powers of two, i.e. 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 ... pixels along each side. If this requirement is not met, your textures may not be visible, or graphics performance may be seriously impacted. PNG or JPG formats are both supported.
+
 
+
===Modifying ngc2000.dat===
+
Each deep sky image has one line in the ngc2000.dat file in the <code>.../nebulae/default/</code> directory (where ... is either the installation directory or the user directory). The file is a plain ASCII file, and may be edited with a normal text editor. Each line contains one record, each record consisting of the following fields:
+
 
+
{|
+
|Offset
+
|Length
+
|Type
+
|Description
+
|-
+
|0
+
|1
+
|%c
+
|Describes the catalogue type. I = Index Catalogue, anything else means NGC
+
|-
+
|1
+
|6
+
|%d
+
|Catalogue number
+
|-
+
|8
+
|3
+
|%3s
+
|Sets nType.
+
 
+
Possible values:
+
 
+
'Gx ' NEB_OC
+
 
+
'OC ' NEB_GC
+
 
+
'Gb ' NEB_N
+
 
+
'Nb ' NEB_PN
+
 
+
'Pl '
+
 
+
'  '
+
 
+
' - '
+
 
+
' * '
+
 
+
'D* '
+
 
+
'***'
+
 
+
'C+N' NEB_CN
+
 
+
' ? ' NEB_UNKNOWN
+
 
+
|-
+
|12
+
|9
+
|%d %f
+
|Right ascension hour; right ascension minute
+
|-
+
|21
+
|1
+
|%c
+
|Declination degree sign
+
|-
+
|22
+
|7
+
|%d %f
+
|Declination degree; Declination minute
+
|-
+
|40
+
|7
+
|%f
+
|Angular size
+
|-
+
|47
+
|6
+
|%f
+
|Magnitude
+
|}
+
 
+
===Modifying ngc2000names.dat===
+
Each line in the <code>ngc2000names.dat</code> file contains one record. A record relates an extended object catalogue number (from ngc2000.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
+
|35
+
|%35s
+
|Name (Note that messier numbers should be “M” then three spaces, then the number).
+
|-
+
|37
+
|1
+
|%c
+
|
+
|-
+
|38
+
|
+
|%d
+
|Catalogue number
+
|-
+
|44
+
|30?
+
|%s
+
|?
+
|}
+
 
+
If an object has more than one record in the <code>ngc2000names.dat</code> file, the last record in the file will be used for the nebula label.
+
 
+
===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 . 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
+
* 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.
+
Line 1 “imageCredits”: {“short” : “<name of source>” : “infoUrl”: http://<web address>},
+
Line 2 “imageUrl” : “<location and name of image>”,
+
Line 3 “worldCoords” : < decimal numerical values of the J2000 coordinates of the corners of the texture > These values displayed to 4 decimal places in the format of the texture coordinates
+
Line 4 “textureCoords” : [[[ 0,0],[1,0],[1,1],[0,1]]], Where 0,0 is South Left , 1,0 the South Right , 1,1 North Right , 0,1 North Left corners of texture Format = RA in degrees, Dec in degrees
+
Line 5 “MinResolution” : <a numerical value that displays the texture>,
+
Line 6 “maxBrightness” : < a numerical vale representing the absolute brightness for the display>
+
 
+
Calculating of the coords of the corners of the images 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 displays can be sectioned into a mosaic of smaller textures for a more accurate display
+
 
+
===Editing Image Files===
+
Images files should be copied to the <code>.../nebulae/<set>/</code> directory (where <code><set></code> is the name of the nebula texture set to be modified which is usually default. Images should be in PNG or JPEG format. Images should have an aspect ratio of 1 (i.e. it should be square), and should have a width & height of 2<sup>''n''</sup> pixels, where ''n'' is a positive integer (i.e. 2, 4, 8, 16, 32, 64, 128, 256, 512, and so on).
+
 
+
Black is interpretted as being 100% transparent. Ensure that the background of the image is totally black (i.e. has RGB values 0, 0, 0), and not just nearly black since this can cause an ugly square around the object.
+
 
+
There is a lot of software which may be used to create / modify PNG and JPEG images. The author recommends the GNU Image Manipulation Program ([http://www.gimp.org GIMP]), since it is more than up to the job, and is free software in the same spirit as Stellarium itself.
+
  
 
==Sky Cultures==
 
==Sky Cultures==
 
Sky cultures are defined in the <code>skycultures/</code> directory which may be found in the installation directory and/or user directory. Inside is one sub-directory per sky culture, each of these containing settings and image files as described in table bottom. Section names should be unique within the <code>ssystem.ini</code> file.
 
Sky cultures are defined in the <code>skycultures/</code> directory which may be found in the installation directory and/or user directory. Inside is one sub-directory per sky culture, each of these containing settings and image files as described in table bottom. Section names should be unique within the <code>ssystem.ini</code> file.
  
{|
+
{| class="guidetable"
 
  |File
 
  |File
 
  |Purpose
 
  |Purpose
Line 546: Line 262:
 
# Star 1 x position in image (pixel)
 
# Star 1 x position in image (pixel)
 
# Star 1 y position in image (pixel)
 
# Star 1 y position in image (pixel)
# Star 1 HP catalogue number
+
# Star 1 HIP catalogue number
 
# Star 2 x position in image (pixel)
 
# Star 2 x position in image (pixel)
 
# Star 2 y position in image (pixel)
 
# Star 2 y position in image (pixel)
# Star 2 HP catalogue number
+
# Star 2 HIP catalogue number
 
# Star 3 x position in image (pixel)
 
# Star 3 x position in image (pixel)
 
# Star 3 y position in image (pixel)
 
# Star 3 y position in image (pixel)
# Star 3 HP catalogue number
+
# Star 3 HIP catalogue number
 
  |-
 
  |-
 
  |constellationship.fab
 
  |constellationship.fab
Line 558: Line 274:
 
# Constellation abbreviation
 
# Constellation abbreviation
 
# Number of lines
 
# Number of lines
After this are pairs of HP catalogue numbers which the lines are drawn between.
+
After this are pairs of HIP catalogue numbers which the lines are drawn between.
 +
|-
 +
|constellations_boundaries.dat
 +
|This file provides data to drawing the boundaries of the constellations.
 
  |-
 
  |-
 
  |info.ini
 
  |info.ini
  |Contains the name for this sky culture as it will appear in the configuration dialog's language tabwindow!configuration!language tab.
+
  |Contains the name for this sky culture as it will appear in the configuration dialog's language [[Configuration#The_Configuration_Window|Configuration -> Language]].
 
  |-
 
  |-
 
  |star_names.fab
 
  |star_names.fab
  |Contains a list of HP catalogue numbers and common names for those stars.
+
  |Contains a list of HIP catalogue numbers and common names for those stars.
 
  |}
 
  |}
  
Line 572: Line 291:
 
The file format follows .ini file conventions. Each section in the file represents the data for one planetary body. Each section has values as described in table.
 
The file format follows .ini file conventions. Each section in the file represents the data for one planetary body. Each section has values as described in table.
  
{|
+
{| class="guidetable"
 
  |Name
 
  |Name
 
  |Format
 
  |Format
Line 624: Line 343:
 
  |float
 
  |float
 
  |Specify the albedo of the body
 
  |Specify the albedo of the body
 +
|-
 +
|absolute_magnitude
 +
|float
 +
|Absolute magnitude
 +
|-
 +
|atmosphere
 +
|boolean
 +
|Has body atmosphere?
 
  |-
 
  |-
 
  |rot_periode
 
  |rot_periode
Line 689: Line 416:
 
  |Object parameter used in comet_orbit calculations
 
  |Object parameter used in comet_orbit calculations
 
  |-  
 
  |-  
  |orbit_ArgOf Pericenter
+
  |orbit_ArgOfPericenter
 
  |float
 
  |float
 
  |Object parameter used in comet_orbit calculations
 
  |Object parameter used in comet_orbit calculations
 +
|-
 +
|orbit_Epoch
 +
|float
 +
|JD epoch for orbit elements
 +
|-
 +
|orbit_visualization_period
 +
|float
 +
|Orbital period (in Earth's days) of body for visualization their orbits
 +
|-
 +
|landscape
 +
|string
 +
|default landscape for this body
 +
|-
 +
|minor_planet_number
 +
|integer
 +
|MPC number of minor planet (used only for asteroids)
 +
|-
 +
|rings
 +
|boolean
 +
|Has body rings?
 +
|-
 +
|rings_outer_size
 +
|float
 +
|Outer size of rings
 +
|-
 +
|rings_inner_size
 +
|float
 +
|Inner size of rings
 +
|-
 +
|tex_ring
 +
|string
 +
|File name of a PNG or JPEG texture file to be used as the “rings” image
 +
|-
 +
|type
 +
|string
 +
|Type of body (using for asteroids and comets)
 
  |}
 
  |}
 
Orbital calculations for the major planets is handled by sophisticated custom algorithms, and are accurate for a comparatively long time. For asteroids and comets the calculations are not as accurate, and the data in <code>ssystem.ini</code> for these bodies should be updated periodically (every year or two).
 
Orbital calculations for the major planets is handled by sophisticated custom algorithms, and are accurate for a comparatively long time. For asteroids and comets the calculations are not as accurate, and the data in <code>ssystem.ini</code> for these bodies should be updated periodically (every year or two).
Line 721: Line 484:
  
 
==Other Configuration Files==
 
==Other Configuration Files==
In addition to the files discussed in the previous sections, Stellarium uses various other data files. Many of these files may be edited easily to change Stellarium's behaviour.  
+
In addition to the files discussed in the previous sections, Stellarium uses various other data files. Many of these files may be edited easily to change Stellarium's behaviour<ref>Not all files in the <code>.../data</code> directory are listed here - only the ones which the advanced user is most likely to want to modify.</ref>.  
  
{|
+
{| class="guidetable"
 
  |File
 
  |File
 
  |Purpose
 
  |Purpose
Line 745: Line 508:
 
  |.../data/user_locations.txt
 
  |.../data/user_locations.txt
 
  |The same format as base_locations.txt. This file is added to when auser defines a new location, and is usually found in the user data directory area, rather than the installation area.
 
  |The same format as base_locations.txt. This file is added to when auser defines a new location, and is usually found in the user data directory area, rather than the installation area.
|-
 
|.../data/constellations_boundaries.dat
 
|This file provides data necessary for Stellarium to draw the boundaries of he constellations.
 
 
  |-
 
  |-
 
  |.../stars/*/name.fab
 
  |.../stars/*/name.fab
  |This file defines the Flamsteed designation for a star (see section [sec:flamsteeddesignation]). Each line of the file contains one record of two fields, separated by the pipe character (|). The first field is the Hipparcos catalogue number of the star, the second is the Flamsteed designation, e.g:
+
  |This file defines the Flamsteed designation for a star (see section [[Astronomical_Phenomena#Flamsteed_Designation|Flamsteed Designation]]). Each line of the file contains one record of two fields, separated by the pipe character (&#x007C;). The first field is the Hipparcos catalogue number of the star, the second is the Flamsteed designation, e.g:
  
 
<code>72370|&alpha;_Aps</code>
 
<code>72370|&alpha;_Aps</code>
Line 759: Line 519:
  
 
==Taking Screenshots==
 
==Taking Screenshots==
You can save what is on the screen to a file by pressing CTRL-s. Screenshots are taken in .bmp format, and have filenames something like this: stellarium-000.bmp, stellariuim-001.bmp (the number increments to prevent over-writing existing files).
+
You can save what is on the screen to a file by pressing '''Control-S'''. Screenshots are taken in ''.png'' format, and have filenames something like this: ''stellarium-000.png'', ''stellariuim-001.png'' (the number increments to prevent over-writing existing files).
  
Stellarium creates screenshots in different directories depending in your system type, see section [sec:filesanddirectories].
+
Stellarium creates screenshots in different directories depending in your system type, see section [[Advanced_Use#Files_and_Directories|Files and Directories]].
  
==Telescope Control==
+
== Plugins ==
Stellarium has a simple control mechanism for motorised telescope mounts. The user selects an object (i.e. by clicking on something - a planet, a star etc.) and presses the ''telescope go-to'' key (see section [sub:telescopekeyboardcontrols]) and the telescope will be guided to the object.
+
Stellarium has been greatly expanded since version 0.10.2 with compiled static plug ins. By this method many add-ons for specific use can be added without modifying the program core. There are many plug ins now available that can be loaded at start up and be available within the program. as each plug in is loaded an icon is placed in the bottom menu bar. At present Version 0.12.3 there are 17 plug ins bundled with the release version of Stellarium. These include:
 +
 
 +
Telescope Control. Stellarium has a simple control mechanism for motorised telescope mounts. The user selects an object (i.e. by clicking on something - a planet, a star etc.) and presses the ''telescope go-to'' key (see section []) and the telescope will be guided to the object.
  
 
Multiple telescopes may be controlled simultaneously.
 
Multiple telescopes may be controlled simultaneously.
  
 
http://www.stellarium.org/wikiimg/UserManual/telescope_control.png
 
http://www.stellarium.org/wikiimg/UserManual/telescope_control.png
 +
 +
The control interface uses the Meade or the Celestron protocol and most telescopes use either one or the other so many different brands of telescopes can be controlled. There is a third party Telescope control system going under the name of ASCOM. They provide an interface to stellarium and then translate the control into many other forms
 +
 +
Multiple telescopes may be controlled simultaneously.
  
 
''WARNING: Stellarium will not prevent your telescope from being pointed at the Sun. It is up to you to ensure proper filtering and safety measures are applied!''
 
''WARNING: Stellarium will not prevent your telescope from being pointed at the Sun. It is up to you to ensure proper filtering and safety measures are applied!''
  
{{Template:UserManualNavigation|1=Configuration|3=Stellarium User Guide|2=Stellarium Reference}}
+
AngleMeasure. Measures the angle and distance between objects on the visible screen
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/angle_measure.png
 +
 
 +
When this plug in is active you can place the cursor on any object and drag the mouse to another object. The program will calculate the angular distance between the objects
 +
 
 +
CompassMarks. places a scale of degrees around the horizon
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/CompassMark.png
 +
 
 +
When active this places a 360 degree scale around the horizon.
 +
 
 +
Exoplanets. A list of stars with planets around that can be displayed from an editable data base - exoplanets.json
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/Exoplanets.png
 +
 
 +
When active this plug in reads the associated exoplanets.json file and places http://barry.sarcasmogerdes.com/stellarium/Exoplanet.png on the item with a name.
 +
 
 +
Oculars. This places a window on the screen that corresponds to the view through a telescope or on a camera. It reads from an editable data base.
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/Oculars.png
 +
 
 +
When this plug in is active a window will appear around the selected object depicting what would be seen by the viewing object. On the top right hand side of the screen a menu will appear that can be used to select the viewing device eg. Camera, Eyepiece. This menu is filled with items from the ocular.ini file in the modules\oculars folder. his file can be edited from the Plugins menu screen or by a text editor.
 +
 
 +
Pulsars. A list of Pulsars that can be displayed from an editable data base.
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/pulsars.png
 +
 
 +
When active this plug in reads the associated pulsars.json file and places http://barry.sarcasmogerdes.com/stellarium/pulsar.png in blue around the pulsar with a name
 +
 
 +
Quasars. A list of Quasars that can be displayed from an editable data base
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/Quasars.png
 +
 
 +
When active this plug in reads the associated pulsars.json file and places http://barry.sarcasmogerdes.com/stellarium/Quasar.png in red around the pulsar with a name
 +
 
 +
RendererStatistics.A list of statistics from the operation of the program
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/rendererstats.png
 +
 
 +
When activated displays statistics about the renderer
 +
 
 +
Satellites. This displays a number of earth orbiting satellies. automatically updated every 72 hours from the internet.
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/satellites.png
 +
 
 +
This plug in reads information on a selected range of near earth orbiting satellites from a file satellites.json that is updated every 72 hours and displays
 +
http://barry.sarcasmogerdes.com/stellarium/hint.png with a name. The file is editable with a text editor to change the colour and visibility when required.
 +
 
 +
Observability. This shows times and availabilty of objects you may wish to see
 +
 
 +
SolarSystemEditor. This can be used to find and include orbital data on Solar System objects and added to the ssystem.ini file
 +
 
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/Observability_Solared.png
 +
 
 +
SuperNova. A list of Super Novas that can be displayed from an editable data base.
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/sn1604wiki.png
 +
 
 +
When Historical SuperNova is active follow the instructions from the plugin screen to display the supernova. This may require resetting the date to the listed date.
 +
 
 +
 
 +
TextUserInterface (TUI). A way to change many parameters from the Stellarium Program
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/TUI-entry.png
 +
 
 +
The text user interface is basically for the use in planetariums. When the plug in is loaded it can be opened and closed with “m”. This will pace the entry point on the lower left of the screen which may be obscured by the landscape. To use it you scroll through the options with the arrow keys and press enter when the desired function is listed.
 +
 
 +
TimeZoneConfiguration. Used to manipulate the time zone of the display.
 +
 
 +
http://barry.sarcasmogerdes.com/stellarium/Timezone.png
 +
 
 +
==References==
 +
<references/>
 +
 
 +
{{Template:LRCNavigation|Configuration|Stellarium User Guide|Built-in Plugins}}
  
 
[[Category:Stellarium User Guide]]
 
[[Category:Stellarium User Guide]]

Revision as of 16:50, 4 October 2013

Information is actual for version 0.12.4

Contents

Files and 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 as 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.

Windows

  • installation directory By default this is C:\Program Files\Stellarium\, although this can be adjusted during the installation process.
  • user directory This is the Stellarium sub-folder in the Application Data folder for the user account which is used to run Stellarium. Depending on the version of Windows and its configuration, this could be any of the following (each of these is tried, if it fails, the next in the list if tried).
%APPDATA%\Stellarium\
%USERPROFILE%\Stellarium\
%HOMEDRIVE%\%HOMEPATH%\Stellarium\
%HOME%\Stellarium\
Stellarium's installation directory

Thus, on a typical Windows XP system with user “Bob Dobbs”, the user directory will be:

C:\Documents and Settings\Bob Dobbs\Application Data\Stellarium\

Thus, on a typical Windows Vista and Windows 7 systems with user “Bob Dobbs”, the user directory will be:

C:\Users\Bob Dobbs\AppData\Roaming\Stellarium\

Stellarium version 0.9.0 did use the %APPDATA%\Stellarium folder. Thus if a config.ini file exists in the %USERPROFILE%\Stellarium\ directory, that will be used in preference to the %APPDATA%\Stellarium\ directory. This is to prevent users of version 0.9.0 from losing their settings when they upgrade.

  • screenshot save directory Screenshots will be saved to the Desktop, although this can be changed with a command line option (see section Command Line Options[2]).

Mac OS X

  • installation directory This is found inside the application bundle, Stellarium.app. See the Inside Application Bundles for more information.
  • user directory This is the Library/Preferences/Stellarium/ (or ~/Library/Application Support/Stellarium on newest versions of Mac OS X) sub-directory of the users home directory.
  • screenshot save directory Screenshots are saved to the users Desktop.

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 users home directory, i.e. ~/.stellarium/.
  • screenshot save directory Screenshots are saved to the users home directory.

Directory Structure

Within the installation directory and user directory (defined in section Files and Directories), files are arranged in the following sub-directories.

  • landscapes/ contains data files and textures used for Stellarium's various landscapes. Each landscape has it's 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.
  • skycultures/ contains constellations, common star names and constellation artwork for Stellarium's many sky cultures. Each culture has it's own sub-directory in the skycultures directory.
  • nebulae/ contains data and image files for nebula textures. In future Stellarium will be able to support multiple sets of nebula images and switch between them at runtime. This feature is not implemented for version 0.9.1, although the directory structure is in place - each set of nebula textures has it's own sub-directory in the nebulae directory.
  • stars/ contains Stellarium's star catalogues. In future Stellarium will be able to support multiple star catalogues and switch between them at runtime. This feature is not implemented for version 0.10.0, although the directory structure is in place - each star catalogue has it's 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.

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 also possible to add new landscapes 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.

The Main Configuration File

The main configuration file is read each time Stellarium starts up, 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 version 0.10.0. Some settings can only be changed by directly editing the configuration file. 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 Files and Directories for the location of the user directory on your operating system). The name of the configuration file is config.ini[3].

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 etc. on Linux.

The following sub-sections contain details on how to make commonly used modifications to the configuration file. A complete list of configuration file values may be found in appendix Configuration file.

Command Line Options

Stellarium's behaviour can be modified by providing parameters to the program when it is run, via the command line. See table [tab:Command-line-options] 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 information, and exit.
--config-file or -c config file name Specify the configuration file name. The default 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] If this option is specified Stellarium will start with the default configuration. Note: The old configuration file will be overwritten.
--user-dir path Specify the user data directory.
--screenshot-dir path Specify the directory to which screenshots will be saved.
--full-screen yes or no Over-rides the full screen setting in the config file.
--home-planet planet Specify observer planet (English name).
--altitude altitude Specify observer altitude in meters.
--longitude longitude Specify latitude, e.g. +53d58'16.65"
--latitude latitude Specify longitude, e.g. -1d4'27.48"
--list-landscapes [none] Print a list of available landscape IDs.
--landscape landscape ID Start using landscape whose ID matches the passed parameter (dir name for 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.
--fov angle The initial field of view in degrees.
--projection-type ptype The initial projection type (e.g. perspective).

Examples

  • To start Stellarium using the configuration file, configuration_one.ini situated in the user directory (use either of these):
stellarium --config-file=configuration_one.ini
stellarium -c configuration_one.ini
  • To list the available landscapes, and then to start using the landscape with the ID, “ocean”
stellarium --list-landscapes
stellarium --landscape=ocean

Getting Extra Star Data

Stellarium is packaged with over 600 thousand stars in the normal program download, but much larger star catalogues may be downloaded using the tool which is in the Tools tab of the Configuration dialog.

Scripting

Since version 0.10.2 of Stellarium includes the beginnings of a new scripting engine. The new scripting engine is still in development - there are missing features and probably a lot of bugs.

Running Scripts

To run a script, open the Configuration dialog and go to the Scripts tab. A list of available scripts will be displayed in the list box on the left side. When a script name is selected by clicking on it, details about that script will be shown in the panel on the right side.

To run the selected script, click the run script button (looks like a play button found on a CD or DVD player).

Installing Scripts

To install a script, copy the script and any related files to <User Data Directory>/scripts/

Writing Scripts

Until the new script engine complete, documentation will not be added to the user guide. In the mean time the following resources may be helpful:

  • API Documentation. Scroll down to see the scripting overview with links to the scripting core object member functions.
  • The scripts in the Subversion repository. Many of these do not get installed because they are not so useful proof-of-concept things, but there are quite a few in there which would be helpful for someone trying to learn about the new scripting engine.
  • The stellarium-pubdevel mailing list.

Visual Effects

Light Pollution

Stellarium can simulate light pollution, which is controlled from the light pollution section of the Sky tab of the View window. Light pollution levels are set using an numerical value between 1 and 9 which corresponds to the Bortle Dark Sky Scale.

Level Title Colour Limiting magnitude (eye) Description
1 Excellent dark sky site black 7.6 – 8.0 Zodiacal light, gegenschein, zodiacal band visible; M33 direct vision naked-eye object; Scorpius and Sagittarius regions of the Milky Way cast obvious shadows on the ground; Airglow is readily visible; Jupiter and Venus affect dark adaptation; surroundings basically invisible.
2 Typical truly dark site grey 7.1 – 7.5 Airglow weakly visible near horizon; M33 easily seen with naked eye; highly structured Summer Milky Way; distinctly yellowish zodiacal light bright enough to cast shadows at dusk and dawn; clouds only visible as dark holes; surroundings still only barely visible silhouetted against the sky; many Messier globular clusters still distinct naked-eye objects.
3 Rural sky blue 6.6 – 7.0 Some light pollution evident at the horizon; clouds illuminated near horizon, dark overhead; Milky Way still appears complex; M15, M4, M5, M22 distinct naked-eye objects; M33 easily visible with averted vision; zodiacal light striking in spring and autumn, color still visible; nearer surroundings vaguely visible.
4 Rural/suburban transition green/yellow 6.1 – 6.5 Light pollution domes visible in various directions over the horizon; zodiacal light is still visible, but not even halfway extending to the zenith at dusk or dawn; Milky Way above the horizon still impressive, but lacks most of the finer details; M33 a difficult averted vision object, only visible when higher than 55°; clouds illuminated in the directions of the light sources, but still dark overhead; surroundings clearly visible, even at a distance.
5 Suburban sky orange 5.6 – 6.0 Only hints of zodiacal light are seen on the best nights in autumn and spring; Milky Way is very weak or invisible near the horizon and looks washed out overhead; light sources visible in most, if not all, directions; clouds are noticeably brighter than the sky.
6 Bright suburban sky red 5.1 – 5.5 Zodiacal light is invisible; Milky Way only visible near the zenith; sky within 35° from the horizon glows grayish white; clouds anywhere in the sky appear fairly bright; surroundings easily visible; M33 is impossible to see without at least binoculars, M31 is modestly apparent to the unaided eye.
7 Suburban/urban transition red 5.0 at best Entire sky has a grayish-white hue; strong light sources evident in all directions; Milky Way invisible; M31 and M44 may be glimpsed with the naked eye, but are very indistinct; clouds are brightly lit; even in moderate-sized telescopes the brightest Messier objects are only ghosts of their true selves.
8 City sky white 4.5 at best Sky glows white or orange — you can easily read; M31 and M44 are barely glimpsed by an experienced observer on good nights; even with telescope, only bright Messier objects can be detected; stars forming familiar constellation patterns may be weak or completely invisible.
9 Inner City sky white 4.0 at best Sky is brilliantly lit with many stars forming constellations invisible and many weaker constellations invisible; aside from Pleiades, no Messier object is visible to the naked eye; only objects to provide fairly pleasant views are the Moon, the Planets and a few of the brightest star clusters.

Customising Landscapes

Adding Nebulae Images

Sky Cultures

Sky cultures are defined in the skycultures/ directory which may be found in the installation directory and/or user directory. Inside is one sub-directory per sky culture, each of these containing settings and image files as described in table bottom. Section names should be unique within the ssystem.ini file.

File Purpose
constellation_names.eng.fab This file contains a list of names for each constellation (from the three latter abbreviation of the constellation).
constellationsart.fab This file contains the details of pictorial representations of the constellations. fields are:
  1. Constellation abbreviation
  2. image filename. This will be appended to .../skycultures/<culturename>/. Should include the .png extension. Note - this is case sensitive.
  3. Star 1 x position in image (pixel)
  4. Star 1 y position in image (pixel)
  5. Star 1 HIP catalogue number
  6. Star 2 x position in image (pixel)
  7. Star 2 y position in image (pixel)
  8. Star 2 HIP catalogue number
  9. Star 3 x position in image (pixel)
  10. Star 3 y position in image (pixel)
  11. Star 3 HIP catalogue number
constellationship.fab Describes the lines for the constellations. The fields are:
  1. Constellation abbreviation
  2. Number of lines

After this are pairs of HIP catalogue numbers which the lines are drawn between.

constellations_boundaries.dat This file provides data to drawing the boundaries of the constellations.
info.ini Contains the name for this sky culture as it will appear in the configuration dialog's language Configuration -> Language.
star_names.fab Contains a list of HIP catalogue numbers and common names for those stars.

Adding Planetary Bodies

Planetary bodies include planets, dwarf planets, moons, comets and asteroids. The orbits and physical characteristics of these bodies are described in the .../data/ssystem.ini file.

The file format follows .ini file conventions. Each section in the file represents the data for one planetary body. Each section has values as described in table.

Name Format Description
name string English name of body, case-sensitive
parent string English name of parent body (the body which this body orbits, e.g. in the case of our Moon, the parent body is Earth)
radius float Radius of body in kilometers
halo boolean If true, the body will have a halo displayed round it when it is bright enough
color r,g,b Colour of object (when rendered as a point). Each of r,g,b is a floating point number between 0 and 1.
tex_map string File name of a PNG or JPEG texture file to be applied to the object. Texture file is searched for in the .../textures directory
tex_halo string File name of a PNG or JPEG texture file to be used as the halo image if the halo option is set to true
tex_big_halo string File name of a PNG or JPEG texture file to be used as the “big halo” image
big_halo_size float The angular size of the big halo texture. Typical values range between 10 and 200.
coord_func string Select the method of calculating the orbit. Possible values are: ell_orbit, comet_orbit, <planet>_special (specific calculations for major bodies).
lighting boolean Turn on or off lighting effects
albedo float Specify the albedo of the body
absolute_magnitude float Absolute magnitude
atmosphere boolean Has body atmosphere?
rot_periode float Specify the rotational period of the body in hours
rot_obliquity float Angle between rotational axis and perpendicular to orbital plane in degrees
rot_equator_ascending_node float Rotational parameter
sidereal_period float Rotational period in days
orbit_Period float Time for one full orbit in days
orbit_SemiMajorAxis float Keplarian orbital element
orbit_Eccentricity float Keplarian orbital element
orbit_Inclination float Keplarian orbital element
orbit_AscendingNode float Keplarian orbital element
orbit_LongOfPericenter float Orbital element used in ell_orbit calculations
orbit_MeanLongitude float Orbital element used in ell_orbit calculations
ascending float Orbital element used in ell_orbit calculations
hidden boolean Display planet as seen from other bodies, or not
orbit_TimeAtPericenter float Object parameter used in comet_orbit calculations
orbit_PericenterDistance float Object parameter used in comet_orbit calculations
orbit_MeanAnomoly float Object parameter used in comet_orbit calculations
orbit_ArgOfPericenter float Object parameter used in comet_orbit calculations
orbit_Epoch float JD epoch for orbit elements
orbit_visualization_period float Orbital period (in Earth's days) of body for visualization their orbits
landscape string default landscape for this body
minor_planet_number integer MPC number of minor planet (used only for asteroids)
rings boolean Has body rings?
rings_outer_size float Outer size of rings
rings_inner_size float Inner size of rings
tex_ring string File name of a PNG or JPEG texture file to be used as the “rings” image
type string Type of body (using for asteroids and comets)

Orbital calculations for the major planets is handled by sophisticated custom algorithms, and are accurate for a comparatively long time. For asteroids and comets the calculations are not as accurate, and the data in ssystem.ini for these bodies should be updated periodically (every year or two).

At present this must be done manually by editing the ssystem.ini file.

An example entry might look like this:

[ceres]
name = Ceres
parent = Sun
radius = 470
oblateness = 0.0
albedo = 0.113
halo = true
color = 1.0,1.0,1.0
tex_halo = star16x16.png
coord_func = comet_orbit
#orbit_TimeAtPericenter = 2453194.01564059
#orbit_PericenterDistance = 2.54413510097202
orbit_Epoch = 2453800.5
orbit_MeanAnomaly = 129.98342
orbit_SemiMajorAxis = 2.7653949
orbit_Eccentricity = 0.0800102
orbit_ArgOfPericenter = 73.23162
orbit_AscendingNode = 80.40970
orbit_Inclination = 10.58687
lighting = true
sidereal_period = 1680.15

Other Configuration Files

In addition to the files discussed in the previous sections, Stellarium uses various other data files. Many of these files may be edited easily to change Stellarium's behaviour[4].

File Purpose
.../data/base_locations.txt Each line is one record which describes a location which will appear on the map in the location dialogwindow!location.

A \# character at the beginning of the record indicates that the record is a comment, and will be ignored by Stellarium. Each record is TAB separated with the following fields:

  1. Location name: province/state
  2. Country: ISO Code/Full English Name
  3. Type code: (C/B=Capital, R=Regional capital, N=Normal city, O=Observatory, L=Lander
  4. Population: in thousands
  5. Latitude: decimal degrees N/S
  6. Longitude: decimal degrees E/W
  7. Altitude: in meters
  8. Light pollution level: 0-9 Bortle scale value
  9. Timezone: emtpy means automatic
  10. Planet: empty means Earth
  11. Landscape ID: the ID for a landscape to be used with thiis location, or empty means “use default”.
.../data/user_locations.txt The same format as base_locations.txt. This file is added to when auser defines a new location, and is usually found in the user data directory area, rather than the installation area.
.../stars/*/name.fab This file defines the Flamsteed designation for a star (see section Flamsteed Designation). Each line of the file contains one record of two fields, separated by the pipe character (|). The first field is the Hipparcos catalogue number of the star, the second is the Flamsteed designation, e.g:

72370|α_Aps

.../data/zone.tab Time zone information.

Taking Screenshots

You can save what is on the screen to a file by pressing Control-S. Screenshots are taken in .png format, and have filenames something like this: stellarium-000.png, stellariuim-001.png (the number increments to prevent over-writing existing files).

Stellarium creates screenshots in different directories depending in your system type, see section Files and Directories.

Plugins

Stellarium has been greatly expanded since version 0.10.2 with compiled static plug ins. By this method many add-ons for specific use can be added without modifying the program core. There are many plug ins now available that can be loaded at start up and be available within the program. as each plug in is loaded an icon is placed in the bottom menu bar. At present Version 0.12.3 there are 17 plug ins bundled with the release version of Stellarium. These include:

Telescope Control. Stellarium has a simple control mechanism for motorised telescope mounts. The user selects an object (i.e. by clicking on something - a planet, a star etc.) and presses the telescope go-to key (see section []) and the telescope will be guided to the object.

Multiple telescopes may be controlled simultaneously.

telescope_control.png

The control interface uses the Meade or the Celestron protocol and most telescopes use either one or the other so many different brands of telescopes can be controlled. There is a third party Telescope control system going under the name of ASCOM. They provide an interface to stellarium and then translate the control into many other forms

Multiple telescopes may be controlled simultaneously.

WARNING: Stellarium will not prevent your telescope from being pointed at the Sun. It is up to you to ensure proper filtering and safety measures are applied!

AngleMeasure. Measures the angle and distance between objects on the visible screen

angle_measure.png

When this plug in is active you can place the cursor on any object and drag the mouse to another object. The program will calculate the angular distance between the objects

CompassMarks. places a scale of degrees around the horizon

CompassMark.png

When active this places a 360 degree scale around the horizon.

Exoplanets. A list of stars with planets around that can be displayed from an editable data base - exoplanets.json

Exoplanets.png

When active this plug in reads the associated exoplanets.json file and places Exoplanet.png on the item with a name.

Oculars. This places a window on the screen that corresponds to the view through a telescope or on a camera. It reads from an editable data base.

Oculars.png

When this plug in is active a window will appear around the selected object depicting what would be seen by the viewing object. On the top right hand side of the screen a menu will appear that can be used to select the viewing device eg. Camera, Eyepiece. This menu is filled with items from the ocular.ini file in the modules\oculars folder. his file can be edited from the Plugins menu screen or by a text editor.

Pulsars. A list of Pulsars that can be displayed from an editable data base.

pulsars.png

When active this plug in reads the associated pulsars.json file and places pulsar.png in blue around the pulsar with a name

Quasars. A list of Quasars that can be displayed from an editable data base

Quasars.png

When active this plug in reads the associated pulsars.json file and places Quasar.png in red around the pulsar with a name

RendererStatistics.A list of statistics from the operation of the program

rendererstats.png

When activated displays statistics about the renderer

Satellites. This displays a number of earth orbiting satellies. automatically updated every 72 hours from the internet.

satellites.png

This plug in reads information on a selected range of near earth orbiting satellites from a file satellites.json that is updated every 72 hours and displays hint.png with a name. The file is editable with a text editor to change the colour and visibility when required.

Observability. This shows times and availabilty of objects you may wish to see

SolarSystemEditor. This can be used to find and include orbital data on Solar System objects and added to the ssystem.ini file


Observability_Solared.png

SuperNova. A list of Super Novas that can be displayed from an editable data base.

sn1604wiki.png

When Historical SuperNova is active follow the instructions from the plugin screen to display the supernova. This may require resetting the date to the listed date.


TextUserInterface (TUI). A way to change many parameters from the Stellarium Program

TUI-entry.png

The text user interface is basically for the use in planetariums. When the plug in is loaded it can be opened and closed with “m”. This will pace the entry point on the lower left of the screen which may be obscured by the landscape. To use it you scroll through the options with the arrow keys and press enter when the desired function is listed.

TimeZoneConfiguration. Used to manipulate the time zone of the display.

Timezone.png

References

  1. The installation directory was referred to as the config root directory in previous versions of this guide
  2. Windows Vista users who do not run Stellarium with administrator priviliges should adjust the shortcut in the start menu to specify a different directory for screenshots as the Desktop directory is not writable for normal progams. The next release of Stellarium will include a GUI option to specify the screenshot directory.
  3. It is possible to specify a different name for the main configuration file using the --config-file command line option. See section Command Line Options for details.
  4. Not all files in the .../data directory are listed here - only the ones which the advanced user is most likely to want to modify.
Personal tools
Namespaces
Variants
Actions
in this wiki
other languages
Toolbox