harmos_signal/waveform/

edge.rs

//! Where a waveform crossed something: a hysteresis trigger, and a plain
//! first crossing.

/// One transition of a waveform through its trigger, at an interpolated
/// coordinate.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Edge {
    /// Where the crossing happened, in the coordinates of the `x` axis.
    pub at: f64,
    /// Whether the waveform was going up. A falling edge is `false`.
    pub rising: bool,
}

/// Every edge a waveform makes through a two-level trigger.
///
/// `low` and `high` are fractions of the waveform's own range, so `0.1` and
/// `0.9` are the usual ten-to-ninety-percent thresholds whatever the signal's
/// amplitude turns out to be. Two levels rather than one is the whole point: a
/// waveform that rings around a single threshold would trigger on every
/// wobble, and one that has to cross the *other* level before it can trigger
/// again cannot.
///
/// Each edge's coordinate is interpolated between the samples that straddle the
/// threshold. A waveform with no range at all — a constant — has no edges.
#[must_use]
pub fn edges(x: &[f64], y: &[f64], low: f64, high: f64) -> Vec<Edge> {
    let length = x.len().min(y.len());
    if length < 2 {
        return Vec::new();
    }

    let lowest = y[..length].iter().copied().fold(f64::INFINITY, f64::min);
    let highest = y[..length]
        .iter()
        .copied()
        .fold(f64::NEG_INFINITY, f64::max);
    let range = highest - lowest;
    if !range.is_finite() || range < f64::EPSILON {
        return Vec::new();
    }

    let (low, high) = (lowest + range * low, lowest + range * high);
    let mut state = level(y[0], low, high);
    let mut found = Vec::new();

    for index in 1..length {
        let (previous, current) = (y[index - 1], y[index]);

        match state {
            Level::Beneath if current > high => {
                found.push(Edge {
                    at: crossed(x, index, high, previous, current),
                    rising: true,
                });
                state = Level::Above;
            }
            Level::Above if current < low => {
                found.push(Edge {
                    at: crossed(x, index, low, previous, current),
                    rising: false,
                });
                state = Level::Beneath;
            }
            Level::Between => state = level(current, low, high),
            Level::Beneath | Level::Above => {}
        }
    }

    found
}

/// The coordinate at which the waveform first reaches `target`.
///
/// Interpolated between the two samples that straddle it, and answered for the
/// first straddle in either direction. A waveform that never reaches the value
/// has no crossing.
#[must_use]
pub fn crossing(x: &[f64], y: &[f64], target: f64) -> Option<f64> {
    let length = x.len().min(y.len());

    (1..length).find_map(|index| {
        let (previous, current) = (y[index - 1], y[index]);
        let straddles =
            (previous <= target && target <= current) || (current <= target && target <= previous);

        straddles.then(|| crossed(x, index, target, previous, current))
    })
}

/// Which side of the trigger a sample is on.
#[derive(Clone, Copy)]
enum Level {
    Beneath,
    Between,
    Above,
}

/// The level one value sits at.
fn level(value: f64, low: f64, high: f64) -> Level {
    if value > high {
        Level::Above
    } else if value < low {
        Level::Beneath
    } else {
        Level::Between
    }
}

/// Where between samples `index - 1` and `index` the waveform met `target`.
fn crossed(x: &[f64], index: usize, target: f64, previous: f64, current: f64) -> f64 {
    let (before, after) = (x[index - 1], x[index]);
    let rise = current - previous;

    if rise.abs() < f64::EPSILON {
        return before;
    }

    before + (target - previous) / rise * (after - before)
}

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

    /// A unit-spaced axis of `count` coordinates.
    fn axis(count: usize) -> Vec<f64> {
        (0..count).map(|index| index as f64).collect()
    }

    #[test]
    fn a_square_wave_makes_one_edge_per_transition() {
        let y = vec![0.0, 0.0, 1.0, 1.0, 0.0, 0.0, 1.0, 1.0];
        let found = edges(&axis(8), &y, 0.1, 0.9);

        assert_eq!(found.len(), 3);
        assert!(found[0].rising);
        assert!(!found[1].rising);
        assert!(found[2].rising);
    }

    #[test]
    fn an_edge_is_placed_between_the_samples_that_straddle_it() {
        // Rising from zero to two over one second crosses one at the half.
        let found = edges(&axis(3), &[0.0, 2.0, 0.0], 0.25, 0.5);

        assert!((found[0].at - 0.5).abs() < 1e-12, "rose at {}", found[0].at);
        assert!(
            (found[1].at - 1.75).abs() < 1e-12,
            "fell at {}",
            found[1].at
        );
    }

    #[test]
    fn hysteresis_refuses_to_trigger_twice_on_one_transition() {
        // A ringing rise: without a second level, the wobble at index 3 would
        // count as a fresh edge.
        let y = vec![0.0, 0.0, 1.0, 0.6, 1.0, 1.0];
        let found = edges(&axis(6), &y, 0.1, 0.9);

        assert_eq!(found.len(), 1);
        assert!(found[0].rising);
    }

    #[test]
    fn a_constant_waveform_has_no_edges() {
        assert!(edges(&axis(10), &[5.0; 10], 0.1, 0.9).is_empty());
        assert!(edges(&[], &[], 0.1, 0.9).is_empty());
        assert!(edges(&[0.0], &[1.0], 0.1, 0.9).is_empty());
    }

    #[test]
    fn a_crossing_is_the_first_one_in_either_direction() {
        let y = vec![0.0, 1.0, 2.0, 1.0, 0.0];

        assert!(crossing(&axis(5), &y, 1.5).is_some_and(|at| (at - 1.5).abs() < 1e-12));
        assert!(crossing(&axis(5), &y, 0.5).is_some_and(|at| (at - 0.5).abs() < 1e-12));
    }

    #[test]
    fn a_value_the_waveform_never_reaches_is_never_crossed() {
        assert!(crossing(&axis(5), &[0.0, 1.0, 2.0, 1.0, 0.0], 5.0).is_none());
        assert!(crossing(&[], &[], 1.0).is_none());
    }

    #[test]
    fn a_flat_pair_straddling_the_target_answers_the_earlier_coordinate() {
        assert!(crossing(&axis(3), &[1.0, 1.0, 2.0], 1.0).is_some_and(|at| at.abs() < 1e-12));
    }
}