pycvcam.FisheyeDistortion#

FisheyeDistortion Class#

class FisheyeDistortion(parameters=None, constants=None, n_params=None)[source]#

Subclass of the pycvcam.core.Distortion class that represents the fisheye distortion model.

Note

This class represents the distortion transformation, which is the middle step of the process from the world_points to the image_points.

The FisheyeDistortion model in the using a polynomial model on the angle \(\theta\) between the optical axis and the incoming ray.

Lets consider normalized_points in the camera normalized coordinate system \(\vec{x}_n = (x_n, y_n)\), the corresponding distorted_points in the camera normalized coordinate system are given \(\vec{x}_d\) can be obtained by :

\[\vec{x}_d = \text{distort}(\vec{x}_n, \lambda_1, \lambda_2, \lambda_3, \ldots)\]

The model of distortion is given by:

\[\begin{split}\begin{bmatrix} x_d \\ y_d \end{bmatrix} = \begin{bmatrix} x(r, \theta_d) \\ y(r, \theta_d) \end{bmatrix}\end{split}\]

where \(r^2 = x_n^2 + y_n^2\) and \(\theta_d\) is the distorted angle given by:

\[\theta_d = \theta(1 + d_1\theta^2 + d_2\theta^4 + d_3\theta^6 + \ldots)\]

The number of parameters is variable and depends on the number of distortion coefficients \(d_i\) used in the model.

Note

If the number of parameters is n_params, the maximum order of the polynomial is \(2*n_params + 1\). and only odd powers of \(\theta\) are used in the polynomial.

Warning

If the number of parameters n_params is given during instantiation, the given parameters are truncated or extended to the given number of parameters.

Parameters:

  • parameters (Optional[numpy.ndarray], optional) – The parameters of the distortion transformation. It should be a numpy array of shape (n_params,) containing the distortion coefficients ordered as described above. Default is None, which means no distortion is setted.

  • n_params (Optional[Integral], optional) – The number of parameters for the distortion model. If not specified, it will be inferred from the shape of the parameters array.

  • constants (None)

Accessing the parameters of FisheyeDistortion objects#

The parameters and constants properties can be accessing using pycvcam.core.Transform methods. Some additional convenience methods are provided to access commonly used parameters of the FisheyeDistortion model:

See also

FisheyeDistortion.get_di(i)

Get the coefficient for the i-th power of the polynomial decomposition.

FisheyeDistortion.set_di(i, value)

Set the coefficient for the i-th power of the polynomial decomposition.

Performing distortion with FisheyeDistortion objects#

The transform and inverse_transform methods can be used to perform distortion and undistortion using the FisheyeDistortion model (as described in the pycvcam.core.Transform documentation).

See also

The implementation of theses transformations and more details on the options available can be found in the following methods:

FisheyeDistortion._cartesian_to_polar(cartesian)

Convert cartesian coordinates to polar coordinates.

FisheyeDistortion._polar_to_cartesian(polar)

Convert polar coordinates to cartesian coordinates.

FisheyeDistortion._transform(...[, dx, dp])

Compute the transformation from the normalized_points to the distorted_points.

FisheyeDistortion._inverse_transform(...[, ...])

Compute the inverse transformation from the distorted_points to the normalized_points.

Examples#

Create an distortion object with a specific number of parameters:

import numpy
from pycvcam import FisheyeDistortion

parameters = numpy.array([0.1, 0.01, 0.02])

distortion = FisheyeDistortion(parameters=parameters)

Then you can use the distortion object to transform normalized_points to distorted_points:

normalized_points = numpy.array([[0.1, 0.2], [0.3, 0.4], [0.5, 0.6]]) # shape (n_points, 2)

result = distortion.transform(normalized_points)
distorted_points = result.distorted_points # Shape (n_points, 2)
print(distorted_points)

You can also access to the jacobian of the distortion transformation:

result = distortion.transform(normalized_points, dx=True, dp=True)
distorted_points_dx = result.jacobian_dx  # Shape (n_points, 2, 2)
distorted_points_dp = result.jacobian_dp  # Shape (n_points, 2, n_params = 3)
print(distorted_points_dx)
print(distorted_points_dp)

The inverse transformation can be computed using the inverse_transform method:

inverse_result = distortion.inverse_transform(distorted_points, dx=True, dp=True)
normalized_points = inverse_result.normalized_points  # Shape (n_points, 2)
print(normalized_points)

Note

The jacobian with respect to the depth is not computed.

See also

For more information about the transformation process, see: