SAO

Configures Scalable Ambient Obscurance (SAO) for a Scene.

[Run this example]

Overview

SAO approximates Ambient Occlusion in realtime. It darkens creases, cavities and surfaces that are close to each other, which tend to be occluded from ambient light and appear darker.

The animated GIF above shows the effect as we repeatedly enable and disable SAO. When SAO is enabled, we can see darkening in regions such as the corners, and the crevices between stairs. This increases the amount of detail we can see when ambient light is high, or when objects have uniform colors across their surfaces. Run the example to experiment with the various SAO configurations.

xeokit's implementation of SAO is based on the paper Scalable Ambient Obscurance.

Caveats

Currently, SAO only works with perspective and orthographic projections. Therefore, to use SAO, make sure Camera#projection is either "perspective" or "ortho".

SAO#scale and SAO#intensity must be tuned to the distance between Perspective#near and Perspective#far, or the distance between Ortho#near and Ortho#far, depending on which of those two projections the Camera is currently using. Use the live example to get a feel for that.

Usage

In the example below, we'll start by logging a warning message to the console if SAO is not supported by the system.

Then we'll enable and configure SAO, position the camera, and configure the near and far perspective and orthographic clipping planes. Finally, we'll use XKTLoaderPlugin to load the OTC Conference Center model.

import {Viewer, XKTLoaderPlugin} from "xeokit-sdk.es.js";

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

const sao = viewer.scene.sao;

if (!sao.supported) {
    sao.warn("SAO is not supported on this system - ignoring SAO configs")
}

sao.enabled = true; // Enable SAO - only works if supported (see above)
sao.intensity = 0.15;
sao.bias = 0.5;
sao.scale = 1.0;
sao.minResolution = 0.0;
sao.numSamples = 10;
sao.kernelRadius = 100;
sao.blendCutoff = 0.1;

const camera = viewer.scene.camera;

camera.eye = [3.69, 5.83, -23.98];
camera.look = [84.31, -29.88, -116.21];
camera.up = [0.18, 0.96, -0.21];

camera.perspective.near = 0.1;
camera.perspective.far = 2000.0;

camera.ortho.near = 0.1;
camera.ortho.far = 2000.0;
camera.projection = "perspective";

const xktLoader = new XKTLoaderPlugin(viewer);

const model = xktLoader.load({
    id: "myModel",
    src: "./models/xkt/OTCConferenceCenter.xkt"
    edges: true
});

[Run this example]

Efficiency

SAO can incur some rendering overhead, especially on objects that are viewed close to the camera. For this reason, it's recommended to use a low value for SAO#kernelRadius. A low radius will sample pixels that are close to the source pixel, which will allow the GPU to efficiently cache those pixels. When Camera#projection is "perspective", objects near to the viewpoint will use larger radii than farther pixels. Therefore, computing SAO for close objects is more expensive than for objects far away, that occupy fewer pixels on the canvas.

Selectively enabling SAO for models

When loading multiple models into a Scene, we sometimes only want SAO on the models that are actually going to show it, such as the architecture or structure, and not show SAO on models that won't show it well, such as the electrical wiring, or plumbing.

To illustrate, lets load some of the models for the West Riverside Hospital. We'll enable SAO on the structure model, but disable it on the electrical and plumbing.

This will only apply SAO to those models if SAO#supported and SAO#enabled are both true.

Note, by the way, how we load the models in sequence. Since XKTLoaderPlugin uses scratch memory as part of its loading process, this allows the plugin to reuse that same memory across multiple loads, instead of having to create multiple pools of scratch memory.

const structure = xktLoader.load({
     id: "structure",
     src: "./models/xkt/WestRiverSideHospital/structure.xkt"
     edges: true,
     saoEnabled: true
 });

 structure.on("loaded", () => {

     const electrical = xktLoader.load({
         id: "electrical",
         src: "./models/xkt/WestRiverSideHospital/electrical.xkt",
         edges: true
     });

     electrical.on("loaded", () => {

         const plumbing = xktLoader.load({
             id: "plumbing",
             src: "./models/xkt/WestRiverSideHospital/plumbing.xkt",
             edges: true
         });
     });
});

Disabling SAO while camera is moving

For smoother interaction with large models on low-power hardware, we can disable SAO while the Camera is moving:

const timeoutDuration = 150; // Milliseconds
var timer = timeoutDuration;
var saoDisabled = false;

const onCameraMatrix = scene.camera.on("matrix", () => {
    timer = timeoutDuration;
    if (!saoDisabled) {
        scene.sao.enabled = false;
        saoDisabled = true;
    }
});

const onSceneTick = scene.on("tick", (tickEvent) => {
    if (!saoDisabled) {
        return;
    }
    timer -= tickEvent.deltaTime; // Milliseconds
    if (timer <= 0) {
        if (saoDisabled) {
            scene.sao.enabled = true;
            saoDisabled = false;
        }
    }
});

[Run this example]