LensDistortion

The LensDistortion node (NukeX and Nuke Studio only) estimates the lens distortion in a given image, either through Grid Detection or manual Line Detection. The warp can then be used to add or remove distortion or produce an STMap in the motion channel for use elsewhere.

Note:  You must perform the analysis in NukeX or Nuke Studio, but you can use the results in Nuke.

Inputs and Controls

Connection Type

Connection Name

Function

Input

Source

The image sequence to warp.

Control (UI)

Knob (Scripting)

Default Value

Function

LensDistortion Tab

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 default blink 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, if available, by navigating to the Preferences and selecting an alternative from the default blink 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.

Model Preset

distortionModelPreset

NukeX Classic

Sets the distortion model to use and adds or removes Distortion Parameter controls depending on the preset selected:

NukeX Classic - uses the distortion model from legacy versions of Nuke.

CaraVR Radial, Degree 3 - uses a distortion model suitable for CaraVR.

3DEqualizer - provides several distortion models suitable for 3DE.

Custom - allows you to customize the distortion model from scratch.

Lens Type

lens

Spherical

Sets the lens type used to shoot the sequence:

Spherical

Anamorphic

Anamorphic Parameters - These controls are only displayed when the Lens Type control is set to Anamorphic.

Squeeze

anamorphicSqueeze

1

Sets the anamorphic squeeze used to rescale the x coefficients in the Distortion Parameters.

Twist

anamorphicTwist

0

Compensates for lens twist, measured in degrees.

Scale x,y

anamorphicScale

1,1

Compensates for lens breathing, the slight changes in focal length when changing the focus.

Distortion Parameters - these controls are dependent on the distortion Model Preset applied.

Denominator s

distortionDenominator0

0

Sets the denominator coefficients for the symmetric coefficients (s) of the distortion model.

These controls are linked to the controls of the same name on the Advanced tab.

distortionDenominator1

0

Centre

centre

0,0

Sets the position of the distortion center.

Output

Mode

output

Undistort

Sets the type of output from the node:

STMap - renders both undistortion and redistortion STMaps in the motion channels. Use the forward channels for undistorting and the backward channels for redistorting. The other input channels are copied to the output directly. In this mode, the overlay grids can be displayed on top of the source image.

Undistort - undistorts the input directly in the Viewer, allowing to visualize the undistorted overlay grid.

Redistort - redistorts the input directly in the Viewer, allowing to visualize the redistorted overlay grid.

Use Fisheye

useFisheye

enabled

When enabled, lens projection is considered as part of the distortion when warping fisheye lenses.

When disabled, Nuke renders an 'ideal' fisheye without distortion when undistorting, and applies distortion to a fisheye image when redistorting.

Note:  This control has no effect on Rectilinear lenses.

Filter

filter

Cubic

When Mode is set to Undistort or Redistort, sets the image resampling filter to use when remapping pixels from their original positions to new positions. This allows you to avoid problems with image quality, particularly in high contrast areas of the frame (where highly aliased or jaggy edges may appear if pixels are not filtered and retain their original values).

Impulse - remapped pixels carry their original values.

Cubic - remapped pixels receive some smoothing.

Keys - remapped pixels receive some smoothing, plus minor sharpening (as shown by the negative -y portions of the curve).

Simon - remapped pixels receive some smoothing, plus medium sharpening (as shown by the negative -y portions of the curve).

Rifman - remapped pixels receive some smoothing, plus significant sharpening (as shown by the negative -y portions of the curve).

Mitchell - remapped pixels receive some smoothing, plus blurring to hide pixelation.

Parzen - remapped pixels receive the greatest smoothing of all filters.

Notch - remapped pixels receive flat smoothing (which tends to hide moire patterns).

Lanczos4, Lanczos6, and Sinc4 - remapped pixels receive sharpening which can be useful for scaling down. Lanczos4 provides the least sharpening and Sinc4 the most.

BBox

bboxType

Auto

Sets how the bounding box is calculated:

Auto - the bounding box is set automatically, which can lead to a performance hit if the bounds are much larger than the image.

Input - the bounding box is set to the same dimensions as the input image.

Manual - allows you to set the bounding manually using the outputBBox controls.

outputBBox

dependent on Compositing environment Project Settings

When BBox is set to Manual, adjust the BBox by entering values in the x, y, r, and t controls.

You can also use the crop widget in the Viewer to adjust the BBox.

Output Format

 

outputFormatType

Input

Sets the output format:

Input - the output format is the same as the input format.

Format - the output format is controlled by the format dropdown.

BBox - the output format is the same as the bounding box.

format

dependent on Compositing environment Project Settings

Sets the output format to use when Output Format is set to Format.

Distortion Scaling

 

distortionScalingType

Scale to Input Format

Sets the rescaling mode:

Scale to Input Format - use the input format to scale the distortion in the output.

Format - use the selected format to scale the output.

outputFormat

dependent on Compositing environment Project Settings

Sets the format to use to reformat the image when Distortion Scaling is set to Format.

Analysis Tab

Grid Detect

Detect

detect

N/A

Click to run the selected detection method on all key frames for a calibration grid shot.

Grid detection consists of feature detection and feature linking. It can be run in one step, using Grids detection, or broken down into two steps to allow for manual corrections.

See the Grid Detection controls for more information on changing the detection parameters.

N/A

detectionFrameType

Current Frame

Sets the number of frames processed by the Detect button:

Current Frame - only detect grids on the current frame.

Every N Frames - detect grids on the current frame and every N frames after that. N is specified by the control to the right.
The default value of N is 5 frames.

Preview

preview

disabled

You can enable the Preview control to view the features that the LensDistortion node is likely to find when you click the Detect button.

You can adjust the controls in the Settings dropdown to improve the result and then click Detect.

Settings

Number of Features

numFeatures

5000

Sets the maximum number of detected features.

You can try increasing the Number of Features if the grid is not fully covered by feature points.

Patch Size

patchSize

9

Sets the patch size for feature relocalization.

Try increasing the Patch Size if features are not consistently located on saddle points.

Feature Separation

featureSeparation

15

Sets the distribution of features in relation to each other.

This value should reflect the scale of a square element of the grid.

Detection Threshold

detectionThreshold

100

Sets the detection threshold at which features are rejected automatically.

You can increase the value to reject weaker features, such as points not on a grid.

Feature Linking

Angle Threshold

angleThreshold

8

Sets the angle tolerance when linking neighboring features.

If you find there are too many missing links between adjacent features, try increasing this value.

High values can introduce ambiguity in the linking process, so adjust the Angle Threshold to get the best coverage of the grid.

Distance Threshold

distanceThreshold

30

Sets the distance tolerance allowed when merging neighboring links.

You can increase the Distance Threshold to recover missing feature points after detection.

Peak Threshold

peakThreshold

20

Sets the peak tolerance when detecting linking directions.

You can decrease the Peak Threshold to improve feature linking if the grid image does not contain a sufficient contrast.

Editing and Drawing

lineDrawingModeSelectAll

N/A

Click to enable the generic selection tool.

lineDrawingModeSelectFeatures

N/A

Click to enable the feature selection tool.

lineDrawingModeSelectLines

N/A

Click to enable the line selection tool.

lineDrawingModeAddFeatures

N/A

Click to enable the add feature tool.

lineDrawingModeRemoveFeatures

N/A

Click to enable the remove feature tool.

lineDrawingModeAddLines

N/A

Click to enable the line drawing tool.

Solve

Keys

N/A

1

Displays the current keyframe number.

N/A

1

Displays the total number of keyframes.

N/A

N/A

Click to jump to the previous keyframe.

N/A

N/A

Click to jump to the next key frame.

N/A

N/A

Click to add a keyframe at the current frame in the sequence.

N/A

N/A

Click to delete the keyframe at the current frame in the sequence.

N/A

N/A

Click to delete all keyframes in the sequence.

Solve

solveDistortion

N/A

Click to estimate the distortion model parameters using the detected grids.

The solver attempts to warp the distorted links into straight lines.

Note:  Solving the distortion model requires at least as many feature links as parameters in the distortion model. If the Detect method doesn't find enough links, try adding more keyframes or tuning the detection parameters.

Reject

deleteOutliers

N/A

Click to reject links for which the residual error is outside the error Threshold.

You can delete outliers drawn red in the overlay and then click Solve again to improve the results by refining the warp.

You can also delete links manually by selecting them and pressing the Delete or Backspace keyboard shortcuts. Holding Ctrl/Cmd while deleting links keeps only the selected links.

Reset

resetDistortion

 

Resets the distortion parameters and solve state. Deleted features and links are not restored.

Solve Error

solveError

0

Displays the root mean square (RMS) solve error in pixels.

This can be used to measure the quality of the solve. It is computed as the average deviation to an ideal straight line for each link. Move the mouse over a link to display its individual residual error.

Threshold

errorThreshold

10

Sets the error threshold for outliers rejection.

Lower values can produce a closer fit, but with the risk of overfitting. Too many outliers can be an indication of an issue with the selected distortion model.

Overlay

Show

overlayType

All

Selects what to display in the overlay:

None - disables the overlay.

Features - only displays detected feature points. Only features are editable in this mode. Deleting a feature does not delete any associated links.

Links - only display the links between feature points. Only links are editable in this mode. Deleting a link does not delete the features it connects.

All - displays both feature points and links. When this option is selected, both types can be edited at the same time.

Advanced Tab

Fisheye

Projection Model

projection

None (Rectilinear)

Sets the projection type, either None (Rectilnear) or Fisheye. Fisheye offers several sub-types:

Stereographic

Equidistant

Equisolid

Orthographic

Focal Length

focal

9

Sets the camera focal length (in mm).

Sensor Size x,y

sensorSize

36,24

Sets the size of the camera sensor (in mm).

Beam Splitter

Enable

enableBeamSplitter

disabled

When enabled, the Direction and Bending controls are enabled to manage images created using a beam splitter.

Direction

beamSplitterDirection

0

Controls the beam splitter's cylindrical direction and bending.

Bending

beamSplitterBending

0

Distortion

Type

distortionModelType

Radial Standard

Sets the distortion model type, though selecting a Preset alters the selection as appropriate:

Radial Standard

Radial Asymmetric

Radial-Tangential (Coupled or Uncoupled)

Order

distortionOrder

0,2

Sets the order of the radial distortion's rational polynomial function.

The first term controls the numerator order and the second controls the denominator order.

Note:   The default values (0, 2) correspond to the legacy NukeX model.

Exponent

distortionExponent

2,2

Sets the base exponent of the radial distortion polynomial.

The first term controls the numerator exponents and the second controls the denominator exponents.

Note:  A base exponent of 2 for the denominator corresponds to the classic NukeX model.

Direction

distortionModelDirection

Forward

Set the distortion model direction:

Forward - estimated directly but needs to be inverted for image rendering.

The NukeX Classic model is an example of a Forward model.

Backward - estimated using its inverse but can be used directly for image rendering. Model inversion is not an exact process and may cause loss of information due to approximations.

The CaraVR Radial model is an example of a Backward model.

Normalisation

normalisationType

Maximum

Sets how the focal length and distortion parameters are normalized:

Width

Height

Diagonal

Maximum

Distort in Fisheye Space

distortInFisheyeSpace

enabled (if a fisheye Projection Model is selected)

When the Project Model is set to Fisheye, this control determines whether to remove or apply the distortion in fisheye or rectilinear space, that is, before or after 'defishing' the lens.

Equation x

distortionModelDisplayX

xu = xd / (1 + k0 * rd^2 + k1 * rd^4)

Distortion model equation display.

Legend: (xd, yd) are the distorted cartesian coordinates, (rd, phid) are the distorted polar coordinates, (xu, yu) are the undistorted cartesian coordinates, (ru, phiu) are the undistorted polar coordinates, and the k-values are the distortion coefficients. The coordinate systems are relative to the distortion centre.

Equation y

distortionModelDisplayY

yu = yd / (1 + k0 * rd^2 + k1 * rd^4)

Distortion model equation display.

Legend: (xd, yd) are the distorted cartesian coordinates, (rd, phid) are the distorted polar coordinates, (xu, yu) are the undistorted cartesian coordinates, (ru, phiu) are the undistorted polar coordinates, and the k-values are the distortion coefficients. The coordinate systems are relative to the distortion centre.

The denominator and numerator controls are dependent on the distortion Model Preset applied on the LenDistortion tab.

Denominator s

distortionDenominator0Link

0

Sets the denominator coefficients for the symmetric coefficients (s) of the distortion model.

These controls are linked to the controls of the same name on the LenDistortion tab.

distortionDenominator1Link

0

Numerator s

distortionNumerator0

0

Sets the numerator coefficients for the symmetric coefficients (s) of the distortion model.

These controls are linked to the controls of the same name on the LensDistortion tab.

distortionNumerator1

0

Centre

centreLink

0,0

Sets the position of the distortion center.

This control is linked to the control of the same name on the LenDistortion tab.

Python Tab (These controls are for Python callbacks and can be used to have Python functions automatically called when various events happen in Nuke.)

before render

beforeRender

none

These functions run prior to starting rendering in execute(). If they throw an exception, the render aborts.

before each frame

beforeFrameRender

none

These functions run prior to starting rendering of each individual frame. If they throw an exception, the render aborts.

after each frame

afterFrameRender

none

These functions run after each frame is finished rendering. They are not called if the render aborts. If they throw an exception, the render aborts.

after render

afterRender

none

These functions run after rendering of all frames is finished. If they throw an error, the render aborts.

render progress

renderProgress

none

These functions run during rendering to determine progress or failure.

Step-by-Step Guides

Working with Lens Distortion