All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Migrating from Previous Versions

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.

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.

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.

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 USB 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.x 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, a new image format converter, 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.png
pylon 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 cannot 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");

There is, however, no difference in parameter access between Low Level Camera classes and Device Specific Instant Camera classes using native parameter access. Example:

// Low Level API:
CBaslerGigECamera camera;
//...
// Maximize the image area of interest (Image AOI).
if (IsWritable(camera.OffsetX))
{
camera.OffsetX.SetValue(camera.OffsetX.GetMin());
}
if (IsWritable(camera.OffsetY))
{
camera.OffsetY.SetValue(camera.OffsetY.GetMin());
}
camera.Width.SetValue(camera.Width.GetMax());
camera.Height.SetValue(camera.Height.GetMax());
// Set the pixel data format.
camera.PixelFormat.SetValue(PixelFormat_Mono8);
// Instant Camera Classes:
CBaslerGigEInstantCamera camera;
//...
// Maximize the image area of interest (Image AOI).
if (IsWritable(camera.OffsetX))
{
camera.OffsetX.SetValue(camera.OffsetX.GetMin());
}
if (IsWritable(camera.OffsetY))
{
camera.OffsetY.SetValue(camera.OffsetY.GetMin());
}
camera.Width.SetValue(camera.Width.GetMax());
camera.Height.SetValue(camera.Height.GetMax());
// Set the pixel data format.
camera.PixelFormat.SetValue(PixelFormat_Mono8);

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 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_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
AutoFunctions ParametrizeCamera_AutoFunctions
ParametrizeCamera_Configurations
ParametrizeCamera_GenericParameterAccess
LoadSaveCameraFeatures ParametrizeCamera_LoadAndSave
LookupTable ParametrizeCamera_LookupTable
ParametrizeCamera ParametrizeCamera_NativeParameterAccess
RunnerShadingSample ParametrizeCamera_Shading
UserSets ParametrizeCamera_UserSets
Utility_Image
Utility_ImageFormatConverter
Utility_ImageLoadAndSave
WaitForMultiple See the Waiting for Multiple Events section.

Project Setting Changes

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 define PYLON_UTILITY_3_0_NO_DEPREC either by adding it to your compiler invocation or by defining it 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 class is not needed anymore when programming against the pylon C++ API, and has been removed. All include statements for the header file "BaslerGigETl.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 )
{
gigeTL->EnumerateAllDevices(dil);
//...
}
// New
//...
IGigETransportLayer* const gigeTL = dynamic_cast<IGigETransportLayer*>(CTlFactory::GetInstance().CreateTl(BaslerGigEDeviceClass));
if ( gigeTL )
{
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.


pylon 5.0.5
Copyright © 2006-2016 Basler AG (Thu Aug 11 2016 18:01:27)