plg_interfaces.tex

%% Part of Stellarium User Guide
%% Status: 2015-12-30 Some parts collected from wiki.
%%         2016-04-05 GZ changed to have 1 chapter per plugin for a better structure. This file may be split up later. 
%%         2016-04-16 split plugin part to topical chapters.

\chapter{Interface Extensions}
\label{ch:plugins:Interfaces}

Most users will soon be familiar with the usual user interface. A few
plugins are available which extend the regular user interface with a
few small additions which are presented first.  However, some
applications and installations of Stellarium require completely
different user interfaces. Mostly, these serve to avoid showing the
user interface panels to an audience, be that in your astronomy club
presentations, a domed planetarium or in a museum installation.


\section{Angle Measure Plugin}
\label{sec:plugins:AngleMeasure}

\begin{quotation}\small
\noindent\emph{goes misty eyed}\\ 
I recall measuring the size of the Cassini Division when I was a student.
It was not the high academic glamor one might expect\ldots It was cloudy\ldots
It was rainy\ldots The observatory lab had some old scopes set up at one
end, pointing at a \emph{photograph} of Saturn at the other end of the
lab. We measured. We calculated. We wished we were in Hawaii. A picture
is worth a thousand words.
\end{quotation}

%\url{http://porpoisehead.net/images/plugin-angle-measure.jpg}

\noindent The Angle Measure plugin is a small tool which is used to measure the
angular distance between two points on the sky. 


%\subsection{Using the plugin}
%\label{sec:plugins:AngleMeasure:using}

\begin{enumerate}
\item Enable the tool by clicking the tool-bar button, or by pressing
  \key{\ctrl+A}. A message will appear at the bottom of the screen to
  tell you that the tool is active.
\item Drag a line from the first point to the second point using the
  left mouse button
\item To clear the measurement, click the right mouse button
\item To deactivate the angle measure tool, press the tool-bar button
  again, or press \key{\ctrl+A} on the keyboard.
\end{enumerate}

\noindent In the configuration dialog, you can configure if you want to have
distances given on the rotating sphere, or in horizontal
(alt-azimuthal) coordinates. You can also link one point to the
resting horizon, the other to the sky and observe how angles change.

\newpage

\section{Compass Marks Plugin}
\label{sec:plugins:CompassMarks}

%\url{http://porpoisehead.net/images/plugin-compass-marks.jpg}

Stellarium helps the user get their bearings using the cardinal point
feature -- the North, South, East and West markers on the horizon.
Compass Marks takes this idea and extends it to add markings every few
degrees along the horizon, and includes compass bearing values in
degrees.

When activated (see section~\ref{sec:Plugins:EnablingPlugins}), there
is a tool bar button \guibutton{0.6}{bt_compass_off.png} for toggling the
compass markings.  Note that when you enable compass marks, the
cardinal points will be turned off.

\begin{figure}[ht]\centering
\includegraphics[width=\textwidth]{compass-marks-plugin.png}
\caption{Markings of Compass Marks Plugin}
\label{fig:plugins:CompassMarks}
\end{figure}

%% TODO/FIXME?: The following is not true for current pre-0.15:
%You can have both active at once, but there is a small
%bug which means you have to press \key{Q} \emph{two times} to
%re-enable cardinal points after enabling the compass markings.


\newpage
\section{Equation of Time Plugin}
\label{sec:plugins:EquationOfTime}

%% The figure just reproduces most of the text. I (GZ) regard it not so necessary. 
%\begin{figure}[h]
%\includegraphics[width=\textwidth]{EquationOfTime-plugin.jpg}
%\caption{Interface of Equation of Time plugin}
%\label{fig:EqOfTime}
%\end{figure}

\begin{figure}[h]\centering
\ifpdf
\includegraphics[width=.42\textwidth]{GZ_analemma_p1000}
\includegraphics[width=.42\textwidth]{GZ_analemma_p2000}
\else
\includegraphics[width=.42\textwidth]{GZ_analemma_p1000.png}
\includegraphics[width=.42\textwidth]{GZ_analemma_p2000.png}
\fi
\caption{Figure-8 plots for Equation of Time, for years 1000 (left)
  and 2000 (right). These plots, often found on sundials, link solar
  declination (vertical axis) and its deviation at mean noon from the
  meridian, in minutes. Labeled dots indicate when the sun entered the
  respective Zodiacal sign (30\degree section of the
  ecliptic). Figures by Georg Zotti.}
\label{fig:EqOfTime}
\end{figure}


\noindent The Equation of Time plugin shows the solution of the equation of time. % (Fig.~\ref{fig:EqOfTime}).
This describes the discrepancy between two kinds of
solar time:
\begin{description}
\item[Apparent solar time] directly tracks the motion of the sun. Most sundials show this time.
\item[Mean solar time] tracks a fictitious ``mean'' sun with noons 24 hours apart. 
\end{description}

There is no universally accepted definition of the sign of the
equation of time. Some publications show it as positive when a sundial
is ahead of a clock; others when the clock is ahead of the sundial. In
the English-speaking world, the former usage is the more common, but
is not always followed. Anyone who makes use of a published table or
graph should first check its sign usage.

If enabled (see section~\ref{sec:Plugins:EnablingPlugins}), click on
the Equation of Time button \guibutton{0.6}{bt_EquationOfTime_72dpi.png}
on the bottom toolbar to display the value for the equation of time on
top of the screen.


\subsection{Section \big[EquationOfTime\big] in config.ini file}
%\label{sec:plugins:EquationOfTime:configuration}

You can edit \file{config.ini} file by yourself for changes of the
settings for the Equation of Time plugin -- just make it carefully!

\noindent%
\begin{tabularx}{\textwidth}{l|l|X}\toprule
\emph{ID}            & \emph{Type} & \emph{Description}\\\midrule
enable\_at\_startup        & bool  & Display solution of the equation of time at startup of Stellarium\\%\midrule
flag\_use\_ms\_format      & bool  & Set format for the displayed solution -- minutes and seconds or decimal minutes\\%\midrule
flag\_use\_inverted\_value & bool  & Change sign of the equation of time \\%\midrule
flag\_show\_button         & bool  & Show the tool's button on the bottom toolbar\\%\midrule
text\_color                & R,G,B & Font color for the displayed solution of the equation of time\\%\midrule
font\_size                 & int   & Font size for the displayed solution of the equation of time \\\bottomrule
\end{tabularx}



\newpage

\section{Field of View Plugin}
\label{sec:plugins:FieldOfView}

\begin{figure}[ht]\centering
\includegraphics[trim=0 55 0 0,clip,width=.65\textwidth]{FOV-plugin.jpg}
\caption{Configuration dialog of Field of View plugin}
\label{fig:plugins:FieldOfView}
\end{figure}

\noindent By default Stellarium uses smooth zooming via mouse wheel or
keyboard shortcuts. Some users may want stepwise zooming to fixed
values for field of view like in the \program{Cartes du
  Ciel}\footnote{SkyChart / Cartes du Ciel planetarium:
  \url{http://www.ap-i.net/skychart/en/start}} planetarium program,
and this plugin provides this feature. You can edit values and use the
keyboard for quick-setting of FOV. All values in degrees.

%\section{Using the Field of View plugin}
%\label{sec:plugins:FieldOfView:using}

\begin{enumerate}
\item Enable the tool by configuring it to ``Load at startup''.
\item Press shortkeys for quick changes of FOV.
\end{enumerate}

\subsection{Section \big[FOV\big] in config.ini file}
%\label{sec:plugins:FieldOfView:configuration}

You can configure the plugin with its dialog (Fig.~\ref{fig:plugins:FieldOfView}) or edit
\file{config.ini} file by yourself for changes of the settings for the
Field of View plugin -- just make it carefully!

\begin{center}
\begin{tabular}{l|l|r|l}\toprule
\emph{ID} & \emph{Type} & \emph{Default} & \emph{Description}\\\midrule
fov\_quick\_0  & float & 0.5& Value of FOV for the shortcut \key{\ctrl+\Alt+0} \\%\midrule
fov\_quick\_1  & float &180 & Value of FOV for the shortcut \key{\ctrl+\Alt+1} \\%\midrule
fov\_quick\_2  & float & 90 & Value of FOV for the shortcut \key{\ctrl+\Alt+2} \\%\midrule
fov\_quick\_3  & float & 60 & Value of FOV for the shortcut \key{\ctrl+\Alt+3} \\%\midrule
fov\_quick\_4  & float & 45 & Value of FOV for the shortcut \key{\ctrl+\Alt+4} \\%\midrule
fov\_quick\_5  & float & 20 & Value of FOV for the shortcut \key{\ctrl+\Alt+5} \\%\midrule
fov\_quick\_6  & float & 10 & Value of FOV for the shortcut \key{\ctrl+\Alt+6} \\%\midrule
fov\_quick\_7  & float &  5 & Value of FOV for the shortcut \key{\ctrl+\Alt+7} \\%\midrule
fov\_quick\_8  & float &  2 & Value of FOV for the shortcut \key{\ctrl+\Alt+8} \\%\midrule
fov\_quick\_9  & float &  1 & Value of FOV for the shortcut \key{\ctrl+\Alt+9} \\\bottomrule
\end{tabular}
\end{center}

\newpage

\section{Pointer Coordinates Plugin}
\label{sec:plugins:PointerCoordinates}


\begin{figure}[th]\centering
\includegraphics[width=.55\textwidth]{PointerCoordinates-plugin.jpg}
\caption{Interface of Pointer Coordinates plugin}
\label{fig:PointerCoordinates}
\end{figure}

\noindent The Pointer Coordinates plugin shows the coordinates of the mouse pointer.
If enabled, click on the plugin button \guibutton{0.6}{bt_PointerCoordinates_Off.png} on the bottom toolbar to display the coordinates of the mouse pointer.

\subsection{Section \big[PointerCoordinates\big] in config.ini file}
%\label{sec:plugins:PointerCoordinates:configuration}

You can edit \file{config.ini} file by yourself for changes of the
settings for the Pointer Coordinates plugin -- just make it carefully!

\begin{longtable}{l|l|p{83mm}}\toprule
\emph{ID}              & \emph{Type} & \emph{Description}\\\midrule
enable\_at\_startup         & bool   & Enable displaying mouse pointer coordinates at program startup\\%\midrule
flag\_show\_button          & bool   & Show the plugin's tool button on the bottom toolbar\\%\midrule
text\_color                 & R,G,B  & Color for coordinates text of the mouse pointer \\%\midrule
font\_size                  & int    & Font size for the displayed mouse pointer coordinates  \\%\midrule
current\_displaying\_place  & string & Specifies the place of displaying coordinates of the mouse pointer. 
                                       \textit{Possible values}: \keymap{TopRight}, \keymap{TopCenter}, 
									   \keymap{RightBottomCorner}, \keymap{Custom}. 
									   \textit{Default value}: \keymap{TopRight}. \\%\midrule
custom\_coordinates        & int,int & Specifies the screen coordinates of the custom place for displaying coordinates of the mouse pointer \\%\midrule
current\_coordinate\_system & string & Specifies the coordinate system. \textit{Possible values}: 
                                       \keymap{RaDecJ2000}, \keymap{RaDec}, \keymap{HourAngle}, \keymap{Ecliptic}, 
									   \keymap{AltAzi}, \keymap{Galactic}. 
									   \textit{Default value}: \keymap{RaDecJ2000}. \\%\midrule
flag\_show\_constellation  & bool    & Add the 3-letter IAU\index{IAU} abbreviation for the constellation of the 
                                       mouse pointer location \citep{1987PASP...99..695R}.\\%\midrule
flag\_show\_crossed\_lines & bool    & Show crossed lines under mouse cursor.\\\bottomrule
\end{longtable}




\newpage

\section{Text User Interface Plugin}
\label{sec:plugins:TextUserInterface}

%\url{http://porpoisehead.net/images/plugin-tui.jpg}

This plugin re-implements the ``TUI'' of the pre-0.10 versions of
Stellarium, an unobtrusive menu used primarily by planetarium system
operators to change settings, run scripts and so on.

Given that color configuration for lines and texts cannot be found
elsewhere, an interesting part for general use (at least for extended
configuration sessions) is the way to interactively select colors in
this menu.

A full list of the commands for the TUI plugin is
given in section~\ref{sec:plugins:TUI:commands}. 

\subsection{Using the Text User Interface}
\label{sec:plugins:TUI:using}

\begin{enumerate}
\item Activate the text menu using the \key{\Alt+T} key.\footnote{This
    used to be hard-coded to \key{M} before version 0.15, but
    \key{\Alt+T} is better to remember as it runs parallel with
    \key{\ctrl+T} for switching the GUI panels, and frees up \key{M}
    for the Milky Way. The \key{\Alt+T} keybinding is hardcoded, i.e.,
    cannot be reconfigured by the user, and should not be used for
    another function.}
\item
  Navigate the menu using the cursors keys.
\item
  To edit a value, press the right cursor until the value you wish to
  change it highlighted with \textgreater{} and \textless{} marks, e.g.\
  \textgreater{}3.142\textless{}. Then press the cursor keys \keys{\arrowkeyup} and \keys{\arrowkeydown} to
  change the value. You may also type in a new value with the other keys
  on the keyboard.
\end{enumerate}

%% List complete as of 2016-04-26. 

\subsection{TUI Commands}
\label{sec:plugins:TUI:commands}
\begin{longtable}{l|p{45mm}|p{85mm}}
\toprule
1   & Location & (menu group)\\%\midrule
1.1 & Latitude & Set the latitude of the observer in degrees\\%\midrule
1.2 & Longitude & Set the longitude of the observer in degrees\\%\midrule
1.3 & Altitude & Set the altitude of the observer in meters\\%\midrule
1.4 & Solar System Body & Select the solar system body on which the observer is\\\midrule
2   & Set Time & (menu group)\\%\midrule
2.1 & Current date/time & Set the time and date for which Stellarium will generate the view\\%\midrule
%2.2 & Set Time Zone & Set the time zone. Zones are split into continent or region, and then by city or province\\\midrule
%2.3 & Days keys & The setting ``Calendar'' makes the \key{-}, \key{=}, \key{[}, \key{]} keys change the date value by calendar days (multiples of 24 hours). 
%                  The setting ``Sidereal day'' changes these keys to change the date by sidereal days\\\midrule
2.2 & Set Time Zone & (disabled in 0.15)\\
2.3 & Days keys & (disabled in 0.15)\\
2.4 & Startup date/time preset & Select the time which Stellarium starts with (if the ``Sky Time At Start-up'' setting is ``Preset Time''\\%\midrule
2.5 & Startup date and time & The setting ``system'' sets Stellarium's time to the computer clock when Stellarium runs. 
                                 The setting ``preset'' selects a time set in menu item ``2.4 - Startup date/time preset''\\%\midrule
2.6 & Date Display Format & Change how Stellarium formats date values. ``system\_default'' takes the format from the computer settings, 
                            or it is possible to select ``yyyymmdd'', ``ddmmyyyy'' or ``mmddyyyy'' modes\\%\midrule
2.7 & Time Display Format & Change how Stellarium formats time values. ``system\_default'' takes the format from the computer settings, 
                            or it is possible to select ``24h'' or ``12h'' clock modes\\\midrule
3    & General      & (menu group)\\%\midrule
3.1  & Starlore     & Select the sky culture to use (changes constellation lines, names, artwork)\\%\midrule
3.2  & Sky Language & Change the language used to describe objects in the sky\\%\midrule
3.3  & App Language & Change the application language (used in GUIs) \\\midrule
4    & Stars          & (menu group)\\%\midrule
4.1  & Show stars     & Turn on/off star rendering\\%\midrule
4.2  & Relative Scale & Change the relative brightness of the stars. Larger values make bright stars much larger.\\%\midrule
4.3  & Absolute Scale & Change the absolute brightness of the stars. Large values show more stars. Leave at 1 for realistic views. \\%\midrule
4.4  & Twinkle        & Sets how strong the star twinkling effect is - zero is off, the higher the value the more the stars will twinkle.\\\midrule
5    & Colors                      & (menu group) change color/brightness of the\ldots\\%\midrule
5.1  & Constellation lines         & constellation lines\\%\midrule
5.2  & Constellation labels        & labels used to name stars\\%\midrule
5.3  & Art brightness              & constellation art\\%\midrule
5.4  & Constellation boundaries    & constellation boundary lines\\%\midrule
5.5  & Cardinal points             & cardinal points markers\\%\midrule
5.6  & Planet labels               & labels for planets\\%\midrule
5.7  & Planet orbits               & orbital guide lines for planets\\%\midrule
5.8  & Planet trails               & planet trails lines\\%\midrule
5.9  & Meridian Line               & meridian line\\%\midrule
5.10 & Azimuthal Grid              & lines and labels for the azimuthal grid\\%\midrule
5.11 & Equatorial Grid             & lines and labels for the equatorial grid\\%\midrule
5.12 & Equatorial J2000 Grid       & lines and labels for the equatorial J2000.0 grid\\%\midrule
5.13 & Equator Line                & equator line\\%\midrule
5.14 & Ecliptic Line               & ecliptic line\\%\midrule
5.15 & Ecliptic Line (J2000)       & J2000 ecliptic line\\%\midrule
5.16 & Nebula names                & labels for nebulae\\%\midrule
5.17 & Nebula hints                & circles  used to mark positions of unspecified nebulae\\%\midrule
5.18 & Galaxy hints                & ellipses used to mark positions of galaxies\\%\midrule
5.19 & Bright nebula hints         & squares  used to mark positions of bright nebulae\\%\midrule
5.20 & Dark nebula hints           & squares  used to mark positions of dark nebulae\\%\midrule
5.21 & Clusters hints              & symbols  used to mark positions of clusters\\%\midrule
5.22 & Horizon line                & horizon line\\%\midrule
5.23 & Galactic grid               & galactic grid\\%\midrule
5.24 & Galactic equator line       & galactic equator line\\%\midrule
5.25 & Opposition/conjunction longitude line  & opposition/conjunction line\\
5.26 & Sky background              & sky background. Note that anything but black is only useful for artistic works.\\\midrule
6    & Effects & (menu group)\\%\midrule
6.1  & Light Pollution & Changes the intensity of the light pollution (see Appendix~\ref{ch:BortleScale} Bortle Scale index)\\%\midrule
6.2  & Landscape       & Select the landscape which Stellarium draws when ground drawing is enabled. Press \key{\return} to activate.\\%\midrule
6.3  & Setting Landscape Sets Location & If ``Yes'' then changing the landscape will move the observer location to the location for that landscape (if one is known). 
                                         Setting this to ``No'' means the observer location is not modified when the landscape is changed.\\%\midrule
6.4  & Auto zoom out returns to initial \ldots view & Changes the behaviour when zooming out from a selected object.
                                                      When set to ``Off'', selected object will stay in center.
                                                      When set to ``On'', view will return to startup view. \\%\midrule
6.5  & Zoom Duration              & Sets the time for zoom operations to take (in seconds)\\%\midrule
6.6  & Milky Way intensity        & Changes the brightness of the Milky Way\\%\midrule
6.7  & Zodiacal light intensity   & Changes the brightness of the Zodiacal light\\\midrule
%6.6 & Nebula label frequency     & Changes the magnitude limit for labelling of nebulae\\\midrule
%6.6 & Nebula label frequency     & (not active) \\\midrule
%6.8 & Cursor Timeout             & Sets the number of seconds of mouse inactivity before the cursor vanishes\\\midrule
7    & Scripts                    & (menu group)\\%\midrule
7.1  & Run local script           & Run a script from the scripts sub-directory of the User Directory or Installation Directory 
                                   (see section~\ref{sec:FilesAndDirectories} (Files and Directories))\\%\midrule
7.1  & Stop running script        & Stop execution of a currently running script \\\midrule
%7.2 & CD/DVD Script              & Run a script from a CD or DVD (only used in planetarium set-ups)\\\midrule
8    & Administration             & (menu group)\\%\midrule
8.1  & Load default configuration & Reset all settings according to the main configuration file\\%\midrule
8.2  & Save current configuration & Save the current settings to the main configuration file\\%\midrule
8.3  & Shutdown                   & Emits a command configured in \\\midrule
\end{longtable}


\subsection{Section \big[tui\big] in config.ini file}
%\label{sec:plugins:TUI:configuration}

The section in \file{config.ini} for this plugin is named only \texttt{[tui]} for historical reasons. As always, be careful when editing!

\noindent%
\begin{tabularx}{\textwidth}{l|l|X}\toprule
\emph{ID}                   & \emph{Type} & \emph{Description}\\\midrule
tui\_font\_color                  & R,G,B & Font color for TUI text \\%\midrule
tui\_font\_size                   & int   & Font size for the TUI \\%\midrule
flag\_show\_gravity\_ui           & bool  & Bend menu text around the screen center. 
                                            May be useful in planetarium setups, and should then be used together with ``Disc viewport'' 
                                            in the configuration menu (see~\ref{sec:gui:configuration:tools}). \\%\midrule
flag\_show\_tui\_datetime         & bool  & Show date and time in lower center.\\%\midrule
flag\_show\_tui\_short\_obj\_info & bool  & Show some object info in lower right, or (in planetarium setups with 
                                            ``Disc viewport'' active,) wrapped along the outer circle border. \\%\midrule
admin\_shutdown\_cmd              & string & executable command to shutdown your system. 
                                            Best used on Linux or Mac systems. E.g.\ \command{shutdown -h now}\\\bottomrule
\end{tabularx}



\newpage
\section{Remote Control Plugin}
\label{sec:plugin:RemoteControl}

The Remote Control plugin enables the user to control Stellarium through an external web 
interface using a standard web browser like Firefox or Chrome, instead of using 
the main GUI. This works on the same computer Stellarium runs as well as over 
the network. Even more, multiple ``remote controls'' can access the same 
Stellarium instance at the same time, without getting in the way of each other. 
Apart from system configuration options, most of the functionality the main interface 
provides is available through it \citep{Zotti-etal:SEAC2016}. 

The plugin may be most useful for presentation scenarios, hiding the GUI from the 
audience and allowing the presenter to change settings on a separate monitor 
without showing distracting dialog windows. It also allows to start and stop 
scripts remotely. 

Because the web interface can be customized (or completely 
replaced) with some knowledge of HTML, CSS and JavaScript, another possibility 
is a kiosk mode, where untrusted users can execute a variety of predefined 
actions (like starting recorded tours) without having access to all Stellarium 
settings. The web API can also be accessed directly (without using a browser 
and the HTML interface), allowing control of Stellarium with external programs 
and scripts using HTTP calls like with the tools \file{wget} and \file{curl}.

This plugin allows also interfacing other programs with Stellarium. 

\subsection{Using the plugin}
\label{sec:plugins:RemoteControl:using}

\begin{figure}[h]
\centering\includegraphics[width=\columnwidth]{remote_web.png}
\caption{The default remote control web interface}
\label{fig:plugins:RemoteControl:using}
\end{figure}

After enabling the plugin, you can set it up through the configuration dialog. 
You can configure it to start the web server automatically whenever Stellarium starts 
or manually start/stop the server using the ``Server enabled'' checkbox or the 
button \guibutton{0.6}{remote.png} in the toolbar.

The plugin starts an HTTP server on the specified port. The default port is 
8090, so you should reach the remote control after enabling it by starting 
a web browser on the same computer and entering \url{http://localhost:8090} in the 
address bar. When trying to access the remote control from another computer, 
you need the IP address or the hostname of the server on which Stellarium runs. 
On a small tablet, you may want to use \url{http://myserver:8090/tablet7in.html} instead.

The plugin shows the locally detected address, but depending on your network or 
if you need external access you might need to use a different one 
--- contact your network administrator if you need help with that.

\noindent The access to the remote control may optionally be restricted with a simple 
password.

\textbf{Warning:} \emph{currently no network encryption is used, meaning that 
an attacker having access to your network can easily find out the password by 
waiting for a user entering it. Access from the Internet to the 
plugin should generally be restricted, except if countermeasures such as VPN 
usage are taken! If you are in a home network using NAT (network access 
translation), this should be enough for basic security except if port 
forwarding or a DMZ is configured.}

\subsection{Remote Control Web Interface}
\label{sec:plugins:RemoteControl:webinterface}


If you are familiar with the main Stellarium interface, you should easily find 
your way around the web interface. 
The remote control automatically uses the same language as set in the main program. 
Tabs at the top allow access to different settings and controls. 

\begin{description}
\item[Main] Contains the time controls and most of the buttons of the 
main bottom toolbar. An additional control allows moving the view like when 
dragging the mouse or using the arrow keys in Stellarium, and a slider enables 
the changing of the field of view. There are also buttons to quickly execute 
time jumps using the commonly used astronomical time intervals.
\item[Selection] Allows searching and selecting objects like in \autoref{sec:gui:search}. 
SIMBAD search is also supported. Quick select buttons are available for the 
primary solar system objects. It also displays the information text for current 
selection.
\item[Sky] Settings related to the sky display as shown in the ``View'' dialog 
as shown in \autoref{sec:gui:view:sky}.
\item[DSO] The deep-sky object catalog, filter and display settings like in 
\autoref{sec:gui:view:markings}.
\item[Landscape] Changing and configuring the background landscape, see 
\autoref{sec:gui:view:landscape}
\item[Actions and scripts] Lists all registered actions, and allows starting 
and stopping of scripts (\autoref{ch:scripting}). If there is no button for the 
action you want in another tab, you can find all actions which can be 
configured as a keyboard shortcut (\autoref{sec:gui:configuration}) here.
\item[Location] Allows changing the location, like in 
\autoref{sec:gui:location}. Custom location saving is currently not 
supported.
\item[Projection] Switch the projection method used, like \autoref{sec:gui:view:markings}.
\end{description}

\subsection{Remote Control Commandline API}
\label{sec:plugins:RemoteControl:CLI}

Apart from retrieving quick object info in your browser with e.g.\ \url{http://localhost:8090/api/objects/info?format=json&name=Sun},
it is also possible to send commands via command line\footnote{%
  Depending on your operating system or command shell,
  you may have to use double quotes in the \texttt{-\/-data} argument to \command{curl}.}%
, e.g.,

\begin{commandsScr}
wget -q --post-data 'id=show.ssc' http://stella:8090/api/scripts/run >/dev/null 2>&1
curl --data 'id=myScript.ssc' http://localhost:8090/api/scripts/run >/dev/null 2>&1
curl -d     'id=myScript.ssc' http://localhost:8090/api/scripts/run >/dev/null 2>&1
curl -d 'id=LandscapeMgr.fogDisplayed&value=false' \ 
      http://localhost:8090/api/stelproperty/set 
\end{commandsScr}
This allows triggering automatic show setups for museums etc.\ via  some centralized schedulers like \command{cron}.

% TODO: List all available commands with examples here?
To get a complete pretty-printed list of properties, use:
\begin{commandsScr}
curl -G -d 'id=propId=-1&actionId=-2' http://localhost:8090/api/main/status | \
     python -m json.tool 
\end{commandsScr} 

  
\subsection{Developer information}
\label{sec:plugins:RemoteControl:developer}

If you are a developer and would like to add functionality to the Remote 
Control API, customize the web interface or access the API through another 
program, further information can be found in the plugin's 
developer documentation\footnote{\url{http://stellarium.org/doc/head/remoteControlDoc.html}}.

This plugin was created by Florian Schaukowitsch in the 2015 campaign of the 
\href{http://sophia.estec.esa.int/socis/}{ESA Summer of Code in Space} programme. 


\newpage
\section{Remote Sync Plugin}
\label{sec:plugin:RemoteSync}

\newFeature{0.16.0}%
The Remote Sync plugin enables setups which connect several instances of
Stellarium running on a network. This may be useful in installations where one
presenter wants to allow a larger audience to follow the actions on several
dim screens (e.g., when you need to avoid a projector's bright light in a 
public observatory). The actions 
performed on a ``master'' instance, which acts as a server, are automatically 
replicated on all connected clients. These clients may run on the same device 
the server runs, or may access the server over a network.

The plugin is still quite experimental, but is provided for testing purposes.
You can configure it through the standard plugin settings dialog 
(\autoref{fig:plugins:RemoteSync:settings}). One Stellarium instance
can either run in the server mode or connect to an existing server as a client.
A custom TCP protocol is used for the connection. The port used by the server is
configurable, and the clients must know the IP address or host name and the port
of the server.

\begin{figure}[htb]
	\centering\includegraphics[width=\columnwidth]{remotesync_settings.png}
	\caption{RemoteSync settings window}
	\label{fig:plugins:RemoteSync:settings}
\end{figure}

Alternatively, you may start the plugin through command line arguments. This is
useful for automated setups or when multiple instances are running on the same
computer. To start the instance as a server, use the
\texttt{-{}-syncMode=server} argument with the optional \texttt{-{}-syncPort}
parameter to specify the port to listen on. To start a client instance, use
\texttt{-{}-syncMode=client} and use \texttt{-{}-syncHost} and
\texttt{-{}-syncPort} to specify the server to connect to.

In the settings window, you can also specify what should happen when the client 
loses the connection to its server, and what to do when the server quits 
normally. You can choose between 
\begin{description}
\item[Do nothing:] connection is lost and will not be re-established. Stellarium client keeps running 
     in whatever state it was, waiting for keyboard/mouse interaction. 
\item[Try reconnecting:] Assume Stellarium is switched off on the server
      but may come back online again, or assume some temporary network problem. 
	  Stellarium client just keeps running in whatever state it was, but tries to reconnect.
\item[Quit:] Assume the server always runs until switched off at the end of operating hours. 
      This is intended for pure client screens without keyboards. When the server  
	  is shut down, assume this is the end of the day, and exit Stellarium. An enclosing run script 
	  can then shutdown the client computer before power is switched off with some main switch. 
\end{description}
By default, the following things are synchronized:
\begin{itemize}
	\item simulation time
	\item viewer location
	\item the selected object
	\item view direction
	\item current field of view
	\item all StelProperty-based settings except for GUI-related properties. 
	This includes almost all settings visible in the configuration dialogs such 
	as projection type, sky and view options, landscape settings, line colors, etc.
\end{itemize}

Because there is currently no full time synchronisation implemented, for the best
results all client computers should make sure their system clocks are set as
close as possible to the server computer's clock (preferably a few milliseconds
difference at most). This can be done for example by using an NTP server.\footnote{
Instructions on how to use the public NTP server pool for the most common
operating systems can be found at \url{http://www.pool.ntp.org/en/use.html}.} 
If all your Stellarium instances run on the same device, this is of course not 
necessary.

\begin{figure}[ht]
	\centering\includegraphics[width=\columnwidth]{remotesync_client.png}
	\caption{RemoteSync client settings window}
	\label{fig:plugins:RemoteSync:client}
\end{figure}

It is also possible to exclude some state from being synchronized. On each
client, the client configuration GUI (\autoref{fig:plugins:RemoteSync:client}) allows to
disable specific settings from being synchronized on this client. 

The lower part of this dialog allows you to 
fine-tune which named StelProperties (which hold parts of the internal program state) 
should be excluded from synchronization. 
The configuration dialog lists all available properties which usually have easy to understand 
names on the left side. Highlight one or more properties which you don't want synchronized 
and press the arrow button to move them to the list of excluded properties.

For historic reasons there are two kinds of Properties: Actions 
(Boolean switches, for which also hotkeys can be assigned) and (genuine) StelProperties. 
The latter have names indicating which module they belong to and may have other data types (numbers, colors, \ldots). 
Note that the actions frequently are just alias names of Boolean StelProperties, 
so in order to inhibit a certain property from being synchronized, you must find both entries.

Properties of plugins will only be visible when the respective plugin has been enabled. 
When a plugin has been disabled, its properties may vanish from the stored list of non-synchronized properties.

Each client can have different settings. This could allow installations with several screens
where on one screen you show the constellation figures, another screen shows the
distribution of deep-sky objects in the same frame, and a third screen may show
a close-up view of the currently centered object. Or just show several sky cultures, 
or show the sky at different locations, \ldots. 

The names of all available StelProperties from which you might want to select a few to exclude  
from synchronisation can also be found with a little scripting (see chapter ~\ref{ch:scripting}). 
Open the script console \key{F12} and enter the following call:
\begin{script}
core.output(core.getPropertyList());
\end{script}
Run the script and inspect the output tab. It may take a little guesswork to select the right names, 
but the general structure of property names like 
\texttt{<Module>.<Property>} should help you to find your way around.

\subsection*{Author and Acknowledgements}

This plugin was created mostly by Florian Schaukowitsch in the 2015-16 campaigns of the 
\href{http://sophia.estec.esa.int/socis/}{ESA Summer of Code in Space} programme. 

% \newpage
% \section{D-Bus Interface}
% \label{sec:plugin:DBus}
% 
% [This may come as user documentation from SoCiS2018/19 (?) work]


\newpage

\section{Solar System Editor Plugin}
\label{sec:plugins:SolarSystemEditor}

Stellarium stores its data (orbital elements and other details) about
solar system objects (planets, their moons, minor bodies) in two files.  
File \file{data/ssystem\_major.ini} in the installation directory contains data for the planets and their moons.
File \file{data/ssystem\_minor.ini} contains data for minor bodies, i.e., planetoids and comets.
 The file will be taken from the user data
directory if it also exists there, which means, users can add minor
planets or comets as they become observable by editing this file.


This plugin provides a window to the Minor Planet Center (MPC\footnote{\url{https://www.minorplanetcenter.net}}) where the
latest Solar System information can be found. When this plugin is
loaded (see section~\ref{sec:Plugins:EnablingPlugins}) and you call the configuration dialog, the first tab
allows to import, export or reset your \file{ssystem\_minor.ini}, 
and also to load extra data for minor bodies in Stellarium's \file{.ini} format. 
For example, the installation directory contains a file \file{ssystem\_1000comets.ini} which contains 
data for over 1000 historical comets. Currently it is not possible to select only a few from that, 
so try loading this only on a reasonably fast computer, and think about deleting comets again (or resetting the file) when 
you don't require them.

The second tab lists all currently loaded minor bodies (see figure~\ref{fig:SolarSystemEditor:SolarSystem}).  It is recommended
to remove old entries of yesteryear's comets if you don't need them any
longer. Just select one or more objects and press \button{Remove}.
If you have a very weak computer, you may want to reduce the number of
minor bodies to just a handful to improve performance.

On this tab, you also find the option to connect to the MPC and download current orbital elements, 
or load a text file in the format provided by MPC (see figures \ref{fig:SolarSystemEditor:ImportData:InitialView} and \ref{fig:SolarSystemEditor:ImportData:FinalView}). 

\begin{figure}[th]\centering
\includegraphics[width=.75\textwidth]{SolarSystemEditor-plugin-conffile.png}
\caption{Interface of Solar System Editor plugin: Configuration file tab}
\label{fig:SolarSystemEditor:ConfigurationFile}
\end{figure}

\begin{figure}[th]\centering
\includegraphics[width=.75\textwidth]{SolarSystemEditor-plugin-solsys.png}
\caption{Interface of Solar System Editor plugin: Solar System tab}
\label{fig:SolarSystemEditor:SolarSystem}
\end{figure}

\begin{figure}[th]\centering
\includegraphics[width=.75\textwidth]{SolarSystemEditor-plugin-import.png}
\caption{Interface of Solar System Editor plugin: Import data dialog}
\label{fig:SolarSystemEditor:ImportData:InitialView}
\end{figure}

\begin{figure}[th]\centering
\includegraphics[width=.75\textwidth]{SolarSystemEditor-plugin-import2.png}
\caption{Interface of Solar System Editor plugin: Import data dialog --- view after downloading and parsing the MPC data.}
\label{fig:SolarSystemEditor:ImportData:FinalView}
\end{figure}


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