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. The output between the GPU and CPU is identical on NVIDIA GPUs, but using the GPU can significantly improve processing performance. 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. Nuke also supports AMD GPUs on any Mac Pro running Mac OS X Mavericks (10.9.3 ), or later, mid 2015 MacBook Pros onward, and late 2017 iMac Pros. Bit-wise equality between GPU and CPU holds in most cases, but for some operations there are limitations to the accuracy possible with this configuration. Warning: Although AMD GPUs are enabled on Mac Pros manufactured prior to the late 2013 model, they are not officially supported and are used at your own risk. See Windows, Mac OS X and macOS, or Linux for more information on the GPUs Nuke supports.
Lens
Type	lensType	Spherical	Sets the lens type used to shoot the sequence: • Spherical • Anamorphic • Beam Splitter
Projection	projection	Rectilinear	Sets the projection type, either Rectilnear or Fisheye. Fisheye offers several sub-types: • Stereographic • Equidistant • Equisolid • Orthographic
Distortion	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.
Projection Parameters - These controls are only displayed when the Projection control is set to a Fisheye sub-type.
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).
Anamorphic Parameters - These controls are only displayed when the 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 Model
Type	distortionModelType	Radial Standard	Sets the distortion model type, though selecting a Preset alters the selection as appropriate: • Radial Standard • Radial Asymetric • 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.
Domain	distortionDomain	Source	Sets the projection domain in which distortion is represented when 'defishing' a fisheye lens: • Source - distortion is removed before projection is taken into account, before defishing. • Rectilinear - distortion is removed after projection is taken into account, after defishing.
Normalisation	normalisationType	Maximum	Sets how the focal length and distortion parameters are normalized: • Width • Height • Diagonal • Maximum
Distortion Equations
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.
Distortion Parameters - dependent on the Distortion model preset applied.
Denominator s	distortionDenominator0	0	Sets the denominator coefficients for the symmetric coefficients (s) of the distortion model.
Denominator s	distortionDenominator1	0
Numerator s	distortionNumerator0	0	Sets the numerator coefficients for the symmetric coefficients (s) of the distortion model.
Numerator s	distortionNumerator1	0
Centre	centre	0,0	Sets the position of the distortion center.
Keyframes
Keys	N/A	1	Displays the current keyframe number. The LensDistortion node creates a keyframe at the beginning of the sequence automatically.
Keys	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.
Step	keyStep	100	Sets the interval between keyframes for the Key All button.
Key All	addAllKeys	N/A	Click to add keyframes to the sequence at intervals set by the Step control.
Delete All	deleteAllKeys	N/A	Click to delete all keyframes from the sequence.
Analysis
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	detectionType	Grids	Sets the detection type executed by the Detect button: • Features - resets the detection state and finds saddle points in the input grid shot. • Links - connects detected features to form a grid. This runs Features detection first if it has not been already been executed. • Grids - runs the Features and Links detection steps without allowing you to apply manual corrections between the two.
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	solverError	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.
Output
Mode	outputType	STMap	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 Projection	useProjection	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	resampleType	Bicubic	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.
Format	scalingType	Input	Sets the rescaling mode: • Input - use the input format for the output. This also uses the input format to scale the distortion. • Rescale - use the selected Format to rescale the distortion. This sets the output format to the input format. • Reformat - reformat the output with the selected Format. This uses the input format to scale the distortion.
N/A	outputFormat	dependent on Compositing environment Project Settings	Sets the format to use to reformat the image or to rescale the distortion when Scaling is set to Rescale or Reformat.
Adjust Format
Override	useAdjustedFormat	disabled	When enabled, override the format selected in the outputFormat dropdown with a new format. The new format is called lens_distortion_adjusted by default, but you can enter any name you choose in the adjustedFormatName control. The name is added to the Project Settings > Format dropdown after adjustment to avoid changing Nuke's default formats.
Override	adjustedFormatName	lens_distortion_adjusted
Add Pixels	addPixelsToFormat	0	Sets the number of pixels to add to the format on all sides. This control allows you to add pixels to the format to bring detail outside the format into view.
Adjust Aspect	pixelAspectMultiplier	1	Sets the input pixel aspect multiplier. Adjusting this control does not affect the format size, only the individual pixels in the image.
Adjust Bounding Box
Add Pixels	addPixelsToBBox	0	Controls the size of the bounding box of the output image, in pixels.
Override BBox	overrideBBox	disabled	When enabled, use the outputBBox controls to adjust the BBox manually.
N/A	outputBBox	dependent on Compositing environment Project Settings	When Override BBox is enabled, manually 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.
Grid Detection Tab
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	detectionType	Grids	Sets the detection type executed by the Detect button: • Features - resets the detection state and finds feature points in the input grid shot. • Links - connects detected features to form a grid. This runs Features detection first if it has not been already been executed. • Grids - runs the Features and Links detection steps without allowing you to apply manual corrections between the two.
Feature Detection
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 increase 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.
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.
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 frames	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.