LDVision.Net 3.0.2

LDVision.Net

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

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

安装

dotnet add package LDVision.Net

API 变更历史

本表按版本自新至旧排列。升级前应定位当前所用版本，并逐行查阅其上方各行， 所列内容即为本次升级涉及的全部公开接口变更。

「公开 API」一栏标注 ⚠️ 的版本含破坏性变更，须修改调用代码后方可升级；标注「无」的版本可略过。

跨越多个主版本升级时，各版本的迁移说明须依次执行，其内容互不覆盖。 例如自 1.x 升级至 3.0，应先完成 2.0 迁移说明所列变更，再执行 3.0 迁移说明。

1.x 属于旧包 LDVisionCamera.Net，已下架且不再维护。升级路径见上表 2.0.0 一行。

快速上手

**推荐写法：**示例对核心入口使用完整名称 LDVision.Device、LDVision.Image、 LDVision.PixelFormat、LDVision.Sdk、LDVision.Error、LDVision.Logging、 LDVision.GenTL。Device、Image、Error 在 GUI、图像处理等项目中很常见， 完整名称可避免与其它命名空间的同名类型产生歧义；普通参数类型仍可通过 using LDVision; 简写。

using LDVision;

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

// 2. 打开（也可 LDVision.Device.Create("192.168.1.10") 或序列号直连）
using var cam = LDVision.Device.Create(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.SetEnumValueByString("TriggerMode", "Off");       // 按名通用写

// 4. 采集
cam.Stream.Start();
using (GrabResult frame = cam.Stream.RetrieveResult(2000))   // 超时 ms
{
    Console.WriteLine($"帧 {frame.FrameId}: {frame.Width}x{frame.Height}");
    LDVision.Image.SaveToFile(frame, "shot.png", ImageFormat.Png);
}
cam.Stream.Stop();

核心对象与入口

按职责定位静态成员

全部成员：

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

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

// 错误码翻译
string text = LDVision.Error.Describe(-10);      // 错误码 → 可读文本
string last = LDVision.Error.Last();           // 最近一次错误详情

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

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

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

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

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

参数读写

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

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

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

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

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

可用的便捷属性：

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

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

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

// ① 只要当前值
long   w    = cam.GetIntValue("Width");
double exp  = cam.GetFloatValue("ExposureTime");
bool   on   = cam.GetBoolValue("AcquisitionFrameRateEnable");
string mode = cam.GetEnumValueByString("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.SetIntValue("Width", 1920);
cam.SetFloatValue("ExposureTime", 5000.0);
cam.SetBoolValue("AcquisitionFrameRateEnable", true);
cam.SetEnumValueByString("TriggerMode", "On");            // 按符号名（推荐）
cam.SetEnumValueByString("TriggerMode", 1u);              // 或按数值
cam.SetStringParam("DeviceUserID", "cam-01");
cam.ExecuteCommand("TriggerSoftware");       // Command 节点

查询相机支持哪些参数

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

// 树形浏览（用于构建属性树界面）
var root = cam.RootParameterNode;
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.Stream.Start();
using (GrabResult frame = cam.Stream.RetrieveResult(2000)) { /* ... */ }

// ② 裸回调（帧到达即触发，每帧零堆分配；请勿在回调中执行耗时操作）
cam.Stream.RegisterBufferCallback((in GrabResult g) => {
    Console.WriteLine($"{g.FrameId} {g.Width}x{g.Height}");
});
cam.Stream.Start();

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

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

获取帧的像素数据

using (GrabResult f = cam.Stream.RetrieveResult(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.Stream.SetDestination("239.192.1.1", 1042);   // 下次 Start 生效
cam.Stream.Start();

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

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

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

错误处理

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

try
{
    cam.Open();
    cam.SetFloatValue("ExposureTime", 999999.0);   // 超出范围
}
catch (DeviceException ex)
{
    Console.WriteLine($"{ex.Message}（错误码 {ex.ErrorCode}）");
    Console.WriteLine(LDVision.Error.Describe(ex.ErrorCode));   // 错误码转可读文本
}

设备信息

foreach (DeviceInfo d in LDVision.Device.Enumerate(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}");
}

图像处理与存图 —— Image 与 PixelFormat

Image 是图像缓冲（转换结果，持有原生内存，须 using），静态成员管转换与存图； 像素格式的查询与 PFNC 常量在 PixelFormat。

Convert / ConvertInto / SaveToFile 都有接受 in GrabResult 或裸指针的重载； 可选参数 DemosaicQuality demosaic（去马赛克质量）与 BitAlign bitAlign（位对齐）。

// 格式转换（Mono / Bayer / RGB 8-16bit、packed 10p/12p、YUV422，含去马赛克）
// Convert 返回持有原生内存的 Image —— 必须 using
using (var rgb = frame.Convert(LDVision.PixelFormat.Rgb8))
    Console.WriteLine($"{rgb.Width}x{rgb.Height} {rgb.Length} 字节");

// 高帧率下复用缓冲，避免逐帧分配（不产生 Image 对象）
byte[] buf = new byte[frame.Width * frame.Height * 3];
int written = frame.ConvertInto(LDVision.PixelFormat.Rgb8, buf);

// 存图：BMP / PNG / TIFF / RAW（位深感知）
frame.SaveToFile("out.png", ImageFormat.Png);

// 像素格式信息
string name = LDVision.PixelFormat.Name(frame.PixelFormat);   // "Mono8"
uint bits   = LDVision.PixelFormat.BitsPerPixel(frame.PixelFormat);
if (LDVision.PixelFormat.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。 另有《LDVision .NET 开发手册》与《LDVision .NET 接口说明》两份完整文档（Document/）。

支持的框架与平台

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

Native AOT / 裁剪：本包在 net8.0 上已标注为 AOT 兼容并经真机实测—— 图像回调、采集统计回调、日志回调三条回调路径在 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（LDVisionTL.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 LDVision.Net.Win7

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

主要能力

• 发现 / 连接：多网卡并发广播、USB 枚举、GenTL .cti 扫描；断线检测 + 自动重连 + 自动重启采集
• 参数：GenICam XML 解析（含 SwissKnife 公式求值）；按名读写 + SFNC 便捷属性；参数树浏览、枚举项、访问模式；参数存档与恢复
• 采集：Start / RetrieveResult / 回调三种模式；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
• 技术支持：请通过官网联系方式与我们取得联系。