csair_visual_project/API_Docs/围界入侵检测接口文档.md

# 围界入侵检测接口文档

## 一、接口概述

本接口用于对视频文件或 RTSP 流进行围界入侵检测，可指定检测的时间范围。通过输入摄像头 ID 来关联特定的监控设备，同时提供入侵方向、风险区域延长等信息，还设有预留的`info`字段用于传递额外的信息，如模型参数等。

## 二、接口信息

### 1. 接口地址

`http://{ip:port}/perimeter_intrusion_detection`

### 2. 请求方法

`POST`

### 3. 请求头

```
Content-Type: application/json
```

## 三、请求参数

| 参数名                | 类型    | 是否必填 | 描述                                                         |
| --------------------- | ------- | -------- | ------------------------------------------------------------ |
| input\_type           | String  | 是       | 输入类型，取值为`mp4`或`rtsp`                                |
| input\_data           | String  | 是       | 若`input_type`为`mp4`，则为视频文件的本地路径或 URL；若为`rtsp`，则为 RTSP 流地址 |
| camera\_id            | String  | 是       | 摄像头的唯一标识符，用于关联特定的监控设备                   |
| start\_time           | String  | 是       | 检测起始时间，格式为`YYYY-MM-DD HH:MM:SS`                    |
| intrusion\_direction  | Array   | 是       | 入侵方向，0 代表`右至左`，1 代表`上至下`，2 代表`左至右`，3 代表`下至上` |
| risk\_area\_extension | Integer | 是       | 风险区域范围标尺值                                           |
| info                  | Object  | 否       | 预留字段，用于传递额外信息，如模型参数等，以字典形式存储     |

### 请求参数示例

```markdown
{
    "input_type": "rtsp",
    "input_data": "rtsp://example.com/stream",
    "camera_id": "CAM001",
    "start_time": "2024-10-01 08:00:00",
    "intrusion_direction": 1,
    "risk_area_extension": 100,
    "info": {
        "detection_threshold": 0.8
    }
}
```

## 四、响应参数

| 参数名              | 类型    | 描述                                                         |
| ------------------- | ------- | ------------------------------------------------------------ |
| status              | Integer | 响应状态码，200 表示成功，其他表示失败                       |
| message             | String  | 状态描述信息                                                 |
| is_intrusion        | String  | 是否存在围界入侵，取值为true或false                          |
| intrusion_timestamp | String  | 入侵发生的时间戳，格式为YYYY-MM-DD HH:MM:SS。当is_intrusion为false时，该字段可不填 |
| request_id          | String  | 当前请求的唯一标识符，用于与历史请求对齐                     |
| result_file_path    | String  | 检测结果落盘的文件路径，用于对齐落盘文件                     |

### 响应参数示例

```markdown
{
    "code": 200,
    "res":{
    	"message": "发起检测成功",
    }
}
```



## 五、错误处理

| 状态码 | 描述                      |
| --- | ----------------------- |
| 400 | 输入参数错误，如参数缺失、格式不正确等     |
| 404 | 未找到指定的视频文件或无法连接到 RTSP 流 |
| 500 | 服务器内部错误，如模型加载失败、计算资源不足等 |

### 错误响应示例

```markdown
{
    "status": 400,
    "message": "输入参数错误：intrusion_direction应输入0、1、2、3中的一个整数",
}
```

## 六、结果写入

存在入侵情况

```markdown
{
    "code": 200,
    "res": {
    	"message": "读取结果成功",
    	"data": {
            "is_intrusion": true,
            "intrusion_timestamp": "2024-01-01 10:02:30"
            "request_id": "123456789",
            "result_file_path": "/path/to/result/file.json"
    	}
    } 
}
```

不存在入侵情况

```markdown
{
    "code": 200,
    "res": {
    	"message": "读取结果成功",
    	"data": {
            "is_intrusion": false,
            "request_id": "123456789",
            "result_file_path": "/path/to/result/file.json"
    	}
    } 
}
```