LDVisionCamera.Net 1.2.0

LDVisionCamera.NET

LDVisionCamera 工业相机 .NET SDK —— 西安立鼎光电科技有限公司出品。

GigE Vision / USB3 Vision / GenTL（Camera Link、CoaXPress 采集卡）三类相机走同一套 API： 发现、连接、参数读写、采集、图像处理。包内自带各平台原生库，引用即用，目标机无需另装运行时。

安装

dotnet add package LDVisionCamera.Net

## 快速上手

using LDVisionCamera;

// 1. 发现设备（GigE / U3V / GenTL 统一列表，DeviceType 区分）
var devices = Ldv.EnumerateDevices(1000);
if (devices.Count == 0) return;

// 2. 打开（也可 Ldv.CreateCamera("192.168.1.10") 或序列号直连）
using var cam = Ldv.CreateCamera(devices[0]);
cam.Open();
cam.Disconnected += (s, e) => Console.WriteLine($"相机断开: 0x{e.ExceptionType:X4}");

// 3. 参数
cam.ExposureTime = 10000.0;              // µs（SFNC 便捷属性）
cam.Gain = 2.0;                          // dB
cam.SetEnum("TriggerMode", "Off");       // 按名通用写

// 4. 采集
cam.StartGrabbing();
using (Frame frame = cam.GrabFrame(2000))   // 超时 ms
{
    Console.WriteLine($"帧 {frame.FrameId}: {frame.Width}x{frame.Height}");
    ImageProcessing.Save(frame, "shot.png", LDV_ImageFormat_t.LDV_IMAGE_PNG);
}
cam.StopGrabbing();

三个入口

Ldv —— SDK 级操作（不针对某台相机）

全部成员：

// 版本与 ABI
Console.WriteLine(Ldv.SdkVersion);       // 如 "1.0.0-rc.27"
Console.WriteLine(Ldv.SdkBuildDateUtc);  // 原生 SDK 构建时间（UTC）
Ldv.EnsureAbiCompatible();               // 校验托管层与原生库 ABI 匹配（不匹配抛异常）

// 日志：将 SDK 内部日志接入调用方自有日志系统
Ldv.SetLogLevel(2);                                      // 级别阈值
Ldv.SetLogCallback((level, msg) => MyLogger.Write(msg));

// 错误码翻译
string text = Ldv.ErrorString(-10);      // 错误码 → 可读文本
string last = Ldv.LastError();           // 最近一次错误详情

// 设备发现与创建（三种创建方式）
IReadOnlyList<LdvDeviceInfo> devs = Ldv.EnumerateDevices(1000);   // 超时 ms
LdvCamera cam1 = Ldv.CreateCamera(devs[0]);            // ① 由枚举信息创建（推荐）
LdvCamera cam2 = Ldv.CreateCamera("192.168.1.10");     // ② 由 IP 直连
LdvCamera cam3 = Ldv.CreateCamera("SN12345678");       // ③ 由序列号直连

// 连接前可达性探测：是否可连接、是否已被其它程序占用
LDV_AccessState_t st = Ldv.IsDeviceAccessible("192.168.1.10");

// 相机 IP 与本机网卡不同网段时，强制改相机 IP（GigE）
Ldv.ForceIp("00:11:22:33:44:55", "192.168.1.10", "255.255.255.0", "192.168.1.1");

// GenTL：接入采集卡厂商的相机（Camera Link / CoaXPress）
Ldv.GentlAddProducer(@"C:\vendor\xxx.cti");            // 手动注册厂商 Producer
Ldv.GentlRemoveProducer(@"C:\vendor\xxx.cti");
IReadOnlyList<string> producers = Ldv.GentlProducers();  // 当前已注册的 Producer

未手动注册时，SDK 也会自动扫描环境变量 GENICAM_GENTL64_PATH 下的 .cti。

参数读写

以下均为 LdvCamera（cam）实例上的操作。参数有两种访问方式，先介绍较简单的一种：

方式一：便捷属性 —— 常用参数直接读写

与普通 C# 属性用法一致，赋值即写、取值即读：

cam.ExposureTime = 10000.0;          // 写：设为 10000 µs
double us = cam.ExposureTime;        // 读：返回当前值 10000.0

cam.Gain = 2.0;                      // 写增益（dB）
cam.Width = 1920;                    // 写分辨率
cam.TriggerMode = LDV_TriggerMode_t.LDV_TRIGGER_ON;

可用的便捷属性：

相机不支持某能力时，读写对应属性会抛 LdvException。

方式二：按名读写 —— 任意 GenICam 参数

便捷属性只覆盖常用项。相机 XML 里的任意参数都可以按名访问，读取分三档：

// ① 只要当前值
long   w    = cam.GetInt("Width");
double exp  = cam.GetFloat("ExposureTime");
bool   on   = cam.GetBool("AcquisitionFrameRateEnable");
string mode = cam.GetEnumString("TriggerMode");        // "Off"

// ② 当前值 + 范围 / 步进 —— 用于数值输入框、滑块
FloatParam e = cam.GetFloatParam("ExposureTime");
Console.WriteLine($"{e.Value} ∈ [{e.Min}, {e.Max}] step {e.Inc}, 小数位 {e.DisplayPrecision}");

IntParam iw = cam.GetIntParam("Width");
Console.WriteLine($"{iw.Value} ∈ [{iw.Min}, {iw.Max}] step {iw.Inc}, repr {iw.Representation}");

// ③ 当前值 + 全部支持项 —— 用于下拉框
EnumParam p = cam.GetEnumParam("PixelFormat");
foreach (EnumEntry entry in p.Entries)
    Console.WriteLine($"{entry.Name} = {entry.Value}");   // Mono8=17301505, ...
Console.WriteLine($"当前: {p.CurrentValue}");

Min / Max / Inc 仅整数和浮点类型具备；枚举提供可选项列表，字符串提供 MaxLength。

写入

cam.SetInt("Width", 1920);
cam.SetFloat("ExposureTime", 5000.0);
cam.SetBool("AcquisitionFrameRateEnable", true);
cam.SetEnum("TriggerMode", "On");            // 按符号名（推荐）
cam.SetEnum("TriggerMode", 1u);              // 或按数值
cam.SetStringParam("DeviceUserID", "cam-01");
cam.ExecuteCommand("TriggerSoftware");       // Command 节点

查询相机支持哪些参数

// 平铺目录
foreach (var item in cam.GetParameterCatalog())
    Console.WriteLine($"[{item.Kind}] {item.Name}  ({item.Category})");

// 树形浏览（用于构建属性树界面）
var root = cam.GetRootParameterNode();
foreach (var child in cam.GetParameterChildren(root))
    Console.WriteLine(child.Name);

// 单个节点的完整信息（显示名、单位、提示、可见性…）
ParamFeature f = cam.GetParameterFeature("ExposureTime");

// 当前是否可写（NI=无此特性 / NA=当前不可用 / RO / RW）
var mode = cam.GetParameterAccessMode("ExposureTime");

GetParameterAccessMode 是「此刻能否写」的权威判据——相机的联动约束（如自动曝光开启时 ExposureTime 只读）都体现在这里，UI 灰显请以它为准。

采集

// ① 主动取帧
cam.StartGrabbing();
using (Frame frame = cam.GrabFrame(2000)) { /* ... */ }

// ② 事件回调（帧到达即触发，请勿在回调中执行耗时操作）
cam.FrameReceived += (s, e) => {
    var f = e.Frame;
    Console.WriteLine($"{f.FrameId} {f.Width}x{f.Height}");
};
cam.StartGrabbing();

// ③ 触发采集
cam.SetEnum("TriggerMode", "On");
cam.SetEnum("TriggerSource", "Software");
cam.ExecuteCommand("TriggerSoftware");

// 采集质量监控（丢包/丢帧统计）
GrabStats st = cam.GetGrabStats();
Console.WriteLine($"完整 {st.FramesComplete} / 缺包丢弃 {st.FramesIncomplete} / 净丢包 {st.NetLostPackets}");

获取帧的像素数据

using (Frame f = cam.GrabFrame(2000))
{
    byte[] data = f.ToArray();        // ① 复制一份（简单、安全）
    IntPtr ptr  = f.DataPointer;      // ② 直接使用指针（零拷贝，仅在 using 块内有效）
    int len     = f.Length;

    if (f.IsIncomplete)               // 缺包导致的不完整帧
        Console.WriteLine($"缺失 {f.LostPackets} 个包");
}   // 离开 using 块后帧归还 SDK 缓冲池——不得在块外继续使用 DataPointer

Frame 的元数据：Width / Height / OffsetX / OffsetY / PixelFormat / FrameId / FrameCounter / DeviceTimestampNs / HostTimestampNs / IsIncomplete / LostPackets / ExpectedPayloads / ReceivedPayloads 等。

务必使用 using（或手动 Dispose）。帧使用的是 SDK 缓冲池，不释放将耗尽该池并导致丢帧。

组播：让多个程序同时收同一路图像（GigE）

一台采集、一台质检看同一路流，不用转发、不加延迟：控制方把流推到组播组，其余进程以 「只接收」角色加入该组。

// —— 控制方（照常打开，多设一行）——
cam.Open();
cam.SetStreamDestination("239.192.1.1", 1042);   // 下次 StartGrabbing 生效
cam.StartGrabbing();

// —— 只接收方（另一个进程，可能在另一台机器上）——
var (group, port) = Ldv.ProbeStreamMulticast("192.168.1.10");  // 先问相机在往哪儿发
if (group != null)
{
    using var viewer = Ldv.CreateCamera("192.168.1.10");
    viewer.OpenAsListener(group, port);          // 不申请控制权、不写任何寄存器
    viewer.StartGrabbing();                      // 收流与普通相机一模一样
    using Frame f = viewer.GrabFrame(2000);
}

只接收角色读参数照常（"控制方现在设的什么曝光"），但一切写操作抛 LdvException （ACCESS_DENIED），GetParameterAccessMode 也一律报只读——界面据此置灰即可。

组播下 SDK 会强制关闭包大小协商与 GVSP 重传（前者会把整路流量从组地址临时切走、 打断所有其它接收方）。包大小请在切组播之前谈好。 传 null 给 SetStreamDestination 即回到单播（默认）。

错误处理

所有失败都抛 LdvException，带原生错误码：

try
{
    cam.Open();
    cam.SetFloat("ExposureTime", 999999.0);   // 超出范围
}
catch (LdvException ex)
{
    Console.WriteLine($"{ex.Message}（错误码 {ex.ErrorCode}）");
    Console.WriteLine(Ldv.ErrorString(ex.ErrorCode));   // 错误码转可读文本
}

设备信息

foreach (LdvDeviceInfo d in Ldv.EnumerateDevices(1000))
{
    Console.WriteLine($"{d.Manufacturer} {d.ModelName} SN={d.SerialNumber}");
    Console.WriteLine($"  类型 {d.DeviceType} 固件 {d.FirmwareVersion}");
    Console.WriteLine($"  GigE: {d.Ip} / {d.Mac} / 网卡 {d.HostNicIp}");
    Console.WriteLine($"  U3V : {d.UsbPath} VID={d.VendorId:X4} PID={d.ProductId:X4}");
}

图像处理与存图 —— ImageProcessing 静态类

全部成员：

Convert / ConvertInto / Save 都有接受 Frame、in LdvFrame 或裸指针的重载； 可选参数 LDV_DemosaicQuality_t demosaic（去马赛克质量）与 LDV_BitAlign_t bitAlign（位对齐）。

// 格式转换（Mono / Bayer / RGB 8-16bit、packed 10p/12p、YUV422，含去马赛克）
byte[] rgb = ImageProcessing.Convert(frame, LDVConstants.LDV_PIXEL_RGB8);

// 高帧率下复用缓冲，避免逐帧分配
byte[] buf = new byte[frame.Width * frame.Height * 3];
int written = ImageProcessing.ConvertInto(frame, LDVConstants.LDV_PIXEL_RGB8, buf);

// 存图：BMP / PNG / TIFF / RAW（位深感知）
ImageProcessing.Save(frame, "out.png", LDV_ImageFormat_t.LDV_IMAGE_PNG);

// 像素格式信息
string name = ImageProcessing.PixelFormatName(frame.PixelFormat);   // "Mono8"
uint bits   = ImageProcessing.PixelFormatBits(frame.PixelFormat);
if (ImageProcessing.TryGetSourceProfile(frame.PixelFormat, out bool isColor, out int srcBits))
    Console.WriteLine($"{(isColor ? "彩色" : "黑白")} {srcBits} bit");

参数存档与恢复

cam.SaveFeatures("profile.txt");                       // 整套参数落盘

FeatureLoadReport r = cam.LoadFeatures("profile.txt"); // 跨设备 / 跨型号批量写入参数
Console.WriteLine($"成功 {r.Applied} / 跳过 {r.Skipped} / 失败 {r.Failed}");

// 需要逐节点明细时
foreach (var entry in cam.LoadFeaturesDetailed("profile.txt"))
    Console.WriteLine($"{entry.Node}: {entry.Outcome}");

相机级其它常用

bool open = cam.IsOpen;            // 是否已打开
cam.Close();                       // 主动关闭（或由 using / Dispose 自动关闭）
float t = cam.Temperature;         // 设备温度 °C
var link = cam.LinkState;          // 链路状态
cam.AutoReconnectWindowMs = 10000; // 断线自动重连窗口 ms；<=0 关闭
cam.Reconnect();                   // 手动重连
cam.InvalidateNodes();             // 相机侧状态发生变化、需使参数缓存失效时

完整示例

随 SDK 交付的 Samples/CSharp/ 有 12 个可直接运行的示例： BasicGrab / CallbackGrab / EventGrab / TriggerGrab / ParameterTree / ParameterConfig / Preprocess / SaveImage / Reconnect / GrabStatsMonitor / DirectConnect / SdkToolbox。 另有《LDVisionCamera .NET 开发手册》与《LDVisionCamera .NET 接口说明》两份完整文档（Document/）。

支持的框架与平台

托管程序集：多目标 netstandard2.0 + net8.0。

Native AOT / 裁剪：本包在 net8.0 上已标注为 AOT 兼容并经真机实测—— 图像回调、FrameReceived 事件、采集统计回调、日志回调四条回调路径在 AOT 产物中 均正常触发。你的应用开 PublishAot 时，不会因为本 SDK 收到 IL2xxx / IL3xxx 告警。

内含原生库（runtimes/<rid>/native/）：

ARM64 两档的收包后端少一项：x64/x86 上可用 RIO 与 XDP 两种高性能收包后端， ARM64 上只编入 RIO（Windows）/ recvmmsg（Linux），失败回退标准 socket。 功能与接口完全一致，只是极高帧率场景下的 CPU 占用不如 x64 档。

使用 .NET 5+ 时，原生库经 deps.json 按 RID 自动解析，无需手动拷贝。

.NET Framework 项目需使用 SDK 风格 csproj + PackageReference 并指定 RID， 否则 runtimes/ 下的原生库不会进输出目录。

当前包不含 macOS（osx-*）原生库。

本包不含 GenTL Producer（LDVisionCameraTL.cti）。Producer 的用途是让 HALCON / VisionPro / harvesters 等第三方机器视觉软件发现本相机，它必须安装到系统并注册 GENICAM_GENTL64_PATH 环境变量才生效——这是 LDVision SDK Runtime 安装包的职责， NuGet 包无法完成。使用本 SDK 编程不需要该组件。 （反向的 GenTL Consumer——加载采集卡厂商的 .cti 接入 CL/CXP 相机——本包完整支持。）

Windows 7 支持

本包的原生库要求 Windows 10 及以上（用到了 Win8+ 的系统 API）。Win7 请改用配套包：

dotnet add package LDVisionCamera.Net.Win7

LDVisionCamera.Net.Win7 的 API 与本包完全一致 （同名程序集，换包无需修改代码），仅原生库改为 Win7 兼容构建。两个包二选一，不能同时安装。 另注意 .NET 5+ 运行时本身不支持 Win7，该场景请配 .NET Framework 4.6.1+ 或 .NET Core 3.1。

主要能力

• 发现 / 连接：多网卡并发广播、USB 枚举、GenTL .cti 扫描；断线检测 + 自动重连 + 自动重启采集
• 参数：GenICam XML 解析（含 SwissKnife 公式求值）；按名读写 + SFNC 便捷属性；参数树浏览、枚举项、访问模式；参数存档与恢复
• 采集：StartGrabbing / GrabFrame / 回调三种模式；GVSP 帧重组（乱序 / 重复 / 丢包容忍 + 按需重传）；U3V Bulk 组帧
• 图像：像素格式转换（Mono / Bayer / RGB 8–16bit、packed 10p/12p、YUV422，含去马赛克）；存图 BMP / PNG / TIFF / RAW
• 诊断：采集统计、丢包分类、设备温度、日志回调

运行环境说明

• GigE / USB3 Vision：零额外运行时依赖（原生库静态链接 CRT，免装 VC++ Redistributable）。
• GenTL 设备：需目标机已装采集卡厂商运行时（随卡驱动自带，本 SDK 不分发）。
• USB3 Vision：设备需绑定 WinUSB 驱动。

许可

专有软件，版权所有 © 2016-2026 西安立鼎光电科技有限公司。详见包内 LICENSE.txt。

• 官网：https://www.leadingoe.com
• 技术支持：请通过官网联系方式与我们取得联系。