oxihuman-morph 0.1.2

Parametric morphology engine for human body generation — targets, blendshapes, FACS
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

// Copyright (C) 2026 COOLJAPAN OU (Team KitaSan)
// SPDX-License-Identifier: Apache-2.0
#![allow(dead_code)]

//! Gaze constraint — limits gaze direction and corrects morph weights.

/// Limits applied to the gaze cone.
#[derive(Debug, Clone)]
pub struct GazeConstraintConfig {
    pub max_yaw_deg: f32,
    pub max_pitch_deg: f32,
    pub soft_limit_ratio: f32,
}

impl Default for GazeConstraintConfig {
    fn default() -> Self {
        Self { max_yaw_deg: 35.0, max_pitch_deg: 25.0, soft_limit_ratio: 0.8 }
    }
}

/// Current constrained gaze state.
#[derive(Debug, Clone, Default)]
pub struct GazeConstraintState {
    pub yaw_deg: f32,
    pub pitch_deg: f32,
    pub config: GazeConstraintConfig,
}

impl GazeConstraintState {
    /// Create a new gaze constraint state with default config.
    pub fn new() -> Self {
        Self { config: GazeConstraintConfig::default(), ..Default::default() }
    }
}

/// Apply gaze direction, clamping to configured limits.
pub fn gc_set_gaze(state: &mut GazeConstraintState, yaw: f32, pitch: f32) {
    state.yaw_deg = yaw.clamp(-state.config.max_yaw_deg, state.config.max_yaw_deg);
    state.pitch_deg = pitch.clamp(-state.config.max_pitch_deg, state.config.max_pitch_deg);
}

/// Return true if the gaze is inside the soft limit cone.
pub fn gc_is_comfortable(state: &GazeConstraintState) -> bool {
    let r = state.config.soft_limit_ratio;
    state.yaw_deg.abs() <= state.config.max_yaw_deg * r
        && state.pitch_deg.abs() <= state.config.max_pitch_deg * r
}

/// Return normalised yaw in [-1, 1] relative to max.
pub fn gc_normalised_yaw(state: &GazeConstraintState) -> f32 {
    if state.config.max_yaw_deg < 1e-6 {
        return 0.0;
    }
    state.yaw_deg / state.config.max_yaw_deg
}

/// Return normalised pitch in [-1, 1] relative to max.
pub fn gc_normalised_pitch(state: &GazeConstraintState) -> f32 {
    if state.config.max_pitch_deg < 1e-6 {
        return 0.0;
    }
    state.pitch_deg / state.config.max_pitch_deg
}

/// Reset gaze to neutral.
pub fn gc_reset(state: &mut GazeConstraintState) {
    state.yaw_deg = 0.0;
    state.pitch_deg = 0.0;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_initial_neutral() {
        /* default state should be neutral */
        let s = GazeConstraintState::new();
        assert_eq!(s.yaw_deg, 0.0);
        assert_eq!(s.pitch_deg, 0.0);
    }

    #[test]
    fn test_set_gaze_clamps() {
        /* gaze beyond limit should be clamped */
        let mut s = GazeConstraintState::new();
        gc_set_gaze(&mut s, 999.0, -999.0);
        assert!((s.yaw_deg - s.config.max_yaw_deg).abs() < 1e-6);
        assert!((s.pitch_deg + s.config.max_pitch_deg).abs() < 1e-6);
    }

    #[test]
    fn test_comfortable() {
        /* small gaze should be comfortable */
        let mut s = GazeConstraintState::new();
        gc_set_gaze(&mut s, 5.0, 5.0);
        assert!(gc_is_comfortable(&s));
    }

    #[test]
    fn test_uncomfortable() {
        /* gaze at max limit should not be comfortable */
        let mut s = GazeConstraintState::new();
        let max = s.config.max_yaw_deg;
        gc_set_gaze(&mut s, max, 0.0);
        assert!(!gc_is_comfortable(&s));
    }

    #[test]
    fn test_normalised_yaw() {
        /* half-max yaw should normalise to 0.5 */
        let mut s = GazeConstraintState::new();
        let half = s.config.max_yaw_deg / 2.0;
        gc_set_gaze(&mut s, half, 0.0);
        assert!((gc_normalised_yaw(&s) - 0.5).abs() < 1e-5);
    }

    #[test]
    fn test_normalised_pitch() {
        /* half-max pitch should normalise to -0.5 */
        let mut s = GazeConstraintState::new();
        let half = s.config.max_pitch_deg / 2.0;
        gc_set_gaze(&mut s, 0.0, -half);
        assert!((gc_normalised_pitch(&s) + 0.5).abs() < 1e-5);
    }

    #[test]
    fn test_reset() {
        /* reset should zero both angles */
        let mut s = GazeConstraintState::new();
        gc_set_gaze(&mut s, 20.0, 10.0);
        gc_reset(&mut s);
        assert_eq!(s.yaw_deg, 0.0);
        assert_eq!(s.pitch_deg, 0.0);
    }

    #[test]
    fn test_default_config_limits() {
        /* config limits should be positive */
        let cfg = GazeConstraintConfig::default();
        assert!(cfg.max_yaw_deg > 0.0);
        assert!(cfg.max_pitch_deg > 0.0);
    }

    #[test]
    fn test_soft_limit_ratio_range() {
        /* soft limit ratio should be within (0, 1) */
        let cfg = GazeConstraintConfig::default();
        assert!((0.0..=1.0).contains(&cfg.soft_limit_ratio));
    }
}