kornia.geometry.camera

Projections

kornia.geometry.camera.project_points_z1(points_in_camera)

Project one or more points from the camera frame into the canonical z=1 plane through perspective division.

\[\begin{split}\begin{bmatrix} u \\ v \\ w \end{bmatrix} = \begin{bmatrix} x \\ y \\ z \end{bmatrix} / z\end{split}\]

Note

This function has a precondition that the points are in front of the camera, i.e. z > 0. If this is not the case, the points will be projected to the canonical plane, but the resulting points will be behind the camera and causing numerical issues for z == 0.

Parameters:

points_in_camera (Tensor) – Tensor representing the points to project with shape (…, 3).

Return type:

Tensor

Returns:

Tensor representing the projected points with shape (…, 2).

Example

>>> points = torch.tensor([1., 2., 3.])
>>> project_points_z1(points)
tensor([0.3333, 0.6667])
kornia.geometry.camera.unproject_points_z1(points_in_cam_canonical, extension=None)

Unproject one or more points from the canonical z=1 plane into the camera frame.

\[\begin{split}\begin{bmatrix} x \\ y \\ z \end{bmatrix} = \begin{bmatrix} u \\ v \end{bmatrix} \cdot w\end{split}\]
Parameters:
  • points_in_cam_canonical (Tensor) – Tensor representing the points to unproject with shape (…, 2).

  • extension (Optional[Tensor], optional) – Tensor representing the extension (depth) of the points to unproject with shape (…, 1). Default: None

Return type:

Tensor

Returns:

Tensor representing the unprojected points with shape (…, 3).

Example

>>> points = torch.tensor([1., 2.])
>>> extension = torch.tensor([3.])
>>> unproject_points_z1(points, extension)
tensor([3., 6., 3.])
kornia.geometry.camera.dx_project_points_z1(points_in_camera)

Compute the derivative of the x projection with respect to the x coordinate.

Returns point derivative of inverse depth point projection with respect to the x coordinate.

\[\begin{split}\frac{\partial \pi}{\partial x} = \begin{bmatrix} \frac{1}{z} & 0 & -\frac{x}{z^2} \\ 0 & \frac{1}{z} & -\frac{y}{z^2} \end{bmatrix}\end{split}\]

Note

This function has a precondition that the points are in front of the camera, i.e. z > 0. If this is not the case, the points will be projected to the canonical plane, but the resulting points will be behind the camera and causing numerical issues for z == 0.

Parameters:

points_in_camera (Tensor) – Tensor representing the points to project with shape (…, 3).

Return type:

Tensor

Returns:

Tensor representing the derivative of the x projection with respect to the x coordinate with shape (…, 2, 3).

Example

>>> points = torch.tensor([1., 2., 3.])
>>> dx_project_points_z1(points)
tensor([[ 0.3333,  0.0000, -0.1111],
        [ 0.0000,  0.3333, -0.2222]])
kornia.geometry.camera.project_points_orthographic(points_in_camera)

Project one or more points from the camera frame into the canonical z=1 plane through orthographic projection.

\[\begin{split}\begin{bmatrix} u \\ v \end{bmatrix} = \begin{bmatrix} x \\ y \\ z \end{bmatrix}\end{split}\]
Parameters:

points_in_camera (Tensor) – Tensor representing the points to project.

Return type:

Tensor

Returns:

Tensor representing the projected points.

Example

>>> points = torch.tensor([1., 2., 3.])
>>> project_points_orthographic(points)
tensor([1., 2.])
kornia.geometry.camera.unproject_points_orthographic(points_in_camera, extension)

Unproject one or more points from the canonical z=1 plane into the camera frame.

\[\begin{split}\begin{bmatrix} x \\ y \\ z \end{bmatrix} = \begin{bmatrix} u \\ v \\ w \end{bmatrix}\end{split}\]
Parameters:
  • points_in_camera (Tensor) – Tensor representing the points to unproject with shape (…, 2).

  • extension (Tensor) – Tensor representing the extension of the points to unproject with shape (…, 1).

Return type:

Tensor

Returns:

Tensor representing the unprojected points with shape (…, 3).

Example

>>> points = torch.tensor([1., 2.])
>>> extension = torch.tensor([3.])
>>> unproject_points_orthographic(points, extension)
tensor([1., 2., 3.])
kornia.geometry.camera.dx_project_points_orthographic(points_in_camera)

Compute the derivative of the x projection with respect to the x coordinate.

\[\frac{\partial u}{\partial x} = 1\]
Parameters:

points_in_camera (Tensor) – Tensor representing the points to project.

Return type:

Tensor

Returns:

Tensor representing the derivative of the x projection with respect to the x coordinate.

Example

>>> points = torch.tensor([1., 2., 3.])
>>> dx_project_points_orthographic(points)
tensor([1.])

Distortion

kornia.geometry.camera.distort_points_affine(projected_points_in_camera_z1_plane, params)

Distort one or more points from the canonical z=1 plane into the camera frame.

\[\begin{split}\begin{bmatrix} u \\ v \end{bmatrix} = \begin{bmatrix} f_x & 0 \\ 0 & f_y \end{bmatrix} \begin{bmatrix} x \\ y \end{bmatrix} + \begin{bmatrix} c_x \\ c_y \end{bmatrix}\end{split}\]
Parameters:
  • projected_points_in_camera_z1_plane (Tensor) – Tensor representing the points to distort with shape (…, 2).

  • params (Tensor) – Tensor representing the parameters of the affine distortion model with shape (…, 4).

Return type:

Tensor

Returns:

Tensor representing the distorted points with shape (…, 2).

Example

>>> points = torch.tensor([319.5, 239.5])  # center of a 640x480 image
>>> params = torch.tensor([600., 600., 319.5, 239.5])
>>> distort_points_affine(points, params)
tensor([192019.5000, 143939.5000])
kornia.geometry.camera.undistort_points_affine(distorted_points_in_camera, params)

Undistort one or more points from the camera frame into the canonical z=1 plane.

\[\begin{split}\begin{bmatrix} x \\ y \end{bmatrix} = \begin{bmatrix} u \\ v \end{bmatrix} - \begin{bmatrix} c_x \\ c_y \end{bmatrix} \begin{bmatrix} f_x & 0 \\ 0 & f_y \end{bmatrix}^{-1}\end{split}\]
Parameters:
  • distorted_points_in_camera (Tensor) – Tensor representing the points to undistort with shape (…, 2).

  • params (Tensor) – Tensor representing the parameters of the affine distortion model with shape (…, 4).

Return type:

Tensor

Returns:

Tensor representing the undistorted points with shape (…, 2).

Example

>>> points = torch.tensor([319.5, 239.5])  # center of a 640x480 image
>>> params = torch.tensor([600., 600., 319.5, 239.5])
>>> undistort_points_affine(points, params)
tensor([0., 0.])
kornia.geometry.camera.dx_distort_points_affine(projected_points_in_camera_z1_plane, params)

Compute the derivative of the x distortion with respect to the x coordinate.

\[\begin{split}\frac{\partial u}{\partial x} = \begin{bmatrix} f_x & 0 \\ 0 & f_y \end{bmatrix}\end{split}\]
Parameters:
  • projected_points_in_camera_z1_plane (Tensor) – Tensor representing the points to distort with shape (…, 2).

  • params (Tensor) – Tensor representing the parameters of the affine distortion model with shape (…, 4).

Return type:

Tensor

Returns:

Tensor representing the derivative of the x distortion with respect to the x coordinate with shape (…, 2).

Example

>>> points = torch.tensor([319.5, 239.5])  # center of a 640x480 image
>>> params = torch.tensor([600., 600., 319.5, 239.5])
>>> dx_distort_points_affine(points, params)
tensor([[600.,   0.],
        [  0., 600.]])
kornia.geometry.camera.distort_points_kannala_brandt(projected_points_in_camera_z1_plane, params)

Distort one or more points from the canonical z=1 plane into the camera frame using the Kannala-Brandt model.

Parameters:
  • projected_points_in_camera_z1_plane (Tensor) – Tensor representing the points to distort with shape (…, 2).

  • params (Tensor) – Tensor representing the parameters of the Kannala-Brandt distortion model with shape (…, 8).

Return type:

Tensor

Returns:

Tensor representing the distorted points with shape (…, 2).

Example

>>> points = torch.tensor([319.5, 239.5])  # center of a 640x480 image
>>> params = torch.tensor([1000.0, 1000.0, 320.0, 280.0, 0.1, 0.01, 0.001, 0.0001])
>>> distort_points_kannala_brandt(points, params)
tensor([1982.6832, 1526.3619])
kornia.geometry.camera.undistort_points_kannala_brandt(distorted_points_in_camera, params)

Undistort one or more points from the camera frame into the canonical z=1 plane using the Kannala-Brandt model.

Parameters:
  • distorted_points_in_camera (Tensor) – Tensor representing the points to undistort with shape (…, 2).

  • params (Tensor) – Tensor representing the parameters of the Kannala-Brandt distortion model with shape (…, 8).

Return type:

Tensor

Returns:

Tensor representing the undistorted points with shape (…, 2).

Example

>>> points = torch.tensor([319.5, 239.5])  # center of a 640x480 image
>>> params = torch.tensor([1000.0, 1000.0, 320.0, 280.0, 0.1, 0.01, 0.001, 0.0001])
>>> undistort_points_kannala_brandt(points, params).shape
torch.Size([2])
kornia.geometry.camera.dx_distort_points_kannala_brandt(projected_points_in_camera_z1_plane, params)

Compute the derivative of the x distortion with respect to the x coordinate.

\[\begin{split}\frac{\partial u}{\partial x} = \begin{bmatrix} f_x & 0 \\ 0 & f_y \end{bmatrix}\end{split}\]
Parameters:
  • projected_points_in_camera_z1_plane (Tensor) – Tensor representing the points to distort with shape (…, 2).

  • params (Tensor) – Tensor representing the parameters of the Kannala-Brandt distortion model with shape (…, 8).

Return type:

Tensor

Returns:

Tensor representing the derivative of the x distortion with respect to the x coordinate with shape (…, 2).

Example

>>> points = torch.tensor([1., 2.])
>>> params = torch.tensor([1000.0, 1000.0, 320.0, 280.0, 0.1, 0.01, 0.001, 0.0001])
>>> dx_distort_points_kannala_brandt(points, params)
tensor([[ 486.0507, -213.5573],
        [-213.5573,  165.7147]])