\chapter{Stellarium's Skylight Models}
\label{ch:skylight}
\chapterauthor*{Georg Zotti}

\section{Introduction}
\label{sec:skylight:introduction}

Stellarium's main aim is a realistic simulation of the night sky. This
is more than just the creation of a star map. Especially a realistic
simulation of twilight and the visibility of stars, deep-sky objects
or the Zodiacal light is a challenge. Since early in its history
Stellarium has used models from the computer graphics literature to
achieve its goals. For most users, the models seem to work well, but
more advanced users may want to tweak some of the values.

\section{The Skylight Models}
\subsection{Legacy Mode: The Preetham Skylight Model}
\label{sec:skylight:Preetham}

A well-known fast computer graphics model for daylight has been
presented by \citet{Preetham:1999}. Its brightness distribution is
based on an all-weather model for sky luminance distribution by
\citet{Perez:1993} and models chromaticity distribution with
similarly-shaped functions. It works reasonably well for average
conditions, and a ``turbidity'' parameter $T$ allows a simple
modelling of visibility conditions. In terms of the atmospheric
extinction coefficient $k$ (see \ref{sec:phenomena:Extinction}), we
can define
\begin{equation}
  T=25(k-0.16)+1
  \label{eq:TfromK}
\end{equation}
In Stellarium, a value of $T=5$ has been used for many years, and the
chromaticity parameters have been slightly changed for a more pleasing
color distribution at this value for $T$. Recently,
\newFeature{0.22.0} we have made the many parameters of the Preetham
model accessible for users to fine-tune. Not many users will even want to do this,
and therefore you must enable this manually by editing \file{config.ini}:
\begin{configfile}
  [Skylight]
  enable_gui=true
\end{configfile}

Only with this setting, a button \guibutton[1.0]{0.75}{uibtEdit.png} will be
available in the View settings, Sky tab (section~\ref{sec:gui:view:sky:atmosphere}).

All settings described here will immediately be stored in \file{config.ini}. 

One setting allows to compute $T$ from $k$ with the above relation
\ref{eq:TfromK}.

Please note that the parameters are far from intuitive, therefore we
added two sets of reset functions. One sets the values to those in the
original paper, the other re-establishes Stellarium's sky colors from
version 0.21.3 and earlier, which however seem only suitable for
$T=5$.

A sky brightness model better suited for astronomical simulation,
including twilight and brightness contributions of the Moon and
airglow, was presented by \citeauthor{Schaefer:Limits-Archaeo}
(\citeyear{Schaefer:Limits-Archaeo} and
\citeyear{Schaefer:Limits}). By default, Stellarium uses this model in
combination with chromaticity from the Preetham model. For
experiments, you can however revert from the Schaefer brightness model
to the Preetham model. The parameters of the Schaefer model are
currently not accessible for further experiments.

Some more parameters fine-tune some aspects of rendering of the Solar
disk and the solar glare. It makes a slight difference whether the
Sun's disk is plotted before or after the glare, and whether the solar
sphere is rendered after the atmosphere. 

\subsection{Advanced Mode: The ShowMySky Skylight Model}
\label{sec:skylight:ShowMySky}

A much more advanced skylight model has been presented by
\citet{Bruneton:2008}. An implementation of this has been developed by
Ruslan Kabatsayev just in time for inclusion in version 1.0. Switching
between the models is described in
section~\ref{sec:gui:view:sky:atmosphere}.

It requires graphics hardware which uses OpenGL~3.3 or better and
consists of two components.  Atmospheric data (a description of gas
composition) is processed by an auxiliary program,
\program{CalcMySky}, which creates a lot of textures and shaders.
For final display, a software component (the
\program{ShowMySky} library) is used that processes these data in
real-time to compute the final sky colors. This model and its default
atmosphere data especially can deliver stunning reality of twilight
colors in a dry atmosphere, and also provides special modes for the
``circular twilight'' during a Total Solar Eclipse.

\begin{description}
\item[To choose a dataset] press \guibutton[1.0]{0.75}{uibtFolder.png}
  near the \emph{Path to data} entry field, and in the dialog that
  opens, choose the directory with the dataset.  Stellarium comes with
  a default dataset that's automatically chosen after a fresh
  installation.  Power users can use
  \program{CalcMySky}\footnote{\url{https://github.com/10110111/CalcMySky}}
  to generate other atmospheres. Creating a new dataset requires some
  understanding of the physics of light scattering.
\item[Eclipse simulation quality] option lets you configure the
  balance between realism of skylight simulation during a solar
  eclipse. The values of this option can be:
  \begin{description}
  \item[0] This is the fastest and crudest mode. The atmosphere is
    simply dimmed to account for the lower amount of direct sunlight.
  \item[1] This is the first mode that actually tries to simulate an
    eclipse. It uses precomputed textures, and may look blocky in some
    cases like e.g.\ very low Sun (and Moon).
  \item[2] This mode is much slower than the previous one (2.5~FPS on
    an NVIDIA GeForce GTX~750Ti).  In this mode part of the
    calculation is done on the fly for the current eclipse phase to
    improve correctness of the simulation, unlike the previous mode
    where a texture was used that contains data only for totality,
    other phases being approximated from this.
  \item[3] This is the slowest mode (1.1 FPS on NVIDIA GeForce
    GTX~750Ti), but computation is done on the fly for the whole
    simulation, which yields best quality.
  \end{description}
\end{description}

\begin{description}
\item[To achieve higher frame rates] on slow systems,
the configuration parameter in \file{config.ini}:
\begin{configfile}
[landscape]
atmosphere_resolution_reduction = 4
\end{configfile}
allows reducing the resolution of the skylight texture.
Preferred values are:
\begin{description}
\item[1] full resolution (default)
\item[2] half resolution
\item[4] quarter resolution
\end{description}
\item[The configuration switch] in \file{config.ini}:
\begin{configfile}
[landscape]
flag_atmosphere_dynamic_resolution = true
\end{configfile}
allows to use the reduced resolution only while moving the view, when panning, 
zooming, dimming or in time-lapse mode. With the real-time display, on the other hand, 
the full resolution is retained.
Possible values are:
\begin{description}
\item[false] static resolution (default)
\item[true] dynamic resolution
\end{description}
\item[Note:]
In dynamic resolution mode, a motion analyzer selects either full or reduced resolution.
The change in resolution could be particularly visible in close proximity to the Sun.
Especially at full resolution, frames will be skipped depending on the speed of movement.
\end{description}

\noindent A more detailed description of how to create a custom atmosphere will
be given in a future version of this User Guide.

\section{Light Pollution}

In urban and suburban areas the night sky is lit by ground sources of light.
This light is scattered by the atmosphere, and the sky appears brighter. This
reduces visibility of astronomical objects.

Stellarium simulates this effect. The main physical quantity that describes light pollution is zenith luminance, measured in candelas per square meter ($\mathrm{cd/m^2}$). It can be measured using a device called \emph{sky quality meter} (SQM).

For astronomical observations often another unit of sky brightness is useful: magnitudes per square arcsecond ($\mathrm{mag/arcsec^2}$). It is related to $\mathrm{cd/m^2}$ as
\begin{equation}
L=10.8\times10^{4-0.4M},
\end{equation}
where $L$ is the value in $\mathrm{cd/m^2}$, and $M$ is the value in $\mathrm{mag/arcsec^2}$. Some SQMs give readings in $\mathrm{mag/arcsec^2}$. Stellarium supports input in both units.

Another way to characterize light pollution is by defining the \emph{naked-eye limiting magnitude} (NELM). Unlike luminance, which, although based on human vision, is well-standardized (in particular, the candela is part of the SI), NELM is subjective and variable: it is based on human vision, depends on weather conditions, and is not standardized. In Stellarium the calculations follow \citet{Schaefer:LimitingMagnitudes}. In particular, equation $(18)$ is used, assuming observer's acuity $F_s=1$ (as suggested in the text as ``typical observer''), and absorption term $k_v=0.3$ (as suggested for ``typical weather'').

A related subjective characterization of light pollution is the \emph{Bortle Dark Sky Scale}, which assigns an integral number from 1 to 9 to the sky based on its brightness. This scale is described in detail in Appendix~\ref{ch:BortleScale}.

Stellarium calculates both Bortle class and NELM for user convenience. They aren't used in the actual calculations for visualization.

\section{Tone Mapping}

Tone mapping is the process which attempts to compress the brightness
values found in nature into the range of brightness values which can
be achieved on a display device so that an image of a natural scene looks reasonably natural
and realistic. The process has been described by
\citet{TumblinRushmeier:1993}, \citet{Larson:1997} and
\citet{DevlinChalmersWilkie:2002}. For low-light conditions like night
and the transitional phase, twilight, special considerations have to
be taken, first described by \citet{WannJensen:2000}.
Stellarium's transformation from skylight model to display colors is based on these papers.

Parameters to tweak the tone mapping can be reached in the view
settings dialog after pressing \guibutton[1.0]{0.75}{uibtProcess.png}.

\begin{description}
\item[Display max luminance] maximal brightness of the used
  screen. This used to be $100 \cdpmQ$ applicable for CRT monitors,
  but more modern screens can achieve much higher luminances of $250
  \cdpmQ$ or more, to be found in the spec sheets. Adjust this value
  to influence the displayed brightness along the horizon.
\item[Display adaptation luminance] describes the view environment
  where the screen is set up. For an average office environment,
  $50 \cdpmQ$ seems a usable default. In an outdoor setting, much
  higher values are possible.
\item[Display Gamma] describes the exponent of a nonlinear correlation
  between input values and output luminance of the screen. Higher
  values push the average image brightness.
\item[Use extra Gamma term] The original implementation of tone
  mapping included a gamma term which did not exactly follow the
  description from \citet{Larson:1997}, but looks better (more
  colorful) than the implementation without the gamma term. You can
  now play with it to find your preferred setting. This flag is only
  used with the Preetham skylight model.
\item[Use sRGB] The final step of color creation is a transformation
  from CIE Yxy to some display RGB color space. Nowadays most monitors
  can display the sRGB color space, therefore this flag is usually
  enabled. Disabling this flag will lead to using the Adobe RGB
  (1998) color space. The colors may look a bit better on monitors
  which are set to display Adobe RGB, but washed-out on sRGB monitors.
\end{description}



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