Struct Frame 

pub struct Frame { /* private fields */ }

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.

Ownership, lifetimes, and thread safety

All frames of a tree share ownership of a single tree arena: keeping any Frame (or Pose) handle alive keeps the whole tree alive, so a leaf handle is always enough to reach the root. Frames removed via Frame::remove_child become stale; operations on stale handles return CartesianTreeError::FrameRemoved.

Frame is Send + Sync and can be shared freely across threads. All operations are synchronized through a tree-wide read/write lock, and every operation (including multi-frame computations like Pose::in_frame) sees a consistent snapshot of the tree.

Implementations

impl Frame

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

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

This allocates a new tree; all frames added below the root share it. 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");

pub fn name(&self) -> String

Returns the name of the frame.

Returns "<removed>" for stale handles whose frame has been removed from the tree.

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.
• The frame has been removed from its tree.

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

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

Returns

The position of the frame in its parent frame (zero for root frames).

Errors

Returns a CartesianTreeError if:

• The frame has been removed from its tree.

pub fn orientation(&self) -> Result<Rotation, CartesianTreeError>

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

Returns

The orientation of the frame in its parent frame (identity for root frames).

Errors

Returns a CartesianTreeError if:

• The frame has been removed from its tree.

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.

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).
• The frame has been removed from its tree.
• The frame is a derived frame (derived frames are read-only).

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();

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.

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).
• The frame has been removed from its tree.
• The frame is a derived frame (derived frames are read-only).

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();

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.

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).
• The frame has been removed from its tree.
• The frame is a derived frame (derived frames are read-only).

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();

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.
• The frame has been removed from its tree.
• The frame is a derived frame.

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();

pub fn remove_child(&self, name: &str) -> Result<(), CartesianTreeError>

Removes the child with the given name and its entire subtree from the tree.

Existing handles to removed frames become stale and return CartesianTreeError::FrameRemoved when used.

Arguments

• name: The name of the child frame to remove.

Errors

Returns a CartesianTreeError if:

• No child with the given name exists.
• The frame has been removed from its tree.
• The frame is a derived frame.

Example

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

let root = Frame::new_origin("root");
let _ = root
    .add_child("camera", Vector3::new(0.0, 0.0, 1.0), UnitQuaternion::identity())
    .unwrap();
root.remove_child("camera").unwrap();
assert!(root.children().is_empty());

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 pose belongs to a different tree or its frame has been removed.
• No common ancestor exists.
• A child with the same name already exists.
• The frame is a derived frame.

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();

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());

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 serialization failure.
• The frame has been removed from its tree, or is a derived frame.

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.

Arguments

• json: The JSON string to apply.

Returns

Ok(()) if applied successfully (even if partial).

Errors

Returns a CartesianTreeError if:

• On deserialization failure.
• The frame names do not match at the root.
• An orientation in the config has a norm too close to zero to normalize.
• The frame has been removed from its tree, or is a derived frame.

Trait Implementations

impl Add<LazyTranslation> for &Frame

Creates a new derived frame translated by rhs, interpreted in the parent frame of self (matching the Pose operator semantics).

The derived frame resolves transforms through self but is not stored in the tree: it does not appear in children() or serialization, is read-only, and is freed when dropped.

type Output = Frame

The resulting type after applying the + operator.

fn add(self, rhs: LazyTranslation) -> Self::Output

Performs the + operation.

impl Clone for Frame

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Frame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasChildren for Frame

type Node = Frame

fn children(&self) -> Vec<Self>

Returns all children.

impl HasParent for Frame

type Node = Frame

fn parent(&self) -> Option<Self::Node>

Returns the parent of this node, if it exists.

impl Mul<LazyRotation> for &Frame

Creates a new derived frame rotated by rhs about the axes of self (local frame, matching the Pose operator semantics).

The derived frame resolves transforms through self but is not stored in the tree: it does not appear in children() or serialization, is read-only, and is freed when dropped.

type Output = Frame

The resulting type after applying the * operator.

fn mul(self, rhs: LazyRotation) -> Self::Output

Performs the * operation.

impl NodeEquality for Frame

fn is_same(&self, other: &Self) -> bool

Whether this node is the same as another.

impl Sub<LazyTranslation> for &Frame

Creates a new derived frame translated by the inverse of rhs, interpreted in the parent frame of self (matching the Pose operator semantics).

The derived frame resolves transforms through self but is not stored in the tree: it does not appear in children() or serialization, is read-only, and is freed when dropped.

type Output = Frame

The resulting type after applying the - operator.

fn sub(self, rhs: LazyTranslation) -> Self::Output

Performs the - operation.