Simple library that manages databases of 3D transformations with explicit accessors.
- 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.
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:
- 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.
- 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.
- 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.
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.
- 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.
- 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
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 buildThe latest release contains pre-compiled 64-bit binaries for Linux, that can be used directly once placed in an appropriate directory.
> git clone https://github.com/PhilNad/with-respect-to.git
> cd with-respect-to
> cmake -S . -B build
> cmake --build build> sudo cmake --install build> cd cli
> sudo make install> cd ../python_bindings
> sudo make install> cd ~
> WRT
> python3 -c $'import with_respect_to as WRT'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]
--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]]
> 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.See test/src/test.cpp.
See python_bindings/src/test.py.
You can use SQLiteStudio to open the database file and read its content through a GUI.