{"id":20059761,"url":"https://github.com/naavis/haloray","last_synced_at":"2025-05-05T15:32:02.841Z","repository":{"id":50407126,"uuid":"189107103","full_name":"naavis/haloray","owner":"naavis","description":"GPU-accelerated atmospheric ice crystal halo simulator","archived":false,"fork":false,"pushed_at":"2023-08-27T17:21:59.000Z","size":20655,"stargazers_count":29,"open_issues_count":0,"forks_count":2,"subscribers_count":6,"default_branch":"develop","last_synced_at":"2024-04-16T04:19:02.067Z","etag":null,"topics":["atmosphere","atmospheric-scattering","gpgpu","gpgpu-computing","gpgpu-sim","ice-crystal-halos","monte-carlo-ray-tracing","monte-carlo-simulation"],"latest_commit_sha":null,"homepage":"https://naavis.github.io/haloray/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/naavis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-28T21:40:01.000Z","updated_at":"2024-02-14T10:09:24.000Z","dependencies_parsed_at":"2023-02-15T23:15:24.485Z","dependency_job_id":null,"html_url":"https://github.com/naavis/haloray","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naavis%2Fhaloray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naavis%2Fhaloray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naavis%2Fhaloray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naavis%2Fhaloray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/naavis","download_url":"https://codeload.github.com/naavis/haloray/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224452805,"owners_count":17313668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atmosphere","atmospheric-scattering","gpgpu","gpgpu-computing","gpgpu-sim","ice-crystal-halos","monte-carlo-ray-tracing","monte-carlo-simulation"],"created_at":"2024-11-13T13:09:27.673Z","updated_at":"2024-11-13T13:09:28.298Z","avatar_url":"https://github.com/naavis.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HaloRay ![](images/hexagon_small.png)\n\n[![Build status](https://ci.appveyor.com/api/projects/status/5k9laekby84x2ex1/branch/develop?svg=true)](https://ci.appveyor.com/project/naavis/haloray/branch/develop)\n\nHaloRay simulates the reflection and refraction of sun light inside hexagonal\nice crystals present in high altitude clouds in the atmosphere. These ice\ncrystals produce various optical phenomena in the sky, including bright spots,\ncircles and arcs.\n\nHaloRay employs GPGPU to massively accelerate simulations. The simulation is\ndone using OpenGL compute and fragment shaders.\n\nHaloRay currently supports Windows and Linux.\n\nAn OpenGL 4.4 compliant GPU is required to run HaloRay. On Windows you also need\nthe [latest Microsoft Visual C++ Redistributable for Visual Studio 2019.](https://aka.ms/vs/16/release/vc_redist.x64.exe)\n\n![Simulation of a column crystal halo display](images/ui-screenshot.png)\n\n## How to use?\n\nHaloRay is designed in such a way that pretty much every simulation parameter\ncan be tweaked in real time. The simulation traces a given number of light rays\nthrough randomly generated ice crystals per rendered frame, and accumulates the\nthe results over time. Any time a simulation parameter is changed, the\nsimulation starts over.\n\nAll the simulation parameters are found on the left-hand side of the user\ninterface. Running the simulation can be started by clicking on the **Render**\nbutton in the bottom left corner.\n\nCamera orientation can be changed by clicking and dragging on the simulated\nview, and the mouse scroll wheel can be used to change the field of view.\n\n### General settings\n\nHere are some general settings for the whole simulation.\n\n- **Sun altitude:** Sun altitude from the horizon in degrees\n- **Sun diameter:** Angular diameter of the sun in degrees\n- **Rays per frame:** Number of rays traced through individual crystals per\n  rendered frame\n  - If the user interface slows down a lot during rendering, lower this value\n  - On an NVIDIA GeForce RTX 3070 a good value seems to be around 500 000\n  - The maximum value for this parameter may be limited by your GPU\n- **Maximum frames:** Simulation stops after rendering this many frames\n- **Double scattering:** Probability of a single light ray to scatter from two\n  different ice crystals\n  - Note that this slows down the simulation significantly!\n  - The current implementation only does double scattering inside one crystal\n    population\n  - A value of 0.0 means no rays are scattered twice, and 1.0 means all rays\n    are scattered twice\n\n### Crystal settings\n\nHaloRay allows you to simulate multiple different ice crystal populations\nsimultaneously. You give each population a name for easier reference by typing\nin the **Crystal population** dropdown menu. Each population has a relative\nweight, which can be changed by adjusting the **Population weight** slider.\nFor example, giving weights 1.0 and 3.0 to two crystal populations respectively\nwould trace three times as many rays through the latter population than the\nformer. It is also possible to enable or disable a crystal population\ntemporarily with the **Population enabled** checkbox.\n\nThe crystals are hexagonal, and have three named axes as shown in the image\nbelow.\n\n![Graphic of the different crystallographic axes](images/crystal-axes.png)\n\nThe orientation of the ice crystals in each population are defined by two\nparameters: tilt of the crystal around the A-axis and rotation around the\nC-axis. For each parameter you can currently choose between two different\nrandom distributions: a uniform distribution and a Gaussian distribution. For\nthe Gaussian distribution you can choose an average angle and the standard\ndeviation of the distribution.\n\nThe following table shows parameters needed to simulate crystal orientations\nknown to happen in nature.\n\n| Orientation | Tilt around a-axis | Rotation around c-axis |\n| ----------- | ------------------ | ---------------------- |\n| Column      | 90                 | Uniform                |\n| Plate       | 0                  | Uniform                |\n| Parry       | 90                 | 0                      |\n| Lowitz      | Uniform            | 0                      |\n| Random      | Uniform            | Uniform                |\n\nThe shape of the crystal can also be adjusted by changing the following\nparameters:\n\n- **C/A ratio average:** Ratio between the C-axis and A-axis lengths of\n  of the crystal\n- **C/A ratio std:** Standard deviation of the C/A ratio\n\n![Graphic of plate and column crystals](images/plate-column.png)\n\nCrystals with a large C/A ratio are look like pencil pieces, and are commonly\ncalled column crystals. Column crystals tend to orient themselves with the\nC-axis horizontal. Crystals with a small C/A ratio are called plate\ncrystals. They tend to orient themselves with the C-axis vertical. Both\nkinds of crystals are shown in the image above.\n\nThe ice crystals also have adjustable pyramidal end caps. Both the upper and\nlower caps have the following settings:\n\n- **Apex angle:** Defines the apex angle of the pyramid cap in degrees\n  - Ranges from 0.0 to 180.0 degrees, where low numbers mean a very pointy cap\n    while high numbers mean the opposite\n  - Typically the apex angle is 56 degrees on water ice crystals\n- **Apex average height:** Defines the height of the pyramid cap\n  - Ranges from 0.0 to 1.0, where 0.0 means the cap is totally flat and 1.0\n    means a cap that converges to a sharp point\n- **Apex height std:** Standard deviation of the pyramid cap height\n\n![Graphic of pyramidal ice crystal](images/pyramid-crystal.png)\n\nAbove is a representation of an ice crystal with pyramidal end caps.\nCurrently HaloRay is limited to convex ice crystals, so the end caps\ncannot extend inwards to make hollow ice crystals.\n\nHaloRay provides six sliders you can use to adjust the **distance of each prism\nface** of the hexagonal ice crystals from the crystal C-axis.\n\n![Graphic of a non-regular shaped ice crystal](images/non-regular-crystal.png)\n\nThe above image shows a crystal where every other prism face has the default\ndistance of 1.0 from the C-axis, while every other is reduced to 0.7.\n\n### View settings\n\nThese settings affect how the results of the simulation are shown on the screen.\n\n- **Camera projection:** Defines how the view is projected to the screen\n- **Field of view:** Vertical field of view in degrees\n- **Pitch:** Vertical orientation of the camera in degrees from the horizon\n- **Yaw:** Horizontal orientation of the camera in degrees from the sun's direction\n- **Brightness:** Alters the total brightness of the image, much like an exposure adjustment on cameras\n- **Hide sub-horizon:** Hides any halos below the horizon level\n- **Lock to light source:** Locks the camera to the sun\n- **Show guides:** Draws markings for horizon, zenith, nadir, 22r and 46r circles\n\n### Atmosphere settings\n\nHaloRay renders a realistic sky and sun disk based on a blend of Hosek-Wilkie and\nPreetham models. The sky model has only a few adjustable parameters:\n\n- **Atmosphere enabled:** Toggles rendering of the sky and sun\n- **Turbidity:** The amount of aerosols/haze in the atmosphere\n- **Ground albedo:** Albedo of the ground plane\n  - 0.0 means the ground does not reflect any light\n  - 1.0 means the ground reflects all light\n\n### Menus\n\nThe top menus should be pretty self-explanatory. Entries in the _File_ menu\nallow you to reset the simulation, save and load simulation parameters, and save\nthe simulation output to an image file on disk.\n\n_View -\u003e Crystal preview_ lets you see a wireframe preview of the an average\nice crystal in the currently selected crystal population.\n\n## How to build?\n\nThe user interface is built with [Qt 5](https://www.qt.io/), so you need to\n[download the Qt libraries](https://www.qt.io/download-qt-installer) before\ncompiling HaloRay.\n\nThe build is handled with Qt's build tool qmake. You can also use the Qt Creator\nIDE to open and build the code.\n\nOn Linux you can install Qt using your package manager. On Ubuntu Linux you can\ninstall Qt by running:\n\n```bash\nsudo apt-get install qt5-default\n```\n\nFinally build the project by running:\n\n```bash\nmkdir build\ncd build\nqmake ../src/haloray.pro\nmake\n```\n\nYou can use `nmake` instead of `make` on Windows.\n\nOn Windows you need to add the Qt5 binary directory to your PATH environment\nvariable or copy at least the following Qt DLL files to the same folder as the\nresulting executable:\n\n- Qt5Core.dll\n- Qt5Widgets.dll\n- Qt5Gui.dll\n- Qt5Svg.dll\n\nYou can also do this automatically with the\n[windeployqt](https://doc.qt.io/qt-5/windows-deployment.html) tool, which is\nshipped with Qt 5. This is the recommended way.\n\nYou can check `scripts\\build.ps1` to see how the project is built on the\nAppveyor CI server.\n\n## FAQ - Frequently asked questions\n\n### UI components are scaled all wrong on a 4K display in Windows, what to do?\n\nOn high-DPI screens Windows scales UI elements by default. HaloRay doesn't fully\nadapt to this scaling yet. For now, you can either disable the scaling on an\noperating system level by setting UI scale to 100% in Windows display settings,\nor try running HaloRay with\n[special command-line parameters](https://doc.qt.io/qt-5/qguiapplication.html#platform-specific-arguments)\nlike this:\n\n```\nHaloRay.exe -platform windows:dpiawareness=2\n```\n\n### HaloRay crashes or does not start, how to troubleshoot?\n\nHaloRay writes a log file to help in troubleshooting.\n\nOn Windows you can find it in `%LOCALAPPDATA%\\Temp\\haloray\\haloray.log` where\n`%LOCALAPPDATA%` is usually equal to `C:\\Users\\\u003cusername\u003e\\AppData\\Local`\n\nOn Linux the log file is in `/tmp/haloray/haloray.log`\n\nIf the logs do not show any useful information and no error messages pop up,\nit is possible the crash happens because of a GPU driver bug. This has\noccasionally happened with some Intel GPUs, and there is not much HaloRay\ncan do about it. It is recommended to update to the latest GPU drivers if\nproblems like this are encountered.\n\n## Acknowledgments\n\n- [Lauri Kangas](https://github.com/lkangas) for providing tons of reading material and debugging help\n- [Panu Lahtinen](https://github.com/pnuu) for additional Linux support\n- Jukka Ruoskanen for making HaloPoint 2.0 back in the day and inspiring me to start working on HaloRay\n- Marko Riikonen for giving valuable feedback and reporting bugs\n- [Jaakko Lehtinen](https://users.aalto.fi/~lehtinj7/) for super valuable lessons in computer graphics\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaavis%2Fhaloray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaavis%2Fhaloray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaavis%2Fhaloray/lists"}