ch_interface.tex

% Status info:
% M. Gates	2006-2009
% A. Wolf	2011-2014
% B. Gerdes	2013
% Additions inserted from wiki 2015-12-26
% Content OK for 0.12.4.
% 2016-04 GZ started restructuring
% TODO: typo&grammar check

% \chapterimage{chapter-t2-bg} % Chapter heading image now set in guide.tex

\chapter{The User Interface}
\label{ch:gui}


This chapter describes the dialog windows which can be accessed from the left menu bar.

Most of Stellarium's settings can be changed using the view window
(press \guibutton[0.35]{2}{btd_view.png} or \key{F4}) and the
configuration window (\guibutton[0.35]{2}{btd_config.png} or
\key{F2}). Most settings have short labels. To learn more about some
settings, more information is available as \emph{tooltips}, small text
boxes which appear when you hover the mouse cursor over a
button.\footnote{Unfortunately, on Windows~7 and later, with some NVidia
  and AMD GPUs in OpenGL mode, these tooltips often do not work.}

\newFeature{0.15} You can drag the
windows around, and the position will be used again when you restart
Stellarium. If this would mean the window is off-screen (because you
start in windowed mode, or with a different screen), the window will
be moved so that at least a part is visible.

Some options are really rarely changed and therefore may only be
configured by editing the configuration file.  See
\ref{sec:ConfigurationFile} The Main Configuration File for more
details.



\section{Setting the Date and Time}
\label{sec:gui:date}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{date_and_time_dialog.png}
\caption{Date and Time dialog}
\label{fig:gui:date}
\end{figure}

In addition to the time rate control buttons on the main toolbar, you
can use the date and time window (open with the \guibutton[0.35]{2}{btd_time.png} 
button or \key{F5}) to set the simulation time. The values
for year, month, day, hour, minutes and seconds may be modified by
typing new values, by clicking the up and down arrows above and below
the values, and by using the mouse wheel.

The other tab in this window allows you to see or set
\indexterm{Julian Day} and/or \indexterm[Julian Day!Modified]{Modified Julian Day} numbers
(see~\ref{sec:Concepts:JulianDay}).

\section{Setting Your Location}
\label{sec:gui:location}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{location_dialog.png}
\caption{Location window}
\label{fig:gui:location}
\end{figure}

\noindent The positions of the stars in the sky is dependent on your location on
Earth (or other planet) as well as the time and date. For Stellarium to
show accurately what is (or will be/was) in the sky, you must tell it
where you are. You only need to do this once -- Stellarium can save your
location so you won't need to set it again until you move.

\newFeature{v0.13.1}
After installation, Stellarium uses an online service which tries to
find your approximate location based on the IP address you are
using. This seems very practical, but if you feel this causes privacy
issues, you may want to switch this feature off. You should also consider 
switching it off on a computer which does not move, to save network bandwidth.

To set your location more accurately, or if the lookup service fails,
press \key{F6} to open the location window (Fig.~\ref{fig:gui:location}). 
There are a few ways you can set your location:

\begin{enumerate}
\item Just click on the map.
\item Search for a city where you live using the search edit box at
  the top right of the window, and select the right city from the
  list.
\item Click on the map to filter the list of cities in the vicinity of
  your click, then choose from the shortlist.
\item Enter a new location using the longitude, latitude and other
  data.
\item Click on \button{Get Location from GPS} if you have a GPS
  receiver. \newFeature{0.16/0.18.1} You activate a periodic request
  for GPS fixes. After a few seconds, the button should change color
  and give a textual feedback. Green indicates a good position, yellow
  indicates a 2D-fix only, which means altitudes are not
  available. (Leave the GPS device running for a few minutes and/or
  search a place with better sky view.) You could leave it running if
  you are operating a fast-moving observatory platform, but rather
  switch it off when you see a good fix, so that other programs can
  use the serial GPS connection.  Red signals an error, and further
  positions are not retrieved but the button is reset. You may press
  the button again to start over.

  Sometimes you have to try several times or let it run for a while to get a
  green button indicating a valid 3D fix including altitude.
  See section~\ref{sec:ExtraData:GPS} for configuration details.
\end{enumerate}

\noindent If you want to use the current location permanently, click on the
``use as default'' checkbox, disable ``Get location from Network'',
and close the location window.



\section{The Configuration Window}
\label{sec:gui:configuration}

The configuration window contains general program settings, and many
other settings which do not concern specific display options. Press
the tool button \guibutton[0.35]{2}{btd_config.png} or \key{F2} to open.


\subsection{The Main Tab}
\label{sec:gui:configuration:main}


\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{config_dialog_main_tab.png}
\caption{Configuration Window: Main Tab}
\label{fig:gui:configuration:main}
\end{figure}

The Main tab in the configuration window (Fig.~\ref{fig:gui:configuration:main}) provides controls for
changing separately the program and sky culture languages.

The next setting group allows to enable using DE430/DE431 ephemeris files. 
These files have to be installed separately. Most users do not require this. 
See section~\ref{sec:ExtraData:ephemerides} if you are interested.

The tab also provides the buttons for saving the current view direction as default 
for the next startup, and for saving the program configuration. 
Most display settings have to be explicitly stored to make a setting change permanent.

\subsection{The Information Tab}
\label{sec:gui:configuration:info}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{config_dialog_info_tab.png}
\caption{Configuration Window: Information Tab}
\label{fig:gui:configuration:info}
\end{figure}

The Information tab (Fig.~\ref{fig:gui:configuration:info}) allows you to set the type and amount of information
displayed about a selected object.
\begin{itemize}
\item Ticking or unticking the relevant boxes will control this.
\item The information displays in various colours depending on the type and
level of the stored data
\end{itemize}

\subsection{The Extras Tab}
\label{sec:gui:configuration:extras}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{config_dialog_extras_tab.png}
\caption{Configuration Window: Extras Tab}
\label{fig:gui:configuration:extras}
\end{figure}

The Extras tab (Fig.~\ref{fig:gui:configuration:extras}) allows you to
customize information displayed about a selected object, download more
star catalogs and also allows to hide or show additional buttons in
the lower button bar. 
\subsubsection{Customization of information displays}
The information display can be tweaked a bit with the options found in the GUI section ``Additional information settings''.

\subsubsection{Customization of button visibility on bottom toolbar}
If your screen is too narrow to show all buttons
or you simply don't need them because you prefer the keyboard
shortcuts, you can choose your optimal setup. The selection of buttons is stored immediately. 
\begin{description}
\item[Show constellation boundaries button] You can toggle display of constellation boundaries with this button.
\item[Show asterism lines button] You can toggle display of asterism lines with this button.
\item[Show asterism labels button] You can toggle display of asterism labels with this button.
\item[Show ecliptic grid button] You can toggle display of ecliptic coordinate grid with this button.
\item[Show ICRS grid button] You can toggle display of the International Coordinate Reference System (equatorial J2000 coordinate grid) with this button.
\item[Show galactic grid button] You can toggle display of galactic coordinate grid with this button.
\item[Show centering button] You can toggle display of the ``center on selected object'' button.
\item[Show nightmode button] You can toggle display of the nightmode button.
\item[Show nebula background button] You can toggle display of DSO photographs with this button.
\item[Show flip buttons] When enabled, two buttons will be added to
  the main tool bar which allow the main view to be mirrored in the
  vertical and horizontal directions. This is useful when observing
  through telecopes which may cause the image to be mirrored.
\item[Show DSS button] You can toggle display of Digitized Sky Survey with this button (see section~\ref{sec:TOAST}).
\item[Show HiPS button] You can toggle display of Hierarchical Progressive Surveys with this button (see section \ref{sec:gui:view:surveys}).
\item[Show bookmarks button] You can enable display of Bookmarks dialog with this button.
\item[Show fullscreen button] You can toggle display of the fullscreen button.
\item[Show Quit button] You can toggle display of the button to quit Stellarium.
\item[Use buttons background] Applies a gray background under the buttons on the bottom bar.
\end{description}

\subsubsection{Download more star catalogs}
Stellarium comes with enough stars for casual stargazing with the
unaided eye or binoculars. If you have a telescope and want to see
more stars, here you can download more catalogs.

\subsection{The Time Tab}
\label{sec:gui:configuration:time}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{config_dialog_time_tab.png}
\caption{Configuration Window: Time Tab}
\label{fig:gui:configuration:time}
\end{figure}

The Time tab (Fig.~\ref{fig:gui:configuration:time}) allows to specify what simulation time should be used
when the program starts:

\begin{description}
\item[System date and time] Stellarium will start with
  the simulation time equal to the operating system clock.
\item[System date at] Stellarium will start with the
  same date as the operating system clock, but the time will be fixed at
  the specified value. This is a useful setting for those people who use
  Stellarium during the day to plan observing sessions for the upcoming
  evening.
\item[Other] some fixed time can be chosen which will
  be used every time Stellarium starts.
\end{description}

\noindent The middle field allows specify display formats for date and time on bottom toolbar:
\begin{description}
\item[JD] Stellarium will display Julian Days (JD).
\item[Date and time] Stellarium will display date and time in selected format.
\end{description}

\noindent The lowest field allows selection of the correction model for the time
correction $\Delta T$ (see section~\ref{sec:Concepts:DeltaT}). Default
is ``Espenak and Meeus (2006)''. Please use other values only if you
know what you are doing.

\subsection{The Tools Tab}
\label{sec:gui:configuration:tools}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{config_dialog_tools_tab.png}
\caption{Configuration Window: Tools Tab}
\label{fig:gui:configuration:tools}
\end{figure}

The Tools tab (Fig.~\ref{fig:gui:configuration:tools}) contains planetarium options (like enabling/disabling of keyboard shortcuts for panning and zooming the main view) and options for screenshots.

\begin{description}
\item[Spheric mirror distortion] This option pre-warps the main view
  such that it may be projected onto a spherical mirror using a
  projector. The resulting image will be reflected up from the spherical
  mirror in such a way that it may shine onto a small planetarium
  dome (or even just the ceiling of your dining room), making a cheap planetarium projection system.
\item[Disc viewport] This option masks the main view
  producing the effect of a telescope eyepiece. It is also useful when
  projecting Stellarium's output with a fish-eye lens planetarium
  projector.
\item[Gravity labels] This option makes labels of objects in the
  main view align with the nearest horizon. This means that labels
  projected onto a dome are always aligned properly.
\item[Select single constellation] When active, clicking on a star
  that is member in the constellation lines will make the
  constellation stand out. You can select several constellations, but
  clicking onto a star which is not member of a constellation line
  will display all constellations.
\item[Auto-enabling for the atmosphere] When changing planet during
  location change, atmosphere will be switched as required.
\item[Dithering] options to allow select better simulation of sky on different hardware.
\item[Auto zoom out returns to initial direction of view] When enabled,
  this option changes the behaviour of the zoom out key
  \key{\textbackslash{}} so that it resets the initial direction of view in
  addition to the field of view.
\item[Enable keyboard navigation]
\item[Enable mouse navigation]

\item[Azimuth from South] Some users may be used to counting azimuth
  from south.
\item[Use decimal degrees] You can toggle usage of decimal degree format for coordinates.
\item[Topocentric coordinates] If you require planetocentric coordinates, you may switch this off. 
  Usually it should be enabled. (See~\ref{sec:Concepts:Parallax:Topocentric})
\item[Include nutation] Compute the slight wobble of earth's
  axis. This feature is active only about 500 years around J2000.0.
\item[Auto select landscapes] When changing the planet in the location
  panel, a fitting landscape panorama will be shown when available.
\item[Indication for mount mode] You can activate the short display of a message when switching type of used mount.
\item[Edit keyboard shortcuts\ldots] See section~\ref{sec:gui:help:hotkeys}.
\item[Mouse cursor timeout] You can decide whether, and when, the
  mouse cursor should disappear from view when not moved.
\item[Use kinetic scrolling]  Text fields in \newFeature{v0.18.3} 
  dialogs can either be moved on sidebar handles (with this switch
  disabled) or by dragging the text itself (enabled), as it is known
  from touch-enabled devices like smartphones. 
\end{description}

\paragraph{Font size and font selection} \newFeature{v0.18.3} You can change the font sizes for on-screen
text and GUI dialogs separately.  For some purposes like presentations
it may be helpful to enlarge screen font size while keeping GUI font
regular, or vice versa.  It also depends on your screen size whether
all the object info fits on screen. This may also depend on the
writing system and installed font. If you are using a non-Western
character system and the default font looks bad, you can select
another system font. For this, edit \file{config.ini} (see
chapter~\ref{sec:Directories}): locate the \texttt{[gui]} section and
set the key \texttt{flag\_font\_selection=true}. On next start of
Stellarium, you will find two elements for font selection: one allows
you to pre-select a writing system, the other will then allow
selection of a font installed in your system that includes the
characters used in the selected writing system. When you have found
the best font, store your settings on the Main tab (see
section~\ref{sec:gui:configuration:main}) and you may edit
\file{config.ini} again to disable the font selection switches.

\paragraph{Screenshots} You can set the directory where screenshots
will be stored, and \newFeature{v0.18.1} also whether you want
screenshots sized like Stellarium's window or some other, likely
larger size. The maximum possible size depends on your
hardware. $4096\times4096$ should be possible on most PCs, others may
even create $16384\times16384$ images. The vertical field of view will be the same as in the current view.
You can also set \newFeature{v0.19.0} the file format. The exact selection depends on
platform and version of the underlying Qt framework. Notable formats are PNG (lossless), JPG (lossy),
JPEG (higher quality JPG), BMP (Windows Bitmap), WEBP, TIF (LZW compressed), TIFF (uncompressed),
PBM, PGM, PPM, XBM, XPM, and ICO (thumbnails).


\subsection{The Scripts Tab}
\label{sec:gui:configuration:scripts}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{config_dialog_scripts_tab.png}
\caption{Configuration Window: Scripts Tab}
\label{fig:gui:configuration:scripts}
\end{figure}

The Scripts tab (Fig.~\ref{fig:gui:configuration:scripts}) allows the
selection of pre-assembled scripts bundled with Stellarium that can be
run (See chapter~\ref{ch:scripting} for an introduction to the
scripting capabilities and language). This list can be expanded by
your own scripts as required. See
section~\ref{sec:FilesAndDirectories:DirectoryStructure} where to
store your own scripts.

When a script is selected it can be run by pressing the arrow button
and stopped with the stop button. With some scripts the stop button is
inhibited until the script is finished. %% TODO: EXPLAIN HOW?

Scripts that use sound or embedded videos will need a version of
Stellarium configured at compile time with multimedia support
enabled. It must be pointed out here that sound or video codecs
available depends on the sound and video capabilities of you computer
platform and may not work.


\subsection{The Plugins Tab}
\label{sec:gui:configuration:plugins}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{config_dialog_plugins_tab.png}
\caption{Configuration Window: Plugins Tab}
\label{fig:gui:configuration:plugins}
\end{figure}


Plugins (see chapter~\ref{ch:Plugins} for an introduction) can be
enabled here (Fig.~\ref{fig:gui:configuration:plugins}) to be loaded the next time
you start Stellarium. When loaded, many plugins allow additional configuration
which is available by pressing the \button{configure} button on this tab.


\section{The View Settings Window}
\label{sec:gui:view}

The View settings window controls many display features of Stellarium
which are not available via the main toolbar.

\subsection{The Sky Tab}
\label{sec:gui:view:sky}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{view_dialog_sky_tab.png}
\caption{View Settings Window: Sky Tab}
\label{fig:gui:view:sky}
\end{figure}

The Sky tab of the View window (Fig.~\ref{fig:gui:view:sky}) contains settings
for changing the general appearance of the main sky view and projections. Some hightlights of sky field:
\begin{description}
\item[Dynamic eye adaptation] When enabled this feature reduces the
  brightness of faint objects when a bright object is in the field of
  view. This simulates how the eye can be dazzled by a bright object
  such as the moon, making it harder to see faint stars and galaxies.
\item[Light pollution] In urban and suburban areas, the sky is
  brightned by terrestrial light pollution reflected in the atmophere.
  Stellarium simulates light pollution and is calibrated to the
  \emph{Bortle Dark Sky Scale} where 1 means a good dark sky, and 9 is
  a very badly light-polluted sky. See Appendix~\ref{ch:BortleScale}
  for more information.
\end{description}

Some
hightlights of stars field:
\begin{description}
\item[Absolute scale] is the size of stars as rendered by
  Stellarium. If you increase this value, all stars will appear larger
  than before.
\item[Relative scale] determines the difference in size of bright
  stars compared to faint stars. Values higher than 1.00 will make the
  brightest stars appear much larger than they do in the sky. This is
  useful for creating star charts, or when learning the basic
  constellations.
\item[Twinkle] controls how much the stars twinkle when atmosphere is
  enabled (\indexterm{scintillation}, see section~\ref{sec:phenomena:Scintillation}). 
  Since v0.15.0, the twinkling is reduced in higher altitudes,
  where the star light passes the atmosphere in a steeper angle and is
  less distorted.
\item[Limit magnitude] Inhibits automatic addition of fainter stars
  when zooming in. This may be helpful if you are interested in naked
  eye stars only.
\item[Labels and markers] you can independantly change the amount of
  labels displayed for stars. The further to the
  right the sliders are set, the more labels you will see. Note that
  more labels will also appear as you zoom in.
\end{description}

Projection field: Selecting items in this list changes the
  projection method which Stellarium uses to draw the sky~\citep{Snyder:MapProjections}. Options are:

\begin{description}
  \item[Perspective] Perspective projection maps the horizon and other
    great circles like equator, ecliptic, hour lines, etc. into
    straight lines. The maximum field of view is 150\degree. The
    mathematical name for this projection method is \emph{gnomonic
      projection}.
  \item[Stereographic] Stereographic projection has been known since
    antiquity and was originally known as the planisphere
    projection. It preserves the angles at which curves cross each
    other but it does not preserve area. Else it is similar to
    fish-eye projection mode. The maximum field of view in this mode
    is 235\degree.
  \item[Fish-Eye] Stellarium draws the sky using \emph{azimuthal
    equidistant projection}. In fish-eye projection, straight lines
    become curves when they appear a large angular distance from the
    centre of the field of view (like the distortions seen with very
    wide angle camera lenses). This is more pronounced as the user zooms
    out. The maximum field of view in this mode is 180\degree.
  \item[Orthographic] Orthographic projection is related to
    perspective projection, but the \emph{point of perspective} is set
    to an infinite distance. The maximum field of view is 180\degree.
  \item[Equal Area] The full name of this projection method is
    \emph{Lambert azimuthal equal-area projection}. It preserves the
    area but not the angle. The maximum field of view is 360\degree.
  \item[Hammer-Aitoff] The Hammer projection is an equal-area map
    projection, described by \name[Ernst von]{Hammer} (1858--1925) in 1892 and directly inspired
    by the Aitoff projection. The maximum field of view in this mode is
    360\degree.
  \item[Sinusoidal] The sinusoidal projection is a
    \emph{pseudocylindrical equal-area map projection}, sometimes
    called the Sanson--Flamsteed or the Mercator equal-area
    projection. Meridians are mapped to sine curves.
  \item[Mercator] Mercator projection is a cylindrical projection developed 
    by \name[Gerardus]{Mercator} (1512--1594)
    which preserves the angles between objects, and the scale around
    an object is the same in all directions. The poles are mapped to
    infinity.  The maximum field of view in this mode is 233\degree.
  \item[Miller cylindrical] The Miller cylindrical projection is a
    modified Mercator projection, proposed by \name[Osborn Maitland]{Miller}
    (1897--1979) in 1942. The poles are no longer mapped to
    infinity.
  \item[Cylinder] The full name of this simple projection mode is
    \emph{cylindrical equidistant projection} or \emph{Plate
      Carr\'ee}. The maximum field of view in this mode is 233\degree.
\end{description}

\subsection{The Solar System Objects (SSO) Tab}
\label{sec:gui:view:sso}

The Solar System Objects tab of the View window (Fig.~\ref{fig:gui:view:sso}) contains settings
for changing the general appearance of the view of Solar system objects. Some hightlights:

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{view_dialog_sso_tab.png}
\caption{View Settings Window: SSO Tab}
\label{fig:gui:view:sso}
\end{figure}


\begin{description}
\item[Solar System objects] this group of options lets you turn on
  and off various features related to the planets. Simulation of light
  speed will give more precise positions for planetary bodies which move
  rapidly against backround stars (e.g. the moons of Jupiter). The
  \emph{Scale Moon} option will increase the apparent size of the moon
  in the sky, which can be nice for wide field of view shots.
\item[Labels and markers] you can independantly change the amount of
  labels displayed for Solar system objects. The further to the
  right the sliders are set, the more labels you will see. Note that
  more labels will also appear as you zoom in.
\item[Shooting stars] Stellarium has a simple meteor simulation
  option. This setting controls how many shooting stars will be shown.
  Note that shooting stars are only visible when the time rate is 1, and
  might not be visiable at some times of day. Meteor showers are not
  currently simulated.
\end{description}

\subsubsection{Atmosphere settings}
\label{sec:gui:view:sky:atmosphere}

An auxiliary dialog contains detail settings for the atmosphere. Here
you can set atmospheric pressure and temperature which influence
refraction (see section~\ref{sec:phenomena:Refraction}), and the
opacity factor $k_v$ for extinction, \emph{magnitude loss per airmass} 
(see section~\ref{sec:phenomena:Extinction}).


\subsection{The Deep-Sky Objects (DSO) Tab}
\label{sec:gui:view:dso}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{view_dialog_dso_tab.png}
\caption{View Settings Window: DSO Tab}
\label{fig:gui:view:dso}
\end{figure}

\indexterm{Deep-sky objects} or DSO are extended objects which are
external to the solar system, and are not point sources like stars.
DSO include galaxies, planetary nebulae and star clusters. These
objects may or may not have images associated with them. Stellarium
comes with a catalogue of over 90,000 extended objects containing
the combined data from many catalogues, with 200 images.  

The DSO tab (Fig.~\ref{fig:gui:view:dso}) allows you to specify which 
catalogs or which object types you are interested in. This selection 
will also be respected in other parts of the program, 
most notably Search (section~\ref{sec:gui:search}) and 
AstroCalc/WUT (section~\ref{sec:gui:AstroCalc:WUT}) 
will not find objects from catalogs which you have not selected here. 

See chapter~\ref{ch:DSO} for details about the catalog, 
and how to extend it with your own photographs.


\subsection{The Markings Tab}
\label{sec:gui:view:markings}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{view_dialog_markings_tab.png}
\caption{View Settings Window: Markings Tab}
\label{fig:gui:view:markings}
\end{figure}

The Markings tab of the View window
(Fig.~\ref{fig:gui:view:markings}) controls plot various grids and lines on celestial sphere.

\subsection{The Landscape Tab}
\label{sec:gui:view:landscape}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{view_dialog_landscape_tab.png}
\caption{View Settings Window: Landscape Tab}
\label{fig:gui:view:landscape}
\end{figure}

The Landscape tab of the View window
(Fig.~\ref{fig:gui:view:landscape}) controls the landscape graphics
(the horizon which surrounds you). To change the landscape graphics,
select a landscape from the list on the left side of the window. A
description of the landscape will be shown on the right.

Note that while a landscape  can include information about where the
landscape graphics were taken (planet, longitude, latitude and
altitude), this location does not have to be the same as the location
selected in the Location window, although you can set up Stellarium such
that selection of a new landscape will alter the location for you.

The controls at the bottom right of the window operate as follows:

\begin{description}
\item[Show ground] This turns on and off landscape rendering (same
  as the button \guibutton{0.6}{bt_ground.png} in the main tool-bar).
\item[Show\_fog] This turns on and off rendering of a band of
  fog/haze along the horizon, when available in this landscape.
\item[Use associated planet and position] When enabled, selecting a
  new landscape will automatically update the observer location.
\item[Use this landscape as default] Selecting this option will save
  the landscape into the program configuration file so that the current
  landscape will be the one used when Stellarium starts.
\item[Minimal brightness] Use some minimal brightness
  setting. Moonless night on very dark locations may appear too dark
  on your screen. You may want to configure some minimal brightness
  here.
\item[from landscape, if given] Landscape authors may decide to
  provide such a minimal brightness value in the \file{landscape.ini}
  file.
\item[Show landscape labels] Landscapes can be configured with a
  gazetteer of interesting points, e.g., mountain peaks, which can be
  labeled with this option.
\item[Show illumination] to reflect the ugly developments of our
  civilisation, landscapes can be configured with a layer of light
  pollution, e.g., streetlamps, bright windows, or the sky glow of a
  nearby city. This layer, if present, will be mixed in when it is
  dark enough.
\end{description}

\noindent Using the button \menu{Add/remove landscapes\ldots}, you can also
install new landscapes from ZIP files which you can download e.g.\
from the Stellarium
website\footnote{\url{http://stellarium.sourceforge.net/wiki/index.php/Landscapes}}
or create yourself (see ch.~\ref{ch:landscapes} Landscapes), or remove
these custom landscapes.

Loading large landscapes may take several seconds. \newFeature{v0.15.2}
If you like to switch rapidly between several landscapes and have enough memory, 
you can increase the default cache size to keep more landscapes loaded previously 
available in memory. Note that a large landscape can take up 200MB or more! 
See section \ref{sec:configini:landscape}.

\subsection{The Starlore Tab}
\label{sec:gui:view:starlore}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{view_dialog_starlore_tab.png}
\caption{View Settings Window: Starlore Tab}
\label{fig:gui:view:starlore}
\end{figure}

The Starlore tab of the View window (Fig.~\ref{fig:gui:view:starlore})
controls what culture's constellations and bright star names will be
used in the main display.  Some cultures have constellation art (e.g.,
Western and Inuit), and the rest do not. Configurable options include
\begin{description}
\item[Use this skyculture as default] Activate this option to load
  this skyculture when Stellarium starts.
\item[Show labels] Activate display of constellation labels, like
  \guibutton{0.6}{bt_constellation_name.png} or \keys{V}. You can further
  select whether you want to display abbreviated, original or
  translated names.
\item[Show lines with thickness\ldots] Activate display of stick
  figures, like \guibutton{0.6}{bt_constellation.png} or \keys{C}, and you
  can configure constellation line thickness here.
\item[Show asterism lines\ldots] Activate display of asterism stick figures   
  (like the shortcut \keys{Alt+A}), and you can configure asterism line thickness here.\newFeature{v0.16.0}
\item[Show ray helpers\ldots] Activate display of special navigational lines which 
 connect stars often from different constellations (like the shortcut \keys{Alt+R}), and you can configure thickness of those lines here.\newFeature{v0.17.0}
\item[Show boundaries] Activate display of constellation boundaries,
  like \keys{B}. Currently, boundaries have been defined only for
  ``Western'' skycultures.
\item[Use native names for planets] If provided, show the planet names
  as used in this skyculture (also shows modern planet name for
  reference). %% TODO THIS FEATURE NEEDS SOME REWORK!
\item[Show art in brightness\ldots] Activate display of constellation
  art (if available), like \guibutton{0.6}{bt_constellation_art.png} or
  \keys{R}. You can also select the brightness here.
\item[Show asterism labels] Activate display of asterism labels, like \keys{Alt+V}.\newFeature{v0.16.0}
\end{description}

\subsection{The Surveys Tab}
\label{sec:gui:view:surveys}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{view_dialog_surveys_tab.png}
\caption{View Settings Window: Surveys Tab}
\label{fig:gui:view:surveys}
\end{figure}

\newFeature{v0.18.0} The Surveys tab (Fig.~\ref{fig:gui:view:surveys}) allows to toggle the
visibility of online sky or solar system surveys (see chapter~\ref{ch:surveys}
for description of the surveys format).  Currently, only HiPS surveys are
supported.

On the left side of the window we see the list of available surveys from
the configured sources (See section \ref{sec:config.ini:hips} for how to
change the default sources).  On the right side a description of the selected
survey and its properties are displayed.

Surveys are grouped by types. The top combobox allows to filter the listed
surveys according to a given type (Deep Sky or Solar System).

You can toggle the visibility of a survey by checking the box on the left
of the survey name in the list.  (Note that as of v0.18.0, only a single deep
sky survey can be rendered at a time, so it makes no sense to select more than one in
the list!) Once a survey is visible you should be able to see its loading
status in the loading bar area of the sky view.

Deep sky surveys will be rendered aligned with the sky view, while solar system
surveys automatically map on the proper body.


\section{The Object Search Window}
\label{sec:gui:search}

\begin{figure}[h]
\centering\includegraphics[width=0.68\textwidth]{search_dialog.png}
\caption{The Search Window: Objects}
\label{fig:gui:search}
\end{figure}

\begin{figure}[h]
\centering\includegraphics[width=0.68\textwidth]{search_dialog_position.png}
\caption{The Search Window: Positions}
\label{fig:gui:search:position}
\end{figure}

\begin{figure}[h]
\centering\includegraphics[width=0.68\textwidth]{search_dialog_list.png}
\caption{The Search Window: Lists}
\label{fig:gui:search:lists}
\end{figure}


\begin{figure}[h]
\centering\includegraphics[width=0.68\textwidth]{search_dialog_option.png}
\caption{The Search Window: Options}
\label{fig:gui:search:options}
\end{figure}

The Object Search window provides a convenient way to locate objects
in the sky. Simply type in the name of an object to find, and press
\key{\return}. Stellarium will point you at that object in the sky.

As you type, Stellarium will make a list of objects which contains 
what you have typed so far. The first of the list of matching objects
will be highlighted. If you press the \key{\tab} key, the selection will change
to the next item in the list. Hitting the \key{\return} key will go to the
currently highlighted object and close the search dialog.

For example, suppose we want to locate Saturn's moon Mimas. 
Type the first letter of the name, \emph{m}, to see a list
of objects whose name contains \emph{m}: Hau\emph{m}ea, \emph{M}iranda, U\emph{m}briel, \ldots 

You may want at this point to have Stellarium rather propose object
names with start with the string you enter. Do that in the Options tab
of this panel. Now repeat searching (delete, and re-enter \emph{m} to start
over). Now the list is shorter and contains only objects which start
with \emph{m}: \emph{M}aia, \emph{M}ars, \ldots The first item in this list, Maia, is
highlighted. Pressing \key{\return} now would go to Maia, but we want
Mimas. We can either press \key{\tab} a few times to highlight Mimas
and then hit \key{\return}, or we can continue to type the name until
it is the first/only object in the list.

The Position tab (Fig.~\ref{fig:gui:search:position}) provides a convenient way to enter a set
of coordinates.

The List Search tab (Fig.~\ref{fig:gui:search:options}) allows selection of an object from predefined
sets.  The number of choices is governed by the loaded DSO catalogs and plug-ins. 
Scroll down the first window to select the type. Click on the name
and Stellarium will go to that object.

The Options tab (Fig.~\ref{fig:gui:search:options}) provides a few settings to fine-tune your search experience.
When the name of an object to find is typed in the object
window and you are connected to the internet and ``Extend search'' is
ticked, Stellarium will search the SIMBAD on-line  data bases for its
coordinates. You can then click the \guibutton{0.6}{bt_search.png} button or press return.
Stellarium will point you at that object in the sky even if there is no
object displayed on the screen. The SIMBAD server being used can be
selected from the scroll window.


\section{The Astronomical Calculations Window}
\label{sec:gui:AstroCalc}

This window \newFeature{v0.15.0} provides advanced functionality, some of which is still in an experimental phase. 
You can call it by pressing \key{F10} or the button \guibutton{0.6}{btd_astrocalc.png} on the left menu bar. 
The Astronomical Calculations window shows six tabs with different functionality.

In version 0.18.3 \newFeature{v0.18.3} we added exporting the data to XLSX files in addition to CSV files.

\subsection{The Positions Tab}
\label{sec:gui:AstroCalc:Positions}

This tab \newFeature{v0.16.0} shows J2000.0 or horizontal positions, magnitudes and additional parameters 
(e.g.\ surface brightness for deep-sky objects or angular separation for double stars) for various 
lists of celestial objects above the horizon at the simulated time, filtered by magnitude. 
Double-clicking on an entry brings the object into focus (Fig.~\ref{fig:gui:AstroCalc:Positions}). 
You may also export the list of positions into an XLSX or CSV file.


\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{astrocalc_dialog_positions_tab.png}
\caption{Astronomical Calculations (AstroCalc): Celestial positions}
\label{fig:gui:AstroCalc:Positions}
\end{figure}

\subsection{The Ephemeris Tab}
\label{sec:gui:AstroCalc:Ephemeris}

Select an object, start and end time, and compute an ephemeris (list of positions and magnitudes evolving over time) for that object. 
The positions are marked in the sky with yellow circles (Fig.~\ref{fig:gui:AstroCalc:Ephemeris}). 

When you click on a date, an orange circle indicates this date and/or magnitude. 
Double-clicking sets the respective date and brings the object to focus. 
Dates and/or magnitudes will show near position markers when \emph{Show dates} and/or \emph{Show magnitudes} checkboxes are active.

You can export the calculated ephemeris into an XLSX or CSV file. 

\begin{figure}[tbp]
\centering\includegraphics[width=0.98\textwidth]{astrocalc_dialog_ephemeris_tab.png}
\caption{Astronomical Calculations (AstroCalc): Plot trace of planet}
\label{fig:gui:AstroCalc:Ephemeris}
\end{figure}

Another interesting option in this tool: using horizontal coordinates for plotting traces of the Solar system objects. 
In this mode, the circle marks are not linked to the sky, but to the horizontal coordinate system.
For example, you can get an analemma of the Sun for any location (Fig.~\ref{fig:gui:AstroCalc:Ephemeris:Analemma} and \ref{fig:gui:AstroCalc:Ephemeris:AnalemmaMars}), 
or observe the visibility of Mercury, Venus or a comet in the twilight sky.

\begin{figure}[tbp]
\centering\includegraphics[width=0.98\textwidth]{astrocalc_dialog_ephemeris_analemma.png}
\caption{Astronomical Calculations (AstroCalc): Analemma on the Earth}
\label{fig:gui:AstroCalc:Ephemeris:Analemma}
\end{figure}

\begin{figure}[tbp]
\centering\includegraphics[width=0.98\textwidth]{astrocalc_dialog_ephemeris_analemma_mars.png}
\caption{Astronomical Calculations (AstroCalc): Analemma on Mars}
\label{fig:gui:AstroCalc:Ephemeris:AnalemmaMars}
\end{figure}

\newpage
\subsection{The Phenomena Tab}
\label{sec:gui:AstroCalc:Phenomena}

This tab allows you to compute phenomena like conjunctions, oppositions, 
occultations and eclipses (in special cases) between planetary objects 
(Fig.~\ref{fig:gui:AstroCalc:Phenomena}). 
You can export the calculated phenomena into an XLSX or CSV file.

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{astrocalc_dialog_phenomena_tab.png}
\caption{Astronomical Calculations (AstroCalc): Phenomena}
\label{fig:gui:AstroCalc:Phenomena}
\end{figure}

Two columns in the table \newFeature{v0.18.2/.3} may be helpful for planning observation of phenomena:
\begin{description}
  \item[solar elongation] angular distance from the Sun
  \item[lunar elongation] angular distance from the Moon
\end{description}


\subsection{The Graphs Tab}
\label{sec:gui:AstroCalc:Graphs}

This tab \newFeature{v0.18.3} provides sub-tabs with graphs helpful for monthly observation planning of deep-sky objects.

\subsubsection{The ``Altitude vs.\ Time'' Subtab}
\label{sec:gui:AstroCalc:Graphs:AltVsTime}
  
On this subtab (the first subtab and default view in the Graphs tab) you can compute the geometrical altitude of the currently selected object 
on the currently set date and draw it as a graph (Fig.~\ref{fig:gui:AstroCalc:Graphs:AltVsTime}).
    
\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{astrocalc_dialog_graphs_tab_altvstime.png}
\caption{Astronomical Calculations (AstroCalc): Graphs / Altitude vs.\ Time}
\label{fig:gui:AstroCalc:Graphs:AltVsTime}
\end{figure}

Optional graphs for the Sun (with lines for civil, nautical and astronomical twilight) and the Moon (dashed) are also available.

\subsubsection{The ``Monthly Elevation'' Subtab}
\label{sec:gui:AstroCalc:Graphs:ME}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{astrocalc_dialog_graphs_tab_me.png}
\caption{Astronomical Calculations (AstroCalc): Graphs / Monthly Elevation}
\label{fig:gui:AstroCalc:Graphs:ME}
\end{figure}

This subtab \newFeature{v0.18.0} can show a ``Monthly Elevation'' graph for the current year at the selected time.
This tool was introduced for planning yearly observations (Fig.~\ref{fig:gui:AstroCalc:Graphs:ME}).

\subsubsection{The ``Graphs'' Subtab}
\label{sec:gui:AstroCalc:Graphs:Graphs}
    
\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{astrocalc_dialog_graphs_tab_graphs.png}
\caption{Astronomical Calculations (AstroCalc): Graphs}
\label{fig:gui:AstroCalc:Graphs:Graphs}
\end{figure}
  
This subtab \newFeature{v0.16.0} can show two functions over time for the current year and draw graphs for them in one screen (Fig.~\ref{fig:gui:AstroCalc:Graphs:Graphs}). 
You can select from 
\begin{itemize}
\item Magnitude vs. Time
\item Phase vs. Time
\item Distance vs. Time 
\item Elongation vs. Time 
\item Angular size vs. Time
\item Phase angle vs. Time
\item Heliocentric distance vs. Time\newFeature{v0.18.2}
\end{itemize}

This tool may be very helpful for educational and statistics purposes.%
	\footnote{The idea for this tool has been obtained from \program{SkytechX}: \url{http://www.skytechx.eu/}}
	
\subsubsection{The ``Angular Distance'' Subtab}
\label{sec:gui:AstroCalc:Graphs:AD}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{astrocalc_dialog_graphs_tab_ad.png}
\caption{Astronomical Calculations (AstroCalc): Graphs / Angular Distance}
\label{fig:gui:AstroCalc:Graphs:AD}
\end{figure}

This subtab \newFeature{v0.18.3} can show ``Angular Distance'' graph --- change of angular distance between the Moon and selected object (for example some deep-sky object) for the nearest 30 days. This tool was introduced for planning monthly observations (Fig.~\ref{fig:gui:AstroCalc:Graphs:AD}).

\subsection{The ``What's Up Tonight'' (WUT) Tab}
\label{sec:gui:AstroCalc:WUT}

The ``What's Up Tonight'' (WUT) tool\newFeature{v0.16.0}%
	\footnote{This tool has been partially ported from the \program{KStars} planetarium: \url{https://edu.kde.org/kstars/}}
 displays a list of objects that will be visible at night for the current date and location.

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{astrocalc_dialog_wut_tab.png}
\caption{Astronomical Calculations (AstroCalc): What's Up Tonight (WUT)}
\label{fig:gui:AstroCalc:WUT}
\end{figure}

The objects are organized into type categories. Select an object type in the box labeled 
\emph{Select a Category}, and all objects of that type which are above the horizon on the selected night 
will be displayed in the box labeled \emph{Matching Objects}. For example, in the screenshot, 
the Planets category has been selected, and three planets which are up in the selected night are displayed (Jupiter, Mars and Mercury). 

By default, the WUT will display objects which are above the horizon between sunset and midnight (i.e.\ \emph{in the evening}). 
You can choose to show objects which are up between midnight and dawn (\emph{in the morning}), 
\emph{around midnight}, 
or any time between dusk and dawn (\emph{any time tonight}) using the combobox near the top of the window. 
You can also choose to see only those objects that are brighter than a certain magnitude by 
setting a minimum magnitude using the \emph{Show objects brighter than magnitude} spinbox. 
You may center an object from the right list in the sky map just by selecting it.

Note that only DSO from catalogs which you have selected in the DSO panel (section~\ref{sec:gui:view:dso}) will be found.

In version 0.18.3 \newFeature{v0.18.3} this tool has been refactored: the tool for searching items from list of \emph{Matching Objects} was removed,
the filter for magnitudes was moved to the right and we added a new filter here to limit the range of acceptable angular sizes of matched objects.
In addition to the names we added 5 new sortable columns: magnitude, rising time, transit time, setting time and angular size of object.


\subsection{The ``Planetary Calculator'' (PC) Tab}
\label{sec:gui:AstroCalc:PC}

The ``Planetary Calculator'' (PC) tool\newFeature{v0.17.0} has been added after user requests. 
It computes the relations between two Solar system bodies for the current date and location --- linear and angular distances, 
orbital resonances and orbital velocities.

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{astrocalc_dialog_pc_tab.png}
\caption{Astronomical Calculations (AstroCalc): Planetary Calculator (PC), Data Tab}
\label{fig:gui:AstroCalc:PC:Data}
\end{figure}

In version 0.18.2 \newFeature{v0.18.2} we enhanced this tool with a new tab (\emph{Graphs}),
where you may see the change in the linear and angular distances between selected celestial bodies
over a range of 600 days (centered on the current date) as graphs (Fig.~\ref{fig:gui:AstroCalc:PC:Graphs}).

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{astrocalc_dialog_pc_graphs_tab.png}
\caption{Astronomical Calculations (AstroCalc): Planetary Calculator (PC), Graphs Tab}
\label{fig:gui:AstroCalc:PC:Graphs}
\end{figure}


\newpage 
   
\section{Help Window}
\label{sec:gui:help}

\subsection{The Help Tab}
\label{sec:gui:help:help}
\begin{figure}[htbp]
\centering\includegraphics[width=0.6\textwidth]{help_dialog.png}
\caption{Help Window}
\label{fig:gui:help}
\end{figure}

\noindent The Help Tab lists all of Stellarium's keystrokes. Note that some
features are only available as keystrokes, so it's a good idea to have
a browse of the information in this window.

\subsection{The About Tab}
\label{sec:gui:help:about}
\begin{figure}[htbp]
\centering\includegraphics[width=0.6\textwidth]{help_dialog_about.png}
\caption{Help Window: About}
\label{fig:gui:help:about}
\end{figure}

The About Tab (Fig.~\ref{fig:gui:help:about}) shows version and licensing information, and a list of people who helped to produce the program.
Since version 0.18.3 \newFeature{0.18.3} this tab has tool to check for updates of Stellarium.

\subsection{The Log Tab}
\label{sec:gui:help:log}
\begin{figure}[htbp]
\centering\includegraphics[width=0.6\textwidth]{help_dialog_log.png}
\caption{Help Window: Logfile}
\label{fig:gui:help:log}
\end{figure}

The Log Tab (Fig.~\ref{fig:gui:help:log}) shows messages like the loading confirmations carried out when
stellarium runs. It is useful to locate the files that stellarium writes
to your computer. The same information is written to  the file \file{log.txt} that you will
find in your user directory (see~\ref{sec:Directories}).

\section{Editing Keyboard Shortcuts}
\label{sec:gui:help:hotkeys}

\begin{figure}[htbp]
\centering\includegraphics[width=0.75\textwidth]{hotkeys_dialog.png}
\caption{Keyboard Shortcuts}
\label{fig:gui:hotkeys}
\end{figure}

You can edit the shortcut keys here. Each available function can be
configured with up to two key combinations. You may want to
reconfigure keys for example if you have a non-English keyboard layout
and some keys either do not work at all, or feel unintuitive for you,
or if you are familiar with other software and want to use the same
hotkeys for similar functions. Simply select the function and click
with the mouse into the edit field, then press your key of choice. If
the key has been taken already, a message will tell you.

This tool is available through the Help Tab of the Help window (see section~\ref{sec:gui:help:help}) and the
Tools Tab of the Configuration window (see section~\ref{sec:gui:configuration:tools}).


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "guide"
%%% End: