Lens Blur

Filter

Defocuses an image the way a real lens does, uniformly or from a depth pass, with a full lens model for aperture shape, bokeh, aberrations, and bloom.

Where a Gaussian Blur averages pixels evenly, Lens Blur spreads light through an aperture shape: highlights take that shape, bright points turn into bokeh discs, and a defocused foreground spills over a sharp background as it would through a real lens. Both defocus modes run the same lens model.

Defocus modes

• Uniform (default) applies one blur radius across the whole frame and needs no extra input: a soft background or a shallow-focus look on flat artwork. Side of Focus says whether the picture sits in front of or behind the focus plane; it changes only the lens effects that differ by side, such as Spherical Aberration, not the amount of blur.
• Depth Map takes a depth image on the Depth input, the same size as the picture, so near and far fall out of focus around a focus plane. Press Pick Focus in Preview and click the surface that should be sharp to set Focus Position from the depth pass’s own values; drag to watch the focus zones follow the cursor. Blur Amount is the largest blur, reached at the ends of the range, and the Near and Far Blur Multipliers scale it separately on each side of focus.

Connecting a depth image switches Defocus Mode to Depth Map, and connecting an Aperture image switches Aperture Shape to Custom. After that both are ordinary settings you can change back.

Caution

Depth Map mode requires 32-bit (Float) Mode. An 8-bit depth pass has only 256 depth steps, which visibly band the focus falloff, and 3D Render’s Depth output is such a pass in an 8-bit document. In an 8-bit document the Depth Map entry is disabled with an explanation and a Switch to 32-bit Mode button; Uniform works at either bit depth.

Reading the depth input

Depth Encoding tells the node how the depth image’s values map to camera distance.

• Normalized (Black Near), the default, suits a relative or AI-generated depth map with values between 0 and 1. Normalized (White Near) flips it.
• Camera Distance, Inverse Distance, and Device Z decode real distances from a 3D renderer’s pass, using Depth Unit and the near and far bounds. Depth Unit changes what the numbers mean rather than converting them: a Far Distance of 100 is 100 m under m and 100 mm under mm.

Focus Position is stored in the depth image’s own raw values, so changing the encoding or the range never slides focus off the surface you picked. The range is never fitted per frame, so focus and blur stay steady across a sequence.

Wire in a source that carries real distances (the depth output of 3D Render, or any depth image with values outside 0 to 1) and Lens Blur switches to Camera Distance once and sets Far Distance from that source’s maximum, so a render is focused sensibly straight away. Near Distance is left alone, because a camera always sits in front of the nearest surface. Editing the encoding or Far Distance stops the automatic choice; Fit to Depth Input in the Depth section re-runs it on demand, for example after moving the camera.

The Depth input also takes a batch of depth frames, matched one to one against the color batch, so a batched render is blurred with each frame’s own depth. A single depth image is shared by every frame.

Background revealed by blurring is an estimate

A color image plus one depth value per pixel does not contain what is behind a foreground object. Background revealed by blurring the foreground is an estimate, never the real hidden detail.

The lens model

The Lens section builds the aperture: a perfect Circle, a polygon of Blades, or a Custom aperture image wired into the Aperture input, grayscale or color, so you can shape the bokeh yourself.

• Bokeh Aspect stretches the bokeh into an oval, as an anamorphic lens does.
• Cat Eye clips the bokeh into cat-eye shapes toward the frame’s edges and corners, as a real lens does.
• Bokeh Bias is the artistic rim-or-core control: positive brightens the rim for a soap-bubble look, negative brightens the center.
• Spherical Aberration is the physical one: it moves light toward the rim or the core without changing total brightness, and its character reverses across the focus plane.
• CA Type/Balance (shown once Chromatic Aberration is above 0) blends between axial (each color focuses at a different depth) and lateral (colors shift apart toward the frame edges) aberration.
• Bloom boosts bright highlights before the blur, so they spread into bokeh shapes and nearer objects still cover them.
• Highlight Reconstruction (shown once Bloom is on) estimates the brightness clipped highlights lost, so a large blown-out area blooms brighter than a lone bright pixel. It acts only in an 8-bit project; a 32-bit (Float) image already carries its brightness above white.

Six Preset looks (Soft Natural, Crisp Hexagon, Rounded Octagon, Anamorphic, Vintage Bubble, and Dreamy Bloom) set the aperture and lens controls without touching focus, radius, or depth. Neutral restores those controls to their defaults, and Custom means the current settings match no preset.

Mix, edges, and rendering

• Mix blends the result back with the original in premultiplied linear light.
• Edge Mode defaults to Extend, which keeps a dark frame from bleeding into large bokeh; Transparent lets the image fade out at the border.
• Invalid Depth treats areas with no usable depth as Far (default), Near, or No Effect (they stay sharp).

On a supported GPU the blur runs there, falling back to the processor automatically otherwise, with the same result either way.

Quality and speed

A large blur is the slowest thing Lens Blur does: doubling the blur radius roughly quadruples the work. Lens Blur keeps large blurs fast by computing them from a smaller copy of the image, reduced only as far as the blur can hide, while everything in focus stays sharp at full size and blurred foreground is laid back over it. Quality sets how far that reduction may go.

• Full, the default, is exact for any blur up to 128 pixels, and beyond that is visually indistinguishable from an exact render.
• Balanced and Draft reduce further for more speed. The difference shows mostly as softer edges on bright bokeh shapes, so they are good working settings while you set up a shot.
• While you drag a Lens Blur slider, the Preview shows a faster level when the chosen one is slow, and the result at your Quality renders when you let go. Nothing downstream recooks until then.

Parameters

Pins

↳ImageImage

InputRequired

↳DepthMask

InputOptional

↳AperturePixels

InputOptional

↦ImageImage

Output

Defocus

Defocus ModeChoice

Default: Uniform

What drives the blur.

Depth Map needs 32-bit (Float) Mode. Connecting a depth image selects it.

• Depth MapOcclusion-aware defocus driven by the connected depth image. Requires 32-bit (Float) Mode.
• UniformOne constant lens blur across the whole image, with no depth input needed. The default.

Uniform RadiusNumber · px/%

Default: 20.0 Range: 0.0–2048.0 px / 0–100%

Defocus Mode = Uniform

Blur radius applied to the whole image. 0 = no blur.

Side of FocusChoice

Default: Behind

Defocus Mode = Uniform

Whether the image sits in front of or behind the focus plane. Lens effects that differ by side, such as Spherical Aberration, follow this choice

• In FrontTreat the whole image as sitting in front of the focus plane, which flips the side-dependent lens character.
• BehindTreat the whole image as sitting behind the focus plane. The default whole-image treatment.

Focus PositionNumber

Default: 0.5000 Range: -1000000.0000–1000000.0000

Defocus Mode = Depth Map

Depth that is in sharp focus, in the depth image's own values. Pick Focus sets it from a click in the Preview. Values past the slider's near and far ends can still be typed

In-Focus RangeNumber

Default: 0.020 Range: 0.000–1.000

Defocus Mode = Depth Map

Width of the sharp zone around Focus Position, as a fraction of the near-to-far depth range. 0 = a single plane.

Focus TransitionChoice

Default: Smooth

Defocus Mode = Depth Map

How sharpness falls off into blur outside the in-focus range

• LinearBlur ramps up in a straight line from the in-focus interval.
• SmoothA smoothstep ramp into blur. The default.
• SmootherA gentler smootherstep ramp with softer ends.

Blur AmountNumber · px/%

Default: 50.0 Range: 0.0–2048.0 px / 0–100%

Defocus Mode = Depth Map

Maximum blur radius at full defocus. The Near and Far multipliers scale this one value for each side of focus

Near Blur MultiplierNumber

Default: 1.00 Range: 0.00–4.00

Defocus Mode = Depth Map

Scales Blur Amount for everything in front of focus. 1.00x is the full amount; 0 leaves the foreground sharp

Far Blur MultiplierNumber

Default: 1.00 Range: 0.00–4.00

Defocus Mode = Depth Map

Scales Blur Amount for everything behind focus. 1.00x is the full amount; 0 leaves the background sharp

QualityChoice

Default: Full Range: Full / Balanced / Draft

How finely a large blur is computed. Full is exact up to 128 px and stays visually exact beyond it; Balanced and Draft trade bokeh edge detail for speed. In-focus detail always stays sharp

MixNumber

Default: 100 Range: 0–100

Blends the result with the original image. 100% = fully blurred.

Lens

Aperture ShapeChoice

Default: Circle

Shape of the aperture, which out-of-focus highlights take on

• CircleA perfect circular aperture. The default.
• BladesA polygon of 3 to 16 aperture blades, with roundness and rotation.
• CustomAn aperture image wired into the Aperture input shapes the bokeh. Without a valid image the node reports an error rather than falling back to Circle.

BladesInteger

Default: 6 Range: 3–16

Aperture Shape = Blades

Number of aperture blades

Blade RoundnessNumber

Default: 20 Range: 0–100

Aperture Shape = Blades

Blends the polygon toward a circle

RotationNumber

Default: 0 Range: 0–360

Aperture Shape = Blades or Custom

Rotates the aperture shape

Bokeh AspectNumber

Default: 1.00 Range: 0.20–5.00

Stretches the bokeh into an oval, as an anamorphic lens does. 1.0 = round.

Bokeh BiasNumber

Default: 0 Range: -100–100

Brightness across each bokeh disc. Positive brightens the rim for a soap-bubble look, negative brightens the center for a smoother blur. 0 = even.

Aperture Edge SoftnessNumber

Default: 5 Range: 0–100

Softens the rim of each bokeh disc

Cat EyeNumber

Default: 0 Range: 0–100

Clips the bokeh into cat-eye shapes toward the edges and corners of the frame, as a real lens does

Use Kernel ColorToggle

Default: false

Aperture Shape = Custom

Tint the bokeh with the custom aperture image's colors instead of reading it as one grayscale shape

Kernel ChannelChoice

Default: Luminance

Aperture Shape = Custom

Which channel of a color aperture image gives the shape when Use Kernel Color is off

• LuminanceUse the aperture image's brightness as the kernel. The default.
• RedUse the red channel as the kernel.
• GreenUse the green channel as the kernel.
• BlueUse the blue channel as the kernel.
• AlphaUse the alpha channel as the kernel.

Highlights

BloomNumber

Default: 0 Range: 0–100

Boosts bright highlights before the blur, so they spread into glowing bokeh shapes. 0 = off.

Bloom ThresholdNumber

Default: 1.00 Range: 0.00–10.00

Bloom > 0 only

Linear-light brightness above which a pixel blooms

Bloom SoftnessNumber

Default: 25 Range: 0–100

Bloom > 0 only

Softens the cutoff at Bloom Threshold, so highlights fade in gradually

Highlight ReconstructionNumber

Default: 0 Range: 0–100

Bloom > 0 only

Estimates the brightness lost in clipped highlights of an 8-bit image, so a large blown-out area blooms brighter than a single bright pixel. Has no effect in a 32-bit project, where the image already carries that brightness. 0 = off.

Aberrations

Spherical AberrationNumber

Default: 0 Range: -100–100

Moves light in each bokeh disc toward its rim or its core without changing overall brightness. The effect reverses between the near and far side of focus. 0 = off.

Chromatic AberrationNumber

Default: 0 Range: 0–100

Strength of color fringing in the blur. 0 = off.

CA Type/BalanceNumber

Default: -100 Range: -100–100

Chromatic Aberration > 0 only

Which kind of color fringing is used. -100 is fully axial: each color focuses at a different depth. +100 is fully lateral: colors shift apart toward the frame edges. 0 blends both

Depth

Depth EncodingChoice

Default: Normalized (Black Near)

Defocus Mode = Depth Map

How the depth image's values map to distance from the camera.

Connecting real distances picks Camera Distance and sets Far Distance once.

• Normalized (Black Near)Values from 1 (near) to 0 (far).
• Normalized (White Near)Values from 1 (near) to 0 (far).
• Camera DistanceReal distances in the chosen Depth Unit, as a 3D renderer's depth pass stores them. Chosen automatically when a source with real distances is connected.
• Inverse DistanceValues proportional to one over distance, with Inverse Scale as the numerator.
• Device ZA renderer's post-projection depth buffer, decoded with the NDC range, projection, direction, and far-plane rows.

Depth ChannelChoice

Default: Luminance

Defocus Mode = Depth Map

Which channel of a color depth image is read as depth

• LuminanceRead the depth source's brightness. The default.
• AlphaRead the alpha channel as depth.
• RedRead the red channel as depth.
• GreenRead the green channel as depth.
• BlueRead the blue channel as depth.

Clamp DepthToggle

Default: true

Defocus Mode = Depth Map

Clamp out-of-range normalized depth values instead of treating them as invalid

Near ValueNumber

Default: 0.000 Range: 0.000–1.000

Depth Encoding = Normalized (Black Near) or Normalized (White Near)

Depth value at the near end of the range. Normalized (White Near) defaults to 1

Far ValueNumber

Default: 1.000 Range: 0.000–1.000

Depth Encoding = Normalized (Black Near) or Normalized (White Near)

Depth value at the far end of the range. Normalized (White Near) defaults to 0

Near DistanceNumber

Default: 0.100 Range: 0.001–100000.000

Defocus Mode = Depth Map

Nearest distance in the depth image, in Depth Unit. For Device Z, the camera's near plane

Far DistanceNumber

Default: 100.000 Range: 0.001–100000.000

Defocus Mode = Depth Map

Farthest distance in the depth image, in Depth Unit. For Device Z, the camera's far plane

Depth UnitChoice

Default: m

Defocus Mode = Depth Map

Unit of the distances in the depth image and of Near and Far Distance. Changing it changes what the numbers mean, not just their label

• mmInterpret distance values as millimeters.
• cmInterpret distance values as centimeters.
• mInterpret distance values as meters. The default.

Inverse ScaleNumber

Default: 1.000 Range: 0.001–100000.000

Depth Encoding = Inverse Distance

Distance is this number divided by the depth value, in Depth Unit

NDC RangeChoice

Default: 0..1

Depth Encoding = Device Z

Value range the depth buffer was written in

• 0..1Depth buffer values run from 0 to 1 (Direct3D and Vulkan convention). The default.
• -1..1Depth buffer values run from -1 to 1 (OpenGL convention).

ProjectionChoice

Default: Perspective

Depth Encoding = Device Z

Camera projection the depth buffer was rendered with. Orthographic cannot be combined with an Infinite Far Plane

• PerspectiveReconstruct camera distance from a perspective projection. The default.
• OrthographicReconstruct camera distance from an orthographic projection. Cannot be combined with an Infinite far plane.

DirectionChoice

Default: Normal

Depth Encoding = Device Z

Which end of the depth buffer is near

• Normal0 is near. The default.
• Reversed1 is near (reversed-Z depth buffers).

Far PlaneChoice

Default: Finite

Depth Encoding = Device Z

Whether the camera had a far plane. Infinite cannot be combined with an Orthographic Projection

• FiniteThe renderer used a finite far plane at Far Distance. The default.
• InfiniteThe renderer used an infinite far plane. Not valid with an Orthographic projection.

Advanced

Invalid DepthChoice

Default: Far

Defocus Mode = Depth Map

How large areas with no usable depth are treated.

A depth image with no usable values at all is an error.

• FarTreat a large invalid-depth region as far. The default.
• NearTreat a large invalid-depth region as near.
• No EffectLeave a large invalid-depth region unblurred.

Edge ModeChoice

Default: Extend

What the blur reads past the image border

• ExtendClamp sampling to the image edge, so a dark frame never bleeds into large bokeh. The default.
• TransparentLet the image fall away to transparency at the boundary.

Usage Tips

• Start in Uniform mode with a preset, then tune Blades and Bokeh Bias while looking at a bright highlight, where the aperture shape reads.
• For a rack-focus shot, connect a 3D Render node’s depth output to the Depth input and click the model with Pick Focus. The encoding and far distance are fitted for you.
• An AI-generated or hand-painted depth map is normalized: leave Depth Encoding on Normalized (Black Near) and turn on Clamp Depth if the map has stray out-of-range values.
• On an 8-bit photograph, turn on Bloom and raise Highlight Reconstruction so clipped lamps and speculars bloom as real points of light rather than flat discs.
• Set Overlay Mode in the Diagnostics section to Focus Zones to check that Focus Position and In-Focus Range sit where you meant before judging the blur.

Related Nodes

• Blur
• 3D Render
• Glow
• Chromatic Aberration
• Displace