Skip to main content

vrm_runtime/
look_at.rs

1use glam::{Quat, Vec3};
2use vrm_spec::vrmc_vrm_1_0 as vrm_schema;
3
4/// How the eyes are driven once the gaze direction is known.
5#[derive(Debug, Clone, Copy, PartialEq, Eq)]
6pub enum LookAtType {
7    /// Rotate the eye bones directly.
8    Bone,
9    /// Drive the lookUp/lookDown/lookLeft/lookRight expression weights.
10    Expression,
11}
12
13/// Maps an input angle (degrees) to an output weight/rotation via a linear
14/// range: `clamp(|deg|, 0, input_max) / input_max * output_scale`.
15#[derive(Debug, Clone)]
16pub struct LookAtRangeMap {
17    /// Input yaw or pitch angle at which the output reaches its maximum.
18    pub input_max_value: f32,
19    /// Maximum bone angle in degrees or expression weight, depending on the mode.
20    pub output_scale: f32,
21}
22
23impl LookAtRangeMap {
24    /// Creates a range map from its input angle and output maximum.
25    pub const fn new(input_max_value: f32, output_scale: f32) -> Self {
26        Self {
27            input_max_value,
28            output_scale,
29        }
30    }
31
32    /// Maps an input angle to the configured output range.
33    pub fn map_value(&self, deg: f32) -> f32 {
34        let max_in = self.input_max_value.max(0.001);
35        let clamped = deg.abs().min(max_in);
36        (clamped / max_in) * self.output_scale
37    }
38
39    fn validate(&self, label: &str) -> Result<(), String> {
40        if !self.input_max_value.is_finite() || !(0.0..=180.0).contains(&self.input_max_value) {
41            return Err(format!(
42                "{label}.inputMaxValue must be finite and within 0..=180"
43            ));
44        }
45        if !self.output_scale.is_finite() {
46            return Err(format!("{label}.outputScale must be finite"));
47        }
48        Ok(())
49    }
50}
51
52impl Default for LookAtRangeMap {
53    fn default() -> Self {
54        Self {
55            input_max_value: 90.0,
56            output_scale: 10.0,
57        }
58    }
59}
60
61/// The eye-gaze configuration of an avatar: pivot offset from the head bone,
62/// range maps per direction, and the mode (bone vs expression).
63#[derive(Debug, Clone)]
64pub struct LookAt {
65    /// Whether gaze drives eye bones or expression presets.
66    pub look_at_type: LookAtType,
67    /// Gaze origin relative to the head bone.
68    pub offset_from_head_bone: Vec3,
69    /// Range used when either eye turns toward the nose.
70    pub range_map_horizontal_inner: LookAtRangeMap,
71    /// Range used when either eye turns away from the nose.
72    pub range_map_horizontal_outer: LookAtRangeMap,
73    /// Range used for downward gaze.
74    pub range_map_vertical_down: LookAtRangeMap,
75    /// Range used for upward gaze.
76    pub range_map_vertical_up: LookAtRangeMap,
77}
78
79impl LookAt {
80    /// Creates a LookAt configuration with the VRM fallback offset and ranges.
81    pub fn new(look_at_type: LookAtType) -> Self {
82        Self {
83            look_at_type,
84            offset_from_head_bone: Vec3::new(0.0, 0.06, 0.0),
85            range_map_horizontal_inner: LookAtRangeMap::default(),
86            range_map_horizontal_outer: LookAtRangeMap::default(),
87            range_map_vertical_down: LookAtRangeMap::default(),
88            range_map_vertical_up: LookAtRangeMap::default(),
89        }
90    }
91
92    pub(crate) fn load_look_at(schema: &vrm_schema::LookAt) -> Self {
93        let look_at_type = match schema.look_at_type {
94            Some(vrm_schema::LookAtType::Expression) => LookAtType::Expression,
95            _ => LookAtType::Bone,
96        };
97
98        let offset_from_head_bone = schema
99            .offset_from_head_bone
100            .as_ref()
101            .and_then(|v| {
102                if v.len() >= 3 {
103                    Some(Vec3::new(v[0] as f32, v[1] as f32, v[2] as f32))
104                } else {
105                    None
106                }
107            })
108            .unwrap_or(Vec3::new(0.0, 0.06, 0.0));
109
110        let map_range = |range: Option<&vrm_schema::LookAtRangeMap>| {
111            range
112                .map(|r| LookAtRangeMap {
113                    input_max_value: r.input_max_value.map(|v| v as f32).unwrap_or(90.0),
114                    output_scale: r.output_scale.map(|v| v as f32).unwrap_or(10.0),
115                })
116                .unwrap_or_default()
117        };
118
119        Self {
120            look_at_type,
121            offset_from_head_bone,
122            range_map_horizontal_inner: map_range(schema.range_map_horizontal_inner.as_ref()),
123            range_map_horizontal_outer: map_range(schema.range_map_horizontal_outer.as_ref()),
124            range_map_vertical_down: map_range(schema.range_map_vertical_down.as_ref()),
125            range_map_vertical_up: map_range(schema.range_map_vertical_up.as_ref()),
126        }
127    }
128
129    pub(crate) fn validate_programmatic(&self) -> Result<(), String> {
130        if !self.offset_from_head_bone.is_finite() {
131            return Err("LookAt offsetFromHeadBone must be finite".to_string());
132        }
133        for (label, range) in [
134            (
135                "LookAt.rangeMapHorizontalInner",
136                &self.range_map_horizontal_inner,
137            ),
138            (
139                "LookAt.rangeMapHorizontalOuter",
140                &self.range_map_horizontal_outer,
141            ),
142            ("LookAt.rangeMapVerticalDown", &self.range_map_vertical_down),
143            ("LookAt.rangeMapVerticalUp", &self.range_map_vertical_up),
144        ] {
145            range.validate(label)?;
146        }
147        Ok(())
148    }
149
150    /// Converts yaw and pitch into left- and right-eye local rotations.
151    ///
152    /// The return order is `(left_eye, right_eye)`.
153    pub fn apply_bone(&self, yaw_deg: f32, pitch_deg: f32) -> (Quat, Quat) {
154        let left_yaw = if yaw_deg > 0.0 {
155            self.range_map_horizontal_outer.map_value(yaw_deg)
156        } else {
157            -self.range_map_horizontal_inner.map_value(yaw_deg)
158        };
159
160        let right_yaw = if yaw_deg > 0.0 {
161            self.range_map_horizontal_inner.map_value(yaw_deg)
162        } else {
163            -self.range_map_horizontal_outer.map_value(yaw_deg)
164        };
165
166        let pitch = if pitch_deg > 0.0 {
167            self.range_map_vertical_down.map_value(pitch_deg)
168        } else {
169            -self.range_map_vertical_up.map_value(pitch_deg)
170        };
171
172        let left_rot = Quat::from_euler(
173            glam::EulerRot::YXZ,
174            left_yaw.to_radians(),
175            pitch.to_radians(),
176            0.0,
177        );
178        let right_rot = Quat::from_euler(
179            glam::EulerRot::YXZ,
180            right_yaw.to_radians(),
181            pitch.to_radians(),
182            0.0,
183        );
184
185        (left_rot, right_rot)
186    }
187
188    /// Converts yaw and pitch into directional expression weights.
189    ///
190    /// The return order is `(look_left, look_right, look_down, look_up)`.
191    pub fn apply_expression(&self, yaw_deg: f32, pitch_deg: f32) -> (f32, f32, f32, f32) {
192        let (look_left, look_right) = if yaw_deg > 0.0 {
193            (
194                self.range_map_horizontal_outer.map_value(yaw_deg).min(1.0),
195                0.0,
196            )
197        } else {
198            (
199                0.0,
200                self.range_map_horizontal_outer.map_value(yaw_deg).min(1.0),
201            )
202        };
203
204        let (look_down, look_up) = if pitch_deg > 0.0 {
205            (
206                self.range_map_vertical_down.map_value(pitch_deg).min(1.0),
207                0.0,
208            )
209        } else {
210            (
211                0.0,
212                self.range_map_vertical_up.map_value(pitch_deg).min(1.0),
213            )
214        };
215
216        (look_left, look_right, look_down, look_up)
217    }
218}
219
220impl Default for LookAt {
221    fn default() -> Self {
222        Self::new(LookAtType::Bone)
223    }
224}
225
226pub(crate) fn validate_schema(schema: &vrm_schema::LookAt) -> Result<(), String> {
227    if let Some(offset) = &schema.offset_from_head_bone {
228        if offset.len() != 3 {
229            return Err("LookAt.offsetFromHeadBone must contain exactly three values".to_string());
230        }
231        if offset.iter().any(|&value| !representable_f32(value)) {
232            return Err(
233                "LookAt.offsetFromHeadBone values must be finite and representable as f32"
234                    .to_string(),
235            );
236        }
237    }
238
239    for (label, range) in [
240        (
241            "LookAt.rangeMapHorizontalInner",
242            schema.range_map_horizontal_inner.as_ref(),
243        ),
244        (
245            "LookAt.rangeMapHorizontalOuter",
246            schema.range_map_horizontal_outer.as_ref(),
247        ),
248        (
249            "LookAt.rangeMapVerticalDown",
250            schema.range_map_vertical_down.as_ref(),
251        ),
252        (
253            "LookAt.rangeMapVerticalUp",
254            schema.range_map_vertical_up.as_ref(),
255        ),
256    ] {
257        let Some(range) = range else {
258            continue;
259        };
260        if range
261            .input_max_value
262            .is_some_and(|value| !representable_f32(value) || !(0.0..=180.0).contains(&value))
263        {
264            return Err(format!(
265                "{label}.inputMaxValue must be finite, representable as f32, and within 0..=180"
266            ));
267        }
268        if range
269            .output_scale
270            .is_some_and(|value| !representable_f32(value))
271        {
272            return Err(format!(
273                "{label}.outputScale must be finite and representable as f32"
274            ));
275        }
276    }
277    Ok(())
278}
279
280fn representable_f32(value: f64) -> bool {
281    value.is_finite() && (value as f32).is_finite()
282}
283
284/// Converts a direction vector (from the look-at pivot toward the target)
285/// into horizontal (yaw) and vertical (pitch) angles in degrees.
286pub fn calc_yaw_pitch(local_target: Vec3) -> (f32, f32) {
287    let x = local_target.x;
288    let y = local_target.y;
289    let z = local_target.z;
290
291    let yaw = x.atan2(z).to_degrees();
292    let xz = (x * x + z * z).sqrt();
293    let pitch = (-y).atan2(xz).to_degrees();
294
295    (yaw, pitch)
296}