流采集器参数#

在 pylon API 中，流采集器管理检索、缓冲和传输图像数据的过程。

本主题描述与流采集器有关的参数。

一般参数#

访问模式#

AccessMode 参数指示当前应用对设备的访问模式：

• 控制：应用具有对设备的控制权限。其他应用仍然可以监视设备，并可以请求接管控制权限或获得对设备的独占访问权限。
• 独占：应用拥有对设备的独占访问权限。其他应用无法控制或监视设备。
• Monitor：应用具有对设备的监测（即只读）访问权限。
• NotInitialized：对设备的访问尚未初始化。

此为只读参数。

自动数据包大小#

使用 AutoPacketSize 参数可以优化通过以太网传输的数据包的大小。

当参数设置为 true 时，相机会自动协商数据包大小，以确定可能的最大数据包大小。

要检索当前的数据包大小，请获取 GevSCPSPacketSize 参数的值。

使用较大的数据包可降低传输图像的开销。最大数据包大小取决于网络硬件及其配置。

最大缓冲区大小#

使用 MaxBufferSize 参数指定用于采集图像的缓冲区的最大大小（以字节为单位）。

采集应用程序必须在采集开始之前设置此参数。

最大缓冲区数量#

使用 MaxNumBuffer 参数指定可同时用于采集图像的最大缓冲区数。

最大传输大小#

使用 MaxTransferSize 参数以字节为单位指定最大 USB 数据传输大小。默认值适用于大多数应用。增加该值可以降低 CPU 负载。

如果应用无法接收图像流，则 USB 主机适配器驱动程序可能需要减小该值。最大值取决于操作系统。

排队的 URB 最大数量#

使用 NumMaxQueuedUrbs 参数指定要同时排入队列的 USB 请求块 (URB) 的最大数量。

增加此值可能会提高稳定性并减少抖动，但需要更多的主机资源。

如果您收到与系统内存不足有关的错误消息，例如，“无法探测和锁定缓冲区 = 0xe2010130”或“无法提交传输状态 = 0xe2100001”，则减小该值可能会有所帮助。

接收线程优先级覆盖#

使用 ReceiveThreadPriorityOverride 参数允许为接收传入流数据包的线程分配自定义优先级。仅在使用套接字驱动程序时可用。

要分配优先级，请使用 ReceiveThreadPriority 参数。

接收线程优先级#

使用 ReceiveThreadPriority 参数设置接收线程的线程优先级。仅在使用 套接字驱动程序时 可用。

要分配优先级，必须将 ReceiveThreadPriorityOverride 参数设置为 true。

套接字缓冲区大小#

使用 SocketBufferSize 参数设置套接字缓冲区的大小（以千字节为单位）。仅在使用 套接字驱动程序时可用。

状态#

Status 参数指示流采集器的当前状态：

• Closed：流采集器已关闭。
• Locked：流采集器已锁定。
• NotInitialized：流采集器未初始化。
• Open：流采集器已打开。

此为只读参数。

传输循环线程优先级#

使用 TransferLoopThreadPriority 参数可以指定处理流接口的 USB 请求的线程优先级。

在 pylon 中，有两个线程属于 USB 传输层，一个线程用于图像 URB（USB 请求块），另一个线程用于事件 URB。传输层将 URB 排入 xHCI 驱动程序队列，并轮询总线以获取已传送的 URB。

您可以通过 TransferLoopThreadPriority 参数控制两个线程的优先级。

在 Windows 上，默认情况下，该参数设置为以下值：

• 25（如果主机应用程序以管理员特权运行。
• 如果主机应用程序在没有管理员特权的情况下运行，则为 15 或更小。

在 Linux 和 macOS 上，默认参数值和参数值范围可能不同。

传输循环优先级应始终高于采集引擎线程优先级（InternalGrabEngineThreadPriority 参数）和采集循环线程优先级（GrabLoopThreadPriority 参数）。

如需了解详情，请参阅 pylon API 文档中的“高性能应用设置”部分。

GigE Vision 驱动程序类型#

使用 Type 参数设置主机应用的 GigE Vision 驱动程序类型：

• WindowsFilterDriver：主机应用使用 pylon GigE Vision 过滤器驱动程序。
• WindowsPerformanceDriver（在 pylon 7.1 版中已弃用）：主机应用使用 pylon GigE Vision 性能驱动程序。
• SocketDriver：主机应用使用 pylon GigE Vision 套接字驱动程序。
• NoDriverAvailable：未安装合适的驱动程序。无法设置驱动程序类型。

如需详细了解驱动程序类型，请参阅“驱动程序”。

类型：可用套接字驱动程序#

TypeIsSocketDriverAvailable 参数指示 pylon GigE Vision 套接字驱动程序当前是可用 (1) 还是不可用 (0)。

类型：可用 Windows 过滤型驱动程序#

TypeIsWindowsFilterDriverAvailable 参数指示 pylon GigE Vision 过滤型驱动程序当前是可用 (1) 还是不可用 (0)。

类型：可用 Windows Intel 性能型驱动程序#

TypeIsWindowsIntelPerformanceDriverAvailable 参数指示 pylon GigE Vision 性能型驱动程序当前是可用 (1) 还是不可用 (0)。

数据包重发机制参数#

包重发机制（仅限 GigE Vision）通过检测并重发丢失的数据包来优化网络性能。

pylon GigE Vision 过滤器和套接字驱动程序具有先进和稳健的数据包重发机制。

它们允许微调并且可以发送多个连续的重发请求，直到达到最大请求数为止。

如果驱动程序检测到数据包（例如，前导数据包、有效负载数据包或尾部数据包）丢失，则会等待一段指定的时间。如果数据包未在指定时间内到达，驱动程序可能会发送一个或多个重发请求，以尝试检索丢失的数据包。

如果丢失了连续范围的有效负载数据包，驱动程序将自动为丢失的数据包范围发送一个“批量重新发送请求”。此外，驱动程序可以针对已被认为丢失的重发请求自动发送重发请求。

启用重发#

使用 EnableResend 参数为当前选定类型的 GigE Vision 驱动程序启用或禁用数据包重发机制。

数据包超时#

使用 PacketTimeout 参数可以指定过滤型驱动程序在启动重发请求之前等待下一个预期数据包的时间（以毫秒为单位）。

确保将参数设置为比包间隔更长的时间间隔。

帧保留#

使用 FrameRetention 参数指定接收帧中所有数据包的最长时间（以毫秒为单位）。计时器在接收到第一个数据包时启动。如果传输未在给定时间内完成，则相应的帧将传送并伴有“失败”状态。

最大重发请求数#

使用 MaximumNumberResendRequests 参数指定每个丢失数据包的最大重发请求数。

防火墙通道间隔#

使用 FirewallTraversalInterval 参数可防止防火墙阻止 GigE Vision 数据包。

该参数可用于流采集器和事件采集器，即用于处理 GigE Vision 流协议 (GVSP) 数据包和消息通道源端口 (MCSP) 数据包。必须为这两种类型的数据包单独配置。如需了解详情，请参阅下面的代码示例。

如果启用，采集卡将发送特定数据包，以模拟防止防火墙阻塞的流量对话。

默认情况下，在给定的流传输会话期间，GVSP 数据包每 10 秒发送一个数据包，MCSP 数据包每 30 秒发送一个数据包。

您能够以毫秒为单位设置参数，以针对您的防火墙进行优化。

如果 FirewallTraversalInterval 参数设置为零，则防火墙通道功能视为已禁用。

流目标参数#

以下参数（仅限 GigE Vision）可让您配置流采集器将采集到的数据发送到何处。

流采集器可以将流数据发送到一个特定设备或网络中的多个设备。

传输类型#

使用 TransmissionType 参数定义如何在网络内传输流数据。您可以将该参数设置为以下值：

• Unicast（默认）：流数据发送到本地网络中的单个设备，通常是相机的GigE 网络适配器（请参阅目标地址）。其他设备无法接收流数据。

  

• LimitedBroadcast：流数据发送到本地网络中）(255.255.255.255) 的所有设备，即使它们没有兴趣接收流数据也是如此。在大型局域网中，这会占用大量网络带宽。要使用此传输类型，您必须设置控制和监视应用。

  

• SubnetDirectedBroadcasting：流数据发送到与相机所在的同一子网中的所有设备，即使它们没有兴趣接收流数据也是如此。如果子网较小，这能节省网络带宽。由于子网外部的设备无法接收流数据，因此这种传输类型可能很有用，例如出于安全目的。

  

  对于子网定向广播，流采集器使用子网广播地址。子网广播地址是通过在相机的 IP 地址与相机子网掩码的位补码之间执行按位“或”运算而获得的（请参见目标地址）。要使用此传输类型，您必须设置控制和监视应用。

  信息

  • 要设置相机的 IP 地址和子网掩码，请使用 pylon IP Configurator。
  • 有关 IP 地址、子网掩码和子网广播地址的更多信息，请访问 Online IP Subnet Calculator 网站。

• Multicast：流数据发送到本地网络中的所选设备。这能节省网络带宽，因为数据仅发送到有兴趣接收数据的那些设备。另外，您可以精确指定要将数据发送到哪些设备。

  

  要使用多播，流目标地址必须设置为多播组地址（224.0.0.0 或 239.255.255.255）。另外，您必须设置控制和监视应用。然后，pylon API 自动负责创建和管理其他设备可以加入的多播组。- UseCameraConfig：从相机读取流传输配置。仅当您想要设置监视应用时才使用此选项。

控制和监视应用#

使用受限广播、子网定向广播或多播时，通常需要将图像数据流从一台相机发送到多个目标。

为此，您必须设置一个控制应用程序和一个或多个监视应用程序。

• 控制应用程序启动和停止图像采集。此外还可以更改相机配置。
• 监视应用程序接收流数据。监视应用程序以只读模式打开相机。这意味着它们无法启动和停止图像采集或更改相机配置。

为了进行测试，您可以使用一个 pylon Viewer 实例作为控制应用，使用另一个 pylon Viewer 实例作为监视应用。

使用不同的 pylon Viewer 实例作为控制和监视应用：

1. 启动 pylon Viewer，然后打开一个 GigE 设备。
2. 启动另一个 pylon Viewer 实例，该实例将用作监视应用：
   • Windows：启动 pylon Viewer。在 pylon Viewer 的设备面板中，右键单击在步骤 1 中打开的 GigE 设备，然后单击打开设备... > 监视模式。
   • Linux：在命令行中，输入：/opt/pylon5/bin/PylonViewerApp -m
   • macOS：在命令行中，输入：./Applications/pylon Viewer.app/Contents/MacOS/pylon Viewer -m

目标地址#

DestinationAddr 参数指示流采集器将所有流数据发送到的 IP 地址。

参数的值和访问模式取决于 TransmissionType 参数值：

目标端口#

DestinationPort 参数指示流采集器要将所有流数据发送到哪个端口。

如果参数设置为 0，pylon 会自动选择一个未使用的端口。

如需了解详情，请参阅 pylon API 文档中的“选择目标端口”部分。

统计参数#

pylon API 提供了统计参数，可让您检查相机的设置是否正确、硬件组件是否正确以及系统性能是否良好。

在相机启动时，所有统计参数均设置为 0。在连续采集图像的同时，将连续更新参数以提供有关例如丢失的图像或未完全采集的缓冲区的信息。

缓冲区不足计数#

Statistic_Buffer_Underrun_Count 参数计算由于队列中没有缓冲区而丢失的帧数。

每当接收到图像，但驱动程序输入队列中没有已排队的空闲缓冲区，因此导致帧丢失，这时此参数值就会增加。

失败缓冲区计数#

Statistic_Failed_Buffer_Count 参数计算以“失败”状态返回的缓冲区的数量，即未完全完成采集的缓冲区。

未完全完成采集的缓冲区的错误代码为 0xE1000014（GigE 相机）或 0xE2000212（USB 3.0 相机）。

失败数据包计数#

Statistic_Failed_Packet_Count 参数对流采集器成功接收到但已被相机报告为“失败”的数据包进行计数。

数据包被报告为“失败”的最常见原因是相机无法满足数据包重发请求。例如，如果请求的数据已经被相机内存中的新图像数据覆盖，就会发生这种情况。

失败的数据包计数不会被视为丢失，因为所有的数据包重发请求均已失败。在这种情况下，失败缓冲区计数将会增加，但“失败数据包计数”不会增加。

上个块 ID#

Statistic_Last_Block_Id 参数指示最后一个采集的块 ID。

上个失败缓冲区状态#

Statistic_Last_Failed_Buffer_Status 参数指示最后一个失败缓冲区的状态码。

上个失败缓冲区状态文本#

Statistic_Last_Failed_Buffer_Status_Text 参数指示读取或写入操作的最后错误状态。

丢帧计数#

Statistic_Missed_Frame_Count 参数计算已采集但由于相机内部帧缓冲区已满而跳过的帧数。

许多 Basler 相机配备了一个帧缓冲器，可以存储多个完整的帧。丢失的帧计数较高表示主机控制器不支持相机的带宽，即主机控制器未及时检索所获取的图像。这使相机将图像缓存在其内部帧缓冲区中。当内部帧缓冲区已满时，相机将开始跳过新获取的传感器数据。

重发数据包计数#

Statistic_Resend_Packet_Count 参数计算重发请求所请求的数据包数量。

重发请求计数#

Statistic_Resend_Request_Count 参数计算已发送的数据包重发请求数量。

根据驱动程序类型和流采集器设置，流采集器可能会针对一个丢失的数据包发送多个请求，也可能会针对多个数据包发送一个请求。因此，重发请求计数和重发数据包计数很可能会有所不同。

重新同步计数#

Statistic_Resynchronization_Count 参数会计算流重新同步的次数。

如果主机在流传输过程中不同步，它将启动重新同步，并刷新相机的内部缓冲区。

如果主机请求具有特定 ID 序列的流数据包，主机可能不会同步，但设备会传送具有不同序列的数据包。相机和主机之间的连接发生问题时，就可能会出现这种情况。主机不同步会导致大量图像丢失。

在 USB 3.0 和 USB3 Vision 规范中，主机重新同步被视为最严重的错误情况。

总缓冲区计数#

在 GigE 相机上，Statistic_Total_Buffer_Count 参数计算以“成功”或“失败”状态返回的缓冲区的数量，即所有成功抓取或未完整抓取的缓冲区。在其他相机（例如 USB 相机）上，将计算处理的缓冲区数。

未完全完成采集的缓冲区的错误代码为 0xE1000014（GigE 相机）或 0xE2000212（USB 3.0 相机）。

数据包总计数#

Statistic_Total_Packet_Count 参数对所有接收到的数据包进行计数，包括已报告为“失败”的数据包，即包括失败数据包计数。

示例代码#

// ** General Parameters **
// Access Mode
AccessModeEnums accessMode = camera.GetStreamGrabberParams().AccessMode.GetValue();
// Auto Packet Size
camera.GetStreamGrabberParams().AutoPacketSize.SetValue(true);
// Maximum Buffer Size
camera.GetStreamGrabberParams().MaxBufferSize.SetValue(131072);
// Maximum Number of Buffers
camera.GetStreamGrabberParams().MaxNumBuffer.SetValue(16);
// Maximum Transfer Size
camera.GetStreamGrabberParams().MaxTransferSize.SetValue(1048568);
// Num Max Queued Urbs
camera.GetStreamGrabberParams().NumMaxQueuedUrbs.SetValue(64);
// Receive Thread Priority Override
camera.GetStreamGrabberParams().ReceiveThreadPriorityOverride.SetValue(true);
// Receive Thread Priority
camera.GetStreamGrabberParams().ReceiveThreadPriority.SetValue(15);
// Socket Buffer Size (socket driver only)
camera.GetStreamGrabberParams().SocketBufferSize.SetValue(2048);
// Status
StatusEnums streamGrabberStatus = camera.GetStreamGrabberParams().Status.GetValue();
// Transfer Loop Thread Priority
camera.GetStreamGrabberParams().TransferLoopThreadPriority.SetValue(15);
// Type of GigE Vision Filter Driver
camera.GetStreamGrabberParams().Type.SetValue(Type_WindowsIntelPerformanceDriver);
// Type: Socket Driver Available
int64_t i = camera.GetStreamGrabberParams().TypeIsWindowsIntelPerformanceDriverAvailable.GetValue();
// Type: Windows Filter Driver Available
int64_t i = camera.GetStreamGrabberParams().TypeIsWindowsFilterDriverAvailable.GetValue();
// Type: Windows Intel Performance Driver Available
int64_t i = camera.GetStreamGrabberParams().TypeIsSocketDriverAvailable.GetValue();
// ** Packet Resend Mechanism Parameters **
// Enable Resends
camera.GetStreamGrabberParams().EnableResend.SetValue(true);
// Packet Timeout
camera.GetStreamGrabberParams().PacketTimeout.SetValue(40);
// Frame Retention
camera.GetStreamGrabberParams().FrameRetention.SetValue(200);
// Maximum Number of Resend Requests
camera.GetStreamGrabberParams().MaximumNumberResendRequests.SetValue(25);
// Firewall Traversal Interval
camera.GetStreamGrabberParams().FirewallTraversalInterval.SetValue(10000);
camera.GetEventGrabberParams().FirewallTraversalInterval.SetValue(30000);
// ** Stream Destination Parameters **
// Transmission Type
camera.GetStreamGrabberParams().TransmissionType.SetValue(TransmissionType_Unicast);
// Destination Address
GenICam::gcstring destinationAddr = camera.GetStreamGrabberParams().DestinationAddr.GetValue();
// Destination Port
camera.GetStreamGrabberParams().DestinationPort.SetValue(0);
// ** Statistics Parameters **
// Buffer Underrun Count
int64_t bufferUnderrunCount = camera.GetStreamGrabberParams().Statistic_Buffer_Underrun_Count.GetValue();
// Failed Buffer Count
int64_t failedBufferCount = camera.GetStreamGrabberParams().Statistic_Failed_Buffer_Count.GetValue();
// Failed Packet Count
int64_t failedPacketCount = camera.GetStreamGrabberParams().Statistic_Failed_Packet_Count.GetValue();
// Last Block ID
int64_t lastBlockId = camera.GetStreamGrabberParams().Statistic_Last_Block_Id.GetValue();
// Last Failed Buffer Status
int64_t lastFailedBufferStatus = camera.GetStreamGrabberParams().Statistic_Last_Failed_Buffer_Status.GetValue();
// Last Failed Buffer Status Text
GenICam::gcstring lastFailedBufferStatusText = camera.GetStreamGrabberParams().Statistic_Last_Failed_Buffer_Status_Text.GetValue();
// Missed Frame Count
int64_t missedFrameCount = camera.GetStreamGrabberParams().Statistic_Missed_Frame_Count.GetValue();
// Resend Request Count
int64_t resendRequestCount = camera.GetStreamGrabberParams().Statistic_Resend_Request_Count.GetValue();
// Resend Packet Count
int64_t resendPacketCount = camera.GetStreamGrabberParams().Statistic_Resend_Packet_Count.GetValue();
// Resynchronization Count
int64_t resynchronizationCount = camera.GetStreamGrabberParams().Statistic_Resynchronization_Count.GetValue();
// Total Buffer Count
int64_t totalBufferCount = camera.GetStreamGrabberParams().Statistic_Total_Buffer_Count.GetValue();
// Total Packet Count
int64_t totalPacketCount = camera.GetStreamGrabberParams().Statistic_Total_Packet_Count.GetValue();

// ** General Parameters **
// Access Mode
string accessMode = camera.Parameters[PLStream.AccessMode].GetValue();
// Auto Packet Size
camera.Parameters[PLStream.AutoPacketSize].SetValue(true);
// Maximum Buffer Size
camera.Parameters[PLStream.MaxBufferSize].SetValue(131072);
// Maximum Number of Buffers
camera.Parameters[PLStream.MaxNumBuffer].SetValue(16);
// Maximum Transfer Size
camera.Parameters[PLStream.MaxTransferSize].SetValue(1048568);
// Num Max Queued Urbs
camera.Parameters[PLStream.NumMaxQueuedUrbs].SetValue(64);
// Receive Thread Priority Override
camera.Parameters[PLStream.ReceiveThreadPriorityOverride].SetValue(true);
// Receive Thread Priority
camera.Parameters[PLStream.ReceiveThreadPriority].SetValue(15);
// Socket Buffer Size (socket driver only)
camera.Parameters[PLStream.SocketBufferSize].SetValue(2048);
// Status
string streamGrabberStatus = camera.Parameters[PLStream.Status].GetValue();
// Transfer Loop Thread Priority
camera.Parameters[PLStream.TransferLoopThreadPriority].SetValue(15);
// Type of GigE Vision Filter Driver
camera.Parameters[PLStream.Type].SetValue(PLStream.Type.WindowsIntelPerformanceDriver);
// Type: Socket Driver Available
Int64 performanceDriverAvailable = camera.Parameters[PLStream.TypeIsWindowsIntelPerformanceDriverAvailable].GetValue();
// Type: Windows Filter Driver Available
Int64 filterDriverAvailable = camera.Parameters[PLStream.TypeIsWindowsFilterDriverAvailable].GetValue();
// Type: Windows Intel Performance Driver Available
Int64 socketDriverAvailable = camera.Parameters[PLStream.TypeIsSocketDriverAvailable].GetValue();
// ** Packet Resend Mechanism Parameters **
// Enable Resends
camera.Parameters[PLStream.EnableResend].SetValue(true);
// Packet Timeout
camera.Parameters[PLStream.PacketTimeout].SetValue(40);
// Frame Retention
camera.Parameters[PLStream.FrameRetention].SetValue(200);
// Maximum Number of Resend Requests
camera.Parameters[PLStream.MaximumNumberResendRequests].SetValue(25);
// Firewall Traversal Interval
camera.Parameters[PLStream.FirewallTraversalInterval].SetValue(10000);
camera.Parameters[PLEventGrabber.FirewallTraversalInterval].SetValue(30000);
// ** Stream Destination Parameters **
// Transmission Type
camera.Parameters[PLStream.TransmissionType].SetValue(PLStream.TransmissionType.Unicast);
// Destination Address
string destinationAddr = camera.Parameters[PLStream.DestinationAddr].GetValue();
// Destination Port
camera.Parameters[PLStream.DestinationPort].SetValue(0);
// ** Statistics Parameters **
// Buffer Underrun Count
Int64 bufferUnderrunCount = camera.Parameters[PLStream.Statistic_Buffer_Underrun_Count].GetValue();
// Failed Buffer Count
Int64 failedBufferCount = camera.Parameters[PLStream.Statistic_Total_Buffer_Count].GetValue();
// Failed Packet Count
Int64 failedPacketCount = camera.Parameters[PLStream.Statistic_Failed_Packet_Count].GetValue();
// Last Block ID
Int64 lastBlockId = camera.Parameters[PLStream.Statistic_Last_Block_Id].GetValue();
// Last Failed Buffer Status
Int64 lastFailedBufferStatus = camera.Parameters[PLStream.Statistic_Last_Failed_Buffer_Status].GetValue();
// Last Failed Buffer Status Text
string lastFailedBufferStatusText = camera.Parameters[PLStream.Statistic_Last_Failed_Buffer_Status_Text].GetValue();
// Missed Frame Count
Int64 missedFrameCount = camera.Parameters[PLStream.Statistic_Missed_Frame_Count].GetValue();
// Resend Packet Count
Int64 resendPacketCount = camera.Parameters[PLStream.Statistic_Resend_Packet_Count].GetValue();
// Resend Request Count
Int64 resendRequestCount = camera.Parameters[PLStream.Statistic_Resend_Request_Count].GetValue();
// Resynchronization Count
Int64 resynchronizationCount = camera.Parameters[PLStream.Statistic_Resynchronization_Count].GetValue();
// Total Buffer Count
Int64 totalBufferCount = camera.Parameters[PLStream.Statistic_Total_Buffer_Count].GetValue();
// Total Packet Count
Int64 totalPacketCount = camera.Parameters[PLStream.Statistic_Total_Packet_Count].GetValue();

此示例代码仅适用于 C++ 和 C# 语言。

您也可以使用 pylon Viewer 轻松设置参数。