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.csVcameraSDK-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.csVcameraSDK-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 获取属性的当前值
整型属性
CameraFeature feat; cc.GetFeature("DepthSgbmTextureFilterValueOffset", out feat); CameraValue currentValue; feat.GetValue(out currentValue); Console.WriteLine($"DepthSgbmTextureFilterValueOffset Current value: {currentValue.SingleValue}");浮点型属性
CameraFeature feat; cc.GetFeature("Left/ExposureTime", out feat); CameraValue currentValue; feat.GetValue(out currentValue); Console.WriteLine($"Left/ExposureTime Current value: {currentValue.SingleValue}");枚举型属性
CameraFeature feature; cc.GetFeature("DeviceLinkHeartbeatMode", out feature); CameraValue currentValue; feature.GetValue(out currentValue); Console.WriteLine($"DeviceLinkHeartbeatMode Current value: {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 Current value: {currentValue.SingleValue}");
SetValue 设置属性值
整型属性
CameraFeature feat; cc.GetFeature("DepthSgbmTextureFilterValueOffset", out feat); status = feat.SetValue(50); Console.WriteLine($"SetValue: {status}");浮点型属性
CameraFeature feat; cc.GetFeature("Left/ExposureTime", out feat); status = feat.SetValue(31); Console.WriteLine($"SetValue: {status}");枚举型属性
CameraFeature feat; cc.GetFeature("TriggerSource", out feat); status = feat.SetValue(0); Console.WriteLine($"SetValue: {status}");布尔型属性
CameraFeature feat; cc.GetFeature("IRUndistortion", out feat); status = feat.SetValue(true); Console.WriteLine($"SetValue: {status}");
范围查询方法
GetRange 获取整型属性的值范围
整型属性
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}"); }浮点型属性
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}");
}