# Interface_Algo

**Repository Path**: dfhhdq/interface-algo

## Basic Information

- **Project Name**: Interface_Algo
- **Description**: 算法端程序，人员入侵，工服，安全帽，烟雾火焰，跌倒，跟踪，抽烟，打电话等
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Interface_Algo — 业务算法 DLL

基于 CGraph 编排的业务算法库,推理端依赖 **Interface_AI**(YOLO detect/pose/segment/obb)。每个算法 = 创建 / 检测 / 销毁 三个导出函数 + 句柄,返回统一报警结构体。

> 文档分工:[AGENTS.md](AGENTS.md) 开发约定 · [handoff.md](handoff.md) 设计决策/踩坑/需求源头 · [CHANGELOG.md](CHANGELOG.md) 变更历史

## 已实现算法

| 算法 | 规则 | 接口 |
|---|---|---|
| 人员入侵 | 框**底部中心点**在 mask 内 → 报警(全部对象) | `createIntrusionDetector` / `detectIntrusion` / `destroyIntrusionDetector` |
| 烟雾火焰 | 框**中心点**在 mask 内 → 报警(全部对象) | `createSmokeFireDetector` / `detectSmokeFire` / `destroySmokeFireDetector` |
| 安全帽 (双模型) | 未戴帽头部框 (label==3) 关联人 (重叠>5% 且框顶在人框上半) 且不与帽框 (label==2) 重叠 → 报警 | `createHelmetDetector(enginePaths)` / `detectHelmet` / `destroyHelmetDetector` |
| 跌倒 | 姿态耳/髋/踝三点几何判平躺 (θ<45°, 0.9<p<1.6, 关键点置信度 ≥0.2) → 报警 | `createFallDetector` / `detectFall` / `destroyFallDetector` |
| 工服 (双模型) | 未穿工服框 (label==1) 关联人 (任意重叠) 且完全在距边缘 ≥80px 区域 → 报警 | `createWorkclothesDetector(enginePaths)` / `detectWorkclothes` / `destroyWorkclothesDetector` |
| 抽烟 | 检测到烟框 (label==0) → 报警(不做人-烟关联) | `createSmokingDetector` / `detectSmoking` / `destroySmokingDetector` |
| 打电话 (双模型) | 手机中心点落在人框头部区域 (上部 1/3) → 报警 | `createPhoningDetector(enginePaths)` / `detectPhoning` / `destroyPhoningDetector` |

> 移植自 `HQ_AI_Flameout` 参考仓库,对照表见 [handoff.md](handoff.md)。多模型算法 `enginePaths` 槽号 = 模型序号(`[0]`=人员,`[1]`=安全帽/工服/手机);空列表/含空元素 = 创建失败。

## 人员跟踪 (v1.7.0 由 beta 预览转正)

| 算法 | 规则 | 接口 |
|---|---|---|
| 人员跟踪 | YOLO11 COCO 检测 (person=类别 0) + OC-SORT/ByteTrack → 跨帧带 ID 轨迹 | `createTracker` / `detectTracker` / `destroyTracker` |

```cpp
std::string err;
biz::AlgoHandle h = biz::createTracker("yolo11m.engine", 0.4f, 0, err);

// 必须按视频帧序、大致固定帧率调用 (跳帧导致轨迹漂移); roiMask 保留参数, 传空 Mat 即可
biz::AlarmResult r = biz::detectTracker(h, frame, cv::Mat());
// r.regionRects[i] = 轨迹框, r.trackIds[i] 平行对应 (含丢失轨迹, box 为预测框), r.alarm = 有存活轨迹
// regionConfs/regionLabels 与 regionRects 平行 (label = "person")

biz::destroyTracker(h);
```

## 接口示例

```cpp
#include "biz_algo/biz_algo.h"

std::string err;
biz::AlgoHandle h = biz::createIntrusionDetector("yolov8n.engine", 0.5f, 0, err);
if (!h) { /* err 带原因 */ }

biz::AlarmResult r = biz::detectIntrusion(h, frame, roiMask);   // r.alarm / r.regionRects
biz::destroyIntrusionDetector(h);
```

**通用约定**:`enginePath` 为空 = 创建失败;`roiMask` 为 CV_8UC1(非零 = 允许,空 Mat = 全图,尺寸不符自动缩放);创建失败返回 `nullptr`;**同一句柄单线程调用**;热更新(参数变更)期间不调用检测。

## 构建与测试

```bash
xmake f -m release && xmake build    # 编译
& "build\windows\x64\release\test_biz_algo.exe"   # 测试: 从项目根手动跑 (勿用 xmake run)
xmake pack                           # 打包 zip → build/xpack/interface_algo/
```

测试程序读 `config/tests.json` 配置驱动跑用例(数据源缺失 SKIP 不 FAIL),字段:`enginePaths`(空=SKIP)、`source{type: image_dir|video, path}`、`mask.points` 两点矩形、`expectAlarm`。数据放 `data/test/`。

## 运行日志

- exe 目录 `biz.log`;级别 `BIZ_LOG_LEVEL = DEBUG|INFO|WARN|ERROR`(默认 INFO);>100ms 自动 warn;失败原因同步进返回的 `msg`

## 依赖与平台

- 依赖清单见 [AGENTS.md](AGENTS.md);跨 Windows/Linux/macOS(见 handoff.md ADR-9),Linux/macOS 需设置:

```bash
export OPENCV_DIR=/path/to/opencv          # 期望布局: include/ lib/
export INTERFACE_AI_DIR=/path/to/Interface_AI
```

## 跟踪模块

`src/tracker/` 跨帧多目标跟踪 (OC-SORT + ByteTrack, 内部模块不导出);对外经 `createTracker` 三函数暴露 (v1.7.0 转正, 见上节, ADR-14/15)。测试 `test/test_tracker.cpp` 走正式接口端到端 (`data/test/people_walking.mp4` 真实视频, ID 连续性断言 + `test/output/beta_track_*.jpg` 留档; 数据缺失 SKIP)。