With pylon 7.0 and newer, the pylon vTools have been added to extend the pylon Camera Software Suite with professional image processing capabilities.
New licensable vTools, e.g., for calibration, measurents, code reading (e.g., barcode, Data Matrix, QR), pattern matching, blob analysis, etc. have been added.
In addition, the Workbench feature has been added to the pylon Viewer. The Workbench offers a graphical editor for creating machine vision, medical, and other applications. The Workbench can be accessed from the Workbench menu, the Window menu, or the Workbench button in the pylon Viewer toolbar.
To enable the integration of pylon vTools into customer applications, the pylon Data Processing C++ API has been added. It extends the existing C++ API for camera configuration and image acquistion. To learn more about the API refer to the new Programmer's Guide for the pylon Data Processing C++ API. It can be accessed from the pylon Viewer's Help menu.
Furthermore, SDK sample programs have been added to demonstrate the use of vTools. They can be found under \Development\Samples\pylonDataProcessing\C++ (Windows) or \share\pylon\Samples\pylonDataProcessing\C++ (Linux).
With pylon 7.1 and newer, a support for new Basler ace 2 5GigE cameras has been added. A new GEV filter driver (recommended for Windows) and a new GEV socket driver (recommended for Linux and macOS) that support all 1GigE, 5GigE, and 10GigE network adapters have been added to enable the for best performance and reliability.
The new GEV drivers support among others:
Advanced and robust resend mechanisms
GVSP Extended ID mode
GVCP Pending Acknowledge messages
Firewall traversal
A new PylonGigEConfigurator CLI (for advanced user) and GUI (for beginners) tool has been added. The tool configures and optimizes the complete GigE setup for best usability and performance when used with Basler hardware components, e.g., network adapters and cameras.
In addition, a new handling of the GEV heartbeat timeout has been implemented. In case an application has been started in debug mode and is terminated, the control channel is closed automatically. This allows you to use the GigE camera again immediately after restarting the application.
pylon 6 introduces support for CoaXPress (CXP) cameras. These are connected to the computer via an adapter, e.g., the Basler CXP-12 interface card. The new transport layer is based on the GenICam GenTL standard and is split into two parts, a GenTL Consumer and a GenTL producer. This is implemented for CoaXPress exclusively.
The new Basler ace 2 GigE cameras use feature names that conform to the SFNC 2.5 standard in contrast to the feature names used by previous ace GigE camera models that were based on SFNC 1.x. pylon offers a convenient migration mode that allows you to work with camera devices that are based on different SFNC versions by translating feature names at runtime, automatically adapting your application code accordingly. Use the MigrationModeEnable option to take advantage of this. If the migration mode is enabled, the changes shown under List of Changes are automatically applied at runtime where appropriate. If you are only working with SFNC 2.x-based cameras, however, Basler strongly recommends rewriting your code to make it SFNC 2.x-compatible. See Handling Differences Between Different Cameras Models and Migration Mode for more information regarding this topic.
Please note the following changes will potentially break existing code:
The device-specific camera classes have been deprecated. The CBaslerUniversalInstantCamera class combines all features of these device-specific camera classes and can be used to replace them.
The following table shows the classes that have been deprecated:
Transport Layer
Name of Class
PylonGigE
Pylon::CBaslerGigEInstantCamera
PylonUsb
Pylon::CBaslerUsbInstantCamera
PylonCLSer
Pylon::CBaslerCameraLinkInstantCamera
Deprecation of Device-Specific Device Info Classes#
The device-specific device info classes, e.g., CBaslerGigEDeviceInfo, have been deprecated. The CDeviceInfo class combines all features of these device-specific device info classes and can always be used instead.
The Close method does not throw any exceptions anymore allowing a safe clean-up of your code even in case of problems. It is not required to change existing code because of this.
Furthermore, new functionality has been added to explicitly start and stop streaming. In the past, streaming was started implicitly while calling the PrepareGrab method and it was stopped implicitly when FinishGrab was called. However, since support for GenTL producers, e.g., CoaXPress, has been introduced, it was necessary to add an explicit way of starting and stopping streaming. With the IsStartAndStopStreamingMandatory method it can be determined if this explicit way is required for this particular stream grabber instance. Currently, this is only required when using GenTL producers. In such cases, StartStreamingIfMandatory must be called after calling the PrepareGrab method and RegisterBuffer can only be called in between those two calls. If you want to stop streaming, StopStreamingIfMandatory must be called before deregistering any buffers with DeregisterBuffer and finally calling FinishGrab. For the existing transport layers this behavior is not required. However, the StartStreamingIfMandatory and StopStreamingIfMandatory methods can still be called but will not have any effect. Basler recommends using one of the Instant Camera classes CBaslerUniversalInstantCamera or CInstantCamera for new projects because they will call the new methods for you.
This version of pylon allows accessing the camera interface via the EnumerateInterfaces and the CreateInterface methods. An instance of the IInterface interface class can represent a frame grabber board, a network card, etc. Currently, this object type is mainly used for the pylon GenTL Consumer transport layer, e.g., for CoaXPress. All other pylon transport layers currently return one default interface. The EnumerateInterfaces method can be used to get information (a list of CInterfaceInfo) about all available interfaces belonging to this transport layer.
The Interface class can be used to get information about all cameras attached to this particular interface. You can do that via the methods from IDeviceFactory implemented by the Interface class just like you would normally do using the transport layer.
Before you can access interface parameters, you must open the interface instance. To do this, call Open. To close the interface, use Close. The 'open' status of an interface instance won't change even if the state of the attached cameras changes, e.g., opened or closed.
To release an interface instance you must call the DestroyInterface method.
pylon 5 has been updated to use the most recent GenICam version 3.0. Thanks to GenICam 3, cameras now open about four times faster than in previous GenICam versions. Additionally, GenICam 3 requires only about half as much memory as previous GenICam versions. Both improvements are especially beneficial for systems with low performance. Furthermore, the pylon binaries have been compiled with the newer version of the Visual Studio compilers to benefit from the compiler improvements. Another change is the different deployment of the pylon SDK. For more detailed information, see section Breaking Changes in pylon 5.
The following table shows performance measurements for pylon 4 and pylon 5. The values have been measured using a GigE Vision camera and a USB3 Vision camera connected to a computer with an Intel i7-3770 CPU running at 3.4 GHz. The measured memory consumption is the whole memory consumption of the application used for testing.
GigE Vision
GigE Vision
GigE Vision
GigE Vision
USB3 Vision
USB3 Vision
USB3 Vision
USB3 Vision
x86
x86
x64
x64
x86
x86
x64
x64
pylon4
pylon5
pylon4
pylon5
pylon4
pylon5
pylon4
pylon5
Time to open camera for the first time [ms]
813
197
944
185
430
111
420
102
Memory consumption after device creation [MB]
45.2
26.8
53.7
35.9
29.2
16.9
38.9
21.1
Peak memory consumption during device creation [MB]
65.0
27.7
80.2
35.9
42.1
18.3
56.5
22.9
Time to open camera from GenICam cache [ms]
285
128
340
118
186
75
198
67
Memory consumption after device creation from cache [MB]
25.9
16.2
31.5
20.9
19.4
13.1
23.8
15.2
Peak memory consumption during device creation from cache [MB]
The GenICam v3.0 library, maintained by the GenICam standard group, introduces a few breaking changes. We're taking this as an opportunity to make additional breaking changes in pylon that will avoid breaking changes in future versions of pylon.
The layout of the pylon installation directory has been changed to reflect which files are needed for which purpose.
Subfolder
Description
Applications
Contains the pylon applications, e.g. the pylon Viewer.
Development
Contains everything needed to develop applications using pylon for all supported language bindings. This includes header files, libraries, samples, documentation, and pylon .NET assemblies.
License
Contains all pylon license documents.
Runtime
Contains everything needed to run applications using pylon, except for the drivers.
The following environment variables are obsolete and no longer set by the installer:
<PYLON_ROOT>
<PYLONC_ROOT>
<PYLON_GENICAM_VERSION>
<PYLON_GENICAM_ROOT>
The following environment variables are now set or changed by the installer:
<PYLON_DEV_DIR> - Contains the path to the Development directory. This environment variable is only set if the SDK component of the installer has been selected.
<PATH> - The Windows <PATH> environment variable is extended by the path to Runtime\Win32 on all Windows operating systems. On x64 Windows operating systems, it is additionally extended by the path to Runtime\x64.
GenICam and GenApi Namespaces and Forward Declarations#
The GenApi and GenICam namespaces are now namespace aliases for more complex namespace names that include the GenICam version. For example, GenApi can be an alias for GenApi_3_0_Basler_pylon_v5_0.
A namespace alias can't be used for forward declarations. Therefore, code using GenApi forward declarations must be changed.
Alternatively, GenICam provides a header file that contains most of the forward declarations:
#include<GenICamFwd.h>
We recommend to only use the Pylon and the GenApi namespace when programming applications using pylon. Most of the types in the GenICam namespace can also be found in the Pylon namespace. You should use Pylon::String_t instead of GenICam::gcstring and Pylon::GenericException instead of GenICam::GenericException. The latter applies to all exceptions in the GenICam namespace.
GenICam::GenericException is no longer derived from std::exception. Therefore, catch clauses in application code using pylon need to be reviewed and updated.
The following exception handling is no longer sufficient:
try{//code using pylon}catch(conststd::exception&e){//handle the exception}
Instead, you must use:
try{//code using pylon}catch(constPylon::GenericException&e){//handle the exception}catch(conststd::exception&e){//handle the exception}
Note
The exception classes in the GenICam namespace are now also available in the Pylon namespace. Therefore, it is not necessary to use the GenICam namespace.
Pylon::PylonInitialize() and Pylon::PylonTerminate() now use reference counting to allow multiple pylon users in one process. You must call PylonInitialize before calling any other pylon functions. PylonTerminate must be called for every time the PylonInitialize function has been called. For example, if an application calls PylonInitialize twice, it must also call PylonTerminate twice. The first call to PylonTerminate just decrements an internal counter; the final PylonTerminate call terminates the pylon runtime system.
To avoid conflicts with non-Basler software based on GenICam, pylon is now delivered with a Basler specific build of GenICam. Therefore, the bootstrapper feature is not needed anymore and has been removed. If not required otherwise, the pylon DLLs can be removed from the list of delay loaded DLLs for all project configurations (Configuration Properties -> Linker -> Input -> Delay Loaded Dlls).
All includes of PylonBootstrapper.h must be removed.
For backwards compatibility, the header file Pylon_W32.h contained the includes for the header files WaitObject.h and WaitObjects.h. Pylon_W32.h has been removed. You can simply include WaitObjects.h instead.
One image is usually seen as block in the image transport. An ID, the Block ID, is assigned to every block. The grab result method Pylon::CGrabResultData::GetBlockID() can now be used to get the Block ID. Previous pylon versions reported Block ID as Frame Number in grab results because Block ID and Frame Number can be equal depending on the camera device used. Therefore, Frame Number and Block ID can also be different for some camera devices. That is why the grab result method Pylon::CGrabResultData::GetFrameNumber() is now deprecated.
pylon 3 extends the API of the previous pylon version by the Instant Camera Classes and further Image Handling Support classes. The Instant Camera classes represent the new API for accessing a camera device. With the new classes it is possible to grab images with a few lines of code giving instant access to grabbed images from a camera device. The previous API used for grabbing is now called Low Level API. It can still be used for existing applications. The Image Handling Support classes help to cover common use cases when working with image data. There are an image class, Windows bitmap image support, a new image format converter, an image window, and support for loading and saving images. Additionally, the GenApi Node Maps GenICam release used by pylon has been updated from version 2.0 to version 2.3. A new set of code samples shows the use of the Instant Camera classes and the Image Handling Support classes.
pylon 3 Is Still Compatible with pylon 2.3 and Offers a New API for Grabbing and Image Handling
The Image Handling support classes can be used together with the Instant Camera classes or the Low Level API. Either the Instant Camera classes or the Low Level API can be used for grabbing images, events or chunk data.
An existing implementation that uses the Low Level API, that is stable and used in the current application should not be changed. In the case of problems you may want to change to the Instant Camera classes. This should drastically reduce the amount of code you need for grabbing and therefore the chance of having a hidden bug.
It is recommended to use the Instant Camera classes for new projects. Only in the case of a rare highly advanced use case that can't be covered using the Instant Camera classes the use of the Low Level API should be considered for a new project. Furthermore, the Instant Camera classes produce only the same overhead a custom grab implementation would cause.
When to Replace Deprecated Pixel Format Converter Classes?#
The image format converter classes based on Pylon::CPixelFormatConverter are now deprecated and can be replaced by the Pylon::CImageFormatConverter class. The Pylon::CImageFormatConverter class is much easier to use. A replacement of the old converters could be considered if it results in much less code for the same operations.
The static methods Pylon::CPixelFormatConverterMonoPacked::Unpack10() and Pylon::CPixelFormatConverterMonoPacked::Unpack12() create a Pylon::CImageFormatConverter object on the stack each time when called and, as a consequence, may take more processing time. If the above methods are used and the additional processing time is not acceptable then the methods should be replaced by using the new converter.
Precautions When Copying Code Snippets from Camera Manuals#
The code snippets included in the Camera Manuals may not have been updated yet to show the API of the Instant Camera classes. In these cases the code snippets illustrating how to grab events, chunks, image data or how to use GigE Multicast still show the use of the Low Level API.
There is a difference when using Generic Parameter Access. An Instant Camera class returns a node map object as reference and not as pointer. This has been changed to avoid additional NULL pointer checks. Example:
// Low Level API:CBaslerGigECameracamera;//...// Get the camera control object.INodeMap&control=*camera.GetNodeMap();constCIntegerPtrHeight=control.GetNode("Height");constCIntegerPtrHeight=camera.GetNodeMap()->GetNode("Height");// Instant Camera Classes:CBaslerGigEInstantCameracamera;//...// Get the camera control object.INodeMap&control=camera.GetNodeMap();constCIntegerPtrWidth=control.GetNode("Width");constCIntegerPtrHeight=camera.GetNodeMap().GetNode("Height");
pylon 3 provides a new set of code samples. The code samples can be found under <SDK ROOT>\Development\Samples\C++. The following table shows the mapping between old and new code samples.
pylon 3 was built using Microsoft Visual Studio 2010. The Debug build libraries are not installed anymore. This makes project setting changes necessary when delay loading is used. The list of delay loaded DLLs for Release and Debug project configurations (Configuration Properties -> Linker -> Input -> Delay Loaded DLLs) needs to be changed as shown in the following example:
If the build application does not use one or more of the delay loaded DLLs the linker will issue warning LNK4199. The unused libraries can then be removed from the list of delay loaded DLLs.
Continuing the Use of Deprecated Pixel Format Converters#
The image format converter classes based on Pylon::CPixelFormatConverter are now deprecated and replaced by wrapper classes that use the new Pylon::CImageFormatConverter class internally. To turn off deprecation warnings add the compile time switch PYLON_UTILITY_3_0_NO_DEPRECATE to your project settings (Configuration Properties -> C/C++ -> Preprocessor -> Preprocessor Definitions) or to your code before including the header files PylonIncludes.h, PylonUtilityIncludes.h or any pixel format converter header files:
The static methods Pylon::CPixelFormatConverterMonoPacked::Unpack10() and Pylon::CPixelFormatConverterMonoPacked::Unpack12() create an Pylon::CImageFormatConverter object on the stack each time when called and, as a consequence, can take more processing time.
The CBaslerGigETl and CBasler1394Tl classes are not needed anymore when programming against the pylon C++ API. These classes have been removed. All include statements for the header files "BaslerGigETl.h" and "Basler1394Tl.h" should be removed from application code. Replace all occurrences of Pylon::CBaslerGigETl by Pylon::IGigETransportLayer.
The IsValidRGB(), IsValidBGR(), and PixelSize() functions in PixelType.h are now deprecated. Alternative functions are Pylon::IsRGB(), Pylon::IsRGBA(), Pylon::IsBGR(), Pylon::IsBGRA(), Pylon::BitDepth(), and Pylon::BitPerPixel(). However, there is no exact replacement available. The deprecated functions are provided as header only code and can be copied to the application's code if needed. The SRGBAPixel struct is deprecated too and can be replaced by Pylon::SBGRA8Pixel. Only the name of this struct has been changed.
To avoid incompatibilities with non-Basler software based on GenICam, beginning with pylon 2.2, the pylon installer no longer sets a GENICAM_ROOT or GENICAM_ROOT_VX_Y environment variable. Instead, a PYLON_GENICAM_ROOT environment variable is set, specifying the location of the GenICam installation used by pylon.
The occurrences of the GENICAM_ROOT_V1_1 environment variable in the compiler's additional incude directories settings and the linker's additional library directories settings must be replaced by PYLON_GENICAM_ROOT.
When migrating from pylon versions older than pylon 2.0, occurrences of the GENICAM_ROOT environment variable in the compiler's additional include directory settings and the linker's additional library directories settings must be replaced by GENICAM_ROOT_V1_1.
Note
The latest pylon version uses PYLON_GENICAM_ROOT instead of GENICAM_ROOT.
For pylon 1.x several pylon and GenICam import libraries had to be explicitely listed in the linker's additional dependencies settings. Each time when pylon updates to a new GenICam version, the names of the GenICam libraries will change. It is no longer necessary to explicitely specify the interconnections with the pylon and GenICam libraries. Your project should include the PylonIncludes.h header file introduced with pylon 2.0 (see below) instead. By including the header file the required import libraries will be automatically linked to your application. It is thus not recommended to adapt your project settings to the new names of the libraries. You should include the PylonIncludes.h header file and remove all explicit references to pylon and GenICam import libraries from your project settings.
In some respects, the programming interface for pylon 2.x is not backward compatible with pylon 1.x. Breaking the backward compatibility was necessary to allow handling of camera description XML files in a more flexible way. Since pylon 2.0, a transport layer can support different camera types with each camera type having a different XML file. For example, the Basler pilot and Basler runner GigE cameras have different XML files. In pylon 2.x, these XML files are downloaded from the camera by default if the camera supports XML files download.
The following chapters describe the necessary changes for compiling an application using the pylon 2.x SDK when the application was originally developed using previous pylon versions.
In pylon 2.0, the PylonIncludes.h header file was added. This header file includes the pylon header files that are typically needed for building pylon-based applications. In addition, the header file includes linker statements that cause the linker to automatically link the import libraries needed to build pylon-based applications. It is no longer necessary and no longer recommended to explicitly link the pylon and GenICam libraries such as PylonBase_MD_VC80.lib.
It is not mandatory to use the PylonIncludes.h header file, but it is convenient since the import libraries are linked automatically.
The following code snippet illustrates how to include the PylonIncludes.h file:
When using Camera classes, some changes are necessary. For creating a camera class in pylon 1.0, it was necessary to downcast the IPylonDevice pointer returned by the Transport Layer object or by the Transport Layer factory to a camera class. This is due to the fact that the objects returned by the CreateDevice() methods in the form of IPylonDevice pointers were instances of the CBasler1394Camera and CBaslerGigECamera classes, respectively. That is to say, the Transport Layer factory or the Transport Layer objects were responsible for creating specific camera classes.
Since pylon 2.0, the CreateDevice() methods return pure IPylonDevice pointers that can no longer be cast to specific camera classes. Instead, a camera class behaves like a smart pointer that is created outside of a Transport Layer and is attached to a IPylonDevice pointer. The Camera class takes ownership of IPylonDevice pointers.
The following code snippets show how to use the new camera class:
// pylon 1.0: creating a CBasler1394 camera object...Pylon::CBasler1394Camera&camera=dynamic_cast<Pylon::CBasler1394Camera&>(*pTl->CreateDevice(devices[0]));// ... becomesPylon::CBasler1394Cameracamera(pTl->CreateDevice(devices[0]));// orPylon::CBasler1394Cameracamera;camera.Attach(pTl->CreateDevice(devices[0]));// orPylon::CBasler1394Camera*camera;camera=newPylon::CBasler1394Camera(pTl->CreateDevice(devices[0]));
// pylon 1.0: creating a CBaslerGigE camera object...Pylon::CBaslerGigECamera&camera=dynamic_cast<Pylon::CBaslerGigECamera&>(*pTl->CreateDevice(devices[0]));// ... becomesPylon::CBaslerGigECameracamera(pTl->CreateDevice(devices[0]));// orPylon::CBaslerGigECameracamera;camera.Attach(pTl->CreateDevice(devices[0]));// orPylon::CBaslerGigECamera*camera;camera=newPylon::CBaslerGigECamera(pTl->CreateDevice(devices[0]));
Using a stream grabber class (e.g., the Pylon::CBasler1394Camera::StreamGrabber_t class) is a convenient way to access a stream grabber's parameters. Since pylon 2.0, stream grabber classes behave very similarly to Camera classes. A stream grabber class takes ownership of a Pylon::IStreamGrabber pointer.
In pylon 1.x a stream grabber class was created as shown in the following example:
In pylon 1.x, the Transport Layer Factory's or the Transport Layer Object's DestroyDevice() method was used for deleting camera objects. In pylon 2.x, the camera class takes ownership of the IPylonDevice pointer. The destructor of the camera class is responsible for cleaning up the camera object.
When migrating a pylon 1.0 application to pylon 2.x, calls to the DestroyDevice() methods must be removed where CBasler1394Camera or CBaslerGigECamera pointers are used as arguments.
In pylon 1.x, the GetNodeMap() methods returned objects of type CNodeMapRef. With pylon 2.1, GenApi::INodeMap pointers are returned instead. Therefore, the INodeMap::GetNode() method must be used for accessing GenApi nodes instead of the CNodeMapRef::_GetNode() method.
In pylon 1.0, the CTlFactory::DestroyTl() method was used for freeing a Transport Layer object. For newer pylon versions, use the ReleaseTl() method instead.