Setting Background Color and Images

The Background in threepipe is managed by the scene in the viewer.

It can be set to a color(using scene.setBackgroundColor), a flat 2d or environment map texture(using scene.background), or both. When both are set, the color is multiplied with the texture, so it can be used to tint the background.

The final intensity(brightness) of the background can also be controlled with the scene.backgroundIntensity property on the scene.

Background Color

To set the background color, use the setBackgroundColor method on the scene. This will set a solid color as the background.

viewer.scene.setBackgroundColor(0x000000); // Set background to black

INFO

The color passed in can be a number (0xff00ff), a string('#ff00ff', 'rgba(255, 0, 255, 1)'), or a Color object.

It will be converted to a Color object internally and set to the backgroundColor property of the scene.

To remove the background color, set it to null:

viewer.scene.setBackgroundColor(null); // Remove background color

To get the current background color, access the backgroundColor property of the scene:

const currentColor = viewer.scene.backgroundColor; // Get current background color
console.log('#' + currentColor.getHexString()); // Log color in hex format

Background Texture

An Image/Texture can be set as the background using the viewer.setBackgroundMap function by passing in a url, IAsset, File object or a loaded Texture.

viewer.setBackgroundMap('https://example.com/path/to/texture.jpg'); // Set background texture
// or load an env map as background
viewer.setBackgroundMap('https://example.com/path/to/envmap.hdr', { 
    setEnvironment: true // if set to true, the environment map will also be set as the scene's background
});
// or set the background property directly
viewer.scene.background = viewer.load<ITexture>('https://example.com/path/to/texture.jpg')

If a color is set, it will be multiplied with the texture, allowing you to tint the background.

To remove the background texture, simply set it to null:

viewer.setBackgroundMap(null)
// or 
viewer.scene.background = null;

TIP

When setting a flat texture as the background, it will be stretched to fill the entire viewport.

This can be changed by either setting the mapping property of the texture to EquirectangularReflectionMapping. (it is set automatically when loading an appropriate HDR/EXR texture)

Transparent Background

To set a transparent background, you can set both the scene.background and scene.backgroundColor to null.

viewer.scene.background = null; // Remove background texture
viewer.scene.setBackgroundColor(null); // Remove background color

RGBM Rendering Mode

ThreeViewer uses rgbm rendering by default, which doesn't directly support transparent backgrounds.

To use transparent background with rgbm mode, clipBackground function in ViewerRenderManager.screenPass is used. This clips/removes the background color from the final render, allowing for a transparent background effect.

Clip Background

In many cases, you may want to render the background color so that it can be used by plugins/post-processing effects like bloom, reflections, etc but composite the render with transparency over other content.

This can be achieved by setting the clipBackground property of ScreenPass in the ViewerRenderManager. This renders the background color and texture normally, but clips it from the final render, allowing for a transparent background effect.

viewer.renderManager.screenPass.clipBackground = true; // Enable clipping of background

Note that this is also automatically set when using rgbm rendering mode, and null for the background. But it will render the background first as black and clip it. So, when using rgbm, set the background color to an ideal color for the scene and use clipBackground to remove it.

Background Intensity

The intensity of the background can be controlled using the backgroundIntensity property of the scene. This property is a multiplier for the background color and texture.

This allows you to adjust the brightness of the background without changing the color or texture itself and even achieve greater than 100% brightness backgrounds for HDR rendering

viewer.scene.backgroundIntensity = 0.5; // Set background intensity to 50%
viewer.scene.backgroundIntensity = 5; // Set background intensity to 500%

Pan/Scale Background

To adjust the position or scale of the background texture, you can modify the offset, center, repeat, rotation properties of the texture. This allows you to pan or scale the background texture as needed.

const backgroundTexture = viewer.scene.background;
if (backgroundTexture) {
    backgroundTexture.offset.set(0.1, 0.1); // Move texture by 10% in both x and y directions
    backgroundTexture.repeat.set(2, 2); // Repeat texture twice in both x and y directions
    backgroundTexture.rotation = Math.PI / 4; // Rotate texture by 45 degrees
}

For equirect textures, rotation can be set to rotate the texture around the y-axis, which can be useful for adjusting the orientation of the environment map.

if (backgroundTexture && backgroundTexture.mapping === EquirectangularReflectionMapping) {
    backgroundTexture.rotation = Math.PI / 2; // Rotate environment map by 90 degrees
}

Serialization

The background color and texture can be serialized to JSON along with the scene.

Since the scene object is part of the viewer configuration when saving a glb with config, it is also saved and applied when loading the glb.

The serialization supports colors, image urls, embedded textures with formats that require external loaders like HDR, EXR, etc.