Struct skelly::Skelly

pub struct Skelly<T: Scalar, D = ()> { /* fields omitted */ }

One’s skeleton. Parameterized with numric value and bone userdata type.

Implementations

impl<T, D> Skelly<T, D> where
    T: Scalar, 

pub fn new() -> Self

Returns new empty skelly.

Example

let skelly = Skelly::<f32>::new();

pub fn add_root_with(&mut self, position: Point3<T>, userdata: D) -> usize where
    T: RealField, 

Creates new root bone in the skelly at specified position.

Root bones are ones that have no parent bone.
Returns id of the added root bone.
userdata will be associated with the bone. It maybe be accessed with Skelly::get_userdata and Skelly::get_userdata_mut using returned id.

Example

let mut skelly = Skelly::<f32, &str>::new();
let root = skelly.add_root_with(Point3::origin(), "root-user-data");

pub fn attach_with(
    &mut self,
    relative: Vector3<T>,
    parent: usize,
    userdata: D
) -> usize where
    T: RealField, 

Attaches new bone to an existing bone with specified id.

Returns id of the added bone.
The bone will be placed relative to its parent.
userdata will be associated with the bone. It maybe be accessed with Skelly::get_userdata and Skelly::get_userdata_mut using returned id.

Example

let mut skelly = Skelly::<f32, &str>::new();
let root = skelly.add_root_with(Point3::origin(), "root-user-data");
let bone = skelly.attach_with(Vector3::x(), root, "bone-user-data");

Panics

This method panics if parent index is out of bounds.

pub fn append_rotation(&mut self, bone: usize, rotation: UnitQuaternion<T>) where
    T: RealField, 

Rotates bone with specified id.

Does not affect relative position to the parent and global position for root bones. Affects global position of all descendant bones.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);

let mut globals = [Isometry3::identity(); 2];
skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_old = globals[bone];

// Ensure that bone is placed correctly in global space at (1, 0, 0).
assert!((bone_global_old.translation.vector - Vector3::x()).magnitude() < EPSILON);

// Rotate root bone. It is still at origin.
// Yet global position of the `bone` attached to `root` has changed accordingly.
skelly.append_rotation(root, UnitQuaternion::from_euler_angles(0.0, 0.0, PI / 2.0));

skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_new = globals[bone];

// Ensure that bone is placed correctly in global space after root rotation at (0, 1, 0).
assert!((bone_global_new.translation.vector - Vector3::y()).magnitude() < EPSILON);

Panics

This method panics if bone index is out of bounds.

pub fn prepend_rotation(&mut self, bone: usize, rotation: UnitQuaternion<T>) where
    T: RealField, 

Rotates bone with specified id.

Affect relative position to the parent and global position for root bones. Affects global position of all descendant bones.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);

let mut globals = [Isometry3::identity(); 2];
skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_old = globals[bone];

// Ensure that bone is placed correctly in global space at (1, 0, 0).
assert!((bone_global_old.translation.vector - Vector3::x()).magnitude() < EPSILON);

// Rotate the bone. It is still at origin.
// Yet global position of the `bone` attached to `root` has changed accordingly.
skelly.prepend_rotation(bone, UnitQuaternion::from_euler_angles(0.0, 0.0, PI / 2.0));

skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_new = globals[bone];

// Ensure that bone is placed correctly in global space after root rotation at (0, 1, 0).
assert!((bone_global_new.translation.vector - Vector3::y()).magnitude() < EPSILON);

Panics

This method panics if bone index is out of bounds.

pub fn append_translation(&mut self, bone: usize, translation: Translation3<T>) where
    T: RealField, 

Translates bone with specified id.

Affects relative position to the parent and global position for root bones. Affects global position of all descendant bones.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);

let mut globals = [Isometry3::identity(); 2];
skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_old = globals[bone];

// Ensure that bone is placed correctly in global space at (1, 0, 0).
assert!((bone_global_old.translation.vector - Vector3::x()).magnitude() < EPSILON);

// Translate root bone.
// Global position of the `bone` attached to `root` has changed accordingly.
skelly.append_translation(root, Vector3::z().into());

skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_new = globals[bone];

// Ensure that bone is placed correctly in global space after root translation at (1, 0, 1).
assert!((bone_global_new.translation.vector - (Vector3::x() + Vector3::z())).magnitude() < EPSILON);

Panics

This method panics if bone index is out of bounds.

pub fn set_position(&mut self, bone: usize, position: Vector3<T>)

Sets relative position for bone with specified id. Affects global position of all descendant bones.

This method ignores current relative position of the bone. To apply translation to current relative poistion see Skelly::append_translation.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);

let mut globals = [Isometry3::identity(); 2];
skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_old = globals[bone];

// Ensure that bone is placed correctly in global space at (1, 0, 0).
assert!((bone_global_old.translation.vector - Vector3::x()).magnitude() < EPSILON);

// Set new relative position for the `bone`.
skelly.set_position(bone, Vector3::z());

skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_new = globals[bone];

// Ensure that bone is placed correctly in global space at new position (0, 0, 1).
assert!((bone_global_new.translation.vector - Vector3::z()).magnitude() < EPSILON);

Panics

This method panics if bone index is out of bounds.

pub fn get_position(&mut self, bone: usize) -> Vector3<T> where
    T: RealField, 

Returns current bone position relative to parent.

pub fn set_orientation(&mut self, bone: usize, orientation: UnitQuaternion<T>)

Sets relative orientation for bone with specified id. Affects global position of all descendant bones.

This method ignores current relative position of the bone. To apply translation to current relative poistion see Skelly::append_translation.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);

let mut globals = [Isometry3::identity(); 2];
skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_old = globals[bone];

// Ensure that bone is placed correctly in global space at (1, 0, 0).
assert!((bone_global_old.translation.vector - Vector3::x()).magnitude() < EPSILON);

// Set new relative orientation for the `bone`.
skelly.set_orientation(root, UnitQuaternion::from_euler_angles(0.0, 0.0, PI / 2.0));

skelly.write_globals(&Isometry3::identity(), &mut globals);
let bone_global_new = globals[bone];

// Ensure that bone is placed correctly in global space at new position (0, 0, 1).
assert!((bone_global_new.translation.vector - Vector3::y()).magnitude() < EPSILON);

Panics

This method panics if bone index is out of bounds.

pub fn get_orientation(&mut self, bone: usize) -> UnitQuaternion<T> where
    T: RealField, 

Returns current bone orientation relative to parent.

pub fn get_isometry(&mut self, bone: usize) -> Isometry3<T> where
    T: RealField, 

Returns current bone isometry relative to parent.

pub fn get_userdata(&self, bone: usize) -> &D

Returns reference to userdata associated with the bone.

Panics

This method panics if bone index is out of bounds.

Example

let mut skelly = Skelly::<f32, &str>::new();
let root = skelly.add_root_with(Point3::origin(), "root-bone-data");
let bone = skelly.attach_with(Vector3::x(), root, "another-bone-data");

assert_eq!(*skelly.get_userdata(root), "root-bone-data");
assert_eq!(*skelly.get_userdata(bone), "another-bone-data");

pub fn get_userdata_mut(&mut self, bone: usize) -> &mut D

Returns mutable reference to userdata associated with the bone.

Panics

This method panics if bone index is out of bounds.

Example

let mut skelly = Skelly::<f32, Vec<&str>>::new();
let root = skelly.add_root_with(Point3::origin(), vec![]);

skelly.get_userdata_mut(root).push("another-root-data-entry");
assert_eq!(*skelly.get_userdata(root), ["another-root-data-entry"]);

pub fn set_userdata(&mut self, bone: usize, userdata: D)

Associated new userdata with the bone.

Panics

This method panics if bone index is out of bounds.

Example

let mut skelly = Skelly::<f32, &str>::new();
let root = skelly.add_root_with(Point3::origin(), "initial-root-data");

skelly.set_userdata(root, "new-root-data");
assert_eq!(*skelly.get_userdata(root), "new-root-data");

pub fn get_parent(&self, bone: usize) -> Option<usize>

Returns parent of the specified bone. Returns None for root bones.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);

assert_eq!(skelly.get_parent(bone), Some(root));

Panics

This method panics if bone index is out of bounds.

pub fn len(&self) -> usize

Returns number of bones in the skelly.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);

assert_eq!(skelly.len(), 2);

pub fn write_globals(
    &self,
    skelly_global: &Isometry3<T>,
    globals: &mut [Isometry3<T>]
) where
    T: RealField, 

Fills slice of Isometry3 with global isometries for each bone of the skelly.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);

let mut globals = [Isometry3::identity(); 2];
skelly.write_globals(&Isometry3::identity(), &mut globals);

pub fn assume_posture(&mut self, posture: &Posture<T>) where
    T: Copy, 

Makes the skelly to assume specifed posture.

pub fn iter_chain(&self, bone: usize) -> impl Iterator<Item = usize> + '_

Iterates through bone ancestors up until root bone is reached yielding their ids.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);
let tip = skelly.attach(Vector3::x(), bone);

assert_eq!(skelly.iter_chain(tip).collect::<Vec<_>>(), [bone, root]);

Panics

This method panics if bone index is out of bounds.

pub fn iter_children(&self, parent: usize) -> impl Iterator<Item = usize> + '_

Iterates through the bone’s direct descendants yielding their ids.

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let left = skelly.attach(Vector3::x(), root);
let right = skelly.attach(Vector3::x(), root);

assert_eq!(skelly.iter_children(root).collect::<Vec<_>>(), [left, right]);

This method is not very efficient. As it effectively scans sub-slice [bone..] Use with caution for too complex skellies in hot-paths.

TODO: Consider adding skelly building phase to pack siblings together.

Panics

This method panics if bone index is out of bounds.

impl<T> Skelly<T> where
    T: Scalar, 

pub fn add_root(&mut self, position: Point3<T>) -> usize where
    T: RealField, 

Creates new root bone in the skelly at specified position.

Root bones are ones that have no parent bone.
Returns id of the added root bone.

skelly.add_root(pos) is a more pleasant shorthand for skelly.add_root_with(pos, ());

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());

pub fn attach(&mut self, relative: Vector3<T>, parent: usize) -> usize where
    T: RealField, 

Attaches new bone to an existing bone with specified id.

Returns id of the added bone.
The bone will be placed relative to its parent.

skelly.attach(relative, parent) is a more pleasant shorthand for skelly.attach_with(relative, parent, ());

Example

let mut skelly = Skelly::<f32>::new();
let root = skelly.add_root(Point3::origin());
let bone = skelly.attach(Vector3::x(), root);

Panics

This method panics if parent index is out of bounds.