Struct blender_armature::BlenderArmature

pub struct BlenderArmature { /* fields omitted */ }

All of the data about a Blender armature that we’ve exported from Blender. A BlenderArmature should have all of the data that you need to implement skeletal animation.

If you have other needs, such as a way to know the model space position of any bone at any time so that you can, say, render a baseball in on top of your hand bone.. Open an issue. (I plan to support this specific example in the future)

Implementations

impl BlenderArmature

pub fn matrix_to_dual_quat(bone: &Bone) -> Bone

Convert a matrix into a dual quaternion https://github.com/chinedufn/mat4-to-dual-quat/blob/master/src/mat4-to-dual-quat.js

pub fn dual_quat_to_matrix(bone: &Bone) -> Bone

https://github.com/chinedufn/dual-quat-to-mat4/blob/master/src/dual-quat-to-mat4.js

impl BlenderArmature

pub fn change_coordinate_system(&mut self, system: CoordinateSystem)

Shift around the data in the armature to a new coordinate system.

For example, if the armature was previously Z up and we’re switching to Y up

• the new +Y axis would be the old +Z axis
• the new +Z axis would be the old -Y axis

impl BlenderArmature

pub fn interpolate_bones(
    &self,
    action_name: &str,
    joint_indices: JointIndicesRef<'_>,
    sample_desc: SampleDesc
) -> BTreeMap<u8, Bone>

Interpolate in between the keyframes of your BlenderArmature. This is useful for skeletal animation.

We return a map so that you can easily merge the the interpolating bones with other interpolations. This is useful when you are combining multiple bone groups.

Panics

We don’t currently interpolating matrix bones, so we panic if your bones aren’t dual quaternions.

Panics if you pass in previous actions that do not have the exact same joint indices as your current action.

TODO

• Return Result<HashMap<u8, Bone>, InterpolationError>
• error if clock time is negative

impl BlenderArmature

pub fn name(&self) -> &String

The name of the armature

pub fn set_name(&mut self, name: String)

Set the name of the armature.

Example

let mut armature = BlenderArmature::default();
armature.set_name("Some Name".to_string());

assert_eq!(armature.name(), "Some Name");

pub fn bone_groups(&self) -> &HashMap<String, Vec<u8>>

Blender bone groups

Maps bone group name to a vector of the bones indices that are in that bone group.

let armature = create_blender_armature();

let joint_indices = armature.bone_groups().get("My bone group").unwrap();

let sample_desc = SampleDesc {
    frame_offset: FrameOffset::new_with_elapsed_time_and_frames_per_second(
        Duration::from_secs(2),
        24,
    ),
    should_loop: false
};

let _bones = armature.interpolate_bones(
    "SomeAction",
    JointIndicesRef::Some(joint_indices),
    sample_desc
);

pub fn create_bone_group(&mut self, name: String, joint_indices: Vec<u8>)

Create a new bone group

pub fn joint_indices(&self) -> &HashMap<String, u8>

Get a bone’s index into the various Vec data structures that hold bone data.

Example

use blender_armature::BlenderArmature;
let mut armature = BlenderArmature::default();

armature.insert_joint_index("Spine".to_string(), 0);

assert_eq!(armature.joint_indices().len(), 1);

pub fn insert_joint_index(&mut self, joint_name: String, joint_idx: u8)

Set a bone’s index into the various Vec data structures that hold bone data.

Example

use blender_armature::BlenderArmature;
let mut armature = BlenderArmature::default();

armature.insert_joint_index("Spine".to_string(), 0);
armature.insert_joint_index("UpperArm".to_string(), 2);

assert_eq!(armature.joint_indices().len(), 2);

pub fn inverse_bind_poses(&self) -> &Vec<Bone>

Every bone’s inverse bind pose.

From Blender

When exporting from Blender these include the armature’s world space matrix.

So, effectively these are (armature_world_space_matrix * bone_bind_pose).inverse()

pub fn set_inverse_bind_poses(&mut self, poses: Vec<Bone>)

Set the inverse bind poses.

pub fn bone_space_actions(&self) -> &HashMap<String, Action>

All of the actions defined on the armature, keyed by action name.

FIXME: Rename to bone_local_space_actions

pub fn insert_bone_space_action(&mut self, name: String, action: Action)

Insert an action into the map of actions.

pub fn remove_bone_space_action<Q>(&mut self, name: &Q) -> Option<Action> where
    String: Borrow<Q>,
    Q: Hash + Eq, 

Remove an action from the map.

pub fn bone_child_to_parent(&self) -> &HashMap<u8, u8>

A map of a bone chil to its parent

If a bone is not stored in this map then it does not have a parent.

pub fn insert_child_to_parent(&mut self, child: u8, parent: u8)

Example

let mut armature = BlenderArmature::default();

let child_idx = 4;
let parent_idx = 2;

armature.insert_joint_index("UpperArm".to_string(), parent_idx);
armature.insert_joint_index("Lower Arm".to_string(), child_idx);

armature.insert_child_to_parent(child_idx, parent_idx);

impl BlenderArmature

pub fn transpose_actions(&mut self)

Tranpose all of the bone matrices in our armature’s action keyframes. Blender uses row major matrices, but OpenGL uses column major matrices so you’ll usually want to transpose your matrices before using them.

impl BlenderArmature

pub fn matrices_to_dual_quats(&mut self)

Convert your action matrices into dual quaternions so that you can implement dual quaternion linear blending.

impl BlenderArmature

pub fn apply_inverse_bind_poses(&mut self)

Iterate over all of the action bones and apply and multiply in the inverse bind pose.

TODO: another function to apply bind shape matrix? Most armatures seem to export an identity bind shape matrix but that might not be the same for every armature.

TODO: Do not mutate the matrices and instead just return the new values and let the caller handle caching them? Would mean less moving parts in our data structures and you always know exactly what you are getting. Right now you have no way actions of knowing whether or not actions have their bind poses pre-multiplied in.

Trait Implementations

impl Clone for BlenderArmature

fn clone(&self) -> BlenderArmature

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BlenderArmature

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

Formats the value using the given formatter.

impl Default for BlenderArmature

fn default() -> BlenderArmature

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for BlenderArmature

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl PartialEq<BlenderArmature> for BlenderArmature

fn eq(&self, other: &BlenderArmature) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &BlenderArmature) -> bool

This method tests for !=.

impl Serialize for BlenderArmature

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for BlenderArmature