Pylon Logo Basler Logo
Programmer's Guide

Getting Started

The pylon Programmer's Guide is a quick guide on how to program using the Basler pylon C++ API. It can be used together with the pylon sample code for getting started. Additionally, the API reference provides documentation about the Basler pylon C++ interface. The documentation of the interfaces is also available in the header files of pylon.

Common Settings for Building Applications with pylon

This section shows the most common Linux build settings for building an application using pylon and the GNU tool chain. Consult the Advanced Topics section for more information.

To collect all the required parameters to build a pylon-based application, we created the pylon-config utility. It works like pkg-config and you can call pylon-config –help to get a list of supported parameters.

In a typical GNU Make-based project you can add the following lines to your Makefile:

PYLON_ROOT ?= /opt/pylon6
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)

If needed, you can now overwrite the default installation path using the environment variable <PYLON_ROOT>. E.g.:

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

Debugging pylon Applications Using GigE Cameras

When debugging a pylon application using GigE cameras you may encounter heartbeat timeouts. The application must send special network packets to the camera in defined intervals. If the camera doesn't receive these heartbeats it will consider the connection as broken and won't accept any commands from the application. This requires setting the heartbeat timeout of a camera to a higher value when debugging. The Advanced Topics section shows how to do this.

Initialization/Uninitialization of the pylon Runtime Library

The pylon runtime system must be initialized before use. A pylon-based application must call the PylonInitialize() method before using any other functions of the pylon runtime system. Before an application exits, it must call the PylonTerminate() method to free resources allocated by the pylon runtime system.

The Pylon::PylonAutoInitTerm convenience class helps to do the above. The constructor of PylonAutoInitTerm calls PylonInitialize(), the destructor calls PylonTerminate(). This ensures that the pylon runtime system is initialized during the lifetime of an object of the PylonAutoInitTerm type.

Example:

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

Error Handling

In the case of errors, the methods of pylon classes may throw C++ exceptions. The pylon C++ API throws exceptions of type GenericException or that are subclasses of GenericException. You should guard pylon calls with exception handlers catching GenericException. Example:

try
{
camera.Width.SetValue( 640 );
}
catch (const GenericException & e)
{
cerr << "Failed to set the AOI width. Reason: "
<< e.GetDescription() << endl;
}

Creating a pylon Device

In pylon, physical camera devices are represented by pylon Devices. The following example shows how to create a pylon Device:

IPylonDevice* pDevice = CTlFactory::GetInstance().CreateFirstDevice();

The first found camera device is created, e.g. for a vision system that uses only one camera. The Advanced Topics section shows how to handle multiple camera devices and how to find specific camera devices.

The Instant Camera Classes

Instant Camera classes make it possible to grab images with a few lines of code reducing the programming effort to a minimum. An Instant Camera class uses a pylon Device internally. The pylon Device needs to be created and attached to the Instant Camera object for operation.

Example:

// 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: " << ptrGrabResult->GetErrorCode() << " " << ptrGrabResult->GetErrorDescription() << endl;
}
}

The above code snippet can be found in the code sample Grab.

The Main Features of an Instant Camera Class

The Instant Camera classes establish convenient access to a camera device while being highly customizable. The following list shows the main features of an Instant Camera class:

Types of Instant Camera Classes

Before starting to program you need to decide what Instant Camera class to use. The following table shows the available Instant Camera classes:

Name of Class Usable for Device Type Device-specific
Pylon::CInstantCamera (recommended) All cameras No
Pylon::CBaslerUniversalInstantCamera (recommended for novice users) All cameras No

The CInstantCamera and the CBaslerUniversalInstantCamera camera classes allow you to operate camera devices of all types.

The CBaslerUniversalInstantCamera class is a specialization of the CInstantCamera class, extending it by a parameter class. The parameter class provides a member for each camera parameter. The additional parameter class provides IDE auto completion (e.g., IntelliSense in Visual Studio) and is helpful when developing an application. It adds a small but neglectable runtime overhead.

Instant Camera Event Handler Basics

The Instant Camera classes allow to register event handler objects for customizing the behavior of the camera object, for processing grab results, and for handling camera events. The following list shows the available event handler types.

Note
For the CBaslerUniversalInstantCamera class, separate event handler base classes are available. These classes use the CBaslerUniversalInstantCamera class and the corresponding grab result smart pointer class.

A custom event handler class can override one or more virtual methods of the base class. For instance whenever Pylon::CConfigurationEventHandler::OnOpened is called by an Instant Camera object it is the right time to set up camera parameters. The following code snippet shows an example of a configuration event handler setting the image area of interest (Image AOI) and the pixel format.

class CPixelFormatAndAoiConfiguration : public Pylon::CConfigurationEventHandler
{
public:
{
try
{
// Allow all the names in the namespace GenApi to be used without qualification.
using namespace Pylon;
// Get the camera control object.
GenApi::INodeMap& nodemap = camera.GetNodeMap();
// Get the parameters for setting the image area of interest (Image AOI).
CIntegerParameter width(nodemap, "Width");
CIntegerParameter height(nodemap, "Height");
CIntegerParameter offsetX(nodemap, "OffsetX");
CIntegerParameter offsetY(nodemap, "OffsetY");
// Maximize the Image AOI.
offsetX.TrySetToMinimum(); // Set to minimum if writable.
offsetY.TrySetToMinimum(); // Set to minimum if writable.
width.SetToMaximum();
height.SetToMaximum();
// Set the pixel data format.
CEnumParameter(nodemap, "PixelFormat").SetValue("Mono8");
}
catch (const Pylon::GenericException& e)
{
throw RUNTIME_EXCEPTION( "Could not apply configuration. const GenericException caught in OnOpened method msg=%hs", e.what());
}
}
};

One or more event handler objects can be registered at the Instant Camera object. The following code snippet shows an example of how the above event handler is registered and appended to the configuration event handler list.

// Register an additional configuration handler to set the image format and adjust the AOI.
// By setting the registration mode to RegistrationMode_Append, the configuration handler is added instead of replacing
// the already registered configuration handler.
camera.RegisterConfiguration( new CPixelFormatAndAoiConfiguration, RegistrationMode_Append, Cleanup_Delete);

For more information about registering and deregistering event handlers consult the interface documentation of the Instant Camera class used and the codes of the following samples: ParametrizeCamera_Configurations, Grab_UsingGrabLoopThread, and Grab_CameraEvents.

Note
It is possible to use the Instant Camera classes without using event handler objects.

Configurations

Configuration event handler classes are also just called "configurations" because they encapsulate certain camera configurations. The pylon C++ API comes with the following configuration classes:

These classes are provided as header files. This makes it possible to see what parameters of the camera are changed. The code can be copied and modified for creating own configuration classes. Pylon::CSoftwareTriggerConfiguration for instance can be used as basis for creating a hardware trigger configuration with few modifications. Pylon::CAcquireContinuousConfiguration is already registered when creating an Instant Camera class, providing a default setup that will work for most cameras.

The following example shows how to apply the software trigger configuration:

// Register the standard configuration event handler for enabling software triggering.
// The software trigger configuration handler replaces the default configuration
// as all currently registered configuration handlers are removed by setting the registration mode to RegistrationMode_ReplaceAll.
camera.RegisterConfiguration( new CSoftwareTriggerConfiguration, RegistrationMode_ReplaceAll, Cleanup_Delete);

The code sample ParametrizeCamera_Configurations provides more examples showing the use of configurations.

Handling Multiple Cameras Using Instant Camera Arrays

The Instant Camera Array classes help managing multiple cameras in a system. An Instant Camera Array represents an array of instant camera objects. It provides almost the same interface as an Instant Camera for grabbing. The main purpose of the CInstantCameraArray is to simplify waiting for images and camera events of multiple cameras in one thread. This is done by providing a single RetrieveResult method for all cameras in the array. The following classes are available:

The Grab_MultipleCameras code sample illustrates the use of the CInstantCameraArray class.

Accessing Parameters

For camera configuration and for accessing other parameters, the pylon API uses the technologies defined by the GenICam standard. The GenICam specification (http://www.GenICam.org) defines a format for camera parameter description files. These files describe the configuration interface of GenICam compliant cameras. The description files are written in XML (eXtensible Markup Language) and describe camera registers, their interdependencies, and all other information needed to access high-level features such as Gain, Exposure Time, or Image Format by means of low level register read and write operations.

The elements of a camera description file are represented as software objects called Nodes. For example, a node can represent a single camera register, a camera parameter such as Gain, a set of available parameter values, etc. Each node implements the GenApi::INode interface.

The nodes have different types. For example, there are nodes representing integer values and other nodes representing strings. For each type of parameter, there is an interface in GenApi. pylon provides additional interfaces and parameter classes to simplify access to the GenApi interfaces. These interfaces and parameter classes are described in the Parameter Types section. The Access Modes for Parameters section introduces the concept of a parameter access mode. An access mode property is used to determine whether a parameter is available, readable, or writable.

The complete set of nodes is stored in a data structure called node map.

Note
Not only camera devices are parameterized using GenICam node maps. Also, most pylon objects provide node maps to provide access to their parameters. Therefore, a common way for accessing parameters is established.

Opening and Closing a Camera

Before reading or writing parameters of a camera, the drivers involved must be initialized and a connection to the physical camera device must be established. This is done by calling the Open() method. The camera can be closed using the Close() method.

Native Parameter Access

pylon provides programming interface classes that are created from parameter description files using the code generators. These classes are exported by the Universal Instant Camera class. This provides a member for each available parameter. The Pylon::CBaslerUniversalInstantCamera class extends the GenApi interfaces to simplify parameterization. This is the easiest way to access parameters.

Example:

// Maximize the image area of interest (Image AOI).
camera.OffsetX.TrySetToMinimum();
camera.OffsetY.TrySetToMinimum();
camera.Width.SetToMaximum();
camera.Height.SetToMaximum();
// Set the pixel data format.
camera.PixelFormat.SetValue(PixelFormat_Mono8);

The ParametrizeCamera_NativeParameterAccess code sample shows how to access parameters via the Pylon::CBaslerUniversalInstantCamera class.

Generic Parameter Access

The complete set of nodes is stored in a data structure called node map. At runtime, a node map is instantiated from an XML description. The parameters or nodes must be accessed using a node map object together with pylon parameter classes based on Pylon::CParameter.

Example (setting the same parameters as in the above example):

// Allow all the names in the namespace GenApi to be used without qualification.
using namespace Pylon;
// Get the camera control object.
GenApi::INodeMap& nodemap = camera.GetNodeMap();
// Get the parameters for setting the image area of interest (Image AOI).
CIntegerParameter width(nodemap, "Width");
CIntegerParameter height(nodemap, "Height");
CIntegerParameter offsetX(nodemap, "OffsetX");
CIntegerParameter offsetY(nodemap, "OffsetY");
// Maximize the Image AOI.
offsetX.TrySetToMinimum(); // Set to minimum if writable.
offsetY.TrySetToMinimum(); // Set to minimum if writable.
width.SetToMaximum();
height.SetToMaximum();
// Set the pixel data format.
CEnumParameter(nodemap, "PixelFormat").SetValue("Mono8");

The ParametrizeCamera_GenericParameterAccess code sample shows how to use the generic parameter access.

Where to Find Information About Camera Parameters

The following sources can be used to get information about camera parameters:

Parameter Types

Integer Parameters

The GenApi::IInteger interface (optionally extended by Pylon::IIntegerEx and Pylon::CIntegerParameter) is used to access integer parameters. An integer parameter represents a feature that can be set by an integer number, such as a camera's image width or height in pixels. The current value of an integer parameter is augmented by a minimum and a maximum value, defining a range of allowed values for the parameter, and by an increment that acts as a 'step width' for changes to the parameter's value. The set of all allowed values for an integer parameter can hence be expressed as x := {minimum} + N * {increment}, with N = 0,1,2 ..., x <= {maximum}. The current value, minimum, maximum, and increment can all be accessed as 64 bit values. The following example prints all valid values for the Width parameter:

camera.Width = camera.Width.GetMin();
int64_t w = camera.Width.GetMin();
while ( w <= camera.Width.GetMax() )
{
cout << w;
w += camera.Width.GetInc();
}

There are two equivalent possibilities for setting a value using the GenApi::IInteger interface:

There are also two equivalent ways to get a parameter's current value:

Floating Point Parameters

Floating point parameters are represented by GenApi::IFloat, Pylon::IFloatEx, and Pylon::CFloatParameter objects. A float parameter represents a feature that can be set by a floating-point value, such as a camera's exposure time expressed in seconds. The floating point parameter is similar to the integer parameter with two exceptions: all values are of the 'double' type (double precision floating point numbers as defined by the IEEE 754 standard) and there is no increment value. Hence, a float parameter is allowed to take any value from the interval {minimum} <= x <={maximum}.

Boolean Parameters

A Boolean parameter represents a binary-valued feature which can be enabled or disabled. It is represented by the GenApi::IBoolean interface and Pylon::IBooleanEx and CBooleanParameter objects. Example: Any 'switch' to enable or disable a feature, such as a camera's external trigger input. Set and get operations are similar to the ones used by the GenApi::IInteger interface.

Enumeration Parameters

The GenApi::IEnumeration interface (optionally extended by Pylon::IEnumerationEx, Pylon::CEnumParameter, and Pylon::IEnumerationT) is used to represent camera parameters that can take any value from a predefined set. Example: Parameters such as PixelFormat or TestImageSelector.

Example:

camera.PixelFormat.SetValue( PixelFormat_Mono16 );

Command Parameters

Command parameters (GenApi::ICommand, Pylon::ICommandEx, and Pylon::CCommandParameter) are used for parameters that trigger an action or an operation inside of the camera, e.g., issue a software trigger. The action is issued by calling the GenApi::ICommand::Execute() method. The GenApi::ICommand::IsDone() method can be used to determine whether a running operation has finished.

String Parameters

The GenApi::IString interface and the Pylon::IStringEx and Pylon::CStringParameter objects provide access to string parameters. The GenICam::gcstring class is used to represent strings. The gcstring class is similar to the C++ Standard Library std::string class. pylon uses GenICam::gcstring by providing the Pylon::String_t type definition.

Access Modes for Parameters

Each parameter has an access mode that describes whether a feature is implemented, available, readable, and writable. For a given camera, a feature may not be implemented at all. For example, a monochrome camera will not include a white balance feature. Depending on the camera's state, a feature may temporarily not be available. For example, a parameter related to external triggering may not be available when the camera is in free run mode. Available features can be read-only, write-only, or readable and writable.

The current state of a parameter can be queried by calling the parameter's GetAccessMode() method, which returns a GenApi::EAccessMode enumeration value described in the following table:

EAccessModeImplementedAvailableReadableWritable
NINo No No No
NAYesNo No No
WOYesYesNoYes
ROYesYesYesNo
RWYesYesYesYes

Typically, it is sufficient to check if a parameter is readable or writable. For this purpose, all pylon parameter interfaces and classes implement the methods Pylon::IValueEx::IsReadable() and Pylon::IValueEx::IsWritable().

Handling Differences Between Different Cameras Models

Most features, e.g., Gain, are named according to the GenICam Standard Feature Naming Convention (SFNC). The SFNC defines a common set of features, their behavior, and the related parameter names. All Basler USB 3.0 and CoaXPress as well as most GigE, e.g., ace 2 GigE, cameras are based on the SFNC version 2.0 or later. Older Basler GigE camera models, however, are based on previous SFNC versions. Accordingly, the behavior of these cameras and some parameter names will be different. The following sections show how to handle this.

Try Methods

The pylon parameter interfaces and classes provide methods that are prefixed with "Try", e.g., Pylon::IEnumerationEx::TrySetValue(int64_t). For these methods, the action is executed if the parameter is writable. Sometimes, the value must also be settable.

Example showing how turn GainAuto off if the camera provides GainAuto:

CEnumParameter gainAuto(nodemap, "GainAuto");
gainAuto.TrySetValue("Off");

For the exact semantics of a "Try" method, check its documentation.

OrDefault Methods

Methods that are suffixed with "OrDefault", e.g., GetValueOrDefault(), can be used to read a parameter value if it is readable or otherwise return a default value.

Example:

//code that runs for cameras with and without chunk support.
if (camera.ChunkModeActive.GetValueOrDefault(false))
{
//do something if chunk mode is active
}

Checking the SFNC Version

If your code has to work with multiple camera device types that are compatible with different SFNC versions, you can use GetSfncVersion() to handle differences in parameter name and behavior.

Example for Generic Parameter Access :

// Check to see which Standard Feature Naming Convention (SFNC) is used by the camera device.
if ( camera.GetSfncVersion() >= Sfnc_2_0_0)
{
// Access the Gain float type node. This node is available for USB camera devices.
// USB camera devices are compliant to SFNC version 2.0.
CFloatParameter gain(nodemap, "Gain");
gain.SetValuePercentOfRange(50.0);
cout << "Gain (50%) : " << gain.GetValue() << " (Min: " << gain.GetMin() << "; Max: " << gain.GetMax() << ")" << endl;
}
else
{
// Access the GainRaw integer type node. This node is available for IIDC 1394 and GigE camera devices.
CIntegerParameter gainRaw(nodemap, "GainRaw");
gainRaw.SetValuePercentOfRange(50.0);
cout << "Gain (50%) : " << gainRaw.GetValue() << " (Min: " << gainRaw.GetMin() << "; Max: " << gainRaw.GetMax() << "; Inc: " << gainRaw.GetInc() << ")" << endl;
}

Grabbing Images

This section shows how to grab images using the Instant Camera class. Before grabbing images the camera parameters must be set up using one or more of the following approaches:

Note
Using the latter three approaches may require to remove the default configuration after the Instant Camera object has been created. The following example shows how to do this. The configuration must be removed before calling the Open() method.
// Create a camera object
CInstantCamera camera;
// Remove the default configuration
camera.RegisterConfiguration( (CConfigurationEventHandler*) NULL, RegistrationMode_ReplaceAll, Cleanup_None);

Acquire, Transfer, and Grab Images

In this document we distinguish between image acquisition, image data transfer, and image grabbing.

We denote the processes inside the camera as image acquisition. When a camera starts image acquisition, the sensor is exposed. When exposure is complete, the image data is read out from the sensor.

The acquired image data is transferred from the camera's memory to the computer using an interface such as USB or Gigabit Ethernet.

The process of writing the image data into the computer's main memory is referred to as "grabbing" an image.

The Grab Result

The data of a grabbed image is held by a Grab Result Data object. The Grab Result Data object can't be directly accessed. It is always held by a grab result smart pointer, e.g. the basic grab result smart pointer CGrabResultPtr . The combination of smart pointer and Grab Result Data object is also referred to as grab result. The smart pointer controls the reuse and the lifetime of the Grab Result Data object and the associated image buffer. When all smart pointers referencing a Grab Result Data object go out of scope, the grab result's image buffer is reused for grabbing. Due to the smart pointer concept, a Grab Result Data object and the associated image buffer can live longer than the camera object used for grabbing the image data. The CBaslerUniversalInstantCamera class has a specific Grab Result Data object and a specific grab result smart pointer. The specific grab result smart pointer can be converted to or from the basic grab result smart pointer CGrabResultPtr by copying or assigning.

Note
The grabbing will stop with a buffer underrun when the grab results are never released, e.g. when put into a container.

The grab result smart pointer classes provide a cast operator that allows passing a grab result smart pointer directly to functions or methods that take a const Pylon::IImage& as parameter, e.g. image saving functions.

Attention
The returned reference to IImage is only valid as long the grab result smart pointer it came from is not destroyed.

Buffer Handling

New buffers are automatically allocated for each grab session starting with StartGrabbing() . The buffer of a grabbed image is held by the Grab Result Data object. While the grabbing is in progress a buffer is reused when the Grab Result Data object is released by the grab result smart pointer. If the Grab Result Data object is released when the grabbing has stopped then the buffer is freed.

The number of used image data buffers can be set using the MaxNumBuffer parameter. The default amount of buffers used for grabbing is 10. The buffer size required for grabbing is automatically determined.

The number of allocated buffers is automatically reduced when grabbing a defined number of images smaller than the value of MaxNumBuffer, e.g. 5.

Note
A buffer factory can be attached to an Instant Camera object for using user provided buffers. The use of a buffer factory is optional and intended for advanced use cases only. Consult the Advanced Topics section for more information.

The Grab Engine

The Instant Camera grab engine consists of an empty buffer queue, an output queue, and a grab thread. The grab engine uses a Low Level API stream grabber to grab images. The empty buffer queue and the output queue can hold the number of buffers defined by the MaxNumBuffer parameter. MaxNumQueuedBuffer buffers are passed to the Low Level API stream grabber at any time. All queues work in FIFO mode (First-In-First-Out). The grab engine thread ensures that the stream grabber does not run out of buffers as long as buffers are available in the empty buffer queue.

The Default Grab Strategy One By One

The Instant Camera supports different grab strategies. The default strategy is One By One. When the grab strategy One By One is used images are processed in the order of their acquisition.

pylon_buffer_flow_one_by_one.png
The Buffer Flow Using Grab Strategy One By One

More information about grab strategies can be found in the advanced topics section.

Grabbing Images in a Loop

The following example shows a simple grab loop:

// 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: " << ptrGrabResult->GetErrorCode() << " " << ptrGrabResult->GetErrorDescription() << endl;
}
}

The camera object is created. The grabbing is started by calling StartGrabbing() . Since the camera is not open yet, it is automatically opened by the StartGrabbing() method. The default configuration event handler is called and it applies the default configuration. Images are grabbed continuously by the Instant Camera object and the grab results are placed into the Instant Camera's output queue in the order they are aqcuired by the camera (Grab Strategy One By One). The RetrieveResult() method is used to wait for a grab result and for retrieving it from the output queue. Some of the grab result data is printed to the screen after it is retrieved. StopGrabbing() is called automatically by the RetrieveResult() method when c_countOfImagesToGrab images have been retrieved. The while statement condition is used to check if the grabbing has been stopped.

It is possible to start grabbing for an unlimited number of images by omitting the maximum number of images to grab in the StartGrabbing() call and call StopGrabbing() from inside the grab loop to finish grabbing.

The above code snippet can be found in the Grab code sample.

Grabbing Images Using the Grab Loop Thread Provided by the Instant Camera

The Instant Camera class can optionally provide a grab loop thread. The thread runs a grab loop calling RetrieveResult() repeatedly. When using the provided grab loop thread an image event handler is required to process the grab results.

The following image event handler is used:

class CImageEventPrinter : public CImageEventHandler
{
public:
virtual void OnImageGrabbed( CInstantCamera& camera, const CGrabResultPtr& ptrGrabResult)
{
std::cout << "OnImageGrabbed event for device " << camera.GetDeviceInfo().GetModelName() << std::endl;
// Image grabbed successfully?
if (ptrGrabResult->GrabSucceeded())
{
std::cout << "SizeX: " << ptrGrabResult->GetWidth() << std::endl;
std::cout << "SizeY: " << ptrGrabResult->GetHeight() << std::endl;
const uint8_t *pImageBuffer = (uint8_t *) ptrGrabResult->GetBuffer();
std::cout << "Gray value of first pixel: " << (uint32_t) pImageBuffer[0] << std::endl;
std::cout << std::endl;
}
else
{
std::cout << "Error: " << ptrGrabResult->GetErrorCode() << " " << ptrGrabResult->GetErrorDescription() << std::endl;
}
}
};

The following example shows how to grab using the grab loop thread provided by the Instant Camera object:

// The image event printer serves as sample image processing.
// When using the grab loop thread provided by the Instant Camera object, an image event handler processing the grab
// results must be created and registered.
camera.RegisterImageEventHandler( new CImageEventPrinter, RegistrationMode_Append, Cleanup_Delete);
// Start the grabbing using the grab loop thread, by setting the grabLoopType parameter
// to GrabLoop_ProvidedByInstantCamera. The grab results are delivered to the image event handlers.
// The GrabStrategy_OneByOne default grab strategy is used.
cerr << endl << "Enter \"t\" to trigger the camera or \"e\" to exit and press enter? (t/e)" << endl << endl;
// Wait for user input to trigger the camera or exit the program.
// The grabbing is stopped, the device is closed and destroyed automatically when the camera object goes out of scope.
char key;
do
{
cin.get(key);
if ( (key == 't' || key == 'T'))
{
// Execute the software trigger. Wait up to 1000 ms for the camera to be ready for trigger.
if ( camera.WaitForFrameTriggerReady( 1000, TimeoutHandling_ThrowException))
{
camera.ExecuteSoftwareTrigger();
}
}
}
while ( (key != 'e') && (key != 'E'));

First, the image event handler is registered. It prints a message on the screen for every grabbed image. It serves as image processing in this example. The grabbing is started using StartGrabbing() for an unlimited number of images and uses the grab loop thread provided by the Instant Camera object by setting the second parameter to GrabLoop_ProvidedByInstantCamera. The main thread can now be used to query the user for input to either trigger an image or to exit the input loop. The grabbing is not explicitly stopped in this example and could be stopped by calling StopGrabbing() . The above code snippet can be found in the Grab_UsingGrabLoopThread code sample.

Grabbing a Single Image

For convenience, the GrabOne() method can be used to grab a single image. The following code shows a simplified version of what is done:

//grab one image
//grab is stopped automatically due to maxImages = 1
return RetrieveResult( timeoutMs, grabResult, timeoutHandling) && grabResult->GrabSucceeded();
Note
Using GrabOne() is more efficient if the pylon Device is already open, otherwise the pylon Device is opened and closed automatically for each call.
Grabbing single images using Software Trigger (CSoftwareTriggerConfiguration ) is recommended if you want to maximize the frame rate. This is because the overhead per grabbed image is reduced compared to Single Frame Acquisition. The grabbing can be started using StartGrabbing() . Images are grabbed using the WaitForFrameTriggerReady() ,ExecuteSoftwareTrigger() and RetrieveResult() methods instead of using GrabOne() . The grabbing can be stopped using StopGrabbing() when done.

Using Advanced Camera Features

Handling Camera Events

Basler GigE Vision and USB3 Vision cameras can send event messages. For example, when a sensor exposure has finished, the camera can send an Exposure End event to the computer. Events can be received by registering an image event handler at an Instant Camera class. See the Advanced Topics section for more information.

Accessing Chunk Features

Basler Cameras are able to send additional information as so-called data chunks appended to the image data, such as frame counters, time stamps, or CRC checksums. Data chunks are automatically parsed by the Instant Camera class if activated. See the Advanced Topics section for more information.

Getting Informed About Camera Device Removal

To get informed about camera device removal the method IsCameraDeviceRemoved() can be queried or a configuration event handler can be registered. The virtual method OnCameraDeviceRemoved() is called if a camera device is removed. See the Advanced Topics section for more information.

Note
The OnCameraDeviceRemoved call is made from a separate thread.

GigE Multicast/Broadcast: Grab Images of One Camera on Multiple Computers

Basler GigE cameras can be configured to send the image data stream to multiple destinations. Either IP multicasts or IP broadcasts can be used. For more information consult the advanced topics section.

Image Handling

Besides the Instant Camera classes used for grabbing images pylon offers additional Image Handling Support support for handling grabbed images. There are an image class, an image format converter, and the loading and saving of images.

The pylon Image Class

When working with image data the handling of buffer size and lifetime often involves a lot of coding. The Pylon::CPylonImage class simplifies this. It also allows to attach a buffer of a grab result preventing its reuse as long as required. Additionally, user buffers or buffers provided by third party software packages can be connected. Besides that, the pylon Image class helps when working with image planes or AOIs. The Utility_Image code sample shows the use of the pylon Image class.

The Image Format Converter

The Pylon::CImageFormatConverter creates new images by converting a source image to a different format. Once the format converter is configured it can convert almost all image formats supported by Basler camera devices. The Utility_ImageFormatConverter code sample shows the use of the Image Format Converter class.

The Video Writer

The Pylon::CVideoWriter can be used to create video files in the MP4 format. The Utility_GrabVideo code sample shows the use of the Video Writer class.

Loading and Saving Images

The Pylon::CImagePersistence class supports loading and saving images to disk. The pylon Image classes use this interface internally and provide methods for loading and saving. The Utility_ImageLoadAndSave code sample shows how to load and save images.


pylon 6.1.0
Copyright (c) 2006-2020 Basler AG (Mon Mar 16 2020 10:56:52)