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.
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 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:
must be changed to:
Alternatively, GenICam provides a header file that contains most of the forward declarations:
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:
Instead, you must use:
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 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.
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, 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.
Yes. The Low Level API will be provided also in future releases.
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 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.
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.
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:
There is, however, no difference in parameter access between Low Level Camera classes and Device Specific Instant Camera classes using native parameter access. Example:
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.
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. |
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:
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
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
.
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.