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 transform_to_parent(&self) -> Result<Isometry3<f64>, CartesianTreeError>

Returns the transformation from this frame to its parent frame.

§Returns

Ok(Isometry3<f64>) if the frame has a parent.
Err(String) if the frame has no parent.

Source

pub fn update_transform<O>( &self, position: Vector3<f64>, orientation: O, ) -> Result<(), CartesianTreeError>
where O: IntoOrientation,

Updates 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.
Err(String) if the frame has no parent.

§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.update_transform(Vector3::new(1.0, 0.0, 0.0), UnitQuaternion::identity())
    .unwrap();

Source

pub fn add_child<O>( &self, name: impl Into<String>, position: Vector3<f64>, orientation: O, ) -> Result<Frame, CartesianTreeError>
where O: IntoOrientation,

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

Ok(Rc<Frame>) the newly added child frame.
Err(String) 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<O>( &self, name: impl Into<String>, desired_position: Vector3<f64>, desired_orientation: O, reference_pose: &Pose, ) -> Result<Frame, CartesianTreeError>
where O: IntoOrientation,

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

Ok(Frame) the new child frame if successful.
Err(CartesianTreeError) if the reference frame is invalid, no common ancestor exists, or a child name conflict occurs.

§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<O>(&self, position: Vector3<f64>, orientation: O) -> Pose
where O: IntoOrientation,

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

Ok(String) the pretty-printed JSON.
Err(CartesianTreeError) on serialization 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 nodes in config). Skips updating root frames (identity assumed) - assumes this frame is the root.