流采集器参数#

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

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

一般参数#

访问模式#

即： AccessMode 参数指示当前应用程序对设备具有的访问模式：

• Control：应用程序对设备具有控制访问权限。其他应用程序仍然可以 监视 设备，并且可以请求接管控制权或获得对设备的独占访问权限。
• Exclusive：应用程序对设备具有独占访问权限。没有其他应用程序可以 控制或监视 设备。
• 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 Filter Driver.
• WindowsPerformanceDriver （在 pylon 7.1 版本中已弃用）：主机应用程序使用 pylon GigE Vision Performance Driver.
• SocketDriver：主机应用程序使用 pylon GigE Vision Socket Driver.
• RDMADriver：主机应用程序使用 pylon RDMA Driver.
• NoDriverAvailable：未安装合适的驱动程序。无法设置驱动程序类型。

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

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

即： TypeIsSocketDriverAvailable 参数指示 pylon GigE Vision Socket Driver 当前是否可用 (1) 或不可用 (0)。

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

即： TypeIsWindowsFilterDriverAvailable 参数指示 pylon GigE Vision Filter Driver 当前是否可用 (1) 或不可用 (0)。

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

即： TypeIsWindowsIntelPerformanceDriverAvailable 参数指示 pylon GigE Vision Performance Driver 当前是否可用 (1) 或不可用 (0)。

数据包重发机制参数#

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

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

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

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

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

启用重发#

使用 EnableResend 参数，用于为当前选定的 GigE Vision 驱动程序类型.

数据包超时#

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

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

帧保留#

使用 FrameRetention 参数，用于指定接收一帧的所有数据包的最大时间（以毫秒为单位）。Timer 在收到第一个数据包时启动。如果未在指定时间内完成传输，则交付的相应帧状态为“Failed”。

最大重发请求数#

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

防火墙通道间隔#

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

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

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

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

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

当 FirewallTraversalInterval 参数设为零时，将视为禁用 Firewall Traversal 功能。

流目标参数#

以下参数（仅限 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 参数用于统计状态返回为“failed”（失败）的缓冲区数量，即未完全采集的缓冲区。

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

失败数据包计数#

即： Statistic_Failed_Packet_Count 参数用于统计流采集器成功接收、但相机报告为“failed”（失败）的数据包。

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

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

上个块 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 参数用于统计状态返回为“success”（成功）或“failed”（失败）的缓冲区数量，即所有成功采集或未完全采集的缓冲区。对于其他相机（例如 USB 相机），则会统计已处理的缓冲区数量。

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

数据包总计数#

即： Statistic_Total_Packet_Count 参数用于统计接收到的所有数据包，包括被报告为“failed”（失败）的数据包，即包括 失败数据包计数.

示例代码#

// ** 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 轻松设置参数。