Bokeh

Bokeh is a plug-in originally developed by Peregrine Labs and acquired by Foundry in 2022. Bokeh was introduced natively to Nuke 14.0v2 and Nuke 13.2v6, and later releases of Nuke, NukeX, Nuke Studio, Nuke Indie, and Nuke Non-commercial to all customers with active licenses.

Bokeh defocuses an image according to a Z depth map, Deep data, or Camera information. You can control where the focal plane lies to focus on specific elements in an image and simulate real-world lenses. You can also control the shape of the defocus kernel using the Kernel input.

Note: You can defocus an image without using any additional depth data, but the result is uniformly defocused by the Multiplier control.

Note: The native version of Bokeh is backward compatible with version 1.4.8 of the pgBokeh plug-in. For older Nuke scripts containing legacy pgBokeh nodes, the pgBokeh nodes are automatically remapped to the Nuke-native Bokeh node. If the old pgBokeh plugin is still present in the Nuke plugin path, we recommend you remove it to ensure the native Bokeh node is used by Nuke.

Inputs and Controls

Connection Type	Connection Name	Function
Input	Mattes	An optional input to use as a mask. By default, the effect is limited to the non-black areas of the mask. At first, the Mattes input appears as a triangle on the right side of the node, but when you drag it, it turns into an arrow labeled mask. If you cannot see the Mattes input, ensure that the Default Matte Channel control is disabled or set to none.
	Deep Input	An optional input to use Deep data as the depth channel.
	Camera	An optional input to use Camera node data to determine the focal plane.
	Kernel	An optional input to control the shape of the defocus kernel. This input is only used when the Kernel Type is set to Input in the node properties.
	Input	The image to which you want to apply the effect.

Control (UI)	Knob (Scripting)	Default Value	Function
Bokeh Tab
Bokeh Channels	bokehChannels	rgba	The effect is only applied to these channels. If you set this to something other than all or none, you can use the checkboxes on the right to select individual channels.
Depth Channel	depthChannel	depth.Z	Specifies the input channel containing the depth map information. Note: You can defocus an image without using any additional depth data, but the result is uniformly defocused by the Multiplier control.
Output Type	outputType	Defocused Image	Sets the output type: • Defocused Image - displays the input image with the Bokeh effects applied. • Lens Bloom - displays just the bloom effect. • Focal Distance Visualization - preview the focal distance values. This option displays where your focus plane is located in the image: • Red - the focal plane, where your image is fully in focus. • Green - areas of the image in front of the focal plane. • Blue - areas of the image behind the focal plane. Tip: Increasing the Focus Region Size can help differentiate between regions. • Filter Shape - preview the shape of the kernel. • Focus Mattes - Front/Back mattes for the focus.
Focus Region Output	focusOutput	Both	Sets whether the Front, Back, or Both focus regions are output to the Viewer. You can switch this control to just output the front or back regions to make adjustments to individual multipliers without taking the processing hit for both regions.
Multiplier	multiplier	1	Sets the overall amount of defocus applied to the image.
Front Multiplier	frontmultiplier	1	Sets the amount of defocus applied to the front focus region in addition to the defocus applied by the Multiplier control.
Back Multiplier	backmultiplier	1	Sets the amount of defocus applied to the back focus region in addition to the defocus applied by the Multiplier control.
Depth Style	depthStyle	Real	Controls how the depth information is interpreted: • Real - uses real world values to calculate the defocus. • 1/z - uses values similar to those output by ScanlineRender nodes to calculate the defocus. Note: If you're using deep data, this control has no effect.
Focal Plane	focalPlane	100	Controls the plane on which the image is totally in focus. Lower values move the plane towards the front of the image and higher values move the plane towards the back of the image. Note: Set the Output Type to Focal Distance Visualization to see a representation of the focal plane in red and the front and back regions in green and blue.
Focus Region Size	focusRegionSize	1	Controls the size of the plane totally in focus. Larger values increase the width of the plane.
Focus Region Falloff	focusRegionFalloff	Linear	Sets the falloff applied between the focal plane and the front and back regions of the image.
Defocus Matte Channel	N/A	off	Enables the associated mask channel to the right. Disabling this checkbox is the same as setting the channel to none.
Defocus Matte Channel	defocusMatteChannel	none	The channel to use as a mask. By default, the defocus effect is limited to the non-black areas of this channel.
Normalize Visualization	normalizeVisualization	on	When Output Type is set to Focal Distance Visualization, color values in the output are limited to the 0-1 range when this control is enabled.
Integrate Deep Front and Back Separately	integrateFrontAndBackSeperately	off	When enabled, front and back deep data from the Deep input is integrated separately. If you notice artifacts in your output from deep data, try enabling this control to reduce the artifacts produced by simultaneous integration.
Lens Tab
Real World Lens Simulation	realWorldLens	off	When enabled, you can use the Lens controls to match your physical lens characteristics, such as Focal Length and Aperture. When disabled, the Lens controls have no effect.
Focal Length	focalLength	35	Sets the focal length of the physical lens you want to match when defocusing.
Aperture	fStop	6	Sets the f-stop value for the physical lens you want to match when defocusing.
World Scale	worldScale	cm	Sets the world scale units to use in the scene. Nuke doesn't rely on any particular unit, but applications such as Maya may default to cm.
World Scale Multiplier	worldScaleMultiplier	1	Sets the multiplier applied to the World Scale. For example, if your scene units are based on 10 cm blocks, you can set the World Scale to cm and the World Scale Multiplier to 10 to adjust the scene accordingly.
Film Format	filmFormat	35mm	Sets the filmback to use from a list of preset values, which automatically sets the Aperture Width and Aperture Height for the selected filmback. If you want to set the aperture manually, set Film Format to Custom and then enter the required aperture dimensions in mm.
Aperture Width	apertureWidth	22	Aperture Width and Aperture Height are controlled by the selected Film Format. If you want to set the aperture manually, set Film Format to Custom and then enter the required aperture dimensions in mm.
Aperture Height	apertureHeight	16
Optical Artifacts Tab
Bloom	bloom	0	Controls the brightness of any bloom applied to the image when the Bloom Threshold is reached. Any pixels with a brightness less than the Bloom Threshold are not affected.
Curvature	bloomCurvature	2	Defines the physical lens curve, which affects the bloom differently depending where light enters the lens.
Bloom Threshold	bloomThreshold	0.7	Controls the brightness level at which pixels are affected by the Bloom control. Any pixels with a brightness less than the Bloom Threshold are not affected.
Bloom Matte Channel	N/A	off	Enables the associated mask channel to the right. Disabling this checkbox is the same as setting the channel to none.
Bloom Matte Channel	bloomMatteChannel	none	The channel to use as a mask. By default, the bloom effect is limited to the non-black areas of this channel.
Spherical Aberration	kSphAbb	0	Defines the spherical aberration in the physical lens, which affects the bloom shape differently depending on the amount of aberration in the lens. Negative Spherical Aberration values make the kernels brighter in the center and positive values make the kernels brighter on the edges.
Chromic Aberration	kChrAbb	0	Defines the chromatic aberration in the physical lens, which affects the bloom color differently depending on the amount of aberration in the lens.
Chromic Aberration Offset	kChrAbbOff	0.6, 1, 1	Controls the chromatic refraction offset for the red, green, and blue channels. You can also use the color picker or color wheel to select an overall offset color.
Chromic Aberration Matte Channel	N/A	off	Enables the associated mask channel to the right. Disabling this checkbox is the same as setting the channel to none.
Chromic Aberration Matte Channel	chromicAberrationMatteChannel	none	The channel to use as a mask. By default, the chromatic aberration effect is limited to the non-black areas of this channel.
Kernel Tab
Kernel Type	kernelType	Circular	Controls the shape of the bloom kernel to apply to the image: • Input - a custom shape defined by the nodes attached to the Kernel input. • Circular - a clean, round lens shape that produces a round bloom effect. • Aperture Blades - a geometric lens shape bloom produced by the aperture blades of the physical lens. The number of blades on the lens is set by the Blades Count control. Tip: You can preview the shape of the kernel by changing the Output Type to Filter Shape on the Bokeh tab.
Maximum Kernel Size	max_kernelsize	256	Sets an upper limit on the size of the kernel. You can reduce this size value to decrease processing time, but any defocus result is then clamped.
Expand Bounding Box To Max Kernel Size	expandBBoxToMaxKernelSize	off	When enabled, the bounding box is increased to accommodate the kernel size if the kernel extends beyond the bounding box. When disabled, the parts of the kernel extending past the bounding box are ignored.
Missing Kernel Channel	N/A	off	Enables the associated mask channel to the right. Disabling this checkbox is the same as setting the channel to none.
Missing Kernel Channel	missingKernelChannel	none	The channel to use if an expected kernel channel is missing from the Kernel input. This channel has no effect on the Circular and Aperture Blades presets.
Aspect Ratio	kAspectRatio	1	Determines the aspect ratio of the kernel. If you're defocusing anamorphic images, set the kernel Aspect Ratio accordingly.
Softness	kSoftness	0.1	Controls the softness of the kernel. A Softness value of 0 produces a very hard edge and a value of 1 produces a very soft edge.
Blade Count	kNumSides	6	When Kernel Type is set to Aperture Blades, this control sets the number of blades to simulate. You can use any value between 3 and 16 sides for the kernel shape.
Curvature	kCurvature	0.1	Controls the curvature of the blades in the kernel shape. Lower values produce sharper angles on the kernel shape and higher values smooth the kernel shape.
Rotation	kRotation	0	Controls the rotation of the blades in the kernel shape.
Corrective Slices Tab
Number of Corrective Slices	correctiveSlices	10	Sets the number of slices the depth channel is divided into during defocus calculations, which can help avoid objects at different depths overlapping incorrectly. The depth volume sliced is defined by the Focal Plane and Focus Region Size. • 1 slice - the image is defocused in one pass, which can result in overlapping. • 2 slices - the front and back regions are processed separately so that objects in the foreground are distinct from objects in the background. • 3+ slices - divide the depth channel into this number of equal slices and process each one separately.
Override Near/Far	overrideNearAndFarForSlices	off	When enabled, you can override the depth slice volume defined by the Focal Plane and Focus Region Size using the Near and Far controls.
Near and Far	depthSlicesNearAndFar	0, 0	When Override Near/Far is enabled, use these controls to define the depth volume to separate into slices. The number of slices is defined by the Number of Corrective Slices control.