跳转到内容
STAGING SERVER
DEVELOPMENT SERVER

快速入门#

本主题通过一个简单的工作流向您展示 pypylon 的入门步骤。

我们的目标不仅是展示能够运行的代码，还要让您了解如何在更复杂的场景中复用和调整示例代码。

分步示例#

最简单的 pypylon 图像采集包含以下步骤：

  • 发现相机
  • 打开相机
  • 开始图像采集
  • 获取图像
  • 处理图像

以下示例演示了这些步骤。它还具有以下附加优势：

  • 它可用于验证您的安装是否正常工作。
  • 您可以测试相机连接。
  • 它有助于您理解采集生命周期。

示例：

from pypylon import pylon

with pylon.InstantCamera(pylon.FirstFound) as camera:
    camera.StartGrabbingMax(1)

    with camera.RetrieveResult(5000) as grab_result:
        if grab_result.GrabSucceeded():
            image = grab_result.Array
            print(image.shape)

让我们将此示例拆解为各个具体的步骤：

  1. 创建和管理相机

    with pylon.InstantCamera(pylon.FirstFound) as camera:

    这行代码完成了两项重要操作：

    • 它选择 第一个可用的相机，使用传输层工厂创建一个 pylon 设备对象，并将其封装在一个 InstantCamera 对象中以便于使用。
    • 使用 with 确保即使发生错误也能自动释放资源并正确关闭相机。

  2. 开始采集

    camera.StartGrabbingMax(1)

    如果相机尚未打开，此操作会将其打开，启动采集引擎，并指示相机执行以下操作：

    • 精确采集 一帧图像。
    • 随后停止采集。

    这非常适合测试，因为它可以避免无限循环。

    也可以通过预先调用 Open 来打开相机。

    camera.Open()

    打开操作会建立连接并使相机准备好执行以下任务：

    • 配置参数
    • 开始采集

  3. 检索采集结果

    with camera.RetrieveResult(5000) as grab_result:

    此调用将阻塞，直到发生以下任一事件：

    • 帧可用。
      或
    • 达到超时时间 (5000 ms)。

    在内部，您是从 buffer queue 中提取图像。

  4. 验证采集

    if grab_result.GrabSucceeded():

    即使返回了采集结果，采集也可能失败（例如传输错误）。在实用数据之前，务必检查是否成功。

  5. 创建像素数据的副本（可选）

    采集结果使用来自缓冲区池的缓冲区。当您访问 grab_result.Array时，您会获得采集结果缓冲区数据的副本。或者，您也可以使用 GetMemoryView() 或 GetArrayZeroCopy() 来访问数据而无需复制。

    由于 with 块已被释放，因此采集结果中的缓冲区在离开 grab_result 块后将失效。若要在 with 块之外使用像素数据，您需要将其复制。您可以使用 Array 函数来创建像素数据的副本。

    image = grab_result.Array

  6. 使用图像

    print(image.shape)

    这确认了以下内容：

    • 图像存在。
    • 数据具有有效的形状。

为交互式 GigE 会话启用 ConnectionGuard#

当您从调试器打开 GigE 相机时，pylon 会自动启用 ConnectionGuardEnable 在……之前 Open()。这会执行两项操作：

  • 它将心跳超时时间增加到 60 分钟，以防止相机意外重启。
  • 如果您的程序突然停止，它会优雅地关闭连接。

如果您想显式进行设置，请在打开相机之前进行：

from pypylon import pylon

with pylon.InstantCamera() as camera:
    camera.Attach(pylon.FirstFound)
    camera.TLNodeMap.ConnectionGuardEnable.Value = True
    camera.Open()

这在您希望在调试器会话之外保持相同行为时非常有用。

心智模型#

此可视化图表展示了内部发生的情况。

Camera (hardware)
      ↓
pylon driver + buffers
      ↓
Transport layer (USB/GigE)
      ↓
RetrieveResult()
      ↓
NumPy array (your application)

核心思想：

  • 相机异步运行（生产图像帧）。
  • 您的 Python 代码同步消费图像帧。

缓冲区位于两者之间，使相机和应用程序这两个世界相互解耦。

核心要点#

  • 始终检查 GrabSucceeded().
  • 在离开结果作用域或释放抓取结果之前，务必复制图像数据，例如使用 Array 函数。
  • 使用 StartGrabbingMax(1) 进行简单测试。或者，您也可以使用 GrabOne(5000).
    StartGrabbingMax(1) 仅抓取一幅图像。 GrabOne(5000) 抓取一幅图像，但在 5000 µs 后超时。
  • 使用 with 以确保安全处理资源。

一旦理解了此模式，您就可以在此基础上编写用于处理以下任务的代码：