MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
IntervalScan.hpp
Go to the documentation of this file.
1#pragma once
2
3/**
4 * @file IntervalScan.hpp
5 * @brief Runs of a score sequence that stay above a threshold, found in order as a stream, for MayaFlux::Kinesis
6 *
7 * Domain-agnostic: the scores can be any per-window measurement. Positions are
8 * in samples, 32 bit.
9 */
10
12
13/**
14 * @struct IntervalScanConfig
15 * @brief Settings of an IntervalScanner
16 *
17 * Score i of a stream sits at sample first_sample + i * hop. A run starts at a
18 * score at or above enter and is released by a score below leave once the quiet
19 * has lasted min_gap. A run not longer than min_run is dropped. Each interval
20 * is widened by padding on both sides, and a gap between neighbours smaller than
21 * twice the padding is split between them.
22 *
23 * max_run caps one interval, 0 for no cap, and must exceed hop + 2 * padding
24 * when set. A capped run is cut at the longest gap seen inside it when
25 * use_longest_gap is set, else at the last gap longer than gap_at_limit, else
26 * where the cap falls.
27 *
28 * With a gate, a position whose gate score is below gate_threshold is silence:
29 * an open run ends there at once whatever min_gap is, the position is never
30 * engaged, and a gap is bridged only while the gate stays at or above its
31 * threshold. A run ended by the gate closes where its last engaged stretch
32 * ended, before padding.
33 *
34 * length is the stream length used to clamp padded ends, 0 for the end of the
35 * scores seen so far.
36 *
37 * With emit_on_close an interval is released the moment it closes, padded by
38 * the full padding on both sides. Nothing waits for a successor, so latency is
39 * the trailing gap alone, and the gap between neighbours is no longer split:
40 * their paddings may overlap.
41 */
43 double enter { 0.5 };
44 double leave { 0.35 };
45 double gate_threshold { 0.5 };
46 uint32_t hop { 512 };
47 uint32_t first_sample { 0 };
48 uint32_t min_run { 4000 };
49 uint32_t min_gap { 1600 };
50 uint32_t padding { 480 };
51 uint32_t gap_at_limit { 1568 };
52 uint32_t max_run { 0 };
53 bool use_longest_gap { true };
54 uint32_t length { 0 };
55 bool emit_on_close { false };
56};
57
58/**
59 * @brief Why a config cannot be scanned.
60 * @return The reason, empty when the config is valid: thresholds finite, hop above 0, and max_run, when set, above hop plus twice the padding.
61 */
62[[nodiscard]] MAYAFLUX_API std::string diagnose_interval_scan(const IntervalScanConfig& config);
63
64/**
65 * @class IntervalScanner
66 * @brief The two threshold run detector as a stateful object
67 *
68 * Every score depends on the state the previous one left, so scores are read in
69 * order, and that state persists between calls: successive push calls continue
70 * one stream. The newest interval stays pending until its successor closes,
71 * because its padded end depends on the gap that follows; flush releases it and
72 * ends the stream. Scores are compared as 32 bit floats, so the intervals match
73 * those of the GPU IntervalExtractor for the same scores and settings.
74 */
75class MAYAFLUX_API IntervalScanner {
76public:
77 using Interval = std::pair<size_t, size_t>;
78
79 /**
80 * @brief Construct a scanner
81 * @throws std::invalid_argument When diagnose_interval_scan gives a reason
82 */
84
85 /**
86 * @brief Continue the stream with more scores
87 * @param scores Scores in order
88 * @param gate One gate score per score, or empty for no gate
89 * @return The half open intervals completed by this call, in order
90 * @throws std::invalid_argument When gate is not empty and its length differs from the scores
91 */
92 [[nodiscard]] std::vector<Interval> push(std::span<const double> scores, std::span<const double> gate = {});
93
94 /**
95 * @brief End the stream: close the open run and release the pending interval
96 * @return The intervals this releases. The next push starts a new stream.
97 */
98 [[nodiscard]] std::vector<Interval> flush();
99
100 /** @brief Start a new stream without releasing anything. */
101 void reset() noexcept;
102
103 [[nodiscard]] const IntervalScanConfig& config() const noexcept { return m_config; }
104
105 /** @brief Start of the run in progress after the last score, if one is open. */
106 [[nodiscard]] std::optional<size_t> open_start() const noexcept
107 {
108 return m_has_start ? std::optional<size_t> { m_start } : std::nullopt;
109 }
110
111 /** @brief The closed interval still waiting for its padded end: its padded start and its end before trailing padding. */
112 [[nodiscard]] std::optional<Interval> pending() const noexcept
113 {
114 return m_pend_valid ? std::optional<Interval> { Interval { m_pend_start, m_pend_end } } : std::nullopt;
115 }
116
117private:
119 uint32_t m_run_limit {};
120 uint32_t m_total {};
121 uint64_t m_seen {};
122
123 bool m_triggered {};
124 uint32_t m_start {};
125 bool m_has_start {};
126 uint32_t m_temp_end {};
127 uint32_t m_prev_end {};
128 uint32_t m_next_start {};
129 uint32_t m_best_end {};
130 uint32_t m_best_dur {};
131 bool m_has_best {};
133 uint32_t m_pend_start {};
134 uint32_t m_pend_end {};
135
136 void close_run(uint32_t start, uint32_t end, std::vector<Interval>& out);
137 void reset_gap_state() noexcept;
138 void update_total() noexcept;
139};
140
141} // namespace MayaFlux::Kinesis::Discrete
const IntervalScanConfig & config() const noexcept
IntervalScanner(const IntervalScanConfig &config)
Construct a scanner.
std::vector< Interval > push(std::span< const double > scores, std::span< const double > gate={})
Continue the stream with more scores.
std::optional< Interval > pending() const noexcept
The closed interval still waiting for its padded end: its padded start and its end before trailing pa...
std::optional< size_t > open_start() const noexcept
Start of the run in progress after the last score, if one is open.
std::string diagnose_interval_scan(const IntervalScanConfig &config)
Why a config cannot be scanned.