three-gpu-pathtracer

npm version build github twitter sponsors

Path tracing project using three-mesh-bvh and WebGL 2 to accelerate high quality, physically based rendering on the GPU. Features include support for GGX surface model, material information, textures, normal maps, emission, environment maps, tiled rendering, and more!

More features and capabilities in progress!

Examples

Setup

Basic glTF Setup Example

Basic Primitive Geometry Example

Beauty Demos

Physically Based Materials

Lego Models

Interior Scene

Depth of Field

Features

Skinned Geometry Support

Morph Target Support

Area Light Support

Spot Light Support

Volumetric Fog Support

Test Scenes

Material Test Orb

Transmission Preset Orb

Model Viewer Fidelity Scene Comparisons

Physical Material Database

Tools

Animation Rendering

Ambient Occlusion Material

Running examples locally

To run and modify the examples locally, make sure you have Node and NPM installed. Check the supported versions in the test configuration.

In order to install dependencies, you will need make and a C++ compiler available.

On Debian or Ubuntu, run sudo apt install build-essential. It should just work on MacOS.

Use

Basic Renderer

import * as THREE from 'three';
import { WebGLPathTracer } from 'three-gpu-pathtracer';

// init scene, camera, controls, etc

renderer = new THREE.WebGLRenderer();
renderer.toneMapping = THREE.ACESFilmicToneMapping;

pathTracer = new WebGLPathTracer( renderer );
pathTracer.updateScene( camera, scene );

animate();

function animate() {

	requestAnimationFrame( animate );
	pathTracer.renderSample();

}

Blurred Environment Map

Using a pre blurred envioronment map can help improve frame convergence time at the cost of sharp environment reflections. If performance is concern then multiple importance sampling can be disabled and blurred environment map used.

import { BlurredEnvMapGenerator } from 'three-gpu-pathtracer';

// ...

const envMap = await new RGBELoader().setDataType( THREE.FloatType ).loadAsync( envMapUrl );
const generator = new BlurredEnvMapGenerator( renderer );
const blurredEnvMap = generator.generate( envMap, 0.35 );

// render!

Exports

WebGLPathTracer

constructor

constructor( renderer : WebGLRenderer )

Pass through functions and fields:

// members
toneMapping,
domElement,

// functions
getPixelRatio,
setPixelRatio,
setDrawingBufferSize,
getDrawingBufferSize,
getSize,
setSize,
setViewport,
getViewport,
getScissor,
setScissor,
getScissorTest,
setScissorTest,
getClearAlpha,
setClearAlpha,
getClearColor,
setClearColor,

.bounces

bounces = 10 : Number

.filteredGlossyFactor

filteredGlossyFactor = 0 : Number

.tiles

tiles = ( 1, 1 ) : Vector2

.dynamicLowRes

dynamicLowRes = false : Boolean

.lowResScale

lowResScale = 0.1 : Number

.renderScale

renderScale = 1 : Number

.synchronizeRenderSize

synchronizeRenderSize = true : Boolean

.rasterizeScene

rasterizeScene = true : Boolean

.renderToCanvas

renderToCanvas = true : Boolean

.textureSize

textureSize = ( 1024, 1024 ) : Vector2

.samples

get samples : Number

.target

get target : WebGLRenderTarget

.updateScene

updateScene( camera : Camera, scene : Scene ) : void

.updateSceneAsync

updateSceneAsync(
	camera : Camera,
	scene : Scene,
	options = {
		onProgress = null : value => void,
	} : Object
) : void

.renderSample

renderSample() : void

.reset

reset() : void

.dispose

dispose() : void

PhysicalCamera

extends THREE.PerspectiveCamera

An extension of the three.js PerspectiveCamera with some other parameters associated with depth of field. These parameters otherwise do not affect the camera behavior are are for convenience of use with the PhysicalCameraUniform and pathtracer.

.focusDistance

focusDistance = 25 : Number

The distance from the camera in meters that everything is is perfect focus.

.fStop

fStop = 1.4 : Number

The fstop value of the camera. If this is changed then the bokehSize field is implicitly updated.

.bokehSize

bokehSize : Number

The bokeh size as derived from the fStop and focal length in millimeters. If this is set then the fStop is implicitly updated.

.apertureBlades

apertureBlades = 0 : Number

The number of sides / blades on the aperture.

.apertureRotation

apertureRotation = 0 : Number

The rotation of the aperture shape in radians.

.anamorphicRatio

anamorphicRatio = 1 : Number

The anamorphic ratio of the lens. A higher value will stretch the bokeh effect horizontally.

EquirectCamera

extends THREE.Camera

A class indicating that the path tracer should render an equirectangular view. Does not work with three.js raster rendering.

PhysicalSpotLight

extends THREE.SpotLight

.radius

radius = 0 : Number

The radius of the spotlight surface. Increase this value to add softness to shadows.

.iesTexture

iesTexture = null : Texture

The loaded IES texture describing directional light intensity. These can be loaded with the IESLoader.

Premade IES profiles can be downloaded from [ieslibrary.com]. And custom profiles can be generated using CNDL.

ShapedAreaLight

extends THREE.RectAreaLight

.isCircular

isCircular = false : Boolean

Whether the area light should be rendered as a circle or a rectangle.

IESLoader

extends Loader

Loader for loading and parsing IES profile data. Load and parse functions return a DataTexture with the profile contents.

BlurredEnvMapGenerator

Utility for generating a PMREM blurred environment map that can be used with the path tracer.

constructor

constructor( renderer : WebGLRenderer )

.generate

generate( texture : Texture, blur : Number ) : DataTexture

Takes a texture to blur and the amount to blur it. Returns a new DataTexture that has been PMREM blurred environment map that can have distribution data generated for importance sampling.

.dispose

dispose() : void

Disposes of the temporary files and textures for generation.

GradientEquirectTexture

.exponent

exponent = 2 : Number

.topColor

topColor = 0xffffff : Color

.bottomColor

bottomColor = 0x000000 : Color

constructor

constructor( resolution = 512 : Number )

.update

update() : void

MaterialBase

extends THREE.ShaderMaterial

Convenience base class that adds additional functions and implicitly adds object definitions for all uniforms of the shader to the object.

.setDefine

setDefine( name : string, value = undefined : any ) : void

Sets the define of the given name to the provided value. If the value is set to null or undefined then it is deleted from the defines of the material. If the define changed from the previous value then Material.needsUpdate is set to true.

FogVolumeMaterial

extends MeshStandardMaterial

A material used for rendering fog-like volumes within the scene. The color, emissive, and emissiveIntensity fields are all used in the render.

NOTE Since fog models many particles throughout the scene and cause many extra bounces fog materials can dramatically impact render time.

.density

The particulate density of the volume.

DenoiseMaterial

extends MaterialBase

Denoise material based on BrutPitt/glslSmartDeNoise intended to be the final pass to the screen. Includes tonemapping and color space conversions.

Uniforms

{

	// sigma - sigma Standard Deviation
	// kSigma - sigma coefficient
	// kSigma * sigma = radius of the circular kernel
	sigma = 5.0 : Number,
	kSigma = 1.0 : Number,

	// edge sharpening threshold
	threshold = 0.03 : Number,

}

CompatibilityDetector

Detects whether the path tracer can run on the current device by checking whether struct precision is reliable and the material shader will compile.

constructor

constructor( renderer : WebGLRenderer, material : Material )

Takes a WebGLRenderer to use and material to test again.

.detect

detect() : {
	pass: Boolean,
	message: String
}

Returns pass === true if the path tracer can run. If it cannot run then a message is returned indicating why.

Gotchas

Screenshots

Sample materials

"SD Macross City Standoff Diorama" scene by tipatat

"Interior Scene" model by Allay Design

Perseverance Rover, Ingenuity Helicopter models by NASA / JPL-Caltech

Gelatinous Cube model by glenatron

Lego models courtesy of the LDraw Official Model Repository

Octopus Tea model by AzTiZ

Botanists Study model by riikkakilpelainen

Japanese Bridge Garden model by kristenlee

Resources

Raytracing in One Weekend Book

PBR Book

knightcrawler25/GLSL-PathTracer

DassaultSystemes-Technology/dspbr-pt