Viz Artist User Guide

Version 3.13 | Published March 28, 2019 ©

Advanced Lens Distortion


Here, you find the following information:

Lens distortion replaces the lens deformation, and was introduced with Viz Artist and Engine 3.9. You can now select the distortion algorithm and distortion parameters provider for each individual camera. There is no longer a need for multiple configuration flags, such as render_scale and Virtual Studio.

The distortion algorithm defines how the rendered image is distorted, and the parameters are the input to the distortion algorithm. Typical algorithms expect k1, k2, centershift_x, centershift_y, chipsize_x, chipsize_y, etc.

Important Changes Compared to Previous Versions

  • Activation of lens distortion does not depend on other settings, such as render_scale or entering Virtual Studio mode.

  • You can explicitly select the algorithm and parameter source per camera, also in Viz Artist. There is an auto mode, which attempts to determinate the correct algorithm and parameter mode based on the available data.

  • Now called Lens Distortion instead of Lens Deformation.

  • render_scale is now correctly applied to FieldOfView. There is no longer a jump when enabling or disabling post processing (PP) in the Scene Editor.

Technical note: In previous versions, FOV was adapted when data was received from the external camera. The received value was already modified to compensate the render_scale setting. This could cause wrong results when the setting was not considered for rendering, such as when disabling post processing effects with the PP button. In 3.9.0, the FOV is untouched and modified on the fly while rendering if necessary.

  • Previous versions rejected distortion values if the distortion was too strong, if pixels from the outside of the rendered area would have been moved inside the visible area. The render_scale defines how much of the border around the visible area should be rendered, to be able to “move” parts from outside to the inside - think of the barrel distortion! If distortion values were too high, and non-available pixels from the outside would have been distorted into the screen, it simply used the last valid distortion parameters instead. This could lead to confusion, as the distortion did not use the real values. Now, the distortion uses the values provided, even if some invisible areas show up on the borders. If you see unexpected black or transparent areas around the border, consider increasing the render_scale. You can do this by editing the entry for render_scale in the configuration file. The default value is 0, but you can change it as an example to 1.2 or even higher.

  • New distortion algorithms:

    • Radial: A classic algorithm.

    • Stype and Trackmen: Implemented according to specifications from tracking data providers.

Distortion Algorithms


  • Distortion Mode

    • Inactive: Does not use a distortion algorithm.

    • Auto: Automatically selects one of the algorithms below, depending on available data.

    • Internal: The internal distortion algorithm used in 3.8.x, when reading data from lens file. It uses a forward calculation, using a mesh with the undistorted render result applied as texture. The result then gets distorted by moving the vertices of the mesh. To calculate the distorted position of each vertex, the inverse formula as proposed in the Brown-Conrady model is used in an iterative approach. The distortion is normalized to the resolution.

    • Libero: The distortion algorithm used in 3.8.x when connected to Viz Libero or Viz Arena.

    • Xpecto: The distortion algorithm used in 3.8.x with external data, similar to the Internal approach but normalized to the chipsize.

    • Radial: Radial lens distortion, based on the Brown-Conrady model. See

    • Stype: Lens distortion as expected by Stype, based on the Brown-Conrady model. This method uses a backward calculation, rendering a full screen rectangle with modified texture coordinates, so that we look up in the undistorted texture for each pixel in the final output (distorted space).

    • Trackmen: Lens distortion as expected by Trackmen, based on the Brown-Conrady model. This method uses a similar approach like Stype.

Parameter Providers


  • Parameter Mode

    • Auto: Automatically selects one of the providers below, depending on the received data.

    • Lensfile: Reads zoom/focus from external and calculates all other parameters from lens file.

    • Libero: Reads K1/K2 from Viz Arena or Viz Libero.

    • Manual: Uses parameter from the configuration settings.

    • Tracking Hub: Reads parameters from Tracking Hub.

Configuration File Flags

## Possible distortion modes: 0=INACTIVE, 1=AUTO, 2=INTERNAL, 3=XPECTO, 4=LIBERO, 5=RADIAL, 6=STYPE, 7=TRACKMEN
## Possible distortion param modes: 0=AUTO, 1=MANUAL, 2=LENSFILE, 3=Tracking Hub, 4=LIBERO
camera1_distortion_mode = 0
camera1_distortion_param_mode = 0
camera1_distortion_param_manual = {"centershift_x": 0.000000, "centershift_y": 0.000000, "chipsize_x": 8.800000, "chipsize_y": 5.200000, "k1": 0.000000, "k2": 0.000000}
camera2_distortion_mode = 0
# lens compatibility mode, see note

Important! For new lens calibrations, always use use_lens_compatibility_mode=0.

Lens Compatibility Mode

Until Viz Artist and Engine 3.8.2, the result of the lens deformation was affected by the hd_halfheight setting. This was corrected in 3.8.3, and the lens deformation now generates the same result for hd_halfheight=1 and hd_halfheight=0. However, if you have lens files that were calibrated with hd_halfheight=1 using an older version, the result now differs. In this case, enable use_lens_compatibility_mode.