O_DisparityGenerator

The O_DisparityGenerator node is used to create disparity maps for stereo images. A disparity map describes the location of a pixel in one view in relation to the location of its corresponding pixel in the other view. It includes two sets of disparity vectors: one maps the left view to the right, and the other maps the right view to the left.

The following Nuke nodes rely on disparity maps to produce their output:

O_OcclusionDetector

O_ColourMatcher

O_FocusMatcher

O_VerticalAligner (in Local Alignment mode)

O_NewView

O_InteraxialShifter

O_DisparityToDepth

O_DisparityViewer

Inputs and Controls

Connection Type

Connection Name

Function

Input

Source

A stereo pair of images. If you intend to use the Alignment control, O_DisparityGenerator requires an O_Solver node as one of its inputs. Alignment defaults to 0, but increasing it forces the disparity map to match the camera geometry to remove noise on the vertical component of disparity.

Mask

An optional mask that specifies areas to exclude from the disparity calculation. You can use this input to prevent distortions at occlusions or to calculate disparity for a background layer by ignoring foreground elements.

Control (UI)

Knob (Scripting) Default Value Description
O_DisparityGenerator

Local GPU

gpuName

N/A

Displays the GPU used for rendering when Use GPU if available is enabled. Local GPU displays Not available when:

Use CPU is selected as the GPU Device in the Preferences.

no suitable GPU was found on your system.

it was not possible to create a context for processing on the selected GPU, such as when there is not enough free memory available on the GPU.

You can select a different GPU Device, if available, by navigating to the Preferences and selecting an alternative from the GPU Device dropdown.

Note:  Selecting a different GPU requires you to restart Nuke before the change takes effect.

Use GPU if available

useGPUIfAvailable

enabled

When enabled, rendering occurs on the Local GPU specified, if available, rather than the CPU.

Note:  Enabling this option with no local GPU allows the script to run on the GPU whenever the script is opened on a machine that does have a GPU available.
You should also select this if you wish to render from the command line with the --gpu option.

See Nuke 14 Release Notes for more information on the GPUs Nuke supports.

Views to Use

viewPair

Dependent on source

Sets the two views you want to use to create the disparity map. These views will be mapped for the left and right eye.

Preset

disparityType

Normal

Use the Preset dropdown to automatically make adjustments to the disparity results by changing the appropriate refinement controls:

Custom - Automatically selected when you adjust the controls manually,

Normal - The default value for all controls.

Strong - Increases match Strength between images at the expense of Stabilisation.

You can use Strong when picture building is poor using O_NewView, O_ColourMatcher, and O_FocusMatcher.

Aggressive - Increases the Strength used to reconstruct images as close as possible to the source, but reduces Stabilisation in favour of accuracy.

This option gives the best result in O_NewView to reproduce the appearance of one view from another and is useful for colour or focus matching.

Note:  Aggressive calculation can produce poor stability, which makes it unsuitable for copying fixes from one view to the other.

Smooth - Reduces match Strength between images and concentrates on Stabilisation.

This option produces smoother, temporally stable vectors. Use Smooth to generate clean depth maps and to prevent flicker when copying a fix from one view to the other.

Note:  Smooth vectors are cleaner and stable from one frame to the next, but the image may not reconstruct well with O_NewView.

Aligned - This option enables the Alignment control, which requires an O_Solver upstream.

Fast - This option disables the Stabilisation control, reducing processing time.

Mask

maskWith

None

An optional mask that specifies areas to exclude from the disparity calculation. You can use this input to prevent distortions at occlusions or to calculate disparity for a background layer by ignoring all foreground elements.

Note that masks should exist in both views, and O_DisparityGenerator treats the alpha values of 1 as foreground and blurs to the 0 value using nearby disparity to recreate object boundaries, rather than image data. When you create a mask using Roto or RotoPaint, you can use the feather control to extend the calculation. For example, the disparity map may have a sharper transition at depth edges with a binary mask, but applying feather on the mask can help smooth the resulting image.

None - Use the entire image area.

Source Alpha - Use the alpha channel of the Source clip as an ignore mask.

Source Inverted Alpha - Use the inverted alpha channel of the Source clip as an ignore mask.

Mask Luminance - Use the luminance of the Mask input as an ignore mask.

Mask Inverted Luminance - Use the inverted luminance of the Mask input as an ignore mask.

Mask Alpha - Use the alpha channel of the Mask input as an ignore mask.

Mask Inverted Alpha - Use the inverted alpha channel of the Mask input as an ignore mask.

Vector Detail

vectorDetail

1

Adjusts the density of the calculated disparity vectors. Higher detail picks up finer disparity changes, but takes longer to calculate.

Strength

strength

5

Sets the strength applied when matching pixels between the left and right views. Higher values allow you to accurately match similar pixels in one image to another, concentrating on detail matching even if the resulting disparity map is jagged. Lower values may miss local detail, but are less likely to provide you with the odd spurious vector, producing smoother results.

Often, it is necessary to trade one of these qualities off against the other. You may want to increase Strength to force the views to match where fine details are missed, or decrease it to smooth out the disparity map.

Consistency

consistency

1

Sets how accurately the same points in the left and right views are mapped to each other. Increase the value to encourage the left and right disparity vectors to match.

Smoothness

smoothness

1

Controls how image edges are used as clues for sharp transitions in depth in the scene. The higher the value, the smoother the transition between depths at edges in the image.

Alignment

alignment

0

Sets how much to constrain the disparities to match the vertical alignment defined by an upstream O_Solver node. Increasing the value forces the disparities to be aligned and requires at least one keyframe match.

Note:  The default Alignment value of 0 calculates the disparity using unconstrained motion estimation, and therefore, does not require O_Solver data.

Using O_DisparityGenerator in conjunction with O_Solver alignment data allows you to constrain the resulting disparity vectors to match global plate alignment. You might want to do this if your plates don't contain much detail, such as bluescreen images with markers in the background or plates with a lot of featureless areas like sky.

Note:  Using the O_Solver alignment data can reduce changes in vertical disparity with depth that are required for Local alignment in O_VerticalAligner and cause a vertical shift in O_NewView, where disparity doesn't pick up the local vertical shift required to match the images.

Stabilisation

stabilisation

1

Sets how heavily vectors are forced to be temporally consistent by generating disparity over multiple frames, rather than a single stereo frame. Increasing the value produces smoother vectors, which are more stable over time, but at the expense of increased processing time.