API 详解（Python）

GetVersionString 获取 VCameraSDK 版本

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

CameraUtils 类

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

Init 初始化 SDK

初始化相机通信底层库。

vcam.CameraUtils.Init(True)

DiscoverCameras 发现相机设备

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

vcam.CameraUtils.DiscoverCameras()

SetIpAddress 设置静态 IP

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

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

完整示例代码请参见： VcameraSDK-X.X.X/python/samples/SetIpAddress.py。

SetIpToDynamic 设置动态 IP

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

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

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

第二种，传入相机的 camera_info。

for item in cameras:
    if item.serial_number == '207000159544':
        status = vcam.CameraUtils.SetIpToDynamic(item)
        if not status:
            print("Failed to set ip address: ", status.message())
            return
        else:
            print("Set IP address success: ", status.message())

CameraFactory 类

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

GetCameraBySerialNumber 通过序列号获取相机

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

vcam.CameraFactory.GetCameraBySerialNumber('207000161660')

GetCameraByIpAddress 通过 IP 获取相机

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

vcam.CameraFactory.GetCameraByIpAddress ('192.168.2.201')

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

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

for info in cameras:
    if info.serial_number == '207000159544':
        cam = vcam.CameraFactory.GetCameraByCameraInfo(info)
        if cam is None:
            print("Failed to create camera instance")
            return

        print("Camera created successfully")

Camera类

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

GetCameraInfo 获取相机信息

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

完整示例代码请参见： VcameraSDK-X.X.X/python/samples/DumpDeviceInfo.py。

devicelist = vcam.CameraUtils.DiscoverCameras()
if not devicelist:
   print("no device found")
   return -1
for device in devicelist:
   # 通过相机信息获取相机对象
   camera = vcam.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)

StartCapture 开始采集图像

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

cam.StartCapture()

StopCapture 停止采集图像

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

cam.StopCapture()

GetFeature 获取待设置的参数

用于获取待设置的参数。

重要

SDK 支持设置的属性列表见 VcameraSDK-X.X.X/doc/feature_list/。

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

GetAllFeatures 获取所有参数

用于获取所有参数。

cam.GetAllFeatures()

FireSoftwareTrigger 发送软触发采图信号

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

完整示例代码请参见： VcameraSDK-X.X.X/python/samples/SoftTrigger.py。

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

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

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

modelist, mode = cam.GetImageModes(vcam.SensorType.Texture)
print("support ",modelist)

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

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

modelist, mode = cam.GetCurrentImageMode(vcam.SensorType.Texture)
print("support ",modelist)

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

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

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

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

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

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

IsSensorEnabled 获取传感器使能状态

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

isenabled = cam.IsSensorEnabled(vcam.SensorType.Depth)
print("depth is enable ",isenabled)

SetSensorEnabled 设置传感器使能状态

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

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

SetUndistortionEnabled 启用或禁用畸变矫正

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

#cam.SetUndistortionEnabled(vcam.SensorType.Texture,False)
cam.SetUndistortionEnabled(vcam.SensorType.Texture,True)

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

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

is_enabled_before, status = camera.IsMapDepthToTextureEnabled()
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'}")

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

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

完整示例代码请参见： VcameraSDK-X.X.X/python/samples/DepthToTextureRegistration.py。

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

SaveFeaturesToFile/LoadFeaturesFromFile 保存相机配置到文件/从文件加载配置

分别用于将相机配置保存到 JSON 文件，以及从 JSON 文件加载配置并应用到相机。

注解

不同相机类型的保存行为：

Gige_2_0 相机：仅保存相机连接后修改的参数。连接前已保存的参数不会被记录。
Gige_2_1 相机：会尽可能保存全部参数。具体保存的参数列表请参考安装路径下的 doc/feature_save_gige2_1.txt。

保存配置到文件：

file_path_save = "1.json"
status = camera.SaveFeaturesToFile(file_path_save)

从文件加载配置：

file_path_load = "1.json"
status, error_message = camera.LoadFeaturesFromFile(file_path_load)

具体使用方法请参见示例程序：

VcameraSDK-X.X.X/python/samples/SaveFeaturesToFile.py
VcameraSDK-X.X.X/python/samples/LoadFeaturesFromFile.py

SaveFeaturesToStorage/LoadFeaturesFromStorage 保存配置到相机内部存储区/从相机内部存储区加载配置

分别用于将相机配置保存到内部存储区，以及从内部存储区加载配置。

注解

该接口仅适用于 Gige_2_0 相机。
对于 Gige_2_1 相机，请使用 UserSetManager 类接口。

保存配置到内部存储区：

status = camera.SaveFeaturesToStorage()
if status.IsSuccess():
    print("Successfully saved features to storage")
else:
    print(f"Fail to save features to storage: {status.message()}")

从内部存储区加载配置：

status, error_message = camera.LoadFeaturesFromStorage()
if status.IsSuccess():
    print("Successfully loaded features from storage")
else:
    print(f"Fail to load features from storage: {status.message()}\n{error_message}")

具体使用方法请参见示例程序：

VcameraSDK-X.X.X/python/samples/SaveFeaturesToStorage.py
VcameraSDK-X.X.X/python/samples/LoadFeaturesFromStorage.py

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

GetType 获取相机属性类型

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

值操作方法

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 设置属性值