Skip to content

Latest commit

 

History

History
68 lines (50 loc) · 2.86 KB

README.md

File metadata and controls

68 lines (50 loc) · 2.86 KB

frame-transforms

frame-transforms is a lightweight, thread-safe, Python-native package to simplify frame transforms in robotics. With it, you can manage and translate between coordinate frames with ease. It features:

  1. Automatic computation of transitive transforms.
  2. Registration and update of relative coordinate frames.
  3. An intuitive, object-oriented API.

Though in beta, the library is extensively tested.

This package was inspired by the interface of posetree and shares much of its functionality but offers a more batteries-included experience. Similarly to posetree's nomenclature, Pose is a location and orientation in space, whereas Transform is an action that describes the change in position and orientation to get from one Pose to another.

Installation

pip install frame-transforms

Application

Consider a simple robot consisting of a mobile base and a camera mounted on a gimbal.

The camera detects an object in its coordinate frame. Where is it in world frame?

# Setup
registry.update(Frame.WORLD, Frame.BASE, base_transform)
registry.update(Frame.BASE, Frame.CAMERA, camera_transform)

# Define the Pose
object_pose = Pose(
    Transform(
        np.array([1, 0, 0]),
        Rotation.from_euler("xyz", [0, 0, 0], degrees=True),
    ),
    parent_frame=Frame.CAMERA,
    registry=registry,
)

# Get the position and orientation of the object in world frame
position_in_world = object_pose.get_position(Frame.WORLD)
orientation_in_world = object_pose.get_orientation(Frame.WORLD)

ROS Integration

Simply wrap the Register in a ROS node, subscribing to pose updates and publishing/service-calling the poses. The Register is thread-safe, so callbacks are simple.

Alternatives

  • tf2: Heavyweight, requires ROS.
  • posetree: Requires PoseTree subclass implementation.

Examples

Development Setup

  • Clone and cd into this repository.
  • Set up virtual environment.
    • python -m venv venv
    • source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows)
  • Install package with dev and test dependencies
    • pip install -e '.[dev,test]'

Implementation Details

  • Transforms are stored as a tree starting from the world frame (provided at Registry initialization).
  • To optimize run-time performance, the paths between all pairs of frames are eagerly precomputed and stored when a frame is added.
    • Therefore, the runtime complexity on request is proportional to the shortest path, instead of all frames in the case of a full graph search.
  • Transitive transforms themselves are only computed on-demand because an intermediate transform can change.
    • This is preferred because poses often change more often than they are requested.