C++ API and example¶

1. Introduction¶

This page exist in order to extract the examples from the Doxygen documentation, Please have look at the end of this page there are all the examples.

2. C++ API and example¶

class EulerTransform

#include <transformation.hpp>

Represents a 3d transformation as translation vector and Euler angles.

The convention used for the Euler angles is extrinsic xyz. Note that these are actually not proper Euler angles but Tait-Bryan (or Cardan) angles. However, the name “Euler” is often used for them as well and probably better known, so we’ll stick with this name here.

Public Functions

EulerTransform(): Construct identity transformation.

EulerTransform(const Eigen::Isometry3d &tf): Construct from an isometry transformation.

EulerTransform(): Construct identity transformation.

EulerTransform(const Eigen::Isometry3d &tf): Construct from an isometry transformation.

Public Members

Eigen::Vector3d translation: Translational part of the transform.

Eigen::Vector3d euler_xyz: Rotational part of the transform in extrinsic xyz Euler angles [radian].

class Transformation

#include <transformation.hpp>

Represents a 3d transformation.

The transformation consists of a rotation R and a translation T with the rotation being applied first. So the transformed version v’ of a vector v is computed as v' = R*v + T.

Public Functions

Transformation(): Construct an identity transformation.

Transformation(const Eigen::Quaterniond &rotation, const Eigen::Vector3d &translation): Construct transformation from the given rotation and translation.

Transformation operator*(const Transformation &other) const: Compose this transformation with the other.

Eigen::Vector3d operator*(const Eigen::Vector3d &vec) const: Apply the transformation on the given vector (same as apply).

Eigen::Vector3d apply(const Eigen::Vector3d &vec) const: Apply the transformation on the given vector.

Transformation inverse() const: Invert the transformation.

Eigen::Matrix4d matrix() const: Convert transformation to a homogeneous matrix (4x4).

Eigen::Isometry3d isometry() const: Convert transformation to an isometry.

template<class Archive> inline void serialize(Archive &archive)

Transformation(): Construct an identity transformation.

Transformation(const Eigen::Quaterniond &rotation, const Eigen::Vector3d &translation): Construct transformation from the given rotation and translation.

Transformation operator*(const Transformation &other) const: Compose this transformation with the other.

Eigen::Vector3d operator*(const Eigen::Vector3d &vec) const: Apply the transformation on the given vector (same as apply).

Eigen::Vector3d apply(const Eigen::Vector3d &vec) const: Apply the transformation on the given vector.

Transformation inverse() const: Invert the transformation.

Eigen::Matrix4d matrix() const: Convert transformation to a homogeneous matrix (4x4).

Eigen::Isometry3d isometry() const: Convert transformation to an isometry.

template<class Archive> inline void serialize(Archive &archive)

Public Members

Eigen::Quaterniond rotation: Rotation part of the transformation.

Eigen::Vector3d translation: Translation part of the transformation.

Public Static Functions

static Transformation fromRotation(const Eigen::Quaterniond &rotation): Construct transformation using only a rotation (translation is set to zero).

static Transformation fromTranslation(const Eigen::Vector3d &translation): Construct transformation using only a translation.

static Transformation Identity(): Construct an identity transformation.

static Transformation fromRotation(const Eigen::Quaterniond &rotation): Construct transformation using only a rotation (translation is set to zero).

static Transformation fromTranslation(const Eigen::Vector3d &translation): Construct transformation using only a translation.

static Transformation Identity(): Construct an identity transformation.

namespace spatial_transformation

Functions

double compute_mean_transform_error(Eigen::Matrix3Xd source_points, Eigen::Matrix3Xd expected_target_points, Eigen::Isometry3d transform)

Compute mean position error of point cloud transformation.

Transform the source points using the given transformation and compute the mean error to the expected target points.

Parameters:

source_points – Point cloud that is to be transformed.
expected_target_points – Expected point positions after transformation.
transform – Transformation that is applied on source_points.

Returns:

Mean absolute position error of the transformed source points to expected_target_points.

std::pair<Eigen::Matrix3Xd, Eigen::Matrix3Xd> json_point_cloud_to_eigen(const json &json_data, const std::string &first_key, const std::string &second_key)

Extract 3d point cloud in two reference frames from a JSON data structure.

The JSON data is expected to be structured as a sequence of objects where each object contains two members with names specified by first_key and second_key. They are expected to be lists of three numbers each, representing the position of the same point in the first and the second frame.

Example (where “foo” and “bar” are first and second key):

[
  {"foo": [-0.79, 2.11, 0.27], "bar": [-0.54, -0.87, -0.62]},
  {"foo": [-0.93, 2.36, 0.26], "bar": [-0.68, -0.62, -0.63]},
  ...
]

The positions are extracted and stored in a pair of 3xN matrices.

Parameters:

json_data – JSON structure as described above.
first_key – Name of the entries containing points in the first frame.
second_key – Name of the entries containing points in the second frame.

Returns:

Pair of 3xN matrices. The first element contains all the points corresponding the first_key, the second element all the points corresponding to second_key.

std::pair<Eigen::Matrix3Xd, Eigen::Matrix3Xd> read_point_clouds_from_json_file(const std::filesystem::path &json_file, const std::string &first_key, const std::string &second_key)

Read 3d point cloud in two reference frames from a JSON file.

Regarding the expected structure of the JSON file and the meaning of first and second key, see json_point_cloud_to_eigen.

Parameters:

json_file – Path to the JSON file.
first_key – Name of the entries containing points in the first frame.
second_key – Name of the entries containing points in the second frame.

Throws:

std::system_error – If opening the file fails.
std::runtime_error – If the file is not valid JSON or does not have the expected structure.

Returns:

Pair of 3xN matrices. The first element contains all the points corresponding the first_key, the second element all the points corresponding to second_key.

std::tuple<Eigen::Isometry3d, double> compute_transformation_between_point_clouds(const Eigen::Matrix3Xd &from_points, const Eigen::Matrix3Xd &to_points)

Compute transformation between two point clouds.

Expects as input two point clouds and computes a transformation that maps the first one to the second. This can be used to find the transformation between two reference frames if a set of points is given in both frames.

The two point clouds are expected to be of equal size and need to be ordered, i.e. point from_points[i] corresponds to to_points[i] for all i.

Parameters:

from_points – Points in reference frame A.
to_points – Same points in reference frame B.

Returns:

Tuple (tf, mean_error) with

tf: the transformation from A to B and
mean_error: the mean absolute error of the transformation based on the given point clouds.

file CMakeCCompilerId.c

Defines

COMPILER_ID

STRINGIFY_HELPER(X)

STRINGIFY(X)

PLATFORM_ID

ARCHITECTURE_ID

DEC(n)

HEX(n)

C_DIALECT

Functions

int main(int argc, char *argv[])

Variables

char const * info_compiler = "INFO" ":" "compiler[" COMPILER_ID "]"

char const * info_platform = "INFO" ":" "platform[" PLATFORM_ID "]"

char const * info_arch = "INFO" ":" "arch[" ARCHITECTURE_ID "]"

const char * info_language_dialect_default ="INFO" ":" "dialect_default[" C_DIALECT "]"

file CMakeCXXCompilerId.cpp

Defines

COMPILER_ID

STRINGIFY_HELPER(X)

STRINGIFY(X)

PLATFORM_ID

ARCHITECTURE_ID

DEC(n)

HEX(n)

CXX_STD

Functions

int main(int argc, char *argv[])

Variables

char const * info_compiler = "INFO" ":" "compiler[" COMPILER_ID "]"

char const * info_platform = "INFO" ":" "platform[" PLATFORM_ID "]"

char const * info_arch = "INFO" ":" "arch[" ARCHITECTURE_ID "]"

const char * info_language_dialect_default = "INFO" ":" "dialect_default[""98""]"

file pointcloud.hpp

#include <filesystem>

#include <spdlog/logger.h>

#include <Eigen/Eigen>

#include “thirdparty/json.hpp”

Utility functions for computing transform between point clouds.

The functions of this library can be used to compute the transformation between two reference frames, given the positions of a point cloud in both frames.

Example:

JSON file points.json:

[
  {"foo": [-0.79, 2.11, 0.27], "bar": [-0.54, -0.87, -0.62]},
  {"foo": [-0.93, 2.36, 0.26], "bar": [-0.68, -0.62, -0.63]},
  ...
]

Code to load the file and compute the transformation:

// load point clouds from file
const auto points = read_point_clouds_from_json_file(
        "points.json", "foo", "bar");

// compute transformation
const auto &[transformation, mean_error] =
    compute_transformation_between_point_clouds(
        points.first, points.second);

file pointcloud.hpp

#include <filesystem>

#include <spdlog/logger.h>

#include <Eigen/Eigen>

#include “thirdparty/json.hpp”

Utility functions for computing transform between point clouds.

The functions of this library can be used to compute the transformation between two reference frames, given the positions of a point cloud in both frames.

Example:

JSON file points.json:

[
  {"foo": [-0.79, 2.11, 0.27], "bar": [-0.54, -0.87, -0.62]},
  {"foo": [-0.93, 2.36, 0.26], "bar": [-0.68, -0.62, -0.63]},
  ...
]

Code to load the file and compute the transformation:

// load point clouds from file
const auto points = read_point_clouds_from_json_file(
        "points.json", "foo", "bar");

// compute transformation
const auto &[transformation, mean_error] =
    compute_transformation_between_point_clouds(
        points.first, points.second);

file transformation.hpp

#include <Eigen/Eigen>

#include <cereal/cereal.hpp>

3D Transformation

file transformation.hpp

#include <Eigen/Eigen>

#include <cereal/cereal.hpp>

3D Transformation

dir build/spatial_transformation/CMakeFiles/3.16.3

dir build

dir build/spatial_transformation/CMakeFiles

dir build/spatial_transformation/CMakeFiles/3.16.3/CompilerIdC

dir build/spatial_transformation/CMakeFiles/3.16.3/CompilerIdCXX

dir install/spatial_transformation/include

dir include

dir install

dir install/spatial_transformation

dir include/spatial_transformation

dir build/spatial_transformation

dir install/spatial_transformation/include/spatial_transformation