Transforms in 2D

Functions for converting SE(2) poses (x, y, yaw) and 2D points (x, y) between coordinate frames. For the 3D counterpart see Transforms in 3D.

Convert SE2 poses between frames

Convert between absolute and relative coordinates:

py123d.geometry.transform.abs_to_rel_se2_array(origin, pose_se2_array)[source]

Convert an SE2 array from absolute to relative coordinates.

Computes \(T_\text{rel} = T_\text{origin}^{-1} \cdot T_\text{abs}\) for each pose in the array.

Example:

>>> origin = PoseSE2(1.0, 2.0, np.pi / 2)
>>> poses = np.array([[3.0, 4.0, 0.0]], dtype=np.float64)
>>> rel = abs_to_rel_se2_array(origin, poses)
Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

SE2 array in relative coordinates with the same shape as pose_se2_array.

py123d.geometry.transform.abs_to_rel_se2(origin, pose_se2)[source]

Convert a single SE2 pose from absolute to relative coordinates.

Typed wrapper around abs_to_rel_se2_array().

Computes \(T_\text{rel} = T_\text{origin}^{-1} \cdot T_\text{abs}\).

Example:

>>> origin = PoseSE2(1.0, 1.0, 0.0)
>>> pose = PoseSE2(2.0, 3.0, 0.0)
>>> rel = abs_to_rel_se2(origin, pose)  # PoseSE2(1.0, 2.0, 0.0)
Parameters:

  • origin (PoseSE2) – Origin pose of the relative coordinate system.

  • pose_se2 (PoseSE2) – The absolute SE2 pose to convert.

Return type:

PoseSE2

Returns:

The SE2 pose in relative coordinates.

py123d.geometry.transform.rel_to_abs_se2_array(origin, pose_se2_array)[source]

Convert an SE2 array from relative to absolute coordinates.

Computes \(T_\text{abs} = T_\text{origin} \cdot T_\text{rel}\) for each pose in the array.

Example:

>>> origin = PoseSE2(1.0, 1.0, 0.0)
>>> rel_poses = np.array([[1.0, 1.0, 0.0]], dtype=np.float64)
>>> abs_poses = rel_to_abs_se2_array(origin, rel_poses)  # [[2.0, 2.0, 0.0]]
Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

SE2 array in absolute coordinates with the same shape as pose_se2_array.

py123d.geometry.transform.rel_to_abs_se2(origin, pose_se2)[source]

Convert a single SE2 pose from relative to absolute coordinates.

Typed wrapper around rel_to_abs_se2_array().

Computes \(T_\text{abs} = T_\text{origin} \cdot T_\text{rel}\).

Example:

>>> origin = PoseSE2(1.0, 1.0, 0.0)
>>> rel = PoseSE2(1.0, 1.0, 0.0)
>>> abs_pose = rel_to_abs_se2(origin, rel)  # PoseSE2(2.0, 2.0, 0.0)
Parameters:

  • origin (PoseSE2) – Origin pose of the relative coordinate system.

  • pose_se2 (PoseSE2) – The relative SE2 pose to convert.

Return type:

PoseSE2

Returns:

The SE2 pose in absolute coordinates.

py123d.geometry.transform.reframe_se2_array(from_origin, to_origin, pose_se2_array)[source]

Convert an SE2 array from one reference frame to another.

Equivalent to converting from the source frame to absolute coordinates, then from absolute coordinates to the target frame: abs_to_rel(to_origin, rel_to_abs(from_origin, poses)).

Example:

>>> frame_a = PoseSE2(1.0, 0.0, 0.0)
>>> frame_b = PoseSE2(0.0, 1.0, np.pi / 2)
>>> poses_in_a = np.array([[1.0, 0.0, 0.0]], dtype=np.float64)
>>> poses_in_b = reframe_se2_array(frame_a, frame_b, poses_in_a)
Parameters:
Raises:

TypeError – If the origins are not PoseSE2 or np.ndarray.

Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

The SE2 array in the target frame, indexed by PoseSE2Index.

py123d.geometry.transform.reframe_se2(from_origin, to_origin, pose_se2)[source]

Convert a single SE2 pose from one reference frame to another.

Typed wrapper around reframe_se2_array().

Parameters:

  • from_origin (PoseSE2) – The source origin state in the absolute frame.

  • to_origin (PoseSE2) – The target origin state in the absolute frame.

  • pose_se2 (PoseSE2) – The SE2 pose in the source frame.

Return type:

PoseSE2

Returns:

The SE2 pose in the target frame.

Convert 2D points between frames

The same absolute/relative/reframe operations, applied to 2D points instead of SE2 poses:

py123d.geometry.transform.abs_to_rel_points_2d_array(origin, points_2d_array)[source]

Convert a 2D point array from absolute to relative coordinates.

Computes \(p_\text{rel} = R_\text{origin}^T \cdot (p_\text{abs} - t_\text{origin})\) for each point in the array.

Example:

>>> origin = PoseSE2(1.0, 1.0, 0.0)
>>> points = np.array([[2.0, 2.0], [0.0, 1.0]], dtype=np.float64)
>>> rel_points = abs_to_rel_points_2d_array(origin, points)  # [[1.0, 1.0], [-1.0, 0.0]]
Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

2D points in relative coordinates with the same shape as points_2d_array.

py123d.geometry.transform.abs_to_rel_point_2d(origin, point_2d)[source]

Convert a single 2D point from absolute to relative coordinates.

Typed wrapper around abs_to_rel_points_2d_array().

Computes \(p_\text{rel} = R_\text{origin}^T \cdot (p_\text{abs} - t_\text{origin})\).

Parameters:

  • origin (PoseSE2) – Origin pose of the relative coordinate system.

  • point_2d (Point2D) – The absolute 2D point to convert.

Return type:

Point2D

Returns:

The 2D point in relative coordinates.

py123d.geometry.transform.rel_to_abs_points_2d_array(origin, points_2d_array)[source]

Convert a relative 2D point array to absolute coordinates.

Computes \(p_\text{abs} = R_\text{origin} \cdot p_\text{rel} + t_\text{origin}\) for each point in the array.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

2D points in absolute coordinates with the same shape as points_2d_array.

py123d.geometry.transform.rel_to_abs_point_2d(origin, point_2d)[source]

Convert a single 2D point from relative to absolute coordinates.

Typed wrapper around rel_to_abs_points_2d_array().

Computes \(p_\text{abs} = R_\text{origin} \cdot p_\text{rel} + t_\text{origin}\).

Parameters:

  • origin (PoseSE2) – Origin pose of the relative coordinate system.

  • point_2d (Point2D) – The relative 2D point to convert.

Return type:

Point2D

Returns:

The 2D point in absolute coordinates.

py123d.geometry.transform.reframe_points_2d_array(from_origin, to_origin, points_2d_array)[source]

Convert 2D points from one reference frame to another.

Equivalent to converting from the source frame to absolute coordinates, then from absolute coordinates to the target frame.

Parameters:
Raises:

TypeError – If the origins are not PoseSE2 or np.ndarray.

Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

The 2D points in the target frame, indexed by Point2DIndex.

py123d.geometry.transform.reframe_point_2d(from_origin, to_origin, point_2d)[source]

Convert a single 2D point from one reference frame to another.

Typed wrapper around reframe_points_2d_array().

Parameters:

  • from_origin (PoseSE2) – The source origin state in the absolute frame.

  • to_origin (PoseSE2) – The target origin state in the absolute frame.

  • point_2d (Point2D) – The 2D point in the source frame.

Return type:

Point2D

Returns:

The 2D point in the target frame.

Translation along body-frame axes

Translate SE2 poses or 2D points along their local (body) coordinate axes. The yaw / orientation is preserved.

py123d.geometry.transform.translate_se2_along_body_frame(pose_se2, translation)[source]

Translate a single SE2 state along its body frame.

Typed wrapper around translate_se2_array_along_body_frame().

Parameters:

  • pose_se2 (PoseSE2) – SE2 state to translate.

  • translation (Vector2D) – 2D translation in the body frame (x: forward, y: left).

Return type:

PoseSE2

Returns:

Translated SE2 state.

py123d.geometry.transform.translate_se2_along_x(pose_se2, distance)[source]

Translate a single SE2 state along its local X-axis (forward direction).

Shorthand for translate_se2_along_body_frame(pose_se2, Vector2D(distance, 0.0)).

Parameters:

  • pose_se2 (PoseSE2) – SE2 state to translate.

  • distance (float) – Distance to translate along the local X-axis.

Return type:

PoseSE2

Returns:

Translated SE2 state.

py123d.geometry.transform.translate_se2_along_y(pose_se2, distance)[source]

Translate a single SE2 state along its local Y-axis (left direction).

Shorthand for translate_se2_along_body_frame(pose_se2, Vector2D(0.0, distance)).

Parameters:

  • pose_se2 (PoseSE2) – SE2 state to translate.

  • distance (float) – Distance to translate along the local Y-axis.

Return type:

PoseSE2

Returns:

Translated SE2 state.

py123d.geometry.transform.translate_se2_array_along_body_frame(pose_se2_array, translation)[source]

Translate an array of SE2 states along their respective body frames.

Each pose is translated by the same translation vector, expressed in its local coordinate frame (x: forward, y: left). The yaw component is unchanged.

Example:

>>> poses = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, np.pi / 2]], dtype=np.float64)
>>> translated = translate_se2_array_along_body_frame(poses, Vector2D(1.0, 0.0))
>>> # First pose moves +1 in x; second pose (rotated 90 deg) moves +1 in y.
Parameters:

  • pose_se2_array (ndarray[tuple[Any, ...], dtype[float64]]) – Array of SE2 states with shape (..., 3), indexed by PoseSE2Index in the last dimension.

  • translation (Vector2D) – 2D translation in the body frame (x: forward, y: left).

Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

Translated SE2 array with the same shape as pose_se2_array.

py123d.geometry.transform.translate_2d_along_body_frame(points_2d, yaws, x_translate, y_translate)[source]

Translate 2D points along their respective body frames.

Unlike translate_se2_array_along_body_frame(), this function accepts separate arrays for orientations and per-point translation distances, which is useful when each point has a different translation.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Returns:

Array of translated 2D points, indexed by Point2DIndex.