Lens Distortion

Use the Lens Distortion node to compute the lens distortion of a clip, employing either a Lens Grid clip or manually-inserted splines. The result of the calculation can be employed to either undistort or distort the clip.

This node replaces the legacy Lens Distort node.


Access	To access the Lens Distortion menu, use: Batch, then select the node from the All Nodes bin. Timeline, then use Batch FX. See Creating Batch FX.
Inputs	Front - The clip to undistort/redistort. Lens Grid - A Lens Grid clip provided with the Front clip to facilitate the lens distortion calculation. Matte - The clip associated with the Front clip. The same effect is applied to this clip.
Outputs	Result - The undistorted/redistorted version of the Front input. STMap - An STMap containing the pixel movement information calculated by the node. This output is useful to apply the same distortion/undistortion to multiple clips using an STMap node. Inverse STMap - The inverse of the STMap output. This output is useful to put back the distortion using an STMap node rather than duplicating the Lens Distortion node. OutMatte - The undistorted/distorted version of the Matte input.

Only the Front input must have an incoming connection for the node to yield a result.

All connected inputs must have the same resolution.

Workflow

When a Lens Grid clip, with identical distortion to your Front clip, is connected to the Lens Grid input, using the Calculate function should suffice to undistort the image.

If a Lens Grid clip is unavailable, you can allow the application to detect lines and convert them into splines, or manually add splines to lines that should be straight prior to using the Calculate function.

Alternatively, a distortion calculation performed in 3DEqualizer can be imported through a data file.

After performing the distortion calculation, use the Controls and Perspective settings to refine the result as necessary.

Once you have made modifications to the undistorted image using other tools, you can reapply the distortion using an STMap or a Lens Distortion node. This can be achieved by using the Inverse STMap output from the Lens Distortion node as the STMap clip input for the STMap node, or by using a duplicated Lens Distortion node and switching the mode to Distort.

Settings

Mode

Mode option

Select whether to undistort or distort the Front clip.

Select:	To:
Undistort	Remove the lens distortion so all lines are straight.
Distort	Apply back the original lens distortion to your composition.

Tip: Change the mode of a duplicated node to reapply the modifications made on the original node.

Model

Select the model for the distortion calculation from the following options:

Model	Lens Type	Description
3DE4 Radial Fisheye, Degree 8	Fisheye	Used to calculate distortion for a fisheye lens.
3DE4 Radial - Standard, Degree 4	Radial	The standard model for radial symmetric lenses with correction terms for lens decentering, based on the original models by Brown (1966) and Conrady (1919). In contrast to the original model, the decentering parameters has been re-mapped so that the model function is linear in these parameters. The price of doing so is one additional non-physical parameter of degree four.
3DE4 Anamorphic - Rescaled, Degree 6	Anamorphic	Similar to Standard, Degree 6 but intended for non-uniformly rescaled images. It has an additional Rescale parameter.
3DE4 Anamorphic - Standard, Degree 6	Anamorphic	Similar to Standard, Degree 4 but with a polynomial correction factor of order six.
3DE4 Anamorphic - Rescaled, Degree 4	Anamorphic	Similar to Standard, Degree 4 but intended for non-uniformly rescaled images. It has an additional Rescale parameter.
3DE4 Anamorphic - Standard, Degree 4	Anamorphic	The standard model for anamorphic lenses, including parameters for lens rotation (for manually mounted anamorphots). It is based on a polynomial correction factor of order four.
3DE Classic LD Model	Radial	A degree four model polynomial for radial lenses, attempting to incorporate anamorphic aspects through a single squeeze-parameter.

Note: The available controls vary depending on the model selection.

Import 3DE Lens Distortion

Import a setup file that has been exported from the 3DEqualizer application.

To export a data file from 3DEQualizer, you first need to download the latest version of the Export Lens Distortion to Autodesk Flame script available from this website. Follow the Installation Instructions at the top of the page to add it to the 3DEQualizer application.

This will make the the Export Lens Distortion to Autodesk Flame option appear in 3DEqualizer's File Export menu.

Once a data file is loaded, the following controls are set and no calculation is required to obtain a result:

The Centre controls
The Focal Length
The Film Back
The Focus Distance
All settings under the Controls section

The Undistort/Distort status is not present in the data file so you need to make sure the appropriate option is selected to obtain the same result.

Detection - Lines

Lines are automatically detected and visible inside the Front and Lens Grid views. If a clip is connected to the Lens Grid input, it is used to detect lines and calculate the distortion. If not, then the Front clip is used in the line detection.

Show Lines

Show the lines detected by the application within the current frame. This is only available when the current viewport is set to either the Front or Lens Grid view.

Note: Show Lines is automatically disabled when Convert to Splines is used.

Lines can be adjusted using these controls:


Threshold	The number of points with the same parameters necessary to generate a line segment.
Minimum Length	The minimum length of lines. Shorter line segments are rejected.
Maximum Gap	The maximum gap between line segments. Line segments with a gap smaller than this value are merged into a single line segment.

Lines need to be converted into Splines before performing the distortion calculation. This conversion is done using the Convert to Splines button. Splines can be adjusted using these controls:


Radius	Radius of search to connect line segments together.
Theta	Tolerance of the angle difference between two line segments.
Perpendicular Distance	The maximum perpendicular distance between the lines. Used to not link parallel lines together.
Error Tolerance	A threshold used to identify and exclude splines that deviate from the majority of other splines.

Detection - Splines

Splines, which can be manipulated like a Garbage Mask, can be added based on the lines detection using the Convert to Splines button, or manually added.

Splines that were manually added are kept when Convert to Splines is used.
The Show Lines option is automatically disabled when Convert to Splines is used.

The Add Spline button adds a new spline. Alternatively, the Add Spline keyboard shortcut (Spacebar+G) can be used. The shortcut also ends the creation of the previous spline, making it easier to create multiple splines one after the other.

The Finish button ends the creation of a spline. You can also click in an empty area of the user interface or use the Finish Spline keyboard shortcut (Alt+F).

Note: Splines are only visible in the Front and Lens Grid views. The Show Spline button can be used to hide all splines from the image.

Use the Delete Selected and Delete All buttons to delete splines.

Distortion Calculation

Use the Calculate button to calculate the amount of distortion based on the position of vertices. If there are enough lines and vertices, most distortion controls are solved. If not, only a subset is solved.

Note: The view inside the current viewport automatically switches to Result after a calculation has completed.

Distortion Calculation option

Select how the distortion is calculated and how channels are created.

Mode	Distortion Calculation Method
Static	Use the splines at the current frame only.
Dynamic	Use every frame of the clip where a spline has a keyframe. The result is animated controls with linear interpolation.
Average	Use every frame of the clip where a spline has a keyframe. The result is non-animated controls with an average value.

Centre

The Centre controls are the same as in the legacy Lens Distort node. They allow the centre of the distortion to be changed on the horizontal and vertical axes. This can be done using the X and Y numeric fields or by moving the Centre manipulator inside a viewport. These controls are not automatically calculated by the application, hence you need to manually enter the values.

The Centre controls are relative to the Film Back size.

Centre Calculation

The distortion Centre X and Y values are calculated for all models.

Film Back

The Film Back refers to the camera sensor size, in centimetre. The difference between the Film Back width and the camera's physical sensor width is that the former takes the film aspect ratio into account. The Film Back width might thus be different from the camera's physical sensor width.

The Width and Height values are set when the Calculate function is used.

Width is set to 1.8672 cm * front_clip_aspect_ratio.
Height is set to 1.8672 cm.

Focal Length

To effectively remove the distortion, set the Focal Length to the same value used on the filming camera. This control is not automatically calculated by the application, hence you need to manually enter the value.

Note: The Focal Length setting is only available when the Fisheye - Degree 8 model is selected.

Focal Length Calculation

The Focal Length value is calculated for the 3D4 Radial - Fisheye - Radial 8 model.

Focus Distance

The Focus Distance control is not calculated by the application and cannot be set by the user. Its value can only be imported from a 3DEqualizer data file.

Note: The Focal Distance button is always greyed out. The keyframe indicator visible at the bottom indicates if the setting is animated or not.

Controls

Controls are used to undistort or distort the image and differ based on the selected model. The two main controls are:


Distortion / c[xy]02	The primary coefficient used to correct barrel or pincushion distortion in an image. This type of distortion becomes more pronounced as points move further away from the center of the image.
Quartic Distortion / c[xy]22	This is the secondary distortion coefficient. The impact of this coefficient increases with the distance from the center of the image, even more so than the primary coefficient. If the image exhibits mustache distortion, this coefficient will have the opposite sign to the primary coefficient.

Additional controls are available based on the selected model. When there are more controls than what can be displayed under the Controls section, the header turns into tabs and additional controls can be accessed using them.

Controls Clipping

The values for the Controls are not clipped after a calculation or a file import. However, the range within the numeric fields is still applied. Therefore, the Animation view must be used to adjust any values exceeding a control's range.

Perspective

The Perspective manipulators can be used to apply further changes on top of the Distortion controls.

Show Boxes

Enable to display the manipulators in the viewport. Disable to hide them.

Box option

Select whether the image or its UVs are moved.

Select:	To:
UVs	The magenta manipulator allows you to slide the UVs within the image. The Front view should be used to properly place the corners of this manipulator.
Vertices	The yellow manipulator allows you to move the four corners of the image.

Reset

Reset both the UVs and Vertices boxes to their original position.

Tip: As the Show Boxes button is solely for displaying the manipulators, the Reset button acts as an indicator of any modifications. It appears greyed out when no changes have been made and becomes active once a modification is present.

Repeat Mode

Repeat Mode option

Determine if the part of the image where no pixels appear remain as-is or is filled.

Select:	To:
Repeat Off	Have parts of the image where no pixels appear remain black. This is the default option.
Mirror Repeat	Mirror pixels to fill the black parts.
Tile Repeat	Tile pixels to fill the black parts.
Repeat Last	Repeat the last pixels up to the edge of the clip to fill the black parts.

Filter

Apply filtering to the pixels that moved in the image.

Filter	Result
Nearest	No filtering is applied. The pixel of the texture closest to the screen pixel is displayed.
Linear	Basic bilinear filtering.
Mitchell-Netravali	Bicubic reconstruction filter designed to minimize reconstruction artifacts. This is the default option.
Catmull-Rom	Bicubic reconstruction filter exhibiting a reasonably sharp frequency response.
Anisotropic	Non-proportional filtering between X and Y (faster to process than EWA).
Aniso + Linear	A combination of Anisotropic and Linear filtering.
EWA	A high-quality elliptical weighted average filter that determines the proportions of an elliptical area around every pixel to perform a weighted sampling of the colours (slower to process than other filters).
EWA + Linear	A combination of EWA and Linear filtering.

Output Resolution

Output Resolution option

Select whether the Result output has the same resolution as the Front Clip, is automatically scaled so all pixels from the Front clip are visible, or has a custom resolution.

Select:	For:
Same as Front	The images coming out from the Result and OutMatte outputs have the same size as the image connected to the Front input.
Auto Scale	The resolution of the images coming out from the Result and OutMatte outputs is adjusted so all pixels from the clip connected to the Front input are still visible.
User Defined	The width and height of the images coming out from the Result and OutMatte outputs can be adjusted to a custom value.

Tip: When a Lens Distortion node using the Undistort mode is duplicated, and the mode is changed from Undistort to Distort, the Output Resolution is automatically switched to the User Defined option. This is done to restore the original width and height values of a clip when the distortion is put back after it was first removed using the Auto Scale option. The width and height information of a clip can also be propagated to the Lens Distortion node using the usual Set Info From Clip (T-Click keyboard shortcut) or Paste Special workflows.

Node Preferences

The appearance of the Centre, Detection Lines, Perspective, and Spline manipulators can be modified from the Node Prefs menu.