oxihuman_morph/
neck_sterno_control.rs

1// Copyright (C) 2026 COOLJAPAN OU (Team KitaSan) / SPDX-License-Identifier: Apache-2.0
2#![allow(dead_code)]
3
4//! Neck sternocleidomastoid (SCM) prominence control.
5
6use std::f32::consts::FRAC_PI_4;
7
8/// SCM side.
9#[allow(dead_code)]
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
11pub enum ScmSide {
12    Left,
13    Right,
14}
15
16/// Config.
17#[allow(dead_code)]
18#[derive(Debug, Clone, PartialEq)]
19pub struct NeckSternoConfig {
20    pub max_prominence_m: f32,
21}
22
23impl Default for NeckSternoConfig {
24    fn default() -> Self {
25        Self {
26            max_prominence_m: 0.009,
27        }
28    }
29}
30
31/// State.
32#[allow(dead_code)]
33#[derive(Debug, Clone, Default)]
34pub struct NeckSternoState {
35    pub left: f32,
36    pub right: f32,
37    /// Head rotation that drives SCM activation, −1..=1.
38    pub head_rotation: f32,
39}
40
41#[allow(dead_code)]
42pub fn new_neck_sterno_state() -> NeckSternoState {
43    NeckSternoState::default()
44}
45
46#[allow(dead_code)]
47pub fn default_neck_sterno_config() -> NeckSternoConfig {
48    NeckSternoConfig::default()
49}
50
51#[allow(dead_code)]
52pub fn nst_set(state: &mut NeckSternoState, side: ScmSide, v: f32) {
53    let v = v.clamp(0.0, 1.0);
54    match side {
55        ScmSide::Left => state.left = v,
56        ScmSide::Right => state.right = v,
57    }
58}
59
60#[allow(dead_code)]
61pub fn nst_set_both(state: &mut NeckSternoState, v: f32) {
62    let v = v.clamp(0.0, 1.0);
63    state.left = v;
64    state.right = v;
65}
66
67#[allow(dead_code)]
68pub fn nst_set_head_rotation(state: &mut NeckSternoState, v: f32) {
69    state.head_rotation = v.clamp(-1.0, 1.0);
70}
71
72#[allow(dead_code)]
73pub fn nst_reset(state: &mut NeckSternoState) {
74    *state = NeckSternoState::default();
75}
76
77#[allow(dead_code)]
78pub fn nst_is_neutral(state: &NeckSternoState) -> bool {
79    state.left < 1e-4 && state.right < 1e-4 && state.head_rotation.abs() < 1e-4
80}
81
82#[allow(dead_code)]
83pub fn nst_asymmetry(state: &NeckSternoState) -> f32 {
84    (state.left - state.right).abs()
85}
86
87/// Angle of SCM pull in radians.
88#[allow(dead_code)]
89pub fn nst_pull_angle_rad(state: &NeckSternoState) -> f32 {
90    ((state.left + state.right) * 0.5) * FRAC_PI_4
91}
92
93#[allow(dead_code)]
94pub fn nst_to_weights(state: &NeckSternoState, cfg: &NeckSternoConfig) -> [f32; 2] {
95    [
96        state.left * cfg.max_prominence_m,
97        state.right * cfg.max_prominence_m,
98    ]
99}
100
101#[allow(dead_code)]
102pub fn nst_blend(a: &NeckSternoState, b: &NeckSternoState, t: f32) -> NeckSternoState {
103    let t = t.clamp(0.0, 1.0);
104    let inv = 1.0 - t;
105    NeckSternoState {
106        left: a.left * inv + b.left * t,
107        right: a.right * inv + b.right * t,
108        head_rotation: a.head_rotation * inv + b.head_rotation * t,
109    }
110}
111
112#[allow(dead_code)]
113pub fn nst_to_json(state: &NeckSternoState) -> String {
114    format!(
115        "{{\"left\":{:.4},\"right\":{:.4},\"head_rotation\":{:.4}}}",
116        state.left, state.right, state.head_rotation
117    )
118}
119
120#[cfg(test)]
121mod tests {
122    use super::*;
123
124    #[test]
125    fn default_neutral() {
126        assert!(nst_is_neutral(&new_neck_sterno_state()));
127    }
128
129    #[test]
130    fn set_clamps_high() {
131        let mut s = new_neck_sterno_state();
132        nst_set(&mut s, ScmSide::Left, 5.0);
133        assert!((s.left - 1.0).abs() < 1e-6);
134    }
135
136    #[test]
137    fn set_clamps_low() {
138        let mut s = new_neck_sterno_state();
139        nst_set(&mut s, ScmSide::Right, -1.0);
140        assert!(s.right < 1e-6);
141    }
142
143    #[test]
144    fn head_rotation_clamps() {
145        let mut s = new_neck_sterno_state();
146        nst_set_head_rotation(&mut s, 2.0);
147        assert!((s.head_rotation - 1.0).abs() < 1e-6);
148    }
149
150    #[test]
151    fn reset_clears() {
152        let mut s = new_neck_sterno_state();
153        nst_set_both(&mut s, 0.8);
154        nst_reset(&mut s);
155        assert!(nst_is_neutral(&s));
156    }
157
158    #[test]
159    fn asymmetry_zero_when_equal() {
160        let mut s = new_neck_sterno_state();
161        nst_set_both(&mut s, 0.5);
162        assert!(nst_asymmetry(&s) < 1e-6);
163    }
164
165    #[test]
166    fn pull_angle_positive() {
167        let mut s = new_neck_sterno_state();
168        nst_set_both(&mut s, 1.0);
169        assert!(nst_pull_angle_rad(&s) > 0.0);
170    }
171
172    #[test]
173    fn weights_correct() {
174        let cfg = default_neck_sterno_config();
175        let mut s = new_neck_sterno_state();
176        nst_set_both(&mut s, 1.0);
177        let w = nst_to_weights(&s, &cfg);
178        assert!((w[0] - cfg.max_prominence_m).abs() < 1e-6);
179    }
180
181    #[test]
182    fn blend_midpoint() {
183        let mut b = new_neck_sterno_state();
184        nst_set_both(&mut b, 1.0);
185        let r = nst_blend(&new_neck_sterno_state(), &b, 0.5);
186        assert!((r.left - 0.5).abs() < 1e-5);
187    }
188
189    #[test]
190    fn json_has_keys() {
191        let j = nst_to_json(&new_neck_sterno_state());
192        assert!(j.contains("left") && j.contains("head_rotation"));
193    }
194}
oxihuman_morph/neck_sterno_control.rs

oxihuman_morph/
neck_sterno_control.rs
