paralleldomain.utilities.projection

class DistortionLookupTable

Container object for distortion lookup tables used in distortion model pd_fisheye. Can be accessed like any np.ndarray

classmethod from_ndarray(data)

Takes a np.ndarray and creates a DistortionLookupTable instance from it.

Parameters:

data (ndarray) – np.ndarray of shape (N x 2). Array will be sorted by first column. Last two rows will be used to extrapolate for maximum valid angle value of Pi.

Return type:

DistortionLookupTable

Returns:

Distortion lookup table to be used with projection functions using distortion model pd_fisheye.

focal_length_to_fov(focal_length, sensor_size)
Calculates the field of view (FOV) from a given focal length and image size.

FOV is defined as the angle around the optical axis covered by the image.

Parameters:

  • focal_length (float) – Focal length.

  • sensor_size (int) – Sensor size along the axis of focal_length.

Return type:

float

Returns:

Field of view in radians. Returns 0.0 if focal_length <= 0.0.

fov_to_focal_length(fov, sensor_size)
Calculates the focal length from a given field of view (FOV) and image size.

FOV is defined as the angle around the optical axis covered by the image.

Parameters:

  • fov (float) – Field of view in radians.

  • sensor_size (int) – Sensor size along the axis of fov.

Return type:

float

Returns:

Focal length. Returns 0.0 if fov <= 0.0.

points_2d_inside_image(width, height, camera_model, points_2d, points_3d=None)

Returns the indices for an array of 2D image points that are inside the image canvas.

Parameters:

  • width (int) – Pixel width of the image canvas.

  • height (int) – Pixel height of the image canvas.

  • camera_model (str) – One of opencv_pinhole, opencv_fisheye, pd_fisheye. More details in CameraModel.

  • points_2d (ndarray) – A matrix with dimensions (nx2) containing the points that should be tested if inside the image canvas. Points must be in image coordinate system (x,y).

  • points_3d (Optional[ndarray]) – Optional array of size (nx3) which provides the 3D camera coordinates for each point. Required for camera models opencv_pinhole and opencv_fisheye.

Return type:

ndarray

Returns:

An array with dimensions (n,).

project_points_2d_to_3d(k_matrix, camera_model, points_2d, depth, distortion_parameters=None, distortion_lookup=None, interpolate=True)

Maps image plane coordinates to 3D points in Cartesian coordinates.

Parameters:

  • k_matrix (ndarray) – Camera intrinsic matrix. Definition can be found in OpenCV documentation.

  • camera_model (str) – One of opencv_pinhole, opencv_fisheye, pd_fisheye. More details in CameraModel.

  • points_2d (ndarray) – A matrix with dimensions (nx2) containing the points. Points must be in image coordinate system (x,y).

  • depth (ndarray) – Depth mask with the same dimensions as the image canvas.

  • distortion_parameters (Optional[ndarray]) – Array of applicable distortion parameters for distortion models opencv_pinhole and opencv_fisheye.

  • distortion_lookup (Optional[DistortionLookup]) – Table of undistorted and distorted angles. Required for pd_fisheye model.

  • interpolate (bool) – When points are not exactly on an image pixel, apply bi-linear interpolation to estimate the corresponding depth value. Default: True.

Return type:

ndarray

Returns:

A matrix with dimensions (nx3) containing the point projections in 3D using the provided depth mask.

project_points_3d_to_2d(k_matrix, camera_model, points_3d, distortion_parameters=None, distortion_lookup=None)

Projects an array of 3D points in Cartesian coordinates onto an image plane.

Parameters:

  • k_matrix (ndarray) –

    Camera intrinsic matrix. Definition can be found in OpenCV documentation.

  • camera_model (str) – One of opencv_pinhole, opencv_fisheye, pd_fisheye, pd_orthographic. More details in CameraModel.

  • points_3d (ndarray) – A matrix with dimensions (nx3) containing the points. Points must be already in the camera’s coordinate system.

  • distortion_parameters (Optional[ndarray]) – Array of applicable distortion parameters for distortion models opencv_pinhole and opencv_fisheye.

  • distortion_lookup (Optional[DistortionLookup]) – Table of undistorted and distorted angles. Required for pd_fisheye model.

Return type:

ndarray

Returns:

A matrix with dimensions (nx2) containing the point projections. dtype is float and values need to be rounded to integers by the user to receive actual pixel coordinates. Includes all points, independent if they are on the image plane or outside. Points behind the image plane will be projected, too. If values are not valid (e.g., for undistorted pinhole cameras), filtering needs to be applied by the calling function.