# 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](https://github.com/robobenjie/posetree?tab=readme-ov-file#philosophy-of-transforms-poses-and-frames)'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
```bash
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?
```python
# 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](https://github.com/MinhxNguyen7/FrameTransforms/blob/main/example.py)
# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "frame-transforms",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "coordinate, frame, geometry, pose, robotics, transformation",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/57/0e/26f01ace1c79183085664775507345671eaa739df233f4a21e0bf35efa1c/frame_transforms-0.3.1.tar.gz",
"platform": null,
"description": "# frame-transforms\n`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:\n\n1. Automatic computation of transitive transforms.\n2. Registration and update of relative coordinate frames.\n3. An intuitive, object-oriented API. \n\nThough in beta, the library is extensively tested.\n\nThis package was inspired by the interface of `posetree` and shares much of its functionality but offers a more batteries-included experience. Similarly to [posetree](https://github.com/robobenjie/posetree?tab=readme-ov-file#philosophy-of-transforms-poses-and-frames)'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.\n\n## Installation\n\n```bash\npip install frame-transforms\n```\n\n## Application\nConsider a simple robot consisting of a mobile base and a camera mounted on a gimbal. \n\nThe camera detects an object in its coordinate frame. Where is it in world frame?\n\n```python\n# Setup\nregistry.update(Frame.WORLD, Frame.BASE, base_transform)\nregistry.update(Frame.BASE, Frame.CAMERA, camera_transform)\n\n# Define the Pose\nobject_pose = Pose(\n Transform(\n np.array([1, 0, 0]),\n Rotation.from_euler(\"xyz\", [0, 0, 0], degrees=True),\n ),\n parent_frame=Frame.CAMERA,\n registry=registry,\n)\n\n# Get the position and orientation of the object in world frame\nposition_in_world = object_pose.get_position(Frame.WORLD)\norientation_in_world = object_pose.get_orientation(Frame.WORLD)\n```\n\n## ROS Integration\n\nSimply 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.\n\n## Alternatives\n- `tf2`: Heavyweight, requires ROS.\n- `posetree`: Requires `PoseTree` subclass implementation.\n\n# [Examples](https://github.com/MinhxNguyen7/FrameTransforms/blob/main/example.py)\n\n# Development Setup\n\n- Clone and `cd` into this repository.\n- Set up virtual environment.\n - `python -m venv venv`\n - `source venv/bin/activate` (Linux/Mac) or `venv\\Scripts\\activate` (Windows)\n- Install package with dev and test dependencies\n - `pip install -e '.[dev,test]'`\n\n# Implementation Details\n\n- Transforms are stored as a tree starting from the world frame (provided at `Registry` initialization).\n- To optimize run-time performance, the paths between all pairs of frames are eagerly precomputed and stored when a frame is added.\n - Therefore, the runtime complexity on request is proportional to the shortest path, instead of all frames in the case of a full graph search.\n- Transitive transforms themselves are only computed on-demand because an intermediate transform can change.\n - This is preferred because poses often change more often than they are requested.\n",
"bugtrack_url": null,
"license": null,
"summary": "Automatically compute and apply coordinate frame transformations",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/MinhxNguyen7/FrameTransforms/"
},
"split_keywords": [
"coordinate",
" frame",
" geometry",
" pose",
" robotics",
" transformation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "feead0a08b78102cfb0f055cdcfab1b234ee6774bd7783a49715d2ddfc093321",
"md5": "beb034650f1cd95a304d0a943a10edae",
"sha256": "c2e95ffb8500422d9f277bffc5fd1b6ea6d49aa63b8f5f5c38d4fd7f363917ca"
},
"downloads": -1,
"filename": "frame_transforms-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "beb034650f1cd95a304d0a943a10edae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6869,
"upload_time": "2025-08-23T05:30:48",
"upload_time_iso_8601": "2025-08-23T05:30:48.025164Z",
"url": "https://files.pythonhosted.org/packages/fe/ea/d0a08b78102cfb0f055cdcfab1b234ee6774bd7783a49715d2ddfc093321/frame_transforms-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "570e26f01ace1c79183085664775507345671eaa739df233f4a21e0bf35efa1c",
"md5": "eac7762a15751f771e580ecdb8e45bcd",
"sha256": "9c8952c8bb95e109aa0eb0449a57bff7074cfd1fb200983c3125123685865941"
},
"downloads": -1,
"filename": "frame_transforms-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "eac7762a15751f771e580ecdb8e45bcd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 17626,
"upload_time": "2025-08-23T05:30:49",
"upload_time_iso_8601": "2025-08-23T05:30:49.318114Z",
"url": "https://files.pythonhosted.org/packages/57/0e/26f01ace1c79183085664775507345671eaa739df233f4a21e0bf35efa1c/frame_transforms-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 05:30:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MinhxNguyen7",
"github_project": "FrameTransforms",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "frame-transforms"
}
JSON
