670 lines
18 KiB
Markdown
670 lines
18 KiB
Markdown
# API 参考文档
|
||
|
||
## 配置参数
|
||
|
||
### RTSP 配置
|
||
RTSP 相关配置位于配置文件的 `rtsp` 部分：
|
||
|
||
```yaml
|
||
rtsp:
|
||
url: "rtsp://example/stream" # RTSP 流地址
|
||
buffer_size: 30 # 缓冲区大小，影响延迟和流畅度
|
||
max_retry_count: 3 # 最大重连次数
|
||
retry_interval_ms: 1000 # 重连间隔（毫秒）
|
||
frame_timeout_ms: 5000 # 读取帧超时时间（毫秒）
|
||
target_fps: 30.0 # 目标帧率，用于控制读取速度
|
||
```
|
||
|
||
#### 参数说明
|
||
- `url`: RTSP 流地址，必须是有效的 RTSP URL
|
||
- `buffer_size`:
|
||
- 类型：整数
|
||
- 默认值：30
|
||
- 说明：设置 RTSP 缓冲区大小，较大的值会增加延迟但提高流畅度，较小的值会降低延迟但可能造成卡顿
|
||
|
||
- `max_retry_count`:
|
||
- 类型：整数
|
||
- 默认值：3
|
||
- 说明：连接断开后的最大重试次数，超过此次数将停止重连
|
||
|
||
- `retry_interval_ms`:
|
||
- 类型：整数
|
||
- 默认值：1000
|
||
- 说明：重连尝试之间的间隔时间（毫秒），避免频繁重连
|
||
|
||
- `frame_timeout_ms`:
|
||
- 类型：整数
|
||
- 默认值：5000
|
||
- 说明：读取单帧的超时时间，超过此时间将视为读取失败
|
||
|
||
- `target_fps`:
|
||
- 类型：浮点数
|
||
- 默认值：30.0
|
||
- 说明：目标帧率，用于控制读取速度，设置为 0 则不限制帧率
|
||
|
||
### YOLO 模型配置
|
||
YOLO 模型相关配置位于配置文件的 `inference.model` 部分：
|
||
|
||
```yaml
|
||
inference:
|
||
model:
|
||
onnx_path: "/app/models/yolov8n.onnx" # ONNX模型路径
|
||
engine_path: "/app/models/yolov8n.engine" # TensorRT引擎路径
|
||
input_shape: [3, 640, 640] # YOLOv8n的输入尺寸
|
||
precision: "FP16" # FP32/FP16/INT8
|
||
version: "yolov8" # 可选：YOLO版本信息
|
||
labels: ["person", "car", "truck"] # 可选：模型标签列表
|
||
threshold:
|
||
conf: 0.5 # 置信度阈值
|
||
nms: 0.45 # NMS阈值
|
||
gpu_id: 0 # GPU设备ID
|
||
```
|
||
|
||
#### 参数说明
|
||
- `onnx_path`: ONNX模型文件路径，必须指定
|
||
- `engine_path`: TensorRT引擎文件路径，必须指定
|
||
- `input_shape`:
|
||
- 类型：整数数组 [channels, height, width]
|
||
- 默认值：[3, 640, 640]
|
||
- 说明：模型输入尺寸，必须与模型定义匹配
|
||
|
||
- `precision`:
|
||
- 类型：字符串
|
||
- 默认值："FP16"
|
||
- 可选值：["FP32", "FP16", "INT8"]
|
||
- 说明：模型精度模式，影响推理速度和精度
|
||
|
||
- `version`:
|
||
- 类型：字符串
|
||
- 默认值：空
|
||
- 可选值：任意字符串
|
||
- 说明：YOLO模型版本信息，用于记录和管理
|
||
|
||
- `labels`:
|
||
- 类型：字符串数组
|
||
- 默认值：空
|
||
- 说明：模型支持的标签列表，按class_id顺序排列
|
||
|
||
- `threshold.conf`:
|
||
- 类型：浮点数
|
||
- 默认值：0.5
|
||
- 范围：[0.0, 1.0]
|
||
- 说明：检测置信度阈值，低于此值的检测框会被过滤
|
||
|
||
- `threshold.nms`:
|
||
- 类型：浮点数
|
||
- 默认值：0.45
|
||
- 范围：[0.0, 1.0]
|
||
- 说明：非极大值抑制阈值，用于过滤重叠框
|
||
|
||
- `gpu_id`:
|
||
- 类型：整数
|
||
- 默认值：0
|
||
- 说明：使用的GPU设备ID
|
||
|
||
## 类说明
|
||
|
||
### RtspReader
|
||
RTSP 流读取器，用于从 RTSP 流中读取视频帧。
|
||
|
||
#### 主要功能
|
||
- 自动重连机制
|
||
- 帧率控制
|
||
- 超时处理
|
||
- 支持配置缓冲区大小
|
||
|
||
#### 示例用法
|
||
```cpp
|
||
// 创建配置
|
||
RtspReader::Config config;
|
||
config.buffer_size = 30;
|
||
config.max_retry_count = 3;
|
||
config.retry_interval_ms = 1000;
|
||
config.frame_timeout_ms = 5000;
|
||
config.target_fps = 30.0f;
|
||
|
||
// 创建读取器
|
||
RtspReader reader(config);
|
||
|
||
// 连接到 RTSP 流
|
||
if (reader.connect("rtsp://example/stream")) {
|
||
cv::Mat frame;
|
||
while (reader.read(frame)) {
|
||
// 处理帧
|
||
}
|
||
}
|
||
```
|
||
|
||
## 1. 输入模块 API
|
||
|
||
### 1.1 InputManager
|
||
|
||
输入管理器，负责管理多路输入源和输出目标映射。
|
||
|
||
#### 类定义
|
||
|
||
```cpp
|
||
class InputManager {
|
||
public:
|
||
InputManager();
|
||
~InputManager();
|
||
|
||
// 禁用拷贝
|
||
InputManager(const InputManager&) = delete;
|
||
InputManager& operator=(const InputManager&) = delete;
|
||
|
||
// 添加输入源
|
||
bool addSource(const std::string& name, const InputConfig& config);
|
||
|
||
// 获取下一帧
|
||
bool getNextFrames(std::vector<FramePtr>& frames);
|
||
|
||
// 获取输入源状态
|
||
SourceStatus getSourceStatus(const std::string& name);
|
||
|
||
// 输出目标映射相关接口
|
||
bool setOutputTargets(const std::string& source_name,
|
||
const std::vector<std::string>& target_names);
|
||
bool getOutputTargets(const std::string& source_name,
|
||
std::vector<std::string>& target_names) const;
|
||
bool hasOutputTargets(const std::string& source_name) const;
|
||
bool clearOutputTargets(const std::string& source_name);
|
||
std::vector<std::string> getAllSourceNames() const;
|
||
};
|
||
```
|
||
|
||
#### 配置结构
|
||
|
||
```cpp
|
||
struct InputConfig {
|
||
std::string type; // "video" 或 "rtsp"
|
||
std::string url; // 输入源地址
|
||
int buffer_size; // 缓冲区大小
|
||
std::vector<std::string> output_targets; // 输出目标列表
|
||
};
|
||
```
|
||
|
||
#### 输出目标映射接口说明
|
||
|
||
1. `setOutputTargets`
|
||
- 功能：设置输入源的输出目标列表
|
||
- 参数：
|
||
- `source_name`: 输入源名称
|
||
- `target_names`: 输出目标名称列表
|
||
- 返回：操作是否成功
|
||
- 说明：
|
||
- 会替换现有的输出目标列表
|
||
- 如果输入源不存在，返回 false
|
||
- 空列表表示清除所有输出目标
|
||
|
||
2. `getOutputTargets`
|
||
- 功能：获取输入源的输出目标列表
|
||
- 参数：
|
||
- `source_name`: 输入源名称
|
||
- `target_names`: 输出参数，存储目标名称列表
|
||
- 返回：操作是否成功
|
||
- 说明：
|
||
- 如果输入源不存在，返回 false
|
||
- 如果没有输出目标，vector 为空
|
||
|
||
3. `hasOutputTargets`
|
||
- 功能：检查输入源是否有输出目标
|
||
- 参数：
|
||
- `source_name`: 输入源名称
|
||
- 返回：是否有输出目标
|
||
- 说明：
|
||
- 如果输入源不存在，返回 false
|
||
- 如果输出目标列表为空，返回 false
|
||
|
||
4. `clearOutputTargets`
|
||
- 功能：清除输入源的所有输出目标
|
||
- 参数：
|
||
- `source_name`: 输入源名称
|
||
- 返回：操作是否成功
|
||
- 说明：
|
||
- 如果输入源不存在，返回 false
|
||
- 清除后可以重新设置输出目标
|
||
|
||
5. `getAllSourceNames`
|
||
- 功能：获取所有输入源的名称
|
||
- 返回：输入源名称列表
|
||
- 说明：
|
||
- 返回当前所有已添加的输入源名称
|
||
- 列表顺序不保证
|
||
|
||
#### 使用示例
|
||
|
||
```cpp
|
||
// 创建输入管理器
|
||
InputManager input_manager;
|
||
|
||
// 添加输入源
|
||
InputConfig config;
|
||
config.type = "rtsp";
|
||
config.url = "rtsp://example/stream";
|
||
config.buffer_size = 30;
|
||
config.output_targets = {"output1", "stream1"}; // 初始输出目标
|
||
input_manager.addSource("camera1", config);
|
||
|
||
// 修改输出目标
|
||
std::vector<std::string> new_targets = {"output1"};
|
||
input_manager.setOutputTargets("camera1", new_targets);
|
||
|
||
// 获取输出目标
|
||
std::vector<std::string> targets;
|
||
if (input_manager.getOutputTargets("camera1", targets)) {
|
||
for (const auto& target : targets) {
|
||
// 处理每个输出目标...
|
||
}
|
||
}
|
||
|
||
// 检查输出目标状态
|
||
if (input_manager.hasOutputTargets("camera1")) {
|
||
// 处理有输出目标的情况...
|
||
} else {
|
||
// 处理没有输出目标的情况...
|
||
}
|
||
|
||
// 清除输出目标
|
||
input_manager.clearOutputTargets("camera1");
|
||
|
||
// 获取所有输入源
|
||
auto sources = input_manager.getAllSourceNames();
|
||
for (const auto& source : sources) {
|
||
// 处理每个输入源...
|
||
}
|
||
```
|
||
|
||
#### 错误处理
|
||
|
||
1. 输入源错误
|
||
- 源不存在：相关操作返回 false
|
||
- 源已存在：addSource 返回 false
|
||
- 源状态异常：通过 getSourceStatus 获取详细信息
|
||
|
||
2. 输出目标错误
|
||
- 目标不存在：setOutputTargets 返回 false
|
||
- 目标列表为空：视为有效操作
|
||
- 重复目标：自动去重
|
||
|
||
3. 线程安全
|
||
- 所有公共接口都是线程安全的
|
||
- 支持多线程并发访问
|
||
- 使用读写锁保护数据
|
||
|
||
#### 性能考虑
|
||
|
||
1. 数据结构
|
||
- 使用哈希表存储映射关系
|
||
- 优化字符串比较和存储
|
||
- 最小化内存占用
|
||
|
||
2. 并发访问
|
||
- 读写锁分离
|
||
- 细粒度锁定
|
||
- 避免长时间持锁
|
||
|
||
3. 资源管理
|
||
- 智能指针管理资源
|
||
- 及时释放不用的资源
|
||
- 缓存常用数据
|
||
|
||
### 1.2 RtspReader
|
||
```cpp
|
||
class RtspReader {
|
||
public:
|
||
// 连接RTSP流
|
||
bool connect(const std::string& url);
|
||
|
||
// 读取帧
|
||
bool read(FramePtr& frame);
|
||
};
|
||
```
|
||
|
||
## 2. 推理模块 API
|
||
|
||
### 2.1 TrtInference
|
||
```cpp
|
||
class TrtInference {
|
||
public:
|
||
// 加载模型
|
||
bool loadEngine(const std::string& enginePath);
|
||
|
||
// 批量推理
|
||
bool infer(const std::vector<FramePtr>& inputs, std::vector<DetectionResult>& results);
|
||
};
|
||
```
|
||
|
||
## 3. 渲染模块 API
|
||
|
||
### 3.1 FrameDrawer
|
||
```cpp
|
||
class FrameDrawer {
|
||
public:
|
||
// 绘制检测结果
|
||
void drawDetections(FramePtr& frame, const DetectionResult& result);
|
||
|
||
// 添加文本信息
|
||
void addText(FramePtr& frame, const std::string& text, const Point& pos);
|
||
};
|
||
```
|
||
|
||
## 4. 输出模块 API
|
||
|
||
### 4.1 OutputManager
|
||
|
||
输出管理器，负责管理多路输出目标和输入源映射。
|
||
|
||
#### 类定义
|
||
|
||
```cpp
|
||
class OutputManager {
|
||
public:
|
||
OutputManager();
|
||
~OutputManager();
|
||
|
||
// 禁用拷贝
|
||
OutputManager(const OutputManager&) = delete;
|
||
OutputManager& operator=(const OutputManager&) = delete;
|
||
|
||
// 添加输出目标
|
||
bool addTarget(const OutputTargetConfig& config);
|
||
|
||
// 写入帧
|
||
bool writeFrames(const cv::Mat& frame);
|
||
bool writeFrames(const std::string& source_name, const cv::Mat& frame);
|
||
|
||
// 获取目标状态
|
||
bool getTargetStatus(const std::string& name, std::string& error_msg) const;
|
||
|
||
// 获取目标数量
|
||
size_t getTargetCount() const;
|
||
|
||
// 获取所有目标名称
|
||
std::vector<std::string> getTargetNames() const;
|
||
|
||
// 移除目标
|
||
bool removeTarget(const std::string& name);
|
||
|
||
// 清理所有资源
|
||
void cleanup();
|
||
|
||
// 输入输出映射相关接口
|
||
bool addSourceTargetMapping(const std::string& source_name,
|
||
const std::vector<std::string>& target_names);
|
||
bool removeSourceMapping(const std::string& source_name);
|
||
bool getSourceTargets(const std::string& source_name,
|
||
std::vector<std::string>& target_names) const;
|
||
bool updateSourceTargets(const std::string& source_name,
|
||
const std::vector<std::string>& target_names);
|
||
bool hasSourceMapping(const std::string& source_name) const;
|
||
bool isTargetMapped(const std::string& target_name) const;
|
||
std::vector<std::string> getMappedSources(const std::string& target_name) const;
|
||
};
|
||
```
|
||
|
||
#### 配置结构
|
||
|
||
```cpp
|
||
struct OutputTargetConfig {
|
||
std::string type; // "video" 或 "rtsp"
|
||
std::string name; // 目标名称
|
||
std::string path; // 输出路径
|
||
int fps; // 输出帧率
|
||
std::string codec; // 编码器类型
|
||
int bitrate; // 码率
|
||
};
|
||
```
|
||
|
||
#### 输入输出映射接口说明
|
||
|
||
1. `addSourceTargetMapping`
|
||
- 功能：添加输入源到输出目标的映射
|
||
- 参数：
|
||
- `source_name`: 输入源名称
|
||
- `target_names`: 输出目标名称列表
|
||
- 返回：操作是否成功
|
||
- 说明：
|
||
- 如果输入源已存在映射，会更新为新的映射关系
|
||
- 所有目标必须已经通过 `addTarget` 添加
|
||
- 支持一对多映射
|
||
|
||
2. `removeSourceMapping`
|
||
- 功能：移除输入源的所有映射关系
|
||
- 参数：
|
||
- `source_name`: 输入源名称
|
||
- 返回：操作是否成功
|
||
- 说明：
|
||
- 不会影响输出目标的存在
|
||
- 如果输入源不存在映射，返回 false
|
||
|
||
3. `getSourceTargets`
|
||
- 功能：获取输入源映射的所有输出目标
|
||
- 参数：
|
||
- `source_name`: 输入源名称
|
||
- `target_names`: 输出参数，存储目标名称列表
|
||
- 返回：操作是否成功
|
||
- 说明：
|
||
- 如果输入源不存在映射，返回 false
|
||
- 如果输入源存在但没有映射目标，vector 为空
|
||
|
||
4. `updateSourceTargets`
|
||
- 功能：更新输入源的输出目标映射
|
||
- 参数：
|
||
- `source_name`: 输入源名称
|
||
- `target_names`: 新的输出目标名称列表
|
||
- 返回：操作是否成功
|
||
- 说明：
|
||
- 会完全替换现有的映射关系
|
||
- 所有目标必须已经存在
|
||
- 如果输入源不存在，会创建新的映射
|
||
|
||
5. `hasSourceMapping`
|
||
- 功能：检查输入源是否有映射关系
|
||
- 参数：
|
||
- `source_name`: 输入源名称
|
||
- 返回：是否存在映射
|
||
|
||
6. `isTargetMapped`
|
||
- 功能：检查输出目标是否被映射
|
||
- 参数：
|
||
- `target_name`: 输出目标名称
|
||
- 返回：是否被映射
|
||
|
||
7. `getMappedSources`
|
||
- 功能：获取映射到指定输出目标的所有输入源
|
||
- 参数：
|
||
- `target_name`: 输出目标名称
|
||
- 返回：输入源名称列表
|
||
- 说明：
|
||
- 如果目标不存在，返回空列表
|
||
- 支持查询多对一映射关系
|
||
|
||
#### 使用示例
|
||
|
||
```cpp
|
||
// 创建输出管理器
|
||
OutputManager output_manager;
|
||
|
||
// 添加输出目标
|
||
OutputTargetConfig video_config;
|
||
video_config.type = "video";
|
||
video_config.name = "output1";
|
||
video_config.path = "/output/result1.mp4";
|
||
output_manager.addTarget(video_config);
|
||
|
||
OutputTargetConfig rtsp_config;
|
||
rtsp_config.type = "rtsp";
|
||
rtsp_config.name = "stream1";
|
||
rtsp_config.path = "rtsp://localhost:8554/live/stream1";
|
||
output_manager.addTarget(rtsp_config);
|
||
|
||
// 配置输入源映射
|
||
std::vector<std::string> targets = {"output1", "stream1"};
|
||
output_manager.addSourceTargetMapping("camera1", targets);
|
||
|
||
// 写入帧
|
||
cv::Mat frame = ...;
|
||
output_manager.writeFrames("camera1", frame);
|
||
|
||
// 更新映射关系
|
||
std::vector<std::string> new_targets = {"output1"};
|
||
output_manager.updateSourceTargets("camera1", new_targets);
|
||
|
||
// 检查映射状态
|
||
if (output_manager.hasSourceMapping("camera1")) {
|
||
std::vector<std::string> mapped_targets;
|
||
output_manager.getSourceTargets("camera1", mapped_targets);
|
||
// 处理映射目标...
|
||
}
|
||
|
||
// 获取反向映射
|
||
std::vector<std::string> sources = output_manager.getMappedSources("output1");
|
||
for (const auto& source : sources) {
|
||
// 处理映射源...
|
||
}
|
||
|
||
// 清理资源
|
||
output_manager.cleanup();
|
||
```
|
||
|
||
#### 错误处理
|
||
|
||
1. 映射错误
|
||
- 目标不存在：添加映射时会返回 false
|
||
- 源不存在：会创建新的映射关系
|
||
- 重复映射：会更新现有映射
|
||
|
||
2. 资源管理
|
||
- 移除目标时会自动清理相关映射
|
||
- 清理时会释放所有资源
|
||
- 异常安全：保证资源正确释放
|
||
|
||
3. 线程安全
|
||
- 所有公共接口都是线程安全的
|
||
- 支持多线程并发访问
|
||
- 内部使用互斥锁保护
|
||
|
||
#### 性能考虑
|
||
|
||
1. 映射查找
|
||
- 使用哈希表实现 O(1) 查找
|
||
- 缓存常用映射关系
|
||
- 优化内存使用
|
||
|
||
2. 并发处理
|
||
- 读写锁分离
|
||
- 最小化锁粒度
|
||
- 避免锁竞争
|
||
|
||
3. 资源管理
|
||
- 智能指针管理资源
|
||
- 内存池复用
|
||
- 延迟初始化
|
||
|
||
### 方法说明
|
||
|
||
#### 构造函数和析构函数
|
||
|
||
- `OutputManager()`: 创建输出管理器实例
|
||
- `~OutputManager()`: 析构时自动清理所有资源
|
||
|
||
#### 目标管理
|
||
|
||
- `bool addTarget(const OutputTargetConfig& config)`
|
||
- 添加新的输出目标
|
||
- 参数：输出目标配置
|
||
- 返回：添加是否成功
|
||
- 线程安全：是
|
||
|
||
- `bool removeTarget(const std::string& name)`
|
||
- 移除指定的输出目标
|
||
- 参数：目标名称
|
||
- 返回：移除是否成功
|
||
- 线程安全：是
|
||
|
||
#### 帧写入
|
||
|
||
- `bool writeFrames(const cv::Mat& frame)`
|
||
- 将帧写入所有输出目标
|
||
- 参数：要写入的帧
|
||
- 返回：写入是否成功
|
||
- 线程安全：是
|
||
|
||
- `bool writeFrames(const std::string& source_name, const cv::Mat& frame)`
|
||
- 将帧写入指定输入源映射的输出目标
|
||
- 参数：
|
||
- source_name: 输入源名称
|
||
- frame: 要写入的帧
|
||
- 返回：写入是否成功
|
||
- 线程安全：是
|
||
|
||
#### 状态查询
|
||
|
||
- `bool getTargetStatus(const std::string& name, std::string& error_msg) const`
|
||
- 获取指定目标的状态
|
||
- 参数：
|
||
- name: 目标名称
|
||
- error_msg: 错误信息输出
|
||
- 返回：目标是否正常
|
||
- 线程安全：是
|
||
|
||
- `size_t getTargetCount() const`
|
||
- 获取当前输出目标数量
|
||
- 返回：目标数量
|
||
- 线程安全：是
|
||
|
||
- `std::vector<std::string> getTargetNames() const`
|
||
- 获取所有输出目标的名称
|
||
- 返回：目标名称列表
|
||
- 线程安全：是
|
||
|
||
#### 映射管理
|
||
|
||
- `bool addSourceTargetMapping(const std::string& source_name, const std::vector<std::string>& target_names)`
|
||
- 添加输入源到输出目标的映射
|
||
- 参数：
|
||
- source_name: 输入源名称
|
||
- target_names: 输出目标名称列表
|
||
- 返回：添加是否成功
|
||
- 线程安全：是
|
||
|
||
- `bool removeSourceMapping(const std::string& source_name)`
|
||
- 移除输入源的映射关系
|
||
- 参数：输入源名称
|
||
- 返回：移除是否成功
|
||
- 线程安全：是
|
||
|
||
#### 资源管理
|
||
|
||
- `void cleanup()`
|
||
- 清理所有资源
|
||
- 线程安全：是
|
||
|
||
### 错误处理
|
||
|
||
所有可能失败的操作都返回bool值表示成功或失败。对于需要详细错误信息的场景，可以通过`getTargetStatus`获取具体的错误信息。
|
||
|
||
### 线程安全性
|
||
|
||
所有公共接口都是线程安全的，内部使用互斥锁保护共享资源。支持多线程并发写入和状态查询。
|
||
|
||
### 使用示例
|
||
|
||
参见README.md中的使用示例部分。
|
||
|
||
## 5. 配置模块 API
|
||
|
||
### 5.1 ConfigParser
|
||
```cpp
|
||
class ConfigParser {
|
||
public:
|
||
// 加载配置文件
|
||
bool load(const std::string& configPath);
|
||
|
||
// 获取配置项
|
||
template<typename T>
|
||
T getValue(const std::string& key, const T& defaultValue);
|
||
};
|
||
```
|