An equirectangular HDR skybox-image

Since the environment map represents scene lighting, it requires extremely high dynamic range to realistically represent either natural or artificial scenes. Traditionally the .hdr image format was used for this purpose (and is supported here), but it has poor compression. Recently, the UltraHDR image format was introduced which is backwards-compatible with JPEG, still called .jpg but efficiently compresses HDR image data. The examples on this page use UltraHDR to showcase its 10x - 30x savings over .hdr. You can use this free converter to compress your .hdr and .exr environment images - choose save as JPEG.

Ground-projected Skybox

This is an example of an equirectangular skybox-image projected onto the ground using a 1.5 meter skybox-height, denoting the height of the camera that took the image. If the camera's height is unknown, a larger value will cause the image below the model to expand. Generally it is best to have a height similar to the size of your model.

Note that ground-projected skyboxes work best with images where the ground is fairly flat and devoid of objects, and the horizon is distant. Indoor images will generally give poor results.

Unlit Model

An equirectangular ground-projected skybox-image with an unlit model

Use environment-image to set environmental lighting without changing the background

Showing the difference between our two baked-in lighting environments

If no environment or skybox is specified, we have a baked-in default scene that is faster to load. It is designed as a neutral lighting environment that is evenly lit on all sides, but there is also a baked-in legacy lighting primarily for frontward viewing, and can be activated by setting environment-image="legacy". Our default neutral lighting has been roughly calibrated to render colors at nearly their baseColorMap RGB values.

Comparing tone mapping

Tone mapping is the critical last stage of the rendering pipeline that controls the final look of your model. It is necessary because the reflections are often much brighter than a screen can reproduce, so they must be smoothly mapped into the sRGB range, ideally while avoiding clipping artifacts or hue shifts. The image sensor and processing on a digital camera performs a similar step.

Khronos PBR Neutral is our new tone mapper, designed specifically for the color accuracy needs of e-commerce. It is guaranteed to avoid all hue shifts, has a relatively sharp rolloff in intensity, and a slower progression to white. This is designed to pass the widest range of base color values through unchanged to the screen, while preserving enough headroom for highlights to show well. Neutral is now our default as of v4.0.

ACES is a film industry standard that is widely used in graphics and was our default tone mapper prior to v4.0. However, it produces serious hue shifts and extreme desaturation, making bright yellow and cyan unattainable under any lighting. See for yourself in this example.

AgX is a relatively new tone mapper that is getting a lot of adoption in graphics. It has less hue shifting than ACES and may be a good option for matching existing artist workflows, but has the same drawback of significant desaturation. However, in more artistic scenes this can be beneficial since it allows for a slower intensity rolloff.

For an apples-to-apples comparison of ACES to Neutral with custom lighting, set the Neutral exposure to 1 and the ACES exposure to 0.77 to account for ACES being artificially bright. This compensation is automatic for our built-in lighting.

Control render exposure with exposure

Control shadow with shadow-intensity and shadow-softness

An equirectangular HDR skybox-image

An equirectangular LDR skybox-image

Note that if you have multiple <model-viewer> elements visible on a page with skyboxes, it is important to be consistent in using either HDR, LDR, or separate environment and skybox for all visible elements. When combining them (as in these examples), there is a serious performance problem, which you will probably notice depending on which examples are currently in your viewport. As this edge case is unlikely anywhere outside of these example pages, it may be some time before it is fixed in three.js.

Supports different resolutions of skybox-image and environment-image images

Environment images should be no more than 1k (1024x512) as they are clamped to this resolution internally. If one needs a higher resolution skybox, then two images must be supplied: a high-res JPEG for the skybox-image and a matching 1k (or less) HDR for the environment-image. Due to compression efficiency, the 4k JPEG and 1k HDR images below are each about 1.5Mb, despite the JPEG having 16 times as many pixels. However, HDR is still recommended for lighting as it yields much more realistic results.