流采集器参数#

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

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

一般参数#

访问模式#

即： AccessMode parameter indicates the mode of access the current application has to the device:

• Control: The application has control access to the device. Other applications are still able to monitor the device and can request to take over control or gain exclusive access to the device.
• Exclusive: The application has exclusive access to the device. No other application can control or monitor the device.
• Monitor: The application has monitoring, i.e., read-only, access to the device.
• NotInitialized: Access to the device hasn't been initialized.

此为只读参数。

自动数据包大小#

Use the AutoPacketSize parameter to optimize the size of the data packets transferred via Ethernet.

When the parameter is set to true, the camera automatically negotiates the packet size to find the largest possible packet size.

To retrieve the current packet size, get the value of the GevSCPSPacketSize parameter.

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

最大缓冲区大小#

Use the MaxBufferSize parameter to specify the maximum size (in bytes) of a buffer used for grabbing images.

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

最大缓冲区数量#

Use the MaxNumBuffer parameter to specify the maximum number of buffers that can be used simultaneously for grabbing images.

最大传输大小#

Use the MaxTransferSize parameter to specify the maximum USB data transfer size in bytes. The default value is appropriate for most applications. Increase the value to lower the CPU load.

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

排队的 URB 最大数量#

Use the NumMaxQueuedUrbs parameter to specify the maximum number of USB request blocks (URBs) to be enqueued simultaneously.

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

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

接收线程优先级覆盖#

Use the ReceiveThreadPriorityOverride parameter to enable assigning a custom priority to the thread which receives incoming stream packets. Only available if the socket driver is used.

To assign the priority, use the ReceiveThreadPriority parameter.

接收线程优先级#

Use the ReceiveThreadPriority parameter to set the thread priority of the receive thread. Only available if the socket driver is used.

To assign the priority, the ReceiveThreadPriorityOverride parameter must be set to true.

套接字缓冲区大小#

Use the SocketBufferSize parameter to set the socket buffer size in kilobytes. Only available if the socket driver is used.

状态#

即： Status parameter indicates the current status of the stream grabber:

• Closed: The stream grabber is closed.
• Locked: The stream grabber is locked.
• NotInitialized: The stream grabber is not initialized.
• Open: The stream grabber is open.

此为只读参数。

传输循环线程优先级#

Use the TransferLoopThreadPriority parameter to specify the priority of the threads that handle USB requests from the stream interface.

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

You can control the priority of both threads via the TransferLoopThreadPriority parameter.

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

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

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

The transfer loop priority should always be higher than the grab engine thread priority (InternalGrabEngineThreadPriority parameter) and the grab loop thread priority (GrabLoopThreadPriority parameter).

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

GigE Vision 驱动程序类型#

Use the Type parameter to set the host application's GigE Vision driver type:

• WindowsFilterDriver: The host application uses the pylon GigE Vision Filter Driver.
• WindowsPerformanceDriver (deprecated in pylon version 7.1): The host application uses the pylon GigE Vision Performance Driver.
• SocketDriver: The host application uses the pylon GigE Vision Socket Driver.
• NoDriverAvailable: No suitable driver is installed. The driver type can't be set.

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

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

即： TypeIsSocketDriverAvailable parameter indicates whether the pylon GigE Vision Socket Driver is currently available (1) or not available (0).

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

即： TypeIsWindowsFilterDriverAvailable parameter indicates whether the pylon GigE Vision Filter Driver is currently available (1) or not available (0).

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

即： TypeIsWindowsIntelPerformanceDriverAvailable parameter indicates whether the pylon GigE Vision Performance Driver is currently available (1) or not available (0).

数据包重发机制参数#

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

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

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

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

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

启用重发#

Use the EnableResend parameter to enable or disable the packet resend mechanism for the currently selected type of GigE Vision driver.

数据包超时#

Use the PacketTimeout parameter to specify how long (in milliseconds) the filter driver waits for the next expected packet before it initiates a resend request.

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

帧保留#

Use the FrameRetention parameter to specify the maximum time in milliseconds to receive all packets of a frame. The timer starts when the first packet has been received. If the transmission is not completed within the time specified, the corresponding frame is delivered with the status "Failed".

最大重发请求数#

Use the MaximumNumberResendRequests parameter to specify the maximum number of resend requests per missing packet.

防火墙通道间隔#

Use the FirewallTraversalInterval parameter to prevent a firewall from blocking GigE Vision packets.

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

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

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

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

When the FirewallTraversalInterval parameter is set to zero, the Firewall Traversal feature is considered disabled.

流目标参数#

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

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

传输类型#

Use the TransmissionType parameter to define how stream data is transferred within the network. You can set the parameter to the following values:

• Unicast (default): The stream data is sent to a single device in the local network, usually the camera's GigE network adapter (see destination address). Other devices can't receive the stream data.

  

• LimitedBroadcast: The stream data is sent to all devices in the local network (255.255.255.255), even if they aren't interested in receiving stream data. In large local networks, this uses a large amount of network bandwidth. To use this transmission type, you must set up the controlling and monitoring applications.

  

• SubnetDirectedBroadcasting: The stream data is sent to all devices in the same subnet as the camera, even if they aren't interested in receiving stream data. If the subnet is small, this may save network bandwidth. Because devices outside the subnet can't receive the stream data, this transmission type can be useful, e.g., for security purposes.

  

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

  信息

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

• Multicast: The stream data is sent to selected devices in the local network. This saves network bandwidth because data is only sent to those devices that are interested in receiving the data. Also, you can specify precisely which devices you want to send the data to.

  

  To use multicast, the stream destination address must be set to a multicast group address (224.0.0.0 to 239.255.255.255). Also, you must set up the controlling and monitoring applications. Then, the pylon API automatically takes care of creating and managing a multicast group that other devices can join. - UseCameraConfig: The stream transmission configuration is read from the camera. Use this option only if you want to set up a monitoring application.

控制和监视应用#

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

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

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

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

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

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

目标地址#

即： DestinationAddr parameter indicates the IP address to which the stream grabber sends all stream data.

The value and the access mode of the parameter depend on the TransmissionType parameter value:

目标端口#

即： DestinationPort parameter indicates the port where the stream grabber will send all stream data to.

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

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

统计参数#

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

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

缓冲区不足计数#

即： Statistic_Buffer_Underrun_Count parameter counts the number of frames lost because there were no buffers in the queue.

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

失败缓冲区计数#

即： Statistic_Failed_Buffer_Count parameter counts the number of buffers that returned with status "failed", i.e., buffers that were grabbed incompletely.

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

失败数据包计数#

即： Statistic_Failed_Packet_Count parameter counts packets that were successfully received by the stream grabber, but have been reported as "failed" by the camera.

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

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

上个块 ID#

即： Statistic_Last_Block_Id parameter indicates the last grabbed block ID.

上个失败缓冲区状态#

即： Statistic_Last_Failed_Buffer_Status parameter indicates the status code of the last failed buffer.

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

即： Statistic_Last_Failed_Buffer_Status_Text parameter indicates the last error status of a read or write operation.

丢帧计数#

即： Statistic_Missed_Frame_Count parameter counts the number of frames that were acquired but skipped because the camera's internal frame buffer was already full.

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

重发数据包计数#

即： Statistic_Resend_Packet_Count parameter counts the number of packets requested by resend requests.

重发请求计数#

即： Statistic_Resend_Request_Count parameter counts the number of packet resend requests sent.

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

重新同步计数#

即： Statistic_Resynchronization_Count parameter counts the number of stream resynchronizations.

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

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

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

总缓冲区计数#

On GigE cameras, the Statistic_Total_Buffer_Count parameter counts the number of buffers that returned with "success" or "failed" status, i.e., all successfully or incompletely grabbed buffers. On other cameras, e.g., USB cameras, the number of buffers processed is counted.

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

数据包总计数#

即： Statistic_Total_Packet_Count parameter counts all packets received, including packets that have been reported as "failed", i.e., including the 失败数据包计数.

示例代码#

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