API 详解 (C#)

GetVersionString 获取 VCameraSDK 版本

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

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

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

Init 初始化 SDK

初始化 SDK 通信库。

CameraUtils.Init(true);

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

DiscoverCameras 发现相机设备

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

CameraUtils.DiscoverCameras();

SetIpAddress 设置静态 IP

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

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

string mac = "06:20:FD:B6:D4:95";
string ip = "192.168.6.119";
string mask = "255.255.255.0";
string gateway = "192.168.6.1";
status = CameraUtils.SetIpAddress(mac, ip, mask, gateway);
if (status != CameraApiStatus.Success) {
    Console.WriteLine($"Force Device IP failed :{ status}");
    return;
}
else
{
    Console.WriteLine($"Force Device IP success :{status}");
    eturn;
}

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

var camInfos = CameraUtils.DiscoverCameras();
foreach (var camInfo in camInfos)
{
    Console.WriteLine($"Found camera: {camInfo.ModelName}, SN: {camInfo.Sn}, IP: {camInfo.NetworkInfo.Ip}");
    if(camInfo.Sn == "207000159118")
    {
        status = CameraUtils.SetIpAddress(camInfo,"192.168.6.119","255.255.255.0","192.168.6.1");
        if (status != CameraApiStatus.Success)
        {
            Console.WriteLine($"Force Device IP failed :{status}");
            return;
        }else
        {
            Console.WriteLine($"Force Device IP success :{status}");
            return;
        }
    }
}

SetDeviceDhcp 设置动态 IP

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

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

string mac = "06:20:FD:B6:D4:95";
status = CameraUtils.SetIpToDynamic(mac);
if (status != CameraApiStatus.Success) {
    Console.WriteLine($"Force Device IP failed :{ status}");
    return;
}else
{
    Console.WriteLine($"Force Device IP success :{status}");
    return;
}

第二种,传入相机的 CamInfo。

var camInfos = CameraUtils.DiscoverCameras();
foreach (var camInfo in camInfos)
{
    Console.WriteLine($"Found camera: {camInfo.ModelName}, SN: {camInfo.Sn}, IP: {camInfo.NetworkInfo.Ip}");
    if(camInfo.Sn == "207000159118")
    {
        status = CameraUtils.SetIpToDynamic(camInfo);
        if (status != CameraApiStatus.Success)
        {
            Console.WriteLine($"Force Device IP failed :{status}");
            return;
        } else
        {
            Console.WriteLine($"Force Device IP success :{status}");
            return;
        }
    }

CameraCapture 类

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

GetCameraBySerialNumber 通过序列号获取相机

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

CameraCapture.GetCameraBySerialNumber("207000159205");

GetCameraByIpAddress 通过 IP 获取相机

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

CameraCapture.GetCameraByIpAddress("192.168.6.50");

GetCameraByDeviceInfo 通过相机信息获取相机

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

var camInfos = CameraUtils.DiscoverCameras();
CameraCapture cc = null;
foreach (var camInfo in camInfos)
{
    Console.WriteLine($"Found camera: {camInfo.ModelName}, SN: {camInfo.Sn}, IP: {camInfo.NetworkInfo.Ip}");
    if (camInfo.Sn == "207000159118")
    {
        cc = CameraCapture.GetCameraByDeviceInfo(camInfo);
    }
}

Connect 连接设备

用于连接设备。

cc.Connect();

Disconnect 断连设备

用于断连设备。

cc.Disconnect();

GetCameraState 获取相机状态

获取设备当前状态,需要在连接相机后调用。

cc = CameraCapture.GetCameraByDeviceInfo(camInfo);
cc.Connect();
CameraState camerastatus;
cc.GetCameraState(out camerastatus);
Console.WriteLine($"CameraState : {camerastatus}");

GetCameraInfo 获取相机信息

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

var camInfos = CameraUtils.DiscoverCameras();
CameraCapture cc = null;
foreach (var camInfo in camInfos)
{
    cc = CameraCapture.GetCameraByDeviceInfo(camInfo);
    CameraApiStatus connectStatus = cc.Connect();
    if (connectStatus != CameraApiStatus.Success)
    {
        Console.WriteLine($"Connect the camera {camInfo.Sn} Failure: {connectStatus}");
        continue;
    }
    CameraInfo detailedInfo;
    CameraApiStatus infoStatus = cc.GetCameraInfo(out detailedInfo);
    if (infoStatus == CameraApiStatus.Success)
    {
        Console.WriteLine("\n====== Camera details ======");
        Console.WriteLine($"   Model number: {detailedInfo.ModelName}");
        Console.WriteLine($"   Serial Number: {detailedInfo.Sn}");
        Console.WriteLine($"   IP address: {detailedInfo.NetworkInfo.Ip}");
        Console.WriteLine($"   Name: {detailedInfo.Name}");
        Console.WriteLine($"   VendorName: {detailedInfo.VendorName}");
        Console.WriteLine($"   FirmwareVersion: {detailedInfo.FirmwareVersion}");
        Console.WriteLine($"   State: {detailedInfo.State}");
        Console.WriteLine($"   Mac: {detailedInfo.NetworkInfo.Mac}");
        Console.WriteLine($"   Netmask: {detailedInfo.NetworkInfo.Netmask}");
        Console.WriteLine($"   Gateway: {detailedInfo.NetworkInfo.Gateway}");
        Console.WriteLine($"   InterfaceType: {detailedInfo.InterfaceInfo.InterfaceType}");
        Console.WriteLine($"   InterfaceName: {detailedInfo.InterfaceInfo.Name}");
    }
    else
    {
        Console.WriteLine($"Get the camera {camInfo.Sn} Details failed: {infoStatus}");
    }
    cc.Disconnect();
}
if (camInfos.Count == 0)
{
    Console.WriteLine("No camera found!");
    return;
}

StartCapture 开始采集图像

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

cc.StartCapture();

StopCapture 停止采集图像

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

cc.StopCapture();

GetFeature 获取待设置的参数

用于获取待设置的参数。

重要

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

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

GetAllFeatures 获取所有参数

用于获取所有参数。

cc.GetAllFeatures();

FireSoftwareTrigger 发送软触发采图信号

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

cc.FireSoftwareTrigger();

IsSupportGenicam 判断相机是否符合 GenICam 标准

判断相机是否符合GenICam标准,若返回True,则表示该相机符合GenICam标准。

CameraApiStatus ret = CameraApiStatus.Success;
cc = CameraCapture.GetCameraByDeviceInfo(camInfo);
ret = cc.Connect();
if(ret == CameraApiStatus.Success)
{
    bool isSupport = cc.IsSupportGenicam(out status);
    if (status == CameraApiStatus.Success)
    {
        if (isSupport)
        {
            Console.WriteLine("Support GenICam");
        }
        else
        {
            Console.WriteLine("Not Support GenICam");
        }
    }
    else
    {
        Console.WriteLine($" IsSupportGenicam API call : {status}");
    }
}

GetImageModes 获取图像格式和分辨率

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

List<ImageMode> image_modes = cc.GetImageModes(SensorType.Right, 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.Left, out status);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"Current ImageModePixelFormat : {currentMode.RawPixelFormat} , ImageModeWidth : {currentMode.Width} , ImageModeHeight : {currentMode.Height}");
}
else
{
    Console.WriteLine($"GetCurrentImageMode API call : {status}");
}

SetImageMode 设置图像格式和分辨率

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

List<ImageMode> image_modes = cc.GetImageModes(SensorType.Texture, 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}");
    }
}
status = cc.SetImageMode(SensorType.Texture, image_modes[1]);
if(status == CameraApiStatus.Success)
{
    Console.WriteLine($"SetImageMode : {status}");
}
else
{
    Console.WriteLine($"SetImageMode : {status}");
}

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

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

bool hasSensor = cc.HasSensor(SensorType.Right);
if (hasSensor) {
    Console.WriteLine($"This camera has Right");
}
else
{
    Console.WriteLine($"This camera does not have Right");
}

IsSensorEnabled 获取传感器使能状态

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

bool enabled;
status = cc.IsSensorEnabled(SensorType.Right, out enabled);
if (status == CameraApiStatus.Success) {
    Console.WriteLine($"Depth is {(enabled ? "Enabled": "Disabled")}");
}
else
{
    Console.WriteLine($"IsSensorEnabled API call : {status}");

}

SetSensorEnabled 设置传感器使能状态

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

status = cc.SetSensorEnabled(SensorType.Depth, true);
if (status != CameraApiStatus.Success)
{
    Console.WriteLine($"SetSensorEnabled API call : {status}");
}
else
{
    Console.WriteLine($"SetSensorEnabled {status}");
}

SetUndistortionEnabled 启用或禁用畸变矫正

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

cc.SetUndistortionEnabled(SensorType.Texture, true);

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

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

bool en = false;
cc.IsMapDepthToTextureEnabled(out en);
Console.WriteLine($"IsMapDepthToTextureEnabled: {en}");

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

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

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

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

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

注解

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

  • Gige_2_0 相机:仅保存相机连接后修改的参数。连接前已保存的参数不会被记录。

  • Gige_2_1 相机:会尽可能保存全部参数。具体保存的参数列表请参考安装路径下的 doc/feature_save_gige2_1.txt

保存配置到文件:

string filePath = "1.json";
status = cc.SaveFeaturesToFile(filePath);

从文件加载配置:

string error_message = "";
// We strongly recommend to use path only including ASCII characters.
string file_path_load = "1.json";
status = cc.LoadFeaturesFromFile(file_path_load, ref error_message);

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

  • VcameraSDK-X.X.X/csharp/net48/example/SaveFeaturesToFile/Program.cs

  • VcameraSDK-X.X.X/csharp/net48/example/LoadFeaturesFromFile/Program.cs

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

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

注解

  • 该接口仅适用于 Gige_2_0 相机 。

  • 对于 Gige_2_1 相机,请使用 UserSetManager类 接口。

保存配置到内部存储区:

status = cc.SaveFeaturesToStorage();

从内部存储区加载配置:

string error_message = "";
status = cc.LoadFeaturesFromStorage(ref error_message);

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

  • VcameraSDK-X.X.X/csharp/net48/example/SaveFeaturesToStorage/Program.cs

  • VcameraSDK-X.X.X/csharp/net48/example/LoadFeaturesFromStorage/Program.cs

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("Save success");
}
else
{
    Console.WriteLine($"SaveToUserSet API call : {status}");
}

SaveToUserSetWithNewName 重命名用户设置

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

var userSetMgr = cc.GetUserSetManager();
status = userSetMgr.SaveToUserSetWithNewName("Default", "MyCustomConfig");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"SaveToUserSetWithNewName : {status}");
}

LoadUserSet 加载用户设置

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

var userSetMgr = cc.GetUserSetManager();
status = userSetMgr.LoadUserSet("Standard");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"LoadUserSet : {status}");
}
else
{
    Console.WriteLine($"LoadUserSet API call : {status}");
}

CurrentUserSet 读取当前用户设置

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

var userSetMgr = cc.GetUserSetManager();
string currentUserSet;
status = userSetMgr.CurrentUserSet(out currentUserSet);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"Get CurrentUserSet {status} , currentuserset is {currentUserSet}");
}
else
{
    Console.WriteLine($"CurrentUserSet API call : {status}");
}

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

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

var userSetMgr = cc.GetUserSetManager();
string powerOnUserSet;
status = userSetMgr.GetPowerOnUserSet(out powerOnUserSet);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"GetPowerOnUserSet : {status} ,name is {powerOnUserSet}");
}
else
{
    Console.WriteLine($"GetPowerOnUserSet API call : {status}");
}

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

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

var userSetMgr = cc.GetUserSetManager();
status = userSetMgr.SetPowerOnUserSet("Standard");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"SetPowerOnUserSet : {status}");
}
else
{
    Console.WriteLine($"SetPowerOnUserSet API call : {status}");
}

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;
status = cc.GetFeature("DepthScaleUnit", out feature);
bool isValid = feature.IsValid();
Console.WriteLine($"Feature is {(isValid ? "Valid" : "Invalid")}");

FullName 获取属性的完整名称

CameraFeature feature;
status = cc.GetFeature("Left/ExposureTime", out feature);
bool isValid = feature.IsValid();
Console.WriteLine($"Feature is {(isValid ? "Valid" : "Invalid")}");
string fullName = feature.FullName;
Console.WriteLine($"{fullName}");

FeatureType 获取相机属性类型

CameraFeature feature;
status = cc.GetFeature("Left/ExposureTime", out feature);
bool isValid = feature.IsValid();
Console.WriteLine($"Feature is {(isValid ? "Valid" : "Invalid")}");
FeatureType type = feature.FeatureType;
Console.WriteLine($"FeatureType is {type}");

GetAccessMode 读取相机属性权限

CameraFeature feature;
status = cc.GetFeature("DepthScaleUnit", out feature);
bool isValid = feature.IsValid();
Console.WriteLine($"Feature is {(isValid ? "Valid" : "Invalid")}");
CameraFeatureAccessMode access_mode;
status = feature.GetAccessMode(out access_mode);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"AccessMode is {access_mode}");
}

值操作方法

GetValue 获取属性的当前值

  1. 整型属性

    CameraFeature feat;
    cc.GetFeature("DepthSgbmTextureFilterValueOffset", out feat);
    CameraValue currentValue;
    feat.GetValue(out currentValue);
    Console.WriteLine($"DepthSgbmTextureFilterValueOffset Current value: {currentValue.SingleValue}");
    
  2. 浮点型属性

    CameraFeature feat;
    cc.GetFeature("Left/ExposureTime", out feat);
    CameraValue currentValue;
    feat.GetValue(out currentValue);
    Console.WriteLine($"Left/ExposureTime Current value: {currentValue.SingleValue}");
    
  3. 枚举型属性

    CameraFeature feature;
    cc.GetFeature("DeviceLinkHeartbeatMode", out feature);
    CameraValue currentValue;
    feature.GetValue(out currentValue);
    Console.WriteLine($"DeviceLinkHeartbeatMode Current value: {currentValue.SingleValue}");
    
  4. 布尔型属性

    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 Current value: {currentValue.SingleValue}");
    

SetValue 设置属性值

  1. 整型属性

    CameraFeature feat;
    cc.GetFeature("DepthSgbmTextureFilterValueOffset", out feat);
    status = feat.SetValue(50);
    Console.WriteLine($"SetValue: {status}");
    
  2. 浮点型属性

    CameraFeature feat;
    cc.GetFeature("Left/ExposureTime", out feat);
    status = feat.SetValue(31);
    Console.WriteLine($"SetValue: {status}");
    
  3. 枚举型属性

    CameraFeature feat;
    cc.GetFeature("TriggerSource", out feat);
    status = feat.SetValue(0);
    Console.WriteLine($"SetValue: {status}");
    
  4. 布尔型属性

    CameraFeature feat;
    cc.GetFeature("IRUndistortion", out feat);
    status = feat.SetValue(true);
    Console.WriteLine($"SetValue: {status}");
    

范围查询方法

GetRange 获取整型属性的值范围

  1. 整型属性

    CameraFeature feat;
    status = cc.GetFeature("DepthSgbmTextureFilterValueOffset", out feat);
    Int64Range range;
    CameraApiStatus ret = feat.GetRange(out range);
    if (ret == CameraApiStatus.Success)
    {
        Console.WriteLine($"GetRange success : [{range.Min}, {range.Max}], Step: {range.Step}");
    }
    
  2. 浮点型属性

    CameraFeature feat;
    status = cc.GetFeature("Left/ExposureTime", out feat);
    Float64Range range;
    CameraApiStatus ret = feat.GetRange(out range);
    if (ret == CameraApiStatus.Success)
    {
        Console.WriteLine($"GetRange success : [{range.Min}, {range.Max}], Step: {range.Step}");
    }
    

枚举型方法

GetEnumItems 获取枚举型属性的所有枚举项

CameraFeature feature;
status = cc.GetFeature("DeviceTimeSyncMode", out feature);
if(status == CameraApiStatus.Success)
{
    List<EnumItem> enum_list = new List<EnumItem>();
    status = feature.GetEnumItems(enum_list);
    if (status == CameraApiStatus.Success)
    {
        foreach (var item in enum_list)
        {
            Console.WriteLine($"Name: {item.Name}, Value: {item.Value}");
        }
    }
    else
    {
        Console.WriteLine($"GetEnumItems failed: {status}");
    }
}
else
{
    Console.WriteLine($"GetFeature {status}");
}