pydistort.Intrinsic#

class pydistort.Intrinsic(intrinsic_matrix: ndarray | None = None)[source]#

Note

This class represents the intrinsic transformation, which is the last step of the process.

The process to correspond a 3D-world point to a 2D-image point in the stenopic camera model is as follows:

  1. The world_3dpoints (\(X_W\)) are expressed in the camera coordinate system using the rotation and translation matrices to obtain the camera_3dpoints (\(X_C\)).

  2. The camera_3dpoints (\(X_C\)) are normalized by dividing by the third coordinate to obtain the normalized_points (\(x_N\)).

  3. The normalized_points (\(x_N\)) are distorted by the distortion model using the coefficients \(\{\lambda_1, \lambda_2, \lambda_3, \ldots\}\) to obtain the distorted_points (\(x_D\)).

  4. The distorted_points (\(x_D\)) are projected onto the image plane using the intrinsic matrix K to obtain the image_points (\(x_I\)).

This tranformation can be decomposed into 3 main steps:

  1. Extrinsic: Transform the world 3dpoints to normalized_points using the extrinsic parameters (rotation and translation).

  2. Distortion: Transform the normalized_points to distorted_points using the distortion model.

  3. Intrinsic: Transform the distorted_points to image_points using the intrinsic matrix K.

The equation used for the intrinsic transformation is:

\[\begin{split}\begin{align*} x_I &= K \cdot x_D \\ \end{align*}\end{split}\]

where \(x_D\) is the distorted points, \(x_I\) is the image points, and \(K\) is the intrinsic matrix defined as:

Note

If no distortion is applied, the distorted_points are equal to the normalized_points.

Parameters:

intrinsic_matrix (Optional[numpy.ndarray], optional) – The intrinsic matrix of the camera. It should be a 3x3 matrix. Default is None.

Example

Create an intrinsic object with a given intrinsic matrix:

import numpy as np
from pydistort import Intrinsic

intrinsic_matrix = np.array([[1000, 0, 320],
                             [0, 1000, 240],
                             [0, 0, 1]])
intrinsic = Intrinsic(intrinsic_matrix)

Then you can use the intrinsic object to transform distorted_points to image_points:

distorted_points = np.array([[100, 200],
                             [150, 250],
                             [200, 300]])
result = intrinsic.transform(distorted_points)
image_points = result.image_points
print(image_points)

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

result = intrinsic.transform(distorted_points, dx=True, dp=True)
image_points_dx = result.jacobian_dx  # Jacobian of the image points with respect to the distorted points
image_points_dp = result.jacobian_dp  # Jacobian of the image points with respect to the intrinsic parameters
print(image_points_dx)

The inverse transformation can be computed using the inverse_transform method:

inverse_result = intrinsic.inverse_transform(image_points, dx=True, dp=True)
distorted_points = inverse_result.transformed_points  # Shape (..., 2)
print(distorted_points)

See also

For more information about the transformation process, see:

property K: ndarray | None#
property Nparams: int#

Property to return the number of parameters of the transformation.

The number of parameters must be a non-negative integer representing the number of parameters of the transformation.

Returns:

The number of parameters of the transformation.

Return type:

int

_abc_impl = <_abc._abc_data object>#
_inverse_transform(image_points: ndarray, *, dx: bool = False, dp: bool = False) → Tuple[ndarray, ndarray | None, ndarray | None][source]#

This method is called by the pydistort.Transform.inverse_transform() method to perform the inverse intrinsic transformation. This method allows to transform the image_points back to distorted_points using the intrinsic parameters.

Note

For _inverse_transform the input must have shape (Npoints, 2) with float64 type. The output has shape (Npoints, 2) for the distorted points and (Npoints, 2, 2)

The equation used for the inverse transformation is:

\[\begin{split}\begin{align*} x_D &= \frac{x_I - c_x}{f_x} \\ y_D &= \frac{y_I - c_y}{f_y} \\ \end{align*}\end{split}\]

where \(x_I\) is the image points, \(x_D\) is the distorted points, and \(K\) is the intrinsic matrix defined as:

\[\begin{split}K = \begin{bmatrix} f_x & 0 & c_x \\ 0 & f_y & c_y \\ 0 & 0 & 1 \end{bmatrix}\end{split}\]

where \(f_x\) and \(f_y\) are the focal lengths in pixels, and \(c_x\) and \(c_y\) are the coordinates of the principal point in pixels.

Warning

This method is not designed to be used directly for the transformation of points. No checks are performed on the input points, so it is the user’s responsibility to ensure that the input points are valid.

Parameters:

  • image_points (numpy.ndarray) – The image points to be transformed. Shape (Npoints, 2).

  • dx (bool, optional) – If True, compute the Jacobian of the distorted points with respect to the image points. Default is False.

  • dp (bool, optional) – If True, compute the Jacobian of the distorted points with respect to the intrinsic parameters. Default is False.

Returns:

  • distorted_points (numpy.ndarray) – The transformed distorted points in the camera coordinate system. Shape (Npoints, 2).

  • jacobian_dx (Optional[numpy.ndarray]) – The Jacobian of the distorted points with respect to the image points if dx is True. Otherwise None. Shape (Npoints, 2, 2), where the last dimension represents (dx, dy).

  • jacobian_dp (Optional[numpy.ndarray]) – The Jacobian of the distorted points with respect to the intrinsic parameters if dp is True. Otherwise None. Shape (Npoints, 2, 4), where the last dimension represents (dfx, dfy, dcx, dcy).

_transform(distorted_points: ndarray, *, dx: bool = False, dp: bool = False) → Tuple[ndarray, ndarray | None, ndarray | None][source]#

This method is called by the pydistort.Transform.transform() method to perform the intrinsic transformation. This method allows to transform the distorted_points to image_points using the intrinsic parameters.

Note

For _transform the input must have shape (Npoints, 2) with float64 type. The output has shape (Npoints, 2) for the image points and (Npoints, 2, 2) for the jacobian with respect to the distorted points and (Npoints, 2, 4) for the jacobian with respect to the intrinsic parameters.

The equation used for the transformation is:

\[\begin{split}\begin{align*} x_I &= K \cdot x_D \\ \end{align*}\end{split}\]

where \(x_D\) is the distorted points, \(x_I\) is the image points, and \(K\) is the intrinsic matrix defined as:

\[\begin{split}K = \begin{bmatrix} f_x & 0 & c_x \\ 0 & f_y & c_y \\ 0 & 0 & 1 \end{bmatrix}\end{split}\]

where \(f_x\) and \(f_y\) are the focal lengths in pixels, and \(c_x\) and \(c_y\) are the coordinates of the principal point in pixels.

Warning

This method is not designed to be used directly for the transformation of points. No checks are performed on the input points, so it is the user’s responsibility to ensure that the input points are valid.

Parameters:

  • distorted_points (numpy.ndarray) – The distorted points to be transformed. Shape (Npoints, 2).

  • dx (bool, optional) – If True, compute the Jacobian of the image points with respect to the distorted points. Default is False.

  • dp (bool, optional) – If True, compute the Jacobian of the image points with respect to the intrinsic parameters. Default is False.

Returns:

  • image_points (numpy.ndarray) – The transformed image points in the camera coordinate system. Shape (Npoints, 2).

  • jacobian_dx (Optional[numpy.ndarray]) – The Jacobian of the image points with respect to the distorted points if dx is True. Otherwise None. Shape (Npoints, 2, 2), where the last dimension represents (dx, dy).

  • jacobian_dp (Optional[numpy.ndarray]) – The Jacobian of the image points with respect to the intrinsic parameters if dp is True. Otherwise None. Shape (Npoints, 2, 4), where the last dimension represents (dfx, dfy, dcx, dcy).

property cx: float#
property cy: float#
property focal_length_x: float | None#

Get or set the focal length fx of the intrinsic transformation.

The focal length is a float representing the focal length of the camera in pixels in x direction.

This parameter is the component K[0, 0] of the intrinsic matrix K of the camera.

Note

An alias for focal_length_x is fx.

See also

Returns:

The focal length of the camera in pixels in x direction. (or None if not set)

Return type:

Optional[float]

property focal_length_y: float | None#

Get or set the focal length fy of the intrinsic transformation.

The focal length is a float representing the focal length of the camera in pixels in y direction.

This parameter is the component K[1, 1] of the intrinsic matrix K of the camera.

Note

An alias for focal_length_y is fy.

See also

Returns:

The focal length of the camera in pixels in y direction. (or None if not set)

Return type:

Optional[float]

property fx: float#
property fy: float#
property input_dim: int#

Property to return the input dimension of the transformation.

The input dimension must be a positive integer representing the number of dimensions of the input points.

Returns:

The number of dimensions of the input points.

Return type:

int

property intrinsic_matrix: ndarray | None#

Get or set the intrinsic matrix of the intrinsic transformation.

The intrinsic matrix is a 3x3 matrix representing the intrinsic parameters of the camera.

\[\begin{split}K = \begin{bmatrix} f_x & 0 & c_x \\ 0 & f_y & c_y \\ 0 & 0 & 1 \end{bmatrix}\end{split}\]

Note

An alias for intrinsic_matrix is K.

See also

Returns:

The intrinsic matrix of the camera. (or None if one of the parameters is not set)

Return type:

Optional[numpy.ndarray]

property intrinsic_vector: ndarray | None#

Get or set the intrinsic vector of the intrinsic transformation.

The intrinsic vector is a 4x1 vector representing the intrinsic parameters of the camera.

\[\begin{split}\begin{bmatrix} f_x \\ f_y \\ c_x \\ c_y \end{bmatrix}\end{split}\]

Note

An alias for intrinsic_vector is k.

See also

Returns:

The intrinsic vector of the camera. (or None if one of the parameters is not set)

Return type:

Optional[numpy.ndarray]

property inverse_result_class: type#

Property to return the class used for the result of the inverse transformation.

The default is InverseTransformResult, but subclasses can override this to return a different class.

Returns:

The class used for the result of the inverse transformation.

Return type:

type

is_set() → bool[source]#

Check if the intrinsic parameters are set.

Returns:

True if all intrinsic parameters are set, False otherwise.

Return type:

bool

property k: ndarray | None#
property output_dim: int#

Property to return the output dimension of the transformation.

The output dimension must be a positive integer representing the number of dimensions of the output points.

Returns:

The number of dimensions of the output points.

Return type:

int

property principal_point_x: float | None#

Get or set the principal point cx of the intrinsic transformation.

The principal point is a float representing the principal point of the camera in pixels in x direction.

This parameter is the component K[0, 2] of the intrinsic matrix K of the camera.

Note

An alias for principal_point_x is cx.

See also

Returns:

The principal point of the camera in pixels in x direction. (or None if not set)

Return type:

Optional[float]

property principal_point_y: float | None#

Get or set the principal point cy of the intrinsic transformation.

The principal point is a float representing the principal point of the camera in pixels in y direction.

This parameter is the component K[1, 2] of the intrinsic matrix K of the camera.

Note

An alias for principal_point_y is cy.

See also

Returns:

The principal point of the camera in pixels in y direction. (or None if not set)

Return type:

Optional[float]

property result_class: type#

Property to return the class used for the result of the transformation.

The default is TransformResult, but subclasses can override this to return a different class.

Returns:

The class used for the result of the transformation.

Return type:

type

class pydistort.IntrinsicResult(transformed_points: ndarray, jacobian_dx: ndarray | None = None, jacobian_dp: ndarray | None = None)[source]#

Bases: TransformResult

Subclass of TransformResult to represent the result of the intrinsic transformation.

This class is used to store the result of transforming the distorted_points to image_points, and the optional Jacobians.

  • transformed_points: The transformed image points in the camera coordinate system. Shape (…, 2).

  • jacobian_dx: The Jacobian of the image points with respect to the input distorted points if dx is True. Otherwise None. Shape (…, 2, 2), where the last dimension represents (dx, dy).

  • jacobian_dp: The Jacobian of the image points with respect to the intrinsic parameters if dp is True. Otherwise None. Shape (…, 2, 4), where the last dimension represents (dfx, dfy, dcx, dcy).

Some properties are provided for convenience:

  • image_points: Alias for transformed_points to represent the transformed distorted points. Shape (…, 2).

  • jacobian_df: Part of the Jacobian with respect to the focal length. Shape (…, 2, 2).

  • jacobian_dc: Part of the Jacobian with respect to the principal point. Shape (…, 2, 2).

Note

If no distortion is applied, the distorted_points are equal to the normalized_points.

Warning

If transpose is set to True during the transformation, the output points will have shape (output_dim, …) instead of (…, output_dim), same for the Jacobian matrices.

property image_points: ndarray#

Get the transformed image points.

Returns:

The transformed image points in the camera coordinate system. Shape (…, 2).

Return type:

numpy.ndarray

property jacobian_dc: ndarray | None#

Get the Jacobian of the image points with respect to the principal point.

Returns:

The Jacobian with respect to principal point (dc). Shape (…, 2, 2).

Return type:

Optional[numpy.ndarray]

property jacobian_df: ndarray | None#

Get the Jacobian of the image points with respect to the focal length.

Returns:

The Jacobian with respect to focal length (df). Shape (…, 2, 2).

Return type:

Optional[numpy.ndarray]

class pydistort.InverseIntrinsicResult(transformed_points: ndarray, jacobian_dx: ndarray | None = None, jacobian_dp: ndarray | None = None)[source]#

Bases: InverseTransformResult

Subclass of InverseTransformResult to represent the result of the inverse intrinsic transformation.

This class is used to store the result of transforming the image_points back to distorted_points, and the optional Jacobians.

  • transformed_points: The transformed distorted points in the camera coordinate system. Shape (…, 2).

  • jacobian_dx: The Jacobian of the distorted points with respect to the input image points if dx is True. Otherwise None. Shape (…, 2, 2), where the last dimension represents (dx, dy).

  • jacobian_dp: The Jacobian of the distorted points with respect to the intrinsic parameters if dp is True. Otherwise None. Shape (…, 2, 4), where the last dimension represents (dfx, dfy, dcx, dcy).

Some properties are provided for convenience:

  • distorted_points: Alias for transformed_points to represent the transformed image points. Shape (…, 2).

  • jacobian_df: Part of the Jacobian with respect to the focal length. Shape (…, 2, 2).

  • jacobian_dc: Part of the Jacobian with respect to the principal point. Shape (…, 2, 2).

Note

If no distortion is applied, the distorted_points are equal to the normalized_points.

Warning

If transpose is set to True during the transformation, the output points will have shape (output_dim, …) instead of (…, output_dim), same for the Jacobian matrices.

property distorted_points: ndarray#

Get the transformed distorted points.

Returns:

The transformed distorted points in the camera coordinate system. Shape (…, 2).

Return type:

numpy.ndarray

property jacobian_dc: ndarray | None#

Get the Jacobian of the distorted points with respect to the principal point.

Returns:

The Jacobian with respect to principal point (dc). Shape (…, 2, 2).

Return type:

Optional[numpy.ndarray]

property jacobian_df: ndarray | None#

Get the Jacobian of the distorted points with respect to the focal length.

Returns:

The Jacobian with respect to focal length (df). Shape (…, 2, 2).

Return type:

Optional[numpy.ndarray]