API reference

The calibration module

Contains implementations of multiple calibration algorithms and a unified method calibrate() to run the calibration using the desired algorithm.

calibration.calibration.calibrate(T1, T2, method='B', n=1, algorithm='DNL', **kwargs)

Run the calibration using the method defined as argument

Parameters:
Returns:

The homogeneous extrinsic sensor to sensor calibration

Return type:

ndarray, shape (4,4)

Raises:

ValueError – Raised if unknown calibration algorithm

[Ali2019]

I. Ali, O. Suominen, A. Gotchev, and E. R. Morales, “Methods for simultaneous robot-world-hand-eye calibration: A comparative study”, Sensors, vol. 19, no. 12, p. 2837, 2019.

[Park2020]

C. Park, P. Moghadam, S. Kim, S. Sridharan, and C. Fookes, “Spatiotemporal camera-lidar calibration: A targetless and structureless approach”, IEEE Robotics and Automation Letters, vol. 5, no. 2, pp. 1556–1563, 2020.

[Taylor2015]

Z. Taylor and J. Nieto, “Motion-based calibration of multimodal sensor arrays”, in 2015 IEEE International Conference on Robotics and Automation (ICRA), 2015, pp. 4843–4850.

[Zhuang1994]

H. Zhuang and Z. Qu, “A new identification Jacobian for robotic hand/eye calibration”, IEEE Transactions on Systems, Man, and Cybernetics, vol. 24, no. 8, pp. 1284–1287, 1994.

The trajectory module

Contains a single class to represent trajectories

class calibration.trajectory.Trajectory(trajectory=[], time=[])

A class to represent trajectories

p

(x,y,z) positions of the trajectory poses

Type:

list

R

3x3 rotation matrices of the trajectory poses

Type:

list

t

Timestamps for the trajectory poses

Type:

list

__getitem__(key)

Enable (multi)indexing using int or slice

Parameters:

key (int or slice) – The (multi)indexing key for the subtrajectory

Returns:

The desired subtrajectory

Return type:

Trajectory

Raises:

ValueError – Raised if key is not int or slice

Todo

Implement boolean indexing

__init__(trajectory=[], time=[])

Initialize the trajectory

Parameters:

  • trajectory (list, optional) – Trajectory poses in homogeneous 4x4 matrix format

  • time (list, optional) – Timestamps for trajectory poses

Raises:

ValueError – Raised if the trajectory and time lengths don’t match

__len__()

Return length of trajectory

as_array()

Get homogeneous transition matrices

Returns:

Size (n,4,4) array of transitions

Return type:

ndarray

as_transitions()

Get homogeneous transition matrices

Returns:

Length n list of size (4,4) ndarrays of transition matrices

Return type:

list

get_euler()

Get rpy values

Returns:

Size (n,3) array of rpy values

Return type:

ndarray

get_quaternion()

Get quaternions

Returns:

Size (n,4) array of quaternions in scalar-last-format (qx qy qz qw)

Return type:

ndarray

get_xyz()

Get xyz values

Returns:

Size (n,3) array of xyz values

Return type:

ndarray

interpolate(t, timeshift=0)

Return trajectory interpolated to given timestamps

Parameters:

  • t (list) – Timestamps to interpolate to

  • timeshift (int, optional) – Optional timeshift to apply before interpolation

Returns:

The interpolated trajectory

Return type:

Trajectory

relative_pose(method='B', n=1)

Return trajectory of relative poses w.r.t method

Parameters:

  • method (str, optional) –

    The method for selecting the reference frame for relative poses. Can take the following values:

    • A, the first pose

    • B, pose k-n

    • C, keypoint every n-th point

  • n (int, optional) – See meaning from method. Ignored for method A

Returns:

The relative trajectory

Return type:

Trajectory

Raises:

ValueError – Raised if method not in {A, B, C}

save(file)

Save the trajectory in TUM format (https://vision.in.tum.de/data/datasets/rgbd-dataset/file_formats)

Parameters:

file (path-like) – The output file. Existing file will be overwritten.

The utils.io module

Contains helper functions for I/O operations

calibration.utils.io.get_trajectories(trajectories, estimate=False)

Read trajectories from file in TUM format (https://vision.in.tum.de/data/datasets/rgbd-dataset/file_formats)

Parameters:

  • trajectories (list) – A list of trajectory files to read

  • estimate (bool, optional) – If True, tries to match the timestamps of trajectories[1:] with trajectories[0] based on when the absolute Cartesian movement is above a threshold (5e-2)

Returns:

List of calibration.trajectory.Trajectory

Return type:

list

Todo

Make the estimation threshold a parameter

The utils.plotting module

Contains helper functions for plotting

calibration.utils.plotting.plot_axes(T, scale=0.1, ax=None, label=None)

Plot the coordinate system given by transformation T

Parameters:

  • T (ndarray) – 4x4 transformation matrix

  • scale (float, optional) – The scale of the unit vectors to plot

  • ax (Axes3D, optional) – A mplot3d axes to plot on. Default plt.gca().

calibration.utils.plotting.plot_trajectory(T, *args, ax=None, **kwargs)

Plot the trajectory

Parameters:

  • T (Trajectory) – The trajectory to plot

  • ax (Axes3D, optional) – A mplot3d axes to plot on. Default plt.gca()

  • args – Passed to matplotlib’s plot command

  • kwargs – Passed to matplotlib’s plot command

calibration.utils.plotting.set_axes_equal(ax=None)

Make axes of 3D plot have equal scale so that spheres appear as spheres, cubes as cubes, etc.. This is one possible solution to Matplotlib’s ax.set_aspect('equal') and ax.axis('equal') not working for 3D.

Parameters:

ax (Axes3D, optional) – A mplot3d axes. Default plt.gca().

The utils.tools module

Contains helper functions for general tasks

calibration.utils.tools.as_axis_angle(R)

Transform rotation matrices to axis-angle

Parameters:

R (array_like, shape (3,3)) – A single rotation matrix

Returns:

  • axis (ndarray, shape (3,)) – The rotation axis

  • angle (double) – The rotation angle

calibration.utils.tools.as_rotation_vector(R)

Transform rotation matrices to rotation vectors

Parameters:

R (array_like, shape (n,3,3) or (3,3)) – A single rotation matrix or a stack of matrices, where matrix[i] is the i-th matrix.

Returns:

The rotation vectors corresponding to the inputs

Return type:

ndarray, shape (3,) or (n,3)

calibration.utils.tools.as_transition_matrix(R, t, inv=False)

Returns a transition matrix

Parameters:

  • R (ndarray) – Rotation matrix

  • t (ndarray) – Translation vector

  • inv (bool) – Invert transition

Returns:

Transition matrix

Return type:

ndarray

calibration.utils.tools.get_absolute_error(T, GT)

Get absolute calibration errors

Parameters:

  • T (ndarray, shape (4,4)) – Sensor to sensor calibration

  • GT (ndarray, shape (4,4)) – Ground truth calibration

Returns:

  • translation (double) – The absolute translation error

  • rotation (double) – The absolute rotation error in degrees

calibration.utils.tools.get_relative_error(T1, T2, T)

Get relative calibration errors

Parameters:

  • T1 (Trajectory) – The first sensor trajectory

  • T2 (Trajectory) – The second sensor trajectory

  • T (ndarray, shape (4,4)) – Sensor to sensor calibration

Returns:

  • translation (double) – The mean relative translation error

  • rotation (double) – The mean relative rotation error in degrees

calibration.utils.tools.interpolate_transition(t0, T0, t)

Interpolate between transitions

Parameters:

  • t0 (ndarray) – Time instances for transitions

  • T0 (list of ndarray) – Transition matrices

  • t (ndarray) – Times to compute interpolations at

Yields:

ndarray – The interpolated transitions

calibration.utils.tools.rotation_error(T1, T2, T, degree=False)

Calculates the mean relative rotation error

Parameters:

  • T1 (Trajectory) – The first sensor trajectory

  • T2 (Trajectory) – The second sensor trajectory

  • T (ndarray, shape (4,4)) – Sensor to sensor calibration

  • degree (bool) – Whether to return the errors as degree or rad (default)

Returns:

The relative rotation errors

Return type:

ndarray

calibration.utils.tools.skew(v)

Returns a skew symmetric matrix corresponding to v

Parameters:

v (arraylike) – Vector of size (3,) where v=[vx, vy, vz]

Returns:

The skew symmetric matrix

Return type:

ndarray

calibration.utils.tools.translation_error(T1, T2, T)

Calculates the relative translation error

Parameters:

  • T1 (Trajectory) – The first sensor trajectory

  • T2 (Trajectory) – The second sensor trajectory

  • T (ndarray, shape (4,4)) – Sensor to sensor calibration

Returns:

The relative translation errors

Return type:

ndarray

calibration.utils.tools.wrap_to_pi(angle)

Wrap the input angle between [-pi,pi)

Parameters:

angle (double) – Angle in radians

Returns:

The input wrapped between [-pi,pi)

Return type:

double