Skip to content

Migrating from Previous Versions#

Migrating from pylon 6.x to pylon 7#

What's new in pylon 7#

Introduction of Image Processing Capabilities#

With pylon 7.0 and newer, the pylon vTools have been added to extend the pylon 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).

Support for 5GigE Cameras#

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.

Migrating from pylon 5.x to pylon 6#

What's new in pylon 6#

Support for CoaXPress 2.0 Cameras#

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.

Migration Mode for Basler GigE Cameras#

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:

Removed support for IEEE1394#

The support for IEEE1394 (also known as IIDC 1394 or FireWire) has been removed.

Deprecation of the Low Level API Camera Classes#

The Low Level API camera classes have been deprecated. Basler recommends porting your code to the CBaslerUniversalInstantCamera class. If you need to continue using your existing Low Level API grab code you can derive from the CBaslerUniversalInstantCamera to gain access to the protected method Pylon::CInstantCamera::GetDevice(). The GetDevice() method returns a Pylon::IPylonDevice pointer that for instance allows to access the stream grabber directly. If you do this you must not use the method Pylon::CInstantCamera::StartGrabbing(), Pylon::CInstantCamera::IsGrabbing(), Pylon::CInstantCamera::RetrieveResult() and Pylon::CInstantCamera::StopGrabbing().

The following table shows the classes that have been deprecated:

Transport Layer Name of Class
PylonGigE Pylon::CBaslerGigECamera
PylonUsb Pylon::CBaslerUsbCamera
PylonCLSer Pylon::CBaslerCameraLinkCamera

Deprecation of Device-Specific Camera Classes#

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.

Changes in the IStreamGrabber API#

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.

Interface Classes#

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.

Migrating from pylon 4.x to pylon 5#

What's new in pylon 5?#

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] 48.0 17.1 63.2 20.9 33.9 13.1 44.5 15.2

Breaking Changes in pylon 5#

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.

Layout of the Installation Directory#

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.

Environment Variables#

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.

Example:

namespace GenApi
{
    interface INodeMap;
}

must be changed to:

#include <GenApi/GenApiNamespace.h>

//...

namespace GENAPI_NAMESPACE
{
    interface INodeMap;
}

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.

Exception Handling#

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(const std::exception& e)
{
    //handle the exception
}

Instead, you must use:

try
{
    //code using pylon
}
catch(const Pylon::GenericException& e)
{
    //handle the exception
}
catch(const std::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.

Behavior of PylonInitialize and PylonTerminate#

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.

Pylon::CTlFactory::GetInstance() does now throw an exception if PylonInitialize has not been called before, instead of performing an implicit initialization. If your code depends on the implicit behavior, you must change your code to properly call PylonInitialize and PylonTerminate as described in Initialization/Uninitialization of the pylon Runtime Library.

pylon Bootstrapper Removed#

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.

Class AlertableWaitObject Removed#

The class Pylon::AlertableWaitObject has been deprecated in pylon 2.1. It has been removed. Use the class Pylon::WaitObjectEx instead. To create a new instance of Pylon::WaitObjectEx, use the static factory method Pylon::WaitObjectEx::Create(). For more information, see section Wait Objects.

Header File Pylon_W32.h 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.

Deploying pylon#

For information about deploying pylon, see the pylon Deployment Guide. The document is available on the Basler website: www.baslerweb.com.

Migrating from pylon 3 to pylon 4#

What's new in pylon 4?#

pylon 4 adds support for Basler USB3 Vision compliant cameras. See the section Migrating Existing Code for Using SFNC 2.x-Based Camera Devices under advanced topics for more information.

Block ID#

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.

Migrating from Pylon 2.3 to Pylon 3#

What's new in pylon 3?#

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.

pylon3_0_migration.svgpylon 3 Is Still Compatible with pylon 2.3 and Offers a New API for Grabbing and Image Handling

Frequently Asked Questions Regarding Migration#

Can I Keep My Implementation Using the Low Level API?#

Yes. The Low Level API will be provided also in future releases.

What Parts of the API Can Be Used Together?#

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.

When to Change to the Instant Camera Classes?#

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.

What to Use When Starting a New Project?#

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:
CBaslerGigECamera camera;
//...

// Get the camera control object.
INodeMap &control = *camera.GetNodeMap();
const CIntegerPtr Height = control.GetNode("Height");
const CIntegerPtr Height = camera.GetNodeMap()->GetNode("Height");


// Instant Camera Classes:
CBaslerGigEInstantCamera camera;
//...

// Get the camera control object.
INodeMap &control = camera.GetNodeMap();
const CIntegerPtr Width = control.GetNode("Width");
const CIntegerPtr Height = camera.GetNodeMap().GetNode("Height");

If code samples are referenced the mapping between old and new code samples can be found in the section Mapping Between Old and New Code Samples.

Mapping Between Old and New Code Samples#

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.

Old Code Sample New Code Sample Comment
RegisterRemovalCallback DeviceRemovalHandling
AcquireSingleFrame See Pylon::CInstantCamera::GrabOne() for information about single frame acquisition.
AcquireSingleFrame_Gen See Pylon::CInstantCamera::GrabOne() for information about single frame acquisition. The ParametrizeCamera_GenericParameterAccess sample shows how to use generic parameter access.
AcquireContinuous Grab Sample Shows how to grab using continuous acquisition. Continuous acquisition is used as default configuration for Instant Camera classes.
CameraEvents Grab_CameraEvents
AcquireSingleFrame_ChunkImage Grab_ChunkImage
AcquireContinuous_Multicast Grab_MultiCast
Grab_MultipleCameras
Grab_Strategies
Grab_UsingActionCommand
Grab_UsingBufferFactory
Grab_UsingExposureEndEvent
AcquireContinuous_SoftTrigger Grab_UsingGrabLoopThread Shows how to use the grab loop thread that is provided by the Instant Camera object and how to use Software Trigger.
Grab_UsingSequencer
GUI_ImageWindow
AutoFunctions ParametrizeCamera_AutoFunctions
ParametrizeCamera_Configurations
ParametrizeCamera_GenericParameterAccess
LoadSaveCameraFeatures ParametrizeCamera_LoadAndSave
LookupTable ParametrizeCamera_LookupTable
ParametrizeCamera ParametrizeCamera_NativeParameterAccess
SerialCommunication ParametrizeCamera_SerialCommunication
RunnerShadingSample ParametrizeCamera_Shading
UserSets ParametrizeCamera_UserSets
Utility_GrabAvi
Utility_GrabVideo
Utility_Image
Utility_ImageFormatConverter
Utility_ImageLoadAndSave
WaitForMultiple See the Waiting for Multiple Events section.

Project Setting Changes#

Delay Loading Settings#

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:

PylonBase_MD_vc100.dll;PylonUtility_MD_VC100.dll;PylonGUI_MD_VC100.dll;GCBase_MD_vc100_$(PYLON_GENICAM_VERSION).dll;GenApi_MD_vc100_$(PYLON_GENICAM_VERSION).dll

Note

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.

API Changes#

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:

#define PYLON_UTILITY_3_0_NO_DEPRECATE
#include <pylon/PylonIncludes.h>

Attention

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.

Removed Classes#

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.

// Old
#include <pylon/gige/BaslerGigETl.h>
//...
CBaslerGigETl* const gigeTL = dynamic_cast<CBaslerGigETl*>(CTlFactory::GetInstance().CreateTl(BaslerGigEDeviceClass));
if ( gigeTL )
{
    DeviceInfoList_t dil;
    gigeTL->EnumerateAllDevices(dil);
    //...
}
// New
#include <pylon/gige/GigETransportLayer.h>
//...
IGigETransportLayer* const gigeTL = dynamic_cast<IGigETransportLayer*>(CTlFactory::GetInstance().CreateTl(BaslerGigEDeviceClass));
if ( gigeTL )
{
    DeviceInfoList_t dil;
    gigeTL->EnumerateAllDevices(dil);
    //...
}

Deprecated Helper Functions and Classes#

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.

Migrating from pylon 2.1 to pylon 2.2#

Project Setting Changes#

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.

Migrating from pylon 2.0 to pylon 2.1#

Deprecated Helper Functions and Classes#

The class Pylon::AlertableWaitObject is now deprecated. Please use the class Pylon::WaitObjectEx instead. Note:To create a new instance of Pylon::WaitObjectEx use the static factory method Pylon::WaitObjectEx::Create(). For further information see section Wait Objects.

Migrating from pylon 1.x to pylon 2.0#

Project Setting Changes#

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.

API Changes#

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.

Convenience Header File#

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:

#include <pylon/PylonIncludes.h>

Device Creation#

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]));

// ... becomes

Pylon::CBasler1394Camera camera( pTl->CreateDevice (devices[0]) );

// or
Pylon::CBasler1394Camera camera;
camera.Attach (pTl->CreateDevice (devices[0]));

// or
Pylon::CBasler1394Camera *camera;
camera = new Pylon::CBasler1394Camera (pTl->CreateDevice (devices[0]));
// pylon 1.0: creating a CBaslerGigE camera object...
Pylon::CBaslerGigECamera &camera
 = dynamic_cast<Pylon::CBaslerGigECamera &> (*pTl->CreateDevice (devices[0]));

// ... becomes
Pylon::CBaslerGigECamera camera( pTl->CreateDevice (devices[0]) );

// or
Pylon::CBaslerGigECamera camera;
camera.Attach (pTl->CreateDevice (devices[0]));

// or
Pylon::CBaslerGigECamera *camera;
camera = new Pylon::CBaslerGigECamera (pTl->CreateDevice (devices[0]));

Stream Grabber Creation#

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:

Pylon::CBasler1394Camera::StreamGrabber_t &StreamGrabber
  = dynamic_cast <Pylon::CBasler1394Camera::StreamGrabber_t&>(*camera.GetStreamGrabber (0));

For newer pylon versions this becomes one of the following variants:

Pylon::CBasler1394Camera::StreamGrabber_t
StreamGrabber( camera.GetStreamGrabber(0) );

// or
Pylon::CBasler1394Camera::StreamGrabber_t StreamGrabber;
// ...
StreamGrabber.Attach( camera.GetStreamGrabber(0) );

// or
Pylon::CBasler1394Camera::StreamGrabber_t * StreamGrabber;
StreamGrabber = new Pylon::CBasler1394Camera::StreamGrabber_t (m_pCamera->GetStreamGrabber (0));

Device Cleanup#

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.

Node Access#

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.

Example:

GenApi::CNodeMapRef *MyNodeMap = pDevice->GetNodeMap();

GenApi::INode* MyNode = MyNodeMap->_GetNode("GainRaw");

becomes

GenApi::INodeMap* MyNodeMap = pDevice->GetNodeMap();

GenApi::INode* MyNode = MyNodeMap->GetNode("GainRaw");

Transport Layer Object Cleanup#

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.