Lens Blur ​

Depth-of-field blur driven by a depth map, with source-owned bokeh and focus controls.

Category: Effects

Menu path: Effects > Lens Blur

Ports ​

PortTypeDirectionDescription
inimageRgba16finputImage to blur.
depth_inimageRgba16finputDepth values from a 3D Z pass, Generate Depth Map, or another image. Disconnected → unchanged image.
kernel_inimageRgba16finputOptional custom aperture. Nonnegative linear luminance × alpha describes light transmission. Its centered native content fills the aperture disc; rotation is supported. Overrides bokehShape. An entirely black/transparent aperture produces a sharp delta rather than losing the image.
outimageRgba16foutputStraight-alpha depth-of-field result.

Expose channels ​

The E button adds scalar focus_in and blurSize_in inputs, overriding Focus Distance and Blur Size. focus_in takes a fraction of the Near→Far range (0 = Near, 1 = Far), like the parameter itself.

Parameters ​

Focus ​

ParamTypeDefaultDescription
focusDistancescalar50%Where the focal plane sits, as a percentage of the way from Near to Far. Shown as a percentage, stored as a fraction (0.5). Use the eyedropper beside it to pick focus in the viewer.
focusRangescalar10%How deep the sharp band around the focal plane is, as a percentage of the Near→Far range. Negative values count as zero.
blurSizescalar30The biggest blur in the shot, in composition pixels — reached at whichever end (Near or Far) is farther from focus. Blur grows at one rate on both sides of the focus band, so the nearer end blurs less. Larger sizes cost more to render.
focusOverlaybooleanfalseFocus zebra — the striped button beside the eyedropper. Draws zebra stripes over the pixels that are in focus, like the zebra display on a camera. Viewer only: renders and exports never show it.

Pick focus. Click the eyedropper beside Focus Distance, then click the viewer. Focus Distance becomes the depth under the cursor at the current frame. The pick sees through transforms after the Lens Blur: if the layer is moved, scaled or rotated downstream, clicking the subject on screen still finds its depth. If Focus Distance has keyframes, the pick sets a keyframe at the playhead, the same as typing a value. Press Esc to cancel. The button is unavailable until a depth map is connected, or while a wire drives Focus Distance.

Focus zebra. Click the striped button beside the eyedropper to see what is in focus: stripes cover every pixel inside the sharp band. Drag Focus Distance and Focus Range and watch the stripes move. The stripes are drawn only in the viewer — a render or export never includes them, even with the button on. Turning it on or off is one undo step.

Depth ​

ParamTypeDefaultDescription
depthNearscalar0The depth-map value that counts as nearest. In the depth map's own units, whatever they are (a Z pass might run 0.108–0.436, another might be in centimetres).
depthFarscalar0The depth-map value that counts as farthest.
depthChannelenumLuminanceLuminance / Red / Green / Blue / Alpha.
invertDepthbooleanfalseUses 1 − depth; useful for reversing normalized depth conventions.

Near and Far fill in by themselves. When Near and Far are equal (as on a new node) they read auto: the node measures the depth map's range on every frame. The first time a range is measured, Caddis writes it into Near and Far and keeps it. From then on the values stay fixed, so if your depth pass changes range over the shot, the focus stays where you put it. The fill-in does not add an undo step, because the picture does not change.

Measure re-reads Near and Far from the frame on screen (one undo step) and keeps the current look: Focus Distance, Focus Range and Blur Size are converted along with the range, so focus stays at the same depth, the sharp band covers the same depths, and blur grows at the same rate. (Keyframes on those three are converted too.) The one visible change: depths that were already at the old maximum blur can now blur a little more, because Blur Size is re-anchored to the new farther end. The latest measured range is shown next to the button, so you can see when it differs from the stored values. If nothing has been measured yet, Measure sets Near and Far back to auto and the next render measures them. To go back to auto yourself, set Near and Far to the same value.

Near and Far do not have to match the depth map's exact extremes. A wider range (which is what an old project converts to) is fine: focus and blur are measured along the Near→Far line even past the map's actual values.

Near / Far Blur ​

ParamTypeDefaultDescription
nearBlurscalar1Blur multiplier for depths nearer than focus.
farBlurscalar1Blur multiplier for depths farther than focus.

Bokeh ​

ParamTypeDefaultDescription
bokehShapeenumPolygonCircle, Polygon, Ring (inner radius 0.6), or Star (alternating outer/0.5-inner vertices). Ignored with a custom kernel.
bokehBladesscalar6Polygon sides or star tips. Evaluated values are rounded and clamped to 3–8, including between animated keys.
bokehRotationscalar0Aperture rotation in degrees, including custom images.
edgeFeatherscalar0.10 = hard discrete aperture. Positive values soften the edge with a transition at least one working pixel wide, avoiding abrupt small-radius sampling changes. This is a pixel-footprint approximation, not exact area integration.
highlightBoostscalar10RGB-only highlight emphasis; does not change alpha. Set to 0 when assessing neutral blur.
highlightThresholdscalar0.2Straight linear luminance above which highlight emphasis applies.

Settings ​

ParamTypeDefaultDescription
repeatEdgesbooleantrueExtends the working canvas by repeating its boundary pixels, with each repeated source keeping its own color, depth, and normalized aperture. It does not extend internal object silhouettes or fill transparent holes. Off → blur can lose coverage at the canvas boundary.
fullDetailbooleanfalseOff, a large blur is computed on a reduced copy of the frame and scaled back up — the same operator with fewer, larger pixels, so dragging Blur Size does not change how responsive the viewport feels. On, the blur is computed at the full working resolution. Rendering and exporting always behave as if this is on, so the faster path can never reach a file. A blur small enough to be cheap at full resolution is never reduced.

Why there is a Full Detail switch. Cost here grows with the fourth power of working resolution: the circle of confusion is measured in composition pixels, so doubling resolution both quadruples the pixel count and quadruples each bokeh disc's area. A Retina Full viewport is therefore ~16x a native render of the same shot. Full Detail off holds the blur's internal resolution steady instead, which keeps the node responsive while you dial settings in; the visible cost is that in-focus detail is slightly softened in the viewport, never in a render.

Out-of-range values are clamped, never fatal. The inspector constrains what you can type, but an expose-channel edge can drive focus_in / blurSize_in anywhere — an oscillator wired to Blur Size spends half its cycle negative — and projects saved before those constraints existed may hold any value. Each parameter is clamped to the nearest usable value (negative multipliers → 0, Edge Feather → 0-1, blade counts rounded into 3-8, a radius that cannot be represented → no blur) and the frame renders. Mismatched image/depth dimensions and GPU resource limits are still reported as errors.

Compatibility only: quality (formerly High) and denoise (formerly 0.2) remain in project files and agent parameter descriptions, but are ignored and no longer appear in the inspector. There is no random sample-count tier or post-denoise pass. Use the Viewer's Draft / Preview / Full selector to control working resolution. These controls are distinct from the retired Lens Quality parameter.

How It Works ​

Each covered source pixel owns its depth-derived blur radius, aperture, RGB and alpha. The GPU normalizes its complete aperture before canvas clipping, then gathers every source whose support reaches a pixel. RGB and coverage use identical weights. Fully transparent sources contribute neither hidden RGB nor hidden depth. There are no random taps, mixed-depth mips, or retained sharp image underneath.

This renderer is the default; no environment flag is needed. There is no legacy fallback, including on Retina displays. The former fixed pixel/radius/work budgets are removed. Work is split into GPU command chunks without discarding contributions. Actual GPU texture/storage/index limits still apply; if those are exceeded, rendering reports an error rather than silently changing the picture.

Radii scale per axis with working resolution, including Retina display scaling. Full Retina rendering can evaluate four times as many pixels as a native-resolution export, and large blur radii can be slow. Preview is useful while adjusting the effect.

Usage Examples ​

3D / AOV depth ​

Connect beauty to in and a Linear Z/depth AOV to depth_in, and pick the appropriate depth channel. Near and Far fill in from the pass. Click the eyedropper beside Focus Distance and click your subject. Depth does not have to be normalized to 0–1.

For Cryptomatte isolation, use ImageSource → Matte → LensBlur → Output, with Cryptomatte wired to Matte and the Z pass wired to Lens Blur. A sharp matte applied after blur cuts away its spill.

Focus pull ​

Keyframe Focus Distance, then move the playhead and use the eyedropper on the next subject: each pick sets a keyframe. Focus Range controls how much stays sharp; Blur Size is the biggest blur in the shot, at whichever end is farther from focus. Turn on the focus zebra to see the sharp band as you go.

AI depth or custom bokeh ​

Wire Generate Depth Map to depth_in. For custom bokeh, connect an Image Source aperture to kernel_in: hearts, asymmetric patterns, or photographic aperture images. Transparent bright RGB in an aperture is ignored. An asymmetric aperture stays asymmetric—it is not automatically recentered.

Tips ​

  • If focus seems off after you change the depth map, click Measure so Near and Far match the new map.

  • Start with Highlight Boost 0 to inspect blur and alpha without added brightness.

  • Keep Focus Range nonnegative. Negative ranges are not an extra-blur control.

  • Use positive Edge Feather for smoother small-radius transitions; hard feather intentionally preserves a discrete aperture.

  • Repeat Edges addresses the canvas boundary, not foreground/background occlusion.

  • Assess alpha and the result over both dark and light backgrounds, not RGB alone.

Projects from earlier versions ​

Projects saved before Near/Far and Blur Size existed convert automatically when you open them, and render exactly as before. The old Blur Strength becomes a Near/Far range around your focus (it can be wider than the depth map itself), and Max Radius becomes Blur Size. Two things cannot carry over exactly: an animated Blur Strength keeps only its first keyframe, and a wire into the old Strength input is removed. A wire into Max Radius now drives Blur Size.

Limitations ​

  • Source transport is not hidden-surface reconstruction. Far color can leak through a sharp foreground; continuously varying blur can leave small alpha ripples on an otherwise opaque surface.
  • Overlapping source coverage is saturated to alpha 1. Straight RGB divides by the original unclamped coverage. This is not additive light transport or a physically complete layered lens model.
  • Large images/radii are expensive. There is no claim of real-time performance on every GPU or AE parity.
  • One depth value cannot describe several transparent surfaces or recover unseen background.

© 2026 Caddis