中文版 / Chinese version

A C++17 ice halo ray-tracing simulator: it traces light rays through ice crystals to reproduce natural halo patterns. Lumice is fast, supports natural spectral color rendering, and handles arbitrary multi-scattering scenes. CLI and GUI front-ends share the same simulation core.

Inspired by HaloPoint 2.0 and HaloSim 3.0.

• High speed. Significantly faster than HaloPoint: roughly 3–4M rays/second on typical single-scattering scenes, and 400k–600k rays/second under two-layer full scattering (prob=1.0, every ray is forced through two crystal interactions).

• Natural spectral color. Wavelength-aware rendering powered by the Spectrum Renderer project produces realistic halo color.

• Multi-scattering support. Arbitrary multi-scattering scenes (e.g. plate ice over randomly-oriented columns) are first-class — see the rendered 44° parhelia below.

  

Build the CLI and run the bundled example. Most readers should be up in five minutes.

# 1. Build (release, parallel) — installs into build/cmake_install/
./scripts/build.sh -j release

# 2. Run the example simulation
./build/cmake_install/Lumice -f examples/config_example.json

The CLI prints progress and writes four PNG/JPG renders next to your working directory.

Runtime. The example traces 9-wavelength × 50 M rays. On a modern multi-core machine this takes about 2 minutes; older laptops may take longer. To smoke-test much faster, set "ray_num": 100000 in the config.

For an interactive workflow with live preview, see the GUI section below.

Lumice reads a single JSON file describing the crystal, filter, scene (light source + ray budget + scattering layers), and render (lens, view, resolution, grid) sections. The example at examples/config_example.json is the canonical reference and is what the Quick start runs.

A minimal skeleton looks like:

{
  "crystal": [ /* one or more crystal definitions, see configuration guide */ ],
  "filter":  [ /* optional ray-path filters */ ],
  "scene":   { "light_source": { /* sun/spectrum */ }, "ray_num": 50000000, "scattering": [ /* layers */ ] },
  "render":  [ { "lens": { "type": "fisheye_equal_area", "fov": 180 }, "resolution": [1920, 1080], /* ... */ } ]
}

For the full field reference (every section, every option, every lens type) see doc/configuration.md.

A graphical front-end (built with ./scripts/build.sh -gj release and launched as ./build/cmake_install/LumiceGUI) lets you edit crystal/scene/render parameters with a real-time 3D preview, cycle lens projections, and inspect simulation output without hand-editing JSON.

The GUI panels cover crystal geometry & axis distributions, lens & view, filters, multi-scattering layers, and project save/load (.lmc). Detailed walkthroughs of each panel — including all lens projections, crystal preview modes, and editing dialogs — live in doc/gui-guide.md.

Configurations from earlier releases may need to be re-authored: v3 reworked the rotation chain. See the breaking-change note at the top of doc/coordinate-convention.md.

1. HaloPoint 2.0 & HaloSim 3.0