README.md

Transforms Library

A blazingly fast and efficient coordinate transform library for robotics and computer vision applications.

Overview

This library provides functionality for managing coordinate transformations between different frames of reference. It supports both synchronous and asynchronous operations through feature flags, making it suitable for both real-time and event-driven applications.

For more detailed information, please refer to the documentation. To view the async-specific documentation, use:

cargo doc --open --features async

Features

• Synchronous and Asynchronous APIs: Choose between sync and async implementations via the async feature flag.
• Interpolation: Smooth linear interpolation between transforms at different timestamps.
• Transform Chaining: Automatic computation of transforms between indirectly connected frames.
• Thread-safe Operations: Safe concurrent access to the transform registry.
• Time-based Buffer Management: Automatic cleanup of old transforms.

Usage

Synchronous Example

use std::time::Duration;
use transforms::{
    geometry::{Quaternion, Transform, Vector3},
    time::Timestamp,
    Registry,
};

let mut registry = Registry::new(Duration::from_secs(60));
let timestamp = Timestamp::now();

// Create a transform from frame "base" to frame "sensor"
let transform = Transform {
    translation: Vector3::new(1.0, 0.0, 0.0),
    rotation: Quaternion::identity(),
    timestamp,
    parent: "base".into(),
    child: "sensor".into(),
};

// Add the transform to the registry
registry.add_transform(transform).unwrap();

// Retrieve the transform
let result = registry.get_transform("base", "sensor", timestamp).unwrap();

Asynchronous Example

use std::time::Duration;
use transforms::{
    geometry::{Quaternion, Transform, Vector3},
    time::Timestamp,
    Registry,
};

let registry = Registry::new(Duration::from_secs(60));
let timestamp = Timestamp::now();

let transform = Transform {
    translation: Vector3::new(1.0, 0.0, 0.0),
    rotation: Quaternion::identity(),
    timestamp,
    parent: "base".into(),
    child: "sensor".into(),
};

registry.add_transform(transform).await.unwrap();

// Wait for transform to become available
let result = registry
    .await_transform("base", "sensor", timestamp)
    .await
    .unwrap();

Relationship with ROS2's tf2

This library draws inspiration from ROS2's tf2 (Transform Framework 2), a widely-used transform library in the robotics community. While this crate aims to solve the same fundamental problem of transformation tracking, it does so in its own way.

Similarities with tf2

• Maintains relationships between coordinate frames in a tree structure.
• Buffers transforms over time.
• Supports transform lookups between arbitrary frames.
• Handles interpolation between transforms.
• Provides both synchronous and asynchronous APIs.

Key Differences

• Is a pure Rust implementation, not a wrapper around tf2.
• Makes no attempt to perfectly match the ROS2/tf2 API.
• Focuses on providing an ergonomic Rust-first experience.
• Is independent of ROS2's middleware and communication system.

Non-Goals

This library intentionally limits its scope to rigid body transformations (translation and rotation) commonly used in robotics and computer vision. The following transformations are explicitly not supported and will not be considered for future implementation:

• Scaling transformations
• Skew transformations
• Perspective transformations
• Non-rigid transformations
• Affine transformations beyond rigid body motion
• Converge to parity with ROS2 / tf2
• Extrapolation

License

This project is licensed under the MIT License - see the LICENSE file for details.