Atmosphere

Introduction

The atmosphere addon provides physically based sky and aerial perspective rendering.

Orbital views of the globe are also supported, as demonstrated in the following playground.

Installation

The atmosphere addon is available as an ES6 NPM package:

npm install @babylonjs/addons --save

and as a UMD NPM package:

npm install babylonjs-addons --save

When using the ES6 package, import the Atmosphere class directly from its subpath:

import { Atmosphere } from "@babylonjs/addons/atmosphere";

Scene Setup

PBRMaterial

For rendering objects within the atmosphere, it is recommended to use physically based materials (PBR).

The atmosphere addon automatically integrates with PBRMaterial, ensuring consistent lighting that accounts for atmospheric effects.

Directional Light

The sun source for the atmosphere is represented by a DirectionalLight.

const light = new DirectionalLight("sun", new Vector3(0, -1, 0), scene);
light.intensity = Math.PI; // Set intensity for PBRMaterials

To get the correct brightness on PBRMaterials, the light intensity can be set to PI. This will cancel out the 1/PI factor from the PBR rendering.

A more physically-based DirectionalLight setup can leverage the IntensityMode to specify the light in physical units (e.g., lux or nits).

Rendering Pipeline

To allow for dynamic range and accurate lighting calculations, the DefaultRenderingPipeline can be used.

const pipeline = new DefaultRenderingPipeline("Default", true /* hdr */, scene);
pipeline.imageProcessingEnabled = true;
pipeline.imageProcessing.toneMappingEnabled = true;
pipeline.imageProcessing.ditheringEnabled = true;

Tonemapping can be enabled to better handle the high dynamic range of the atmosphere, and dithering will help reduce color banding in the sky.

Customizing the Atmosphere

Create the atmosphere by passing the directional light.

const atmosphere = new Atmosphere("atmosphere", scene, [light]);
// True if rendering to an HDR target (e.g. DefaultRenderingPipeline with hdr: true)
atmosphere.isLinearSpaceComposition = true;
// True if light value in the scene is expected to be linear (e.g. PBRMaterials)
atmosphere.isLinearSpaceLight = true;

By default, Earth-like scattering parameters and dimensions are used. This can be further customized.

Rayleigh Scattering

Rayleigh scattering can have a strong effect on the overall color of the atmosphere.

atmosphere.physicalProperties.peakRayleighScattering = new Vector3(0.001, 0.034, 0.001); // r, g, b

Mie Scattering and Absorption

Mie scattering and absorption affect the haziness of the atmosphere.

atmosphere.physicalProperties.mieScatteringScale = 100;

Ozone Absorption

Ozone absorption can also affect the color of the atmosphere.

atmosphere.physicalProperties.ozoneAbsorptionScale = 5;

Multiple Scattering

Multiple scattering simulates light within the atmosphere that has scattered more than once. This affects the brightness of the atmosphere but can also affect the overall color, especially depending on the ground albedo.

atmosphere.multiScatteringIntensity = 4.0;
atmosphere.groundAlbedo = new Color3(1.0, 0.2, 0.2);

Optimization and Quality

By default, the atmosphere uses lookup tables (LUTs) for improved efficiency. To fall back to the more expensive but higher-quality ray marching, use the following properties.

atmosphere.isAerialPerspectiveLutEnabled = false;
atmosphere.isSkyViewLutEnabled = false;

Time of Day

The atmosphere can simulate different times of day by changing the direction of the light.

Typically, a -Y light direction can be used for a directly overhead sun, although this depends on what is considered the up-vector of the scene.

// Assuming +Y is up
light.direction = new Vector3(0, -1, 0); // Day
light.direction = new Vector3(0, 1, 0); // Night
light.direction = new Vector3(1, 0, 0); // Sunrise/Sunset

To simulate night, a minimum multiple scattering intensity can be set. This maintains some ambient light in the atmosphere even when the sun is below the horizon.

atmosphere.minimumMultiScatteringIntensity = 0.1;

Disposal

When the atmosphere is no longer needed, call dispose() to release all GPU resources and remove it from the scene:

atmosphere.dispose();