Smart Vision SDK for Python

TIP

使用smart vision sdk，需要先导入smartvisionsdk package:

from pysmartvision import smartvisionsdk

Python API预览

类（class）	公共成员函数（public member function）	类型（Type）	描述（Description）
Camera	open(GetImageCB)	function	以无参模式打开相机
	open(DeviceParam, GetImageCB)	function	以有参模式打开相机
	start_capture()	function	打开流开关
	stop_capture()	function	关闭流开关
	close()	function	关闭相机
Image	data	str	指向存放数据的缓冲区的指针
	w	int	目标图片宽度
	h	int	目标图片高度
	c	int	目标图片的通道（通常为3）
	length	int	图片数据所占内存长度
	srcWidth	int	图片内部宽度，通常比最终宽度大
	srcHeight	int	图片内部高度
	lmemCopyStartIndexength	int	指示缓冲区中数据的索引
	memCopyEndIndex	int	指示缓冲区中数据的结束索引
	planeOffset	int	YUV数据的偏移值
TcpConfig	ip	str	IP地址
	port	int	端口号
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号
MediaInfo	duration	int	视频时长
	width	int	视频宽度
	height	int	视频高度
	frame_rate	int	视频帧率
	file_size	int	视频文件大小
	file_name	int	视频文件名

公共函数（public function）	描述（Description）
set_log_level(SVLogLevel log_level)	设置日志级别
set_log_destination(str destinationPath, bool also_to_stderr)	设置日志文件名及路径
log_to_stderr()	设置日志输出到终端。一旦设置则不会再保存日志文件。一般不建议使用。
GetImageCB(const Image, int)	作为open()函数的入参，用于获取相片资源。此函数由使用者自定义。接口仅提供类型定义来规范回调函数的定义。
set_off_mode()	设置OFF关闭信号输出配置。
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)	安全地从指定摄像头读取当前预览帧（JPEG格式）。
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)	指定摄像头的像素合并和位深。

枚举（ENUM）	成员变量名（public member variable）	类型（Type）	描述（Description）
SVLogLevel	SINFO	int	日志级别SINFO
	SWARNING	int	日志级别SWARNING
	SERROR	int	日志级别SERROR
	SDEBUG	int	日志级别SDEBUG
	SFATAL	int	日志级别SFATAL（Smart Vision SDK中未使用此级别）
SignalType	OFF	int	关闭信号输出配置
	NG_SIGNAL	int	NG信号输出模式
	ALARM_SIGNAL	int	alarm信号输出模式
SignalMode	IO_MODE	uint8_t	IO模式
	TCP_MODE	uint8_t	TCP模式
	MODBUS_MODE	uint8_t	MODBUS模式
	UART_MODE	uint8_t	串口模式

类Camera

实例化类Camera对象相关操作。打开相机、抓图等相关的操作都基于实例化Camera对象

WARNING

与C++中不同，python代码中无需引入名字空间，而需要使用以下命令在python代码中import模块smartvisionsdk：

from pysmartvision import smartvisionsdk

具体使用方法请参考以下接口。

无参模式打开相机（函数 open）

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

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

# 以无参模式打开相机 
camera_instance = smartvisionsdk.Camera()
res = camera_instance.open(get_img_cb)

有参模式打开相机（函数 open）

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

举例如下：

# 以有参模式打开相机
camera_instance = smartvisionsdk.Camera()
res = camera_instance.open(device_param, get_img_cb)

打开流开关（函数 start_capture）

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

举例如下：

# 打开流开关
camera_instance.start_capture()

关闭流开关（函数 stop_capture）

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

举例如下：

# 关闭流开关
camera_instance.stop_capture()

关闭相机（函数close）

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

举例如下：

//关闭流开关
camera_instance.close()

类DeviceParam

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

成员变量名	类型	默认值	描述
cfg_name	str		带路径的参数配置文件名

设置DeviceParam配置文件

API	set_cfgname(config_file)
描述	设置带路径的参数配置文件。 通过这个接口可设置cfg_name变量
参数	config_file为相机参数配置文件
返回值	无

举例如下：

# 设置配置文件
device_param = smartvisionsdk.DeviceParam()
device_param.set_cfgname("./config.json")

类Image

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

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

类TcpConfig

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

成员变量名	类型	默认值	描述
ip	str		IP地址
port	int		端口号

类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号

设置日志级别（函数 set_log_level

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

举例如下：

# 设置日志级别
smartvisionsdk.set_log_level(smartvisionsdk.SVLogLevel.SINFO)

设置日志文件名及路径（函数 set_log_destination）

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

举例如下：

# 设置日志文件名及路径
log_path = "./aidclog_smart_vision_setting_";
smartvisionsdk.set_log_destination(log_path, False)

设置日志输出到终端（函数 log_to_stderr）

API	log_to_stderr()
描述	设置日志文件名及路径
参数	设置日志输出到终端。一旦设置则不会再保存日志文件。一般不建议使用。
返回值	无

举例如下：

# 设置日志文件名及路径
smartvisionsdk.log_to_stderr()

日志级别（枚举 SVLogLevel）

成员变量名	类型	默认值	描述
SINFO	int	0	日志级别SINFO
SWARNING`	int		日志级别SWARNING
SERROR	int		日志级别SERROR
SDEBUG	int		日志级别SDEBUG
SFATAL	int		日志级别SFATAL（未使用）

回调函数 GetImageCB

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

举例如下：

# 回调函数定义
def get_img_cb(cap_img, mem_info):
    ......
    return 0

有参形式打开摄像头（函数start_camera_with_parameter）

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

举例如下：

result = Aidlux::SmartVision::start_camera_with_parameter(myImageCallback, "/home/config/camera.json", 1, 0)

无参形式打开摄像头（函数start_camera_without_parameter）

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

举例如下：

result = Aidlux::SmartVision::start_camera_with_parameter(myImageCallback, 1, 0)

打开指定摄像头（函数start_camera）

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

举例如下：

result = Aidlux::SmartVision::start_camera(0)

通过配置文件打开指定摄像头（函数start_camera）

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

举例如下：

config = '''{
    "width": 1280,
    "height": 720,
    "fps": 30,
    "format": "MJPG"
}'''


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

激活配置摄像头参数（函数configure_camera_parameter）

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"
result = Aidlux::SmartVision::configure_camera_parameter(config_path, 1, 0)

激活json配置摄像头参数（函数configure_camera_parameter）

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： 失败。

举例如下：

config = '''{
        "width": 1280,
        "height": 720,
        "fps": 25,
        "exposure": -4,
        "brightness": 50
    }'''
result = Aidlux::SmartVision::configure_camera_parameter(1, config, 0)

重启摄像头流（函数configure_camera_parameter_io）

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

举例如下：

void myImageCallback(cv::Mat img) 
{
    cv::imshow("Camera IO Config", img)
    cv::waitKey(1)
}
new_config ='''{
        "width": 1920,
        "height": 1080,
        "fps": 30,
        "format": "H264"
    }'''
result = Aidlux::SmartVision::configure_camera_parameter_io(myImageCallback, new_config, 0)

应用设置是否启动（函数configure_camera）

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"
result = Aidlux::SmartVision::configure_camera(config_file, true, false)

关闭指定索引摄像头（函数close_camera）

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

举例如下：

result = Aidlux::SmartVision::close_camera(0)

预览功能（函数preview_set）

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

举例如下：

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

设置OFF关闭信号输出配置（函数 set_off_mode）

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

举例如下：

# 设置OFF关闭信号输出模式
res = smartvisionsdk.set_off_mode()

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

API	get_build_version()
描述	获取SDK版本信息。
参数	无
返回值	SDK版本信息

举例如下：

# 获取SDK版本信息
res = smartvisionsdk.get_build_version()

获取Mat对象数据（函数 get_cvimage）

API	get_cvimage()
描述	获取mat对象数据。仅适用于python版本。可以通过此接口直接获取转换后的cv Mat对象数据。
参数	无
返回值	mat对象数据

举例如下：

# 获取Mat对象数据，其中cap_img为输入的Mat对象，其值为YUV数据
im = smartvisionsdk.get_cvimage(cap_img)

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

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

举例如下：

# 获取最新日志信息
res = smartvisionsdk.log_last_msg(log_level)

配置MIPI相机（函数configure_camera）

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

举例如下：

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

配置TCP（函数get_tcp_setting）

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

举例如下：

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

获取TCP的设置（函数tcp_send_signal）

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

举例如下：

cam_id = 0
message = "hello world"
res = get_signal_sending_mode(cam_id, tcpsetting)

TCP信息内容发送（函数tcp_send）

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

举例如下：

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

IO数据发送（函数io_send）

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： 成功

举例如下：

gpio_value_path = "/sys/class/gpio/gpio17/value"
value = "1"
result = Aidlux.SmartVision.io_send(value, gpio_value_path)

数字输出控制（函数send_signal_on）

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

举例如下：

res = send_signal_on(1)

数字输出控制（函数send_signal_on带保持时间）

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

举例如下：

res = send_signal_on(1, 5000)

信号类型定义（枚举SignalType）

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

YUV格式数据转BGR格式数据（函数yuv_to_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： 成功

举例如下：

def my_get_img_cb(cap_img: Any, index: Any) -> int:
    global t_count, sdk_frame, data_sign, idx
    t_count += 1
    print(f"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}")

    if data_sign:
        res = yuv_to_bgr(sdk_frame, cap_img.srcHeight, cap_img.srcWidth, cap_img.planeOffset, cap_img.data, idx)
        data_sign = False  
    return 0

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

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

举例如下：

// 获取SDK版本信息
res = get_build_version()

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

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

举例如下：

// 获取最新日志信息
res = log_last_msg(log_level)

获取FPS帧率（函数get_fps）

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

举例如下：

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

获取MIPI相机配置（函数get_camera_setting）

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

举例如下：

res = get_camera_setting()

获取摄像头配置（函数get_camera_info）

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

举例如下：

info = Aidlux.SmartVision.get_camera_info(0)

获取完整配置（函数get_camera_default_setting）

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

举例如下：

setting = Aidlux::SmartVision::get_camera_default_setting(0)

获取传感器模型信息（函数get_sensor_model_info）

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

举例如下：

setting = Aidlux::get_sensor_model_info(0)

获取所有的cam_id（函数get_all_cam_ids）

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

举例如下：

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

获取所有的index（函数get_all_cam_index）

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

举例如下：

camera_list = get_all_cam_index()

获取摄像头信息（函数get_all_cameras）

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

举例如下：

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

获取所有的cam_id（函数get_idx_by_loc_id）

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

举例如下：

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

获取所有的loc_id（函数get_loc_id_by_idx）

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

举例如下：

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

获取逻辑索引（函数get_cam_index）

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

举例如下：

dx = get_cam_index("OV5645")

获取相机名称（函数get_cam_id）

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

举例如下：

cam_name = get_cam_id(0)

获取预览帧（函数image_read）

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

举例如下：

cv::Mat jpg_data = Aidlux::SmartVision::image_read(0)

获取当前相机状态（函数get_camera_status）

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

举例如下：

status = Aidlux::SmartVision::get_camera_status(0)

启动图像捕获（函数start_camera_capture）

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

举例如下：

Aidlux::SmartVision::start_camera_capture(0)

停止图像捕获（函数stop_camera_capture）

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

举例如下：

Aidlux::SmartVision::stop_camera_capture(0)

获取目标宽度（函数get_dst_width）

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

举例如下：

width = Aidlux::SmartVision::get_dst_width(0)

获取目标高度（函数get_dst_height）

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

举例如下：

width = Aidlux::SmartVision::get_dst_height(0)

发送任务通知（函数notify_sve）

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

举例如下：

res = notify_sve(SPhase::OPEN_CAMERA_ING_ENUM1)

上传内容到sve服务（函数save_result）

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：失败。

举例如下：

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)
)

图像转换（函数get_cvimage）

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

举例如下：

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

关闭摄像头服务（函数qmm_cleanup）

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

举例如下：

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

关闭摄像头服务（函数qmm_cleanup_all）

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

举例如下：

qmm_cleanup_all()

清理异常进程（函数qmm_cleanup_invalid）

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

举例如下：

qmm_cleanup_all()

进程检查（函数qmm_cleanup）

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

举例如下：

status = qmm_status(0)

关闭摄像头服务（函数start_record）

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

举例如下：

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

录制状态检测（函数get_record_status）

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

举例如下：

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

停止录制（函数stop_record）

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

举例如下：

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

像素合并和位深（函数set_bpp_binning）

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 输出
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 输出
)

设置配置文件名（函数set_cfgname）

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")