Smart Vision SDK for C++

TIP

使用Smart Vision SDK C++ API编译，需要引入Smart Vision SDK 头文件:

#include "smart_vision.hpp"

链接时需要指定Smart Vision SDK so库，例如：

$g++ example.cpp -o demo -lsmartvision -L/usr/local/lib/

Smart Vision SDK 头文件地址： /usr/local/include/aidlux/smartvision/smart_vision.hpp

Smart Vision SDK 库文件地址： /usr/local/lib/libsmartvision.so

C++ API预览汇总

Camera 公共函数接口汇总

公共函数（public function）	描述（Description）
int8_t open(GetImageCB cb)	以无参模式打开相机
int8_t open(const DeviceParam & dev_param, GetImageCB cb)	以有参模式打开相机
void start_capture(void)	打开流开关
void stop_capture(void)	关闭流开关
void close()	关闭相机
void set_log_level(SVLogLevel log_level)	设置日志级别
void set_log_destination(const char* destinationPath, bool also_to_stderr)	设置日志文件名及路径
typedef std::function<int8_t(const Image &, const SVSdkMemfdInfo &)> GetImageCB	作为open()函数的入参。此函数由使用者自定义。接口仅提供类型定义来规范回调函数的定义。
bool is_bgr(const cv::Mat &image)	判断输入的 OpenCV 图像是否为BGR格式。
int start_camera_with_parameter(GetImageCB cb, const char *conf_file, int8_t preview, int8_t idx)	打开摄像头，有参形式。
int start_camera_without_parameter(GetImageCB cb, int8_t preview, int8_t idx)	打开摄像头，无参形式。
int start_camera(int8_t idx)	启动指定索引的摄像头进行预览。
int start_camera(const char* json_param, int8_t idx)	通过配置参数启动指定索引的摄像头。
int8_t configure_camera_parameter(const char *conf_file, int8_t activate, int8_t idx = 0)	激活启动摄像头配置参数。
int8_t configure_camera_parameter(int8_t activate, const char *json_param, int8_t idx = 0)	激活启动摄像头json配置参数。
int8_t configure_camera_parameter_io(GetImageCB cb, const char* json_param, int8_t idx)	根据配置差异决定是否需要重启摄像头流。
int8_t configure_camera(const char *file_path, bool set_property, bool validation)	根据参数决定是否立即应用设置。
int8_t close_camera(int8_t idx = 0)	关闭指定索引摄像头。
int8_t preview_set(int8_t enable, int8_t idx)	开启或关闭指定摄像头的预览功能。
int8_t set_off_mode()	关闭信号输出配置。
int8_t get_tcp_setting(int cam_id, TcpConfig& tcp_setting)	获取TCP的设置。
int8_t tcp_send_signal(int cam_id, std::string message)	TCP发送信号。
int8_t tcp_send(std::string message, TcpConfig& tcp_setting)	发送TCP字符串消息。
int8_t io_send(std::string io_str, std::string io_control_file)	指定字符串写入到特定文件。
int8_t send_signal_on(int device_id)	发送up信号到指定设备（比如do1，do2， do3），keeptime从配置读。
int8_t send_signal_on(int device_id, int keeptime)	发送up信号到指定设备（比如do1，do2， do3），接口传入keeptime。
int8_t send_signal_off(int device_id)	发送clear信号到指定设备（比如do1，do2， do3）。
string get_camera_info(int8_t idx = 0)	根据摄像头索引 idx 获取对应配置文件路径，读取并解析 JSON 格式的摄像头配置信息。
string get_camera_default_setting(int8_t idx = 0)	通过摄像头索引 idx 加载默认配置，获取完整配置字符串并同步到系统单例。
string get_sensor_model_info(int idx)	获取传感器模型信息。
vector<std::string> get_all_cam_ids(bool disable_cache = false)	根据是否禁用缓存来决定是从本地配置读取还是实时探测所有摄像头的型号名称。
vector<int> get_all_cam_index()	获取所有的index。
unordered_map<int, std::string> get_all_cameras(bool disable_cache = false)	调用底层探测逻辑获取所有摄像头信息。
int get_idx_by_loc_id(int loc_id)	根据摄像头的物理位置 ID（loc_id）查找其对应的逻辑索引(cam_id或idx)。
int get_loc_id_by_idx(int idx)	根据摄像头的逻辑索引（idx）反向查找其所在的物理位置 ID（loc_id）。
int get_cam_index(std::string cam_id)	通过相机名称查找其对应的逻辑索引。
string get_cam_id(int cam_index)	根据逻辑索引查找并返回对应的相机名称。
cv::Mat image_read(int8_t idx = 0)	安全地从指定摄像头读取当前预览帧（BGR格式）。
int8_t get_camera_status(int8_t idx = 0)	通过日志记录并返回指定索引摄像头的当前状态码。
void start_camera_capture(int idx = 0)	启动指定摄像头的图像捕获功能。
void stop_camera_capture(int idx = 0)	停止指定摄像头的图像捕获。
int get_dst_width(int8_t idx = 0)	获取指定摄像头输出图像的目标宽度。
int get_dst_height(int8_t idx = 0)	获取指定摄像头输出图像的目标高度。
int8_t notify_sve(SPhase phase_enum)	通过HTTP（POST）请求向本地 SVE 服务发送当前任务阶段通知。
int8_t save_result(const char *release_id, const char *release_version,const char *origin_file, const char *mask_file, const char *final_file, const char *additional = "")	将图像分析任务的结果文件路径及附加信息打包为 JSON 并上报至本地 SVE 服务。
cv::Mat get_cvimage(const Image &img, int idx = 0)	摄像头原始YUV格式的图像数据转换为 OpenCV 可用的BGR三通道矩阵。
void qmm_cleanup(int cam_id = 0)	发送特定格式的控制信号来停止指定或全部摄像头服务。
void qmm_cleanup_all()	发送特定格式的控制信号来停止指定或全部摄像头服务。
void qmm_cleanup_invalid()	清理状态异常的 qmm 进程。
int qmm_status(int idx = 0)	检查指定摄像头索引 idx 对应的服务进程是否存活,基于 Redis 心跳机制实现。
int start_record(int idx)	安全地启动摄像头视频录制，执行多项前置检查。
int get_record_status(int idx)	查询指定摄像头的视频录制状态。
MediaInfo stop_record(int idx)	停止摄像头的录制过程，并从内部状态中提取并填充录制结果元数据。
int set_bpp_binning(std::string cam_id, int binning_flag, int hb, int vb, int bpp_flag, int bpp)	指定摄像头的像素合并和位深。
void set_cfgname(const std::string &cfg_name_str)	设置设备参数类中的配置文件名。
bool isIPFormat(const char* str)	判断字符串是否为 IPv4 或（完整格式）IPv6 地址。
bool isFileExists(const std::string& filePath)	判断一个文件路径是否对应一个存在的文件（或目录）。
bool createNewSignalFile(const std::string& filePath)	创建一个新文件，如果文件已存在则删除并重新创建。
int get_fd_with_meta(int idx, AidluxSocketfdInfo &out_meta)	获取指定摄像头对应的文件描述符，并返回文件描述符数据。
int get_cvimage(Image &img, int idx, int max_timeout_ms)	从指定的索引中获取图像数据。
void disconnect(int idx)	断开指定索引的摄像头零拷贝连接。
SVSdkMemfdInfo get_camera_rt_info(int idx)	获取指定索引的摄像头实时信息。

结构体（struct）	成员变量名（public member variable）	类型（Type）	描述（Description）
DeviceParam	cfg_name	const char *	带路径的参数配置文件路径
	cfg_name_s	string	带路径的参数配置文件名
	dev_name	const char *	相机设备名称
	sn	const char *	相机 SN code
Image	data	const char *	指向存放数据的缓冲区的指针
	w	int	目标图片宽度
	h	int	目标图片高度
	c	int	目标图片的通道（通常为3）
	length	int	图片数据所占内存长度
	srcWidth	int	图片内部宽度，通常比最终宽度大
	srcHeight	int	图片内部高度
	memCopyStartIndex	int	指示缓冲区中数据的索引
	memCopyEndIndex	int	指示缓冲区中数据的结束索引
	planeOffset	int	YUV数据的偏移值
	srcYPlaneStride	int	YUV数据的宽
	srcSliceHeight	int	YUV数据的高
	bufferSize	int	缓冲区大小
	frame_number	int	帧号
	exposureTimeNs	int64_t	曝光时间，单位为纳秒
	isoValue	int64_t	感光度
TcpConfig	ip	const char *	IP地址
	port	uint16_t	端口号
SVSdkMemfdInfo	srcYPlaneStride	int	YUV数据的宽
	srcSliceHeight	int	YUV数据的高
	memCopyStartIndex	int	Start index值（注：Start index的值与End index相等）
	memCopyEndIndex	int	End index值
	planeOffset	int	YUV偏移值
	cam_id	int	相机的ID号
	exposureTime	int64_t	曝光时间
	sensitivity	int64_t	感光度
MediaInfo	duration	int	时间ms
	width	int	宽度
	height	int	高度
	frame_rate	float	帧率
	file_size	uint64_t	文件大小
	file_name	string	文件名

枚举（ENUM）	成员变量名（public member variable）	类型（Type）	描述（Description）
SVLogLevel	SINFO	uint8_t	日志级别SINFO
	SWARNING	uint8_t	日志级别SWARNING
	SERROR	uint8_t	日志级别SERROR
	SDEBUG	uint8_t	日志级别SDEBUG
	SOFF	uint8_t	日志级别SOFF
SignalType	OFF	uint8_t	关闭信号输出配置
	NG_SIGNAL	uint8_t	NG信号输出模式
	ALARM_SIGNAL	uint8_t	alarm信号输出模式
	OK_SIGNAL	uint8_t	ok信号输出模式
SignalMode	IO_MODE	uint8_t	IO模式
	TCP_MODE	uint8_t	TCP模式
	MODBUS_MODE	uint8_t	MODBUS模式
	UART_MODE	uint8_t	串口模式
CameraTriggerMode	INVALID_TRIGGER_MODE_ENUM0	uint8_t	无效触发模式
	INTERNAL_TRIGGER_MODE_ENUM1	uint8_t	内触发
	EXTERNAL_TRIGGER_MODE_ENUM2	uint8_t	外触发，外部硬件触发
	SOFTWARE_TRIGGER_MODE_ENUM3	uint8_t	软件触发

相机参考函数

TIP

本版本兼容了一代相机的打开相机函数open，启流函数start_capture，停流函数stop_capture，关闭相机函数close。

最新的函数参考如下： 有参模式打开相机函数参考start_camera_with_parameter。

无参模式打开相机函数参考start_camera_without_parameter。

开启流函数参考start_camera_capture。

关闭流函数参考stop_camera_capture。

关闭相机函数参考close_camera。

WARNING

如非特殊说明，所有的定义都属于名字空间Aidlux::SmartVision。可通过以下命令在代码中引入：

using namespace Aidlux::SmartVision;

无参模式打开相机

无参模式：使用默认的相机参数配置

API	int8_t open(GetImageCB cb)
描述	以无参模式打开相机。
参数	输入参数为回调函数。回调函数由客户自定义。关于回调函数请参考回调函数GetImageCB
返回值	0: 成功。-1: 失败。

举例如下（Camera为类Camera的实例化对象，下同）：

// 无参模式打开相机 
int8_t res = camera.open(my_get_img_cb);

有参模式打开相机

有参模式：使用自定义的参数配置详见DeviceParam

API	int8_t open(const DeviceParam & dev_param, GetImageCB cb)
描述	以有参模式打开相机。
参数	dev_param为结构体的实例化对象。 cb为回调函数。回调函数由客户自定义。关于回调函数请参考回调函数GetImageCB
返回值	0: 成功。-1: 失败。

举例如下：

// 有参模式打开相机
int8_t res = camera.open(dev_param, my_get_img_cb);

打开流开关

API	void start_capture(void)
描述	打开流开关
参数	无
返回值	无

举例如下：

// 打开流开关
camera.start_capture();

关闭流开关

API	void stop_capture(void)
描述	关闭流开关
参数	无
返回值	无

举例如下：

//关闭流开关
camera.stop_capture();

关闭相机开关

API	void close()
描述	关闭相机
参数	无
返回值	无

举例如下：

//关闭相机开关
camera.close();

结构体DeviceParam

定义带路径的参数配置文件名。该参数配置文件用于配置相机参数。因此本结构体仅用于有参模式打开相机。

成员变量名	类型	默认值	描述
cfg_name	const char*		带路径的参数配置文件路径
cfg_name_s	string		带路径的参数配置文件名
dev_name	const char*		相机设备名称
sn	const char*		相机SN code

结构体Image

定义图片数据相关信息，包括图片配置信息及指针变量。

成员变量名	类型	默认值	描述
data	const char*		指向存放数据的缓冲区的指针
w	int		目标图片宽度
h	int		目标图片高度
c	int		目标图片的通道（通常为3）
length	int		图片数据所占内存长度
srcWidth	int		图片内部宽度，通常比最终宽度大
srcHeight	int		图片内部高度
memCopyStartIndex	int		指示缓冲区中数据的索引
memCopyEndIndex	int		指示缓冲区中数据的结束索引
planeOffset	int		YUV数据的偏移值

结构体TcpConfig

定义TCP信号输出配置信息。

成员变量名	类型	默认值	描述
ip	const char*		IP地址
port	uint16_t		端口号

结构体SVSdkMemfdInfo

定义数据缓冲区信息。

成员变量名	类型	描述
srcYPlaneStride	int	YUV数据的宽
srcSliceHeight	int	YUV数据的高
memCopyStartIndex	int	Start index值（注：Start index的值与End index相等）
memCopyEndIndex	int	End index值
planeOffset	int	YUV偏移值
cam_id	int	相机的ID号
exposureTime	int64_t	相机曝光时间
sensitivity	int64_t	相机感光度

设置日志级别

API	void set_log_level(SVLogLevel log_level)
描述	设置日志级别。
参数	log_level为SVLogLevel类型的枚举，关于SVLogLevel请参考枚举SVLogLevel
返回值	无

举例如下：

//设置日志级别
Aidlux::SmartVision::set_log_level(SVLogLevel::SINFO);

设置日志文件名及路径

API	void set_log_destination(const char* destinationPath, bool also_to_stderr)
描述	设置日志文件名及路径
参数	destinationPath：带路径的日志文件名，默认值为"./aidclog_smart_vision_"。also_to_stderr：是否输出到终端，默认值为false
返回值	无

举例如下：

//设置日志文件名及路径
const char* log_path = "./aidclog_smart_vision_";
Aidlux::SmartVision::set_log_destination(log_path);

日志级别（枚举SVLogLevel）

成员变量名	类型	默认值	描述
SINFO	uint8_t	0	日志级别SINFO
SWARNING	uint8_t		日志级别SWARNING
SERROR	uint8_t		日志级别SERROR
SDEBUG	uint8_t		日志级别SDEBUG
SOFF	uint8_t		日志级别SOFF

回调函数

API	typedef std::function<int8_t(const Image &, const SVSdkMemfdInfo &)> GetImageCB
描述	作为open()函数的入参，用于获取相片资源。此函数由使用者自定义。接口仅提供类型定义来规范回调函数的定义。
参数	参数一是结构体Image 的实例化对象，数据由此传入。参数二是缓冲区结构体对象，存储包括缓冲区index、YUV数据宽高等
返回值	自定义

举例如下：

//回调函数定义
bool data_sign = false;
cv::Mat SDKframe;  
int8_t my_get_img_cb(const Aidlux::SmartVision::Image & cap_img, const SVSdkMemfdInfo &index)
{
    t_count++;
    cout << "Image - w: " << cap_img.w << ", h: " << cap_img.h << "Image - w: " << cap_img.srcWidth << ", h: " << cap_img.srcHeight << ", length: " << cap_img.length << ", rt fps: " << cap_img.rt_fps << ", ma fps: " << cap_img.ma_fps << endl;
    // 添加处理程序，当data_sign为真才处理
    if(data_sign){
        data_sign1 = false;
    }        

    return 0;        
}

判断图像是否为BGR格式

API	bool is_bgr(const cv::Mat &image)
描述	判断输入的OpenCV图像是否为BGR格式。
参数	&image：输入图像的常量引用
返回值	true：图像有 3 个通道。false：图像不是 3 个通道

举例如下：

 Mat image = imread("test.jpg");
bool result = is_bgr(image);

有参形式打开摄像头

有参形式：自定义相机配置文件

API	int start_camera_with_parameter(GetImageCB cb, const char *conf_file, int8_t preview, int8_t idx)
描述	自定义相机配置的形式打开摄像头。
参数	cb: 图像获取回调函数，用于处理摄像头捕获的图像回调函数GetImageCB。conf_file: 包含摄像头设置的配置文件路径。preview: 标识是否开启预览模式。idx:摄像头索引。
返回值	0：成功。-1： 失败。

举例如下：

int idx = 0;
int8_t my_get_img_cb(const Aidlux::SmartVision::Image & cap_img, const SVSdkMemfdInfo &index)
{
    t_count++;
    cout << "Image - w: " << cap_img.w << ", h: " << cap_img.h << "Image - w: " << cap_img.srcWidth << ", h: " << cap_img.srcHeight << ", length: " << cap_img.length << ", rt fps: " << cap_img.rt_fps << ", ma fps: " << cap_img.ma_fps << endl;
    // 添加处理程序，当data_sign为真才处理
    if(data_sign){
        data_sign1 = false;
    }        
    return 0;        
}

const char* conf_file = "/home/config/camera.json";
int result = start_camera_with_parameter(my_get_img_cb,conf_file, 1, idx);

无参形式打开摄像头

无参形式：使用默认配置

API	int start_camera_without_parameter(GetImageCB cb, int8_t preview, int8_t idx)
描述	无参的形式打开摄像头。
参数	cb: 图像获取回调函数，用于处理摄像头捕获的图像回调函数GetImageCB。preview: 标识是否开启预览模式。idx:摄像头索引。
返回值	0：成功。-1： 失败。

举例如下：

int idx = 0;
int8_t my_get_img_cb(const Aidlux::SmartVision::Image & cap_img, const SVSdkMemfdInfo &index)
{
    t_count++;
    cout << "Image - w: " << cap_img.w << ", h: " << cap_img.h << "Image - w: " << cap_img.srcWidth << ", h: " << cap_img.srcHeight << ", length: " << cap_img.length << ", rt fps: " << cap_img.rt_fps << ", ma fps: " << cap_img.ma_fps << endl;
    // 添加处理程序，当data_sign为真才处理
    if(data_sign){
        data_sign1 = false;
    }        
    return 0;        
}
int result = start_camera_with_parameter(myImageCmy_get_img_cballback, 1, idx);

打开指定索引的相机

API	int start_camera(int8_t idx)
描述	无参的形式打开摄像头。
参数	idx:摄像头索引。
返回值	0：成功。-1： 失败。

举例如下：

int result = start_camera(0);

通过配置文件打开指定摄像头

API	int start_camera(const char* json_param, int8_t idx)
描述	无参的形式打开摄像头。
参数	json_param：JSON 格式字符串。idx:摄像头索引。
返回值	0：成功。-1： 失败。

举例如下：

 const char* config = R"({
        "width": 1280,
        "height": 720,
        "fps": 30,
        "format": "MJPG"
    })";

// 启动第0个摄像头，使用上述配置
int result =start_camera(config, 0);

激活配置文件设置摄像头

API	int8_t configure_camera_parameter(const char *conf_file, int8_t activate, int8_t idx = 0)
描述	通过配置文件激活摄像头参数。
参数	conf_file:向摄像头配置文件路径的字符串。activate:0不激活，1激活。idx:摄像头索引。
返回值	0：成功。-1： 失败。

举例如下：

const char* config_path = "/home/user/camera_config_1080p.json";
int8_t result = Aidlux::SmartVision::configure_camera_parameter(config_path, 1, 0);

激活json配置摄像头

API	int8_t configure_camera_parameter(int8_t activate, const char* json_param, int8_t idx)
描述	通过json配置文件激活摄像头参数。
参数	activate:0不激活，1激活。json_param：JSON 格式字符串。idx:摄像头索引。
返回值	0：成功。-1： 失败。

举例如下：

const char* config = R"({
        "width": 1280,
        "height": 720,
        "fps": 25,
        "exposure": -4,
        "brightness": 50
    })";
int8_t result = Aidlux::SmartVision::configure_camera_parameter(1, config, 0);

重启摄像头流

API	int8_t configure_camera_parameter_io(GetImageCB cb, const char* json_param, int8_t idx)
描述	根据配置差异决定是否需要重启摄像头流。
参数	cb: 图像获取回调函数，用于处理摄像头捕获的图像回调函数GetImageCB。json_param：JSON 格式字符串。idx:摄像头索引。
返回值	0：成功。-1： 失败。

举例如下：

int8_t my_get_img_cb(const Aidlux::SmartVision::Image & cap_img, const SVSdkMemfdInfo &index)
{
    t_count++;
    cout << "Image - w: " << cap_img.w << ", h: " << cap_img.h << "Image - w: " << cap_img.srcWidth << ", h: " << cap_img.srcHeight << ", length: " << cap_img.length << ", rt fps: " << cap_img.rt_fps << ", ma fps: " << cap_img.ma_fps << endl;
    // 添加处理程序，当data_sign为真才处理
    if(data_sign){
        data_sign1 = false;
    }        
    return 0;        
}
const char* new_config = R"({
        "width": 1920,
        "height": 1080,
        "fps": 30,
        "format": "H264"
    })";
int8_t result = Aidlux::SmartVision::configure_camera_parameter_io(my_get_img_cb, new_config, 0);

应用设置是否启动

API	int8_t configure_camera(const char *file_path, bool set_property, bool validation)
描述	过传入配置文件路径来配置摄像头，并根据参数决定是否立即应用设置。
参数	file_path：摄像头配置文件的路径（如 /home/config/cam1.json），包含分辨率、帧率等参数。set_property：是否在加载后立即激活/应用参数。validation：参数被忽略（未使用）。
返回值	0：成功。-1： 失败。

举例如下：

const char* config_file = "/home/user/1080p_config.json";
int8_t result = Aidlux::SmartVision::configure_camera(config_file, true, false);

关闭指定索引摄像头

API	int8_t close_camera(int8_t idx)
描述	关闭指定索引的摄像头。
参数	idx:摄像头索引。
返回值	0：请求发送成功。

举例如下：

int8_t result = close_camera(0);

预览功能

API	int8_t preview_set(int8_t enable, int8_t idx)
描述	开启或关闭指定摄像头的预览功能。
参数	enable：0开启，1关闭。idx:摄像头索引。
返回值	0：成功。非0： 失败。

举例如下：

int8_t result = Aidlux::SmartVision::preview_set(1, 0);

设置OFF关闭信号输出配置

API	int8_t set_off_mode()
描述	设置OFF关闭信号输出配置。
参数	无
返回值	-1： 失败。0： 成功。

举例如下：

//设置OFF关闭信号输出模式
int8_t res = set_off_mode();

配置TCP

API	int8_t get_tcp_setting(int cam_id, TcpConfig& tcp_setting)
描述	配置TCP的设置
参数	cam_id：相机的ID号。 tcpsetting: 类TcpConfig的实例化对象。包含TCP输出类的信息。
返回值	-1： 失败。0： 成功。

举例如下：

int8_t cam_id = 0;
TcpConfig tcpsetting;
int8_t res = get_signal_sending_mode(cam_id, tcpsetting);

获取TCP的设置

API	int8_t tcp_send_signal(int cam_id, std::string message)
描述	TCP发送信号到指定相机。
参数	cam_id：相机的ID号。 message: 字符串数据信息。
返回值	-1： 失败。0： 成功。

举例如下：

int8_t cam_id = 0;
string message = "hello world";
int8_t res = get_signal_sending_mode(cam_id, message);

TCP信息内容发送

API	int8_t tcp_send(std::string message, TcpConfig& tcp_setting)
描述	发送TCP类信息到指定的字符串。
参数	message: 字符串数据信息。 tcpsetting: 类TcpConfig的实例化对象。包含TCP输出类的信息。
返回值	-1： 失败。0： 成功。

举例如下：

string message = "hello world";
TcpConfig tcpsetting;
int8_t res = tcp_send(message, tcpsetting);

IO数据发送

API	int8_t io_send(std::string io_str, std::string io_control_file)
描述	将指定的字符串数据写入到一个由路径指定的系统文件中。
参数	io_str：要写入文件的字符串数据。 io_control_file: 目标文件的完整路径（如 /sys/class/gpio/gpio17/value）。
返回值	-1： 失败。0： 成功。

举例如下：

std::string gpio_value_path = "/sys/class/gpio/gpio17/value";
std::string value = "1";
int8_t result = Aidlux::SmartVision::io_send(value, gpio_value_path);

数字输出控制

API	int8_t send_signal_on(int device_id)
描述	根据传入的设备 ID，从配置中获取对应的信号保持时间。
参数	device_id: 设备编号（1, 2, 3 分别对应 DO1, DO2, DO3）。
返回值	-1： 失败。0： 成功。

举例如下：

int8_t res = send_signal_on(1);

数字输出信号控制

API	int8_t send_signal_off(int device_id, int keeptime)
描述	启动一个独立线程来管理信号的持续时间和状态。
参数	device_id: 设备编号（1, 2, 3 分别对应 DO1, DO2, DO3）。keeptime: 信号保持时间。
返回值	-1： 失败。0： 成功。

举例如下：

int8_t res = send_signal_off(1, 5000);

信号类型定义（枚举SignalType）

成员变量名	类型	默认值	描述
OFF	uint8_t	0	关闭信号输出配置
NG_SIGNAL	uint8_t		NG信号输出模式
ALARM_SIGNAL	uint8_t		alarm信号输出模式
OK_SIGNAL	uint8_t		ok信号输出模式

信号类型定义（枚举SignalMode）

成员变量名	类型	默认值	描述
IO_MODE	uint8_t	0	IO模式
TCP_MODE	uint8_t	1	TCP模式
MODBUS_MODE	uint8_t	2	MODBUS模式
UART_MODE	uint8_t	3	串口模式

信号类型定义（枚举CameraTriggerMode）

成员变量名	类型	默认值	描述
INVALID_TRIGGER_MODE_ENUM0	uint8_t	0	无效触发模式
INTERNAL_TRIGGER_MODE_ENUM1	uint8_t		内触发
EXTERNAL_TRIGGER_MODE_ENUM2	uint8_t		外触发，外部硬件触发
SOFTWARE_TRIGGER_MODE_ENUM3	uint8_t		软件触发

不同状态类型定义（枚举SPhase）

成员变量名	类型	描述
OPEN_CAMERA_ING_ENUM1	1	打开相机中
OPEN_CAMERA_SUC_ENUM2		打开相机成功
OPEN_CAMERA_FAIL_ENUM3		打开相机失败
LOAD_MODEL_ING_ENUM4		模型加载中
LOAD_MODEL_SUC_ENUM5		模型加载成功
LOAD_MODEL_FAIL_ENUM6		模型加载失败
WAIT_IMAGE_ING_ENUM7		等待图像中

YUV格式数据转BGR格式数据

API	bool yuv_to_bgr(cv::Mat &destMat, int srcSliceHeight, int srcYPlaneStride, int planeOffset, void *memdata, int idx)
描述	YUV格式数据转BGR格式数据。通过入参destMat对象来将转换后的数据传出。
参数	destMat: 输出的BGR图像。srcSliceHeight: 原始图像高度。srcYPlaneStride: Y平面的行字节数。planeOffset: UV平面的偏移量。memdata: 输入的YUV数据。idx: 相机的索引。
返回值	false： 失败。true： 成功

举例如下：

int idx = 0;
cv::Mat sdk_frame;

int8_t my_get_img_cb(const Aidlux::SmartVision::Image & cap_img, const SVSdkMemfdInfo &index)
{
    t_count++;
    cout << "Image - w: " << cap_img.w << ", h: " << cap_img.h << "Image - w: " << cap_img.srcWidth << ", h: " << cap_img.srcHeight << ", length: " << cap_img.length << ", rt fps: " << cap_img.rt_fps << ", ma fps: " << cap_img.ma_fps << endl;
    // 添加处理程序，当data_sign为真才处理
    if(data_sign){
        bool res = yuv_to_bgr(sdk_frame, cap_img.srcHeight, cap_img.srcWidth, cap_img.planeOffset, (void *)cap_img.data, idx);
        data_sign = false;
    }
    return 0;
}

获取SDK版本信息（函数get_build_version）

API	const char *get_build_version()
描述	获取sdk版本信息。
参数	无
返回值	sdk版本信息。

举例如下：

// 获取SDK版本信息
const char* res = get_build_version();

标识构建时间（函数get_build_meta）

API	const char *get_build_meta(void)
描述	构造时间。
参数	无
返回值	编译时期的时间戳 。

举例如下：

// 获取SDK版本信息
const char* res = get_build_meta();

标识代码版本（函数get_build_id）

API	const char *get_build_id(void)
描述	标识代码版本。
参数	无
返回值	Git 代码仓库的提交哈希。

举例如下：

// 获取SDK版本信息
const char* res = get_build_id();

获取最新日志信息（函数log_last_msg）

API	const char* log_last_msg(SVLogLevel log_level)
描述	获取最新日志信息。
参数	SVLogLevel日志级别。
返回值	最新的一条日志记录。

举例如下：

// 获取最新日志信息
const char* res = log_last_msg(log_level);

获取FPS帧率（函数get_fps）

API	double get_fps(int idx)
描述	获取callback函数中的实时帧率，其能代表相机采集数据的帧率。
参数	相机类型索引idx。MIPI相机：0 ~2。默认值为0。
返回值	帧率值

举例如下：

// 获取当期相机采集的实时帧率
int idx = 0;
double fps_v = get_fps(idx);

配置MIPI相机（函数configure_camera）

API	int8_t configure_camera(const char *file_path, bool set_property = false, bool validation = true)
描述	设置相机参数。
参数	file_path： 配置文件。 set_property：是否即时生效（true：是 false：否）。 validation： 是否校验参数（true：是 false：否）
返回值	0： 成功设置 1： 设置失败。

举例如下：

// 获取当期相机采集的实时帧率
double res = configure_camera("./param.json", true, true);

获取相机配置（函数get_camera_setting）

API	string get_camera_setting(int8_t idx = 0)
描述	获取相机配置参数。
参数	idx： 相机索引。 默认值为0。当前可不用输入参数值，使用默认值即可。
返回值	json格式字符串。

举例如下：

const char* res = get_camera_setting();

获取摄像头配置

API	string get_camera_info(int8_t idx)
描述	根据摄像头索引 idx 获取对应配置文件路径，读取并解析 JSON 格式的摄像头配置信息。
参数	idx： 相机索引。
返回值	成功：返回一个包含摄像头配置信息的 JSON 格式字符串。失败：返回一个 空字符串 ("")。

举例如下：

std::string info = Aidlux::SmartVision::get_camera_info(0);

获取摄像头默认配置

API	string get_camera_default_setting(int8_t idx)
描述	通过摄像头索引 idx 加载默认配置，获取完整配置字符串并同步到系统单例。
参数	idx： 相机索引。
返回值	成功：返回一个包含摄像头配置信息的 JSON 格式字符串。失败：返回一个 空字符串 ("")。

举例如下：

std::string setting = Aidlux::SmartVision::get_camera_default_setting(0);

获取传感器模型信息

API	string get_sensor_model_info(int idx)
描述	获取传感器模型信息。
参数	idx： 相机索引。
返回值	成功：返回一个包含传感器模型信息的字符串。失败：返回一个 空字符串 ("")。

举例如下：

std::string setting = Aidlux::get_sensor_model_info(0);

获取所有的相机物理位置

API	std::vector<std::string> get_all_cam_ids(bool disable_cache)
描述	根据是否禁用缓存来决定是从本地配置读取还是实时探测所有摄像头的型号名称。
参数	disable_cache(true：强制重新探测摄像头，清空缓存。false：优先使用缓存数据，不重新启动探测)。
返回值	包含所有成功识别摄像头的 SensorName 字符串列表。

举例如下：

auto camera_list = get_all_cam_ids(false);// 使用缓存

获取所有相机的索引

API	std::vector<int> get_all_cam_index()
描述	get_all_cam_index。
参数	无
返回值	所有相机的索引集合。

举例如下：

auto camera_list = get_all_cam_index();

获取所有摄像头信息

API	std::unordered_map<int, std::string> get_all_cameras(bool disable_cache)
描述	调用底层探测逻辑获取所有摄像头信息。
参数	disable_cache(true：强制重新探测摄像头，清空缓存。false：优先使用缓存数据，不重新启动探测)。
返回值	键（key）是摄像头的 物理位置 ID（如 0,1,2），值（value）是对应的传感器名称。

举例如下：

auto cameras = get_all_cameras(false); // 使用缓存

根据物理位置查找逻辑索引

API	int get_idx_by_loc_id(int loc_id)
描述	根据摄像头的物理位置 ID（loc_id）查找其对应的逻辑索引(cam_id或idx)。
参数	loc_id:物理位置标识。
返回值	成功：对应的逻辑索引。失败：-1。

举例如下：

int idx = get_idx_by_loc_id(1); // 假设 loc_id=1 对应 idx=0 → 返回 0

根据逻辑索引查找物理位置

API	int get_loc_id_by_idx(int idx)
描述	根据摄像头的逻辑索引（idx）反向查找其所在的物理位置 ID（loc_id）。
参数	idx： 相机索引。
返回值	成功：对应的 loc_id。失败：-1。

举例如下：

int loc_id = get_loc_id_by_idx(0); // 假设 idx=0 来自 loc_id=1 → 返回 1

根据相机名称查找索引

API	int get_cam_index(std::string cam_id)
描述	通过相机名称查找其对应的逻辑索引。
参数	cam_id： 相机名称。
返回值	成功：对应的逻辑索引（如 0, 1，2）。失败：-1。

举例如下：

int idx = get_cam_index("OV5645");

根据索引查找相机名称

API	string get_cam_id(int cam_index)
描述	根据逻辑索引查找并返回对应的相机名称。
参数	cam_index：相机逻辑索引。
返回值	成功：对应的相机名称。失败：空字符串""。

举例如下：

std::string cam_name = get_cam_id(0);

获取预览帧

API	cv::Mat image_read(int8_t idx)
描述	安全地从指定摄像头读取当前预览帧（JPEG格式）。
参数	idx：相机的逻辑索引。
返回值	成功：包含 JPEG 图像数据的矩阵。失败：空矩阵cv::Mat()。

举例如下：

cv::Mat jpg_data = image_read(0);

获取当前相机状态

API	int8_t get_camera_status(int8_t idx)
描述	通过日志记录并返回指定索引摄像头的当前状态码。
参数	idx：相机的逻辑索引。
返回值	摄像头的状态码具体含义由 CameraSIns 定义。

举例如下：

int8_t status = get_camera_status(0);

启动图像捕获

API	void start_camera_capture(int idx)
描述	启动指定摄像头的图像捕获功能。
参数	idx：相机的逻辑索引。
返回值	无

举例如下：

start_camera_capture(0);

停止图像捕获

API	void stop_camera_capture(int idx)
描述	停止指定摄像头的图像捕获。
参数	idx：相机的逻辑索引。
返回值	无

举例如下：

stop_camera_capture(0);

获取目标宽度

API	int get_dst_width(int8_t idx)
描述	获取指定摄像头输出图像的目标宽度。
参数	idx：相机的逻辑索引。
返回值	成功：返回目标宽度（如 1920, 1280 等）。失败：-1或0。

举例如下：

int width = get_dst_width(0);

获取目标高度

API	int get_dst_height(int8_t idx)
描述	获取指定摄像头输出图像的目标高度。
参数	idx：相机的逻辑索引。
返回值	成功：返回目标高度（如 1080, 720 等）。失败：-1或0。

举例如下：

int width = get_dst_height(0);

发送任务通知

API	int8_t notify_sve(SPhase phase_enum)
描述	通过HTTP（POST）请求向本地 SVE 服务发送当前任务阶段通知。
参数	phase_enum：表示当前任务状态的枚举值（OPEN_CAMERA_ING_ENUM1 = 1,OPEN_CAMERA_SUC_ENUM2）。
返回值	0：请求成功发送并收到响应。 -1：初始化失败或发生错误。

举例如下：

int8_t res = notify_sve(SPhase::OPEN_CAMERA_ING_ENUM1);

上传内容到sve服务

API	int8_t save_result(const char *release_id, const char *release_version, const char *origin_file, const char *mask_file, const char *final_file, const char *additional)
描述	将图像分析任务的结果文件路径及附加信息打包为 JSON 并上报至本地 SVE 服务。
参数	release_id：发布/任务 ID。release_version:版本号。origin_file：原始图像文件路径。mask_file：掩码图像文件路径。final_file：最终结果图像文件路径。additional：额外的 JSON 字符串（可为空）。
返回值	0：成功。 -1：失败。

举例如下：

int8_t ret = save_result(
    "task_123",                    // release_id
    "v1.0",                        // release_version
    "/tmp/origin.jpg",             // origin_file
    "/tmp/mask.png",               // mask_file
    "/tmp/final.jpg",              // final_file
    "{\"defect_size\":23.5,\"confidence\":0.98}"  // additional (JSON string)
);

旧版图像转换

API	cv::Mat get_cvimage(const Image &img, int idx)
描述	摄像头原始YUV格式的图像数据转换为 OpenCV 可用的BGR三通道矩阵。
参数	const Image &img：包含原始图像数据的结构体。idx：相机的逻辑索引。
返回值	成功：转换后的 BGR 图像矩阵。失败：返回空矩阵（cv::Mat()。

举例如下：

int cam_idx = 0;
struct Image {
    uint8_t* data;         // 指向YUV数据起始地址
    int srcWidth;          // 图像宽度
    int srcHeight;         // 图像高度
    int planeOffset[3];    // Y,U,V各平面的偏移量
    // 其他字段...
};
cv::Mat bgr_image = get_cvimage(img, cam_idx);

关闭摄像头服务

API	void qmm_cleanup(int cam_id)
描述	发送特定格式的控制信号来停止指定或全部摄像头服务。
参数	cam_id:相机逻辑索引。
返回值	"5" + to_string(cam_id) → 例如 "50" 表示停止 0 号摄像头。调用 qmm_message(_signal) 发送控制指令输出调试日志。

举例如下：

// 停止 0 号摄像头
qmm_cleanup(0);

关闭所有摄像头服务

API	void qmm_cleanup_all()
描述	发送特定格式的控制信号来停止指定或全部摄像头服务。
参数	无
返回值	- 循环3个摄像头，对每个索引调用 qmm_message("5" + to_string(i))，每次发送都输出日志。

举例如下：

qmm_cleanup_all();

清理异常进程

API	void qmm_cleanup_invalid()
描述	清理状态异常的 qmm 进程。
参数	无
返回值	无

举例如下：

qmm_cleanup_invalid();

检查摄像头服务状态

API	int qmm_status(int idx)
描述	检查指定摄像头索引 idx 对应的服务进程是否存活，基于 Redis 心跳机制实现。
参数	idx：相机的逻辑索引。
返回值	2：服务正在运行 0：未注册 4：服务异常。

举例如下：

int status = qmm_status(0);

启动录制

API	int start_record(int idx)
描述	安全地启动摄像头视频录制，执行多项前置检查。
参数	idx：相机的逻辑索引。
返回值	0：成功。 -1：失败。

举例如下：

int cam_idx = 0;
if (Aidlux::SmartVision::get_camera_status(cam_idx) == 2)
{
    int ret = Aidlux::SmartVision::start_record(cam_idx);
    if (ret == 0) {
        CLOGI("成功启动！");
    } else {
        CLOGE("启动录制失败，请检查预览是否开启或帧率设置");
    }
} else {
    CLOGE("摄像头未运行，请先调用start_camera_capture()");
}

录制状态检获取录制状态测

API	int get_record_status(int idx)
描述	查询指定摄像头的视频录制状态。
参数	idx：相机的逻辑索引。
返回值	0：正在录制。 -1：录制失败。

举例如下：

int cam_idx = 0;
int record_status = Aidlux::SmartVision::get_record_status(cam_idx);
if (record_status == 0) {
    CLOGI("摄像头 %d 正在录制视频...", cam_idx);
} else {
    CLOGI("摄像头 %d 当前未录制", cam_idx);
}

停止录制

API	MediaInfo stop_record(int idx)
描述	停止摄像头的录制过程，并从内部状态中提取并填充录制结果元数据。
参数	idx：相机的逻辑索引。
返回值	MediaInfo：一个包含录制结果信息的结构体，即使未成功录制也可能返回默认值。

举例如下：

int cam_idx = 0;
// 停止录制并获取信息
MediaInfo record_info = Aidlux::SmartVision::stop_record(cam_idx);

设置像素合并和位深

API	int set_bpp_binning(string cam_id, int binning_flag, int hb, int vb, int bpp_flag, int bpp)
描述	指定摄像头的像素合并和位深。
参数	cam_id：摄像头唯一标识符。binning_flag：是否启用 binning（0=关闭，1=开启）。hb：水平方向合并倍数（如 2 表示每 2 像素合并为 1）。vb：垂直方向合并倍数（如 2 表示每 2 行合并为 1）。bpp_flag：是否启用自定义位深（0=使用默认，1=启用 bpp 设置）。bpp：目标位深值（常见值：8、10、12、16 bit）。
返回值	0：成功。 -1：失败。

举例如下：

// 示例：配置 camera0 启用 2x2 binning 和 12-bit 输出
int ret = set_bpp_binning
(
    "camera0",   // cam_id
    1,           // binning_flag: 开启
    2,           // hb: 水平 2 合 1
    2,           // vb: 垂直 2 合 1
    1,           // bpp_flag: 自定义位深
    12           // bpp: 12-bit 输出
);

设置配置文件名

API	void DeviceParam::set_cfgname(const string &cfg_name_str)
描述	设置设备参数类中的配置文件名。
参数	cfg_name_str (const string &)：要设置的配置文件名（如 "camera_config.json"）。
返回值	无

举例如下：

Aidlux::SmartVision::DeviceParam device_param;
// 设置配置文件名
device_param.set_cfgname("my_camera_config.json");

判断字符串是否为IP地址

API	bool isIPFormat(const char* str)
描述	判断字符串是否为 IPv4 或（完整格式）IPv6 地址。
参数	str (const char*)：待检测的字符串。
返回值	true：字符串匹配IPv4或IPv6。false：格式不匹配或为空指针。

举例如下：

std::cout << isIPFormat("192.168.1.1") << std::endl;

文件判断

API	bool isFileExists(const std::string& filePath)
描述	判断一个文件路径是否对应一个存在的文件（或目录）。
参数	str (const char*)：待检测的字符串。
返回值	true：文件存在。false：文件不存在。

举例如下：

std::string path1 = "/data/camera_config.json";
std::string path2 = "/data/nonexistent.txt";
if (isFileExists(path1)) {
    CLOGI("文件存在：%s", path1.c_str());
} else {
    CLOGE("文件不存在：%s", path1.c_str());
}

if (isFileExists(path2)) {
    CLOGI("文件存在：%s", path2.c_str());
} else {
    CLOGE("文件不存在：%s", path2.c_str());
}

创建并写入配置文件

API	bool createNewSignalFile(const std::string& filePath)
描述	创建指定路径的文本文件，并写入默认 JSON 配置。
参数	str (const char*)：待检测的字符串。
返回值	true：文件存在。false：文件不存在。

举例如下：

std::string signalPath = "/tmp/my_service_signal.json";

if (createNewSignalFile(signalPath)) {
    CLOGI("信号文件创建成功：%s", signalPath.c_str());
    // 输出：{"mode":0}
} else {
    CLOGE("无法创建信号文件，请检查路径和权限");
}

获取相机图像的fd并返回完整元数据

API	int get_fd_with_meta(int idx, AidluxSocketfdInfo &out_meta)
描述	获取指定摄像头的文件描述符，并返回完整的元数据。
参数	idx：摄像头索引。out_meta：输出元数据。
返回值	文件描述符。

举例如下：

int cam_idx = 0;
AidluxSocketfdInfo meta;
int fd = Aidlux::SmartVision::get_fd_with_meta(cam_idx, meta);
if (fd != -1) {
    CLOGI("get_fd_meta sccessfully!: %d", fd);
    CLOGI("the fd_meta is: %s", meta.toString().c_str());
} else {
    CLOGE("get_fd_meta failed!");
}

获取图像数据

API	cv::Mat get_cvimage(Image &img, int idx, int max_timeout_ms)
描述	获取指定摄像头的图像数据，并将其转换为相机图像的 Mat 对象。
参数	img：Image 结构体，用于存储图像数据。idx：摄像头索引。max_timeout_ms：最大等待时间（毫秒）。
返回值	转换后的 Mat 对象。

举例如下：

Imgage img;
while (!g_stop_signal)
{
    cv::Mat frame = Aidlux::SmartVision::get_cvimage(img, camera_idx, 1000);
    printf("res=%dx%d | exp=%ld ns | iso=%ld\n",img.h, img.w,img.exposureTimeNs,img.isoValue);
    if (frame.empty())
    {
        CLOGI ("Failed to get frame from camera %d",camera_idx);
        usleep(10 * 1000);
        continue;
    }

    CLOGI("Camera %d success!",camera_idx);
}

断开连接

API	void disconnect(int idx)
描述	关闭指定摄像头的文件描述符连接。
参数	idx：摄像头索引。
返回值	无

举例如下：

int cam_idx = 0;
Aidlux::SmartVision::disconnect(cam_idx);

获取相机实时信息

API	SVSdkMemfdInfo get_camera_rt_info(int idx)
描述	获取指定摄像头的实时信息，包括曝光时间和其他参数。
参数	idx：摄像头索引。
返回值	SVSdkMemfdInfo 结构体，包含实时信息。

举例如下：

int cam_idx = 0;
SVSdkMemfdInfo info = Aidlux::SmartVision::get_camera_rt_info(cam_idx);
CLOGI("曝光时间: %d", info.exposure_time);