API 详解（C#）

GetVersionString 获取VCameraSDK版本

string versionString = UCV.CameraApi.Interop.Version.GetVersionString();
Console.WriteLine($"GetVersionString: {versionString}");

CameraUtils相机管理与IP配置工具类

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

Init初始化相机

初始化相机系统环境。

CameraUtils.Init(true);

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

DiscoverCameras发现相机设备

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

CameraUtils.DiscoverCameras();

SetIpAddress设置静态IP

该接口用于设置相机的静态ip。传入相机的mac地址，以及需要设置的ip、netmask、gateway。

string mac = "06:2E:68:E5:81:8C";
string ip = "192.168.6.37";
string mask = "255.255.255.0";
string gateway = "192.168.6.1";

CameraApiStatus status = CameraUtils.SetIpAddress(mac, ip, mask, gateway);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"Successfully set the IP of the camera {mac} to {ip}");
}

SetDeviceDhcp设置动态IP

该接口用于设置相机的动态ip。传入相机的mac地址。

CameraUtils.SetDeviceDhcp("06:22:7F:05:9B:16");

CameraCapture类

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

GetCameraBySerialNumber通过序列号获取相机

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

CameraCapture.GetCameraBySerialNumber("207000159205");

GetCameraByIpAddress通过IP获取相机

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

CameraCapture.GetCameraByIpAddress("192.168.6.50");

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

该接口用于通过相机的信息获取相机对象。

// 初始化
CameraUtils.InitChannel();
// 发现所有相机
CameraCapture camera = null;
var deviceList = CameraUtils.DiscoverCameras();
foreach (var list in deviceList)
{
     // 输出每个相机的信息
     Console.WriteLine($"序列号: {list.Sn}, 型号: {list.ModelName}, IP: {list.NetworkInfo.Ip}");
     if (list.Sn == "207000163420")
     {
         cc = CameraCapture.GetCameraByDeviceInfo(list);
         Console.WriteLine($"找到目标相机: {list.ModelName}");
         break;
     }
 }

Camera类

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

GetCameraInfo获取相机信息

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

// 初始化通道
CameraUtils.InitChannel();
// 发现相机
var deviceList = CameraUtils.DiscoverCameras();
if (deviceList.Count == 0)
{
    Console.WriteLine("未发现任何相机！");
    return;
}
// 连接相机并获取详细信息
foreach (var camInfo in deviceList)
{
    // 创建相机实例
    CameraCapture cc = CameraCapture.GetCameraByDeviceInfo(camInfo);

    // 连接相机
    CameraApiStatus connectStatus = cc.Connect();
    if (connectStatus != CameraApiStatus.Success)
    {
        Console.WriteLine($"连接相机 {camInfo.Sn} 失败: {connectStatus}");
        continue;
    }
    // 使用 GetCameraInfo 获取相机信息
    CameraInfo detailedInfo;
    CameraApiStatus infoStatus = cc.GetCameraInfo(out detailedInfo);
    if (infoStatus == CameraApiStatus.Success)
    {
        Console.WriteLine("\n====== 相机详细信息 ======");
        Console.WriteLine($"   型号: {detailedInfo.ModelName}");
        Console.WriteLine($"   序列号: {detailedInfo.Sn}");
        Console.WriteLine($"   IP地址: {detailedInfo.NetworkInfo.Ip}");
        Console.WriteLine($"   名称: {detailedInfo.Name}");
        Console.WriteLine($"   厂商: {detailedInfo.VendorName}");
        Console.WriteLine($"   固件版本: {detailedInfo.FirmwareVersion}");
        Console.WriteLine($"   状态: {detailedInfo.State}");
        // 网络信息
        Console.WriteLine($"   MAC地址: {detailedInfo.NetworkInfo.Mac}");
        Console.WriteLine($"   子网掩码: {detailedInfo.NetworkInfo.Netmask}");
        Console.WriteLine($"   网关: {detailedInfo.NetworkInfo.Gateway}");
        // 接口信息
        Console.WriteLine($"   接口类型: {detailedInfo.InterfaceInfo.InterfaceType}");
        Console.WriteLine($"   接口名称: {detailedInfo.InterfaceInfo.Name}");
    }
    else
    {
        Console.WriteLine($"获取相机 {camInfo.Sn} 详细信息失败: {infoStatus}");
    }
    // 断开连接
    cc.Disconnect();
}

Connect连接设备

用于连接设备。

cc.Connect();

Disconnect断连设备

用于断连设备。

cc.Disconnect();

GetCameraState获取相机状态

用于获取相机状态。

var status = cc.Connect();
if (status != CameraApiStatus.Success)
{
    Console.WriteLine($"连接相机失败: {status}");
    return;
}

StartCapture开始采集图像

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

cc.StartCapture();

StopCapture停止采集图像

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

cc.StopCapture();

GetFeature获取待设置的参数

用于获取待设置的参数。

重要

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

CameraFeature feature;
CameraApiStatus status=cc.GetFeature("Left/ExposureTime", out feature);
Console.WriteLine($"GetFeature Left/ExposureTime Status: {status}");

GetAllFeatures获取所有参数

用于获取所有参数。

cc.GetAllFeatures();

FireSoftwareTrigger发送软触发采图信号

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

cc.FireSoftwareTrigger();

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

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

List<ImageMode> image_modes = cc.GetImageModes(SensorType.IrRight, out status);
if (status != CameraApiStatus.Success)
{
    Console.WriteLine($"GetImageModes failed : {status}");
}
else
{
    foreach (var mode in image_modes)
    {
        Console.WriteLine($"ImageModePixelFormat : {mode.RawPixelFormat} , ImageModeWidth : {mode.Width} , ImageModeHeight : {mode.Height}");
      }
}

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

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

var currentMode = cc.GetCurrentImageMode(SensorType.IrLeft, out status);
Console.WriteLine($"ImageModePixelFormat : {currentMode.RawPixelFormat} , ImageModeWidth : {currentMode.Width} , ImageModeHeight : {currentMode.Height}");

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

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

ImageMode image_mode = new ImageMode();
image_mode.RawPixelFormat = RawPixelFormat.JPEG;
image_mode.Width = 640;
image_mode.Height = 480;
status= cc.SetImageMode(SensorType.Rgb, image_mode);
Console.WriteLine($"设置图像格式和分辨率 {status}");

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

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

//读取相机支持的传感器
var sensorTypes = Enum.GetValues(typeof(SensorType)).Cast<SensorType>();
foreach (var sensorType in sensorTypes)
{
if (cc.HasSensor(sensorType))
        {
          Console.WriteLine($"Support sensors: {sensorType}");
        }
}

有以下几种传感器：

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

IsSensorEnabled获取传感器使能状态

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

//读取相机所支持传感器的使能状态
var sensorTypes = Enum.GetValues(typeof(SensorType)).Cast<SensorType>();
foreach (var sensorType in sensorTypes)
{
     if (cc.HasSensor(sensorType))
     {
            bool enabled;
             status = cc.IsSensorEnabled(sensorType, out enabled);
             if (status == CameraApiStatus.Success)
                    {
                        Console.WriteLine($"Sensor {sensorType}: {(enabled ? "Enabled" : "Disabled")}");
                    }
         }
}

SetSensorEnabled设置传感器使能状态

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

CameraApiStatus status = cc.SetSensorEnabled(SensorType.Depth, true);
if (status != CameraApiStatus.Success)
{
    Console.WriteLine($"Failed to set sensor enabled: {status}");
    return;
}

SetUndistortionEnabled启用或禁用畸变矫正

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

cc.SetUndistortionEnabled(SensorType.Rgb, true);

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

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

bool isEnabled;
CameraApiStatus status = cc.IsMapDepthToColorEnabled(out isEnabled);

if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"Depth-to-color mapping: {(isEnabled ? "Enabled" : "Disabled")}");
}
else
{
    Console.WriteLine($"Failed to check depth-to-color mapping status: {status}");
}

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

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

status = cc.SetMapDepthToColorEnabled(true);
if (status != CameraApiStatus.Success)
{
    Console.WriteLine($"Failed to enable MapDepthToColor: {status}");
    return;
}

RegisterFrameSetCallback图像回调函数

图像回调函数。

RegisterCameraEventCallback相机事件回调函数

相机事件回调函数。

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

注册属性变化回调函数。

UserSetManager类

GetAllUserSets获取所有用户设置

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

var userSetMgr = cc.GetUserSetManager();
var userSets = new List<UserSet>();
status = userSetMgr.GetAllUserSets(userSets);
Console.WriteLine("Available User Sets:");
for (int i = 0; i < userSets.Count; i++)
{
    Console.WriteLine($"  [{i}] {userSets[i].Name}");
}

SaveToUserSet保存到用户设置

将当前相机的所有参数设置保存到指定的用户配置集。

var userSetMgr = cc.GetUserSetManager();
status = userSetMgr.SaveToUserSet("Default");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine("配置已保存到 Default 配置集");
}
else
{
    Console.WriteLine($"保存失败: {status}");
}

SaveToUserSetWithNewName重命名用户设置

将现有配置集保存为新的名称，实现配置集的重命名。

var userSetMgr = cc.GetUserSetManager();
status = userSetMgr.SaveToUserSetWithNewName("MyCustomConfig", "9876");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine("配置已保存为 9876");
}

LoadUserSet加载用户设置

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

// 获取用户配置集管理器
var userSetMgr = cc.GetUserSetManager();
CameraApiStatus status = userSetMgr.LoadUserSet("HighAccuracy");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine("已加载高精度模式配置");
}
else
{
    Console.WriteLine($"加载配置集失败: {status}");
}

CurrentUserSet读取当前用户设置

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

// 获取用户配置集管理器
var userSetMgr = cc.GetUserSetManager();
// 获取当前用户设置
string currentUserSet;
status = userSetMgr.CurrentUserSet(out currentUserSet);
if (status == CameraApiStatus.Success)
{
         if (string.IsNullOrWhiteSpace(currentUserSet))
{
         Console.WriteLine("当前未设置用户配置集");
        }
else
           {
            Console.WriteLine($"当前用户设置: {currentUserSet}");
           }
}
else
            {
                Console.WriteLine($"获取当前用户设置失败: {status}");
            }

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

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

var userSetMgr = cc.GetUserSetManager();
// 获取当前的开机自启动配置集
string powerOnUserSet;
status = userSetMgr.GetPowerOnUserSet(out powerOnUserSet);
if (status == CameraApiStatus.Success)
{
    if (string.IsNullOrEmpty(powerOnUserSet))
    {
        Console.WriteLine("当前未设置开机自启动配置集");
    }
    else
    {
        Console.WriteLine($"当前开机自启动配置集: {powerOnUserSet}");
    }
}
else
{
    Console.WriteLine($"获取开机配置集失败: {status}");
}

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

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

string optimizedConfig = "HighAccuracy";
status = userSetMgr.SetPowerOnUserSet(optimizedConfig);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"设备已配置为开机自动加载 '{optimizedConfig}' 模式");
}

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检查属性是否有效

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

CameraFeature feature;
CameraApiStatus ret = cc.GetFeature("DepthScaleUnit", out feature);

bool isValid = feature.IsValid();
if (isValid)
{
    Console.WriteLine("\u001b[92m Feature is valid and available\u001b[0m");
}

FullName获取属性的完整名称

//获取属性的完整路径名称，通常包含分组信息
CameraFeature feature;
cc.GetFeature("DepthSgbmUniqueMaxCost", out feature);
string fullName = feature.FullName;
Console.WriteLine($"完整名称: {fullName}");

GetType获取相机属性类型

CameraFeature feature;
string Feature = "AcquisitionMode";
cc.GetFeature(Feature, out feature);
FeatureType type = feature.FeatureType;
Console.WriteLine($"{Feature} FeatureType is {type}");

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

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

GetAccessMode读取相机属性权限

CameraFeature feature;
CameraApiStatus ret = cc.GetFeature("Depth/ExposureTime", out feature);
CameraFeatureAccessMode access_mode;
ret = feature.GetAccessMode(out access_mode);
if (ret == CameraApiStatus.Success)
{
        Console.WriteLine($"Depth/ExposureTime AccessMode : {access_mode}");
}

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

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

值操作方法

GetValue获取属性的当前值

整型属性

CameraFeature feat;
cc.GetFeature("DepthSgbmTextureFilterValueOffset", out feat);
CameraValue currentValue;
feat.GetValue(out currentValue);
Console.WriteLine($"Left/ExposureTime 当前值: {currentValue.SingleValue}");

浮点型属性

CameraFeature feat;
cc.GetFeature("Left/ExposureTime", out feat);
CameraValue currentValue;
feat.GetValue(out currentValue);
Console.WriteLine($"Left/ExposureTime 当前值: {currentValue.SingleValue}");

枚举型属性

CameraFeature feature;
cc.GetFeature("DeviceLinkHeartbeatMode", out feature);
CameraValue currentValue;
feature.GetValue(out currentValue);
Console.WriteLine($"DeviceLinkHeartbeatMode 当前值: {currentValue.SingleValue}");

布尔型属性

CameraFeature feat;
cc.GetFeature("Texture/BalanceWhiteAuto", out feat);
feat.SetValue(new CameraValue(CameraValueType.Int64, 31));
CameraValue currentValue;
feat.GetValue(out currentValue);
Console.WriteLine($"Texture/BalanceWhiteAuto 当前值: {currentValue.SingleValue}");

SetValue设置属性值