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

Source: https://doc.babylonjs.com/addons/atmosphere

# 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.

- [Playground: Default Atmosphere](https://playground.babylonjs.com/#K1Y1Q8#82) - The default atmosphere with a globe toggle.

## Installation

The atmosphere addon is available as an ES6 NPM package:

```shell
npm install @babylonjs/addons --save
```

and as a UMD NPM package:

```shell
npm install babylonjs-addons --save
```

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

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

> [!NOTE]
> The atmosphere requires WebGPU or WebGL2. Call `Atmosphere.IsSupported(engine)` before creating an instance to verify the engine is compatible.

## Scene Setup

### PBRMaterial

For rendering objects within the atmosphere, it is recommended to use [physically based materials (PBR)](https://doc.babylonjs.com/features/featuresDeepDive/materials/using/introToPBR).

- [Playground: PBR Integration](https://playground.babylonjs.com/#K1Y1Q8#94) - A PBR sphere rendered within the atmosphere.

<br/>
<br/>

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`.

```javascript
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 `PBRMaterial`s, 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](https://doc.babylonjs.com/features/featuresDeepDive/materials/using/masterPBR#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.

```javascript
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.

```javascript
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.

- [Playground: Green Rayleigh Scattering](https://playground.babylonjs.com/#K1Y1Q8#83) - Create a green sky by increasing Rayleigh scattering in the green channel.

```javascript
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.

- [Playground: Increased Mie Scattering](https://playground.babylonjs.com/#K1Y1Q8#84) - Increased Mie scattering for a hazier atmosphere.

```javascript
atmosphere.physicalProperties.mieScatteringScale = 100;
```

### Ozone Absorption

Ozone absorption can also affect the color of the atmosphere.

- [Playground: Increased Ozone Absorption](https://playground.babylonjs.com/#K1Y1Q8#85) - Increased ozone absorption for a deeper blue sky.

```javascript
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.

- [Playground: Increased Multiple Scattering](https://playground.babylonjs.com/#K1Y1Q8#86) - Increased multiple scattering and red ground albedo.

```javascript
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.

- [Playground: Full Ray Marching](https://playground.babylonjs.com/#K1Y1Q8#87) - The default atmosphere with full ray marching.

```javascript
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.

- [Playground: Day-Night Animation](https://playground.babylonjs.com/#K1Y1Q8#90) - Simulating different times of day by animating the sun position.

```javascript
// 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.

```javascript
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:

```javascript
atmosphere.dispose();
```
