API 详解（Python）

GetVersionString 获取VCameraSDK版本

version = GetVersionString()
print('version = ', version)

CameraUtils类

CameraUtils 是 SDK 提供的一个静态工具类，专门用于相机设备的发现、网络配置、SDK和相机日志配置。

Init初始化相机

初始化相机系统环境。

percipio.CameraUtils.Init(true)

说明：必须在其他操作前调用。

DiscoverCameras发现相机设备

扫描并发现所有可用的图漾相机。

percipio.CameraUtils.DiscoverCameras()

SetIpAddress设置静态IP

该接口用于设置相机的静态ip。该接口有2种使用方法。

第一种，传入相机的mac地址，以及需要设置的ip、netmask、gateway。

percipio.CameraUtils.SetIpAddress("06:2B:5B:1E:70:D4", "192.168.2.144", "255.255.255.0", "192.168.2.1")

第二种，传入相机的Camera_info，以及需要设置的ip、netmask、gateway。

information, ret = cam.GetCameraInfo()
print("camera infor statis is ",ret)
print(f"Camera Info: {information}")
percipio.CameraUtils.SetIpAddress(information, "192.168.2.223", "255.255.255.0", "192.168.2.1")

SetIpToDynamic设置动态IP

该接口用于设置相机的动态ip。该接口有2种使用方法。

第一种，传入相机的mac地址。

percipio.CameraUtils. SetIpToDynamic ("06:26:CD:26:6C:38")

第二种，传入相机的 camera_info。

information, ret = cam.GetCameraInfo()
print("camera infor statis is ",ret)
print(f"Camera Info: {information}")
percipio.CameraUtils. SetIpToDynamic (information, "192.168.2.223", "255.255.255.0", "192.168.2.1")

CameraFactory类

CameraFactory 是 Percepio SDK 中的工厂类，专用于实例化并连接不同配置的相机设备。提供三种静态工厂方法，支持通过序列号、IP地址或预配置信息创建相机实例。

GetCameraBySerialNumber通过序列号获取相机

该接口用于通过相机序列号来获取相机对象。

percipio.CameraFactory.GetCameraBySerialNumber('207000161660')

GetCameraByIpAddress通过IP获取相机

该接口用于通过相机ip地址来获取相机对象。

percipio.CameraFactory.GetCameraByIpAddress ('192.168.2.201')

GetCameraByCameraInfo通过相机信息获取相机

该接口用于通过相机的信息来创建相机实例。

percipio.CameraFactory.GetCameraByCameraInfo(device)

Camera类

核心设备控制与图像采集接口。

GetCameraInfo获取相机信息

用于获取相机设备的信息。

devicelist = percipio.CameraUtils.DiscoverCameras()
if not devicelist:
   print("no device found")
   return -1
for device in devicelist:
   # 通过相机信息获取相机对象
   camera = percipio.CameraFactory.GetCameraByCameraInfo(device)
   # 连接相机
   status = camera.Connect()
   if not status.IsSuccess():
      print(f"Camera Connect error: {status.message()}")
      return -1
   # 获取相机信息
   camera_info = camera.GetCameraInfo()
   print(f"Camera Info: {camera_info}")

相机信息包括以下字段：

interface_info: InterfaceInfo - 接口信息
network_info: NetworkInfo - 网络信息
usb_info: UsbInfo - USB信息
serial_number: str - 序列号
name: str - 相机名称
model: str - 型号
vendor: str - 厂商
firmware_version: str - 固件版本
state: CameraState - 相机状态

Connect连接设备

用于连接设备。

cam.Connect('')

Disconnect断连设备

用于断连设备。

cam.Disconnect()

GetCameraState获取相机状态

用于获取相机状态。

statuss = cam.GetCameraState()
print("the status is: ", statuss)

相机有 7 种状态：NotFound、Occupied、Opened、Closed、Capturing、Offlined、Error。

StartCapture开始采集图像

用于控制相机开始采集图像。

camera.StartCapture()

StopCapture停止采集图像

用于控制相机停止采集图像。

camera.StopCapture()

GetFeature获取待设置的参数

用于获取待设置的参数。

重要

SDK 支持设置的属性列表见 {SDK 安装路径}\Percipio_SDK\doc\feature_list.txt。

acq_mode, status = cam.GetFeature('AcquisitionMode')
if not status:
print("Failed to get AcquisitionMode: ", status.message())

GetAllFeatures获取所有参数

用于获取所有参数。

cam.GetAllFeatures()

FireSoftwareTrigger发送软触发采图信号

用于为工作在软触发模式下的相机发送软触发采图信号。

status = cam.FireSoftwareTrigger()
if not status:
print("Failed to fire a software trigger:", status.message())

GetImageModes获取图像格式和分辨率

用于获取指定传感器支持设置的图像格式和分辨率。

modelist, mode = cam.GetImageModes(percipio.SensorType.COLOR)
print("support ",modelist)

GetCurrentImageMode获取当前的图像格式和分辨率

用于获取指定传感器当前的图像格式和分辨率。

modelist, mode = cam.GetCurrentImageMode(percipio.SensorType.COLOR)
print("support ",modelist)

SetImageMode设置图像格式和分辨率

用于设置指定传感器的图像格式和分辨率。

image_mode = percipio.ImageMode()
image_mode.pixel_format = percipio.RawPixelFormat.CSIBayer12GBRG
image_mode.width = 2560
image_mode.height = 1920
cam.SetImageMode(percipio.SensorType.COLOR,image_mode)
modelist, mode = cam.GetCurrentImageMode(percipio.SensorType.COLOR)
print("support ",modelist)

HasSensor查询相机是否具有指定传感器

用于判断相机是否拥有指定的传感器。

has_color,status = cam.HasSensor(percipio.SensorType.COLOR)
   if has_color:
        status = cam.SetSensorEnabled(percipio.SensorType.COLOR, True)
        if not status:
            print("Failed to enable color sensor: ", status.message())
            cam.Disconnect()
            return

有以下几种传感器：

DEPTH = “Depth”
LEFT = “Left”
RIGHT = “Right”
COLOR = “Color”

IsSensorEnabled获取传感器使能状态

用于判断相机指定的传感器是否被使能。

isenabled = cam.IsSensorEnabled(percipio.SensorType.DEPTH)
print("depth is enable ",isenabled)

SetSensorEnabled设置传感器使能状态

用于使能或去使能指定的传感器输出图像。

status = cam.SetSensorEnabled(percipio.SensorType.DEPTH, True)
if not status:
print("Failed to enable depth sensor: ", status.message())

SetUndistortionEnabled启用或禁用畸变矫正

用于对指定的传感器图像进行畸变校正或去畸变校正。

cam.SetUndistortionEnabled(percipio.SensorType.COLOR,False)
cam.SetUndistortionEnabled(percipio.SensorType.COLOR,True)

IsMapDepthToColorEnabled获取深度对齐彩色使能状态

用于查询深度图到彩色图映射（深度与彩色对齐）是否启用。

is_enabled_before, status = camera.IsMapDepthToColorEnabled()
if not status.IsSuccess():
    print(f"Failed to check mapping status: {status.message()}")
    return

print(f"Before setting: {'Enabled' if is_enabled_before else 'Disabled'}")

SetMapDepthToColorEnabled启用或禁用深度对齐彩色

启用或禁用深度图到彩色图的映射（深度图与彩色图对齐）。

status = cam.SetMapDepthToColorEnabled(True)
if not status:
    print(f"enable depth to color mapping err: {status.message()}")
    return -1

RegisterFrameSetCallback图像回调函数

图像回调函数。

cam.RegisterFrameSetCallback(frame_callback)

RegisterFeaturesChangedCallback()注册属性变化回调函数

RegisterFeaturesChangedCallback(callback: Callable[[list[Feature]], None]) -> None 注册属性变化回调函数

RegisterCameraEventCallback()注册相机事件回调函数

RegisterCameraEventCallback(callback: Callable[[CameraEventCode, int], None]) -> None 注册相机事件回调函数

相机事件代码包括：

Closed # 关闭
Opened # 打开
Started # 开始
Stopped # 停止
Offlined # 离线
Error # 错误

UserSetManager类

GetAllUserSets获取所有用户设置

该 API 用于获取相机所有的 UserSet 参数。

usets, status = user_set_mgr.GetAllUserSets()
print("Available User Sets:")

SaveToUserSet保存到用户设置

status=user_set_mgr.SaveToUserSet("123")
if status:
    print("Save success")
else:
    print("Save fail")

SaveToUserSetWithNewName重命名用户设置并保存

该接口用于重命名用户设置（Userset）并执行保存动作。

status=user_set_mgr.SaveToUserSetWithNewName('123', '456')
if status:
    print("rename success")
else:
    print("rename fail")

LoadUserSet加载用户设置

该接口用于加载所需的 Userset，调用时传入需要加载的 UserSet 名称即可，代码如下：

index_str = input("\nSelect a user set index: ")
index = int(index_str)

if index < len(usets):
    print(f"You selected: {usets[index].name}")
    status = user_set_mgr.LoadUserSet(usets[index].name)
    if status:
       print("Load success")
    else:
       print("Load fail")
else:
    print("Invalid index.")

CurrentUserSet读取当前用户设置

该接口用于读取当前使用的 UserSet 名称。

name, status = user_set_mgr.CurrentUserSet()
print("Current user set: ", name)

GetPowerOnUserSet读取相机上电时的用户设置

该接口用于读取相机上电时的默认UserSet的名称。

name, status = user_set_mgr.GetPowerOnUserSet()
print("GetPowerOnUserSet user set: ", name)

SetPowerOnUserSet设置相机上电时的用户设置

该接口用于设置相机上电时的UserSet。调用时传入UserSet的名称即可。

user_set_mgr.SetPowerOnUserSet(usets[2].name)
name, status = user_set_mgr.GetPowerOnUserSet()
print("GetPowerOnUserSet user set: ", name)

CameraApiStatusCode（API状态码）

Success,
Failure,
ArrayInfoInvalid,
ArrayInvalid,
CalibrationInfoInvalid,
CameraInvalid,
ComponentInvalid,
DeviceInvalid,
DeviceError,
DeviceIdle,
DeviceBusy,
DeviceLost,
DeviceInterfaceInvalid,
DeviceInterfaceTypeError,
DeviceInfoInvalid,
FeatureInvalid,
FeatureInfoInvalid,
FeatureTypeError,
FrameInvalid,
FrameMetadataInvalid,
FrameBufferInvalid,
FrameBufferConsumerInvalid,
FrameSetInvalid,
FrameSetStreamInvalid,
FrameSetConsumerInvalid,
TriggerModeError,
NotExist,
NotImplemented,
NotPermitted,
NotSupported,
OutOfMemory,
OutOfIndexRange,
OutOfValueRange,
ParameterInvalid,
StructureInfoInvalid,
StructureInvalid,
Timeout,
ValueInvalid,
ValueTypeError,
ValueInfoInvalid,
NullCameraHandle,
UserSetIsFull,

相机属性类

基本信息方法

IsValid检查属性是否有效

判断该相机是否支持该属性。

acq_mode, status = cam.GetFeature('AcquisitionMode')
print(acq_mode.IsValid())

GetName获取属性名称

acq_mode, status = cam.GetFeature('AcquisitionMode')
print(acq_mode.GetName())

GetAccessMode读取相机属性权限

acq_mode, status = cam.GetFeature('AcquisitionMode')
print(acq_mode.GetAccessMode())

VCameraSDK中，属性的权限共有如下四种：

NotAvailable：不可用
Readable：可读
Writable：可写
ReadWritable：可读写

GetType获取相机属性类型

acq_mode, status = cam.GetFeature('AcquisitionMode')
print(acq_mode.GetType())

VCameraSDK中，属性的类型共有如下八种：

Undefined：未定义
Bool：布尔值
Int64：64位整数
Float64：64位浮点数
Enumeration：枚举
String：字符串
ByteArray：字节数组
Dictionary：字典

值操作方法

GetValue获取属性的当前值

整型属性

acq_mode, status = cam.GetFeature('CaptureTimeStatistic')
print("capture time is ",acq_mode.GetValue())

浮点型属性

acq_mode, status = cam.GetFeature('DepthScaleUnit')
print("DepthScaleUnit is ",acq_mode.GetValue())

枚举型属性

acq_mode, status = cam.GetFeature('DeviceTimeSyncMode')
print("DeviceTimeSyncMode is ",acq_mode.GetValue())

布尔型属性

acq_mode, status = cam.GetFeature('IRUndistortion')
print("IRUndistortion is ",acq_mode.GetValue())

SetValue设置属性值