pycvcam.project_points#

project_points(world_points, intrinsic, distortion, extrinsic, *, transpose=False, dx=False, dp=False, dintrinsic=False, ddistortion=False, dextrinsic=False, intrinsic_kwargs=None, distortion_kwargs=None, extrinsic_kwargs=None)[source]#

Project 3D world_points \(\vec{X}_w\) to 2D image_points \(\vec{x}_i\) using the camera intrinsic, distortion and extrinsic transformations.

As a reminder,

\[\begin{split}\vec{x}_n &= \text{Extrinsic}(\vec{X}_w) \\ \vec{x}_d &= \text{Distortion}(\vec{x}_n) \\ \vec{x}_i &= \text{Intrinsic}(\vec{x}_d) \\\end{split}\]

Where:

  • \(\vec{X}_w\) are the 3D world_points in the world coordinate system \((\vec{E}_x, \vec{E}_y, \vec{E}_z)\).

  • \(\vec{x}_n\) are the 2D normalized_points in the normalized coordinate system \((\vec{I}, \vec{J})\).

  • \(\vec{x}_d\) are the 2D distorted_points in the normalized coordinate system \((\vec{I}, \vec{J})\).

  • \(\vec{x}_i\) are the 2D image_points in the image coordinate system \((\vec{e}_x, \vec{e}_y)\).

Note

The image_points can be then converted to pixel coordinates \((\vec{u}, \vec{v})\) by applying a swap of the axes.

To compute the Jacobians of the image points with respect to the input 3D world points and the projection parameters, set the dx and dp parameters to True. The Jacobians are computed using the chain rule of differentiation and are returned in the result object.

To access the Jacobians, you can use the following properties of the result object:

  • jacobian_dx: The Jacobian of the image points with respect to the input 3D world points. Shape (…, 2, 3).

  • jacobian_dp: The Jacobian of the image points with respect to the projection parameters (extrinsic, distortion, intrinsic). Shape (…, 2, Nextrinsic + Ndistortion + Nintrinsic).

  • jacobian_dintrinsic: Alias for jacobian_dp[..., :Nintrinsic] to represent the Jacobian with respect to the intrinsic parameters. Shape (…, 2, Nintrinsic).

  • jacobian_ddistortion: Alias for jacobian_dp[..., Nintrinsic:Nintrinsic + Ndistortion] to represent the Jacobian with respect to the distortion parameters. Shape (…, 2, Ndistortion).

  • jacobian_dextrinsic: Alias for jacobian_dp[..., Nintrinsic + Ndistortion:] to represent the Jacobian with respect to the extrinsic parameters. Shape (…, 2, Nextrinsic).

Parameters:

  • world_points (ArrayLike) – The 3D points in the world coordinate system. Shape (…, 3).

  • intrinsic (Optional[Intrinsic]) – The intrinsic transformation to be applied to the distorted points. If None, a no intrinsic transformation is applied (identity intrinsic).

  • distortion (Optional[Distortion]) – The distortion model to be applied to the normalized points. If None, a no distortion transformation is applied (identity distortion).

  • extrinsic (Optional[Extrinsic]) – The extrinsic transformation to be applied to the 3D world points. If None, a no extrinsic transformation is applied (identity transformation).

  • transpose (bool, optional) – If True, the input points are assumed to be in the shape (3, …) instead of (…, 3). Default is False. In this case, the output points will be in the shape (2, …) and the jacobians will be in the shape (2, …, 3) and (2, …, n_params) respectively.

  • dx (bool, optional) – If True, compute the Jacobian of the image points with respect to the input 3D world points with shape (…, 2, 3). If False, the Jacobian is not computed. default is False.

  • dp (bool, optional) – If True, compute the Jacobian of the image points with respect to the projection parameters with shape (…, 2, n_params). If True (dintrinsic, ddistortion, dextrinsic are ignored and computed automatically. If False, the Jacobian is not computed. Default is False.

  • dintrinsic (bool, optional) – If True, compute the Jacobian of the image points with respect to the intrinsic parameters only (other dp components are ignored for efficiency and set to nan in the result).

  • ddistortion (bool, optional) – If True, compute the Jacobian of the image points with respect to the distortion parameters only (other dp components are ignored for efficiency and set to nan in the result).

  • dextrinsic (bool, optional) – If True, compute the Jacobian of the image points with respect to the extrinsic parameters only (other dp components are ignored for efficiency and set to nan in the result).

  • intrinsic_kwargs (Optional[dict], optional) – Additional keyword arguments to be passed to the intrinsic transformation.

  • distortion_kwargs (Optional[dict], optional) – Additional keyword arguments to be passed to the distortion transformation.

  • extrinsic_kwargs (Optional[dict], optional) – Additional keyword arguments to be passed to the extrinsic transformation.

Returns:

The result of the projection transformation containing the projected image points and the Jacobians if requested in the image coordinate system.

Return type:

TransformResult

Examples

See a complete example in the gallery: Projecting 3D points to 2D image points with project_points.

On this page

This Page