Struct Frame

Source

pub struct Frame { /* private fields */ }

Expand description

Represents a coordinate frame in a Cartesian tree structure.

Each frame can have one parent and multiple children. The frame stores its transformation (position and orientation) relative to its parent.

Root frames (created via Frame::new_origin) have no parent and use the identity transform.

Implementations§

Source §

impl Frame

Source

pub fn new_origin(name: impl Into<String>) -> Self

Creates a new root frame (origin) with the given name.

The origin has no parent and uses the identity transform.

§Arguments

name: The name of the root frame.

§Example

use cartesian_tree::Frame;

let origin = Frame::new_origin("world");

Source

pub fn name(&self) -> String

Returns the name of the frame.

Source

pub fn transformation(&self) -> Result<Isometry3<f64>, CartesianTreeError>

Returns the transformation from this frame to its parent frame.

§Returns

The isometry from this frame to its parent frame.

§Errors

Returns a CartesianTreeError if:

The frame has no parent.

Source

pub fn position(&self) -> Vector3<f64>

Returns the position of this frame relative to its parent frame.

§Returns

The position of the frame in its parent frame.

Source

pub fn orientation(&self) -> Rotation

Returns the orientation of this frame relative to its parent frame.

§Returns

The orientation of the frame in its parent frame.

Source

pub fn set( &self, position: Vector3<f64>, orientation: impl Into<Rotation>, ) -> Result<(), CartesianTreeError>

Sets the frame’s transformation relative to its parent.

This method modifies the frame’s position and orientation relative to its parent frame. It fails if the frame is a root frame (i.e., has no parent).

§Arguments

position: A 3D vector representing the new translational offset from the parent.
orientation: An orientation convertible into a unit quaternion for new orientational offset from the parent.

§Returns

Ok(()) if the transformation was updated successfully.

§Errors

Returns a CartesianTreeError if:

The frame has no parent (i.e., the root frame).

§Example

use cartesian_tree::Frame;
use nalgebra::{Vector3, UnitQuaternion};

let root = Frame::new_origin("root");
let child = root
    .add_child("camera", Vector3::new(0.0, 0.0, 1.0), UnitQuaternion::identity())
    .unwrap();
child.set(Vector3::new(1.0, 0.0, 0.0), UnitQuaternion::identity())
    .unwrap();

Source

pub fn apply_in_parent_frame( &self, isometry: &Isometry3<f64>, ) -> Result<(), CartesianTreeError>

Applies the provided isometry interpreted in the parent frame to this frame.

This method modifies the frame’s position and orientation relative to its current position and orientation. It fails if the frame is a root frame (i.e., has no parent).

§Arguments

isometry: The isometry (describing a motion in the parent frame coordinates) to apply to the current transformation.

§Returns

Ok(()) if the transformation was updated successfully.

§Errors

Returns a CartesianTreeError if:

The frame has no parent (i.e., the root frame).

§Example

use cartesian_tree::Frame;
use nalgebra::{Isometry3, Translation3, Vector3, UnitQuaternion};

let root = Frame::new_origin("root");
let child = root
    .add_child("camera", Vector3::new(1.0, 0.0, 1.0), UnitQuaternion::identity())
    .unwrap();
child.apply_in_parent_frame(&Isometry3::from_parts(Translation3::new(1.0, 0.0, 0.0), UnitQuaternion::identity()))
    .unwrap();

Source

pub fn apply_in_local_frame( &self, isometry: &Isometry3<f64>, ) -> Result<(), CartesianTreeError>

Applies the provided isometry interpreted in this frame to this frame.

This method modifies the frame’s position and orientation relative to its current position and orientation. It fails if the frame is a root frame (i.e., has no parent).

§Arguments

isometry: The isometry (describing a motion in this frame) to apply to the current transformation.

§Returns

Ok(()) if the transformation was updated successfully.

§Errors

Returns a CartesianTreeError if:

The frame has no parent (i.e., the root frame).

§Example

use cartesian_tree::Frame;
use nalgebra::{Isometry3, Translation3, Vector3, UnitQuaternion};

let root = Frame::new_origin("root");
let child = root
    .add_child("camera", Vector3::zeros(), UnitQuaternion::from_euler_angles(0.0, 0.0, std::f64::consts::FRAC_PI_2))
    .unwrap();
child.apply_in_local_frame(&Isometry3::from_parts(Translation3::new(1.0, 0.0, 0.0), UnitQuaternion::identity()))
    .unwrap();

Source

pub fn add_child( &self, name: impl Into<String>, position: Vector3<f64>, orientation: impl Into<Rotation>, ) -> Result<Self, CartesianTreeError>

Adds a new child frame to the current frame.

The child is positioned and oriented relative to this frame.

Returns an error if a child with the same name already exists.

§Arguments

name: The name of the new child frame.
position: A 3D vector representing the translational offset from the parent.
orientation: An orientation convertible into a unit quaternion.

§Returns

The newly added child frame.

§Errors

Returns a CartesianTreeError if:

A child with the same name already exists.

§Example

use cartesian_tree::Frame;
use nalgebra::{Vector3, UnitQuaternion};

let root = Frame::new_origin("base");
let child = root
    .add_child("camera", Vector3::new(0.0, 0.0, 1.0), UnitQuaternion::identity())
    .unwrap();

Source

pub fn calibrate_child( &self, name: impl Into<String>, desired_position: Vector3<f64>, desired_orientation: impl Into<Rotation>, reference_pose: &Pose, ) -> Result<Self, CartesianTreeError>

Adds a new child frame calibrated such that a reference pose, when expressed in the new frame, matches the desired position and orientation.

§Arguments

name: The name of the new child frame.
desired_position: The desired position of the reference pose in the new frame.
desired_orientation: The desired orientation of the reference pose in the new frame.
reference_pose: The existing pose (in some frame A) used as the calibration reference.

§Returns

The new child frame if successful.

§Errors

Returns a CartesianTreeError if:

The reference frame is invalid.
No common ancestor exists.
A child with the same name already exists.

§Example

use cartesian_tree::Frame;
use nalgebra::{Vector3, UnitQuaternion};

let root = Frame::new_origin("root");
let reference_pose = root.add_pose(Vector3::new(1.0, 0.0, 0.0), UnitQuaternion::identity());
let calibrated_child = root.calibrate_child(
    "calibrated",
    Vector3::zeros(),
    UnitQuaternion::identity(),
    &reference_pose,
).unwrap();

Source

pub fn add_pose( &self, position: Vector3<f64>, orientation: impl Into<Rotation>, ) -> Pose

Adds a pose to the current frame.

§Arguments

position: The translational part of the pose.
orientation: The orientational part of the pose.

§Returns

The newly added pose.

§Example

use cartesian_tree::Frame;
use nalgebra::{Vector3, UnitQuaternion};

let frame = Frame::new_origin("base");
let pose = frame.add_pose(Vector3::new(0.5, 0.0, 0.0), UnitQuaternion::identity());

Source

pub fn to_json(&self) -> Result<String, CartesianTreeError>

Serializes the frame tree to a JSON string.

This recursively serializes the hierarchy starting from this frame (ideally the root). Transforms for root frames are set to identity.

§Returns

The serialized tree as a JSON string.

§Errors

Returns a CartesianTreeError if:

On deserialization failure.

Source

pub fn apply_config(&self, json: &str) -> Result<(), CartesianTreeError>

Applies a JSON config to this frame tree by updating matching transforms.

Deserializes the JSON to a temporary structure, then recursively updates transforms where names match (partial apply; ignores unmatched frames in config). Skips updating root frames (identity assumed) - assumes this frame is the root.