@threlte/extras

<Environment>

Scene environment map implementation with included loaders and ground projected environment.

Usage

Pass absolute path to path. For example, if you are using sveltekit and you put your files in static/envmap/hdr then path will be /envmap/hdr/

The component decides whether to use cubic or equirectangular map based on the files prop. Provide a string array for cubic or a string for equirectangular.

Currently supported formats are ‘ldr’ (.jpg, .png, etc.) and ‘hdr’ .hdr. Format is inferred based on file extension but it can be provided in format prop.

isBackground prop controls if environment is set as the background of scene. This is not related to GroundProjection which produces a faux background effect by creating a spherical object textured by the provided environment.

To enable GroundProjection pass a configuration object as a groundProjection prop. The most common use case is to pass radius, height and scale ({ radius: 200, height: 5, scale: {x: 100,y: 100,z: 100}) however, you can pass any props you would pass THREE.Mesh since it is built as its extension.

<!-- Cubic jpg envmap -->
<Environment
  path="/envmap/bridge_cube/"
  files={['posx.jpg', 'negx.jpg', 'posy.jpg', 'negy.jpg', 'posz.jpg', 'negz.jpg']}
  isBackground={true}
  format="ldr"
  groundProjection={{ radius: 200, height: 5, scale: { x: 100, y: 100, z: 100 } }}
/>

<!-- Equirectangular jpg envmap -->
<Environment
  path="/envmap/"
  files="pisa_1k.jpg"
  isBackground={true}
/>

<!-- Cubic hdr envmap -->
<Environment
  path="/envmap/pisaHdr/"
  files={[['px.hdr', 'nx.hdr', 'py.hdr', 'ny.hdr', 'pz.hdr', 'nz.hdr']]}
  isBackground={true}
  groundProjection={{ radius: 200, height: 5, scale: { x: 100, y: 100, z: 100 } }}
/>

<!-- Equirectangular hdr envmap -->
<Environment
  path="/envmap/"
  files="shanghai_riverside_1k.hdr"
  isBackground={true}
  format="hdr"
  groundProjection={{ radius: 200, height: 5, scale: { x: 100, y: 100, z: 100 } }}
/>

Component Signature

Props

name
type
required
description

files
string | string[]
yes
Provide a string to use an equirectangular envmap and a string array to use a cubic envmap

encoding
TextureEncoding
no
Envmap `TextureEncoding`. If not provided it defaults to `sRGBEncoding` for cubemap and `LinearEncoding` for equirectangular

format
'ldr' | 'hdr'
no
Use `ldr` for .png, .jpg and `hdr` for .hdr file formats

groundProjection
Props<GroundProjectedEnv>
no
Props for ground projection. Scalar recommended to 100. Depending on envmap and project requirements, good starting point is radius: 200, height: 5.

isBackground
boolean
no
Boolean to toggle whether to use envmap as a scene background.

path
string
no
Defaults to "/"