ch_advanced_use.tex

% Status info:
% M. Gates	2006-2009
% A. Wolf	2011-2015
% ArdWar	2012
% B. Gerdes	2013
% TODO insert further additions from wiki?
% Content OK for 0.15+.
% GZ: typo&grammar check 20160329

\chapter{Files and Directories}
\label{sec:FilesAndDirectories}

\section{Directories}
\label{sec: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 \indexterm{user directory}\footnote{also called \indexterm{user data directory}} for the account which is running
Stellarium. If the file is not found there, Stellarium looks in the
\indexterm{installation directory}\footnote{The installation directory was
  referred to as the config root directory in previous versions of this
  guide}. Thus it is possible for Stellarium to be installed by 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,
\indexterm{screenshot save directory} and \indexterm{script save directory} vary
according to the operating system and installation options used. The
following sections describe the locations for various operating systems.

\subsection{Windows}
\label{sec:FilesAndDirectories:Windows}

\begin{description}
\item[installation directory] By default this is
  \file{C:\textbackslash{}Program\ Files\textbackslash{}Stellarium\textbackslash{}},
  although this can be adjusted during the installation process.
\item[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).

\begin{commands}
%APPDATA%\Stellarium\
%USERPROFILE%\Stellarium\
%HOMEDRIVE%\%HOMEPATH%\Stellarium\
%HOME%\Stellarium\
Stellarium's installation directory
\end{commands}

Thus, on a typical Windows Vista/7/10 system with user ``Bob
Dobbs'', the user directory will be:

\begin{commands}
C:\Users\Bob Dobbs\AppData\Roaming\Stellarium\
\end{commands}

The user data directory is unfortunately hidden by default. To make it accessible in the Windows file
explorer, open an \program{Explorer} window and select \menu{Organize... > Folder and
search options}. Make sure folders marked as hidden are now 
displayed. Also, deselect the checkbox to ``hide known file name
endings''.\footnote{This is a very confusing default setting and in fact
  a security risk: Consider you receive an email with some file
  \file{funny.png.exe} attached. Your explorer displays this as
  \file{funny.png}. You double-click it, expecting to open some image
  browser with a funny image. However, you start some unknown program
  instead, and running this \file{.exe} executable program may turn
  out to be anything but funny!}

\item[screenshot save directory] Screenshots will be saved to the
  \file{Pictures/Stellarium} directory, although this can be changed in the GUI 
  (see section~\ref{sec:gui:configuration:tools}) or with a command line option (see
  section~\ref{sec:CommandLineOptions}).
\end{description}

\subsection{macOS}
\label{sec:FilesAndDirectories:MacOSX}

\begin{description}
\item[installation directory] This is found inside the application
  bundle, \file{Stellarium.app}. See \emph{The Anatomy of macOS App 
  Bundles}\footnote{\url{https://www.maketecheasier.com/anatomy-macos-app-bundles/}}
  or \emph{Bundle Programming Guide}\footnote{\url{https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html}} 
  for more information.
\item[user directory] This is the sub-directory 
  \file{\textasciitilde{}/Library/Application\ Support/Stellarium} of the user's home
  directory.
\item[screenshot save directory] Screenshots are saved to the user's
  Desktop.
\end{description}

\subsection{Linux}
\label{sec:FilesAndDirectories:Linux}

\begin{description}
\item[installation directory] This is in the
  \file{share/stellarium} sub-directory of the installation prefix,
  i.e., usually \file{/usr/share/stellarium} or
  \file{/usr/local/share/stellarium/}.
\item[user directory] This is the \file{.stellarium} sub-directory of
  user's home directory, i.e.,
  \file{\textasciitilde{}/.stellarium/}. This is a hidden folder, so
  if you are using a graphical file browser, you may want to change
  its settings to ``display hidden folders''.
\item[screenshot save directory] Screenshots are saved to the user's
  home directory.
\end{description}

\subsection{Customized Location}
\label{sec:FilesAndDirectories:Custom}

Some users\newFeature{0.19.0} may prefer non-standard locations for
their own data, for example when the Windows \file{C:} drive (which
usually contains user data), or the Linux \file{/home} partition has
become too small to hold tens of high-resolution landscapes or
detailed 3D sceneries. You can move the entire directory elsewhere and
use an environment variable \texttt{STEL\_USERDIR} that contains the
pathname.

\section{Directory Structure}
\label{sec:FilesAndDirectories:DirectoryStructure}

Within the \emph{installation directory} and \emph{user directory}
defined in section~\ref{sec:Directories}, files are arranged in the
following sub-directories.

\begin{description}
\item[\file{landscapes/}] contains data files and textures used for
  Stellarium's various landscapes. Each landscape has its own
  sub-directory. The name of this sub-directory is called the
  \emph{landscape ID}, which is used to specify the default landscape in
  the main configuration file, or in script commands.
\item[\file{skycultures/}] contains constellations, common star names and
  constellation artwork for Stellarium's many sky cultures. Each culture
  has its own sub-directory in the \file{skycultures} directory.
\item[\file{scripts/}] contains your own scripts. These can be used to create
  complex demonstrations (see ch.~\ref{ch:scripting}). 
\item[\file{nebulae/}] contains data and image files for nebula textures.
  In the future Stellarium may be able to support multiple sets of nebula
  images and switch between them at runtime. This feature is not
  implemented for version~\StelVersion, although the directory structure is in
  place -- each set of nebula textures has its own sub-directory in the
  nebulae directory.
  %% TODO: Update this if no longer valid.
\item[\file{stars/}] contains Stellarium's star catalogues. In the
  future Stellarium may be able to support multiple star catalogues
  and switch between them at runtime. This feature is not implemented
  for version~\StelVersion, although the directory structure is in
  place -- each star catalogue has its own sub-directory in the stars
  directory.
  %% TODO: Update this if no longer valid. 
\item[\file{data/}] contains miscellaneous data files including fonts,
  solar system data, city locations, etc.
\item[\file{textures/}] contains miscellaneous texture files, such as the
  graphics for the toolbar buttons, planet texture maps, etc.
\item[\file{ephem/}] (optional) may contain data files for planetary
  ephemerides DE430, DE431, DE440 and DE441 (see~\ref{sec:ExtraData:ephemerides}).
\end{description}

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 recommended to add new landscapes or sky cultures 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, and 
updating Stellarium will not risk the loss of your own data. 


\section{The Logfile}
\label{sec:LogFile}

Stellarium reports various events and confirmations to a \indexterm{logfile}, \file{log.txt}, 
in the \emph{user directory}. This has the same content as you can see on the console 
on Linux when you start Stellarium on the command line. Normally you don't need to bother with its contents, 
however, if Stellarium behaves unexpectedly, crashes, or shows other problems, a quick look into this 
file may help to identify the problem. Also when you report a problem to the developers in the hope 
that they (we) can 'fix' anything, this logfile is an essential ingredient to your report. 
The logfile can also be displayed within the program: press \key{F1} to call the help panel, and select the Logfile tab. 


\section{The Main Configuration File}
\label{sec:ConfigurationFile}

The main \indexterm{configuration file} is read each time Stellarium starts, 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 each version. Some
settings, esp.\ color values for some lines, grids, etc.\ can only be
changed by directly editing the configuration file.\footnote{Color
  values can be edited interactively by the Text User Interface plugin
  (see~\ref{sec:plugins:TextUserInterface}).} This section describes
some of the settings a user may wish to modify in this way, and how to
do it.

The name of the configuration file is
\file{config.ini}\footnote{It is possible to specify a different name
  for the main configuration file using the \texttt{-\/-config-file}
  command line option. See section~\ref{sec:CommandLineOptions} Command 
  Line Options for details.}.
If the configuration file does not exist in the \emph{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~\ref{sec:FilesAndDirectories} Files and
Directories for the location of the user directory on your operating
system).


The configuration file is a regular text file, so all you need to edit
it is a text editor like \program{Notepad} on Windows, \program{Text Edit} on
the Mac, or \program{nano}/\program{vi}/\program{gedit}/\program{emacs}/\program{leafpad} 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 options and values may be found
in appendix~\ref{sec:config.ini}.


\section{Getting Extra Data}
\label{sec:ExtraData}

\subsection{More Stars}
\label{sec:ExtraData:stars}
Stellarium is packaged with over 600 thousand stars in the normal
program download, but much larger star catalogues may be downloaded
in the \emph{Tools} tab of the \emph{Configuration} dialog (\guibutton[0.25]{2}{btd_config.png} or
\key{F2}).

\subsection{More Deep-Sky Objects}
\label{sec:ExtraData:DSOs}

\noindent\newFeature{0.16.1}Stellarium is packaged with over 94 thousand deep-sky 
objects\footnote{Over 83 thousand deep-sky objects in version 0.16.0.} in the normal
program download (the \emph{standard edition} of Stellarium DSO catalog\footnote{The first 
number in the version of Stellarium DSO catalog meaning version of catalog structure 
and second number meaning version of data.}, see section \ref{sec:dso:catalog}), 
but an \emph{extended edition} of DSO catalog with over one million objects (up to $20.0^m$ for galaxies) may be downloaded
from Stellarium's Github website\footnote{\url{https://github.com/Stellarium/stellarium-data/releases/tag/dso-3.20}}:

\noindent\begin{tabular}{lllr}
\toprule
\emph{Version; Edition} & \emph{Filename} & \emph{MD5 hash} & \emph{Size}\\\midrule
3.20; extended & \file{catalog-3.20.dat} & \texttt{8b25343a5983ef5841cbc0b60e96f4dc} & 28MB\\\bottomrule
\end{tabular}

The file can be placed in a folder named \file{nebulae/default} inside the \emph{user directory}
(see section~\ref{sec:FilesAndDirectories:DirectoryStructure}).

\subsection{Alternative Planet Ephemerides: DE430, DE431, DE440, DE441}
\label{sec:ExtraData:ephemerides}

\noindent\newFeature{0.15.0}By default, Stellarium uses the \indexterm{VSOP87} planetary theory,
an analytical solution which is able to deliver planetary positions
for any input date~\citep{1988A&A...202..309B}. However, its use is recommended only for the year
range $-4000\ldots+8000$. Outside this range, it seems to be usable
for a few more millennia without too great errors, but with degrading accuracy. 
Likewise for the moon, Stellarium by default uses ELP~2000-82B~\citep{1982CeMec..26...63C, 1983A&A...124...50C, ELP2000-82B}.

Since v0.15.0 you can install extra data files which allow access to the
numerical integration runs \indexterm{DE430} and \indexterm{DE431} \citep{DE43x},
and meanwhile also \newFeature{0.21.2} \indexterm{DE440} and \indexterm{DE441} \citep{DE44x},
from NASA's Jet Propulsion Laboratory (JPL). The data files have to be
downloaded separately, and most users will likely not need them. DE430 and DE440
provide highly accurate data for the years $+1550\ldots+2650$, while
DE431 and DE441 covers years $-13000\ldots+17000$, which allows e.g.\ 
archaeoastronomical research on Mesolithic landscapes. (But see Appendix~\ref{ch:Accuracy}!) Outside these
year ranges, positional computation falls back to VSOP87.

Some current approximations may still lead to numerical data which differ slightly from best possible ephemerides.  
Please at least compare with JPL Horizons\footnote{\url{https://ssd.jpl.nasa.gov/horizons.cgi}} for dependable results.

To enable use of these data, download the files from
JPL\footnote{\url{https://ssd.jpl.nasa.gov/ftp/eph/planets/Linux/} (Also
  download from this directory if you are not running Linux!)}:

\noindent\begin{tabular}{lllr}
\toprule
\emph{Ephemeris}&\emph{Filename}& \emph{MD5 hash}& \emph{Size}\\\midrule
DE430& \file{linux\_p1550p2650.430}  &\texttt{707c4262533d52d59abaaaa5e69c5738}& 97.5\,MB\\
DE431& \file{lnxm13000p17000.431}    &\texttt{fad0f432ae18c330f9e14915fbf8960a}& 2.59\,GB\\
DE440& \file{linux\_p1550p2650.440}  &\texttt{9dc8a9cefd32b0090002407847e718ba}& 97.5\,MB\\
DE441& \file{linux\_m13000p17000.441}&\texttt{4e3b924463d17b68ec9c4a18240300cd}& 2.59\,GB\\\bottomrule
\end{tabular}


The files can be placed in a folder named \file{ephem} inside either
the \emph{installation directory} or the \emph{user directory}
(see \ref{sec:FilesAndDirectories:DirectoryStructure}). Alternatively,
if you have them already stored elsewhere, you may add the path to
\file{config.ini} like:
\begin{configfile}
[astro]
de430_path = C:/Astrodata/JPL_DE43x/linux_p1550p2650.430
de431_path = C:/Astrodata/JPL_DE43x/lnxm13000p17000.431
de440_path = C:/Astrodata/JPL_DE44x/linux_p1550p2650.440
de441_path = C:/Astrodata/JPL_DE44x/linux_m13000p17000.441
\end{configfile}

For fast access avoid storing them on a network drive or USB pendrive!

You activate use of either ephemeris in the \emph{Configuration} panel
(\key{F2}). If you activate more than one, preference will be given
for DE440 over DE441 if the simulation time allows it. Only if DE44x
are not enabled, DE430 is given preference over DE431 if simulation
time allows it.  Outside of the valid times, VSOP87 will always be
used.

\paragraph{Acknowledgement}
The optional use of DE430/431 has been supported by the ESA Summer of
Code in Space 2015 initiative.

\subsection{GPS Position}
\label{sec:ExtraData:GPS}

\noindent In the \emph{Location} panel (see
section~\ref{sec:gui:location}) you can receive your location from a
\indexterm{GPS} device.  \newFeature{0.16/0.18.1} The exact way to receive
GPS location depends on your operating system. 

\subsubsection{GPSD (Linux, Mac OS X only)}
\label{sec:ExtraData:GPS:GPSD}

On Linux, Mac-OS X and other Unixoid platforms, Stellarium preferably
should not connect directly to a GPS USB device, serial device,
bluetooth device, etc., but use a connection to the \program{gpsd}
daemon running on a computer in your network which provides GPS
services concurrently for any interested application. In most cases,
this will be a \program{gpsd} running on your localhost, receiving
data from some GPS device plugged in via USB.
Please follow instructions by the \program{gpsd}
authors\footnote{\url{https://gpsd.gitlab.io/gpsd/index.html}} to properly
configure this system daemon.  A few hints:
\begin{itemize}
\item On Ubuntu 16.04 and likely other systems, USB hotplug devices
  are handled by the \program{udev} daemon which detects newly
  plugged-in devices and creates device files in the \file{/dev}
  directory. Unfortunately, most GPS devices use the Prolific 2303
  chipset in their serial-to-USB converter and are identified as
  such, without other unique information like serial numbers. 
  This chipset is also used in other Serial-to-USB converter
  cables, and to avoid conflicts the according rule has been disabled
  by the release managers of Ubuntu.  In
  \file{/lib/udev/60-gpsd.rules}, find the commented line and
  re-activate it.

\item If you have such an USB GPS mouse and USB-to-serial converters
  for other purposes like for your telescope control, you must solve
  the ``\program{udev} crisis'' in some other way to get
  \program{gpsd} running. You may be able to find some property in
  your device to uniquely identify this device and write an
  \program{udev} rule to create the symlink in \file{/dev/gps0} to
  which \program{gpsd} can then connect.

\item You can also connect to another computer which runs
  \program{gpsd}. This could be a little Raspberry Pi computer which
  happens to be in your WiFi to allow localisation and time service.
 To configure this, you must manually edit
  \file{config.ini}. Find the \texttt{[gui]} section and edit
\begin{configfile}
[gui]
# These values are used on non-Windows systems 
# supporting GPSD
gpsd_hostname   = localhost
gpsd_port       = 2947 
\end{configfile}
Also, \program{gpsd} must be started with the \texttt{-G} parameter to
enable this.
\item Even your smartphone can be used as GPS data
  source\footnote{Thanks to user Caysho for this hint.}: Apps like
  \program{BlueNMEA} can provide these data for \program{gpsd}, but
  you must make sure to configure hostname/IP Address and port number
  correctly, for example
  \begin{commands}
 sudo gpsd -n -D8 -S 1001 tcp://192.168.1.101:4352
  \end{commands}
which means
\begin{description}
\item[-n] to start without a device connection
\item[-D8] maximum debug level. When it works, use what suits you
\item[-S 1001] provide service on port 1001
\item[tcp] Use this address:port combination to receive data from (IP of
  your smartphone, port shown on \program{BlueNMEA} screen).
\end{description}
\item In case you really don't want to use the \program{gpsd}, you can
  use a directly connected device, see below. This is however not
  recommended when you have \program{gpsd} available.
\end{itemize}


\subsubsection{NMEA Device}
\label{sec:ExtraData:GPS:NMEA}

This mode is primarily for Windows users, but also for Linux and Mac
users who don't want to use \program{gpsd}.

Virtually all GPS receivers are able to emit the standardized
\indexterm{NMEA}-0183 messages which encode time, position, speed,
satellite information and other data.  The standard originally
required connection settings of 4800\,baud, 8 bit, no parity, one stop
bit (8N1), however some devices come with faster transfer.

Compatible devices today are connected on a ``virtual COM port'' via
USB. Unfortunately the COM number seems to depend on the USB plug
where you attach the receiver.  You can identify the port name (COM3,
COM4, \ldots) in the Windows system configuration (Device Manager) or
with the software that came with your device.\footnote{On Linux, this
  may read \file{/dev/ttyUSB0}, \file{/dev/gps0} or similar.}

If this is the only serial device, Stellarium should automatically
connect to it regardless of configuration entries.  If you
have a device with non-standard baudrate or several serial devices on
serial ports (e.g., your telescope?), you must find out which serial port is
used by the GPS device and manually edit \file{config.ini}.  Find
the \texttt{[gui]} section and edit
\begin{configfile}
[gui]
# These values are used on Windows primarily.
gps_interface     = COM3
gps_baudrate      = 4800
\end{configfile}
From now on, always use the same USB plug configuration to connect GPS
and telescope.\footnote{Again, for Linux the port number is defined in
  order of hotplugging by \program{udev}. You should develop an
  \program{udev} rule which adds a unique name and use this. In this
  case, you may also need to add your user to the \texttt{dialout}
  group (or whichever group owns your serial port).  Better yet, use
  \program{gpsd} (see above).}

If GPS lookup fails, run Stellarium with the \texttt{--verbose} option and
see the logfile for diagnostic messages.

\paragraph{Bluetooth GPS} Most smartphones provide GPS and Bluetooth
hardware. You can install a virtual COM port in your Windows Bluetooth
settings and use a smartphone app like \program{Share
  GPS}\footnote{\url{https://play.google.com/store/apps/details?id=com.jillybunch.shareGPS}}
to provide the NMEA strings.

\paragraph{Windows location service} On Windows devices, you can get your location
using the Windows location service. The result depends on available
hardware and other settings, e.g. real GPS sensor or network and WiFi
detection.\footnote{\url{https://support.microsoft.com/en-us/windows/windows-location-service-and-privacy-3a8eee0a-5b0b-dc07-eede-2a5ca1c49088}}


\subsection{Modernized MESA3D libraries (Software OpenGL on Windows)}
\label{sec:ExtraData:Mesa}

Stellarium uses hardware-accelerated OpenGL for rendering. On very old Windows systems without dedicated graphics hardware, 
or in special circumstances like virtual machines, hardware accelerated graphics may not be available, 
and the \program{Mesa3D} software implementation of OpenGL is used. This can also be forced by the command-line option \command{-\/-mesa-mode}. 
Rendering the graphics without hardware acceleration is of course much slower than accelerated graphics, but it's surely better than nothing.

Qt's default Mesa library (Mesa 11) provides support for OpenGL~3.0 only. This prevents users of all versions from applying dithering in Mesa mode. 
Also the \program{ShowMySky} skylight model (see section~\ref{sec:skylight:ShowMySky}) is then not available.

We have replaced\newFeature{23.4} this by a version of Mesa~20 compiled by Federico Dossena\footnote{\url{https://fdossena.com/?p=mesa/index.frag}} which appears to be even a bit faster.

The \program{Mesa3D} project \footnote{\url{https://www.mesa3d.org/}} meanwhile (2023) provides at least OpenGL~4.5. 
If you wish to use more ``up to date'' precompiled binaries and have Administrator privileges on your Windows system, 
you can replace this library using the following steps to install inofficial builds\footnote{\url{https://github.com/pal1000/mesa-dist-win/}}. 
Note however that after this upgrade, the program runs with considerably ($\approx$35\%?) lower framerate. 
You must decide whether this is really beneficial in your situation. The libraries don't provide any additional graphics features that Stellarium makes use of.

\begin{itemize}
\item Download the latest ``release-msvc'' package as you need from \url{https://github.com/pal1000/mesa-dist-win/releases} and unpack it somewhere.
\item Copy \file{(x86|x64)/{libglapi.dll,libgallium\_wgl.dll,opengl32.dll}} to where the executable \file{stellarium.exe} is.
\item Delete the existing \file{opengl32sw.dll}
\item Rename the just-copied \file{opengl32.dll} to \file{opengl32sw.dll}.
\end{itemize}

\noindent Now running Stellarium in Mesa mode (with link from program menu or command line) should report to provide OpenGL~4.5.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Command Line Options}
%\label{command-line-options}
\label{sec:CommandLineOptions}

Stellarium's behaviour can be modified by providing parameters to the
program when it is called via the command line. See table for a full list:

\begin{longtable}{l|c|p{68mm}}\toprule
\emph{Option}         & \emph{Option Parameter} & \emph{Description}\\\midrule
-\/-help or -h        & {[}none{]}       & Print a quick command line help message, and exit. \\\midrule
-\/-version or -v     & {[}none{]}       & Print the program name and version information, and exit. \\\midrule
-\/-config-file or -c & config file name & Specify the configuration file name. The default value is \file{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 ``\file{.}'', which may be used to explicitly
                                           specify a file in the current directory or similar.

For example, using the option \texttt{-c\ my\_config.ini} would resolve to the file 
\file{\textless{}user\ directory\textgreater{}/my\_config.ini} whereas 
\file{-c\ ./my\_config.ini} can be used to explicitly point to the file
\file{my\_config.ini} in the current working directory.\\
-\/-log-file or -l   & log file name     & Specify the log file name. The default value is \file{log.txt}.

Any path is stripped from the filename. When a path is specified like \texttt{-l\ /mypath/my\_log.txt}, 
the file will be written to \file{\textless{}user\ directory\textgreater{}/my\_log.txt}\\\midrule
-\/-restore-defaults &  [none]    & Stellarium will start with the default configuration. 
                                    Note: The old configuration file will be overwritten. \\\midrule
-\/-user-dir         & path       & Specify the user data directory. \\
-\/-screenshot-dir   & path       & Specify the directory to which screenshots will be saved. \\\midrule
-\/-full-screen      & yes or no  & Overrides the full screen setting in the config file. \\\midrule
-\/-home-planet      & planet     & Specify observer planet (English name). \\
-\/-longitude        & longitude  & Specify latitude, e.g. +53d58'16.65" \\
-\/-latitude         & latitude   & Specify longitude, e.g. -1d4'27.48" \\
-\/-altitude         & altitude   & Specify observer altitude in meters. \\\midrule
-\/-list-landscapes  & {[}none{]} & Print a list of available landscape IDs and exit. \\
-\/-landscape        & landscape ID & Start using landscape whose ID matches the passed parameter (dir name of landscape). \\\midrule
-\/-sky-date         & date       & The initial date in \texttt{yyyymmdd} format. \\
-\/-sky-time         & time       & The initial time in \texttt{hh:mm:ss} format. \\\midrule
-\/-startup-script   & script name & The name of a script to run after the program has started. [\file{startup.ssc}] \\\midrule
-\/-fov              & angle (degrees) & The initial vertical field of view in degrees. \\\midrule
-\/-scale-gui        & scale factor & Scaling the GUI according to scale factor\\
-\/-gui-css style    & name       & Use \file{name.css} to define GUI style\\\midrule
-\/-projection-type  & ptype      & The initial projection type (e.g. \texttt{perspective}). \\\midrule
-\/-spout  or -S     & all or sky & Act as Spout sender (See section \ref{sec:CommandLineOptions:Special:Spout}).%
                                    \footnote{On Windows only}\footnote{This function requires running in OpenGL mode.}\\
-\/-spout-name       & name       & Use \texttt{name} as name of the Spout sender. Default name: \texttt{Stellarium}.\footnotemark[1]\\\midrule									
-\/-verbose          &            & Even more diagnostic output in logfile (esp.\ multimedia handling)\\
-\/-dump-opengl-details or -d     & {[}none{]} & Dump information about OpenGL support to logfile. 
                                                 Use this is you have graphics problems and want to send a bug report. \\\midrule
-\/-angle-mode or -a & {[}none{]} & Use ANGLE as OpenGL ES2 rendering engine (autodetect Direct3D version).\footnotemark[1]\footnote{Stellarium 0.* series only}\\
-\/-angle-d3d9 or -9 & {[}none{]} & Force use Direct3D 9 for ANGLE OpenGL ES2 rendering engine.\footnotemark[1]\footnotemark[3]\\
-\/-angle-d3d11      & {[}none{]} & Force use Direct3D 11 for ANGLE OpenGL ES2 rendering engine.\footnotemark[1]\footnotemark[3]\\
-\/-angle-warp       & {[}none{]} & Force use the Direct3D 11 software rasterizer for ANGLE OpenGL ES2 rendering engine.\footnotemark[1]\footnotemark[3]\\
-\/-mesa-mode or -m  & {[}none{]} & Use MESA as software OpenGL rendering engine.\footnotemark[1]\\
-\/-single-buffer    & {[}none{]} & Use single-buffering. This reportedly avoids screen blanking problems with some Intel GPUs. \\
-\/-opengl-compat or -C & {[}none{]} & Request OpenGL 3.3 Compatibility Profile. Might fix graphics problems in some driver configurations.\\
\bottomrule
\end{longtable}

\noindent \newFeature{0.15} If you want to avoid adding the same
switch every time when you start Stellarium from the command line, you
can also set an environment variable \file{STEL\_OPTS} with your
default options. 

\section{Examples}
\label{sec:CommandLineOptions:Examples}

\begin{itemize}
\item To start Stellarium using the configuration file,
  \file{configuration\_one.ini} situated in the user directory (use either of
  these):

\begin{commands}
stellarium --config-file=configuration_one.ini
stellarium -c configuration_one.ini
\end{commands}

\item To list the available landscapes, and then start using the
  landscape with the ID ``ocean''
\begin{commands}
stellarium --list-landscapes 
stellarium --landscape=ocean
\end{commands}
\end{itemize}

%% GZ found in 2015:
\noindent Note that console output (like \command{-\/-list-landscapes}) on Windows is not possible. 

\section{Special Options}
\label{sec:CommandLineOptions:Special}
\subsection{Spout}\newFeature{0.15.1} 
\label{sec:CommandLineOptions:Special:Spout}
Apart from stand-alone use, Stellarium can be used as multimedia source in larger installations, in museums or science exhibitions. 
\program{Spout}\footnote{\url{https://spout.zeal.co/}} is a technology which enables use of Stellarium's 
output window as texture in DirectX applications on Windows. Simply start Stellarium with 
the \texttt{-\/-spout=sky} command line option. (Currently \program{Spout} output is limited to the main window 
without GUI panels, but this may change in future versions.) 
Your master application must obviously embed a \program{Spout} receiver. 
The default name of the \program{Spout} sender is \texttt{Stellarium}. If you need more than one instance of Stellarium acting as source, 
you can use option \texttt{-\/-spout-name=StelSpout2} in addition to create another \program{Spout} sender without a name conflict. 
In such cases, it may be useful to also have separate user data directories and use option \texttt{-\/-user-dir}. 

This mode does not work in ANGLE mode and requires modern graphics hardware with the \texttt{WGL\_NV\_DX\_interop} 
driver extension running in OpenGL mode. Some Nvidia GPUs work without this extension listed explicitly. 
On a notebook with Nvidia Optimus technology, make sure to launch Stellarium \emph{and} \program{SpoutReceiver} 
(or your target application) on the Nvidia hardware. 
For permanent setting, use the Nvidia configuration dialog to configure Stellarium and the target application explicitly to run always on the Nvidia card.

Note that Spout use disables any multisampling setting (see Appendix~\ref{sec:config.ini:video}). 

\subsection{Environment Variables}
\label{sec:Environment}

Some command-line options can be set permanently by storing them into
environment variables. How to set them depends on the respective
operating system. Calling the respective options on the command line
still overrides an environment variable (apart from
\texttt{STEL\_OPTS}).

This may be especially helpful on Windows systems with older graphics
cards which may not fully be compatible with OpenGL. Here we recommend
you either use the program links using the ANGLE-related options, or
you can set the environment variable once and forget about the
problems.

\begin{description}
\item[STEL\_OPTS] may contain a default commandline with options in the syntax of the table above.
\item[STEL\_USERDIR] may contain the path to a user data directory
  deviating from the default (see section \ref{sec:Directories}).
\item[QT\_OPENGL]\footnote{Windows only} May be one of \texttt{desktop} (native OpenGL for your GPU, recommended),
  \texttt{angle}\footnote{Stellarium 0.* series only} or \texttt{software}. The last activates pure software rendering using the MESA OpenGL library. Note that command line options take precedence over this environment variable.
\item[QT\_ANGLE\_PLATFORM]\footnote{Windows and Stellarium 0.* series only} May be one of \texttt{d3d9} (DirectX~9) or \texttt{d3d11} (DirectX~11),
  or \texttt{warp} for another software-only solution. Note that command line options take precedence over this environment variable.
\end{description}

\subsection{Customized GUI Colors}
\label{sec:CommandLineOptions:Special:CSS}

Some users have difficulties to read Stellarium's rather dark user
interface. Some screens may be too dark, or environments too
bright. Others find it is still too bright, and they would prefer a
real ``dark mode''. To allow this, you can create and load your own alternative style files.

The appearance of the windows, buttons etc.\ is governed by a CSS
(Cascaded Style Sheet) file. It certainly requires some knowledge and
guessing to edit your own, but there is enough help available
online. You can find the CSS files in Stellarium's Github site%
\footnote{\url{https://github.com/Stellarium/stellarium/blob/stellarium-stable/data/gui/normalStyle.css} and
  \url{https://github.com/Stellarium/stellarium/blob/stellarium-stable/data/gui/normalHtml.css}}.


Copy them into your user directory
and rename to e.g. \file{myOwnGreatStyle.css}. Edit numbers, but do
not change the item names! Then you can either launch Stellarium with
the added command line option like
\begin{commands}
  stellarium --gui-css myOwnGreatStyle
\end{commands}
or you could also use the scripting option (see chapter~\ref{ch:scripting}):
\begin{script}
  core.setGuiStyle("MyOwnGreatStyle");
\end{script}
To go back to Stellarium's default, just use
\begin{script}
  core.setGuiStyle("default");
\end{script}

If link colors in text panels are now difficult to read, copy
\file{normalHtml.css} from Github to
\file{MyOwnGreatStyleHtml.css} and modify to your taste.

Note that, as Stellarium evolves, these files also may change from
version to version. We cannot give any guarantees that one customized
file will work without adaptation on later or earlier versions of Stellarium.

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