 |
CalcMySky
v0.3.1
|
|
CalcMySky
v0.3.1
|
The model is generated by calcmysky utility from a text file, whose name normally has .atmo suffix. The command
will use the input file description.atmo and output the model to a directory named output-directory.
This utility has some options that can be listed by running it with --help option.
calcmyskyGenerally the command line of calcmysky utility looks as
-h, --help
-v, --version
--out-dir <output directory>
--texture-save-precision <bits>
These options are not useful for a normal user, they are used by developers.
--opengl-debug
--opengl-debug-full
--save-irradiance
--save-scat-density2-from-ground
--save-scat-density
--save-delta-scattering
--save-accum-scattering
--save-light-pollution
Model description files consist of entries that represent key-value pairs. Empty lines between entries are ignored, and "#" character starts comments. Single-line entries can also be followed by a comment in the same line.
Any text on a line before the first colon character ":" is considered to be key. Depending on the key, corresponding value can be one of the following:
123.456;min=360nm,max=830nm,count=16;A dimensionful quantity is a number followed by a unit. Scientific notation is not supported. An example of a length quantity is 1.234 m.
Several types of quantities are supported:
| Dimension | Supported units |
|---|---|
| length | nm, um, mm, m, km, Mm, Gm, AU |
| reciprocal length | nm^-1, um^-1, mm^-1, m^-1, km^-1, Mm^-1, Gm^-1 |
| area | am^2, fm^2, pm^2, nm^2, um^2, mm^2, cm^2, m^2, km^2, Mm^2, Gm^2 |
Spectra are specified in predefined units, which depend on the key to which this spectrum corresponds.
There are several ways to specify a spectrum:
wavelengths entry. Example of such spectrum: "file ". The format is described in Spectrum file format section. Here the spectrum may be sampled at any points, it will be resampled to match wavelengths automatically. Example: "weighted file ", and each new such entry accumulates the new values in the corresponding spectrum. Example: Spectrum files are CSV (Comma-Separated Values) tables with two columns. Each line corresponds to one spectral point: first column specifies wavelength in nanometers, second column holds value. Empty lines are ignored.
Example of a spectrum from \(400\,\mathrm{nm}\) to \(700\,\mathrm{nm}\) with \(100\,\mathrm{nm}\) interval:
A section begins on the next line after the key, the colon character remains on the line with the key.
Top-level sections are bounded by an opening brace "{" and a closing brace "}". Between braces there can be multiple key-value entries.
Example of a section:
Some section:
{
some value: 234
}
Code blocks look similarly to sections, but instead of braces they are bounded by triple backticks "```", similarly to fenced code blocks in Markdown.
Example of a code block:
number density:
```
const float rayleighScaleHeight=8*km;
return 3.08458e25*exp(-1/rayleighScaleHeight * altitude);
```
The keys listed here are grouped by common parts of the name. The omitted parts are marked with "*". A few examples of complete *.atmo files can be found under the examples directory in the source tree.
versionThis entry must be the first entry in the atmosphere description file. It defines the layout of the model data and general format of the atmosphere description file. If it doesn't match the format supported by the given version of CalcMySky, an error will be emitted by calcmysky and showmysky utilities, as well as by the ShowMySky library.
atmosphere heightThis entry is dimensionful. Atmosphere height is the maximum altitude at which density of some constituents of the atmosphere is considered nonzero. The sphere of all the points at this altitude is called TOA, i.e. top of atmosphere. All the textures span altitudes from 0 to atmosphere height. Valid values for this entry are length quantities from 1 m to 1 Mm.
scattering ordersWhen a light ray propagates in the atmosphere, it can be scattered on the inhomogeneities of this medium (molecules, dust, etc.). This produces secondary rays, which, in turn, can also be scattered to produce tertiary rays, etc. The first scattering of the initial ray is called first-order scattering. Scattering of the secondary rays is second-order, and so on.
Radiance in each subsequent scattering order normally becomes smaller, approaching zero in the limit. This makes it possible to ignore the scattering events starting with some order of scattering, with negligible loss of accuracy. The scattering orders entry sets number of scattering orders to take into account.
transmittance texture size*Transmittance texture holds a map of percentage of light that's transmitted through the atmosphere from the TOA to the camera, given altitude of a camera and view zenith angle (VZA) of this camera. The entries above control the resolution of the transmittance texture in each of these dimensions.
irradiance texture size*Irradiance texture contains values of irradiance of a horizontal surface at the point with given altitude and zenith angle of the Sun (SZA). The entries above control the resolution of the irradiance texture in each of these dimensions.
scattering texture size*Scattering textures are the main textures that contain the actual radiance or luminance from given direction as seen by a camera at the given altitude, with the Sun being at a given zenith angle.
VZA, SZA and altitude here are similar to the corresponding parameters in irradiance and transmittance textures.
The dot(view,sun) parameter determines cosine of the angular distance between the direction from the camera to the Sun and the direction of view of the camera.
For technical reasons the texture size for VZA here must be even.
eclipsed scattering texture size*When solar eclipse is simulated, corresponding first-order scattering texture is computed on the fly during rendering, for the current altitude of the camera and the current positions of the Sun and the Moon. This is unlike the case of non-eclipsed calculations, where such radiance is precomputed for all altitudes and solar elevations.
Relative azimuth is the azimuth of the view direction relative to the Sun. VZA is view zenith angle, as described for transmittance texture.
eclipsed double scattering texture size*When solar eclipse is simulated, it's only simulated for two scattering orders, because going further is prohibitively slow. Even second-order scattering is quite slow on many GPUs. These entries control precomputation of a texture that will hold second-order scattering radiance for the given view zenith angle, solar elevation, and azimuth of view relative to the Sun.
eclipsed double scattering number of * pairs to sampleBecause second-order scattering is so slow to compute, radiance is sampled on a very sparse grid of points. Several circles at different azimuths are sampled at multiple elevations, with an optimized distribution of samples. The samples are taken in pairs, e.g. if one sampling direction is forward, one more will be backward.
The more samples one takes, the higher the resolution of the final second-order scattering layer.
light pollution texture size*Light pollution is simulated with the assumption that the whole Earth glows uniformly with the given luminance (which is controlled at runtime). This makes the radiance quite symmetric (although overestimated near the horizon), depending only on altitude of the camera and zenith angle of its view direction. These entries control resolution in these parameters.
transmittance/radial integration pointsComputation of transmittance and inscattered radiance is done in the direction of view from camera position to the TOA. Since transmittance is stored in a 2D texture, rather than 4D, it's relatively cheap to compute it more precisely. Inscattered radiance, OTOH, is stored in a 4D texture, so radial integration points value has to be smaller to make the computation faster. This is especially important for eclipsed atmosphere, where this computation is done on the fly.
angular integration points*Angular integration is done at every point of sampling of a ray, to collect the radiance that comes in from all directions, and compute the radiance that is scattered out. The integration is performed using a quasi-uniform spherical Fibonacci lattice, a good explanation of which can be seen here. The entries above all define total number of points in this lattice, for normal and eclipsed atmospheres.
light pollution angular integration pointsDue to the symmetry of the uniformly-glowing-globe approximation, light pollution is computed as a 1D integral over elevations, so this entry just defines number of points in 1D quadrature.
Earth-Sun distance, Earth-Moon distance, Earth radiusThese entries are dimensionful. They define the physical constants used in the model. Earth-Sun distance can be from \(0.5\,\mathrm{AU}\) to \(10^{20}\,\mathrm{AU},\) Earth-Moon distance can be from \(10^{-4}\,\mathrm{AU}\) to \(10^{20}\,\mathrm{AU},\) and Earth radius can be from 100 km to 10 Gm.
Earth-Moon distance is used only for precomputation of eclipsed double scattering.
Note that these limits are rather arbitrary, and nothing too far (like orders of magnitude difference) from the real Earth-Sun-Moon system has ever been tested.
wavelengthsThis entry describes the set of wavelengths to use. It consists of smallest wavelength (min), largest (max), and total number of wavelengths in the set (count). The calculations are done separately for each wavelength to obtain radiance from different directions. Then these values are saved into the textures.
After radiance is obtained, to be displayed on a screen it needs to be converted to some color space. This is done by numerically integrating the radiance with respect to the CIE 1931 color matching functions, after which the conversion to the target color space is done.
Scattering textures are stored as either spectral radiance (when requested by --radiance option for calcmysky), or as \(XYZW\) luminance. \(XYZ\) here are the CIE 1931 tristimulus values, and \(W\) is the scotopic luminance.
solar irradiance at TOAThis entry is a spectrum. It defines spectral irradiance in \(\mathrm{\frac W{m^2 nm}}\) as it would be measured at the TOA when the Sun is at zenith.
ground albedoThis entry is a spectrum. It defines ground albedo, where each point is a dimensionless value in the range from 0 to 1. Ground BRDF is hard-coded to be Lambertian.
light pollution relative radianceThis entry is a spectrum. It defines spectral radiance of the ground, in \(\mathrm{cd/m^2}.\) The total luminance here should be normalized to \(1\,\mathrm{cd/m^2}.\)
Scatterer "*"This entry is a section. Its name is formed as Scatterer keyword followed by name of the scatterer species in quotes. The species name must consist only of alphanumeric characters and underscores and have no spaces. Inside the braces there are several key-value entries, described in the following subsections.
number densityThis entry is a code block. It defines number density of the scatterer being described in the current section. This code block is used as the implementation of a GLSL function that has a float parameter called altitude, with a value in meters, and returns a float value of number density in \(\mathrm m^{-3}\).
phase functionThis entry is a code block that computes the phase function of the current scatterer. It takes a float parameter called dotViewSun, and returns vec4 relative intensity, where each component of vec4 corresponds to wavelength in corresponding component of the global vec4 variable wavelengths.
Mathematically, the parameter is cosine of the angle between the incoming ray and the scattered ray. Each component of the output vec4 (let's call \( i\)th component \(f_i\)) must be normalized by the following condition:
\begin{equation} \int_{0}^{2\pi}\mathrm{d}\varphi \int_{0}^{\pi} \mathrm{d}\theta \sin(\theta) f_i(\theta)=1. \end{equation}
phase function typeDepending on the properties of the scatterer, there may be some ways to optimize storage of the computation results. This entry can have the following values:
general — the most general way of storing computation results: first-order scattering in a separate texture, split into separate textures per wavelength set, multiple scattering in another texture.achromatic — denotes a phase function that doesn't depend on wavelength. This lets us merge all the single scattering radiance textures into a single luminance texture without compromising correctness of rendering.smooth — a kind of phase function that doesn't need a high resolution texture to be represented well. This lets the phase function be embedded into the texture. Such texture data can be saved as color instead of radiance. This helps save storage space and improve rendering performance.cross section at 1 umThis entry is a dimensionful quantity of area. It defines extinction cross section of the current scatterer at \(1\,\mathrm{\mu m}\) wavelength. The values for other wavelengths are obtained using the angstrom exponent parameter.
For gases Rayleigh scattering cross section can be found from refractive index using the following formula (see Landau, Lifshitz, "Electrodynamics of Continuous Media", equation \((120.4)\) for reference; we augment it with \(h=\sigma N\) to get \(\sigma\)):
\begin{equation} \sigma_{\text{sc}}=\frac{8\pi^3}3\frac{(n^2-1)^2}{\lambda^4}\left(\frac{k_{\text{B}}T}P\right)^2, \end{equation}
where \(n\) is refractive index, \(\lambda\) is the vacuum wavelength (taken as \(1\,\mathrm{\mu m}\) for this entry), \(k_{\text{B}}\) is the Boltzmann constant, and \(T\) and \(P\) are respectively temperature and pressure at which this refractive index was measured.
angstrom exponentThis entry defines the Ångström exponent, which describes the power law dependence of the optical thickness (extinction coefficient) of a medium on wavelength. For Rayleigh scattering its value is 4, while for clouds it is about zero.
single scattering albedoThis entry is a spectrum. It defines single scattering albedo of current scatterer. Each point of this spectrum is a dimensionless value in the range from 0 to 1. If not specified, the default is albedo of 1 at each wavelength.
needs interpolation guidesThis entry is a special token that's not a key: it isn't followed by a colon with a value.
Presence of this entry means that single scattering data for the scatterer described in current section have a rapid variation of colors in the Venus belt region, which, if texture resolution is small, will look jumpy when interpolated using the usual quadrilinear filter — either when looking at a single frame (similar to aliasing of lines), or when watching the sunset (the Venus belt will jump from one elevation to the next in the texture as the Sun goes deeper under the horizon). To fix this problem, special files will be created which will guide the renderer's interpolation function to improve quality.
If this entry is not present, interpolation guides are not created, so interpolation will use quadrilinear filter. This is better for performance, so should be the default.
Absorber "*"This entry is a section. Its name is formed as Absorber keyword followed by name of the absorbing species in quotes. The species name must consist only of alphanumeric characters and underscores and have no spaces. Inside the braces there are several key-value entries, described in the following subsections.
number densityThis entry is of the same kind as the one in the Scatterer section.
cross sectionThis entry is a spectrum. It defines cross section of absorption of the current absorber. The data points in this spectrum are in units of \(\mathrm{\frac{m^2}{particle}}\) (where "particle" is the object counted by the number density parameter).
1.8.15