blenderproc.python.camera.LensDistortionUtility module

This file provides to functions to first set up the lens distortion used in this particular BlenderProc run and then to apply the said lens distortion parameters to an image rendered by Blender. Both functions must be called after each other to use the lens distortion feature correctly. The set_lens_distortion fct. has to be called before the rendering takes place and the apply_lens_distortion has to be applied to the rendered images.

For more information on lens distortion see: https://en.wikipedia.org/wiki/Distortion_(optics) Note that, unlike in that wikipedia entry as of early 2021, we’re here using the undistorted-to-distorted formulation.

blenderproc.python.camera.LensDistortionUtility.apply_lens_distortion(image, mapping_coords=None, orig_res_x=None, orig_res_y=None, use_interpolation=True)

This functions applies the lens distortion mapping that needs to be precalculated by bproc.camera.set_lens_distortion().

Without calling this function the set_lens_distortion fct. only increases the image resolution and changes the K matrix of the camera.

Parameters:

• image (Union[List[ndarray], ndarray]) – a list of images or an image to be distorted

• mapping_coords (Optional[ndarray]) – an array of pixel mappings from undistorted to distorted image

• orig_res_x (Optional[int]) – original and output width resolution of the image

• orig_res_y (Optional[int]) – original and output height resolution of the image

• use_interpolation (bool) – if this is True, for each pixel an interpolation will be performed, if this is false the nearest pixel will be used

Return type:

Union[List[ndarray], ndarray]

Returns:

a list of images or an image that have been distorted, now in the desired (original) resolution

blenderproc.python.camera.LensDistortionUtility.set_camera_parameters_from_config_file(camera_intrinsics_file_path, read_the_extrinsics=False, camera_index=0)

This function sets the camera intrinsic parameters based on a config file, currently it only supports the DLR-RMC camera calibration file format used in the “DLR CalDe and DLR CalLab” camera calibration toolbox. The calibration file allows to use multiple cameras, but only one can be used inside of BlenderProc per run.

Parameters:

• camera_intrinsics_file_path (str) – Path to the calibration file

• camera_index (int) – Used camera index

Return type:

Tuple[int, int, ndarray]

Returns:

mapping coordinates from distorted to undistorted image pixels, as returned from set_lens_distortion()

blenderproc.python.camera.LensDistortionUtility.set_lens_distortion(k1, k2, k3=0.0, p1=0.0, p2=0.0, use_global_storage=False)

This function applies the lens distortion parameters to obtain an distorted-to-undistorted mapping for all natural pixels coordinates of the goal distorted image into the real pixel coordinates of the undistorted Blender image. Since such a mapping usually yields void image areas, this function suggests a different (usually higher) image resolution for the generated Blender image. Eventually, the function apply_lens_distortion will make us of this image to fill in the goal distorted image with valid color values by interpolation. Note that when adapting the internal image resolution demanded from Blender, the camera main point (cx,cy) of the K intrinsic matrix is (internally and temporarily) shifted.

This function has to be used together with bproc.postprocessing.apply_lens_distortion(), else only the resolution is increased but the image(s) will not be distorted.

Parameters:

• k1 (float) – First radial distortion parameter (of 3rd degree in radial distance) as defined by the undistorted-to-distorted Brown-Conrady lens distortion model, which is conform to the current DLR CalLab/OpenCV/Bouguet/Kalibr implementations. Note that undistorted-to-distorted means that the distortion parameters are multiplied by undistorted, normalized camera projections to yield distorted projections, that are in turn digitized by the intrinsic camera matrix.

• k2 (float) – Second radial distortion parameter (of 5th degree in radial distance) as defined by the undistorted-to-distorted Brown-Conrady lens distortion model, which is conform to the current DLR CalLab/OpenCV/Bouguet/Kalibr implementations.

• k3 (float) – Third radial distortion parameter (of 7th degree in radial distance) as defined by the undistorted-to-distorted Brown-Conrady lens distortion model, which is conform to the current DLR CalLab/OpenCV/Bouguet/Kalibr implementations. The use of this parameter is discouraged unless the angular field of view is too high, rendering it necessary, and the parameter allows for a distorted projection in the whole sensor size (which isn’t always given by features-driven camera calibration).

• p1 (float) – First decentering distortion parameter as defined by the undistorted-to-distorted Brown-Conrady lens distortion model in (Brown, 1965; Brown, 1971; Weng et al., 1992) and is comform to the current DLR CalLab implementation. Note that OpenCV/Bouguet/Kalibr permute them. This parameter shares one degree of freedom (j1) with p2; as a consequence, either both parameters are given or none. The use of these parameters is discouraged since either current cameras do not need them or their potential accuracy gain is negligible w.r.t. image processing.

• p2 (float) – Second decentering distortion parameter as defined by the undistorted-to-distorted Brown-Conrady lens distortion model in (Brown, 1965; Brown, 1971; Weng et al., 1992) and is comform to the current DLR CalLab implementation. Note that OpenCV/Bouguet/Kalibr permute them. This parameter shares one degree of freedom (j1) with p1; as a consequence, either both parameters are given or none. The use of these parameters is discouraged since either current cameras do not need them or their potential accuracy gain is negligible w.r.t. image processing.

Use_global_storage:

Whether to save the mapping coordinates and original image resolution in a global storage (backward compat for configs)

Return type:

ndarray

Returns:

mapping coordinates from distorted to undistorted image pixels