GPU-accelerated atmospheric ice crystal halo simulator
HaloRay simulates the reflection and refraction of sun light inside hexagonal ice crystals present in high altitude clouds in the atmosphere. These ice crystals produce various optical phenomena in the sky, including bright spots, circles and arcs.
HaloRay employs GPGPU to massively accelerate simulations. The simulation is done using OpenGL compute and fragment shaders.
HaloRay currently supports Windows and Linux.
An OpenGL 4.4 compliant GPU is required to run HaloRay. On Windows you also need the latest Microsoft Visual C++ Redistributable for Visual Studio 2019.
HaloRay is designed in such a way that pretty much every simulation parameter can be tweaked in real time. The simulation traces a given number of light rays through randomly generated ice crystals per rendered frame, and accumulates the the results over time. Any time a simulation parameter is changed, the simulation starts over.
All the simulation parameters are found on the left-hand side of the user interface. Running the simulation can be started by clicking on the Render button in the bottom left corner.
Camera orientation can be changed by clicking and dragging on the simulated view, and the mouse scroll wheel can be used to change the field of view.
Here are some general settings for the whole simulation.
HaloRay allows you to simulate multiple different ice crystal populations simultaneously. You give each population a name for easier reference by typing in the Crystal population dropdown menu. Each population has a relative weight, which can be changed by adjusting the Population weight slider. For example, giving weights 1.0 and 3.0 to two crystal populations respectively would trace three times as many rays through the latter population than the former. It is also possible to enable or disable a crystal population temporarily with the Population enabled checkbox.
The crystals are hexagonal, and have three named axes as shown in the image below.
The orientation of the ice crystals in each population are defined by two parameters: tilt of the crystal around the A-axis and rotation around the C-axis. For each parameter you can currently choose between two different random distributions: a uniform distribution and a Gaussian distribution. For the Gaussian distribution you can choose an average angle and the standard deviation of the distribution.
The following table shows parameters needed to simulate crystal orientations known to happen in nature.
Orientation | Tilt around a-axis | Rotation around c-axis |
---|---|---|
Column | 90 | Uniform |
Plate | 0 | Uniform |
Parry | 90 | 0 |
Lowitz | Uniform | 0 |
Random | Uniform | Uniform |
The shape of the crystal can also be adjusted by changing the following parameters:
Crystals with a large C/A ratio are look like pencil pieces, and are commonly called column crystals. Column crystals tend to orient themselves with the C-axis horizontal. Crystals with a small C/A ratio are called plate crystals. They tend to orient themselves with the C-axis vertical. Both kinds of crystals are shown in the image above.
The ice crystals also have adjustable pyramidal end caps. Both the upper and lower caps have the following settings:
Above is a representation of an ice crystal with pyramidal end caps. Currently HaloRay is limited to convex ice crystals, so the end caps cannot extend inwards to make hollow ice crystals.
HaloRay provides six sliders you can use to adjust the distance of each prism face of the hexagonal ice crystals from the crystal C-axis.
The above image shows a crystal where every other prism face has the default distance of 1.0 from the C-axis, while every other is reduced to 0.7.
These settings affect how the results of the simulation are shown on the screen.
HaloRay renders a realistic sky and sun disk based on a blend of Hosek-Wilkie and Preetham models. The sky model has only a few adjustable parameters:
The top menus should be pretty self-explanatory. Entries in the File menu allow you to reset the simulation, save and load simulation parameters, and save the simulation output to an image file on disk.
View -> Crystal preview lets you see a wireframe preview of the an average ice crystal in the currently selected crystal population.
The user interface is built with Qt 5, so you need to download the Qt libraries before compiling HaloRay.
The build is handled with Qt's build tool qmake. You can also use the Qt Creator IDE to open and build the code.
On Linux you can install Qt using your package manager. On Ubuntu Linux you can install Qt by running:
sudo apt-get install qt5-default
Finally build the project by running:
mkdir build
cd build
qmake ../src/haloray.pro
make
You can use nmake
instead of make
on Windows.
On Windows you need to add the Qt5 binary directory to your PATH environment variable or copy at least the following Qt DLL files to the same folder as the resulting executable:
You can also do this automatically with the windeployqt tool, which is shipped with Qt 5. This is the recommended way.
You can check scripts\build.ps1
to see how the project is built on the
Appveyor CI server.
On high-DPI screens Windows scales UI elements by default. HaloRay doesn't fully adapt to this scaling yet. For now, you can either disable the scaling on an operating system level by setting UI scale to 100% in Windows display settings, or try running HaloRay with special command-line parameters like this:
HaloRay.exe -platform windows:dpiawareness=2
HaloRay writes a log file to help in troubleshooting.
On Windows you can find it in %LOCALAPPDATA%\Temp\haloray\haloray.log
where
%LOCALAPPDATA%
is usually equal to C:\Users\<username>\AppData\Local
On Linux the log file is in /tmp/haloray/haloray.log
If the logs do not show any useful information and no error messages pop up, it is possible the crash happens because of a GPU driver bug. This has occasionally happened with some Intel GPUs, and there is not much HaloRay can do about it. It is recommended to update to the latest GPU drivers if problems like this are encountered.