use crate::HumanBone;
use crate::diagnostic::{Diagnostic, LoadOptions, ValidationMode};
use glam::{Mat4, Quat, Vec3, Vec4};
use std::collections::{HashMap, HashSet, VecDeque};
use std::path::{Path, PathBuf};
use vrm_spec::vrmc_vrm_1_0::{ExpressionPresetName, HumanBoneName};
use vrm_spec::vrmc_vrm_animation_1_0::{VRMC_VRM_ANIMATION, VRMCVrmAnimationSchema};
const SUPPORTED_VRMA_EXTENSIONS: &[&str] = &[VRMC_VRM_ANIMATION];
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Interpolation {
#[default]
Linear,
Step,
CubicSpline,
}
impl From<gltf::animation::Interpolation> for Interpolation {
fn from(value: gltf::animation::Interpolation) -> Self {
match value {
gltf::animation::Interpolation::Linear => Self::Linear,
gltf::animation::Interpolation::Step => Self::Step,
gltf::animation::Interpolation::CubicSpline => Self::CubicSpline,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Keyframe<T> {
time: f32,
value: T,
in_tangent: Option<T>,
out_tangent: Option<T>,
}
impl<T: Copy> Keyframe<T> {
pub const fn new(time: f32, value: T) -> Self {
Self {
time,
value,
in_tangent: None,
out_tangent: None,
}
}
pub const fn cubic(time: f32, value: T, in_tangent: T, out_tangent: T) -> Self {
Self {
time,
value,
in_tangent: Some(in_tangent),
out_tangent: Some(out_tangent),
}
}
pub const fn time(&self) -> f32 {
self.time
}
pub const fn value(&self) -> T {
self.value
}
pub const fn in_tangent(&self) -> Option<T> {
self.in_tangent
}
pub const fn out_tangent(&self) -> Option<T> {
self.out_tangent
}
}
pub trait TrackValue: Copy {
fn linear(self, other: Self, amount: f32) -> Self;
fn cubic(
start: Self,
start_tangent: Self,
end: Self,
end_tangent: Self,
amount: f32,
duration: f32,
) -> Self;
fn is_finite(self) -> bool;
fn is_valid_value(self) -> bool {
self.is_finite()
}
fn normalized(self) -> Self {
self
}
}
impl TrackValue for f32 {
fn linear(self, other: Self, amount: f32) -> Self {
self + (other - self) * amount
}
fn cubic(
start: Self,
start_tangent: Self,
end: Self,
end_tangent: Self,
amount: f32,
duration: f32,
) -> Self {
hermite(start, start_tangent, end, end_tangent, amount, duration)
}
fn is_finite(self) -> bool {
f32::is_finite(self)
}
}
impl TrackValue for Vec3 {
fn linear(self, other: Self, amount: f32) -> Self {
self.lerp(other, amount)
}
fn cubic(
start: Self,
start_tangent: Self,
end: Self,
end_tangent: Self,
amount: f32,
duration: f32,
) -> Self {
let t2 = amount * amount;
let t3 = t2 * amount;
let h00 = 2.0 * t3 - 3.0 * t2 + 1.0;
let h10 = t3 - 2.0 * t2 + amount;
let h01 = -2.0 * t3 + 3.0 * t2;
let h11 = t3 - t2;
start * h00 + start_tangent * (duration * h10) + end * h01 + end_tangent * (duration * h11)
}
fn is_finite(self) -> bool {
Vec3::is_finite(self)
}
}
impl TrackValue for Quat {
fn linear(self, other: Self, amount: f32) -> Self {
self.normalize().slerp(other.normalize(), amount)
}
fn cubic(
start: Self,
start_tangent: Self,
end: Self,
end_tangent: Self,
amount: f32,
duration: f32,
) -> Self {
let start = Vec4::from_array(start.to_array());
let start_tangent = Vec4::from_array(start_tangent.to_array());
let end = Vec4::from_array(end.to_array());
let end_tangent = Vec4::from_array(end_tangent.to_array());
let t2 = amount * amount;
let t3 = t2 * amount;
let h00 = 2.0 * t3 - 3.0 * t2 + 1.0;
let h10 = t3 - 2.0 * t2 + amount;
let h01 = -2.0 * t3 + 3.0 * t2;
let h11 = t3 - t2;
let value = start * h00
+ start_tangent * (duration * h10)
+ end * h01
+ end_tangent * (duration * h11);
let value = Quat::from_array(value.to_array());
normalize_quaternion(value).unwrap_or_else(|| {
let endpoint = if amount <= 0.5 {
Quat::from_array(start.to_array())
} else {
Quat::from_array(end.to_array())
};
normalize_quaternion(endpoint).unwrap_or(Quat::IDENTITY)
})
}
fn is_finite(self) -> bool {
Quat::is_finite(self)
}
fn is_valid_value(self) -> bool {
self.is_finite() && self.length_squared() > f32::EPSILON
}
fn normalized(self) -> Self {
normalize_quaternion(self).unwrap_or(Quat::IDENTITY)
}
}
fn normalize_quaternion(value: Quat) -> Option<Quat> {
let length_squared = value.length_squared();
if value.is_finite() && length_squared > f32::EPSILON {
Some(value / length_squared.sqrt())
} else {
None
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct Track<T> {
interpolation: Interpolation,
keyframes: Vec<Keyframe<T>>,
}
impl<T> Track<T> {
pub fn new(interpolation: Interpolation, keyframes: Vec<Keyframe<T>>) -> Self {
Self {
interpolation,
keyframes,
}
}
pub const fn interpolation(&self) -> Interpolation {
self.interpolation
}
pub fn keyframes(&self) -> &[Keyframe<T>] {
&self.keyframes
}
pub fn len(&self) -> usize {
self.keyframes.len()
}
pub fn is_empty(&self) -> bool {
self.keyframes.is_empty()
}
}
impl<T: TrackValue> Track<T> {
pub fn sample(&self, time: f32) -> Option<T> {
let (left, right, amount) = track_segment(&self.keyframes, time)?;
let start = self.keyframes[left];
if left == right {
return Some(start.value.normalized());
}
let end = self.keyframes[right];
Some(match self.interpolation {
Interpolation::Step => start.value.normalized(),
Interpolation::Linear => start.value.linear(end.value, amount),
Interpolation::CubicSpline => T::cubic(
start.value,
start.out_tangent?,
end.value,
end.in_tangent?,
amount,
end.time - start.time,
),
})
}
fn validate(&self, label: &str, duration: f32) -> Result<(), String> {
if self.keyframes.is_empty() {
return Err(format!("{label} must contain at least one keyframe"));
}
if self.keyframes.iter().any(|keyframe| {
!keyframe.time.is_finite() || keyframe.time < 0.0 || keyframe.time > duration
}) {
return Err(format!("{label} contains a time outside the clip duration"));
}
if self
.keyframes
.windows(2)
.any(|pair| pair[0].time >= pair[1].time)
{
return Err(format!(
"{label} keyframe times must be strictly increasing"
));
}
if self
.keyframes
.iter()
.any(|keyframe| !keyframe.value.is_valid_value())
{
return Err(format!("{label} contains an invalid value"));
}
if self.interpolation == Interpolation::CubicSpline {
if self.keyframes.len() < 2 {
return Err(format!(
"{label} CUBICSPLINE requires at least two keyframes"
));
}
if self.keyframes.iter().any(|keyframe| {
keyframe.in_tangent.is_none_or(|value| !value.is_finite())
|| keyframe.out_tangent.is_none_or(|value| !value.is_finite())
}) {
return Err(format!("{label} contains an invalid CUBICSPLINE tangent"));
}
}
Ok(())
}
}
fn hermite(
start: f32,
start_tangent: f32,
end: f32,
end_tangent: f32,
amount: f32,
duration: f32,
) -> f32 {
let t2 = amount * amount;
let t3 = t2 * amount;
let h00 = 2.0 * t3 - 3.0 * t2 + 1.0;
let h10 = t3 - 2.0 * t2 + amount;
let h01 = -2.0 * t3 + 3.0 * t2;
let h11 = t3 - t2;
start * h00 + start_tangent * duration * h10 + end * h01 + end_tangent * duration * h11
}
fn track_segment<T>(keyframes: &[Keyframe<T>], time: f32) -> Option<(usize, usize, f32)> {
if !time.is_finite() {
return None;
}
let first = keyframes.first()?;
let last_index = keyframes.len() - 1;
if time <= first.time {
return Some((0, 0, 0.0));
}
if time >= keyframes[last_index].time {
return Some((last_index, last_index, 0.0));
}
let right = keyframes.partition_point(|keyframe| keyframe.time < time);
if keyframes[right].time == time {
return Some((right, right, 0.0));
}
let left = right - 1;
let span = keyframes[right].time - keyframes[left].time;
Some((left, right, (time - keyframes[left].time) / span))
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct BoneTrack {
rotation: Option<Track<Quat>>,
translation: Option<Track<Vec3>>,
}
impl BoneTrack {
pub const fn new() -> Self {
Self {
rotation: None,
translation: None,
}
}
pub fn with_rotation(mut self, rotation: Track<Quat>) -> Self {
self.rotation = Some(rotation);
self
}
pub fn with_translation(mut self, translation: Track<Vec3>) -> Self {
self.translation = Some(translation);
self
}
pub fn rotation(&self) -> Option<&Track<Quat>> {
self.rotation.as_ref()
}
pub fn translation(&self) -> Option<&Track<Vec3>> {
self.translation.as_ref()
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct SourceBoneRestPose {
local_rotation: Quat,
world_rotation: Quat,
world_translation: Vec3,
}
impl SourceBoneRestPose {
pub const fn local_rotation(&self) -> Quat {
self.local_rotation
}
pub const fn world_rotation(&self) -> Quat {
self.world_rotation
}
pub const fn world_translation(&self) -> Vec3 {
self.world_translation
}
}
#[doc(alias = "VRMA")]
#[derive(Debug, Clone, Default)]
pub struct VrmAnimation {
duration: f32,
bone_tracks: HashMap<HumanBone, BoneTrack>,
expression_tracks: HashMap<String, Track<f32>>,
look_at_rotation_track: Option<Track<Quat>>,
source_rest_pose: HashMap<HumanBone, SourceBoneRestPose>,
look_at_offset_from_head_bone: Option<Vec3>,
}
#[derive(Debug, Clone)]
pub struct AnimationLoadOutcome {
pub animation: VrmAnimation,
pub diagnostics: Vec<Diagnostic>,
}
#[derive(Debug, thiserror::Error)]
pub enum AnimationLoadError {
#[error("failed to read `{path}`: {source}")]
Io {
path: PathBuf,
#[source]
source: std::io::Error,
},
#[error("glTF parse error: {0}")]
Gltf(#[from] gltf::Error),
#[error("VRMC_vrm_animation extension missing")]
MissingExtension,
#[error("invalid VRMC_vrm_animation extension: {0}")]
InvalidExtension(#[from] serde_json::Error),
#[error("invalid VRM animation: {0}")]
InvalidAnimation(String),
#[error("required extension `{0}` is not supported by the VRMA loader")]
UnsupportedRequiredExtension(String),
}
impl VrmAnimation {
pub fn new(duration: f32) -> Self {
Self {
duration,
bone_tracks: HashMap::new(),
expression_tracks: HashMap::new(),
look_at_rotation_track: None,
source_rest_pose: HashMap::new(),
look_at_offset_from_head_bone: None,
}
}
pub const fn duration(&self) -> f32 {
self.duration
}
pub fn with_bone_track(mut self, bone: HumanBone, track: BoneTrack) -> Self {
self.insert_bone_track(bone, track);
self
}
pub fn insert_bone_track(&mut self, bone: HumanBone, track: BoneTrack) -> Option<BoneTrack> {
self.bone_tracks.insert(bone, track)
}
pub fn with_expression_track(mut self, name: impl Into<String>, track: Track<f32>) -> Self {
self.insert_expression_track(name, track);
self
}
pub fn insert_expression_track(
&mut self,
name: impl Into<String>,
track: Track<f32>,
) -> Option<Track<f32>> {
self.expression_tracks.insert(name.into(), track)
}
pub fn with_look_at_rotation_track(mut self, track: Track<Quat>) -> Self {
self.look_at_rotation_track = Some(track);
self
}
pub fn set_look_at_rotation_track(&mut self, track: Track<Quat>) -> Option<Track<Quat>> {
self.look_at_rotation_track.replace(track)
}
pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, AnimationLoadError> {
Self::from_file(path)
}
pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, AnimationLoadError> {
Ok(Self::from_file_with_options(path, LoadOptions::default())?.animation)
}
pub fn from_bytes(bytes: &[u8]) -> Result<Self, AnimationLoadError> {
Ok(Self::from_bytes_with_options(bytes, LoadOptions::default())?.animation)
}
pub fn load_with_options<P: AsRef<Path>>(
path: P,
options: LoadOptions,
) -> Result<AnimationLoadOutcome, AnimationLoadError> {
Self::from_file_with_options(path, options)
}
pub fn from_file_with_options<P: AsRef<Path>>(
path: P,
options: LoadOptions,
) -> Result<AnimationLoadOutcome, AnimationLoadError> {
let path = path.as_ref();
let file = std::fs::File::open(path).map_err(|source| AnimationLoadError::Io {
path: path.to_path_buf(),
source,
})?;
let gltf = gltf::Gltf::from_reader_without_validation(std::io::BufReader::new(file))?;
validate_gltf_document(&gltf.document)?;
let base = path.parent();
let buffers = gltf::import_buffers(&gltf.document, base, gltf.blob)?;
load_document(&gltf.document, &buffers, options)
}
pub fn from_bytes_with_options(
bytes: &[u8],
options: LoadOptions,
) -> Result<AnimationLoadOutcome, AnimationLoadError> {
let gltf = gltf::Gltf::from_slice_without_validation(bytes)?;
validate_gltf_document(&gltf.document)?;
let buffers = gltf::import_buffers(&gltf.document, None, gltf.blob)?;
load_document(&gltf.document, &buffers, options)
}
pub fn bone_track(&self, bone: HumanBone) -> Option<&BoneTrack> {
self.bone_tracks.get(&bone)
}
pub fn bone_tracks(&self) -> impl Iterator<Item = (HumanBone, &BoneTrack)> {
self.bone_tracks.iter().map(|(&bone, track)| (bone, track))
}
pub fn expression_track(&self, name: &str) -> Option<&Track<f32>> {
self.expression_tracks.get(name)
}
pub fn expression_tracks(&self) -> impl Iterator<Item = (&str, &Track<f32>)> {
self.expression_tracks
.iter()
.map(|(name, track)| (name.as_str(), track))
}
pub fn look_at_rotation_track(&self) -> Option<&Track<Quat>> {
self.look_at_rotation_track.as_ref()
}
pub fn look_at_offset_from_head_bone(&self) -> Option<Vec3> {
self.look_at_offset_from_head_bone
}
pub fn source_bone_rest_pose(&self, bone: HumanBone) -> Option<SourceBoneRestPose> {
self.source_rest_pose.get(&bone).copied()
}
pub(crate) fn has_source_rest_pose(&self) -> bool {
!self.source_rest_pose.is_empty()
}
pub fn source_hips_height(&self) -> Option<f32> {
self.source_bone_rest_pose(HumanBone::Hips)
.map(|pose| pose.world_translation.y)
}
pub fn validate(&self) -> Result<(), String> {
if !self.duration.is_finite() || self.duration < 0.0 {
return Err("duration must be finite and non-negative".to_string());
}
for (bone, track) in &self.bone_tracks {
if track.rotation.is_none() && track.translation.is_none() {
return Err(format!(
"bone track {bone:?} must contain a rotation or translation channel"
));
}
if let Some(rotation) = &track.rotation {
rotation.validate(&format!("bone rotation track {bone:?}"), self.duration)?;
}
if let Some(translation) = &track.translation {
if *bone != HumanBone::Hips {
return Err(format!(
"bone translation track {bone:?} is not allowed; only Hips may translate"
));
}
translation.validate(&format!("bone translation track {bone:?}"), self.duration)?;
}
}
for (name, track) in &self.expression_tracks {
if name.is_empty() {
return Err("expression track names must not be empty".to_string());
}
track.validate(&format!("expression track `{name}`"), self.duration)?;
if track
.keyframes
.iter()
.any(|keyframe| !(0.0..=1.0).contains(&keyframe.value))
{
return Err(format!(
"expression track `{name}` contains a weight outside 0..=1"
));
}
}
if let Some(track) = &self.look_at_rotation_track {
track.validate("LookAt rotation track", self.duration)?;
}
if self.source_rest_pose.values().any(|pose| {
!pose.local_rotation.is_finite()
|| !pose.world_rotation.is_finite()
|| !pose.world_translation.is_finite()
}) {
return Err("source rest pose contains a non-finite transform".to_string());
}
if self
.look_at_offset_from_head_bone
.is_some_and(|offset| !offset.is_finite())
{
return Err("LookAt offset contains a non-finite value".to_string());
}
Ok(())
}
pub fn sample_look_at_rotation(&self, time: f32) -> Option<Quat> {
self.look_at_rotation_track
.as_ref()?
.sample(time)
.map(Quat::normalize)
}
pub fn sample_programmatic_bone_rotation_delta(
&self,
bone: HumanBone,
time: f32,
) -> Option<Quat> {
if self.source_rest_pose.contains_key(&bone) {
return None;
}
self.bone_track(bone)?
.rotation()?
.sample(time)
.map(Quat::normalize)
}
pub fn sample_source_bone_rotation(&self, bone: HumanBone, time: f32) -> Option<Quat> {
self.source_rest_pose.get(&bone)?;
self.bone_track(bone)?
.rotation()?
.sample(time)
.map(Quat::normalize)
}
pub fn sample_normalized_source_bone_rotation(
&self,
bone: HumanBone,
time: f32,
) -> Option<Quat> {
let rotation = self.sample_source_bone_rotation(bone, time)?;
let rest = self.source_bone_rest_pose(bone)?;
Some(
(rest.world_rotation
* rest.local_rotation.inverse()
* rotation
* rest.world_rotation.inverse())
.normalize(),
)
}
pub fn sample_retargeted_source_bone_rotation(
&self,
bone: HumanBone,
time: f32,
target_world_rest_rotation: Quat,
) -> Option<Quat> {
let normalized = self.sample_normalized_source_bone_rotation(bone, time)?;
Some(
(target_world_rest_rotation.inverse() * normalized * target_world_rest_rotation)
.normalize(),
)
}
pub fn sample_bone_translation_delta(&self, bone: HumanBone, time: f32) -> Option<Vec3> {
self.bone_track(bone)?.translation()?.sample(time)
}
pub fn sample_expression_weight(&self, name: &str, time: f32) -> f32 {
let Some(track) = self.expression_tracks.get(name) else {
return 0.0;
};
track.sample(time).unwrap_or(0.0).clamp(0.0, 1.0)
}
}
fn load_document(
document: &gltf::Document,
buffers: &[gltf::buffer::Data],
options: LoadOptions,
) -> Result<AnimationLoadOutcome, AnimationLoadError> {
for required in document.extensions_required() {
if !SUPPORTED_VRMA_EXTENSIONS.contains(&required) {
return Err(AnimationLoadError::UnsupportedRequiredExtension(
required.to_string(),
));
}
}
let extension_value = document
.extension_value(VRMC_VRM_ANIMATION)
.ok_or(AnimationLoadError::MissingExtension)?;
let schema: VRMCVrmAnimationSchema = serde_json::from_value(extension_value.clone())?;
let mut diagnostics = Vec::new();
if options.validation == ValidationMode::Permissive {
let required_extensions = document.extensions_required().collect::<HashSet<_>>();
for extension in document.extensions_used() {
if !SUPPORTED_VRMA_EXTENSIONS.contains(&extension)
&& !required_extensions.contains(extension)
{
diagnostics.push(Diagnostic::warning(
"VRMA_UNSUPPORTED_OPTIONAL_EXTENSION",
"/extensionsUsed",
format!(
"optional extension `{extension}` is not interpreted by the VRMA loader"
),
));
}
}
}
let mappings = validate_schema(document, &schema, options.validation, &mut diagnostics)?;
let mut animations = document.animations();
let animation = animations.next().ok_or_else(|| {
AnimationLoadError::InvalidAnimation(
"VRMA document must contain at least one glTF animation".to_string(),
)
})?;
if animations.next().is_some() {
diagnostics.push(Diagnostic::warning(
"VRMA_ADDITIONAL_ANIMATIONS_IGNORED",
"/animations/1",
"only the first glTF animation is loaded",
));
}
let (source_rest_pose, local_translations) =
source_rest_pose(document, &mappings.bone_by_node)?;
let mut bone_tracks = HashMap::new();
let mut expression_tracks = HashMap::new();
let mut look_at_rotation_track = None;
let mut duration = 0.0_f32;
for channel in animation.channels() {
validate_channel_accessors(&channel)?;
let node_index = channel.target().node().index();
let property = channel.target().property();
let interpolation = Interpolation::from(channel.sampler().interpolation());
let reader =
channel.reader(|buffer| buffers.get(buffer.index()).map(|data| data.0.as_slice()));
let times = reader
.read_inputs()
.ok_or_else(|| invalid_channel(channel.index(), "input accessor cannot be read"))?
.collect::<Vec<_>>();
validate_input_times(channel.index(), ×)?;
duration = duration.max(times.last().copied().unwrap_or(0.0));
let outputs = reader
.read_outputs()
.ok_or_else(|| invalid_channel(channel.index(), "output accessor cannot be read"))?;
if let Some(&bone) = mappings.bone_by_node.get(&node_index) {
match (property, outputs) {
(
gltf::animation::Property::Rotation,
gltf::animation::util::ReadOutputs::Rotations(values),
) => {
let values = values.into_f32().map(Quat::from_array).collect::<Vec<_>>();
let track = make_track(×, values, interpolation, channel.index())?;
let slot = &mut bone_tracks
.entry(bone)
.or_insert_with(BoneTrack::new)
.rotation;
if slot.replace(track).is_some() {
return Err(invalid_channel(
channel.index(),
"duplicate humanoid rotation channel",
));
}
}
(
gltf::animation::Property::Translation,
gltf::animation::util::ReadOutputs::Translations(values),
) => {
if bone != HumanBone::Hips {
handle_violation(
options.validation,
&mut diagnostics,
"VRMA_NON_HIPS_TRANSLATION",
format!("/animations/0/channels/{}", channel.index()),
format!("translation is not allowed for humanoid bone {bone:?}"),
)?;
continue;
}
let values = values.map(Vec3::from_array).collect::<Vec<_>>();
let mut track = make_track(×, values, interpolation, channel.index())?;
let rest_translation = local_translations[node_index];
for keyframe in &mut track.keyframes {
keyframe.value -= rest_translation;
}
let slot = &mut bone_tracks
.entry(bone)
.or_insert_with(BoneTrack::new)
.translation;
if slot.replace(track).is_some() {
return Err(invalid_channel(
channel.index(),
"duplicate Hips translation channel",
));
}
}
(gltf::animation::Property::Scale, _) => {
handle_violation(
options.validation,
&mut diagnostics,
"VRMA_HUMANOID_SCALE_CHANNEL",
format!("/animations/0/channels/{}", channel.index()),
format!("scale animation is not allowed for humanoid bone {bone:?}"),
)?;
}
_ => {}
}
continue;
}
if let Some(name) = mappings.expression_by_node.get(&node_index) {
if let (
gltf::animation::Property::Translation,
gltf::animation::util::ReadOutputs::Translations(values),
) = (property, outputs)
{
let vector_track = make_track(
×,
values.map(Vec3::from_array).collect(),
interpolation,
channel.index(),
)?;
let scalar_track = Track::new(
vector_track.interpolation,
vector_track
.keyframes
.into_iter()
.map(|keyframe| Keyframe {
time: keyframe.time,
value: keyframe.value.x.clamp(0.0, 1.0),
in_tangent: keyframe.in_tangent.map(|value| value.x),
out_tangent: keyframe.out_tangent.map(|value| value.x),
})
.collect(),
);
if expression_tracks
.insert(name.clone(), scalar_track)
.is_some()
{
return Err(invalid_channel(
channel.index(),
"duplicate expression translation channel",
));
}
}
continue;
}
if mappings.look_at_node == Some(node_index)
&& property == gltf::animation::Property::Rotation
&& let gltf::animation::util::ReadOutputs::Rotations(values) = outputs
{
let track = make_track(
×,
values.into_f32().map(Quat::from_array).collect(),
interpolation,
channel.index(),
)?;
if look_at_rotation_track.replace(track).is_some() {
return Err(invalid_channel(
channel.index(),
"duplicate LookAt rotation channel",
));
}
}
}
let result = VrmAnimation {
duration,
bone_tracks,
expression_tracks,
look_at_rotation_track,
source_rest_pose,
look_at_offset_from_head_bone: mappings.look_at_offset,
};
result
.validate()
.map_err(AnimationLoadError::InvalidAnimation)?;
Ok(AnimationLoadOutcome {
animation: result,
diagnostics,
})
}
fn validate_channel_accessors(
channel: &gltf::animation::Channel<'_>,
) -> Result<(), AnimationLoadError> {
use gltf::accessor::{DataType, Dimensions};
use gltf::animation::Property;
let input = channel.sampler().input();
if input.data_type() != DataType::F32
|| input.dimensions() != Dimensions::Scalar
|| input.normalized()
|| input.min().is_none()
|| input.max().is_none()
{
return Err(invalid_channel(
channel.index(),
"input accessor must be a non-normalized FLOAT SCALAR with min and max",
));
}
let output = channel.sampler().output();
let property = channel.target().property();
let float_vector = |dimensions| {
output.data_type() == DataType::F32
&& output.dimensions() == dimensions
&& !output.normalized()
};
let normalized_scalar_or_vector = |dimensions| {
output.dimensions() == dimensions
&& match output.data_type() {
DataType::F32 => !output.normalized(),
DataType::I8 | DataType::U8 | DataType::I16 | DataType::U16 => output.normalized(),
DataType::U32 => false,
}
};
let valid_output = match property {
Property::Translation | Property::Scale => float_vector(Dimensions::Vec3),
Property::Rotation => normalized_scalar_or_vector(Dimensions::Vec4),
Property::MorphTargetWeights => normalized_scalar_or_vector(Dimensions::Scalar),
};
if !valid_output {
let property_name = match property {
Property::Translation => "translation",
Property::Rotation => "rotation",
Property::Scale => "scale",
Property::MorphTargetWeights => "weights",
};
return Err(invalid_channel(
channel.index(),
format!("output accessor is not valid for the {property_name} animation target"),
));
}
if property != Property::MorphTargetWeights {
let interpolation_multiplier =
if channel.sampler().interpolation() == gltf::animation::Interpolation::CubicSpline {
3
} else {
1
};
let expected = input
.count()
.checked_mul(interpolation_multiplier)
.ok_or_else(|| invalid_channel(channel.index(), "animation sample count overflows"))?;
if output.count() != expected {
return Err(invalid_channel(
channel.index(),
format!(
"output accessor count {} does not match the expected {expected}",
output.count()
),
));
}
}
Ok(())
}
struct AnimationMappings {
bone_by_node: HashMap<usize, HumanBone>,
expression_by_node: HashMap<usize, String>,
look_at_node: Option<usize>,
look_at_offset: Option<Vec3>,
}
fn validate_schema(
document: &gltf::Document,
schema: &VRMCVrmAnimationSchema,
validation: ValidationMode,
diagnostics: &mut Vec<Diagnostic>,
) -> Result<AnimationMappings, AnimationLoadError> {
if schema.spec_version != "1.0" {
return Err(AnimationLoadError::InvalidAnimation(format!(
"VRMC_vrm_animation specVersion must be exactly `1.0`, found `{}`",
schema.spec_version
)));
}
let node_count = document.nodes().len();
let mut claimed_nodes = HashSet::new();
let mut bone_by_node = HashMap::new();
if let Some(humanoid) = &schema.humanoid {
const REQUIRED: [HumanBoneName; 15] = [
HumanBoneName::Hips,
HumanBoneName::Spine,
HumanBoneName::Head,
HumanBoneName::LeftUpperLeg,
HumanBoneName::LeftLowerLeg,
HumanBoneName::LeftFoot,
HumanBoneName::RightUpperLeg,
HumanBoneName::RightLowerLeg,
HumanBoneName::RightFoot,
HumanBoneName::LeftUpperArm,
HumanBoneName::LeftLowerArm,
HumanBoneName::LeftHand,
HumanBoneName::RightUpperArm,
HumanBoneName::RightLowerArm,
HumanBoneName::RightHand,
];
for required in REQUIRED {
if humanoid
.human_bones
.0
.get(&required)
.and_then(Option::as_ref)
.and_then(|bone| bone.node.as_ref())
.is_none()
{
return Err(AnimationLoadError::InvalidAnimation(format!(
"required humanoid bone {required:?} is missing"
)));
}
}
for (name, bone) in &humanoid.human_bones.0 {
if matches!(name, HumanBoneName::LeftEye | HumanBoneName::RightEye) {
return Err(AnimationLoadError::InvalidAnimation(format!(
"{name:?} cannot be mapped by VRMC_vrm_animation"
)));
}
let node = bone
.as_ref()
.and_then(|bone| bone.node.as_ref())
.ok_or_else(|| {
AnimationLoadError::InvalidAnimation(format!(
"humanoid bone {name:?} must contain a node"
))
})?;
let index = node.value();
claim_node(&mut claimed_nodes, index, node_count, "humanoid bone")?;
bone_by_node.insert(index, HumanBone::from(*name));
}
validate_humanoid_rest_pose(document, &humanoid.human_bones, validation, diagnostics)?;
}
let mut expression_by_node = HashMap::new();
if let Some(expressions) = &schema.expressions {
if let Some(preset) = &expressions.preset {
for (name, expression) in &preset.0 {
if matches!(
name,
ExpressionPresetName::LookUp
| ExpressionPresetName::LookDown
| ExpressionPresetName::LookLeft
| ExpressionPresetName::LookRight
) {
return Err(AnimationLoadError::InvalidAnimation(format!(
"LookAt preset expression `{}` cannot be animated by an expression node",
expression_preset_name(*name)
)));
}
let node = expression.node.as_ref().ok_or_else(|| {
AnimationLoadError::InvalidAnimation(format!(
"preset expression `{}` has no node",
expression_preset_name(*name)
))
})?;
let index = node.value();
claim_node(&mut claimed_nodes, index, node_count, "expression")?;
expression_by_node.insert(index, expression_preset_name(*name).to_string());
}
}
if let Some(custom) = &expressions.custom {
for (name, expression) in custom {
if name.is_empty() || is_preset_expression_name(name) {
return Err(AnimationLoadError::InvalidAnimation(format!(
"custom expression name `{name}` is invalid"
)));
}
let node = expression.node.as_ref().ok_or_else(|| {
AnimationLoadError::InvalidAnimation(format!(
"custom expression `{name}` has no node"
))
})?;
let index = node.value();
claim_node(&mut claimed_nodes, index, node_count, "expression")?;
expression_by_node.insert(index, name.clone());
}
}
}
let (look_at_node, look_at_offset) = if let Some(look_at) = &schema.look_at {
let node = look_at.node.as_ref().ok_or_else(|| {
AnimationLoadError::InvalidAnimation("LookAt mapping has no node".to_string())
})?;
let index = node.value();
claim_node(&mut claimed_nodes, index, node_count, "LookAt")?;
let offset = look_at
.offset_from_head_bone
.map(|offset| Vec3::new(offset[0] as f32, offset[1] as f32, offset[2] as f32));
if offset.is_some_and(|offset| !offset.is_finite()) {
return Err(AnimationLoadError::InvalidAnimation(
"LookAt offsetFromHeadBone must contain finite values".to_string(),
));
}
(Some(index), offset)
} else {
(None, None)
};
Ok(AnimationMappings {
bone_by_node,
expression_by_node,
look_at_node,
look_at_offset,
})
}
fn validate_humanoid_rest_pose(
document: &gltf::Document,
bones: &vrm_spec::vrmc_vrm_animation_1_0::VRMCVrmAnimationHumanBones,
validation: ValidationMode,
diagnostics: &mut Vec<Diagnostic>,
) -> Result<(), AnimationLoadError> {
for node in document.nodes() {
let (_, _, scale) = node.transform().decomposed();
let max_scale = scale.iter().copied().fold(0.0_f32, f32::max);
let tolerance = max_scale * 2.0e-3;
let valid = scale.iter().all(|value| value.is_finite() && *value > 0.0)
&& (scale[0] - scale[1]).abs() <= tolerance
&& (scale[1] - scale[2]).abs() <= tolerance;
if !valid {
handle_violation(
validation,
diagnostics,
"VRMA_HUMANOID_SCALE_INVALID",
format!("/nodes/{}/scale", node.index()),
"every T-pose node scale must be positive and uniform".to_string(),
)?;
}
}
let mut parents = vec![None; document.nodes().len()];
for node in document.nodes() {
for child in node.children() {
parents[child.index()] = Some(node.index());
}
}
let mapped_bones = bones.0.iter().filter_map(|(name, entry)| {
entry.as_ref().and_then(|bone| {
bone.node
.as_ref()
.map(|node| (HumanBone::from(*name), node.value()))
})
});
for violation in crate::humanoid::hierarchy_violations(mapped_bones, &parents) {
let bone_name = violation.bone().spec_name();
handle_violation(
validation,
diagnostics,
"VRMA_HUMANOID_HIERARCHY_INVALID",
format!("/extensions/{VRMC_VRM_ANIMATION}/humanoid/humanBones/{bone_name}"),
violation.message(),
)?;
}
Ok(())
}
fn claim_node(
claimed: &mut HashSet<usize>,
index: usize,
node_count: usize,
role: &str,
) -> Result<(), AnimationLoadError> {
if index >= node_count {
return Err(AnimationLoadError::InvalidAnimation(format!(
"{role} references node {index}, but only {node_count} nodes exist"
)));
}
if !claimed.insert(index) {
return Err(AnimationLoadError::InvalidAnimation(format!(
"node {index} is assigned to more than one VRMA role"
)));
}
Ok(())
}
fn expression_preset_name(name: ExpressionPresetName) -> &'static str {
match name {
ExpressionPresetName::Aa => "aa",
ExpressionPresetName::Angry => "angry",
ExpressionPresetName::Blink => "blink",
ExpressionPresetName::BlinkLeft => "blinkLeft",
ExpressionPresetName::BlinkRight => "blinkRight",
ExpressionPresetName::Ee => "ee",
ExpressionPresetName::Happy => "happy",
ExpressionPresetName::Ih => "ih",
ExpressionPresetName::LookDown => "lookDown",
ExpressionPresetName::LookLeft => "lookLeft",
ExpressionPresetName::LookRight => "lookRight",
ExpressionPresetName::LookUp => "lookUp",
ExpressionPresetName::Neutral => "neutral",
ExpressionPresetName::Oh => "oh",
ExpressionPresetName::Ou => "ou",
ExpressionPresetName::Relaxed => "relaxed",
ExpressionPresetName::Sad => "sad",
ExpressionPresetName::Surprised => "surprised",
}
}
fn is_preset_expression_name(name: &str) -> bool {
[
"aa",
"angry",
"blink",
"blinkLeft",
"blinkRight",
"ee",
"happy",
"ih",
"lookDown",
"lookLeft",
"lookRight",
"lookUp",
"neutral",
"oh",
"ou",
"relaxed",
"sad",
"surprised",
]
.contains(&name)
}
fn make_track<T: TrackValue>(
times: &[f32],
values: Vec<T>,
interpolation: Interpolation,
channel: usize,
) -> Result<Track<T>, AnimationLoadError> {
let keyframes = if interpolation == Interpolation::CubicSpline {
if values.len() != times.len() * 3 {
return Err(invalid_channel(
channel,
"CUBICSPLINE output count must be three times the input count",
));
}
times
.iter()
.copied()
.zip(values.chunks_exact(3))
.map(|(time, values)| Keyframe::cubic(time, values[1], values[0], values[2]))
.collect()
} else {
if values.len() != times.len() {
return Err(invalid_channel(
channel,
"animation output count must equal the input count",
));
}
times
.iter()
.copied()
.zip(values)
.map(|(time, value)| Keyframe::new(time, value))
.collect()
};
Ok(Track::new(interpolation, keyframes))
}
fn validate_input_times(channel: usize, times: &[f32]) -> Result<(), AnimationLoadError> {
if times.is_empty() {
return Err(invalid_channel(channel, "input accessor is empty"));
}
if times.iter().any(|time| !time.is_finite() || *time < 0.0) {
return Err(invalid_channel(
channel,
"input times must be finite and non-negative",
));
}
if times.windows(2).any(|pair| pair[0] >= pair[1]) {
return Err(invalid_channel(
channel,
"input times must be strictly increasing",
));
}
Ok(())
}
fn invalid_channel(channel: usize, message: impl Into<String>) -> AnimationLoadError {
AnimationLoadError::InvalidAnimation(format!("animation channel {channel}: {}", message.into()))
}
fn handle_violation(
mode: ValidationMode,
diagnostics: &mut Vec<Diagnostic>,
code: &'static str,
path: String,
message: String,
) -> Result<(), AnimationLoadError> {
match mode {
ValidationMode::Strict => Err(AnimationLoadError::InvalidAnimation(message)),
ValidationMode::Permissive => {
diagnostics.push(Diagnostic::warning(code, path, message));
Ok(())
}
}
}
fn source_rest_pose(
document: &gltf::Document,
bone_by_node: &HashMap<usize, HumanBone>,
) -> Result<(HashMap<HumanBone, SourceBoneRestPose>, Vec<Vec3>), AnimationLoadError> {
let nodes = document.nodes().collect::<Vec<_>>();
let mut parents = vec![None; nodes.len()];
let mut indegree = vec![0_usize; nodes.len()];
let mut children = vec![Vec::new(); nodes.len()];
let mut local_matrices = Vec::with_capacity(nodes.len());
let mut local_rotations = Vec::with_capacity(nodes.len());
let mut local_translations = Vec::with_capacity(nodes.len());
for node in &nodes {
let (translation, rotation, scale) = node.transform().decomposed();
let translation = Vec3::from_array(translation);
let rotation = Quat::from_array(rotation).normalize();
local_translations.push(translation);
local_rotations.push(rotation);
local_matrices.push(Mat4::from_scale_rotation_translation(
Vec3::from_array(scale),
rotation,
translation,
));
for child in node.children() {
parents[child.index()] = Some(node.index());
indegree[child.index()] += 1;
children[node.index()].push(child.index());
}
}
let mut queue = indegree
.iter()
.enumerate()
.filter_map(|(index, °ree)| (degree == 0).then_some(index))
.collect::<VecDeque<_>>();
let mut world_matrices = vec![Mat4::IDENTITY; nodes.len()];
let mut visited = 0;
while let Some(index) = queue.pop_front() {
world_matrices[index] = parents[index]
.map(|parent| world_matrices[parent] * local_matrices[index])
.unwrap_or(local_matrices[index]);
visited += 1;
for &child in &children[index] {
indegree[child] -= 1;
if indegree[child] == 0 {
queue.push_back(child);
}
}
}
if visited != nodes.len() {
return Err(AnimationLoadError::InvalidAnimation(
"node graph contains a cycle".to_string(),
));
}
let rest_pose = bone_by_node
.iter()
.map(|(&node, &bone)| {
let (_, world_rotation, world_translation) =
world_matrices[node].to_scale_rotation_translation();
(
bone,
SourceBoneRestPose {
local_rotation: local_rotations[node],
world_rotation: world_rotation.normalize(),
world_translation,
},
)
})
.collect();
Ok((rest_pose, local_translations))
}
fn validate_gltf_document(document: &gltf::Document) -> Result<(), AnimationLoadError> {
validate_raw_node_graph(document.as_json())?;
crate::extension_declarations::validate(document.as_json())
.map_err(AnimationLoadError::InvalidAnimation)?;
use gltf::json::validation::Validate;
let root = document.as_json();
let mut errors = Vec::new();
root.validate(root, gltf::json::Path::new, &mut |path, error| {
if error != gltf::json::validation::Error::Unsupported {
errors.push((path(), error));
}
});
if errors.is_empty() {
Ok(())
} else {
Err(AnimationLoadError::Gltf(gltf::Error::Validation(errors)))
}
}
fn validate_raw_node_graph(root: &gltf::json::Root) -> Result<(), AnimationLoadError> {
let mut indegree = vec![0_usize; root.nodes.len()];
let mut children = vec![Vec::new(); root.nodes.len()];
for (parent, node) in root.nodes.iter().enumerate() {
for child in node.children.as_deref().unwrap_or_default() {
let child = child.value();
if child >= root.nodes.len() {
return Err(AnimationLoadError::InvalidAnimation(format!(
"node {parent} references out-of-range child {child}"
)));
}
indegree[child] += 1;
if indegree[child] > 1 {
return Err(AnimationLoadError::InvalidAnimation(format!(
"node {child} has multiple parents"
)));
}
children[parent].push(child);
}
}
let mut queue = indegree
.iter()
.enumerate()
.filter_map(|(index, °ree)| (degree == 0).then_some(index))
.collect::<VecDeque<_>>();
let mut visited = 0;
while let Some(node) = queue.pop_front() {
visited += 1;
for &child in &children[node] {
indegree[child] -= 1;
if indegree[child] == 0 {
queue.push_back(child);
}
}
}
if visited != root.nodes.len() {
return Err(AnimationLoadError::InvalidAnimation(
"node graph contains a cycle".to_string(),
));
}
Ok(())
}