EnvironmentPlugin

Manages scene environment: HDRI, lighting presets, shadows, and viewer background. Thin wrapper over EnvironmentService.

Usage

const viewer = new ViewerCore(container, {
  plugins: [{ name: "environment", enabled: true }],
});
await viewer.ready();

const env = viewer.pluginManager.getPlugin("environment") as EnvironmentPlugin;
env.setEnvironment("studio");

Or:

await viewer.loadPlugin(new EnvironmentPlugin());

Service dependency: environment.

Public API

Method	Description
setEnvironment(preset: string)	Apply a registered preset (HDRI + lighting + background).
getPresets()	List registered preset names.
registerPreset(name, preset: EnvironmentPreset)	Add a custom preset.
getEnvironmentMap()	Returns the current PMREM-processed env map (`THREE.Texture
setLighting(config: LightingConfig)	Replace lights from a config.
setShadows(enabled, config?: ShadowConfig)	Toggle contact shadows; optional shadow config.
requestShadowUpdate(reason?)	Request a debounced shadow refresh.
updateShadows()	Re-render contact shadows after model bounds or transforms change.
setBackground(background: ViewerBackgroundInput)	Set viewer background (config object, THREE.Color, THREE.Texture, or null).
getBackground()	Current normalized public background config, or null for texture backgrounds.
drawBackgroundToCanvas(context, width, height)	Draw the current viewer background into a canvas context for export.
setHDRI(url: string)	Load and apply an HDRI from URL. Returns a Promise<void>.
setShowEnvironmentBackground(show)	Toggle whether the HDRI is shown as the background.
getShowEnvironmentBackground()	Current background-visibility flag.
setHDRIConfig(config: Partial<HDRIConfig>)	Patch HDRI parameters (intensity, rotation, etc.).
getHDRIConfig()	Current HDRI config.

See EnvironmentService for EnvironmentPreset, LightingConfig, ShadowConfig, and HDRIConfig shapes. ShadowConfig supports the legacy names intensity, blurRadius, and shadowMapSize, plus contact-shadow options such as opacity, blur, resolution, padding, groundOffset, ambientFill, ambientFalloff, autoUpdate, updateDebounceMs, and animationUpdateMs.

Example

const env = viewer.pluginManager.getPlugin("environment") as EnvironmentPlugin;

await env.setHDRI("/hdri/studio.hdr");
env.setHDRIConfig({ intensity: 1.2, rotation: 45 });
env.setShowEnvironmentBackground(false);
env.setBackground({
  type: "gradient",
  shape: "vertical",
  startColor: "#1e293b",
  endColor: "#0f172a",
});
env.setShadows(true, { intensity: 0.45, blurRadius: 4, shadowMapSize: 1024 });