With-Respect-To (+ Expressed-In)

Simple library that manages databases of 3D transformations with explicit accessors.

Goals

• Simple. A single 3D convention is used and is explicitly defined.
• Fast. The user should not worry about the overhead of calling accessors.
• Accessible. Information is accessible from a variety of interfaces on Linux (Python, Julia, Bash).
• Minimalist. The API contains as few methods as possible.

Usage

Example Usage From Python

This is part of python_bindings/src/test.py.

#Connect to a temporary database
TEMPORARY_DATABASE = 1
db = WRT.DbConnector(TEMPORARY_DATABASE)

#Set the pose of frame b with respect to frame a, which does not exist yet (permitted).
pose = SE3.Rx(90, "deg").A
db.In('test').Set('b').Wrt('a').Ei('a').As(pose)

#Set the pose of frame a with respect to the world (default frame)
pose = np.array([[1,0,0,1],[0,1,0,1],[0,0,1,1],[0,0,0,1]])
db.In('test').Set('a').Wrt('world').Ei('world').As(pose)

#Get the pose of frame a with respect to frame b
T_a_b = SE3(db.In('test').Get('a').Wrt('b').Ei('b'))

Example Usage From C++

This is part of test/src/test.cpp.

//Connect to a temporary database
auto wrt = DbConnector(DbConnector::TEMPORARY_DATABASE);

//Set the pose of frame a with respect to the world (default frame)
Affine3d pose;
pose.matrix() << 1,0,0,1, 0,1,0,1, 0,0,1,1, 0,0,0,1;
wrt.In("test").Set("a").Wrt("world").Ei("world").As(pose.matrix());
pose = wrt.In("test").Get("a").Wrt("world").Ei("world");

//Set the pose of frame b with respect to frame a
pose.linear() = AngleAxisd(deg_to_rad(90), Vector3d::UnitX());
pose.translation() << 0,0,0;
wrt.In("test").Set("b").Wrt("a").Ei("a").As(pose.matrix());

//Get the pose of frame a with respect to the world
Matrix4d T_b_a = wrt.In("test").Get("a").Wrt("world").Ei("world");

Example Usage From Bash

> WRT --In test --Get d --Wrt a --Ei a
 0 -1  0  1
 0  0 -1  0
 1  0  0  1
 0  0  0  1
> WRT --compact --In test --Get d --Wrt a --Ei a
0,-1,0,1,0,0,-1,0,1,0,0,1,0,0,0,1
> WRT --In test --Set a --Wrt world --Ei world --As [[1,0,0,1],[0,1,0,1],[0,0,1,1],[0,0,0,0]]
The format of the submitted matrix is wrong (-3).
> WRT --quiet --In test --Set a --Wrt world --Ei world --As [[1,0,0,1],[0,1,0,1],[0,0,1,1],[0,0,0,0]]
> WRT --In test --Set a --Wrt world --Ei world --As [[1,0,0,1],[0,1,0,1],[0,0,1,1],[0,0,0,1]]
> WRT --dir /home/username/other_dir/ --In test --Get d --Wrt a --Ei a
The reference frame a does not exist in this world.

Usage of the Command-Line Interface

Usage: WRT [options] 

Optional arguments:
-h --help    	shows help message and exits
-v --version 	prints version information and exits
-q --quiet   	If a problem arise, do now output any information, fails quietly. [default: false]
-c --compact 	Output a compact representation of the matrix as a comma separated list of 16 numbers in row-major order. [default: false]
-d --dir     	Path to the directory in which the database is located.
--In         	The world name the frame lives in ([a-z][0-9]-). [required]
--Get        	Name of the frame to get ([a-z][0-9]-).
--Set        	Name of the frame to set ([a-z][0-9]-).
--Wrt        	Name of the reference frame the frame is described with respect to ([a-z][0-9]-). [required]
--Ei         	Name of the reference frame the frame is expressed in ([a-z][0-9]-). [required]
--As         	If setting a frame, a string representation of the array defining the pose with rotation R and translation t: [[R00,R01,R02,t0],[R10,R11,R12,t1],[R20,R21,R22,t2],[0,0,0,1]]

Differences With tf2

Although this library might seem to be similar to tf2, there are notable differences that should be taken into account when choosing which one to use:

• 1. tf2 requires running the ROS ecosystem, WRT does not.

  If you are already running ROS for other reasons, it might make more sense to continue using it. However, it might seem excessive to run the whole ROS ecosystem for the sole reason of recording transformations.

• 2. tf2 does transformation interpolation, WRT does not.

  One of the primary use case for tf2 is to linearly interpolate poses through time. WRT does not do such operation and assumes that all transformations are exact at the time at which they are accessed. If the previous pose of a moving frame must be recorded, a timestamp can be appended to the name of the frame to differentiate between the older and newer frames.

• 3. tf2 is designed as a distributed system while WRT is designed as a centralized system.

  While it is possible (and easy) to use WRT over ethernet through a network file system, it is certainly not optimal. Conversely, while it is possible to use tf2 in a setup consisting in a single machine, it really shines when used by many machines over a network. However, be wary of the bandwidth requirements imposed by the frequent transfer of ROS messages over the network.

Performances

Stress-testing the library through the Python interface on a Lenovo X1 Yoga 1st Gen i5 (2016), we got the following results:

• With a tree 10 levels deep, with 3 concurrent writers, the average time for a SET operation was 0.0026 seconds (>390 Hz) on over 99% of the operations.
• With a tree 10 levels deep, with 3 concurrent readers, the average time for a GET operation was 0.0026 seconds (>380 Hz) on over 99% of the operations.
• With a tree 50 levels deep, with 3 concurrent writers, the average time for a SET operation was 0.0031 seconds (>325 Hz) on over 99% of the operations.
• With a tree 50 levels deep, with 3 concurrent readers, the average time for a GET operation was 0.0032 seconds (>315 Hz) on over 99% of the operations.
• With a tree 50 levels deep, with 2 concurrent readers and 1 writer, the average time for an operation was 0.0032 seconds (>315 Hz) on over 99% of the operations.

The GET operations seems to be about 3% slower than the SET operations for the same tree depth. The depth of the tree seems to have a much greater impact as the operations done on the 50 levels tree are about 20% slower than the operations done on the 10 levels tree. Clearly, a tree depth of 50 levels is an edge-case.

Design

• Uses the Eigen library
• Produces and consumes 4x4 transformation Eigen matrices
• Store data in a SQLITE database using sqlite3
• The scene is described by a tree
  • Re-setting a parent node, also changes the children nodes (i.e. assumes a rigid connection between parent and children)
  • If setting a transform would create a loop, the node is reassigned to a new parent. A frame only has a single parent.

Dependencies

• Python 3.x
• Python 3.x Development Files
• C++ 17 Compiler (Yes, you need C++17.)
• CMake > 3.15
• Eigen > 3.4
• pybind11
• SQLiteCpp
• sqlite3

Dependencies Installation

Most dependencies should be provided by your preferred package manager. PyBind11 and SQLiteCpp are included in this repository as submodules and can be easily installed with:

> git submodule update --init --recursive
> cd extern/pybind11
> cmake -S . -B build
> cmake --build build
> sudo cmake --install build
> cd ../SQLiteCpp
> cmake -S . -B build
> cmake --build build
> sudo cmake --install build

Installation From Pre-Compiled Binaries

The latest release contains pre-compiled 64-bit binaries for Linux, that can be used directly once placed in an appropriate directory.

Installation From Source Code

Build Executables

> git clone https://github.com/PhilNad/with-respect-to.git
> cd with-respect-to
> cmake -S . -B build
> cmake --build build

Install Everything

> sudo cmake --install build

Install Command-Line Interface (cli)

> cd cli
> sudo make install

Install Python3 bindings

> cd ../python_bindings
> sudo make install

Installation Verification

> cd ~
> WRT
> python3 -c $'import with_respect_to as WRT'

Debugging

You can use SQLiteStudio to open the database file and read its content through a GUI.