🎥 LuxVideoDet 整体架构

跨平台工业视频检测系统 — 单一视频源 + 多算法并行推理的通用框架 技术栈：C# / .NET 8 · OpenCvSharp · ONNX Runtime / OpenVINO · Avalonia UI · ASP.NET Core

1. 系统定位

LuxVideoDet 是一个面向工业制造现场的视频行为检测与流程合规判定平台。它从一路视频源（RTSP 摄像头 / 本地视频文件 / MQTT 推流 / 本地摄像头）读取画面，同时并行运行一个或多个「检测算法」，对画面中的目标进行识别、对作业流程进行状态机判定，并在命中违规/异常时触发多渠道告警（Webhook / 企业微信 / 语音播报 / PLC），同时落盘 NG 截图、录像与生产统计。

核心设计原则：

1. 一源多用：视频流只拉取一次，分发给 N 个算法各自独立推理，避免带宽与解码浪费。
2. 算法可插拔：每个算法是一个「描述符 + 算法类」的组合，通过反射自动注册，新增算法无需改动框架代码。
3. 三宿主形态：同一套 Core 引擎由 Desktop（Avalonia 桌面端）、Web（ASP.NET Core 控制台）、Headless（无头服务）三种前端复用。
4. 状态机驱动：每个流程类算法内部用显式状态机描述「上一步完成 → 检测下一步」的语义，而非散落的 if/else。

2. 解决方案结构

解决方案 LuxVideoDet.sln 由 6 个项目 + 1 个测试分组构成：

依赖方向：Desktop / Web / Headless → Core + Localization，三者互不依赖，共享同一套 Core 引擎。

3. Core 分层架构

LuxVideoDet.Core 内部按职责划分为以下命名空间（目录）：

4. 运行时数据流

一次检测会话（Session）从启动到产出的完整链路如下：

flowchart LR
    subgraph VideoSource[视频源层]
        RTSP[RtspSource]
        Local[LocalVideoSource]
        Mqtt[MqttVideoSource]
        Cam[CameraSource]
    end

    subgraph Pipeline[流水线层 MultiAlgorithmPipeline]
        BC[BroadcastLoopAsync
取帧广播循环]
        BC -->|IngestFrameForRecording| REC[录像环形缓冲]
        BC -->|DistributeFrameAsync| W1
        BC -->|DistributeFrameAsync| W2
        BC -->|DistributeFrameAsync| WN
    end

    subgraph Workers[算法工作者]
        W1[AlgorithmWorker 1
队列+处理线程]
        W2[AlgorithmWorker 2]
        WN[AlgorithmWorker N]
    end

    subgraph Algorithm[算法实例]
        A1[DetectionAlgorithmBase
ProcessDetections]
        A2[DetectionAlgorithmBase]
        AN[DetectionAlgorithmBase]
    end

    subgraph Inference[推理引擎]
        ONNX[OnnxInferenceEngine]
        OV[OpenVinoInferenceEngine]
        HTTP[RemoteHttpInferenceEngine]
        MQTTE[MqttInferenceEngine]
    end

    subgraph Output[结果产出]
        R[DetectionResult]
        N[Notification 告警]
        S[Storage 截图/录像]
        T[ProductionStatisticsStore 统计]
    end

    RTSP --> BC
    Local --> BC
    Mqtt --> BC
    Cam --> BC
    W1 --> A1 --> ONNX
    W2 --> A2 --> OV
    WN --> AN --> HTTP
    ONNX --> R
    OV --> R
    HTTP --> R
    MQTTE --> R
    R --> N
    R --> S
    R --> T

关键机制：

• 单帧多投：BroadcastLoopAsync 是唯一的取帧线程，读取一帧后分发给所有 AlgorithmWorker。单算法时直接传原始帧（零克隆），多算法时前 N-1 个收到克隆、最后一个收到原始帧，避免引用冲突。
• 异步解耦：每个 Worker 拥有独立的 Queue<Frame> 与处理线程，以各自节奏推理，互不阻塞；队列满时丢弃最旧帧（RTSP 式跳帧），保证实时预览不堆积。
• 本地视频节流：LocalVideoSource 按标称帧率节流，防止文件被以最大速度解码导致播放加速。
• 录像解耦：录像帧由 IngestFrameForRecording(Mat) 在取帧线程全速喂入环形缓冲，与算法推理速度无关，保证慢推理（如远程 HTTP）下 NG 视频帧仍充足。
• 多算法结果合成：以「处理帧数最多」的算法画面为底图，叠加其他算法的检测框与区域轮廓，避免快慢算法并行时画面「跳回过去」。

5. 算法开发框架

5.1 三层抽象

classDiagram
    class IDetectionAlgorithm {
        <>
        +AlgorithmType
        +Initialize(config)
        +Process(frame) DetectionResult
        +RenderAnnotations(frame, result)
        +Reset()
    }
    class IAlgorithmDescriptor {
        <>
        +TypeKey
        +DisplayName
        +DefaultClasses
        +RequiredRegions
        +Create(...) IDetectionAlgorithm
        +DefaultOtherArgs
        +AlgorithmAoiUsages
    }
    class DetectionAlgorithmBase {
        <>
        #_inferenceEngine
        #_regionManager
        #_notifiers
        +Initialize(config)
        #ProcessDetections(...)
        #GetDetectionClassBindings()
    }
    IDetectionAlgorithm <|.. DetectionAlgorithmBase
    IAlgorithmDescriptor ..> IDetectionAlgorithm : Create
    DetectionAlgorithmBase <|-- 具体算法

• IAlgorithmDescriptor：算法的「元数据 + 工厂」。框架启动时通过反射扫描程序集中所有实现自动注册，无需手动改工厂代码。它声明了算法类型键、显示名、默认类别、所需区域、可配置的「其他参数」（DefaultOtherArgs）与 AOI 使用声明（AlgorithmAoiUsages）。
• DetectionAlgorithmBase：模板方法基类。子类只需实现 ProcessDetections（核心判定逻辑）；可选覆写 GetDetectionClassBindings 完成「业务键 ↔ 模型类名 ↔ ClassId」映射，基类会在配色前统一处理类别绑定。
• IDetectionAlgorithm：运行实例接口，Process(frame) 是每帧入口。

5.2 每个算法的标准文件结构

一个算法目录通常包含以下协作文件（以 E9_2F_NXT_PDA_Feeding_Monitor 为例）：

5.3 状态机模式

流程类算法采用「检测下一步」的状态机语义：

• 每个状态对应一个实际步骤；TransitionTo 进入新状态时重置 CurrentStateEnterTime 计时起点。
• 每帧 ProcessDetections 先计算各信号的确认值（经 ConfirmWithFrames 连续 N 帧抗抖动），再交给状态机 Update() 判定推进或超时。
• 步骤超时：每个中间步骤可配独立的 *_timeout_seconds 参数，超时即报「操作错误」并进入 ERROR 状态，等待恢复或手动确认。

5.4 算法清单

6. 推理引擎体系

6.1 引擎抽象

所有推理引擎实现 IInferenceEngine 接口，通过 InferenceEngineFactory 按配置实例化：

设备注册表 InferenceDeviceRegistry 提供 CPU / CUDA / QNN / CoreML 等设备描述。

6.2 模型输出布局

DetectionOutputLayout 自动区分两种导出格式：

• 标准格式：[1, 4+nc, anchors]（YOLO 原始输出，需本框架做 NMS）。
• end2end 格式：[1, max_det, 6]（导出时已内嵌 NMS），按 dim2==6 && dim1>6 自动识别，不重复 NMS。

预处理：letterbox + BGR→RGB + /255 + NCHW。后处理按任务类型由 PostprocessorFactory 分发（检测/旋转框/姿态/分割/分类），检测类无 DFL。

6.3 类别名解析

• 模型类别名从 ONNX 元数据 metadata_props["names"] 读取。
• ClassIdsResolution 将「业务键 ↔ 模型类名」绑定解析为实际 ClassId；配置 classes 与 metadata 不一致时引擎告警并按模型顺序强制解析。
• ClassIdAutoMapper 支持类别名自动映射。

7. 通知体系

告警由算法在 DetectionResult 中携带，经 NotificationServiceFactory 分发到配置的渠道：

正文归属原则：NotificationMessage.Text（自定义模板）由算法自行构造，渠道不硬编码算法文案。当算法未提供 Text 时，Webhook 回退到通用默认格式 【标题】\n时间\n级别\n内容（标题优先级：title_content 参数 → NotificationTitle → AlgorithmType → “检测告警”）。企业微信 / 喇叭 / PLC 各自使用固定格式，不读 Text。

8. 配置系统

• 存储：JsonConfigurationStore（多文件）或 SingleFileConfigurationStore（单文件 configs.json）。
• 服务：ConfigurationService 提供 ListAsync / LoadAsync / SaveAsync / ValidateAsync / ImportAsync 等。
• 序列化：JSON 键统一 camelCase（ConfigurationJsonOptions.ForConfigurationFile + JsonNamingPolicy.CamelCase），代码中禁止使用 JsonPropertyName 特性。
• 校验：DetectionConfigurationValidator 在启动/保存时校验区域完整性、算法与模型类别匹配等，缺失必要区域抛 MissingAlgorithmRegionsException。
• 数据模型：DetectionConfiguration（顶层，含 Name/Id/Enabled/VideoSource/Algorithms[]）→ AlgorithmConfig（含 AlgorithmType/Inference/Regions/Notification/Args）→ InferenceConfig（模型路径/设备/阈值/类别）。

9. 存储与统计

10. 三种宿主形态

三者均通过 AddLuxVideoDetCore() 复用同一套 DI 注册与 Core 引擎，仅前端呈现层不同。

11. 关键设计决策（约定）

1. JSON 键 camelCase，禁止 JsonPropertyName 特性。
2. UI 文案本地化：一律 _appLocalizer.GetString(UiKeys.Xxx)，禁止 AXAML 硬编码中文。
3. 增量功能禁止引入新 NuGet 包。
4. 「其他参数」UI 自动驱动：IAlgorithmDescriptor.DefaultOtherArgs 声明参数即出现在编辑器，无需改 ViewModel/AXAML。
5. 清单渲染统一缩放：s = frame.Width / 2560.0，新增清单渲染器须带同样缩放。
6. 通知正文归算法所有：渠道不硬编码算法文案。
7. NG 录像与推理解耦：录像帧全速喂入环形缓冲，不在 Process 内喂。
8. 类别名严格一致：模型 metadata 类别名须与代码类名精确匹配（大小写/空格/拼写）。
9. 测试用 --filter 定向运行：存在预存错误时跳过，避免全量测试被旧错误阻塞。
10. 模型选型以实测为准：不同训练轮次/窄化重训模型能力差异大，不能仅凭类别名判断。

文档基于代码库 LuxVideoDet.sln 结构梳理，随架构演进持续更新。