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 \emph{user directory} for the account which is running
Stellarium. If the file is not found there, Stellarium looks in the
\emph{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,
\emph{screenshot save directory} and \emph{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{Mac OS X}
\label{sec:FilesAndDirectories:MacOSX}

\begin{description}
\item[installation directory] This is found inside the application
  bundle, \file{Stellarium.app}. See \emph{Inside Application
    Bundles}\footnote{\url{http://www.mactipsandtricks.com/articles/Wiley_HT_appBundles.lasso}}
  for more information.
\item[user directory] This is the sub-directory 
  \file{Library/Preferences/Stellarium/} (or \\
  \file{\textasciitilde{}/Library/Application\ Support/Stellarium} on
  newest versions of Mac OS X) 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{v.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 skycultures directory.
\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 and DE431 (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 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 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 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.

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 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.}.

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} Configuration File.


\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{v0.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 standard edition of Stellarium DSO catalog, see section \ref{sec:dso:catalog}), 
but an extended 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.6}}:

\noindent\begin{tabular}{lllr}
\toprule
\emph{Version}&\emph{Filename}& \emph{MD5 hash}& \emph{Size}\\\midrule
3.6; extended edition & \file{catalog.dat} &\texttt{ba67e8526c68d980c384a0b8fe39521b}& 28.3\,MB\\\bottomrule
\end{tabular}

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

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

\noindent\newFeature{v0.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}
from NASA's Jet Propulsion Laboratory (JPL)~\citep{DE43x}. The data files have to be
downloaded separately, and most users will likely not need them. DE430
provides highly accurate data for the years $+1550\ldots+2650$, while
DE431 covers years $-13000\ldots+17000$, which allows e.g.\ 
archaeoastronomical research on Mesolithic landscapes. Outside these
year ranges, positional computation falls back to VSOP87.

The integration of this feature is still somewhat experimental, and some other current 
approximations will 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{ftp://ssd.jpl.nasa.gov/pub/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\\\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:
\newpage
\begin{configfile}
[astro]
de430_path = C:/Astrodata/JPL_DE43x/linux_p1550p2650.430
de431_path = C:/Astrodata/JPL_DE43x/lnxm13000p17000.431
\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 both, preference will be given for DE430
if the 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 preferrably
should not connect directly to a GPS USB device, serial device,
bluetooth device, etc., but uses 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{http://catb.org/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{BlueNMEA} to provide
the NMEA strings.

\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 say the file
\file{my\_config.ini} in the current working directory.\\\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  & Over-rides 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      & The initial vertical field of view in degrees. \\\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]\\
-\/-angle-d3d9 or -9 & {[}none{]} & Force use Direct3D 9 for ANGLE OpenGL ES2 rendering engine.\footnotemark[1]\\
-\/-angle-d3d11      & {[}none{]} & Force use Direct3D 11 for ANGLE OpenGL ES2 rendering engine.\footnotemark[1]\\
-\/-angle-warp       & {[}none{]} & Force use the Direct3D 11 software rasterizer for ANGLE OpenGL ES2 rendering engine.\footnotemark[1]\\
-\/-mesa-mode or -m  & {[}none{]} & Use MESA as software OpenGL rendering engine.\footnotemark[1]\\
-\/-safe-mode or -s  & {[}none{]} & Synonymous to -\/-mesa-mode.\footnotemark[1]\\
-\/-compat33 or -C   & {[}none{]} & Request OpenGL 3.3 Compatibility Profile. May help for certain driver configurations. Mac?\\
-\/-fix-text or -t   & {[}none{]} & Alternative way of creating the Info text, required on some systems.\footnote{E.g., Raspberry Pi 2/3 with Raspbian Jessie and VC4 drivers from Mesa 11 (2016).}\\\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{v0.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{http://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 on the NVidia hardware. 
For permanent setting, use the NVidia configuration dialog to configure Stellarium explicitly to run always on the NVidia card.

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