波形识别分析插件接口

wave_recognition 与 analyzer_epoch、analyzer_erp 一样，是由分析页动态发现的 AnalyzerViewPlugin。生产入口为：

from plugins.wave_recognition import AnalyzerViewPlugin

# AnalyzerViewPlugin is AnalyzerWaveRecognitionWidget

插件包通过 info.json 中的 {"analyzer_view": {"enabled": true}} 参与发现， 宿主不应直接导入具体插件类。

1. 组件边界

AnalyzerWaveRecognitionWidget 是唯一总装和状态协调层，内部包含：

• WaveRecognitionTopBar：背景活动、导航、设置和 panel 显隐；
• WaveformAreaWidget：当前窗口 EEG、Trigger、Mark 和 Segment；
• WaveRecognitionProgressBar：整段记录缩略时间轴和当前窗口；
• AnnotationOverviewPanel：背景、Segment 和 Mark 列表。

波形、时间轴和 panel 不直接修改宿主数据。它们发出用户意图，由总装层更新权威状态， 再向所有子组件回填完整快照。

2. AnalyzerViewPlugin 宿主钩子

set_data_provider(provider)

宿主注入整段预处理 EEG：

provider() -> (
    eeg,          # np.ndarray, shape=(channels, samples)
    fs,           # float, Hz
    ch_names,     # list[str]
    trigger_mat,  # np.ndarray, shape=(N, 2), [sample_index, code]
    scale_unit,   # float, 转换到 µV 的倍率
)

set_event_provider(provider)

宿主注入统一 Auto、Manual、behavioral 事件流。事件至少包含 source、label， 并通过 sample_index 或 display_timestamp / timestamp 定位。

bind_eeg_preprocessing(host)

绑定宿主预处理变更和现有 EEG 波形显示配置。插件通过鸭子类型消费宿主能力，不导入 app.view 中的具体视图类。

recompute() / activate_analysis_view()

• 首次激活或预处理变化后，重新读取整段 EEG；
• 普通再次激活只同步事件和显示配置，不重复执行整段预处理；
• 隐藏时延迟计算，重新显示后再刷新。

refresh_events()

Manual 事件新增或删除后由宿主调用。只刷新 Trigger 层，不重新计算 EEG。

3. 唯一时间契约

秒与毫秒、绝对时间与相对时间只允许在 AnalyzerWaveRecognitionWidget 中转换。

4. 标注数据

波形帧的字典键携带标注类型：

marks = {
    "Mark": [(label, channel, unix_start_sec, duration_ms, highlighted)],
    "Segment": [(label, "", unix_start_sec, duration_ms, highlighted)],
    "background": [],
}

时间轴统一使用记录内相对毫秒：

marks = {
    "Mark": [(label, channel, relative_start_ms, duration_ms)],
    "Segment": [(label, "", relative_start_ms, duration_ms)],
}

波形通过 marks_change 发出变更命令：

{
    "action": "add" | "del" | "change",
    "before": (mark_type, label, channel, unix_start_sec, duration_ms) | None,
    "after": (mark_type, label, channel, unix_start_sec, duration_ms) | None,
}

总装层处理命令后重新向波形、时间轴和右侧 panel 回填状态。

Segment 使用相邻边界形成：第一个边界提供标签和起点，后一个边界提供结束点；相邻同标签 Segment 自动合并。

5. 标签定义

设置弹窗使用：

LabelDefinition(label, color, description, shortcut)

波形的统一标签表为：

wave_key_map = {
    label: (shortcut, color, "mark" | "segment" | "background")
}

时间轴读取同一映射的前两个字段。标签或快捷键冲突时，总装层保留第一项；重复快捷键的 后续项按空快捷键处理，避免交互崩溃。

6. 状态所有权

• EEG、预处理配置和 Auto/Manual 事件属于宿主；
• 当前观察窗口、波形 Mark、Segment 边界、背景活动和标签配置属于插件实例；
• annotation_state() 返回插件标注状态副本，供后续持久化或导出适配器使用；
• 所有子组件只持有渲染快照，不作为权威数据源。