Lens Blur

Depth-of-field camera blur driven by a depth map. Bokeh-shaped, depth-aware blur with focus controls — the foundation for cinematic shallow focus.

Category: Effects Menu path: Effects > Lens Blur

Ports

Port	Type	Direction	Description
in	imageRgba16f	input	The image to blur
depth_in	imageRgba16f	input	Depth map: a grayscale image where pixel value = distance. From the Generate Depth Map AI node, a 3D render's Z/depth AOV, or any image. Disconnected → passthrough (no blur).
kernel_in	imageRgba16f	input	Optional custom bokeh aperture. A grayscale image (white = light passes) defines the bokeh shape — like a real lens aperture / Redshift's bokeh image. PNG, EXR (linear float), HDR, etc. all work — wire an Image Source pointing at the kernel file. It's sampled in its own space (any size, centered), so it fills the disc regardless of comp size. Overrides bokehShape when connected.
out	imageRgba16f	output	The depth-of-field result

Expose channels (the "E" button on the node) add scalar input ports — Focus, Strength, Max Radius — that drive focusDistance / blurStrength / maxRadius from the graph (e.g. a rack-focus animated or tracked from another node).

Parameters

Focus

Param	Type	Default	Description
focusDistance	scalar	0.5	The depth value (0–1) that stays sharp — the focal plane. Animate it for a focus pull.
focusRange	scalar	0.2	Width of the in-focus band around focusDistance. Larger = deeper depth of field.
blurStrength	scalar	0.5	How quickly things blur as they leave the focus band. Higher = a tighter focus transition.
maxRadius	scalar	100	Bokeh size — the maximum blur radius in pixels (the circle of confusion for fully out-of-focus areas). Raise it for bigger, more dramatic bokeh; it also sets how far a blurry foreground bleeds.

Near / Far

Param	Type	Default	Description
nearBlur	scalar	1.0	Multiplier for foreground blur (depth nearer than focus).
farBlur	scalar	1.0	Multiplier for background blur (depth farther than focus).

Bokeh

Param	Type	Default	Description
bokehShape	enum	Polygon	Aperture shape: Circle, Polygon (blade count), Ring (catadioptric / mirror-lens donut), Star. Ignored when a kernel_in image is connected.
bokehBlades	scalar	6	Sides for Polygon / points for Star.
bokehRotation	scalar	0	Rotates the bokeh shape (degrees).
edgeFeather	scalar	0.1	How soft each bokeh disc's edge is. 0 = crisp, defined discs (busy/highlight bokeh); 1 = fully soft/creamy. Raise it if blurry regions look like they end in a hard ring.
highlightBoost	scalar	10	Emphasis on bright out-of-focus samples, so highlights bloom into bokeh discs.
highlightThreshold	scalar	0.2	Luma above which a sample counts as a highlight.

Depth

Param	Type	Default	Description
depthChannel	enum	Luminance	Which channel of depth_in carries depth (Luminance / Red / Green / Blue / Alpha).
invertDepth	boolean	false	Flip the near/far convention. AI depth maps and 3D Z passes disagree on whether near is bright or dark — toggle this if focus feels backwards.

Settings

Param	Type	Default	Description
denoise	scalar	0.2	Strength of the out-of-focus denoise (0 = off, skips the pass). Lower it if the denoise is softening bokeh detail you want to keep.
repeatEdges	boolean	true	Repeat edge pixels so the blur doesn't pull transparency in at the frame / layer edge. Turn off if you want the blur to fade into transparency at content edges.
quality	enum	High	Gather sample count: Draft (24) / Normal (48) / High (160) / Ultra (320). Higher = smoother bokeh (esp. large blur + custom kernels), at more cost.

How It Works

For each pixel, Lens Blur computes a circle of confusion (CoC) from how far its depth is from focusDistance, then gathers its samples over a radius matched to that CoC (expanding it via a short probe when a blurrier foreground sits close enough to bleed in). Because the taps scale to the blur actually needed, every pixel — in focus, half-blurred, or fully defocused — gets the full sample budget, so the focus→defocus falloff is smooth rather than a hard, undersampled band. Each sample reads the color and depth and contributes only if its own blur disc reaches the pixel being shaded ("scatter-as-gather"), so a blurry foreground bleeds over a sharper background while in-focus regions stay crisp.

Bokeh shape comes from masking the sample disc to a regular polygon (bokehBlades); bright out-of-focus samples are boosted (highlightBoost) so specular highlights bloom into aperture-shaped discs — the look that sells a real lens.

The blur radius is computed in composition pixels, so it stays visually consistent across Draft / Preview / Full quality. The gather pattern is jittered per pixel (so it doesn't read as a structured grid) and a final depth-aware denoise pass cleans up the resulting noise in out-of-focus regions — both automatic.

Usage Examples

Cinematic shallow focus from an AI depth map

ImageSource → LensBlur.in, and ImageSource → Generate Depth Map → LensBlur.depth_in. Set focusDistance to the depth of your subject (toggle invertDepth if focus lands on the wrong plane), raise maxRadius for a shallower look, and shape the bokeh with bokehBlades.

Focus pull

Keyframe focusDistance from the foreground subject's depth to the background's — the focal plane racks between them over time.

3D / AOV depth

Feed a render's Z or depth AOV into depth_in, pick the right depthChannel, and set invertDepth to match the pass's convention (linear Z is often near=dark).

Tips

• If everything blurs (or nothing does), check invertDepth and depthChannel first — depth conventions vary.
• focusRange controls how much stays sharp; blurStrength controls how hard the falloff is. Tune them together.
• Higher bokehBlades (8+) approximates a rounded aperture; 5–6 gives classic polygonal bokeh.
• Custom bokeh: wire a grayscale aperture image (white = light passes) into kernel_in — hearts, stars, anamorphic ovals, dirty/realistic apertures. It overrides bokehShape. A Ring shape mimics mirror-lens "donut" bokeh.
• repeatEdges is on by default so full-frame footage doesn't get a transparent halo at the frame edge; turn it off for a layer that should blur into transparency.
• quality: High is best for final renders; Draft keeps scrubbing responsive.

Limitations

• Single-pass gather: an in-focus subject against a very blurry background can show a faint edge halo. True near/far field separation (which removes it) is a planned enhancement.
• No chromatic fringing or anamorphic (elliptical) bokeh yet.

Related Nodes

• Generate Depth Map — AI depth map to drive this node
• Blur — uniform / blur-map gaussian blur (not depth-aware)