Pylon C++ Programmer's Guide

移步至Pylon C++ Programmer's Guide观看效果更佳

Getting Started

pylon编程指南是一个关于如何使用Basler pylon C++ API进行编程的快速指南。它可以与pylon示例代码一起使用，以帮助初学者入门。此外，API renfence提供了有关Basler pylon C++接口的描述。接口的描述也可在pylon的头文件中找到。在使用Microsoft Visual Studio 时，右键点击所需的方法或类，并从上下文菜单中选择“转到声明”，以访问相关的文档。

对于为Basler blaze相机编程的信息，请参考pylon为blaze提供的补充包（可在Basler网站上下载）。这包括了一个C++ API和一个.NET API，以及示例代码。

Common Settings for Building Applications with pylon (Linux)

这一部分展示了使用pylon和GNU工具链构建应用程序的最常见的Linux构建设置。有关更多信息，请查阅Advanced Topics部分。

为了集中管理负责构建基于pylon的应用程序所需的所有参数，我们创建了pylon-config工具。它的工作方式类似于pkg-config，您可以调用pylon-config --help来获取支持的参数列表。

在典型的基于GNU Make的项目中，您可以在Makefile中添加以下行：

PYLON_ROOT ?= /opt/pylon
CPPFLAGS   += $(shell $(PYLON_ROOT)/bin/pylon-config --cflags)
LDFLAGS    += $(shell $(PYLON_ROOT)/bin/pylon-config --libs-rpath)
LDLIBS     += $(shell $(PYLON_ROOT)/bin/pylon-config --libs)

如有需要，您现在可以使用环境变量<PYLON_ROOT>覆盖默认的安装路径。例如：

PYLON_ROOT=/path/to/your/pylon/install make

Initialization/Uninitialization of the pylon Runtime Library

在使用pylon API前必须初始化pylon运行时系统。基于pylon的应用程序在使用pylon运行时系统的任何其他功能之前必须调用PylonInitialize()。应用程序退出前，必须调用PylonTerminate()方法以释放pylon运行时系统分配的资源。

Pylon::PylonAutoInitTerm便利类有助于执行上述操作。Pylon::PylonAutoInitTerm的构造函数调用PylonInitialize()，析构函数调用PylonTerminate()。这确保了在Pylon::PylonAutoInitTerm类型对象的生命周期内，pylon运行时系统被初始化。

示例如下：

#include <pylon/PylonIncludes.h>
using namespace Pylon;

int main(int argc, char* argv[])
{

  Pylon::PylonAutoInitTerm autoInitTerm;  // PylonInitialize() will be called now

  // Use pylon
  // ..

}  // autoInitTerm's destructor calls PylonTerminate() now

Advanced Topics包含MFC用户的附加信息

Error Handling

在出现错误的情况下，pylon类中的方法可能会抛出C++异常。pylon C++ API抛出的异常类型为GenericException或其子类。您应该使用捕获GenericException的异常处理程序来保护pylon调用。例如：

try
{
  camera.Width.SetValue(640);
}
catch (const GenericException & e)
{
  cerr << "设置AOI宽度失败。原因："
  << e.GetDescription() << endl;
}

Creating a pylon Device

在 pylon 中，物理相机设备由pylon Devices表示。以下示例展示了如何创建一个pylon设备：

CInstantCamera camera(CTlFactory::GetInstance().CreateFirstDevice());

创建第一个找到的相机设备，例如用于仅使用一个相机的视觉系统。Advanced Topics展示了如何处理多个相机设备以及如何找到特定的相机设备。

The Instant Camera Classes

即时相机(Instant Camera)类使得仅通过几行代码就可以抓取图像，将编程工作量降至最低。即时相机类内部使用一个pylon设备(ptlon Device)。需要创建pylon设备并将其附加到即时相机对象上以进行操作。

示例:

// Create an instant camera object with the camera device found first.
CInstantCamera camera( CTlFactory::GetInstance().CreateFirstDevice() );

// Print the model name of the camera.
cout << "Using device " << camera.GetDeviceInfo().GetModelName() << endl;

// Start the grabbing of c_countOfImagesToGrab images.
// The camera device is parameterized with a default configuration which
// sets up free-running continuous acquisition.
camera.StartGrabbing( c_countOfImagesToGrab );

// This smart pointer will receive the grab result data.
CGrabResultPtr ptrGrabResult;

// Camera.StopGrabbing() is called automatically by the RetrieveResult() method
// when c_countOfImagesToGrab images have been retrieved.
while (camera.IsGrabbing())
{
    // Wait for an image and then retrieve it. A timeout of 5000 ms is used.
    camera.RetrieveResult( 5000, ptrGrabResult, TimeoutHandling_ThrowException );

    // Image grabbed successfully?
    if (ptrGrabResult->GrabSucceeded())
    {
        // Access the image data.
        cout << "SizeX: " << ptrGrabResult->GetWidth() << endl;
        cout << "SizeY: " << ptrGrabResult->GetHeight() << endl;
        const uint8_t* pImageBuffer = (uint8_t*) ptrGrabResult->GetBuffer();
        cout << "Gray value of first pixel: " << (uint32_t) pImageBuffer[0] << endl << endl;

    }
    else
    {
        cout << "Error: " << std::hex << ptrGrabResult->GetErrorCode() << std::dec << " " << ptrGrabResult->GetErrorDescription() << endl;
    }
}

上述代码可以在示例代码中的Grab Sample中找到。

The Main Features of an Instant Camera Class

即时相机类为访问相机设备提供了便捷的途径，同时具有高度的可定制性。以下列表展示了即时相机类的主要功能：

• 它作为单一访问点用于访问相机功能。
• 它可以“开箱即用”，无需设置任何参数。相机使用设备的默认配置。默认配置可以被覆盖。
• 它管理pylon设备的生命周期。
• 它自动打开和关闭pylon设备。
• 它处理缓冲区的创建、重用和销毁。
• 如有需要，它提供一个抓取循环线程。
• 它可以检测相机设备的移除。
• 它支持高级相机功能，如块模式和事件报告（相机事件）。
• 可以通过派生来扩展。
• 可以通过注册额外的事件处理器对象来扩展。

Types of Instant Camera Classes

在开始编程之前，你需要确定要使用哪种即时相机类。下表显示了可用的即时相机类：

Name of Class	Usable for Device Type	Device-specific
Pylon::CInstantCamera (推荐)	All cameras	No
Pylon::CBaslerUniversalInstantCamera (新手推荐)	All cameras	No

CInstantCamera和CBaslerUniversalInstantCamera允许你操作所有类型的相机设备。

CBaslerUniversalInstantCamera类是CInstantCamera类的一个特化，它通过一个参数类对其进行了扩展。参数类为每个相机参数提供了一个成员。附加的参数类提供了IDE自动补全功能（例如，Visual Studio中的IntelliSense），在开发应用程序时非常有帮助。虽然这会增加一点运行时开销，但这种开销非常小，可以忽略不计。

后续内容请移步至Pylon C++ Programmer's Guide