Accueil / npm / three@0.186.1 / examples / jsm / tsl / display / BilateralBlurNode.js
BilateralBlurNode.js
import { RenderTarget, Vector2, NodeMaterial, RendererUtils, QuadMesh, TempNode, NodeUpdateType } from 'three/webgpu';
import { Fn, float, uv, uniform, convertToTexture, vec2, vec4, passTexture, luminance, abs, exp, max, context } from 'three/tsl';
const _quadMesh = /*@__PURE__*/ new QuadMesh();
let _rendererState;
/**
* Post processing node for creating a bilateral blur effect.
*
* Bilateral blur smooths an image while preserving sharp edges. Unlike a
* standard Gaussian blur which blurs everything equally, bilateral blur
* analyzes the intensity/color of neighboring pixels. If a neighbor is too
* different from the center pixel (indicating an edge), it is excluded
* from the blurring process.
*
* Reference: {@link https://en.wikipedia.org/wiki/Bilateral_filter}
*
* @augments TempNode
* @three_import import { bilateralBlur } from 'three/addons/tsl/display/BilateralBlurNode.js';
*/
class BilateralBlurNode extends TempNode {
static get type() {
return 'BilateralBlurNode';
}
/**
* Constructs a new bilateral blur node.
*
* @param {TextureNode} textureNode - The texture node that represents the input of the effect.
* @param {Node<vec2|float>} directionNode - Defines the direction and radius of the blur.
* @param {number} sigma - Controls the spatial kernel of the blur filter. Higher values mean a wider blur radius.
* @param {number} sigmaColor - Controls the intensity kernel. Higher values allow more color difference to be blurred together.
*/
constructor( textureNode, directionNode = null, sigma = 4, sigmaColor = 0.1 ) {
super( 'vec4' );
/**
* The texture node that represents the input of the effect.
*
* @type {TextureNode}
*/
this.textureNode = textureNode;
/**
* Defines the direction and radius of the blur.
*
* @type {Node<vec2|float>}
*/
this.directionNode = directionNode;
/**
* Controls the spatial kernel of the blur filter. Higher values mean a wider blur radius.
*
* @type {number}
*/
this.sigma = sigma;
/**
* Controls the color/intensity kernel. Higher values allow more color difference
* to be blurred together. Lower values preserve edges more strictly.
*
* @type {number}
*/
this.sigmaColor = sigmaColor;
/**
* A uniform node holding the inverse resolution value.
*
* @private
* @type {UniformNode<vec2>}
*/
this._invSize = uniform( new Vector2() );
/**
* Bilateral blur is applied in two passes (horizontal, vertical).
* This node controls the direction of each pass.
*
* @private
* @type {UniformNode<vec2>}
*/
this._passDirection = uniform( new Vector2() );
/**
* The render target used for the horizontal pass.
*
* @private
* @type {RenderTarget}
*/
this._horizontalRT = new RenderTarget( 1, 1, { depthBuffer: false } );
this._horizontalRT.texture.name = 'BilateralBlurNode.horizontal';
/**
* The render target used for the vertical pass.
*
* @private
* @type {RenderTarget}
*/
this._verticalRT = new RenderTarget( 1, 1, { depthBuffer: false } );
this._verticalRT.texture.name = 'BilateralBlurNode.vertical';
/**
* The result of the effect is represented as a separate texture node.
*
* @private
* @type {PassTextureNode}
*/
this._textureNode = passTexture( this, this._verticalRT.texture );
this._textureNode.uvNode = textureNode.uvNode;
/**
* The material for the blur pass.
*
* @private
* @type {?NodeMaterial}
*/
this._material = null;
/**
* The `updateBeforeType` is set to `NodeUpdateType.FRAME` since the node renders
* its effect once per frame in `updateBefore()`.
*
* @type {string}
* @default 'frame'
*/
this.updateBeforeType = NodeUpdateType.FRAME;
/**
* The resolution scale.
*
* @type {number}
* @default 1
*/
this.resolutionScale = 1;
}
/**
* Sets the size of the effect.
*
* @param {number} width - The width of the effect.
* @param {number} height - The height of the effect.
*/
setSize( width, height ) {
width = Math.max( Math.round( width * this.resolutionScale ), 1 );
height = Math.max( Math.round( height * this.resolutionScale ), 1 );
this._invSize.value.set( 1 / width, 1 / height );
this._horizontalRT.setSize( width, height );
this._verticalRT.setSize( width, height );
}
/**
* This method is used to render the effect once per frame.
*
* @param {NodeFrame} frame - The current node frame.
*/
updateBefore( frame ) {
const { renderer } = frame;
_rendererState = RendererUtils.resetRendererState( renderer, _rendererState );
//
const textureNode = this.textureNode;
const map = textureNode.value;
const currentTexture = textureNode.value;
_quadMesh.material = this._material;
this.setSize( map.image.width, map.image.height );
const textureType = map.type;
this._horizontalRT.texture.type = textureType;
this._verticalRT.texture.type = textureType;
// horizontal
renderer.setRenderTarget( this._horizontalRT );
this._passDirection.value.set( 1, 0 );
_quadMesh.name = 'Bilateral Blur [ Horizontal Pass ]';
_quadMesh.render( renderer );
// vertical
textureNode.value = this._horizontalRT.texture;
renderer.setRenderTarget( this._verticalRT );
this._passDirection.value.set( 0, 1 );
_quadMesh.name = 'Bilateral Blur [ Vertical Pass ]';
_quadMesh.render( renderer );
// restore
textureNode.value = currentTexture;
RendererUtils.restoreRendererState( renderer, _rendererState );
}
/**
* Returns the result of the effect as a texture node.
*
* @return {PassTextureNode} A texture node that represents the result of the effect.
*/
getTextureNode() {
return this._textureNode;
}
/**
* This method is used to setup the effect's TSL code.
*
* @param {NodeBuilder} builder - The current node builder.
* @return {PassTextureNode}
*/
setup( builder ) {
const textureNode = this.textureNode;
//
const uvNode = uv();
const directionNode = vec2( this.directionNode || 1 );
const sampleTexture = ( uv ) => textureNode.sample( uv );
const blur = Fn( () => {
const kernelSize = this.sigma * 2 + 3;
const spatialCoefficients = this._getSpatialCoefficients( kernelSize );
const invSize = this._invSize;
const direction = directionNode.mul( this._passDirection );
// Sample center pixel
const centerColor = sampleTexture( uvNode ).toVar();
const centerLuminance = luminance( centerColor.rgb ).toVar();
// Accumulate weighted samples
const weightSum = float( spatialCoefficients[ 0 ] ).toVar();
const colorSum = vec4( centerColor.mul( spatialCoefficients[ 0 ] ) ).toVar();
// Precompute color sigma factor: -0.5 / (sigmaColor^2)
const colorSigmaFactor = float( - 0.5 ).div( float( this.sigmaColor * this.sigmaColor ) ).toConst();
for ( let i = 1; i < kernelSize; i ++ ) {
const x = float( i );
const spatialWeight = float( spatialCoefficients[ i ] );
const uvOffset = vec2( direction.mul( invSize.mul( x ) ) ).toVar();
// Sample in both directions (+/-)
const sampleUv1 = uvNode.add( uvOffset );
const sampleUv2 = uvNode.sub( uvOffset );
const sample1 = sampleTexture( sampleUv1 );
const sample2 = sampleTexture( sampleUv2 );
// Compute luminance difference for edge detection
const lum1 = luminance( sample1.rgb );
const lum2 = luminance( sample2.rgb );
const diff1 = abs( lum1.sub( centerLuminance ) );
const diff2 = abs( lum2.sub( centerLuminance ) );
// Compute color-based weights using Gaussian function
const colorWeight1 = exp( diff1.mul( diff1 ).mul( colorSigmaFactor ) ).toVar();
const colorWeight2 = exp( diff2.mul( diff2 ).mul( colorSigmaFactor ) ).toVar();
// Combined bilateral weight = spatial weight * color weight
const bilateralWeight1 = spatialWeight.mul( colorWeight1 );
const bilateralWeight2 = spatialWeight.mul( colorWeight2 );
colorSum.addAssign( sample1.mul( bilateralWeight1 ) );
colorSum.addAssign( sample2.mul( bilateralWeight2 ) );
weightSum.addAssign( bilateralWeight1 );
weightSum.addAssign( bilateralWeight2 );
}
// Normalize by the total weight
return colorSum.div( max( weightSum, 0.0001 ) );
} );
//
const material = this._material || ( this._material = new NodeMaterial() );
material.contextNode = context( builder.getSharedContext() );
material.fragmentNode = blur();
material.name = 'Bilateral_blur';
material.needsUpdate = true;
//
const properties = builder.getNodeProperties( this );
properties.textureNode = textureNode;
//
return this._textureNode;
}
/**
* Frees internal resources. This method should be called
* when the effect is no longer required.
*/
dispose() {
super.dispose();
this._horizontalRT.dispose();
this._verticalRT.dispose();
if ( this._material !== null ) this._material.dispose();
}
/**
* Computes spatial (Gaussian) coefficients depending on the given kernel radius.
* These coefficients are used for the spatial component of the bilateral filter.
*
* @private
* @param {number} kernelRadius - The kernel radius.
* @return {Array<number>}
*/
_getSpatialCoefficients( kernelRadius ) {
const coefficients = [];
const sigma = kernelRadius / 3;
for ( let i = 0; i < kernelRadius; i ++ ) {
coefficients.push( 0.39894 * Math.exp( - 0.5 * i * i / ( sigma * sigma ) ) / sigma );
}
return coefficients;
}
}
export default BilateralBlurNode;
/**
* TSL function for creating a bilateral blur node for post processing.
*
* Bilateral blur smooths an image while preserving sharp edges by considering
* both spatial distance and color/intensity differences between pixels.
*
* @tsl
* @function
* @param {Node<vec4>} node - The node that represents the input of the effect.
* @param {Node<vec2|float>} directionNode - Defines the direction and radius of the blur.
* @param {number} sigma - Controls the spatial kernel of the blur filter. Higher values mean a wider blur radius.
* @param {number} sigmaColor - Controls the intensity kernel. Higher values allow more color difference to be blurred together.
* @returns {BilateralBlurNode}
*/
export const bilateralBlur = ( node, directionNode, sigma, sigmaColor ) => new BilateralBlurNode( convertToTexture( node ), directionNode, sigma, sigmaColor );