pydistort.Transform#

class pydistort.Transform[source]#

Bases: ABC

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.

This class provides the base for all transformations in the stenopic camera model. It defines the interface for extrinsic, distortion, and intrinsic transformations.

Each sub-classes must implement the following methods and properties:

  • input_dim: (attribute) The dimension of the input points (should be 2 for 2D points).

  • output_dim: (attribute) The dimension of the output points (should be 2 for

  • Nparams: (attribute) The number of parameters for the transformation, if applicable.

  • _transform: (method) Apply the transformation to the given points.

  • _inverse_transform: (method) Apply the inverse transformation to the given points.

  • is_set: (method) Check if the transformation is set (i.e., if the parameters are initialized).

More details on the transformation methods are provided in the transform and inverse_transform methods.

See also

Note

... in the shape of the attributes indicates that the shape can have any number of leading dimensions, which is useful for batch processing of points.

If given, subclasses of TransformResult and InverseTransformResult should be used to return the results of the transformation and inverse transformation, respectively. The attributes result_class and inverse_result_class can be overridden to specify the result classes for the transformation and inverse transformation, respectively.

abstract 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>#
abstract _inverse_transform(points: ndarray, *, dx: bool = True, dp: bool = True, **kwargs) → Tuple[ndarray, ndarray | None, ndarray | None][source]#

Apply the inverse transformation to the given points.

This method must be implemented by subclasses to apply the inverse transformation to the input points.

Parameters:

  • points (numpy.ndarray) – The input points to be transformed. Shape (Npoints, output_dim).

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

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

  • **kwargs – Additional keyword arguments for the transformation.

Returns:

A tuple containing:

  • transformed_points: The transformed points of shape (Npoints, input_dim).

  • jacobian_dx: The Jacobian matrix with respect to the input points of shape (Npoints, input_dim, output_dim) if dx is True, otherwise None.

  • jacobian_dp: The Jacobian matrix with respect to the parameters of the transformation of shape (Npoints, input_dim, Nparams) if dp is True, otherwise None.

Return type:

Tuple[numpy.ndarray, Optional[numpy.ndarray], Optional[numpy.ndarray]]

abstract _transform(points: ndarray, *, dx: bool = True, dp: bool = True, **kwargs) → Tuple[ndarray, ndarray | None, ndarray | None][source]#

Apply the transformation to the given points.

This method must be implemented by subclasses to apply the transformation to the input points.

Parameters:

  • points (numpy.ndarray) – The input points to be transformed. Shape (Npoints, input_dim).

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

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

  • **kwargs – Additional keyword arguments for the transformation.

Returns:

A tuple containing:

  • transformed_points: The transformed points of shape (Npoints, output_dim).

  • jacobian_dx: The Jacobian matrix with respect to the input points of shape (Npoints, output_dim, input_dim) if dx is True, otherwise None.

  • jacobian_dp: The Jacobian matrix with respect to the parameters of the transformation of shape (Npoints, output_dim, Nparams) if dp is True, otherwise None.

Return type:

Tuple[numpy.ndarray, Optional[numpy.ndarray], Optional[numpy.ndarray]]

abstract 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 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

inverse_transform(points: ndarray, *, transpose: bool = False, dx: bool = False, dp: bool = False, **kwargs) → ndarray[source]#

The given points points are assumed to be with shape (…, output_dim) or (output_dim, …), depending on the value of transpose.

The output transformed_points will have shape (…, input_dim) if transpose is False, or (input_dim, …) if transpose is True.

Warning

The points are converting to float64 before applying the inverse transformation.

The method also computes 2 Jacobian matrices if requested:

  • dx: Jacobian of the transformed points with respect to the input points.

  • dp: Jacobian of the transformed points with respect to the parameters of the transformation.

The jacobian matrice with respect to the input points is a (…, input_dim, output_dim) matrix where:

jacobian_dx[..., 0, 0]  # ∂x_i/∂x_o -> Jacobian of the coordinates x_i with respect to the coordinates x_o.
jacobian_dx[..., 0, 1]  # ∂x_i/∂y_o
...

jacobian_dx[..., 1, 0]  # ∂y_i/∂x_o -> Jacobian of the coordinates y_i with respect to the coordinates x_o.
jacobian_dx[..., 1, 1]  # ∂y_i/∂y_o
...

The Jacobian matrice with respect to the parameters is a (…, input_dim, Nparams) matrix where:

jacobian_dp[..., 0, 0]  # ∂x_i/∂λ_1 -> Jacobian of the coordinates x_i with respect to the first parameter λ_1.
jacobian_dp[..., 0, 1]  # ∂x_i/∂λ_2
...

jacobian_dp[..., 1, 0]  # ∂y_i/∂λ_1 -> Jacobian of the coordinates y_i with respect to the first parameter λ_1.
jacobian_dp[..., 1, 1]  # ∂y_i/∂λ_2
...

The Jacobian matrices are computed only if dx or dp are set to True, respectively.

The output will be a InverseTransformResult object containing the transformed points and the Jacobian matrices if requested.

Parameters:

  • points (numpy.ndarray) – The input points to be transformed. Shape (…, output_dim) (or (output_dim, …) if transpose is True).

  • transpose (bool, optional) – If True, the input points are transposed to shape (output_dim, …). Default is False.

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

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

  • **kwargs – Additional keyword arguments for the transformation.

Returns:

An object containing the transformed points and the Jacobian matrices if requested.

Return type:

InverseTransformResult

Developer Notes#

The subclasses must implement the _inverse_transform method to apply the inverse transformation to the input points.

The _inverse_transform method should:

  • take the input points as a numpy array of shape (Npoints, output_dim)

  • return 3 numpy arrays:

    • transformed_points: The transformed points of shape (Npoints, input_dim).

    • jacobian_dx: The Jacobian matrix with respect to the input points of shape (Npoints, input_dim, output_dim) if dx is True, otherwise None.

    • jacobian_dp: The Jacobian matrix with respect to the parameters of the transformation of shape (Npoints, input_dim, Nparams) if dp is True, otherwise None.

abstract is_set() → bool[source]#

Method to check if the transformation parameters are set.

This method should return True if the transformation parameters are initialized, otherwise False.

Returns:

True if the transformation parameters are set, otherwise False.

Return type:

bool

abstract 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 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

transform(points: ndarray, *, transpose: bool = False, dx: bool = False, dp: bool = False, **kwargs) → ndarray[source]#

The given points points are assumed to be with shape (…, input_dim) or (input_dim, …), depending on the value of transpose.

The output transformed_points will have shape (…, output_dim) if transpose is False, or (output_dim, …) if transpose is True.

Warning

The points are converting to float64 before applying the transformation.

The method also computes 2 Jacobian matrices if requested:

  • dx: Jacobian of the transformed points with respect to the input points.

  • dp: Jacobian of the transformed points with respect to the parameters of the transformation.

The jacobian matrice with respect to the input points is a (…, output_dim, input_dim) matrix where:

jacobian_dx[..., 0, 0]  # ∂x_o/∂x_i -> Jacobian of the coordinates x_o with respect to the coordinates x_i.
jacobian_dx[..., 0, 1]  # ∂x_o/∂y_i
...

jacobian_dx[..., 1, 0]  # ∂y_o/∂x_i -> Jacobian of the coordinates y_o with respect to the coordinates x_i.
jacobian_dx[..., 1, 1]  # ∂y_o/∂y_i
...

The Jacobian matrice with respect to the parameters is a (…, output_dim, Nparams) matrix where:

jacobian_dp[..., 0, 0]  # ∂x_o/∂λ_1 -> Jacobian of the coordinates x_o with respect to the first parameter λ_1.
jacobian_dp[..., 0, 1]  # ∂x_o/∂λ_2
...

jacobian_dp[..., 1, 0]  # ∂y_o/∂λ_1 -> Jacobian of the coordinates y_o with respect to the first parameter λ_1.
jacobian_dp[..., 1, 1]  # ∂y_o/∂λ_2
...

The Jacobian matrices are computed only if dx or dp are set to True, respectively.

The output will be a TransformResult object containing the transformed points and the Jacobian matrices if requested.

Parameters:

  • points (numpy.ndarray) – The input points to be transformed. Shape (…, input_dim) (or (input_dim, …) if transpose is True).

  • transpose (bool, optional) – If True, the input points are transposed to shape (input_dim, …). Default is False.

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

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

  • **kwargs – Additional keyword arguments for the transformation.

Returns:

  • TransformResult – An object containing the transformed points and the Jacobian matrices if requested.

  • Developer Notes

  • ~~~~~~~~~~~~~~~

  • The subclasses must implement the _transform method to apply the transformation to the input points.

  • The _transform method should

  • - take the input points as a numpy array of shape (Npoints, input_dim)

  • - return 3 numpy arrays –

    • transformed_points: The transformed points of shape (Npoints, output_dim).

    • jacobian_dx: The Jacobian matrix with respect to the input points of shape (Npoints, output_dim, input_dim) if dx is True, otherwise None.

    • jacobian_dp: The Jacobian matrix with respect to the parameters of the transformation of shape (Npoints, output_dim, Nparams) if dp is True, otherwise None.

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

Bases: object

A class to represent the result of a transformation.

This class is used to store the results of a transformation, including the transformed points and the Jacobian matrices.

Note

... in the shape of the attributes indicates that the shape can have any number of leading dimensions, which is useful for batch processing of 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.

transformed_points#

The transformed points after applying the transformation. Shape (…, output_dim).

Type:

numpy.ndarray

jacobian_dx#

The Jacobian matrix with respect to the input points. Shape (…, output_dim, input_dim).

Type:

Optional[numpy.ndarray]

jacobian_dp#

The Jacobian matrix with respect to the parameters of the transformation. Shape (…, output_dim, Nparams).

Type:

Optional[numpy.ndarray]

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

Bases: object

A class to represent the result of an inverse transformation.

This class is used to store the results of an inverse transformation, including the transformed points and the Jacobian matrices.

Note

... in the shape of the attributes indicates that the shape can have any number of leading dimensions, which is useful for batch processing of points.

Warning

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

transformed_points#

The transformed points after applying the inverse transformation. Shape (…, input_dim).

Type:

numpy.ndarray

jacobian_dx#

The Jacobian matrix with respect to the input points. Shape (…, input_dim, output_dim).

Type:

Optional[numpy.ndarray]

jacobian_dp#

The Jacobian matrix with respect to the parameters of the transformation. Shape (…, input_dim, Nparams).

Type:

Optional[numpy.ndarray]