tf_tree

A transform tree: it stores time-stamped poses between named frames and answers "where was frame A relative to frame B at time t?". Use it in a control loop, across processes on one host, or in a dataloader with no robot attached.

It is faster than ROS tf2 (below) but is not tf2: no ROS dependency and no drop-in tf2_ros::Buffer, only a one-way /tf ingest bridge (0008). Linux first: shared memory and frozen .tft files are Linux-only (shm feature); the in-process engine is portable.

0.0.x promises nothing between releases. Pin exactly (CHANGELOG.md).

Install

• Rust: cargo add tf_tree
• Python: pip install transform_tree, then import tf_tree
• CLI (tf_tree, alias tft): a binary from the latest release, or cargo install --path crates/tf_tree_cli --features shm
• C ABI, C++ header, ROS 2 bridge: just c-abi-check, just cpp-check, just ros-build

Quickstart

Python, from scratch (just quickstart runs this). Stamps are integer nanoseconds; a pose is [qw, qx, qy, qz, x, y, z].

import tf_tree

tree = tf_tree.build([("map", "base"), ("base", "cam")])
tf_tree.push(tree, "base", "map", 1_000, [1, 0, 0, 0, 1.0, 2.0, 3.0])
tf_tree.push(tree, "base", "map", 2_000, [1, 0, 0, 0, 3.0, 4.0, 5.0])

plan = tree.plan("map", "base")   # compile the route once, reuse it
print(plan.at(1_500)[:3, 3])      # -> [2. 3. 4.]

Rust:

use tf_tree::{Capacity, EdgeCfg, Iso3, Quat, Stamp, TreeBuilder, Vec3};

let tree = TreeBuilder::new()
    .static_edge("base_link", "lidar_top", &Iso3::IDENTITY)   // (parent, child)
    .dynamic_edge("odom", "base_link", EdgeCfg::new(Capacity::history(100.0, 10.0)))
    .build()
    .expect("layout");
let odom = tree.frame("odom").expect("declared");
let base_link = tree.frame("base_link").expect("declared");
let lidar_top = tree.frame("lidar_top").expect("declared");

let w = tree.claim(base_link, odom).expect("unclaimed");   // (child, parent)
let at_x = |x| Iso3::new(Quat::IDENTITY, Vec3::new(x, 0.0, 0.0));
w.push(1_000_000_000, &at_x(0.0)).expect("monotonic");
w.push(1_010_000_000, &at_x(1.0)).expect("monotonic");

let plan = tree.plan(odom, lidar_top).expect("connected");
let g = tree.guard();
let t: Stamp = Stamp::from_nanos(1_005_000_000);
let pose = plan.at(&g, t).expect("in range");
assert!((pose.t.x - 0.5).abs() < 1e-12);

From a recorded bag

MCAP only (for .db3, run ros2 bag convert first):

tft doctor --from-bag drive.mcap                 # what is wrong with this /tf traffic
tft freeze --from-bag drive.mcap -o drive.tft    # index it

tree = tf_tree.open_file("drive.tft")   # an mmap; open per worker, after fork/spawn
poses = tree.plan("base_link", "lidar_top").at(stamps_ns, layout="quat_twist")  # (N, 13)

Against tf2

In-process, one thread, same interpolation, tf2 called natively; 4-core EPYC-Milan, not core-pinned. Both agree to 7e-15 on 50,000 recorded queries.

Without LTO the lookup gap is 1.8×; through the C ABI, 1.5×. Method: tf2.md; sources: EVIDENCE.md.

Not for

Status

The §0.0 tables in PHASE2, PHASE4 and PHASE5 win over this one.

Shared memory is not a sandbox

Processes sharing an arena trust each other: a read-write participant can corrupt it (PHASE2.md §3.10; SECURITY.md). A read-only participant (the default for readers) cannot, and a crashed or hung one cannot wedge the others.

fork() is the sharp edge: a child's inherited handles report ChildDetached. Python's multiprocessing forks by default on Linux, so open the arena inside the worker or use spawn. A frozen .tft survives a fork.

Layout

crates/: tf_tree_math, tf_tree_arena, tf_tree_core, tf_tree (facade), tf_tree_ipc, tf_tree_c, tf_tree_bridge, tf_tree_ingest, tf_tree_py, tf_tree_bench, tf_tree_tf2_sys, tf_tree_cli. ros/ holds the ROS 2 packages. tf_tree_py, tf_tree_tf2_sys and ros/ sit outside the cargo workspace and have their own just recipes. Five crates publish: tf_tree, tf_tree_core, tf_tree_math, tf_tree_arena, tf_tree_ipc. MSRV 1.87.

Docs: docs/README.md · CONTRIBUTING.md · SUPPORT.md · SECURITY.md · CODE_OF_CONDUCT.md

Licence

Dual MIT / Apache-2.0, at your option. See NOTICE.